codeassembly-guidance 0.0.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.
- package/.meta/changelog.json +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +70 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +6 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +214 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +180 -0
- package/content/skills/_data/title-templates.md +632 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +85 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +148 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +71 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +317 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: accessibility-conventions
|
|
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
|
+
---
|
|
7
|
+
|
|
8
|
+
# Accessibility conventions
|
|
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 released interface.
|
|
11
|
+
|
|
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
|
+
|
|
14
|
+
## Text legibility
|
|
15
|
+
|
|
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
|
+
- **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 is within a few shades of the second and adds little.
|
|
19
|
+
|
|
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`.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: codeassembly-content-specification
|
|
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
|
|
5
|
+
delivery: skill
|
|
6
|
+
version: '31'
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# CodeAssembly content specification
|
|
10
|
+
|
|
11
|
+
The declaration contract for CodeAssembly artifacts -- skills, subagents, rulebooks, and collections. (Here "artifact" means an authored library item, not a generated output like a review or devlog.)
|
|
12
|
+
|
|
13
|
+
## Enforcement
|
|
14
|
+
|
|
15
|
+
Every rule below belongs to one of three classes, marked where it appears.
|
|
16
|
+
|
|
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.
|
|
18
|
+
|
|
19
|
+
**Enforced by `validate`.** `codeassembly validate` checks a content root against these rules without deploying it. Such a rule names `validate`.
|
|
20
|
+
|
|
21
|
+
**Convention.** The rest is marked _(Convention; not enforced.)_ Nothing checks it.
|
|
22
|
+
|
|
23
|
+
## Declaring dependencies
|
|
24
|
+
|
|
25
|
+
When a rulebook, skill, or subagent relies on another -- such as a skill that invokes another skill, or a subagent that calls a skill without injecting it -- declare the edge in its frontmatter `dependencies:` block, grouped by type:
|
|
26
|
+
|
|
27
|
+
```yaml
|
|
28
|
+
dependencies:
|
|
29
|
+
rulebooks:
|
|
30
|
+
- shell-conventions
|
|
31
|
+
skills:
|
|
32
|
+
- capture-event
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`sync` resolves these edges transitively, so declaring one artifact pulls in its whole closure. Prefer a declared dependency over a prose note that another artifact "must be present." _(Convention; not enforced.)_
|
|
36
|
+
|
|
37
|
+
## Invocation tokens
|
|
38
|
+
|
|
39
|
+
When a skill or subagent invocation appears inline in a skill's or subagent's body, write it as a token rather than a hardcoded harness-specific form:
|
|
40
|
+
|
|
41
|
+
- `{rulebook:<slug>}` renders to the harness skill sigil plus the skill name under which the named rulebook deploys -- its `skill-name` when it declares one, `consult-<slug>` otherwise. Because it resolves through the target rather than copying the slug, an override on the target stays correct at every call site.
|
|
42
|
+
- `{skill:<slug>}` renders to the harness skill sigil plus the slug -- `/<slug>` on Claude, `!<slug>` on Rovo.
|
|
43
|
+
- `{subagent:<slug>}` renders to the harness subagent sigil plus the slug. That sigil is empty on both current harnesses, so it renders to the bare slug, which is how a subagent is dispatched on each.
|
|
44
|
+
|
|
45
|
+
Slugs are kebab-case and letter-led (`[a-z][a-z0-9-]*`). The sigils are a typed property of each harness in `HarnessConfig`. A new harness must declare its own rendering or the build fails.
|
|
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.
|
|
48
|
+
|
|
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.
|
|
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`.)_
|
|
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.)_
|
|
54
|
+
|
|
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.
|
|
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.
|
|
58
|
+
|
|
59
|
+
Only `{rulebook:<slug>}` is checked for deployability, and the check covers the target's `supported-harnesses:`: A token in a body that deploys to a harness that the target excludes fails the run, naming the harnesses to which the target deploys. A subagent's `rulebooks:` entry is checked the same way. A `{skill:<slug>}` or `{subagent:<slug>}` token renders on every harness to which the body deploys, including one to which its target does not deploy: A token naming a skill that narrows itself with `supported-harnesses:` still renders an invocation elsewhere. Name such a skill only where the surrounding text already scopes it to that harness. _(Convention; not enforced.)_
|
|
60
|
+
|
|
61
|
+
Reserve a `dependencies:` entry for a non-inline edge; use a token for any invocation that appears in the body. _(Convention; not enforced.)_
|
|
62
|
+
|
|
63
|
+
## Links in rulebook bodies
|
|
64
|
+
|
|
65
|
+
A rulebook addresses a file by linking to it, not by naming it in prose. Author the target relative to the rulebook's own place in the content tree, which is `guidance/rulebooks/<slug>.md`, and `sync` emits the absolute path that each target harness can follow. A target of `../../skills/_data/concision.md`, in a rulebook from the source named `codeassembly-guidance`, resolves from `sync --global` on Claude to `~/.claude/skills/_sources/codeassembly-guidance/_data/concision.md` and on Rovo to `~/.rovo/skills/_sources/codeassembly-guidance/_data/concision.md`. Which root the path takes depends on the tree into which the target is deployed, which is the deploying domain in both cases: One naming a skill delivered by the same run is anchored where that run wrote it, so `../../skills/consult-<slug>/SKILL.md` resolves on Claude under the project root from bare `sync`, and to `~/.claude/skills/consult-<slug>/SKILL.md` from `sync --global`. Every other target resolves into the owning source's support namespace, `skills/_sources/<name>/`, under the project root from bare `sync` and under the harness home from `sync --global`. `{harness_home_dir}` and `{harness_id}` expand per harness, including where one opens a link target.
|
|
66
|
+
|
|
67
|
+
A rulebook may link only into `skills/` and `scripts/`, the two trees whose source layout matches where they deploy under every harness home. Any other target fails the run, with an error naming the rulebook, the target as authored, and why it was rejected. `subagents/` is rejected because a subagent is dispatched rather than read, so a link into one is not worth authoring. `_partials/` and `collections/` never deploy as files. A link into one would name nothing.
|
|
68
|
+
|
|
69
|
+
A rulebook inlines partials, which is how it receives shared doctrine, and that puts a constraint on a partial written for two kinds of host: A relative Markdown link cannot serve both a skill host and a rulebook host. A skill's links resolve against `<slug>/SKILL.md` in skills-dir space and a rulebook's against `guidance/rulebooks/<slug>.md` in content-root space. One authored target names two different files. A skill-shaped target resolves outside a linkable root from a rulebook host and fails the run rather than deploying as a broken link, but a partial meant for both hosts does not contain any relative link at all.
|
|
70
|
+
|
|
71
|
+
A link to a sibling rulebook is rejected too, and its error names the `{rulebook:<slug>}` token that addresses it instead. A rulebook is invoked rather than read: The skill that it deploys is discovered by name, so an invocation resolves wherever it was deployed, while a path would be right in one domain and broken in the other. _(Validated on parse.)_
|
|
72
|
+
|
|
73
|
+
A target that is rooted correctly but names a file that has moved or been deleted is caught separately, by `validate`, which looks for the file in the content root, and resolves a fragment on such a target to exactly one heading in the file into which it points. _(Enforced by `validate`.)_
|
|
74
|
+
|
|
75
|
+
One limitation is worth knowing before writing a rulebook that documents linking: Rewriting runs over the whole body, so a Markdown link inside a code fence or an inline code span is rewritten along with the rest. A rulebook cannot show a relative link verbatim as an example, and must describe the target instead. Because invocation tokens are rewritten the same way, an example token keeps the `<slug>` placeholder rather than naming a real artifact.
|
|
76
|
+
|
|
77
|
+
## Anchor links
|
|
78
|
+
|
|
79
|
+
An anchor-only link addresses the body in which it appears. Its fragment must name exactly one heading there. Naming none fails the run, and so does naming two: A locator that resolves by accident is not a locator. The rule covers every rulebook, skill, and subagent, and the guidance files that `install` deploys. _(Validated on parse.)_
|
|
80
|
+
|
|
81
|
+
In every artifact whose includes the pipeline expands -- i.e., rulebooks, skills, subagents, and harness guidance -- the body checked is the expanded one, so an anchor authored in a `_partials/` file resolves against each artifact that inlines it, and the error names that artifact rather than the partial. A shared guidance file does not have a check of its own: The pipeline reads it only through the harness guidance that inlines it, and checks an anchor that it contains against that expanded body.
|
|
82
|
+
|
|
83
|
+
Frontmatter, fenced code blocks (backtick or tilde), and inline code spans are exempt on both sides: A heading inside one does not provide an anchor, and a link inside one does not need an anchor. A code span _within_ a heading is the opposite case: Because it is part of that heading's text, the heading still provides an anchor, with the backticks dropped as punctuation -- ``### The `respond-to-review` path`` resolves to `#the-respond-to-review-path`. An indented code block is not exempt, because telling one from a nested list item would take block-level parsing. Show an example anchor in a fence or a code span. An anchor-only target is never rewritten, so unlike a relative one it survives either intact.
|
|
84
|
+
|
|
85
|
+
A fence that nothing closes fails the run in its own right. Everything below it reads as code. The pipeline cannot check any anchor there, and a silent pass over an unchecked remainder is worse than a rejection. A closing fence repeats the opening character at least as many times, which is the rule on which a four-backtick example wrapping a three-backtick one depends. _(Validated on parse.)_
|
|
86
|
+
|
|
87
|
+
A heading containing a token cannot be anchored: It renders to a different slug on each harness, so a single fragment cannot address it on every harness. Give such a heading a token-free title if a link must address it. _(Validated on parse.)_
|
|
88
|
+
|
|
89
|
+
## Collections
|
|
90
|
+
|
|
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.
|
|
95
|
+
|
|
96
|
+
```yaml
|
|
97
|
+
members:
|
|
98
|
+
skills:
|
|
99
|
+
- capture-feedback
|
|
100
|
+
subagents:
|
|
101
|
+
- canary
|
|
102
|
+
```
|
|
103
|
+
|
|
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.
|
|
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
|
+
|
|
124
|
+
## Frontmatter fields
|
|
125
|
+
|
|
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.
|
|
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.
|
|
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).
|
|
131
|
+
|
|
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.)_
|
|
133
|
+
|
|
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.)_
|
|
135
|
+
|
|
136
|
+
### Version bumps
|
|
137
|
+
|
|
138
|
+
A rulebook's `version` tracks the operative content of its deployed body: Bump it whenever an edit changes what the rulebook asks of an agent, and leave it when the edit was cosmetic. The field exists to prevent two different bodies from reporting one version. `revise-prose` does not key a repository's sweep coverage on it: Coverage follows each rule's sweep version, as "Declaring rule ids and sweep versions" below states.
|
|
139
|
+
|
|
140
|
+
The deployed body is the body after includes expand. Editing a partial is therefore a content change for every rulebook that includes it, and the version changes although the rulebook's own file is untouched. A file that the body links to rather than inlines, such as a `_data/` reference, is outside the body and does not require a bump. _(Convention; not enforced.)_
|
|
141
|
+
|
|
142
|
+
A `revise-prose` repair does not change what a rulebook asks, because the sweep's calibration rules out any rewrite that would change what the text directs. Keep the rulebook's `version` and each rule's sweep version, and re-pin only the hashes that changed: Once a rule's sweep version rises, `revise-prose` no longer counts that rule's coverage, including the coverage that the same sweep recorded. _(Convention; not enforced.)_
|
|
143
|
+
|
|
144
|
+
## Naming
|
|
145
|
+
|
|
146
|
+
A `delivery: skill` rulebook deploys as `consult-<slug>`.
|
|
147
|
+
|
|
148
|
+
A rulebook slug's final segment names the kind of document rather than its subject. This library uses `-conventions`, `-policy`, `-preferences`, and `-specification`; other content roots add `-guidance`, `-guide`, `-references`, and `-settings`. The set is open, and `-rulebook` is the fallback when the document does not fit any kind noun. _(Convention; not enforced.)_
|
|
149
|
+
|
|
150
|
+
Skill names are verb-led. Order list members and frontmatter lists alphabetically unless there is a reason to group otherwise. _(Conventions; not enforced.)_
|
|
151
|
+
|
|
152
|
+
## Adding guidance
|
|
153
|
+
|
|
154
|
+
Correct a behavior at the fewest surfaces that plausibly account for it, deploy that change, and observe. Extend to further surfaces only after the minimal change has been seen to fail. Changing every contributing surface at once means that the improvement cannot be credited to any single edit, so the cheapest sufficient fix is never learned, and each surface touched permanently adds tokens to every later invocation.
|
|
155
|
+
|
|
156
|
+
A proposal justifies its breadth rather than assuming it. A contributing surface left unaddressed is recorded as an observation for a later pass rather than offered as an option to adopt now. Before adding exposition to a rulebook, check whether its existing examples already teach the point. _(Convention; not enforced.)_
|
|
157
|
+
|
|
158
|
+
Before making any change to a guidance file, identify whether the new text makes any existing text redundant (whether in that file or any other) and trim the redundancy in the same change. If the file is larger after the change than before, offer to run {skill:streamline-guidance} against it. _(Convention; not enforced.)_
|
|
159
|
+
|
|
160
|
+
## Procedures in helpers
|
|
161
|
+
|
|
162
|
+
A step whose result is fixed by its inputs belongs in a helper that emits JSON, and the skill or subagent invokes the helper and reads its output. Such steps include parsing a file or a command's output, walking a fallback cascade, matching by pattern or timestamp, and converting a format. A prose description of such a step is a copy that the agent re-executes on every run, and it drifts from any helper that performs the same step. Judgment stays in prose: choosing among options, composing text, and deciding what a result means.
|
|
163
|
+
|
|
164
|
+
A step that mixes the two splits at that boundary: The helper performs the deterministic part and returns its result, or the candidates among which the agent chooses, and the choice stays in the skill.
|
|
165
|
+
|
|
166
|
+
When authoring or editing a skill or subagent, move such a procedure in the text being changed into a helper as part of the same change. First check whether an existing helper already performs it, and extend that helper rather than writing a second one. A procedure found outside the text being changed follows the [scope doctrine](../../skills/_data/scope-and-deferral.md) rather than prompting a sweep of the library. A content root declares its helpers under `helpers:` in its `codeassembly-content.yaml`. _(Convention; not enforced.)_
|
|
167
|
+
|
|
168
|
+
## Declaring rule ids and sweep versions
|
|
169
|
+
|
|
170
|
+
A rulebook written for the `comment-preferences` or `writing-preferences` hook is a unit of the `revise-prose` sweep, and it declares an id and a sweep version for each rule that it states. The declaration is a `<!-- rule: <id> <version> -->` marker on the first non-blank line under the rule's `##` heading; a rule stated in an included partial has its marker in the partial. The sweep records coverage and rejections under the id, and `prose-reviser` reports each site under it; therefore, an id stays as written when its heading changes. Take a new rule's id from the kebab-case form of its heading.
|
|
171
|
+
|
|
172
|
+
The marker declares the rule whether or not a detector covers it: The helper's registry alone decides which rules it detects. A rulebook that declares one id declares one under every `##` heading, and each id is declared only once across the content root. _(Convention; not enforced.)_
|
|
173
|
+
|
|
174
|
+
A sweep version is a positive integer, and a new rule starts at `1`. Raise it when some text that complied with the rule's old wording could fail the new one, including through an edit outside every rule section, such as to a rulebook's introduction, and raise it when unsure. Leave it for a relaxation, a clarification, or a rewording. The `plain-speech` unit's `unit-version` follows the same test. A raised sweep version re-opens that rule's coverage and rejections in every repository's record, and a rulebook `version` change re-opens none. Because a rule that becomes stricter changes what its rulebook asks, the rulebook's `version` rises with every sweep-version rise. _(Convention; not enforced.)_
|
|
175
|
+
|
|
176
|
+
## Guidance hooks
|
|
177
|
+
|
|
178
|
+
When a step's guidance is a matter of local taste rather than library doctrine -- such as a user's code-style preferences, or a project's own glossary -- neither a pointer to a stated rule nor an inlined partial fits: A pointer sends the agent away to fetch the rule, and an inlined partial fixes one answer for every consumer at authoring time. Declare a guidance hook instead, `<!-- guidance-hook: <name> -->`, and leave the slot for a `codeassembly.yaml` to bind per project or per machine. An unbound hook contributes nothing to deployed output, so declaring one is safe wherever nothing fills it. A rulebook written for that slot declares `delivery: hook`, which records the route and lets `sync` report a binding and a delivery that disagree. The directive grammar is specified in `content/_partials/README.md` and the binding syntax in `packages/agents/docs/project-declaration.md`. _(Convention; not enforced.)_
|
|
179
|
+
|
|
180
|
+
## Injection-point placement
|
|
181
|
+
|
|
182
|
+
Injected content contributes its own headings: a partial's as authored, and a guidance-hook fill's demoted one level, so a bound rulebook's title appears at `##`. If a host heading follows a directive and is deeper than the injected content's shallowest heading, it renders as a subsection of the injection rather than of the host. For a hook, it renders under whichever rulebook the local binding supplied, which makes one body read differently on two machines.
|
|
183
|
+
|
|
184
|
+
Place every directive where the next host heading is at or above that level. If a section would otherwise nest, promote it or move the directive below it. The level that decides is what the injection contributes, not a fixed `##`: A partial that opens at `###` and does not declare a hook legitimately takes `###` siblings after it. _(Enforced by `validate`.)_
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: command-output-conventions
|
|
3
|
+
description: What an agent prints from a command's output, which is the fact that the step needs, decided before the command runs.
|
|
4
|
+
delivery: ambient
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Command output conventions
|
|
9
|
+
|
|
10
|
+
Output that a command prints into the conversation stays in the context window for the rest of the session. Before running a command whose output is large or repeats across iterations, name the fact that the step needs from it, and print only that fact.
|
|
11
|
+
|
|
12
|
+
- Filter, count, or diff inside the command, rather than printing everything and reading it.
|
|
13
|
+
- When an evaluation repeats across iterations, such as scoring each reply against an answer key, write a small scorer once and print one line per case: the verdict, what is missing, and what is extra.
|
|
14
|
+
- Open detail only for a failing case, and only the part that explains the failure.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commit-conventions
|
|
3
|
+
description: Commit title and body conventions, the work-type taxonomy, and branch naming. Consult before writing a commit message or naming a branch.
|
|
4
|
+
delivery: skill
|
|
5
|
+
version: '10'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Git commit conventions
|
|
9
|
+
|
|
10
|
+
A commit on the default branch is extracted into the changelog and, for release-notes-contributing work types, into release notes. Under a squash merge that is the merge commit alone, whose body `merge-pr` composes from the pull request's `## What`; the branch commits collapsed by a squash do not appear in any changelog or release notes. A branch commit is input to `summarize-change`'s entry drafter instead, which reads the branch's commit log alongside the diff to answer what changed. Write with that reader in mind.
|
|
11
|
+
|
|
12
|
+
## Commit metadata
|
|
13
|
+
|
|
14
|
+
- `WORK_TYPE` describes the category of work (see [`work-types.json`](../../skills/_data/work-types.json)).
|
|
15
|
+
|
|
16
|
+
## Commit title
|
|
17
|
+
|
|
18
|
+
Voice, length, content discipline, and the ticket-reference rule are stated in [`title-voice.md`](../../skills/_data/title-voice.md), which governs the authored string across every surface into which it is rendered. Two rules are commit-specific:
|
|
19
|
+
|
|
20
|
+
- Render via `describe-change.mjs`; see [`title-templates.md`](../../skills/_data/title-templates.md) for the full template syntax, supported tokens, and rendering pipeline.
|
|
21
|
+
- Mark breaking changes by appending `!` to the work type: `agents|feat!: Remove deprecated API`. See [Breaking changes](#breaking-changes) below for which types are eligible.
|
|
22
|
+
|
|
23
|
+
## Ticket ID
|
|
24
|
+
|
|
25
|
+
The branch name records the ticket. Include the ID at the end of the commit body only if the branch covers more than one ticket (rare).
|
|
26
|
+
|
|
27
|
+
## Commit body
|
|
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 show.
|
|
30
|
+
|
|
31
|
+
### Body mechanics
|
|
32
|
+
|
|
33
|
+
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
34
|
+
|
|
35
|
+
- **Punctuate list items.** Each bulleted item ends with a period, comma, or semicolon.
|
|
36
|
+
- **Use backticks for code identifiers.** Variable names, function names, class names, and file paths must be wrapped in backticks (e.g., `handleStateUpdate`, `AgentActor`, `src/lib/manifest.ts`).
|
|
37
|
+
- **Break up large paragraphs.** Use a blank line between paragraphs. Prefer short, focused paragraphs over walls of text.
|
|
38
|
+
|
|
39
|
+
## Changes touching multiple scopes
|
|
40
|
+
|
|
41
|
+
For the structural scope values (`root`, `*`, workspace name), see "Scope values" in [`title-templates.md`](../../skills/_data/title-templates.md).
|
|
42
|
+
|
|
43
|
+
Commit-side application: When more than one scope-value would technically apply, use the closest fit. If a root change is tightly associated with only one workspace, count it as a workspace change rather than a root change. Common example: If a package is added to `packages/workspace-a`, that updates the package lock file in root; still treat the commit as a workspace change.
|
|
44
|
+
|
|
45
|
+
## Branch naming
|
|
46
|
+
|
|
47
|
+
Branch names follow `{ticket}/{description}`. `_` is interchangeable with `/` as a separator. See [`branch-format.md`](../../skills/_data/branch-format.md) for the full specification.
|
|
48
|
+
|
|
49
|
+
## Work types reference
|
|
50
|
+
|
|
51
|
+
See [`work-types.json`](../../skills/_data/work-types.json) for the canonical taxonomy. Each type belongs to one of three tiers:
|
|
52
|
+
|
|
53
|
+
- **Public**: Consumer-facing.
|
|
54
|
+
- **Internal**: Not consumer-facing.
|
|
55
|
+
- **Process**: Tooling and supporting work.
|
|
56
|
+
|
|
57
|
+
<!-- include: ../../_partials/work-type-choice.md / -->
|
|
58
|
+
|
|
59
|
+
### Precedence
|
|
60
|
+
|
|
61
|
+
This section governs every work-type resolution: one commit, a multi-commit pull request, and a merge commit alike.
|
|
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 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
|
+
|
|
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
|
+
|
|
67
|
+
### Breaking changes
|
|
68
|
+
|
|
69
|
+
Whether a commit can take a breaking-change marker (`!`, e.g., `feat!`, `drop!`) is set per-type by the `breakingPolicy` field in `work-types.json`:
|
|
70
|
+
|
|
71
|
+
- **`optional`**: `feat`, `drop`, `fix`, `sec`, `perf`. Any of these can break consumers, and the marker records when one does. A removal breaks consumers only when the removed surface was published, a fix can break consumers who relied on the defective behavior, and a performance change can break a contract to achieve its gain.
|
|
72
|
+
- **`forbidden`**: `deprecate` and every internal- and process-tier type. Deprecating a surface keeps it working, and removing it is a `drop`. Internal- and process-tier work does not face consumers; a change that breaks consumers faces them and therefore takes a public-tier type.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: generated-content-policy
|
|
3
|
+
description: What an agent needs to recognize about CodeAssembly to work safely alongside the content that it deploys.
|
|
4
|
+
delivery: ambient
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Generated content policy
|
|
9
|
+
|
|
10
|
+
A `<!-- codeassembly-` marker signifies generated content, as does any file in your harness's `skills/` or `scripts/` directory. Consult [deployed-file provenance](../../skills/_data/deployed-file-provenance.md) before editing either.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: live-worktree-policy
|
|
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
|
|
5
|
+
delivery: ambient
|
|
6
|
+
version: '3'
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Live worktree policy
|
|
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.
|
|
12
|
+
|
|
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.
|
|
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.
|
|
16
|
+
|
|
17
|
+
Advancing `live` deploys to the machine, which makes it the developer's action. Never advance or reset that branch.
|
|
18
|
+
|
|
19
|
+
Author in a branch worktree, never through `.live`. A write there changes the deployed tree rather than the branch under review. Reading from `.live` is fine, and is often how the deployed state is inspected.
|