11<!--
2- DESIGN NOTES — SKULK CLI
2+ DESIGN NOTES — HPL CLI
33 The Human Pattern Lab
44
5- This document explains *why* Skulk behaves the way it does.
5+ This document explains *why* HPL behaves the way it does.
66 It is not required reading, but it is canonical.
77-->
8- # Skulk CLI — Design Notes
8+
9+ # HPL CLI — Design Notes
910
1011> Looking for usage or setup?
1112> Go back to → [ README.md] ( ./README.md )
1415
1516## Design Goals
1617
17- Skulk is designed to be:
18+ HPL is designed to be:
1819- predictable
1920- automation-safe
2021- easy to reason about
2122- boring in the right ways
2223
23- The goal is not cleverness.
24+ The goal is not cleverness.
2425The goal is trust.
2526
2627---
@@ -34,15 +35,15 @@ It means building tools that:
3435- communicate clearly
3536- don’t require guesswork when automated
3637
37- As tooling increasingly interacts with agents and scripts , ambiguity becomes technical debt.
38+ As tooling increasingly interacts with agents, scripts, and orchestration layers , ambiguity becomes technical debt.
3839
39- Skulk treats that as a first-class concern.
40+ HPL treats that as a first-class concern.
4041
4142---
4243
4344## Output Is a Contract
4445
45- Skulk has two explicit output modes:
46+ HPL has two explicit output modes.
4647
4748### Human Mode (default)
4849- readable progress
@@ -55,6 +56,8 @@ Skulk has two explicit output modes:
5556- errors are written to stderr
5657- exit codes are deterministic
5758
59+ This distinction is intentional and enforced.
60+
5861---
5962
6063## JSON Purity Enforcement
@@ -65,7 +68,7 @@ The project includes a hard verification step:
6568npm run json:check
6669```
6770
68- This runs Skulk in JSON mode and pipes stdout directly into ` JSON.parse ` .
71+ This runs HPL in JSON mode and pipes stdout directly into ` JSON.parse ` .
6972
7073If * anything* other than valid JSON is emitted, the command fails immediately.
7174
@@ -78,6 +81,8 @@ If *anything* other than valid JSON is emitted, the command fails immediately.
7881- Output formatting happens at the command boundary
7982- Exit codes reflect real success or failure
8083
84+ This separation keeps behavior testable and contracts stable.
85+
8186---
8287
8388## Why This Matters
@@ -87,14 +92,14 @@ Most CLI bugs don’t come from broken logic — they come from:
8792- mixed streams
8893- silent contract changes
8994
90- Skulk is designed to avoid those classes of problems entirely.
95+ HPL is designed to avoid those classes of problems entirely.
9196
9297---
9398
9499## Final Note
95100
96101These constraints are intentional.
97102
98- They make Skulk easier to automate, easier to test, and easier to trust — now and later.
103+ They make HPL easier to automate, easier to test, and easier to trust — now and later.
99104
100105If a future change breaks these guarantees, it should break loudly.
0 commit comments