codeassembly-guidance 0.1.0 → 0.2.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 (137) hide show
  1. package/.meta/changelog.json +757 -0
  2. package/CHANGELOG.md +181 -0
  3. package/README.md +125 -95
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +2 -2
  6. package/content/_partials/code-style.md +1 -1
  7. package/content/_partials/comment-discipline.md +1 -1
  8. package/content/_partials/plain-speech-calibration.md +4 -0
  9. package/content/_partials/technical-recommendations.md +1 -0
  10. package/content/codeassembly-content.yaml +11 -1
  11. package/content/collections/all.md +2 -2
  12. package/content/collections/atlassian.md +2 -1
  13. package/content/collections/recommended.md +9 -2
  14. package/content/collections/triage.md +3 -67
  15. package/content/collections/williamthorsen.md +2 -1
  16. package/content/guidance/README.md +1 -1
  17. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  18. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  19. package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
  20. package/content/guidance/rulebooks/commit-conventions.md +2 -2
  21. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  22. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  23. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  24. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  25. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  26. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
  27. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  28. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  29. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  30. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  31. package/content/guidance/shared/AGENTS.md +8 -0
  32. package/content/scripts/README.md +5 -2
  33. package/content/scripts/check-branch-currency.mjs +11 -0
  34. package/content/scripts/check-prose.mjs +171 -0
  35. package/content/scripts/describe-change.mjs +97 -97
  36. package/content/scripts/manage-jira-ticket.mjs +99 -94
  37. package/content/scripts/resolve-frontmatter.sh +1 -1
  38. package/content/scripts/resolve-review-run.mjs +9 -9
  39. package/content/scripts/select-lede-exemplars.mjs +87 -87
  40. package/content/scripts/validate-preferences.mjs +146 -0
  41. package/content/skills/_data/artifact-conventions.md +46 -14
  42. package/content/skills/_data/branch-currency.md +36 -0
  43. package/content/skills/_data/change-record.md +2 -2
  44. package/content/skills/_data/design-priorities.md +3 -3
  45. package/content/skills/_data/project-stage.md +32 -0
  46. package/content/skills/_data/recommendation-gradient.md +9 -7
  47. package/content/skills/_data/scope-and-deferral.md +1 -1
  48. package/content/skills/_data/spike-conventions.md +1 -1
  49. package/content/skills/_data/ticket-evaluation.md +2 -2
  50. package/content/skills/_data/ticket-source-resolution.md +36 -3
  51. package/content/skills/_data/title-templates.md +19 -11
  52. package/content/skills/_partials/action-items.md +2 -2
  53. package/content/skills/_partials/commit-title-rendering.md +1 -1
  54. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  55. package/content/skills/_partials/next-steps-after-plan.md +10 -10
  56. package/content/skills/_partials/next-steps-after-review.md +9 -9
  57. package/content/skills/_partials/option-format.md +18 -17
  58. package/content/skills/_partials/plan-template.md +5 -5
  59. package/content/skills/_partials/split-ticket-compose.md +1 -1
  60. package/content/skills/_partials/split-ticket-create.md +1 -1
  61. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  62. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  63. package/content/skills/add-change-record/SKILL.md +2 -2
  64. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  65. package/content/skills/anti-patterns/SKILL.md +1 -1
  66. package/content/skills/assess-usability/SKILL.md +96 -0
  67. package/content/skills/capture-event/SKILL.md +2 -2
  68. package/content/skills/capture-event/capture-event.mjs +89 -89
  69. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  70. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  71. package/content/skills/collaborate/SKILL.md +1 -1
  72. package/content/skills/create-gh-pr/SKILL.md +24 -9
  73. package/content/skills/create-pr/SKILL.md +5 -5
  74. package/content/skills/create-ticket/SKILL.md +61 -16
  75. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  76. package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
  77. package/content/skills/design-and-plan/SKILL.md +13 -10
  78. package/content/skills/groom-backlog/SKILL.md +8 -6
  79. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  80. package/content/skills/implement-plan/SKILL.md +25 -21
  81. package/content/skills/index-prototypes/SKILL.md +85 -30
  82. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  83. package/content/skills/kb-add/SKILL.md +2 -1
  84. package/content/skills/kb-add/kb-add.mjs +128 -128
  85. package/content/skills/kb-curate/SKILL.md +9 -7
  86. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  87. package/content/skills/kb-edit/SKILL.md +3 -3
  88. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  89. package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
  90. package/content/skills/kb-retrieve-events/SKILL.md +1 -1
  91. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
  92. package/content/skills/kb-update-events/SKILL.md +2 -2
  93. package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
  94. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  95. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  96. package/content/skills/merge-pr/SKILL.md +11 -11
  97. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  98. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  99. package/content/skills/plan/SKILL.md +1 -1
  100. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  101. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  102. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  103. package/content/skills/refine-plan/SKILL.md +7 -3
  104. package/content/skills/refine-prototype/SKILL.md +113 -0
  105. package/content/skills/respond-to-review/SKILL.md +1 -1
  106. package/content/skills/review-bb-pr/SKILL.md +1 -1
  107. package/content/skills/review-branch/SKILL.md +4 -2
  108. package/content/skills/review-criteria/SKILL.md +36 -3
  109. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  110. package/content/skills/revise-comments/SKILL.md +38 -5
  111. package/content/skills/revise-prose/SKILL.md +1 -1
  112. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  113. package/content/skills/save-artifact/SKILL.md +2 -0
  114. package/content/skills/streamline-guidance/SKILL.md +1 -1
  115. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  116. package/content/skills/summarize-change/SKILL.md +22 -13
  117. package/content/skills/testing-conventions/SKILL.md +74 -7
  118. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  119. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  120. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  121. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  122. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  123. package/content/skills/update-project-guidance/SKILL.md +2 -2
  124. package/content/subagents/_data/claude.yaml +6 -0
  125. package/content/subagents/_data/rovo.yaml +12 -2
  126. package/content/subagents/canary.md +2 -1
  127. package/content/subagents/disposition-challenger.md +78 -0
  128. package/content/subagents/entry-drafter.md +14 -10
  129. package/content/subagents/handoff-reviewer.md +2 -2
  130. package/content/subagents/plan-reviewer.md +1 -1
  131. package/content/subagents/prose-reviser.md +4 -2
  132. package/content/subagents/ticket-assessor.md +9 -6
  133. package/content/subagents/usability-assessor.md +157 -0
  134. package/package.json +15 -11
  135. package/schemas/preferences.v1.json +29 -2
  136. package/schemas/work-types.v1.json +1 -1
  137. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -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, and progress reports, 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, and `content/__tests__/shared-doctrine-reach.unit.test.ts` asserts it along with 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,192 @@
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, 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: '4'
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
+ ## Color
155
+
156
+ - **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.
157
+ - **A set `NO_COLOR` environment variable, or `--no-color`, turns styling off** even on a terminal.
158
+
159
+ Example, for `<bin> list > list.txt`:
160
+
161
+ - ❌ `list.txt` contains `\e[32mok\e[0m deploy`
162
+ - ✅ `list.txt` contains `ok deploy`
163
+
164
+ ## Logic and presentation
165
+
166
+ - **A command's logic returns a result value.** It does not write to a stream, and it does not exit.
167
+ - **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.
168
+ - **Only the entry point writes to stdout and stderr and sets the exit code.**
169
+ - **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`.
170
+
171
+ Example, for a library function that finds an invalid state file and falls back to an empty one:
172
+
173
+ - ❌ The function prints "existing state is invalid and will be reset", even when its caller is a dry run that resets nothing.
174
+ - ✅ The function returns the empty state with a flag that records the fallback, and each caller reports it in its own terms.
175
+
176
+ ## Help topics
177
+
178
+ These rules apply to any CLI that prints a doc as a help topic, as `<bin> help <topic>`.
179
+
180
+ - **A link to another topic** prints as the command that prints that topic: `<bin> help <topic>`.
181
+ - **A link to anything else** prints as its absolute URL.
182
+ - **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.
183
+ - **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.
184
+
185
+ ### Example
186
+
187
+ 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:
188
+
189
+ - ❌ The raw Markdown, with both relative paths.
190
+ - ✅ `See authoring kits (<bin> help kits) and the changelog (https://example.com/repo/blob/main/CHANGELOG.md).`
191
+
192
+ With the stem alias, `<bin> help authoring-kits` prints the same topic as `<bin> help kits`.
@@ -1,8 +1,9 @@
1
1
  ---
2
2
  slug: codeassembly-content-specification
3
3
  description: The declaration contract and authoring doctrine for CodeAssembly skills, subagents, rulebooks, and collections -- frontmatter, dependencies, invocation tokens, how broad a guidance change goes, and when a procedure belongs in a helper.
4
+ standalone: wanted by repositories that author CodeAssembly content, which declare it directly
4
5
  delivery: skill
5
- version: '29'
6
+ version: '31'
6
7
  ---
7
8
 
8
9
  # CodeAssembly content specification
@@ -13,7 +14,7 @@ The declaration contract for CodeAssembly artifacts -- skills, subagents, rulebo
13
14
 
14
15
  Every rule below belongs to one of three classes, marked where it appears.
15
16
 
16
- **Validated on parse.** A malformed `slug` or `skill-name`, a `delivery` value outside `ambient`/`hook`/`skill`, an empty `delivery` list, an unknown artifact-type key, a non-list value under one, and a `members:` block on anything but a collection each fail the run with an error naming the source file. Seven more fail outside the parser: a token naming an artifact that does not exist fails the run with an error naming the slug and the directories searched, whether it names that artifact as a dependency or optionally; a rulebook link target outside a linkable root fails the run before anything is written; a rulebook token naming a target that does not deploy a skill to invoke fails the same pre-write pass, and so does a rulebook token written in the optional form, which does not have a name to render; an anchor-only link target that does not name any heading in its own body fails wherever that body is rendered or installed, and so does a code fence that nothing closes; and a harness that does not declare a sigil is a type error at its `HarnessConfig` literal, so the build fails.
17
+ **Validated on parse.** A malformed `slug` or `skill-name`, a rulebook without `delivery`, a `delivery` value outside `ambient`/`hook`/`skill`, an empty `delivery` list, an unknown artifact-type key, a non-list value under one, a `members:` block or a `disposition:` on anything but a collection, and a `standalone:` on a collection each fail the run with an error naming the source file. Seven more fail outside the parser: a token naming an artifact that does not exist fails the run with an error naming the slug and the directories searched, whether it names that artifact as a dependency or optionally; a rulebook link target outside a linkable root fails the run before anything is written; a rulebook token naming a target that does not deploy a skill to invoke fails the same pre-write pass, and so does a rulebook token written in the optional form, which does not have a name to render; an anchor-only link target that does not name any heading in its own body fails wherever that body is rendered or installed, and so does a code fence that nothing closes; and a harness that does not declare a sigil is a type error at its `HarnessConfig` literal, so the build fails.
17
18
 
18
19
  **Enforced by `validate`.** `codeassembly validate` checks a content root against these rules without deploying it. Such a rule names `validate`.
19
20
 
@@ -45,13 +46,13 @@ Slugs are kebab-case and letter-led (`[a-z][a-z0-9-]*`). The sigils are a typed
45
46
 
46
47
  A token is also a dependency edge: `sync` extracts the tokens from a rulebook's, skill's, or subagent's include-expanded body and pulls each target into the deploy closure. An inline invocation is therefore expressed once, as the token -- it does not need a duplicate `dependencies:` entry, and a token naming a non-existent artifact fails the run just as a missing `dependencies:` edge does. Because extraction runs on the include-expanded body, a token inside a shared `_partials` file becomes an edge for every artifact that inlines it.
47
48
 
48
- A skill or subagent token has an optional form, marked `?` before the colon: `{skill?:<slug>}` and `{subagent?:<slug>}`. It renders exactly as the required form does, so an invocation reads the same wherever the target deploys. Its target must still exist: `sync` resolves one, and a rename or a deletion fails the run. Because it does not contribute an edge, the target deploys only if a declaration reaches it another way. Use it when a body names an artifact that a consumer may not want, such as a platform delegate for an ecosystem not used by the consumer.
49
+ A skill or subagent token has an optional form, marked `?` before the colon: `{skill?:<slug>}` and `{subagent?:<slug>}`. It renders exactly as the required form does, so an invocation reads the same wherever the target deploys. Its target must still exist: `sync` resolves one, and a rename or a deletion fails the run. Because it does not contribute an edge, the target deploys only if a declaration includes it some other way. Use it when a body names an artifact that a consumer may not want, such as a platform delegate for an ecosystem not used by the consumer.
49
50
 
50
51
  `{rulebook?:<slug>}` fails the run: A rulebook token renders the skill name under which its target deploys, and an undeployed target supplies that name nowhere. `dependencies:` does not have an optional counterpart, because a frontmatter entry exists to pull an artifact in; a body that names one without pulling it in is the only case that the marker addresses. A content root declares content format 2 if any body that it contains, a `_partials` file included, uses an optional token. _(Enforced by `validate`.)_
51
52
 
52
53
  A support entry under `skills/` does not contribute an edge: It is linked to rather than inlined, so `sync` never reads it. Each skill or subagent that links into the section containing a required `{skill:<slug>}` or `{subagent:<slug>}` token declares its target under `dependencies:`. An optional token there is exempt, since asserting the target may be absent is the opposite of guaranteeing its presence. The requirement depends on the fragment: A bare link to the file does not have a requirement, and a link to an enclosing heading has the requirements of its subsections. _(Enforced by `validate`, which also reports a support-entry token naming an artifact that the content root does not contain, optional or required.)_
53
54
 
54
- Rulebooks, skills, and subagents all support tokens; collections do not have a body to render. `{rulebook:<slug>}` has one restriction that the others do not: It renders only if a declaration supplies the deployed rulebook set, which is true for every body that `sync` and `validate` render but not for a support entry under `skills/`, since a source's support entries deliver to every consumer of the source, whichever rulebooks that consumer declares. A rulebook token in a support entry fails the run, as does one naming a rulebook that does not deploy a skill -- an `ambient`-only target is already in the reader's context, so there is nothing to invoke. Express that relationship with `dependencies:` instead.
55
+ Rulebooks, skills, and subagents all support tokens; collections do not have a body to render. `{rulebook:<slug>}` has one restriction that the others do not: It renders only if a declaration supplies the deployed rulebook set, which is true for every body that `sync` and `validate` render but not for a support entry under `skills/`, since a source's support entries are delivered to every consumer of the source, whichever rulebooks that consumer declares. A rulebook token in a support entry fails the run, as does one naming a rulebook that does not deploy a skill -- an `ambient`-only target is already in the reader's context, so there is nothing to invoke. Express that relationship with `dependencies:` instead.
55
56
 
56
57
  That boundary decides what a shared partial may contain. A partial inlined by both a skill body and a support entry cannot contain a `{rulebook:<slug>}` token: It renders in the skill but breaks the support entry's delivery.
57
58
 
@@ -87,7 +88,10 @@ A heading containing a token cannot be anchored: It renders to a different slug
87
88
 
88
89
  ## Collections
89
90
 
90
- A collection's only payload is a `members:` block -- the constituents that it pulls into the deployed closure. List them per type (the same shape that `dependencies:` uses), or use the computed token `'@library'` for every rulebook, skill, and subagent in the content root to which the collection belongs, the source from which it resolved:
91
+ A collection's payload is a `members:` block -- the constituents that it pulls into the deployed closure -- and an optional `disposition:`. List the members per type (the same shape that `dependencies:` uses), or name a computed token, which expands within the content root to which the collection belongs, the source from which it resolved:
92
+
93
+ - `'@library'`: every rulebook, skill, and subagent in that root.
94
+ - `'@unclaimed'`: every rulebook, skill, and subagent in that root that does not declare `standalone:` and is not enumerated by any collection with a `disposition:`. The root must declare content format 3 or later.
91
95
 
92
96
  ```yaml
93
97
  members:
@@ -99,16 +103,35 @@ members:
99
103
 
100
104
  `members:` is collections-only; rulebooks, skills, and subagents use `dependencies:` instead. Declaring `dependencies:` on a collection, or `members:` on any other type, is an error. The resolver follows both keys identically -- the split is semantic: A collection contains members, an artifact depends on prerequisites.
101
105
 
106
+ ### Dispositions
107
+
108
+ A `disposition:` states what membership in a collection that enumerates its members claims about them, and `codeassembly validate` holds the root to that claim. A collection without one is a plain bundle: Its membership does not claim anything, so it neither covers an artifact nor conflicts with a disposition.
109
+
110
+ - `public`: Its members are generally fit. Its closure may reach only the members of public collections.
111
+ - `personal`: Its members are fitted to one author. Its closure may reach the members of personal and public collections.
112
+ - `opt-in`: Its members are fitted to one vendor ecosystem. Its closure may reach its own members and the members of public collections, and the closure of every other collection, other than an `'@library'` one, must not reach its members, so that only a consumer declaring it deploys them.
113
+
114
+ An artifact that is deliberately outside every collection declares `standalone:` in its own frontmatter, with the reason as the value. A collection must not enumerate it, and the closure of a collection, other than an `'@library'` one, must not reach it. An artifact that several collections claim is within a closure's reach when any one of its claims is. `disposition:` on a collection whose members are computed, `standalone:` on a collection, and `disposition:` on any other type are errors.
115
+
116
+ `validate` checks a root that declares a disposition, a standalone artifact, or an `'@unclaimed'` collection, and reports each of these as a `disposition` defect:
117
+
118
+ - a standalone artifact that a collection enumerates, or that the closure of a collection other than an `'@library'` one reaches
119
+ - a collection with a disposition whose closure reaches an artifact outside its reach
120
+ - a collection, other than an `'@library'` one, whose closure reaches a member of an opt-in collection other than itself
121
+ - in a root without an `'@unclaimed'` collection, an artifact that is not covered by any disposition
122
+ - a `disposition:` or `standalone:` value that cannot be read
123
+
102
124
  ## Frontmatter fields
103
125
 
104
- - **Rulebooks:** `slug`, optional `description`, optional `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; defaults to `ambient`), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every route that delivers the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A route omits the line for a rulebook that does not declare a version. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
105
- - **Skills:** `name`, `description`, optional `user-invocable` (defaults to `true`), optional `supported-harnesses` (a harness id or list restricting deployment to those harnesses; absent deploys to all). The deploy writes every other key to every harness unchanged, so a key that only one harness reads, such as Claude's `context` or `model`, reaches the others, which ignore it.
126
+ - **Rulebooks:** `slug`, optional `description`, required `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; `ambient` only when nearly every session needs the content, since an ambient rulebook is loaded by every session that declares it, and `skill` or `hook` otherwise), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every route that delivers the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A route omits the line for a rulebook that does not declare a version. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
127
+ - **Skills:** `name`, `description`, optional `user-invocable` (defaults to `true`), optional `supported-harnesses` (a harness id or list restricting deployment to those harnesses; absent deploys to all). The deploy writes every other key to every harness unchanged, so a key that only one harness reads, such as Claude's `context` or `model`, is also written to the others, which ignore it.
106
128
  - **Subagents:** `name`, `description`, optional `tools`, optional `disallowedTools`, optional `maxTurns`, optional `skills` (skills injected into the subagent's context), optional `rulebooks` (rulebooks injected the same way, named by slug rather than by deploy name, so that a `skill-name` override on the target stays correct). `sync` pulls both lists into the deploy closure, merges each injected rulebook's deploy name into the deployed `skills:`, and drops the `rulebooks:` key from what it writes.
107
- - **Collections:** `name`, `description`, and a `members:` block -- the collection's only payload.
129
+ - **Collections:** `name`, `description`, a `members:` block, and an optional `disposition`; see [Dispositions](#dispositions).
130
+ - **Rulebooks, skills, and subagents** also take an optional `standalone`, the reason that the artifact is outside every collection; see [Dispositions](#dispositions).
108
131
 
109
132
  A subagent's tool grant is either named or inherited. `tools` names the grant outright; a subagent that omits it inherits the harness's whole subagent tool pool, and `disallowedTools` then removes names from whatever pool results. Use inheritance when the subagent needs a tool that an allowlist cannot name -- an MCP tool whose name varies by machine -- and weigh the consequence: A denylist names tools the same way an allowlist does, so it removes the listed names and nothing else. The residual grant is whatever the machine supplies, and the subagent's own instructions limit the rest. Choose inheritance when that residual is acceptable, and name a `tools` allowlist when it is not. Claude applies the denylist. Rovo does not read it, and its overlay names a `tools` allowlist for every subagent, so a subagent relying on inheritance states its Rovo grant in that overlay. _(Convention; not enforced.)_
110
133
 
111
- Only the rulebook row is validated on parse; a `members:` block is validated wherever it appears. The other rows are read leniently: A field consumed by a deploy pass takes effect, and an absent one falls back to a default rather than failing. A skill without a `description` appears in Rovo's prompt index with an empty one. _(Convention; not enforced.)_
134
+ Only the rulebook row is validated on parse; a `members:` block is validated wherever it appears, and `validate` reads every `disposition` and `standalone` in the root. The other rows are read leniently: A field consumed by a deploy pass takes effect, and an absent one falls back to a default rather than failing. A skill without a `description` appears in Rovo's prompt index with an empty one. _(Convention; not enforced.)_
112
135
 
113
136
  ### Version bumps
114
137
 
@@ -26,7 +26,7 @@ The branch name records the ticket. Include the ID at the end of the commit body
26
26
 
27
27
  ## Commit body
28
28
 
29
- **Body voice.** The body is a source that the entry drafter reads, not an entry that a reader meets. Report what the commit did, completely and factually, and leave the selecting to the drafter: It drops what the change's reader would not act on. The drafter also reads the diff, so what the body adds is the intent behind an edit, which the hunks do not carry.
29
+ **Body voice.** The body is a source that the entry drafter reads, not an entry that a reader meets. Report what the commit did, completely and factually, and leave the selecting to the drafter: It drops what the change's reader would not act on. The drafter also reads the diff, so what the body adds is the intent behind an edit, which the hunks do not show.
30
30
 
31
31
  ### Body mechanics
32
32
 
@@ -60,7 +60,7 @@ See [`work-types.json`](../../skills/_data/work-types.json) for the canonical ta
60
60
 
61
61
  This section governs every work-type resolution: one commit, a multi-commit pull request, and a merge commit alike.
62
62
 
63
- Pick the type that best describes the change's dominant purpose. A type applies only when the change meets that type's own description in `work-types.json`; a type whose description the change does not meet is out of the running, and the tiebreak below never reaches it. When more than one type genuinely applies, tiebreak in favor of the higher tier (public > internal > process), then by earlier listing within a tier. The tiebreak is not a promotion rule: Raising the tier raises both the audience and the strength of the claim.
63
+ Pick the type that best describes the change's dominant purpose. A type applies only when the change meets that type's own description in `work-types.json`; a type whose description the change does not meet is excluded, and the tiebreak below never considers it. When more than one type genuinely applies, tiebreak in favor of the higher tier (public > internal > process), then by earlier listing within a tier. The tiebreak is not a promotion rule: Raising the tier raises both the audience and the strength of the claim.
64
64
 
65
65
  The tiebreak resolves the type. Having applied it, act on the result: A rule that resolves an input determines it, and re-presenting its output as a choice spends the developer's attention on a settled decision. When the result looks wrong for a specific change, apply it, state the outcome and the reservation in one sentence, and continue.
66
66
 
@@ -1,15 +1,16 @@
1
1
  ---
2
2
  slug: live-worktree-policy
3
3
  description: How a repository with a `live` worktree deploys, and where changes to it are authored.
4
+ standalone: wanted in the repositories that have a `live` worktree, which declare it directly
4
5
  delivery: ambient
5
- version: '2'
6
+ version: '3'
6
7
  ---
7
8
 
8
9
  # Live worktree policy
9
10
 
10
11
  A repository that keeps a worktree on a `live` branch deploys from that worktree, and never from the main one. Deployed configuration, installed commands, and loaded extensions all resolve through it, so a path derived from the main worktree names a file that nothing on the machine reads.
11
12
 
12
- Because `git worktree list` reports every worktree of a repository from any one of them, a `live` row identifies a participating repository and gives the deployment worktree's path in the same line. That worktree is named `{path}.live`, where `{path}` is the main worktree's path: `~/repos/projects/codeassembly` is accompanied by `~/repos/projects/codeassembly.live`. If the machine has the repo registry, `list-repos --tag live` enumerates the tagged set; for a registry whose entries do not have the tag, it returns nothing, which is not evidence that a repository does not deploy from a `live` worktree.
13
+ Because `git worktree list` reports every worktree of a repository from any one of them, a `live` row identifies a participating repository and gives the deployment worktree's path in the same line. That worktree is named `{path}.live`, where `{path}` is the main worktree's path: `~/repos/projects/codeassembly` is accompanied by `~/repos/projects/codeassembly.live`. If the machine has the repo registry, `thor-repo list --tag live` enumerates the tagged set; for a registry whose entries do not have the tag, it returns nothing, which is not evidence that a repository does not deploy from a `live` worktree.
13
14
 
14
15
  A merged change is deployed to the machine only once `live` is advanced to it. Until then the deployed behavior is the old one, so a change is not live while `live` still points at its predecessor.
15
16
 
@@ -11,7 +11,7 @@ A README answers two questions for a reader who arrived a moment ago: whether th
11
11
 
12
12
  ## Audience
13
13
 
14
- A README is written for people. `AGENTS.md` is the agent-facing companion, and it takes the context that an agent needs and a human reader does not: exact test invocations, constraints on what to modify, conventions that a contributor absorbs from the code but that an agent must be told.
14
+ A README is written for people. `AGENTS.md` is the agent-facing companion, and it contains the context that an agent needs and a human reader does not: exact test invocations, constraints on what to modify, conventions that a contributor absorbs from the code but that an agent must be told.
15
15
 
16
16
  The split is not a matter of taste. An agent loads `AGENTS.md` in full at every session, so a line there takes up context every time, whereas a human reads a README once and skims it later. Assigning content to a file by who reads it keeps both files short.
17
17
 
@@ -47,7 +47,7 @@ The opening makes up to three moves, in order. The first applies to every type;
47
47
  2. **How to get it running.** The install command, the import line, or the bootstrap command, whichever the type calls for.
48
48
  3. **The smallest thing that works.** One example, short enough to read without scrolling, that a reader can run unchanged.
49
49
 
50
- A README that reaches its second heading before making the moves that apply to it has buried its answer.
50
+ If the moves that apply to a README come after its second heading, the README presents its answer too late.
51
51
 
52
52
  ## Moving detail out of the README
53
53
 
@@ -71,4 +71,4 @@ These share a failure mode: Each stays wrong without a test failing or a reader
71
71
 
72
72
  ## Adding a type
73
73
 
74
- The table extends by rows. A new row is justified when it produces a README that its neighbors would get wrong, and it states four things: the slug that its marker takes, what the README leads with, what it keeps that the others drop, and what it omits that the others keep. A row differing from its neighbor only in wording is evidence that the distinction is not real; merge the two.
74
+ Extend the table by adding a row. A new row is justified when it produces a README that its neighbors would get wrong, and it states four things: the slug that its marker takes, what the README leads with, what it keeps that the others drop, and what it omits that the others keep. A row differing from its neighbor only in wording is evidence that the distinction is not real; merge the two.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  slug: shared-data-conventions
3
3
  description: 'Changes to shared data: unmerged code never writes to a shared store, and a change to the shape of persisted data proceeds as expand, migrate, contract. Consult before planning, implementing, or reviewing a change that alters the shape of persisted data or writes to a shared store.'
4
- delivery: [ambient, skill]
4
+ delivery: [skill]
5
5
  version: '1'
6
6
  ---
7
7
 
@@ -10,5 +10,5 @@ version: '1'
10
10
  Shared state is any store that a deployed product or another person reads, such as a production database or a content dataset. A local or disposable copy is not shared. The repository's `AGENTS.md` names which stores are shared and how their migrations run.
11
11
 
12
12
  - **Writes.** Unmerged code never writes to shared state, even when a plan or a ticket directs it. Asked to run a migration or another write against shared state from a branch, decline and name the route: Merge, then run it from merged code.
13
- - **Sequence.** A change to the shape of data proceeds as expand, migrate, contract. Expand adds the new shape alongside the old one, migrate moves the data, and contract removes the old shape once no deployed code reads it. Each step is its own change, merged and deployed before the next begins, so that every order of deploy and migration leaves the product working.
13
+ - **Sequence.** A change to the shape of data proceeds as expand, migrate, contract. Expand adds the new shape alongside the old one, migrate moves the data, and contract removes the old shape once the deployed code no longer reads it. Each step is its own change, merged and deployed before the next begins, so that every order of deploy and migration leaves the product working.
14
14
  - **Migrations.** A migration runs from merged code, by automation or by the developer, and by an agent only when the developer directs that run. It defaults to a dry run and is idempotent.