codeassembly-guidance 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -0,0 +1,18 @@
1
+ #!/usr/bin/env node
2
+
3
+ // Runs the bundled validate-preferences helper. The bundle is self-contained, so the package doesn't need any runtime
4
+ // dependencies, and its own entry guard stays false here because `process.argv[1]` names this file.
5
+ import path from 'node:path';
6
+ import process from 'node:process';
7
+
8
+ import { runValidatePreferences } from '../content/scripts/validate-preferences.mjs';
9
+
10
+ const programName = path.basename(process.argv[1] ?? 'codeassembly-validate-preferences', '.js');
11
+
12
+ try {
13
+ process.exitCode = await runValidatePreferences(process.argv.slice(2), process.cwd(), programName);
14
+ } catch (error) {
15
+ const message = error instanceof Error ? error.message : String(error);
16
+ process.stderr.write(`${programName}: ${message}\n`);
17
+ process.exitCode = 1;
18
+ }
@@ -25,13 +25,27 @@ Inline a spec **once per skill, as a section**, and point every use site at it w
25
25
 
26
26
  Several skill bodies (`collaborate`, `design-and-plan`, and `refine-plan` among them) contain a pointer to the option-format rules at their question-asking steps, duplicating the universal rule in `AGENTS.md`. That duplication is intentional, and a DRY-driven refactor must not strip it. The rule and its rationale are stated in the repo-local `codeassembly-repo-conventions` rulebook (`.agents/content/guidance/rulebooks/`), under "Skill-local reinforcement".
27
27
 
28
+ ## When content becomes a partial
29
+
30
+ A partial exists to share text. Content becomes a partial when two or more files include it, another partial or a `_data` doc counting as a file that includes it, and a partial that only one file includes is inlined back into that file. Write a doctrine in its one host until a second file needs it.
31
+
32
+ Partials that the same files include are one partial when every one of those files includes them at one point, with none of its own text between them. When a host's own text separates them, they stay apart: Passing that text through the `<!-- children -->` slot would change the rendered whitespace, as [Verbatim slot substitution](#verbatim-slot-substitution) explains. The list below names each such group and the text that separates it.
33
+
34
+ `content/__tests__/partial-consumers.unit.test.ts` fails when a partial is included by fewer than two files, or when partials that the same files include are missing from the list.
35
+
36
+ ### Partials kept apart
37
+
38
+ - `skills/_partials/ticket-skeleton.md`, `skills/_partials/ticket-composition.md`, `skills/_partials/ticket-criteria-conventions.md`: Each host closes the skeleton's code fence, which `design-and-plan` opens with a title line, before the composition; `create-ticket` adds its spike-mode paragraph there, and `align-ticket-with-implementation` its `## Guidance` heading. Each host then follows the composition with its own sentence on what _the implementation_ is.
39
+ - `skills/_partials/plan-template.md`, `skills/_partials/ticket-and-plan-completeness.md`: Each host places them in different sections.
40
+ - `skills/_partials/split-ticket-compose.md`, `skills/_partials/split-ticket-create.md`, `skills/_partials/split-launch-prompts.md`: Each host puts its own steps before and after `split-ticket-create.md`.
41
+
28
42
  ## Directive grammar
29
43
 
30
44
  Three include shapes are recognized. Each must occupy a full line, with optional leading and trailing whitespace. That whitespace affects recognition alone; injected lines keep the partial's own indentation rather than the directive's, so a directive cannot appear inside a list item. Inline directives inside prose or code spans are not expanded.
31
45
 
32
46
  | Shape | Syntax | Use |
33
47
  | ------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
