codeassembly-guidance 0.0.0 → 0.1.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 +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- 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 +66 -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 +5 -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 +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -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 +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -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 +18 -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 +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -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 +43 -0
- package/content/scripts/README.md +41 -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 +209 -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/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -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/recommendation-gradient.md +90 -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 +147 -0
- package/content/skills/_data/title-templates.md +624 -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/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 +84 -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/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 +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -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 +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -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 +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -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 +136 -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 +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -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 +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -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 +115 -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 +69 -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 +308 -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 +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -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 +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -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 +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: recommended
|
|
3
|
+
description: The vetted, generally applicable set (artifacts any project can declare).
|
|
4
|
+
members:
|
|
5
|
+
rulebooks:
|
|
6
|
+
- accessibility-conventions
|
|
7
|
+
- command-output-conventions
|
|
8
|
+
- generated-content-policy
|
|
9
|
+
- readme-conventions
|
|
10
|
+
- shared-data-conventions
|
|
11
|
+
skills:
|
|
12
|
+
- capture-event
|
|
13
|
+
- capture-feedback
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Recommended
|
|
17
|
+
|
|
18
|
+
The public collection. Membership claims that an artifact was examined and found generally applicable: It names nothing specific to one author's environment, does not state any personal doctrine, declares its prerequisites where a reader looks before invoking, and deploys only where it works.
|
|
19
|
+
|
|
20
|
+
Membership is per-artifact and enumerated in full rather than by dependency root, so the closure check notices every member that an artifact's dependency edges would add.
|
|
21
|
+
|
|
22
|
+
The skills belong here on different grounds. A rulebook of the personal collection names `capture-feedback` in a body token, and `capture-feedback` names `capture-event` in another. Because a collection cannot be closed over an artifact of lesser standing, both were promoted. `capture-event`'s promotion was forced by that chain rather than chosen on its own merits. It is the one member to re-examine first. `capture-feedback` qualifies on its own terms: It does not name any store, declares the registry needed by a capture, and sends a record to the store that the registry's `feedback_kb` names.
|
|
23
|
+
|
|
24
|
+
`generated-content-policy` qualifies on its own terms too: What it states is a mechanism that every consumer meets, not a preference, and the guidance that a reader needs beyond the trigger is in the linked reference rather than in the ambient body loaded by every session.
|
|
25
|
+
|
|
26
|
+
`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
|
+
|
|
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.
|
|
29
|
+
|
|
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.
|
|
31
|
+
|
|
32
|
+
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
|
+
|
|
34
|
+
`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.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: triage
|
|
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
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
# Triage
|
|
72
|
+
|
|
73
|
+
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
|
+
|
|
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.
|
|
76
|
+
|
|
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.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: williamthorsen
|
|
3
|
+
description: The vetted personal set (artifacts that deliberately encode William Thorsen's preferences, environment, and domain).
|
|
4
|
+
members:
|
|
5
|
+
rulebooks:
|
|
6
|
+
- williamthorsen-code-layout-preferences
|
|
7
|
+
- williamthorsen-collaboration-preferences
|
|
8
|
+
- williamthorsen-comment-preferences
|
|
9
|
+
- williamthorsen-subagent-model-preferences
|
|
10
|
+
- williamthorsen-ticketing-preferences
|
|
11
|
+
- williamthorsen-tooling-preferences
|
|
12
|
+
- williamthorsen-typescript-preferences
|
|
13
|
+
- williamthorsen-workflow-preferences
|
|
14
|
+
- williamthorsen-writing-preferences
|
|
15
|
+
skills:
|
|
16
|
+
- people-report
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
# William Thorsen
|
|
20
|
+
|
|
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
|
+
|
|
23
|
+
Its closure contains `capture-feedback` and `capture-event` in `recommended` and nothing else, which makes declaring it safe alongside the public collection.
|
|
24
|
+
|
|
25
|
+
Every member is invoked often enough to justify its standing line in the skill index. An artifact that is deliberate but rarely wanted belongs outside every collection, declared directly where it is needed.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Agent guidance content
|
|
2
|
+
|
|
3
|
+
This directory contains the source-of-truth guidance content that `codeassembly install` renders into platform-specific files (`~/.claude/CLAUDE.md`, `~/.rovo/AGENTS.md`).
|
|
4
|
+
|
|
5
|
+
This README is for maintainers of this directory. It is not referenced by any `<!-- include: -->` directive and is not part of the rendered output.
|
|
6
|
+
|
|
7
|
+
## `shared/AGENTS.md`
|
|
8
|
+
|
|
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
|
+
|
|
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.
|
|
12
|
+
|
|
13
|
+
## Ambient delivery: Harness regions
|
|
14
|
+
|
|
15
|
+
A rulebook with `delivery: ambient` is delivered by `sync` into the ambient region (`<!-- codeassembly-ambient:start -->` / `<!-- codeassembly-ambient:end -->`) of a per-harness guidance file, wrapped in `<!-- rulebook:<slug> -->` sentinels, with `<!-- rulebook-version: <version> -->` directly below the open sentinel if the rulebook declares a version. The region opens with a comment naming its content generated and warning that edits inside the region are overwritten; the comment is part of the rendered body, so a region without ambient content does not have one. Both domains work this way, and both are mechanical end to end: Every host is a file loaded by its harness at launch, without any agent-elective read anywhere on the path. They differ in which file, and in who creates the region.
|
|
16
|
+
|
|
17
|
+
- **Home / all-projects scope** (`sync --global`): The host is each targeted harness's guidance file under its home directory (`~/.claude/CLAUDE.md`, and the equivalent under each other harness's home). The templates in `_harnesses/` contain the empty region, so the region's location is `install`'s decision while its content is `sync`'s: `sync --global` regenerates the region wholesale each run, and `install` splices the region's content into every re-render and excludes it from drift hashing (`ambient-region.ts`). Hand edits outside the region still count as drift. Run `install` before the first `sync --global`; a guidance file that is missing or does not have a region is skipped with a warning naming the fix.
|
|
18
|
+
- **Project scope** (`sync`): The host is each targeted harness's machine-local project guidance file at the project root (`CLAUDE.local.md`, `AGENTS.local.md`). `install` does not manage user-local files, so `sync` owns region creation here: An absent host is created with the region, and a host that already exists keeps everything it contains and gains the region below it. A host is materialized only when the scope declares an ambient rulebook. A project that declares none is left without a file. A host with a half-written region fails the run rather than being appended to, since appending beside a stray marker would delete the text between them on the following sync. Because the host is gitignored, it exists only in the worktree in which it was created. A multi-worktree checkout needs a sync per worktree; `sync` warns when a host that it writes is not git-ignored.
|
|
19
|
+
|
|
20
|
+
**Destination tiers.** Harness-neutral and per-harness destinations are not interchangeable. A project's root `AGENTS.md` is the one neutral destination: One body of text serves every harness, so it cannot contain a harness-scoped path, and content that needs one belongs in an ambient rulebook instead. Every generated destination has a known target harness: skills, subagents, and both ambient tiers. The root `AGENTS.md` does not receive any generated content at all. It is hand-authored, and `sync` strips the rulebook blocks that a previous version left there or in the `.agents/PROJECT.md` that it superseded.
|
|
21
|
+
|
|
22
|
+
Two files under `~/.agents/` are retired. `GLOBAL.md` was the home ambient host: `sync --global` strips the sync-owned blocks from a legacy copy and deletes the file once nothing hand-written remains. `AGENTS.md` was a verbatim copy of `shared/AGENTS.md`: `install` and `uninstall` each remove a copy deployed by the CLI, keep one containing hand-written content, and leave alone a copy that it never deployed. For machine-local guidance that should stay out of source control, declare a machine-local source in `~/.agents/codeassembly.yaml` (a directory shaped like the library's `content/`, with rulebooks at `guidance/rulebooks/<slug>.md`) and give the rulebook `delivery: ambient`; it then uses the same injection as library rulebooks.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
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'
|
|
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 shipped 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 sits 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.
|
|
@@ -0,0 +1,161 @@
|
|
|
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
|
+
delivery: skill
|
|
5
|
+
version: '29'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# CodeAssembly content specification
|
|
9
|
+
|
|
10
|
+
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.)
|
|
11
|
+
|
|
12
|
+
## Enforcement
|
|
13
|
+
|
|
14
|
+
Every rule below belongs to one of three classes, marked where it appears.
|
|
15
|
+
|
|
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
|
+
|
|
18
|
+
**Enforced by `validate`.** `codeassembly validate` checks a content root against these rules without deploying it. Such a rule names `validate`.
|
|
19
|
+
|
|
20
|
+
**Convention.** The rest is marked _(Convention; not enforced.)_ Nothing checks it.
|
|
21
|
+
|
|
22
|
+
## Declaring dependencies
|
|
23
|
+
|
|
24
|
+
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:
|
|
25
|
+
|
|
26
|
+
```yaml
|
|
27
|
+
dependencies:
|
|
28
|
+
rulebooks:
|
|
29
|
+
- shell-conventions
|
|
30
|
+
skills:
|
|
31
|
+
- capture-event
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`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.)_
|
|
35
|
+
|
|
36
|
+
## Invocation tokens
|
|
37
|
+
|
|
38
|
+
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:
|
|
39
|
+
|
|
40
|
+
- `{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.
|
|
41
|
+
- `{skill:<slug>}` renders to the harness skill sigil plus the slug -- `/<slug>` on Claude, `!<slug>` on Rovo.
|
|
42
|
+
- `{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.
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
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
|
+
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
|
+
|
|
50
|
+
`{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
|
+
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
|
+
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
|
+
|
|
56
|
+
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
|
+
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.)_
|
|
59
|
+
|
|
60
|
+
Reserve a `dependencies:` entry for a non-inline edge; use a token for any invocation that appears in the body. _(Convention; not enforced.)_
|
|
61
|
+
|
|
62
|
+
## Links in rulebook bodies
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
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.)_
|
|
71
|
+
|
|
72
|
+
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`.)_
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
## Anchor links
|
|
77
|
+
|
|
78
|
+
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.)_
|
|
79
|
+
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
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.
|
|
83
|
+
|
|
84
|
+
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.)_
|
|
85
|
+
|
|
86
|
+
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.)_
|
|
87
|
+
|
|
88
|
+
## Collections
|
|
89
|
+
|
|
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
|
+
|
|
92
|
+
```yaml
|
|
93
|
+
members:
|
|
94
|
+
skills:
|
|
95
|
+
- capture-feedback
|
|
96
|
+
subagents:
|
|
97
|
+
- canary
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`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
|
+
|
|
102
|
+
## Frontmatter fields
|
|
103
|
+
|
|
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.
|
|
106
|
+
- **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.
|
|
108
|
+
|
|
109
|
+
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
|
+
|
|
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.)_
|
|
112
|
+
|
|
113
|
+
### Version bumps
|
|
114
|
+
|
|
115
|
+
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.
|
|
116
|
+
|
|
117
|
+
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.)_
|
|
118
|
+
|
|
119
|
+
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.)_
|
|
120
|
+
|
|
121
|
+
## Naming
|
|
122
|
+
|
|
123
|
+
A `delivery: skill` rulebook deploys as `consult-<slug>`.
|
|
124
|
+
|
|
125
|
+
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.)_
|
|
126
|
+
|
|
127
|
+
Skill names are verb-led. Order list members and frontmatter lists alphabetically unless there is a reason to group otherwise. _(Conventions; not enforced.)_
|
|
128
|
+
|
|
129
|
+
## Adding guidance
|
|
130
|
+
|
|
131
|
+
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.
|
|
132
|
+
|
|
133
|
+
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.)_
|
|
134
|
+
|
|
135
|
+
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.)_
|
|
136
|
+
|
|
137
|
+
## Procedures in helpers
|
|
138
|
+
|
|
139
|
+
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.
|
|
140
|
+
|
|
141
|
+
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.
|
|
142
|
+
|
|
143
|
+
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.)_
|
|
144
|
+
|
|
145
|
+
## Declaring rule ids and sweep versions
|
|
146
|
+
|
|
147
|
+
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.
|
|
148
|
+
|
|
149
|
+
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.)_
|
|
150
|
+
|
|
151
|
+
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.)_
|
|
152
|
+
|
|
153
|
+
## Guidance hooks
|
|
154
|
+
|
|
155
|
+
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.)_
|
|
156
|
+
|
|
157
|
+
## Injection-point placement
|
|
158
|
+
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
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 carry.
|
|
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 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.
|
|
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,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: live-worktree-policy
|
|
3
|
+
description: How a repository with a `live` worktree deploys, and where changes to it are authored.
|
|
4
|
+
delivery: ambient
|
|
5
|
+
version: '2'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Live worktree policy
|
|
9
|
+
|
|
10
|
+
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
|
+
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
|
+
|
|
14
|
+
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
|
+
Advancing `live` deploys to the machine, which makes it the developer's action. Never advance or reset that branch.
|
|
17
|
+
|
|
18
|
+
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.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: readme-conventions
|
|
3
|
+
description: What belongs in a README, how its shape follows from what it describes, and where detail goes when it leaves. Consult before writing, revising, or tightening a README, or before adding a section to one.
|
|
4
|
+
delivery: skill
|
|
5
|
+
version: '2'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# README conventions
|
|
9
|
+
|
|
10
|
+
A README answers two questions for a reader who arrived a moment ago: whether this is the right thing, and how to begin using it. The reader decides in about thirty seconds. A README keeps what serves that decision and the first successful use; the rest is reference, and reference belongs elsewhere.
|
|
11
|
+
|
|
12
|
+
## Audience
|
|
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.
|
|
15
|
+
|
|
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
|
+
|
|
18
|
+
When agents are the only likely readers, the README states what the thing is and where its entry points are, and stops. A stub is the correct shape there, not a gap to fill.
|
|
19
|
+
|
|
20
|
+
## Types
|
|
21
|
+
|
|
22
|
+
What the README describes decides its shape. Find the row; the rest of this rulebook is the general case that each row narrows.
|
|
23
|
+
|
|
24
|
+
| Type | Leads with | Keeps | Omits |
|
|
25
|
+
| --------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------- |
|
|
26
|
+
| Application or service (`application`) | What it does for the person running it | Screenshots, how to run it, how to configure a first run | Internal architecture, exhaustive configuration |
|
|
27
|
+
| CLI tool (`cli`) | The install command, then the single most common invocation | Copy-pasteable examples of the two or three real tasks | A command inventory, which `--help` already prints |
|
|
28
|
+
| Library or package (`library`) | The import line and a minimal use in about three lines | What problem it solves, and how it compares to known alternatives | A full API listing, once it outgrows the first screen |
|
|
29
|
+
| Configuration or preset package (`config`) | How to consume, extend, override, and compose it | Per-option detail, which is the subject here rather than an excess | Narrative about the tools that it configures |
|
|
30
|
+
| Monorepo root (`monorepo-root`) | What the repository is, and a map of its packages | One bootstrap command, and where each package's README is | Anything a package's own README states |
|
|
31
|
+
| Content or data repository (`content`) | What the content is, and the shape that it takes | The authoring contract: how to add an entry, and what checks it | Detail belonging to whatever consumes the content |
|
|
32
|
+
| Internal or agent-facing package (`internal`) | What the thing is, and its entry points | A pointer to the guidance that governs work on it | Everything else |
|
|
33
|
+
|
|
34
|
+
Screenshots belong in the application row and almost nowhere else. A library does not have an interface to show, and a terminal recording of a CLI demonstrates one path, whereas the text already shows three.
|
|
35
|
+
|
|
36
|
+
## Recording the type
|
|
37
|
+
|
|
38
|
+
A README records its row on its first line, as `<!-- readme-type: <slug> -->` with the slug from the Type column, so that the choice of row happens once rather than at every revision. Writing a README adds the marker. Revising one follows it; if the marker is missing or does not name a row, choose the row that fits and add the marker.
|
|
39
|
+
|
|
40
|
+
The marker records a decision rather than a fact. When it no longer fits what the README describes, such as an internal package that is now published, say so before editing rather than following it.
|
|
41
|
+
|
|
42
|
+
## The first screen
|
|
43
|
+
|
|
44
|
+
The opening makes up to three moves, in order. The first applies to every type; the second and third apply to every type that a reader installs, imports, or runs.
|
|
45
|
+
|
|
46
|
+
1. **One sentence of identity.** What this is and who it serves. "A lightweight CLI that converts Markdown to PDF" tells a reader more than a paragraph of welcome.
|
|
47
|
+
2. **How to get it running.** The install command, the import line, or the bootstrap command, whichever the type calls for.
|
|
48
|
+
3. **The smallest thing that works.** One example, short enough to read without scrolling, that a reader can run unchanged.
|
|
49
|
+
|
|
50
|
+
A README that reaches its second heading before making the moves that apply to it has buried its answer.
|
|
51
|
+
|
|
52
|
+
## Moving detail out of the README
|
|
53
|
+
|
|
54
|
+
The test is who a section is written for, not how long the README has grown. A section addressed to a reader who has already decided to use the thing, and who has come back with a specific question, belongs in the `docs/` directory of the tier that owns it: the repository's for a root README, the package's own for a package README.
|
|
55
|
+
|
|
56
|
+
Detail about one symbol's behavior, such as its edge cases, its failure modes, and the reason for a rule that it enforces, belongs in that symbol's doc comment, where a caller reads it while using the symbol. A README paragraph that would make a good doc comment is a doc comment in the wrong file.
|
|
57
|
+
|
|
58
|
+
Length is a symptom worth examining, with one hard limit: The npm registry truncates a published package's README at 65,536 characters, silently and mid-sentence, and `wc -m README.md` measures it. Within that limit, a configuration package whose README runs long because per-option detail is its subject is correct as it stands; an application README of the same length usually contains a reference manual.
|
|
59
|
+
|
|
60
|
+
Move the section, and leave a link where a reader looking for it would have found it. A pointer takes one line, and a reader who concludes that the answer does not exist loses more than that.
|
|
61
|
+
|
|
62
|
+
## What never belongs
|
|
63
|
+
|
|
64
|
+
- Anything the tool prints about itself. A command table restates `--help` and goes stale the moment a flag changes.
|
|
65
|
+
- Release history, which is the changelog's subject.
|
|
66
|
+
- Badge walls and marketing copy. A badge that a reader acts on justifies its line; the rest is decoration.
|
|
67
|
+
- Content copied from another file. Two copies of one fact drift apart, and the copy that nobody owns is the one that goes wrong.
|
|
68
|
+
- A claim that has gone stale. A revision checks each claim that it keeps against what the README describes.
|
|
69
|
+
|
|
70
|
+
These share a failure mode: Each stays wrong without a test failing or a reader complaining.
|
|
71
|
+
|
|
72
|
+
## Adding a type
|
|
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.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: shared-data-conventions
|
|
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]
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Shared data conventions
|
|
9
|
+
|
|
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
|
+
|
|
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.
|
|
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.
|