34
- | Self-close | `<!-- include: path / -->` | Inline a partial without slot content (or use the partial's empty-slot defaults). |
48
+ | Self-close | `<!-- include: path / -->` | Inline a partial without slot content (or use the partial's empty-slot defaults). |
35
49
  | Open + close | `<!-- include: path -->` ... `<!-- /include -->` | Inline a partial and pass slot content into its `<!-- children -->` placeholder. |
36
50
  | Children slot | `<!-- children -->` | Inside a partial: Marks where the caller's slot content is substituted. |
37
51
 
@@ -61,13 +75,13 @@ A **relative Markdown link** cannot serve both a skill host and a rulebook host.
61
75
 
62
76
  A partial that `guidance/shared/AGENTS.md` inlines does not contain any relative link at all. That file is inlined into each harness's guidance file at the harness home root, where a source-tree-relative target names nothing, so the template-variable form is the only one that resolves to a file from there. `codeassembly validate` scans the expanded body and reports a relative target that it finds.
63
77
 
64
- A **`{rulebook:<slug>}` token** cannot serve both a skill body and a support entry under `skills/`. The deployed rulebook set is available only to a host that resolves a declaration, and a source's support entries deliver to every consumer of the source, whichever rulebooks that consumer declares. The token renders in the skill but breaks the support entry's delivery.
78
+ A **`{rulebook:<slug>}` token** cannot serve both a skill body and a support entry under `skills/`. The deployed rulebook set is available only to a host that resolves a declaration, and a source's support entries are delivered to every consumer of the source, whichever rulebooks that consumer declares. The token renders in the skill but breaks the support entry's delivery.
65
79
 
66
80
  ## Path references in installed content
67
81
 
68
82
  Installable content is rewritten at install time. Author cross-references in one of three forms, depending on intent:
69
83
 
70
- - **Runtime references**: Paths that the agent reads or executes at runtime. Use `[text](relative/path.md)` for a Markdown link, or `{harness_home_dir}/...` inside inline code or a command (e.g., `{harness_home_dir}/skills/_data/work-types.json`), the form that a partial inlined at several depths can use. Both name a file by its place in the content tree, and the pipeline resolves both to where that file is deployed: A target naming a skill deployed by the same run resolves where that run wrote it, a target in one of the owning source's support entries resolves into that source's namespace, `skills/_sources/<name>/`, and anything else resolves to the harness home. `sync --global` anchors the first two under the harness home, and bare `sync` under the project root. Every other `{harness_home_dir}` expands to the platform home (e.g., `~/.claude`), where `scripts/` deploys.
84
+ - **Runtime references**: Paths that the agent reads or executes at runtime. Use `[text](relative/path.md)` for a Markdown link, or `{harness_home_dir}/...` inside inline code or a command (e.g., `{harness_home_dir}/skills/_data/work-types.json`), the form that a partial inlined at several depths can use. Both name a file by its place in the content tree, and the pipeline resolves both to where that file is deployed: A target naming a skill deployed by the same run resolves where that run wrote it, a target in one of the owning source's support entries resolves into that source's namespace, `skills/_sources/<name>/`, and anything else resolves to the harness home. `sync --global` anchors the first two under the harness home, and bare `sync` under the project root. Every other `{harness_home_dir}` expands to the platform home (e.g., `~/.claude`), where `scripts/` is deployed.
71
85
  - **Source-tree citations**: Prose pointing the reader to the canonical implementation, like a doc reference. A bare `packages/guidance/content/...` path is acceptable in this case, but the file must be added to the allowlist in `packages/guidance/content/__tests__/content-path-conventions.unit.test.ts`.
72
86
  - **Self-referential prose** about the source tree itself (e.g., this paragraph) is treated as a source-tree citation.
73
87
 
@@ -79,7 +93,7 @@ Partials are stored in `_partials/` directories. The directory is recognized at
79
93
 
80
94
  - `content/_partials/`: Cross-cutting partials shared across skills, subagents, and platform guidance.
81
95
  - `content/skills/_partials/`: Partials shared across skills.
82
- - `content/skills/{name}/_partials/`: Partials internal to a single skill.
96
+ - `content/skills/{name}/_partials/`: Partials shared by one skill's own files.
83
97
 
84
98
  The `_partials` directory itself never appears in installed output.
85
99
 
@@ -108,7 +122,7 @@ When a placeholder names a tool outside that set, the rewriter aborts install wi
108
122
 
109
123
  **Authoring guidance:**
110
124
 
111
- - Use `{tool:NAME}` for body prose that names a tool *as a tool*, not for English verbs ("Read the file", "Write a paragraph", "Read project guidelines" are not migrated).
125
+ - Use `{tool:NAME}` for body prose that names a tool _as a tool_, not for English verbs ("Read the file", "Write a paragraph", "Read project guidelines" are not migrated).
112
126
  - Preserve surrounding context: `` `Write` `` becomes `` `{tool:Write}` ``; bare `Write` becomes `{tool:Write}`.
113
127
  - Do **not** use placeholders in frontmatter `tools:` values. Frontmatter is replaced wholesale by the overlay merger; placeholders there would create two overlapping mechanisms.
114
128
  - The placeholder mechanism is body-only, applied to subagent and skill `.md` files. Guidance files (`content/guidance/`) are not passed through the rewriter.
@@ -119,6 +133,8 @@ When a partial contains `<!-- children -->`, expansion removes that line and ins
119
133
 
120
134
  A consequence: Avoid placing blank lines on both sides of a `<!-- children -->` boundary. If the partial has a blank line above `<!-- children -->` and the caller's slot content begins with a blank line, the result is two consecutive blank lines.
121
135
 
136
+ Prettier sets part of that spacing on both sides: It puts a blank line after an open directive, so slot content begins with one, and it puts one before `<!-- children -->` unless a paragraph line precedes the placeholder. A partial that keeps its placeholder directly under a paragraph line therefore renders one blank line at the boundary, and any other placement renders two.
137
+
122
138
  ## Common patterns
123
139
 
124
140
  ### Bare self-close: No slot
@@ -34,7 +34,7 @@ The library's behavior belongs in the library's docs. A helper's contract belong
34
34
 
35
35
  **4. The derivation test: Do the listed cases follow from one rule?** Then state the rule.
36
36
 
37
- A comment that enumerates the cases below it copies each case's own description, and the copy drifts: The enumeration keeps a name that the code has since renamed, or it places one case on both sides of a distinction. State the invariant that generates the cases, and let each case's own description carry its specifics. An exception is worth naming once, beside the rule.
37
+ A comment that enumerates the cases below it copies each case's own description, and the copy drifts: The enumeration keeps a name that the code has since renamed, or it places one case on both sides of a distinction. State the invariant that generates the cases, and let each case's own description state its specifics. An exception is worth naming once, beside the rule.
38
38
 
39
39
  Tells: The same name appearing in two of the comment's lists, a run of backticked member names already documented at their own declarations below, and a list whose length tracks the number of members or branches below it.
40
40
 
@@ -4,6 +4,7 @@ Before reporting what a change did, read the change back, and repair what you fi
4
4
 
5
5
  - **Claims.** Every statement about the change is read from the diff, not from what you set out to do. A claim that something was left unchanged needs the same evidence as a claim that something changed, and it is the one most often written from memory.
6
6
  - **Reach.** What the edit moved beyond its target: a parallel enumeration of the same list elsewhere, such as a README mirroring the edited source doc; sibling wording invalidated by a rename or re-framing, in a test title, a function header, or a neighboring doc; declaration ordering after an insertion; and adjacent behavior that a changed guard now covers or stops covering.
7
+ - **Placement.** Each hunk that writes guidance or documentation states a fact only where the fact is defined, such as the config that declares it, the code, its owning README section, or a rulebook, and elsewhere points to that source. A list copied from a config, or a paragraph that restates a rulebook, is a copy that drifts.
7
8
  - **Class.** When the change corrects a defect, the site that you were pointed at is a sample of its class. Audit the other members before reporting, or the next reviewer finds the one that you left.
8
9
 
9
10
  A green gate is not this audit: A suite that passes reports that nothing broke, not that the record which you are about to write is true.
@@ -0,0 +1,7 @@
1
+ ## Standard tags
2
+
3
+ Every knowledge store shares these tags. Tag a record's disposition with one of these names, never with a variant spelling:
4
+
5
+ - `deferred`: Reviewed and set aside, to surface again later rather than act on now.
6
+ - `obsolete`: Valid when recorded, but no longer applies.
7
+ - `rejected`: Judged incorrect, or declined.
@@ -52,6 +52,10 @@ The helper reports every determiner "no" under this rule, as shape 9, in any pos
52
52
 
53
53
  ### Words to look for
54
54
 
55
+ <!-- rule: overused-word 1 -->
56
+
57
+ The helper reports every sentence that contains one of these words or an inflection of one under this rule. Report a site of a listed word under `overused-word`, and every other site that breaks the plain-speech rule under `plain-speech`.
58
+
55
59
  Ten words recur in this corpus in uses for which a word naming the relation exists. Each is a search term rather than a rule, as a shape is: A match is a candidate for the rule's tests. When an entry names a sense that stays, a use in that sense is not a candidate.
56
60
 
57
61
  - **carry**: "the change carries a flag". Instead: has, includes, declares, sets, states.
@@ -2,4 +2,5 @@
2
2
 
3
3
  - Default to current best practices. Before recommending an approach, verify it reflects the current state of the ecosystem, not a pattern that was standard two years ago.
4
4
  - When unsure whether your knowledge is current, say so and look it up rather than presenting a possibly outdated approach as the answer.
5
+ - Before weighing options for a design problem, name the solutions that current best practice applies to that kind of problem and the conditions under which each one fits, then start from the one whose conditions hold. Label an option that departs from all of them as non-standard, and state why none of them fits. When the standard solution requires revising an existing API, recommend the revision rather than an addition that works around the current contract.
5
6
  - Prefer CLI tools over web UI instructions. When a task can be done via a CLI command (e.g., `npm trust`, `gh repo edit`, `gh secret set`), recommend the command, not manual steps in a browser. When multiple commands need to be run, offer to write a script in the most suitable language (other things being equal, prefer bash and TypeScript), following the relevant coding conventions.
@@ -1,5 +1,5 @@
1
1
  # The content-format contract against which this root is authored; see "Content-format version" in packages/agents/docs/project-declaration.md.
2
- format: 2
2
+ format: 3
3
3
 
4
4
  # The TypeScript helpers that `codeassembly bundle-helpers` bundles into this root, both paths relative to this file.
5
5
  helpers:
@@ -33,6 +33,8 @@ helpers:
33
33
  out: skills/revise-prose/revise-prose.mjs
34
34
  - entry: ../src/streamline-guidance/cli.ts
35
35
  out: skills/streamline-guidance/streamline-guidance.mjs
36
+ - entry: ../src/validate-preferences/cli.ts
37
+ out: scripts/validate-preferences.mjs
36
38
  - entry: ../src/describe-change/cli.ts
37
39
  out: scripts/describe-change.mjs
38
40
  - entry: ../src/select-lede-exemplars/cli.ts
@@ -47,3 +49,17 @@ helpers:
47
49
  out: skills/index-prototypes/index-prototypes.mjs
48
50
  - entry: ../src/select-pr-ticket/cli.ts
49
51
  out: skills/review-gh-pr/select-pr-ticket.mjs
52
+ - entry: ../src/resolve-ticket-target/cli.ts
53
+ out: skills/create-ticket/resolve-ticket-target.mjs
54
+ - entry: ../src/assess-code-health/cli.ts
55
+ out: skills/assess-code-health/assess-code-health.mjs
56
+ - entry: ../src/lesson-clusters/cli.ts
57
+ out: skills/lesson-clusters/lesson-clusters.mjs
58
+ - entry: ../src/triage-feedback/cli.ts
59
+ out: skills/triage-feedback/triage-feedback.mjs
60
+ - entry: ../src/triage-spike-findings/cli.ts
61
+ out: skills/triage-spike-findings/triage-spike-findings.mjs
62
+ - entry: ../src/check-branch-currency/cli.ts
63
+ out: scripts/check-branch-currency.mjs
64
+ - entry: ../src/check-prose/cli.ts
65
+ out: scripts/check-prose.mjs
@@ -6,6 +6,6 @@ members: '@library'
6
6
 
7
7
  # All
8
8
 
9
- The whole-catalog collection. `members: '@library'` resolves to every rulebook, skill, and subagent in the content library, computed at resolution time so that a newly added artifact joins automatically without an edit here. Collections are excluded: The resolver never emits them, and "every collection" would be self-referential.
9
+ The whole-catalog collection. `members: '@library'` resolves to every rulebook, skill, and subagent in the content library, computed at resolution time so that the resolver includes a newly added artifact automatically, without an edit here. Collections are excluded: The resolver never emits them, and "every collection" would be self-referential.
10
10
 
11
- This is the escape hatch, not the expected declaration. It does not make any claim about its members: It deploys the vetted, the unexamined, and the artifacts deliberately left out of every collection alike, and a newly added artifact joins it before anyone has read it. A consumer should declare the collections whose dispositions it wants instead, and reach for this one only to take the catalog whole.
11
+ This is the fallback, not the expected declaration. It does not make any claim about its members: It deploys the vetted, the unexamined, and the artifacts deliberately left out of every collection alike, and it includes a newly added artifact before anyone has read it. A consumer should declare the collections whose dispositions it wants instead, and declare this one only to deploy the whole catalog.
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: atlassian
3
3
  description: Skills that act on Bitbucket pull requests and Jira work items.
4
+ disposition: opt-in
4
5
  members:
5
6
  skills:
6
7
  - create-bitbucket-pr
@@ -13,4 +14,4 @@ members:
13
14
 
14
15
  Every member acts on one of Atlassian's hosted products: creating, reviewing, and merging Bitbucket pull requests, and creating and updating Jira work items. A consumer should declare this collection only if one of those products is in use.
15
16
 
16
- Nothing outside this collection reaches a member. `create-pr`, `merge-pr`, `review-pr`, and `create-ticket` each name one through an optional invocation token, and `collection-dispositions.unit.test.ts` fails when a token naming a member is written in its required form.
17
+ Artifacts outside this collection do not require any member. `create-pr`, `merge-pr`, `review-pr`, and `create-ticket` each name one through an optional invocation token, and `codeassembly validate` reports a token naming a member that is written in its required form.
@@ -1,13 +1,16 @@
1
1
  ---
2
2
  name: recommended
3
3
  description: The vetted, generally applicable set (artifacts any project can declare).
4
+ disposition: public
4
5
  members:
5
6
  rulebooks:
6
7
  - accessibility-conventions
8
+ - cli-conventions
7
9
  - command-output-conventions
8
10
  - generated-content-policy
9
11
  - readme-conventions
10
12
  - shared-data-conventions
13
+ - ui-copy-conventions
11
14
  skills:
12
15
  - capture-event
13
16
  - capture-feedback
@@ -25,10 +28,14 @@ The skills belong here on different grounds. A rulebook of the personal collecti
25
28
 
26
29
  `accessibility-conventions` also qualifies on its own terms. It states an external standard, WCAG 2.2 AA, and floors that do not name any author, repository, or tool. Its body does not contain any invocation token, so its closure is empty.
27
30
 
28
- `command-output-conventions` qualifies on its own terms too. What it states follows from a mechanism that every agent session meets, the cost of output kept in the context window, rather than from a preference, and it does not name any tool, host, or store. Its body does not contain any invocation token, so its closure is empty.
31
+ `cli-conventions` qualifies on its own terms as well. What it asks of a CLI's options, configuration, help, exit codes, errors, JSON output, progress reports, and check results, and of the split between its logic and its presentation, follows from who reads them, a person at a terminal that cannot follow a link and a script or an agent that reads the exit code and the streams, rather than from a preference. It does not name any author, repository, language, or tool. Its body does not contain any invocation token, so its closure is empty.
29
32
 
30
- `readme-conventions` qualifies on its own terms as well. It does not name any repository, tool, or path belonging to one author, and what it asks of a README follows from who reads the file rather than from a preference about how a README should read. Its body does not contain any invocation token, so its closure is empty and admitting it extends this collection's reach by nothing.
33
+ `command-output-conventions` qualifies on its own terms too. What it states follows from a mechanism that every agent session meets, the context-window space that retained output takes up, rather than from a preference, and it does not name any tool, host, or store. Its body does not contain any invocation token, so its closure is empty.
34
+
35
+ `readme-conventions` qualifies on its own terms as well. It does not name any repository, tool, or path belonging to one author, and what it asks of a README follows from who reads the file rather than from a preference about how a README should read. Its body does not contain any invocation token, so its closure is empty and admitting it does not add any other artifact to what this collection deploys.
31
36
 
32
37
  Adding a skill that declares a guidance hook has a drawback that the current members do not have. A project declaring this collection deploys its own copy of that skill, and that copy shadows the user's home-bound one. Because guidance-hook bindings do not cross the boundary between the user-global and project domains, guidance bound globally by the developer goes missing in that repository until the project binds it too. Weigh that against the general applicability claimed by membership before admitting such a skill.
33
38
 
34
39
  `shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract, and the rule that unmerged code does not write to shared state, and it does not name any author, platform, or store: Each repository's `AGENTS.md` names its own. Its body does not contain any invocation token, so its closure is empty.
40
+
41
+ `ui-copy-conventions` qualifies on its own terms as well. What it asks of the text on a page follows from who reads that text, the person who returns to the page every week, rather than from a preference, and it does not name any author, repository, product, or tool. A project that has content guidelines of its own names them, and they take precedence. Its body does not contain any invocation token, so its closure is empty.
@@ -1,77 +1,13 @@
1
1
  ---
2
2
  name: triage
3
3
  description: The not-yet-examined set, the default home for library content awaiting a disposition.
4
- members:
5
- rulebooks:
6
- - commit-conventions
7
- - shell-conventions
8
- skills:
9
- - add-change-record
10
- - add-test-ids
11
- - align-ticket-with-implementation
12
- - anti-patterns
13
- - assess-ticket
14
- - brainstorming
15
- - capture-lede-decision
16
- - classify-complexity
17
- - collaborate
18
- - condense-branch
19
- - create-commit
20
- - create-devlog
21
- - create-gh-pr
22
- - create-pr
23
- - create-ticket
24
- - design-and-plan
25
- - development-workflows
26
- - get-ticket-id
27
- - groom-backlog
28
- - implement-plan
29
- - index-prototypes
30
- - kb-add
31
- - kb-curate
32
- - kb-edit
33
- - kb-retrieve
34
- - kb-retrieve-events
35
- - kb-update-events
36
- - merge-gh-pr
37
- - merge-pr
38
- - plan
39
- - prepare-prototype-brief
40
- - pull-from-backlog
41
- - refine-plan
42
- - respond-to-review
43
- - review-branch
44
- - review-criteria
45
- - review-gh-pr
46
- - review-permissions
47
- - review-pr
48
- - revise-comments
49
- - revise-prose
50
- - save-artifact
51
- - save-plan
52
- - software-engineering
53
- - streamline-guidance
54
- - summarize-change
55
- - summarize-chat
56
- - systematic-debugging
57
- - testing-conventions
58
- - typescript-testing-conventions
59
- - update-project-guidance
60
- - upgrade-dependencies
61
- - wrap-up
62
- subagents:
63
- - entry-drafter
64
- - handoff-reviewer
65
- - plan-reviewer
66
- - plan-reviser
67
- - prose-reviser
68
- - ticket-assessor
4
+ members: '@unclaimed'
69
5
  ---
70
6
 
71
7
  # Triage
72
8
 
73
9
  The not-yet-examined collection, and where new content starts. Membership claims nothing about an artifact beyond its existence: Nobody has yet read it for personal doctrine or for coupling to one author's environment, so it can be neither offered as generally applicable nor vouched for as deliberately personal.
74
10
 
75
- Declaring it deploys the catalog minus the vetted collections and the artifacts recorded standalone. That is the honest way to keep everything while the vetting proceeds, and it is why the vetted collections are usable before the vetting examines a single artifact.
11
+ `members: '@unclaimed'` computes the membership: every artifact of this content root that no collection with a `disposition:` enumerates and that does not declare `standalone:`. A newly added artifact is therefore a member without an edit here. Declaring the collection is the honest way to keep everything while the vetting proceeds, and it is why the vetted collections are usable before the vetting examines a single artifact.
76
12
 
77
- This collection only shrinks. An artifact leaves it by promotion into a public or personal collection, by moving into an opt-in collection once it turns out to be wanted often but only on the machines using one vendor's ecosystem, or by being recorded standalone once it turns out to be deliberate but rarely wanted; nothing is ever moved back in. Several members contain general and personal guidance in one file and become decidable only after a rewrite splits them.
13
+ An artifact leaves this collection by promotion into a public or personal collection, by moving into an opt-in collection once it turns out to be wanted often but only on the machines using one vendor's ecosystem, or by declaring `standalone:` once it turns out to be deliberate but rarely wanted. Nothing that has left is ever moved back in. Several members contain general and personal guidance in one file and become decidable only after a rewrite splits them.
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: williamthorsen
3
3
  description: The vetted personal set (artifacts that deliberately encode William Thorsen's preferences, environment, and domain).
4
+ disposition: personal
4
5
  members:
5
6
  rulebooks:
6
7
  - williamthorsen-code-layout-preferences
@@ -18,7 +19,7 @@ members:
18
19
 
19
20
  # William Thorsen
20
21
 
21
- The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The nine rulebooks state one author's preferences as rules that another team would answer differently, and `people-report` serves a domain in which one author works rather than one that every project shares.
22
+ The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The nine rulebooks state one author's preferences as rules that another team would decide differently, and `people-report` serves a domain in which one author works rather than one that every project shares.
22
23
 
23
24
  Its closure contains `capture-feedback` and `capture-event` in `recommended` and nothing else, which makes declaring it safe alongside the public collection.
24
25
 
@@ -8,7 +8,7 @@ This README is for maintainers of this directory. It is not referenced by any `<
8
8
 
9
9
  Inlined into every rendered platform guidance file via the directive expander, which puts it in every session that loads one of those files. It does not have a destination of its own; `install` deployed a copy to `~/.agents/AGENTS.md` until that tier was retired, and both `install` and `uninstall` now remove what it left there.
10
10
 
11
- A subagent does not load any platform guidance file, so a section that its role's work needs is inlined from `_partials/` instead. This file composes from those same partials rather than restating them, which keeps the two routes from drifting: A section that reaches some subagent is in a partial included by both hosts, and one that reaches none stays written out here. `content/test-utils/shared-doctrine-carriers.ts` records the per-role coverage, and `content/__tests__/shared-doctrine-reach.unit.test.ts` asserts it along with the order in which the sections render.
11
+ A subagent does not load any platform guidance file, so a section that its role's work needs is inlined from `_partials/` instead. This file composes from those same partials rather than restating them, which keeps the two routes from drifting: A section delivered to some subagent is in a partial included by both hosts, and one not delivered to any subagent stays written out here. `content/test-utils/shared-doctrine-carriers.ts` records the per-role coverage, `content/__tests__/doctrine-reach.unit.test.ts` asserts that each section reaches its carriers, and `content/__tests__/shared-doctrine-reach.unit.test.ts` asserts that it reaches no other subagent and the order in which the sections render.
12
12
 
13
13
  ## Ambient delivery: Harness regions
14
14
 
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  slug: accessibility-conventions
3
- description: 'Accessibility of interfaces: usability before style, and contrast and size floors for text. Consult before writing an artifact page, a prototype, or a mockup, before defining or changing colour tokens, and before writing CSS or a UI component.'
4
- delivery: [ambient, skill]
5
- version: '1'
3
+ description: 'Accessibility of interfaces: usability before style, contrast and size floors for text, the states that show an element is interactive, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
4
+ delivery: [skill]
5
+ version: '2'
6
6
  ---
7
7
 
8
8
  # Accessibility conventions
9
9
 
10
- Accessibility and usability are requirements, not a finishing touch. Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a shipped interface.
10
+ Accessibility and usability are requirements, not a finishing touch. Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
11
11
 
12
12
  The standard is WCAG 2.2 AA. This rulebook restates only the values that an agent checks while authoring and the rules that WCAG does not set; for everything else, follow WCAG.
13
13
 
@@ -15,6 +15,24 @@ The standard is WCAG 2.2 AA. This rulebook restates only the values that an agen
15
15
 
16
16
  - **Contrast.** Every text colour meets SC 1.4.3 against each surface on which it is set, in each theme that the page defines: 4.5:1, or 3:1 for large text (at least 24px, or at least 18.7px bold).
17
17
  - **Size.** Body text is at least 14px, and secondary text (captions, counts, states, hints) at least 12px. WCAG does not set either floor.
18
- - **Tiers.** Use two text colours, primary and secondary. Add a third only if it meets the same contrast floor; a third tier that passes sits within a few shades of the second and adds little.
18
+ - **Tiers.** Use two text colours, primary and secondary. Add a third only if it meets the same contrast floor; a third tier that passes is within a few shades of the second and adds little.
19
19
 
20
20
  Check contrast whenever colour tokens are defined or changed. Compute the WCAG contrast ratio of each text token against each surface token on which it is used, in each theme, compositing any translucent colour or `opacity` over its surface first. Report every failing pair with its ratio, and fix it before presenting the page.
21
+
22
+ ## Interaction states
23
+
24
+ Every element that responds to a click or a key shows that it does:
25
+
26
+ - **Pointer.** The cursor is a pointer over it.
27
+ - **Hover.** Its appearance changes while the pointer is over it.
28
+ - **Focus.** A visible indicator marks it while it has keyboard focus, per SC 2.4.7, and the indicator meets the 3:1 non-text contrast of SC 1.4.11 against its surface.
29
+
30
+ A disabled element, whether disabled by the native attribute or by `aria-disabled`, shows neither the hover state nor the pointer.
31
+
32
+ Put the states in a base style or a shared component rather than setting them at each call site, so that a new element has them without anyone remembering to add them. Do not rely on a framework's or a reset's defaults: Some remove the pointer from a button.
33
+
34
+ ## Checking in a browser
35
+
36
+ Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
37
+
38
+ When a browser is not available, report that the check did not run and name the elements that it would have covered. Never report it as passed.
@@ -0,0 +1,206 @@
1
+ ---
2
+ slug: cli-conventions
3
+ description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, JSON output, progress and outcome reports, check results, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
4
+ delivery: skill
5
+ version: '5'
6
+ ---
7
+
8
+ # CLI conventions
9
+
10
+ A CLI has two kinds of reader. A person at a terminal reads its help and its messages, and a script or an agent reads its exit code and its streams. A terminal cannot follow a link, and a script cannot read a message, so each rule below serves one of the two without breaking the other.
11
+
12
+ These rules apply whatever language the tool is written in.
13
+
14
+ ## Subcommand names
15
+
16
+ - **A subcommand that acts names its action and its object**, so that a reader of the bare command line can tell what it does. The object may be left out when the tool acts on only one, as in `<bin> deploy`.
17
+ - **A flat verb-object name fits while the object has one action**: `<bin> show-instance-page`. **A noun group with verb subcommands fits once the object has several**: `<bin> instance-page show`, `<bin> instance-page reload`.
18
+ - **An existing name that breaks these rules is not precedent for a new one.**
19
+
20
+ Example, for a subcommand that prints the page of the running instance:
21
+
22
+ - ❌ `<bin> page`
23
+ - ✅ `<bin> show-instance-page`, which becomes `<bin> instance-page show` once the instance page has a second action
24
+
25
+ ## Subcommands and options
26
+
27
+ - **An action is a subcommand, and an option changes how an action runs.** A reader scans the subcommands to learn what a tool can do, and scans one subcommand's options to learn how to adjust it.
28
+ - **Flags that select different actions are subcommands.** A set of mutually exclusive flags, each of which makes the command do something different, hides the tool's actions among its options and leaves a reader to discover which flags cannot be combined.
29
+
30
+ Example, for a tool that either verifies a file against its template or creates it:
31
+
32
+ - ❌ `<bin> --verify`, `<bin> --create`
33
+ - ✅ `<bin> verify-file`, `<bin> create-file`
34
+
35
+ ## Standard option names
36
+
37
+ These options mean the same thing in every tool, so that a reader who knows one tool can guess them in another, and a script that passes one does not get a different behavior. A tool that offers the behavior uses the name, and a tool does not use any of these names, long or short, for anything else.
38
+
39
+ | Option | Meaning |
40
+ | ----------------- | ----------------------------------------------------------------- |
41
+ | `-h`, `--help` | Print help and exit 0 |
42
+ | `-V`, `--version` | Print the version and exit 0 |
43
+ | `-c`, `--config` | Read configuration from the file at this path |
44
+ | `-n`, `--dry-run` | Report what a command that writes would change, and write nothing |
45
+ | `-f`, `--force` | Proceed past a safety check or a confirmation |
46
+ | `-q`, `--quiet` | Print less: verdicts and errors only |
47
+ | `-v`, `--verbose` | Print more: per-step detail |
48
+ | `--json` | Print the result as JSON on stdout |
49
+ | `--write` | Let a command that reports by default write its changes |
50
+ | `--no-color` | Turn off color and other terminal styling |
51
+
52
+ Every tool responds to `--version`, so that a bug report can name the version that produced it.
53
+
54
+ Example, for a tool that reads its input from a file:
55
+
56
+ - ❌ `<bin> -f input.json`, with `-f` meaning `--file`
57
+ - ✅ `<bin> --file input.json`, which leaves `-f` to mean `--force`
58
+
59
+ ## Configuration
60
+
61
+ - **A tool that reads a config file accepts `--config <path>`, short `-c`.** A relative path resolves against the working directory, as every other path argument does.
62
+ - **A setting resolves in the order flag, environment variable, config file, built-in default.** The value given closest to the invocation wins, so that one run can override a project's setting without editing the file.
63
+ - **A path given to `--config` that does not exist is an error.** Falling back to defaults would run the command with settings that the caller did not ask for. A config file that the tool looks up by itself may be absent; then the defaults apply.
64
+
65
+ Example, for `<bin> --config ./ci.yaml` run in a directory that does not contain `ci.yaml`:
66
+
67
+ - ❌ The command runs with the built-in defaults and reports success.
68
+ - ✅ `<bin>: --config ./ci.yaml: file not found` on stderr, with exit 2
69
+
70
+ ## Writing modes
71
+
72
+ A command's default follows its purpose.
73
+
74
+ - **A command whose purpose is a change writes by default** and offers `--dry-run`, which reports what it would change and writes nothing. A deploy, an install, and a migration are such commands.
75
+ - **A command whose main use is reporting reports by default** and writes only under `--write`. A check, a scan, and a formatter are such commands. Its report says what `--write` would change, so that the reader knows the next step.
76
+
77
+ Example, for a formatter run without `--write` on files that need changes:
78
+
79
+ - ❌ `<bin>: 3 files need formatting`
80
+ - ✅ `<bin>: 3 files need formatting; run <bin> --write to format them`
81
+
82
+ ## Help
83
+
84
+ - **Every command and subcommand responds to `--help` and `-h`.** A subcommand prints its own help, not the top level's.
85
+ - **`--help` is an option of every command, and it is handled before arguments are validated.** `<bin> deploy --help` prints the help of `deploy`, never "Unknown option", and prints it even when a required argument of `deploy` is missing.
86
+ - **Help states** the one-line purpose, the usage synopsis, the arguments, the options, and at least one example. A tool that needs an external program names it.
87
+ - **Requested help goes to stdout and exits 0**, so that it can be piped to a pager or a search.
88
+ - **Usage printed after an error goes to stderr and exits non-zero**, so that it does not mix with the command's output.
89
+
90
+ ## Exit codes
91
+
92
+ | Situation | Exit code |
93
+ | ------------------------------------------------------------------------ | --------- |
94
+ | Success | 0 |
95
+ | `--help`, `-h`, `--version`, or `-V` | 0 |
96
+ | A check that ran and found problems | 1 |
97
+ | Any other failure while running | 1 |
98
+ | Usage error: bad input, a missing argument, an unknown command or option | 2 |
99
+ | Required external command not found | 127 |
100
+
101
+ A usage error exits 2 so that a script that runs a check can tell the problems that the check found from a mistake in its own invocation.
102
+
103
+ ## Error messages
104
+
105
+ - **Errors go to stderr**, never to stdout, where they would be read as output.
106
+ - **Each error is prefixed with the program's name**, as `<bin>: message`, so that a reader of combined output can tell which program wrote it. A subcommand's errors may name the subcommand too: `<bin> deploy: message`.
107
+ - **Each error names the fix.** State what went wrong, then the command or action that resolves it. A refusal names the condition under which the command would run.
108
+ - **An unknown command or option suggests the nearest valid name**, so that a typo costs one more run rather than a trip to the help.
109
+ - **An invalid value lists the accepted values.** A tool rejects a value that it does not accept, from a flag or from an environment variable, rather than silently falling back to a default.
110
+ - **A secret is never taken as an argument**, because shell history and the process list expose arguments. A secret comes from stdin, a prompt, or a file.
111
+
112
+ Example, for a deploy that refuses to run from a dirty checkout:
113
+
114
+ - ❌ `Error: working tree not clean`
115
+ - ✅ `<bin> deploy: the working tree has uncommitted changes; commit or stash them, then run <bin> deploy again`
116
+
117
+ Example, for an invalid value:
118
+
119
+ - ❌ `<bin>: invalid --format`
120
+ - ✅ `<bin>: --format accepts text or json, not yaml`
121
+
122
+ Example, for a command that needs an access token:
123
+
124
+ - ❌ `<bin> publish --token <value>`
125
+ - ✅ `<bin> publish --token-file <path>`, or the token piped to `<bin> publish --token-stdin`
126
+
127
+ ## JSON output
128
+
129
+ - **A command whose output a script or an agent may read supports `--json`.** Parsing text written for a person breaks when its wording changes.
130
+ - **Under `--json`, stdout contains one JSON document and nothing else.** A command that streams records as it finds them writes JSON Lines instead, one object per line.
131
+ - **Progress, warnings, and errors still go to stderr in their usual form, and the exit code keeps its meaning.** A failure is not wrapped in a JSON envelope that exits 0, because a caller that checks the exit code would read it as success.
132
+ - **A published field is part of the tool's interface.** Adding a field is safe; renaming, retyping, or removing one is a breaking change.
133
+
134
+ Example, for a check that found problems, run with `--json`:
135
+
136
+ - ❌ `{"ok":false,"problems":[...]}` with exit 0
137
+ - ✅ `{"problems":[...]}` on stdout with exit 1
138
+
139
+ ## Progress and outcome
140
+
141
+ These rules apply to a command that runs for more than a moment or changes state: a deploy, an install, a migration, a sync.
142
+
143
+ - **Report each step as it completes**, one line per step, so that a reader can tell where a slow or failed run stopped.
144
+ - **End with what changed.** Name the state before and after when both exist, such as the release replaced and the release deployed. When nothing changed, say so in a line of its own; silence does not distinguish "nothing to do" from "did nothing".
145
+ - **A failure partway through names what completed and what did not**, then exits non-zero.
146
+ - **Keep the default output short.** An agent that runs the command keeps every line in its context, so put per-step detail behind a verbose flag rather than in the default output.
147
+ - **Progress goes to stderr when stdout contains data**, so that a pipe receives the data alone.
148
+
149
+ Example, for `<bin> deploy`:
150
+
151
+ - ❌ `<bin> deploy: deployed 20261012-142530Z-a10a17e`
152
+ - ✅ One line for each step (pull, build, stage, restart, readiness check), then `<bin> deploy: replaced 20261009-091200Z-4c2e8b1 with 20261012-142530Z-a10a17e (3 commits)`
153
+
154
+ ## Check results
155
+
156
+ These rules apply to a command that checks state without changing it: a `check` or `verify` mode, a health probe, a pre-flight.
157
+
158
+ - **Each item's line states what it checked and the state that it found**, on a pass as well as on a failure. A bare `PASS` does not say what was compared with what, so a reader cannot tell a check that verified something from one that compared nothing.
159
+ - **A failure shows its evidence in the default output**: a diff for a file compared with its definition, the actual state otherwise. A reader who sees only the verdict must run the check again, or reproduce it by hand, to learn what is wrong.
160
+ - **A check whose items read only configuration also probes the function that the configuration serves, end to end.** Configuration that matches its definition does not show that the service works: A resolver can match its config file and still fail to answer a query.
161
+ - **`--verbose` adds only detail too long to print on every run.** The per-item lines and a failure's evidence belong in the default output. The exit code stays the contract for scripts, as "Exit codes" states.
162
+
163
+ Example, for `<bin> check` on a host whose hosts file matches its definition and whose resolver config does not:
164
+
165
+ - ❌ `PASS hosts`, then `FAIL resolver`
166
+ - ✅ `PASS hosts: /etc/hosts matches hosts.conf`, then `FAIL resolver: /etc/resolv.conf differs from resolver.conf`, followed by the diff
167
+
168
+ ## Color
169
+
170
+ - **Color and other terminal styling appear only when the stream is a terminal.** Escape codes written to a file or a pipe corrupt the text that the reader receives.
171
+ - **A set `NO_COLOR` environment variable, or `--no-color`, turns styling off** even on a terminal.
172
+
173
+ Example, for `<bin> list > list.txt`:
174
+
175
+ - ❌ `list.txt` contains `\e[32mok\e[0m deploy`
176
+ - ✅ `list.txt` contains `ok deploy`
177
+
178
+ ## Logic and presentation
179
+
180
+ - **A command's logic returns a result value.** It does not write to a stream, and it does not exit.
181
+ - **A renderer turns the result into output.** The text renderer and the JSON renderer read the same result, so the two outputs cannot disagree, and each can be tested without running the command.
182
+ - **Only the entry point writes to stdout and stderr and sets the exit code.**
183
+ - **A library module never prints.** It returns what it found, such as a warning or a fallback that it took, and its caller decides whether and how to report it. A library that prints takes that decision from every caller, including one that runs under `--json` or `--quiet`.
184
+
185
+ Example, for a library function that finds an invalid state file and falls back to an empty one:
186
+
187
+ - ❌ The function prints "existing state is invalid and will be reset", even when its caller is a dry run that resets nothing.
188
+ - ✅ The function returns the empty state with a flag that records the fallback, and each caller reports it in its own terms.
189
+
190
+ ## Help topics
191
+
192
+ These rules apply to any CLI that prints a doc as a help topic, as `<bin> help <topic>`.
193
+
194
+ - **A link to another topic** prints as the command that prints that topic: `<bin> help <topic>`.
195
+ - **A link to anything else** prints as its absolute URL.
196
+ - **The source doc keeps its relative links**, so that it still works where it is read as Markdown, such as on a code host. The CLI rewrites each link when it prints the topic.
197
+ - **The file stem also names the topic.** When a doc's file name differs from its topic name, `<bin> help` accepts the stem of the file name as well, so that a name copied from the source still resolves.
198
+
199
+ ### Example
200
+
201
+ A topic's source says "See authoring kits and the changelog", linking the first phrase to `./authoring-kits.md`, the doc of the `kits` topic, and the second to `../CHANGELOG.md`, which is not a topic. `<bin> help` prints:
202
+
203
+ - ❌ The raw Markdown, with both relative paths.
204
+ - ✅ `See authoring kits (<bin> help kits) and the changelog (https://example.com/repo/blob/main/CHANGELOG.md).`
205
+
206
+ With the stem alias, `<bin> help authoring-kits` prints the same topic as `<bin> help kits`.