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
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## 0.1.0 — 2026-10-10
|
|
6
|
+
|
|
7
|
+
### 🎉 Features
|
|
8
|
+
|
|
9
|
+
- Moves the CodeAssembly library and its helpers from the `codeassembly` package into the new `codeassembly-guidance` package at `packages/guidance`, whose support files deploy under `_sources/codeassembly-guidance/`. (#1933)
|
|
10
|
+
- Adds the Claude-only `prepare-prototype-brief` skill, which composes and checks the shared brief for a round of competing prototypes, dispatches one builder per lens, and writes a comparison of the prototypes after `index-prototypes` builds the index page. (#1936)
|
|
11
|
+
- Adds the ambient rulebook `command-output-conventions` to the `recommended` collection, which directs an agent to print only the fact that a step needs from a large or repeated command's output, and, for a repeated evaluation, to print one line per case from a single scorer. (#1938)
|
|
12
|
+
- Adds a "Procedures in helpers" section to the `codeassembly-content-specification` rulebook, which directs an author who edits a skill or subagent to move a step whose result is fixed by its inputs into a helper that emits JSON, extending an existing helper when one already performs the step. (#1952)
|
|
13
|
+
- Makes `create-ticket` resolve a new ticket's labels by running `describe-change.mjs resolve-labels`, which now accepts a call without `--body-file` and labels the record from `--type`, `--scope`, and `--breaking` alone. (#1952)
|
|
14
|
+
- Adds the `manage-jira-ticket.mjs` helper, which `create-ticket` now runs to resolve the project key and issue type from the repository's `.agents/preferences.yaml`, check a parent reference, and run `acli jira workitem create` exactly once. (#1955)
|
|
15
|
+
- Directs the `acli` path of `update-jira-ticket` to convert a Markdown body to ADF with the helper's `convert-body` subcommand, which turns GFM task lists into Jira task items. (#1955)
|
|
16
|
+
- Adds the `describe-change render-details` subcommand, which renders a change summary's `## Details` body from an entries file, with its headings, subsection order, and breaking prefix taken from `work-types.json`. (#1957)
|
|
17
|
+
- Adds a launch prompt for each ticket that keeps work to the "Split the ticket" report of `design-and-plan`, `plan`, `refine-plan`, and `save-plan`, which starts the session at `design-and-plan`, `plan`, `refine-plan`, or `implement-plan`, depending on how much of the ticket's design and plan is already settled, and lists the ticket's plan path, scope notes, and blockers. (#1961)
|
|
18
|
+
- Adds a launch prompt for each piece to the "Split the branch" report of `implement-plan`, which starts the session at `review-branch` with the piece's diff base, names the piece's branch and worktree, and shows each later piece as blocked until its predecessor merges. (#1961)
|
|
19
|
+
- Adds the `--related-to <#>` option to the `groom-backlog` skill, which assesses the open tickets related to a closed ticket in place of the backlog: the tickets that mention it or its closing pull request, the tickets that it blocked, its parent and the parent's other open children, and the tickets that name a file touched by the closing pull request. (#1966)
|
|
20
|
+
- Adds the `pending-ripples` command to the `groom-backlog` helper, which lists the closed tickets that a ripple has not yet assessed, since a given date or else since the last pull or the last groom that was not a dry run. (#1966)
|
|
21
|
+
- Adds the `related` command to the `groom-backlog` helper, which returns a ripple's related set with its counts by tier without writing anything. (#1966)
|
|
22
|
+
- Directs the `ticket-assessor` subagent to examine a ripple's closed ticket and pull request first, and to recommend `close-complete` when the pull request met the ticket's motivation or when the ticket is a parent whose children are all closed. (#1966)
|
|
23
|
+
- Extends the `groom-backlog` issue fetch to request each ticket's parent, blockers, sub-issue counts, assignees, and milestone, which requires `gh` 2.100 or later. (#1966)
|
|
24
|
+
- Adds a final step to `merge-pr` that reads the open tickets related to the ticket that the merge commit closes and asks for consent before running `groom-backlog --related-to` on them, or records an empty ripple when the merged ticket does not have any related tickets. (#1967)
|
|
25
|
+
- Adds a "Ripple merged ticket #N" action to `wrap-up`, which it offers for a ticket closed by a PR merged in the session when `pending-ripples` reports that the ticket has not been rippled yet. (#1967)
|
|
26
|
+
- Adds the `pull-from-backlog` skill, which presents the current milestone's umbrellas, in-progress tickets, and blocked tickets with the backlog's warnings, offers the unblocked and unassigned tickets as a ranked menu with the reasons for each rank, and assigns the picked ticket to the user on consent. (#1969)
|
|
27
|
+
- Adds the `ticket.pull` project preferences, which set the milestone that `pull-from-backlog` treats as current, the prefix of the priority labels, the thresholds at which a branch or a groom counts as stale, and whether a pick assigns the user without asking. (#1969)
|
|
28
|
+
- Adds a "Product development" section to the `williamthorsen-workflow-preferences` rulebook, which states the stages from idea to increments, with a usable MVP before further features, and the shape to propose once the developer approves the end vision: an epic whose iterations are its sub-issues, with only the current one specified in detail. (#1973)
|
|
29
|
+
- States which artifact holds what: a design doc in the repo holds the vision, the epic points to it and lists the iterations in order, the milestone marks the current iteration, and each later iteration stays a one-line outcome until its work starts. (#1973)
|
|
30
|
+
- Names the winning prototype as the baseline for the finished product, the floor on quality and feel against which it is judged, with a feature reduced in one iteration recorded as a one-line sub-issue and a feature settled below that bar recorded in the design doc with its reason. (#1973)
|
|
31
|
+
- Makes `create-commit` take the paths to stage and a one-line purpose as arguments, compose the body from the diff alone when no purpose is passed, and report the new commit's short SHA and title or the reason that nothing was committed. (#1979)
|
|
32
|
+
- States in `codeassembly-content-specification` that the deploy writes every skill frontmatter key other than `supported-harnesses` 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. (#1979)
|
|
33
|
+
- Adds a step to `merge-pr` that offers to close the parent ticket when the merge closed its last open child, and lists any of the parent's own unchecked acceptance criteria beneath the question. (#1980)
|
|
34
|
+
- Names `clients/<library>/` in place of `integrations/` in the `williamthorsen-code-layout-preferences` rulebook as the directory for code that talks to a third-party service or library or maps to its data shapes, and directs code that uses a client to a directory named for its domain. (#1982)
|
|
35
|
+
- Changes `groom-backlog` to keep an in-progress ticket open without commenting on it or presenting it in a digest when its assessment is a `keep` whose verdicts are all baseline; previously, `groom-backlog` presented every in-progress ticket to the user for a decision. (#1983)
|
|
36
|
+
- Counts `partial` progress as baseline for an umbrella ticket, which is a ticket that has open children and whose only unchecked criterion is "Every child is closed", so that `groom-backlog` keeps such a ticket silently when its assessment is a `keep` and its other verdicts are baseline, and does not post a comment when the user decides to keep it. (#1983)
|
|
37
|
+
- Adds a `post` field to the result of the `groom-backlog` helper's `comment` command, which states whether the decision's comment is posted and leaves `--out` unwritten when it is `false`, replacing the skill's own check of the verdicts. (#1983)
|
|
38
|
+
- Replaces the per-group bulk question and the per-entry decision in `groom-backlog` with one proposed action per digest entry, which the skill applies to the whole page after one confirmation, with overrides named per entry. (#1984)
|
|
39
|
+
- Adds the `--close-not-planned <reason>` option to `groom-backlog`, which closes the selected tickets as not planned without assessing them, requires `--scope` or `--older-than`, and lists the tickets in one confirmation before it closes any. (#1984)
|
|
40
|
+
- Makes `groom-backlog` apply the edit that `ticket-assessor` drafts for a confirmed `update`, `revise`, or `split`, replacing the rewritten body sections, creating and linking a split's child tickets, and naming the rewritten sections in its comment, and skipping a draft when the ticket changed after its assessment or when the draft would rewrite the Problem, Context, or Proposed solution of an in-progress ticket. (#1984)
|
|
41
|
+
- Adds an instruction to the umbrella criterion convention, which `create-ticket`, `design-and-plan`, and `align-ticket-with-implementation` include, to create a child ticket for every planned piece once the split is decided and to defer a piece by closing its child as not planned, so that the criterion "Every child is closed" cannot hold while a planned piece lacks a ticket. (#1987)
|
|
42
|
+
- Adds an instruction to the `williamthorsen-workflow-preferences` rulebook to create every iteration's sub-issue when the epic is created. (#1987)
|
|
43
|
+
- Directs `assess-ticket` to count the `partial` progress of an umbrella (a ticket that has open children and whose only unchecked criterion is "Every child is closed") as baseline, recognized from the ticket's child counts, and not to offer an update or close action for it. (#1989)
|
|
44
|
+
- Adds a test-file length rule to the `testing-conventions` skill, which directs an agent to split a test file by aspect before adding tests that would leave it past the project's `max-lines` setting for test files, or past 500 lines when the lint does not set one, and to move shared fixture builders into a `test-utils/` module beside the tests. (#1991)
|
|
45
|
+
- Adds a rule to the `review-criteria` skill that classifies a test file that the change adds to and leaves past that ceiling as a Warning, except in a project whose lint already applies `max-lines` to test files. (#1991)
|
|
46
|
+
- Adds the `shared-data-conventions` rulebook, which forbids writes to shared state from unmerged code and requires each expand, migrate, or contract step of a data-shape change to be merged and deployed before the next begins, to the `recommended` collection. (#1992)
|
|
47
|
+
- Directs `create-ticket`, `design-and-plan`, and `plan` to scope a ticket or plan that changes the shape of persisted data to one step of that sequence, and bars every planned task and verification check from writing to shared state before merge. (#1992)
|
|
48
|
+
- Directs `implement-plan` to treat a step or verification check that writes to shared state from the branch as material divergence, to be reported rather than run even when the plan directs it. (#1992)
|
|
49
|
+
- Adds a "Data changes" item to `review-criteria`, which flags a change that removes or renames data still read by deployed code, or that depends on a migration run before merge. (#1992)
|
|
50
|
+
- Adds a "Subagent models" section to the Claude harness `CLAUDE.md`, which directs a session to pass `haiku` to a subagent that only searches for files or code, to pass `sonnet` to one that only reads, runs checks, or reports, and to leave the model unset for one that writes code or prose. (#1996)
|
|
51
|
+
- Changes the model declared for the `plan-reviser` subagent from `sonnet` to `inherit`, so that the subagent, which rewrites plans, runs on the session's model. (#1996)
|
|
52
|
+
- 🚨 **Breaking:** Publishes the `preferences` and `work-types` JSON Schemas in `codeassembly-guidance` as `schemas/preferences.v1.json` and `schemas/work-types.v1.json`, each with an `$id` of the form `https://unpkg.com/codeassembly-guidance@<version>/schemas/<name>.v<N>.json`, so that one `$id` always names the same schema. (#2000)
|
|
53
|
+
- Adds the `ticket.pull.excludeLabels` preference, which lists the labels that make a ticket ineligible for `pull-from-backlog`, matches them without regard to case, and defaults to `["status:blocked", "status:on-hold"]`. (#2002)
|
|
54
|
+
- Makes `pull-from-backlog` report when the Now milestone has no eligible open tickets left, with a suggestion to close it or plan a new one, and state how many open tickets an excluded label kept off the menu. (#2002)
|
|
55
|
+
- Adds a stderr warning from `describe-change.mjs`, issued when preferences load, for each configured `title_format` that loses a token for some record shape, such as a flat `[{scope}|{type}: ]` group that drops the type when the scope is absent or `*`, while the run still renders. (#2006)
|
|
56
|
+
- Adds the `supported-harnesses:` rulebook frontmatter field, which restricts the rulebook's ambient region, rulebook skill, and hook fill to the named harnesses under both `sync` and content-root rendering, and makes `sync` retract what it previously deployed to a harness that the rulebook now excludes. (#2009)
|
|
57
|
+
- Moves the subagent-model guidance from the Claude harness `CLAUDE.md` into the new ambient rulebook `williamthorsen-subagent-model-preferences`, which declares `claude` as its only supported harness and is added to the `williamthorsen` collection. (#2010)
|
|
58
|
+
- Adds a rule to `testing-conventions` that a passing test prints nothing beyond the runner's report, directing each test to capture output that is the behavior, silence output that is incidental, and intercept only the channels that it expects to fire. (#2015)
|
|
59
|
+
- Adds a section to `typescript-testing-conventions` that names `silenceConsole` and `listConsoleLines` from `@williamthorsen/toolbelt.vitest/candidate` and `captureStdio` from `@williamthorsen/toolbelt.testing/candidate` for applying that rule, with a `vi.spyOn` or `jest.spyOn` fallback for a project that does not depend on those packages. (#2015)
|
|
60
|
+
- Widens the description of `typescript-testing-conventions` from Jest-based projects to Vitest- and Jest-based projects, so that the skill is also selected in a Vitest project. (#2015)
|
|
61
|
+
- Adds a "Noisy tests" section to `review-criteria`, which classifies a test that the change adds and that writes output on a passing run as a Suggestion whose proposed change is the interception described in `testing-conventions`. (#2015)
|
|
62
|
+
- Makes the builders' write allowance in `prepare-prototype-brief` a default of the output file alone, which the developer's ask can extend to a repository directory that keeps the prototypes or to a dependency install, and directs the agent to state the allowance in the brief's rules of engagement. (#2018)
|
|
63
|
+
- Adds an assessment step to `upgrade-dependencies` that checks the working tree for uncommitted manifest or lockfile changes, because the outdated report omits an upgrade already applied there, and that requires verifying those changes through the quality gate before planning new upgrades. (#2019)
|
|
64
|
+
- Sets the `@types/node` target in `upgrade-dependencies` to the major of the project's Node floor rather than the latest major listed by the outdated report. (#2019)
|
|
65
|
+
- Limits the security fast-track in `upgrade-dependencies` to actionable advisories, and directs the agent to check whether re-resolving a transitive package within its parent's range, or upgrading the direct dependency that pulls it in, resolves the advisory, and to record one without an upstream fix as a known issue in the PR body rather than force a version with an override. (#2019)
|
|
66
|
+
- Extends the downstream-support check that `upgrade-dependencies` runs before a major upgrade to shared configs and the plugins that they pull in transitively, and directs holding the upgrade at its ceiling when one of them does not support the new major and a maintained fork does not exist. (#2019)
|
|
67
|
+
- Defines a major upgrade together with the code and config adaptations that it requires as one logical change in the commit guidance of `upgrade-dependencies`. (#2019)
|
|
68
|
+
|
|
69
|
+
### 🪦 Removed
|
|
70
|
+
|
|
71
|
+
- 🚨 **Breaking:** Removes the skills `orchestrate`, `orchestrate-dev`, `orchestrate-review`, `plan-orchestrable-steps`, and `find-orchestration-savings`, together with the subagents that only those skills dispatched, such as `orchestrated-coder`, `planner`, and the `aspect-*` reviewers. (#1943)
|
|
72
|
+
- Removes the `orchestration` block (review rounds, severity thresholds, MCP policy, and per-role model overrides) from the `preferences.yaml` schema, which sets `additionalProperties: false`, so an editor that validates the file now reports an `orchestration` key as unknown. (#1943)
|
|
73
|
+
- Removes the parts of the surviving skills that served only engine runs: the `--run-id` argument of `create-devlog`, the `--role` argument and run-artifact path of `plan`, the orchestrated session type of `wrap-up`, the JSON-companion plan format of `refine-plan`, and the reuse of an active run directory by `review-branch`, which now always creates a new `{timestamp}-interactive` run directory. (#1943)
|
|
74
|
+
- Removes the post-merge ripple, `groom-backlog --related-to`, which assessed the open tickets related to a merged ticket, along with the offers to run it from `merge-pr`, `wrap-up`, and `pull-from-backlog`. (#1980)
|
|
75
|
+
|
|
76
|
+
### 🐛 Bug fixes
|
|
77
|
+
|
|
78
|
+
- Fixes the issue that a next-steps menu could recommend an option by what the session holds, such as a table "already in context": `option-format` now names any pro or con that cites the conversation as one to cut, and `next-steps-after-plan` states that the saved ticket and plan are the complete handoff, with a fact found only in the session added to the artifact instead. (#1939)
|
|
79
|
+
- Corrects the context-clearing rationales in `implement-plan`, `next-steps-after-plan`, and `next-steps-after-review` that justified staying in the session by what the session remembers, so that each names the branch's commits and diff, the saved plan, or the saved review as its source. (#1939)
|
|
80
|
+
- Fixes the issue that `review-gh-pr` could select a different ticket on each run when a pull request body referenced several issues, by adding a `select-pr-ticket` helper that takes the first `closingIssuesReferences` entry or else the earliest reference in the body outside code. (#1954)
|
|
81
|
+
- Fixes the issue that `williamthorsen-collaboration-preferences` did not state when an agent may hand a step to the developer, by adding a "Handoffs" section that directs the agent to perform every step, verification included, and to hand over only the part that it cannot perform, with the reason. (#1956)
|
|
82
|
+
- Fixes the issue that `williamthorsen-tooling-preferences` read as licence to hand a sandbox-refused command to the developer, by rewriting the rule to direct the agent to retry the command through the permission gate or to ask once for the grant that clears it. (#1956)
|
|
83
|
+
- Fixes the issue that the plan template let a plan name the developer as the actor of a task or verification check: Every step now names the agent, a part that only the developer can perform is written as a `**Residue:**` line with its reason, and `plan-reviewer` and `handoff-reviewer` report a developer-assigned step that lacks one. (#1956)
|
|
84
|
+
- Fixes the issue that `implement-plan` turned a plan's developer-assigned verification step into a request for the developer to run it, by revising its steps to direct the agent to run every check itself, through a debug browser where one is provided, and to raise only the ask that a `**Residue:**` line states. (#1956)
|
|
85
|
+
- Fixes the issue that the action-items sweep let an agent fill the block with checks and commands that it could resolve itself, by naming those forms in the sweep and directing the agent to run such an item rather than ask it. (#1956)
|
|
86
|
+
- Fixes the issue that `summarize-change` headed the `## Details` subsections with labels of the agent's own, such as `🔧 Tooling` for `⚙️ Tooling`, rather than with the headings declared in `work-types.json`. (#1957)
|
|
87
|
+
- Fixes the issue that `review-branch` and `review-pr` created a new run directory for every review, so a re-review neither read nor joined the run that holds the earlier review and the author's response. (#1958)
|
|
88
|
+
- Fixes the issue that `respond-to-review` could select a run directory written by the retired orchestration engine when it looked for the newest review. (#1958)
|
|
89
|
+
- Addresses the issue that commit titles composed with `create-commit` contained backticks, which `title-voice.md` forbids, by directing step 3 of the skill to strip any backticks from the title text. (#1970)
|
|
90
|
+
- Fixes the issue that the rulebook's existing rules read as claims about the world rather than as instructions, by opening each with an imperative addressed to the agent. (#1973)
|
|
91
|
+
- Fixes the issue that `derive-session-context` returned a cached branch manifest after a preference change, which left `ticket_id`, `ticket_ref`, `artifact_base_dir`, and the other preference-derived fields at their original values until the file was deleted by hand. (#1993)
|
|
92
|
+
- Fixes the issue that `resolve-frontmatter.sh` read the manifest file directly and stamped artifacts with a stale `ticket_id` and `ticket_ref`, by taking the manifest from the deriver on every call. (#1993)
|
|
93
|
+
- Fixes the issue that `artifact-conventions.md` did not state that a `ticket_ref_prefix` other than `#` is part of `ticket_id` and names the artifact directory, such as `tickets/ABC-100/` for branch `100` under `ABC-`, and that changing the prefix sends later artifacts to a different directory. (#1994)
|
|
94
|
+
- Fixes the issue that `ticket-source-resolution.md` told the agent to join a numeric `ticket_id` to a Jira-style prefix read from `.agents/preferences.yaml`, a case that the session-context deriver never produces because it already includes that prefix in `ticket_id`. (#1994)
|
|
95
|
+
- Fixes the issue that `resolve-frontmatter.sh` looked for the `derive-session-context` helper in `skills/derive-session-context/`, where `sync` does not deploy it, by making the script search every source namespace under `skills/_sources/` and exit non-zero with the searched path when it finds no match or several. (#1999)
|
|
96
|
+
- Fixes the issue that `resolve-frontmatter.sh` reported a missing bundled helper when the path set by `RESOLVE_FRONTMATTER_BUNDLE_PATH` was not readable. (#1999)
|
|
97
|
+
- Fixes the issue that `pull-from-backlog` offered shelved tickets as candidates and counted them when choosing the Now milestone, which could produce a Now set made up only of shelved work. (#2002)
|
|
98
|
+
- Fixes the issue that `pull-from-backlog` showed a short or empty menu when the Now milestone held fewer eligible tickets than the menu limit, by filling the remaining slots with the highest-ranked eligible tickets from outside Now and marking each one `(outside Now)`. (#2002)
|
|
99
|
+
- Fixes the issue that `entry-drafter` and `title-voice.md` stated their doctrine in figures forbidden by the plain-speech rule, such as "earns its place", "the count is the tell", and "a ceiling, not a target", by replacing each with a literal statement. (#2005)
|
|
100
|
+
- Fixes the issue that `prepare-prototype-brief` stated its instructions as aphorisms and agentless statements, such as "Settled intent stays settled", rather than as imperatives that name the action. (#2018)
|
|
101
|
+
- Fixes the issue that `entry-drafter` and `summarize-change` stated that the lede reaches the changelog and the release notes, which `release-kit` renders from the change entries without the lede. (#2023)
|
|
102
|
+
|
|
103
|
+
### ⚡ Performance
|
|
104
|
+
|
|
105
|
+
- Declares `context: fork`, `model: sonnet`, and `background: false` on `create-commit`, so that Claude runs each commit in a fresh Sonnet subagent and waits for it, instead of running every commit step against the invoking session's whole context on the session's model. (#1979)
|
|
106
|
+
|
|
107
|
+
### 🏗️ Internal features
|
|
108
|
+
|
|
109
|
+
- Replaces the `create` subcommand of `resolve-review-run.mjs` with `open`, which returns the ticket's active run and creates a `{timestamp}-interactive` run directory only when the ticket directory does not contain one. (#1958)
|
|
110
|
+
|
|
111
|
+
### ♻️ Refactoring
|
|
112
|
+
|
|
113
|
+
- Moves review run-directory creation and lookup from the `review-branch` and `respond-to-review` instructions into the `resolve-review-run` helper so that every run follows one procedure, which selects the newest run and review by the timestamps in their names. (#1953)
|
|
114
|
+
- Replaces the inline `ENOENT` checks in `run-core`'s `resolve-base-dir.ts` and in `read-dir-entries.ts` and `list-markdown-files.ts` under `packages/guidance/content/test-utils/` with each package's existing `isEnoent`, and removes the private copy of the guard from the test utilities. (#2004)
|
|
115
|
+
- Moves `describe-change`, `capture-lede-decision`, and the work-types reader onto `@williamthorsen/change-grammar` and deletes the local engine in `packages/guidance/src/change-grammar/`, together with its release-kit parity test and its ESLint boundary rules. (#2007)
|
|
116
|
+
|
|
117
|
+
### 🧪 Tests
|
|
118
|
+
|
|
119
|
+
- Replaces the hand-rolled `process.stderr` spies and the console output rebuilt from spy call records in the repo's tests with `captureStdio` from `@williamthorsen/toolbelt.testing`, which restores the stream when the test scope exits and buffers console output into `stdout` and `stderr`. (#2003)
|
|
120
|
+
|
|
121
|
+
### ⚙️ Tooling
|
|
122
|
+
|
|
123
|
+
- Makes the `guidance` build generate `content/skills/_data/work-types.json` from the package's `CANONICAL_TAXONOMY`, and makes `check:content` fail when the committed copy differs from the generated one. (#2007)
|
|
124
|
+
|
|
125
|
+
### 🤖 Agentic support
|
|
126
|
+
|
|
127
|
+
- Adds a "Model declarations" section to the `codeassembly-repo-conventions` rulebook, which permits a skill to declare `model` only together with `context: fork` and limits every declared model to a Claude Code alias or a full `claude-` model ID, and adds `model-declarations.unit.test.ts`, which fails on a declaration that breaks either rule. (#1996)
|
|
128
|
+
|
|
129
|
+
### 📚 Documentation
|
|
130
|
+
|
|
131
|
+
- Adds `docs/schemas.md` to `codeassembly-guidance`, which lists the published schemas with their import paths and states which schema changes bump a schema's major version. (#2000)
|
|
132
|
+
- Changes the example template in `packages/guidance/docs/preferences.md` to the nested `[[{scope}|]{type}: ]` form, so that the example output for a change without a scope keeps the type. (#2006)
|
|
133
|
+
|
|
134
|
+
<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->
|
package/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 William Thorsen
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
|
|
6
|
+
|
|
7
|
+
The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.
|
package/README.md
CHANGED
|
@@ -1 +1,165 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- readme-type: content -->
|
|
2
|
+
|
|
3
|
+
# codeassembly-guidance
|
|
4
|
+
|
|
5
|
+
The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](../agents/README.md) CLI deploys into Claude Code and Rovo Dev.
|
|
6
|
+
|
|
7
|
+
<!-- section:release-notes -->
|
|
8
|
+
## Release notes — v0.1.0 (2026-10-10)
|
|
9
|
+
|
|
10
|
+
### 🎉 Features
|
|
11
|
+
|
|
12
|
+
- Moves the CodeAssembly library and its helpers from the `codeassembly` package into the new `codeassembly-guidance` package at `packages/guidance`, whose support files deploy under `_sources/codeassembly-guidance/`. (#1933)
|
|
13
|
+
- Adds the Claude-only `prepare-prototype-brief` skill, which composes and checks the shared brief for a round of competing prototypes, dispatches one builder per lens, and writes a comparison of the prototypes after `index-prototypes` builds the index page. (#1936)
|
|
14
|
+
- Adds the ambient rulebook `command-output-conventions` to the `recommended` collection, which directs an agent to print only the fact that a step needs from a large or repeated command's output, and, for a repeated evaluation, to print one line per case from a single scorer. (#1938)
|
|
15
|
+
- Adds a "Procedures in helpers" section to the `codeassembly-content-specification` rulebook, which directs an author who edits a skill or subagent to move a step whose result is fixed by its inputs into a helper that emits JSON, extending an existing helper when one already performs the step. (#1952)
|
|
16
|
+
- Makes `create-ticket` resolve a new ticket's labels by running `describe-change.mjs resolve-labels`, which now accepts a call without `--body-file` and labels the record from `--type`, `--scope`, and `--breaking` alone. (#1952)
|
|
17
|
+
- Adds the `manage-jira-ticket.mjs` helper, which `create-ticket` now runs to resolve the project key and issue type from the repository's `.agents/preferences.yaml`, check a parent reference, and run `acli jira workitem create` exactly once. (#1955)
|
|
18
|
+
- Directs the `acli` path of `update-jira-ticket` to convert a Markdown body to ADF with the helper's `convert-body` subcommand, which turns GFM task lists into Jira task items. (#1955)
|
|
19
|
+
- Adds the `describe-change render-details` subcommand, which renders a change summary's `## Details` body from an entries file, with its headings, subsection order, and breaking prefix taken from `work-types.json`. (#1957)
|
|
20
|
+
- Adds a launch prompt for each ticket that keeps work to the "Split the ticket" report of `design-and-plan`, `plan`, `refine-plan`, and `save-plan`, which starts the session at `design-and-plan`, `plan`, `refine-plan`, or `implement-plan`, depending on how much of the ticket's design and plan is already settled, and lists the ticket's plan path, scope notes, and blockers. (#1961)
|
|
21
|
+
- Adds a launch prompt for each piece to the "Split the branch" report of `implement-plan`, which starts the session at `review-branch` with the piece's diff base, names the piece's branch and worktree, and shows each later piece as blocked until its predecessor merges. (#1961)
|
|
22
|
+
- Adds the `--related-to <#>` option to the `groom-backlog` skill, which assesses the open tickets related to a closed ticket in place of the backlog: the tickets that mention it or its closing pull request, the tickets that it blocked, its parent and the parent's other open children, and the tickets that name a file touched by the closing pull request. (#1966)
|
|
23
|
+
- Adds the `pending-ripples` command to the `groom-backlog` helper, which lists the closed tickets that a ripple has not yet assessed, since a given date or else since the last pull or the last groom that was not a dry run. (#1966)
|
|
24
|
+
- Adds the `related` command to the `groom-backlog` helper, which returns a ripple's related set with its counts by tier without writing anything. (#1966)
|
|
25
|
+
- Directs the `ticket-assessor` subagent to examine a ripple's closed ticket and pull request first, and to recommend `close-complete` when the pull request met the ticket's motivation or when the ticket is a parent whose children are all closed. (#1966)
|
|
26
|
+
- Extends the `groom-backlog` issue fetch to request each ticket's parent, blockers, sub-issue counts, assignees, and milestone, which requires `gh` 2.100 or later. (#1966)
|
|
27
|
+
- Adds a final step to `merge-pr` that reads the open tickets related to the ticket that the merge commit closes and asks for consent before running `groom-backlog --related-to` on them, or records an empty ripple when the merged ticket does not have any related tickets. (#1967)
|
|
28
|
+
- Adds a "Ripple merged ticket #N" action to `wrap-up`, which it offers for a ticket closed by a PR merged in the session when `pending-ripples` reports that the ticket has not been rippled yet. (#1967)
|
|
29
|
+
- Adds the `pull-from-backlog` skill, which presents the current milestone's umbrellas, in-progress tickets, and blocked tickets with the backlog's warnings, offers the unblocked and unassigned tickets as a ranked menu with the reasons for each rank, and assigns the picked ticket to the user on consent. (#1969)
|
|
30
|
+
- Adds the `ticket.pull` project preferences, which set the milestone that `pull-from-backlog` treats as current, the prefix of the priority labels, the thresholds at which a branch or a groom counts as stale, and whether a pick assigns the user without asking. (#1969)
|
|
31
|
+
- Adds a "Product development" section to the `williamthorsen-workflow-preferences` rulebook, which states the stages from idea to increments, with a usable MVP before further features, and the shape to propose once the developer approves the end vision: an epic whose iterations are its sub-issues, with only the current one specified in detail. (#1973)
|
|
32
|
+
- States which artifact holds what: a design doc in the repo holds the vision, the epic points to it and lists the iterations in order, the milestone marks the current iteration, and each later iteration stays a one-line outcome until its work starts. (#1973)
|
|
33
|
+
- Names the winning prototype as the baseline for the finished product, the floor on quality and feel against which it is judged, with a feature reduced in one iteration recorded as a one-line sub-issue and a feature settled below that bar recorded in the design doc with its reason. (#1973)
|
|
34
|
+
- Makes `create-commit` take the paths to stage and a one-line purpose as arguments, compose the body from the diff alone when no purpose is passed, and report the new commit's short SHA and title or the reason that nothing was committed. (#1979)
|
|
35
|
+
- States in `codeassembly-content-specification` that the deploy writes every skill frontmatter key other than `supported-harnesses` 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. (#1979)
|
|
36
|
+
- Adds a step to `merge-pr` that offers to close the parent ticket when the merge closed its last open child, and lists any of the parent's own unchecked acceptance criteria beneath the question. (#1980)
|
|
37
|
+
- Names `clients/<library>/` in place of `integrations/` in the `williamthorsen-code-layout-preferences` rulebook as the directory for code that talks to a third-party service or library or maps to its data shapes, and directs code that uses a client to a directory named for its domain. (#1982)
|
|
38
|
+
- Changes `groom-backlog` to keep an in-progress ticket open without commenting on it or presenting it in a digest when its assessment is a `keep` whose verdicts are all baseline; previously, `groom-backlog` presented every in-progress ticket to the user for a decision. (#1983)
|
|
39
|
+
- Counts `partial` progress as baseline for an umbrella ticket, which is a ticket that has open children and whose only unchecked criterion is "Every child is closed", so that `groom-backlog` keeps such a ticket silently when its assessment is a `keep` and its other verdicts are baseline, and does not post a comment when the user decides to keep it. (#1983)
|
|
40
|
+
- Adds a `post` field to the result of the `groom-backlog` helper's `comment` command, which states whether the decision's comment is posted and leaves `--out` unwritten when it is `false`, replacing the skill's own check of the verdicts. (#1983)
|
|
41
|
+
- Replaces the per-group bulk question and the per-entry decision in `groom-backlog` with one proposed action per digest entry, which the skill applies to the whole page after one confirmation, with overrides named per entry. (#1984)
|
|
42
|
+
- Adds the `--close-not-planned <reason>` option to `groom-backlog`, which closes the selected tickets as not planned without assessing them, requires `--scope` or `--older-than`, and lists the tickets in one confirmation before it closes any. (#1984)
|
|
43
|
+
- Makes `groom-backlog` apply the edit that `ticket-assessor` drafts for a confirmed `update`, `revise`, or `split`, replacing the rewritten body sections, creating and linking a split's child tickets, and naming the rewritten sections in its comment, and skipping a draft when the ticket changed after its assessment or when the draft would rewrite the Problem, Context, or Proposed solution of an in-progress ticket. (#1984)
|
|
44
|
+
- Adds an instruction to the umbrella criterion convention, which `create-ticket`, `design-and-plan`, and `align-ticket-with-implementation` include, to create a child ticket for every planned piece once the split is decided and to defer a piece by closing its child as not planned, so that the criterion "Every child is closed" cannot hold while a planned piece lacks a ticket. (#1987)
|
|
45
|
+
- Adds an instruction to the `williamthorsen-workflow-preferences` rulebook to create every iteration's sub-issue when the epic is created. (#1987)
|
|
46
|
+
- Directs `assess-ticket` to count the `partial` progress of an umbrella (a ticket that has open children and whose only unchecked criterion is "Every child is closed") as baseline, recognized from the ticket's child counts, and not to offer an update or close action for it. (#1989)
|
|
47
|
+
- Adds a test-file length rule to the `testing-conventions` skill, which directs an agent to split a test file by aspect before adding tests that would leave it past the project's `max-lines` setting for test files, or past 500 lines when the lint does not set one, and to move shared fixture builders into a `test-utils/` module beside the tests. (#1991)
|
|
48
|
+
- Adds a rule to the `review-criteria` skill that classifies a test file that the change adds to and leaves past that ceiling as a Warning, except in a project whose lint already applies `max-lines` to test files. (#1991)
|
|
49
|
+
- Adds the `shared-data-conventions` rulebook, which forbids writes to shared state from unmerged code and requires each expand, migrate, or contract step of a data-shape change to be merged and deployed before the next begins, to the `recommended` collection. (#1992)
|
|
50
|
+
- Directs `create-ticket`, `design-and-plan`, and `plan` to scope a ticket or plan that changes the shape of persisted data to one step of that sequence, and bars every planned task and verification check from writing to shared state before merge. (#1992)
|
|
51
|
+
- Directs `implement-plan` to treat a step or verification check that writes to shared state from the branch as material divergence, to be reported rather than run even when the plan directs it. (#1992)
|
|
52
|
+
- Adds a "Data changes" item to `review-criteria`, which flags a change that removes or renames data still read by deployed code, or that depends on a migration run before merge. (#1992)
|
|
53
|
+
- Adds a "Subagent models" section to the Claude harness `CLAUDE.md`, which directs a session to pass `haiku` to a subagent that only searches for files or code, to pass `sonnet` to one that only reads, runs checks, or reports, and to leave the model unset for one that writes code or prose. (#1996)
|
|
54
|
+
- Changes the model declared for the `plan-reviser` subagent from `sonnet` to `inherit`, so that the subagent, which rewrites plans, runs on the session's model. (#1996)
|
|
55
|
+
- 🚨 **Breaking:** Publishes the `preferences` and `work-types` JSON Schemas in `codeassembly-guidance` as `schemas/preferences.v1.json` and `schemas/work-types.v1.json`, each with an `$id` of the form `https://unpkg.com/codeassembly-guidance@<version>/schemas/<name>.v<N>.json`, so that one `$id` always names the same schema. (#2000)
|
|
56
|
+
- Adds the `ticket.pull.excludeLabels` preference, which lists the labels that make a ticket ineligible for `pull-from-backlog`, matches them without regard to case, and defaults to `["status:blocked", "status:on-hold"]`. (#2002)
|
|
57
|
+
- Makes `pull-from-backlog` report when the Now milestone has no eligible open tickets left, with a suggestion to close it or plan a new one, and state how many open tickets an excluded label kept off the menu. (#2002)
|
|
58
|
+
- Adds a stderr warning from `describe-change.mjs`, issued when preferences load, for each configured `title_format` that loses a token for some record shape, such as a flat `[{scope}|{type}: ]` group that drops the type when the scope is absent or `*`, while the run still renders. (#2006)
|
|
59
|
+
- Adds the `supported-harnesses:` rulebook frontmatter field, which restricts the rulebook's ambient region, rulebook skill, and hook fill to the named harnesses under both `sync` and content-root rendering, and makes `sync` retract what it previously deployed to a harness that the rulebook now excludes. (#2009)
|
|
60
|
+
- Moves the subagent-model guidance from the Claude harness `CLAUDE.md` into the new ambient rulebook `williamthorsen-subagent-model-preferences`, which declares `claude` as its only supported harness and is added to the `williamthorsen` collection. (#2010)
|
|
61
|
+
- Adds a rule to `testing-conventions` that a passing test prints nothing beyond the runner's report, directing each test to capture output that is the behavior, silence output that is incidental, and intercept only the channels that it expects to fire. (#2015)
|
|
62
|
+
- Adds a section to `typescript-testing-conventions` that names `silenceConsole` and `listConsoleLines` from `@williamthorsen/toolbelt.vitest/candidate` and `captureStdio` from `@williamthorsen/toolbelt.testing/candidate` for applying that rule, with a `vi.spyOn` or `jest.spyOn` fallback for a project that does not depend on those packages. (#2015)
|
|
63
|
+
- Widens the description of `typescript-testing-conventions` from Jest-based projects to Vitest- and Jest-based projects, so that the skill is also selected in a Vitest project. (#2015)
|
|
64
|
+
- Adds a "Noisy tests" section to `review-criteria`, which classifies a test that the change adds and that writes output on a passing run as a Suggestion whose proposed change is the interception described in `testing-conventions`. (#2015)
|
|
65
|
+
- Makes the builders' write allowance in `prepare-prototype-brief` a default of the output file alone, which the developer's ask can extend to a repository directory that keeps the prototypes or to a dependency install, and directs the agent to state the allowance in the brief's rules of engagement. (#2018)
|
|
66
|
+
- Adds an assessment step to `upgrade-dependencies` that checks the working tree for uncommitted manifest or lockfile changes, because the outdated report omits an upgrade already applied there, and that requires verifying those changes through the quality gate before planning new upgrades. (#2019)
|
|
67
|
+
- Sets the `@types/node` target in `upgrade-dependencies` to the major of the project's Node floor rather than the latest major listed by the outdated report. (#2019)
|
|
68
|
+
- Limits the security fast-track in `upgrade-dependencies` to actionable advisories, and directs the agent to check whether re-resolving a transitive package within its parent's range, or upgrading the direct dependency that pulls it in, resolves the advisory, and to record one without an upstream fix as a known issue in the PR body rather than force a version with an override. (#2019)
|
|
69
|
+
- Extends the downstream-support check that `upgrade-dependencies` runs before a major upgrade to shared configs and the plugins that they pull in transitively, and directs holding the upgrade at its ceiling when one of them does not support the new major and a maintained fork does not exist. (#2019)
|
|
70
|
+
- Defines a major upgrade together with the code and config adaptations that it requires as one logical change in the commit guidance of `upgrade-dependencies`. (#2019)
|
|
71
|
+
|
|
72
|
+
### 🪦 Removed
|
|
73
|
+
|
|
74
|
+
- 🚨 **Breaking:** Removes the skills `orchestrate`, `orchestrate-dev`, `orchestrate-review`, `plan-orchestrable-steps`, and `find-orchestration-savings`, together with the subagents that only those skills dispatched, such as `orchestrated-coder`, `planner`, and the `aspect-*` reviewers. (#1943)
|
|
75
|
+
- Removes the `orchestration` block (review rounds, severity thresholds, MCP policy, and per-role model overrides) from the `preferences.yaml` schema, which sets `additionalProperties: false`, so an editor that validates the file now reports an `orchestration` key as unknown. (#1943)
|
|
76
|
+
- Removes the parts of the surviving skills that served only engine runs: the `--run-id` argument of `create-devlog`, the `--role` argument and run-artifact path of `plan`, the orchestrated session type of `wrap-up`, the JSON-companion plan format of `refine-plan`, and the reuse of an active run directory by `review-branch`, which now always creates a new `{timestamp}-interactive` run directory. (#1943)
|
|
77
|
+
- Removes the post-merge ripple, `groom-backlog --related-to`, which assessed the open tickets related to a merged ticket, along with the offers to run it from `merge-pr`, `wrap-up`, and `pull-from-backlog`. (#1980)
|
|
78
|
+
|
|
79
|
+
### 🐛 Bug fixes
|
|
80
|
+
|
|
81
|
+
- Fixes the issue that a next-steps menu could recommend an option by what the session holds, such as a table "already in context": `option-format` now names any pro or con that cites the conversation as one to cut, and `next-steps-after-plan` states that the saved ticket and plan are the complete handoff, with a fact found only in the session added to the artifact instead. (#1939)
|
|
82
|
+
- Corrects the context-clearing rationales in `implement-plan`, `next-steps-after-plan`, and `next-steps-after-review` that justified staying in the session by what the session remembers, so that each names the branch's commits and diff, the saved plan, or the saved review as its source. (#1939)
|
|
83
|
+
- Fixes the issue that `review-gh-pr` could select a different ticket on each run when a pull request body referenced several issues, by adding a `select-pr-ticket` helper that takes the first `closingIssuesReferences` entry or else the earliest reference in the body outside code. (#1954)
|
|
84
|
+
- Fixes the issue that `williamthorsen-collaboration-preferences` did not state when an agent may hand a step to the developer, by adding a "Handoffs" section that directs the agent to perform every step, verification included, and to hand over only the part that it cannot perform, with the reason. (#1956)
|
|
85
|
+
- Fixes the issue that `williamthorsen-tooling-preferences` read as licence to hand a sandbox-refused command to the developer, by rewriting the rule to direct the agent to retry the command through the permission gate or to ask once for the grant that clears it. (#1956)
|
|
86
|
+
- Fixes the issue that the plan template let a plan name the developer as the actor of a task or verification check: Every step now names the agent, a part that only the developer can perform is written as a `**Residue:**` line with its reason, and `plan-reviewer` and `handoff-reviewer` report a developer-assigned step that lacks one. (#1956)
|
|
87
|
+
- Fixes the issue that `implement-plan` turned a plan's developer-assigned verification step into a request for the developer to run it, by revising its steps to direct the agent to run every check itself, through a debug browser where one is provided, and to raise only the ask that a `**Residue:**` line states. (#1956)
|
|
88
|
+
- Fixes the issue that the action-items sweep let an agent fill the block with checks and commands that it could resolve itself, by naming those forms in the sweep and directing the agent to run such an item rather than ask it. (#1956)
|
|
89
|
+
- Fixes the issue that `summarize-change` headed the `## Details` subsections with labels of the agent's own, such as `🔧 Tooling` for `⚙️ Tooling`, rather than with the headings declared in `work-types.json`. (#1957)
|
|
90
|
+
- Fixes the issue that `review-branch` and `review-pr` created a new run directory for every review, so a re-review neither read nor joined the run that holds the earlier review and the author's response. (#1958)
|
|
91
|
+
- Fixes the issue that `respond-to-review` could select a run directory written by the retired orchestration engine when it looked for the newest review. (#1958)
|
|
92
|
+
- Addresses the issue that commit titles composed with `create-commit` contained backticks, which `title-voice.md` forbids, by directing step 3 of the skill to strip any backticks from the title text. (#1970)
|
|
93
|
+
- Fixes the issue that the rulebook's existing rules read as claims about the world rather than as instructions, by opening each with an imperative addressed to the agent. (#1973)
|
|
94
|
+
- Fixes the issue that `derive-session-context` returned a cached branch manifest after a preference change, which left `ticket_id`, `ticket_ref`, `artifact_base_dir`, and the other preference-derived fields at their original values until the file was deleted by hand. (#1993)
|
|
95
|
+
- Fixes the issue that `resolve-frontmatter.sh` read the manifest file directly and stamped artifacts with a stale `ticket_id` and `ticket_ref`, by taking the manifest from the deriver on every call. (#1993)
|
|
96
|
+
- Fixes the issue that `artifact-conventions.md` did not state that a `ticket_ref_prefix` other than `#` is part of `ticket_id` and names the artifact directory, such as `tickets/ABC-100/` for branch `100` under `ABC-`, and that changing the prefix sends later artifacts to a different directory. (#1994)
|
|
97
|
+
- Fixes the issue that `ticket-source-resolution.md` told the agent to join a numeric `ticket_id` to a Jira-style prefix read from `.agents/preferences.yaml`, a case that the session-context deriver never produces because it already includes that prefix in `ticket_id`. (#1994)
|
|
98
|
+
- Fixes the issue that `resolve-frontmatter.sh` looked for the `derive-session-context` helper in `skills/derive-session-context/`, where `sync` does not deploy it, by making the script search every source namespace under `skills/_sources/` and exit non-zero with the searched path when it finds no match or several. (#1999)
|
|
99
|
+
- Fixes the issue that `resolve-frontmatter.sh` reported a missing bundled helper when the path set by `RESOLVE_FRONTMATTER_BUNDLE_PATH` was not readable. (#1999)
|
|
100
|
+
- Fixes the issue that `pull-from-backlog` offered shelved tickets as candidates and counted them when choosing the Now milestone, which could produce a Now set made up only of shelved work. (#2002)
|
|
101
|
+
- Fixes the issue that `pull-from-backlog` showed a short or empty menu when the Now milestone held fewer eligible tickets than the menu limit, by filling the remaining slots with the highest-ranked eligible tickets from outside Now and marking each one `(outside Now)`. (#2002)
|
|
102
|
+
- Fixes the issue that `entry-drafter` and `title-voice.md` stated their doctrine in figures forbidden by the plain-speech rule, such as "earns its place", "the count is the tell", and "a ceiling, not a target", by replacing each with a literal statement. (#2005)
|
|
103
|
+
- Fixes the issue that `prepare-prototype-brief` stated its instructions as aphorisms and agentless statements, such as "Settled intent stays settled", rather than as imperatives that name the action. (#2018)
|
|
104
|
+
- Fixes the issue that `entry-drafter` and `summarize-change` stated that the lede reaches the changelog and the release notes, which `release-kit` renders from the change entries without the lede. (#2023)
|
|
105
|
+
|
|
106
|
+
### ⚡ Performance
|
|
107
|
+
|
|
108
|
+
- Declares `context: fork`, `model: sonnet`, and `background: false` on `create-commit`, so that Claude runs each commit in a fresh Sonnet subagent and waits for it, instead of running every commit step against the invoking session's whole context on the session's model. (#1979)
|
|
109
|
+
<!-- /section:release-notes -->
|
|
110
|
+
|
|
111
|
+
## Using the library
|
|
112
|
+
|
|
113
|
+
A declaration names the library as a source and adopts what it wants from it, usually through a collection. For the home harness directories, clone the repository and declare its content directory in `~/.agents/codeassembly.yaml`:
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
sources:
|
|
117
|
+
- name: codeassembly-guidance
|
|
118
|
+
path: ~/repos/codeassembly/packages/guidance/content
|
|
119
|
+
collections:
|
|
120
|
+
use:
|
|
121
|
+
- recommended
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Then run `codeassembly install` and `codeassembly sync --global`. A project declares the same in its own `.agents/codeassembly.yaml` and runs `codeassembly sync`. [Project declaration](../agents/docs/project-declaration.md) documents the declaration format.
|
|
125
|
+
|
|
126
|
+
## What the content contains
|
|
127
|
+
|
|
128
|
+
`content/` is a content root, laid out as the `codeassembly` tool expects:
|
|
129
|
+
|
|
130
|
+
| Directory | Contains |
|
|
131
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| `collections/` | Named sets of artifacts: `recommended` is vetted and generally applicable, and `triage` is not yet examined |
|
|
133
|
+
| `guidance/` | Rulebooks, and the harness guidance templates that `install` deploys |
|
|
134
|
+
| `skills/` | Skills, and the support files under `skills/_data/` that they read at runtime |
|
|
135
|
+
| `subagents/` | Subagent definitions |
|
|
136
|
+
| `scripts/` | Shell scripts and helper bundles that `install` deploys into each harness's `scripts/` directory |
|
|
137
|
+
| `_partials/` | Text that the expander inlines into several artifacts at deploy time |
|
|
138
|
+
|
|
139
|
+
## Adding or changing content
|
|
140
|
+
|
|
141
|
+
The `codeassembly-content-specification` rulebook ([`content/guidance/rulebooks/codeassembly-content-specification.md`](content/guidance/rulebooks/codeassembly-content-specification.md)) is the authoring contract: frontmatter fields, dependencies, invocation tokens, and naming. [`_partials/README.md`](content/_partials/README.md) covers shared text.
|
|
142
|
+
|
|
143
|
+
A skill that needs more than a few lines of shell runs a TypeScript helper. Its source lives under `src/`, `content/codeassembly-content.yaml` declares it, and `codeassembly bundle-helpers` builds it into a tracked `.mjs` bundle beside the skill. Commit a helper's source change together with its rebuilt bundle.
|
|
144
|
+
|
|
145
|
+
The package's `check` runs the tests, then `codeassembly validate` and `codeassembly bundle-helpers --check`, which fail on content that would reach a consumer broken and on a bundle that is stale.
|
|
146
|
+
|
|
147
|
+
## Preferences
|
|
148
|
+
|
|
149
|
+
Agent behavior is configured through `.agents/preferences.yaml` files. The resolution cascade is:
|
|
150
|
+
|
|
151
|
+
1. **Project**: `.agents/preferences.yaml` in the repository root (committed, shared with team)
|
|
152
|
+
2. **Global**: `~/.agents/preferences.yaml` in the user's home directory (personal defaults)
|
|
153
|
+
3. **Default**: built-in fallback (documented per key in [Preferences](docs/preferences.md))
|
|
154
|
+
|
|
155
|
+
Project-level values take precedence over global. An explicitly empty value at the project level (e.g., `title_format: ''`) overrides a non-empty global value.
|
|
156
|
+
|
|
157
|
+
The package publishes a JSON Schema for the file; [Schemas](docs/schemas.md) gives its identifier and versioning.
|
|
158
|
+
|
|
159
|
+
## Helper reference
|
|
160
|
+
|
|
161
|
+
- [Prose sweep helper](docs/revise-prose-helper.md): the sweep that the `revise-prose` skill runs.
|
|
162
|
+
- [Backlog sweep helper](docs/groom-backlog-helper.md): the helper that the `groom-backlog` skill runs.
|
|
163
|
+
- [Next-ticket helper](docs/pull-from-backlog-helper.md): the helper that the `pull-from-backlog` skill runs.
|
|
164
|
+
- [Prototype index helper](docs/index-prototypes-helper.md): the helper that the `index-prototypes` skill runs.
|
|
165
|
+
- [Guidance streamlining helper](docs/streamline-guidance-helper.md): the helper that the `streamline-guidance` skill runs.
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
<!-- readme-type: content -->
|
|
2
|
+
|
|
3
|
+
# Partials
|
|
4
|
+
|
|
5
|
+
Partials are reusable Markdown fragments shared across rulebooks, skills, subagents, and platform guidance. The install pipeline expands include directives at install time, before frontmatter merging, marker injection, and link rewriting. It never writes a partial as a standalone file; instead, it inlines the content into each consumer.
|
|
6
|
+
|
|
7
|
+
This README is the canonical reference for the partial system. The expander is implemented in `packages/agents/src/lib/directive-expander.ts`.
|
|
8
|
+
|
|
9
|
+
## Choosing a bucket
|
|
10
|
+
|
|
11
|
+
Shared Markdown belongs in one of two buckets. The bucket is chosen by _when_ the agent needs the content, not by _what kind_ of content it is; the choice decides whether the agent reliably sees it at all.
|
|
12
|
+
|
|
13
|
+
- **`_partials/`: Content that the agent must reproduce, or must apply as it writes.** Output blocks, option menus, render formats, checklists to work through, and the doctrine for an act that it performs every time (what belongs in a comment, how tight a ticket must be). Inlined at install time, so it is in context the moment the agent acts.
|
|
14
|
+
- **`_data/`: Content that the agent consults when a situation arises.** Resolution tables, classification rubrics, ranking criteria. Accessed through a runtime Markdown link and read only when the situation calls for it.
|
|
15
|
+
|
|
16
|
+
A runtime link is an optional read. When the model already has a strong prior for what the content looks like (and it does, for anything resembling a standard option menu or output block), it generates from that prior instead of following the link. Emphasis is not a remedy: A `<HARD-GATE>` reading "follow its options and output format exactly; do not improvise" preceded one such link, and the agent improvised the block anyway. Never put must-reproduce content behind a runtime link.
|
|
17
|
+
|
|
18
|
+
Doctrine is not automatically reference material. A doctrine applied by the agent every time it performs the act (comment discipline, whenever it writes a comment) binds only when it is already in context, and behind a link it does not bind at all, however well written. A doctrine consulted only when a decision arises stays in `_data/`.
|
|
19
|
+
|
|
20
|
+
Inlining is not free (every consumer contains the partial's full text), so content that the agent needs only sometimes stays in `_data/`. A spec that is partly apply-time and partly reference splits into those two parts: The binding contract becomes a partial, and the reference material stays in `_data/` and includes the partial. There is still one source of truth. If a doctrine does not have a reference-only part, it is a partial outright, and a `_data/` doc does not remain for it.
|
|
21
|
+
|
|
22
|
+
Inline a spec **once per skill, as a section**, and point every use site at it with an in-file anchor (`[option format](#option-format)`). Anchor-only links pass through the link rewriter untouched. A skill with two use sites would otherwise contain the block twice, and a reference from inside a numbered procedure cannot contain a long block inline. An in-file anchor does not require an extra read, because the content is already in context; the filesystem lookup is the defect, not the pointer.
|
|
23
|
+
|
|
24
|
+
### Skill-local pointers are required
|
|
25
|
+
|
|
26
|
+
Several skill bodies (`collaborate`, `design-and-plan`, and `refine-plan` among them) contain a pointer to the option-format rules at their question-asking steps, duplicating the universal rule in `AGENTS.md`. That duplication is intentional, and a DRY-driven refactor must not strip it. The rule and its rationale are stated in the repo-local `codeassembly-repo-conventions` rulebook (`.agents/content/guidance/rulebooks/`), under "Skill-local reinforcement".
|
|
27
|
+
|
|
28
|
+
## Directive grammar
|
|
29
|
+
|
|
30
|
+
Three include shapes are recognized. Each must occupy a full line, with optional leading and trailing whitespace. That whitespace affects recognition alone; injected lines keep the partial's own indentation rather than the directive's, so a directive cannot appear inside a list item. Inline directives inside prose or code spans are not expanded.
|
|
31
|
+
|
|
32
|
+
| Shape | Syntax | Use |
|
|
33
|
+
| ------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
|
|
34
|
+
| Self-close | `<!-- include: path / -->` | Inline a partial without slot content (or use the partial's empty-slot defaults). |
|
|
35
|
+
| Open + close | `<!-- include: path -->` ... `<!-- /include -->` | Inline a partial and pass slot content into its `<!-- children -->` placeholder. |
|
|
36
|
+
| Children slot | `<!-- children -->` | Inside a partial: Marks where the caller's slot content is substituted. |
|
|
37
|
+
|
|
38
|
+
Self-close is matched before open so that a path with a trailing slash is read correctly as a self-close, not as an open directive whose path ends with a slash.
|
|
39
|
+
|
|
40
|
+
The `<!-- children -->` placeholder is a partial-side directive. It appears at most once per partial. If a partial does not have `<!-- children -->` and the caller provides slot content, the expander throws `slot-without-children`. If a partial has `<!-- children -->` and the caller does not provide any slot content (bare self-close, or empty open/close pair), the placeholder line is removed and surrounding lines join verbatim.
|
|
41
|
+
|
|
42
|
+
## Directive placement
|
|
43
|
+
|
|
44
|
+
If a host heading follows a directive and is deeper than the shallowest heading that the injection contributes, it renders as a subsection of the injected content rather than of the host body. Place every directive where the next host heading is at or above that level. The `codeassembly-content-specification` rulebook states the rule that an author follows, under "Injection-point placement"; this section explains the level computation behind it.
|
|
45
|
+
|
|
46
|
+
The deciding level is what the injection contributes, not a fixed `##`. A partial contributes its headings as authored, and `##` for any guidance hook that it declares, since hooks resolve after includes expand and so are filled inside the host. For example, `_partials/ticket-assessment.md` opens at `###`, and the `## Key principles` heading that follows its directive in `assess-ticket` is above that level. A hook declared by the host contributes `##` on its own, because a bound rulebook's title is demoted one level to fit.
|
|
47
|
+
|
|
48
|
+
Slot content is the caller's own text and contributes nothing here: A heading passed into a partial's `<!-- children -->` is authored in the host beside the section that follows it. Its nesting is already visible where it is written. `codeassembly validate` enforces the rule.
|
|
49
|
+
|
|
50
|
+
## Path resolution
|
|
51
|
+
|
|
52
|
+
Include paths are resolved relative to the source-tree directory of the file that contains the directive. The resolved target must remain inside `packages/guidance/content/` (lexical containment is checked, not symlink resolution). The expander throws `out-of-tree` for an out-of-tree reference.
|
|
53
|
+
|
|
54
|
+
A partial's own includes are resolved relative to that partial's directory, not the caller's. This means a deeply nested partial can include a sibling partial without knowing where its caller is.
|
|
55
|
+
|
|
56
|
+
### What breaks when a partial moves between host kinds
|
|
57
|
+
|
|
58
|
+
Two things that a partial may contain are resolved against the host that inlines it rather than against the partial, so neither survives a move between host kinds.
|
|
59
|
+
|
|
60
|
+
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; a rulebook's resolve against `guidance/rulebooks/<slug>.md` in content-root space. One authored target therefore names two different files, and a skill-shaped one resolves outside a rulebook's linkable roots and fails the run. Write the target as `{harness_home_dir}/...` inside inline code when a partial must refer to a file from both.
|
|
61
|
+
|
|
62
|
+
A partial that `guidance/shared/AGENTS.md` inlines does not contain any relative link at all. That file is inlined into each harness's guidance file at the harness home root, where a source-tree-relative target names nothing, so the template-variable form is the only one that resolves to a file from there. `codeassembly validate` scans the expanded body and reports a relative target that it finds.
|
|
63
|
+
|
|
64
|
+
A **`{rulebook:<slug>}` token** cannot serve both a skill body and a support entry under `skills/`. The deployed rulebook set is available only to a host that resolves a declaration, and a source's support entries deliver to every consumer of the source, whichever rulebooks that consumer declares. The token renders in the skill but breaks the support entry's delivery.
|
|
65
|
+
|
|
66
|
+
## Path references in installed content
|
|
67
|
+
|
|
68
|
+
Installable content is rewritten at install time. Author cross-references in one of three forms, depending on intent:
|
|
69
|
+
|
|
70
|
+
- **Runtime references**: Paths that the agent reads or executes at runtime. Use `[text](relative/path.md)` for a Markdown link, or `{harness_home_dir}/...` inside inline code or a command (e.g., `{harness_home_dir}/skills/_data/work-types.json`), the form that a partial inlined at several depths can use. Both name a file by its place in the content tree, and the pipeline resolves both to where that file is deployed: A target naming a skill deployed by the same run resolves where that run wrote it, a target in one of the owning source's support entries resolves into that source's namespace, `skills/_sources/<name>/`, and anything else resolves to the harness home. `sync --global` anchors the first two under the harness home, and bare `sync` under the project root. Every other `{harness_home_dir}` expands to the platform home (e.g., `~/.claude`), where `scripts/` deploys.
|
|
71
|
+
- **Source-tree citations**: Prose pointing the reader to the canonical implementation, like a doc reference. A bare `packages/guidance/content/...` path is acceptable in this case, but the file must be added to the allowlist in `packages/guidance/content/__tests__/content-path-conventions.unit.test.ts`.
|
|
72
|
+
- **Self-referential prose** about the source tree itself (e.g., this paragraph) is treated as a source-tree citation.
|
|
73
|
+
|
|
74
|
+
The `content-path-conventions` regression test flags any raw `packages/guidance/content/` string in installable Markdown outside the allowlist.
|
|
75
|
+
|
|
76
|
+
## Partial locations
|
|
77
|
+
|
|
78
|
+
Partials are stored in `_partials/` directories. The directory is recognized at any depth and is excluded from the install copy:
|
|
79
|
+
|
|
80
|
+
- `content/_partials/`: Cross-cutting partials shared across skills, subagents, and platform guidance.
|
|
81
|
+
- `content/skills/_partials/`: Partials shared across skills.
|
|
82
|
+
- `content/skills/{name}/_partials/`: Partials internal to a single skill.
|
|
83
|
+
|
|
84
|
+
The `_partials` directory itself never appears in installed output.
|
|
85
|
+
|
|
86
|
+
## Install pipeline
|
|
87
|
+
|
|
88
|
+
For each `.md` source file, the install pipeline performs, in order:
|
|
89
|
+
|
|
90
|
+
1. **Expand includes.** `expandIncludes(srcPath, contentDir)` resolves all directive shapes recursively and substitutes slot content.
|
|
91
|
+
2. **Merge frontmatter** (subagents only). Platform-specific frontmatter overrides are merged into the source's frontmatter from the `_data/{platform}.yaml` of the content root from which the subagent resolved. A source without an overlay does not contribute any overrides.
|
|
92
|
+
3. **Rewrite tool-name placeholders.** `rewriteToolNames(content, harnessId)` replaces each `{tool:NAME}` placeholder with what that platform calls the tool. An unmapped name is a fatal install error that names the source file and line. See [Tool-name placeholders](#tool-name-placeholders).
|
|
93
|
+
4. **Inject the provenance marker.** A `GENERATED FILE` comment is added at the top of the output, with a `Source:` link to the original file.
|
|
94
|
+
5. **Rewrite paths** (skills only, post-write). Bare-relative Markdown links are rewritten to absolute platform paths.
|
|
95
|
+
6. **Write the destination file.**
|
|
96
|
+
|
|
97
|
+
For subagents, all steps run on the in-memory merged string before write. For directory-form skills, step 3 runs on each value of the in-memory `expandedDirContents` map before `writeExpandedSkillDir` writes files to disk; step 5 (path rewriting) then runs as a second pass over the written tree. For flat-file skills, step 3 runs on `expandedFileContent` before `writeFile`.
|
|
98
|
+
|
|
99
|
+
Expansion runs before the dry-run gate, so missing partials, cycles, and out-of-tree references are reported even when the run would not write any files.
|
|
100
|
+
|
|
101
|
+
## Tool-name placeholders
|
|
102
|
+
|
|
103
|
+
Subagent and skill body text reference tools using the `{tool:NAME}` placeholder so that the same source can install for platforms that name their tools differently. `NAME` is the canonical (Claude) tool name (`AskUserQuestion`, `Bash`, `Edit`, `Glob`, `Grep`, `Read`, `Task`, `Write`). The install pipeline rewrites each placeholder to the platform's own name for that tool, which `codeassembly` keeps in its harness table rather than reading from content.
|
|
104
|
+
|
|
105
|
+
The canonical set is closed and identical across platforms: Every platform names every canonical tool, so a name that one platform maps is mapped by all of them. Introducing a new canonical name is a change to `codeassembly` itself and is delivered in a release; content cannot add one.
|
|
106
|
+
|
|
107
|
+
When a placeholder names a tool outside that set, the rewriter aborts install with a fatal error that names the source file and line. The rewriter does not pass any name through unchanged; every match must resolve through the table. This catches typos (e.g., `{tool:Reed}`) and out-of-date placeholders at install time rather than at agent runtime.
|
|
108
|
+
|
|
109
|
+
**Authoring guidance:**
|
|
110
|
+
|
|
111
|
+
- Use `{tool:NAME}` for body prose that names a tool *as a tool*, not for English verbs ("Read the file", "Write a paragraph", "Read project guidelines" are not migrated).
|
|
112
|
+
- Preserve surrounding context: `` `Write` `` becomes `` `{tool:Write}` ``; bare `Write` becomes `{tool:Write}`.
|
|
113
|
+
- Do **not** use placeholders in frontmatter `tools:` values. Frontmatter is replaced wholesale by the overlay merger; placeholders there would create two overlapping mechanisms.
|
|
114
|
+
- The placeholder mechanism is body-only, applied to subagent and skill `.md` files. Guidance files (`content/guidance/`) are not passed through the rewriter.
|
|
115
|
+
|
|
116
|
+
## Verbatim slot substitution
|
|
117
|
+
|
|
118
|
+
When a partial contains `<!-- children -->`, expansion removes that line and inserts the caller's slot lines verbatim: It does not trim leading or trailing lines, and it does not collapse blank lines. Partial authors control the spacing on their side; caller authors control the spacing on theirs.
|
|
119
|
+
|
|
120
|
+
A consequence: Avoid placing blank lines on both sides of a `<!-- children -->` boundary. If the partial has a blank line above `<!-- children -->` and the caller's slot content begins with a blank line, the result is two consecutive blank lines.
|
|
121
|
+
|
|
122
|
+
## Common patterns
|
|
123
|
+
|
|
124
|
+
### Bare self-close: No slot
|
|
125
|
+
|
|
126
|
+
Use when the partial does not have a `<!-- children -->` placeholder, or when the caller wants the partial's empty-slot rendering:
|
|
127
|
+
|
|
128
|
+
```
|
|
129
|
+
<!-- include: _partials/shared-prose.md / -->
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Open/close with slot content
|
|
133
|
+
|
|
134
|
+
Use when the partial has `<!-- children -->` and the caller wants to fill it:
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
<!-- include: _partials/with-slot.md -->
|
|
138
|
+
Caller-provided slot lines.
|
|
139
|
+
Multiple lines are allowed.
|
|
140
|
+
<!-- /include -->
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Empty open/close pair
|
|
144
|
+
|
|
145
|
+
Functionally equivalent to bare self-close. Useful when the surrounding text reads more naturally as an explicit empty pair:
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
<!-- include: _partials/with-slot.md -->
|
|
149
|
+
<!-- /include -->
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Forward-compatibility constraints
|
|
153
|
+
|
|
154
|
+
The grammar reserves additional tokens for future use. Partial authors must not emit them in source content:
|
|
155
|
+
|
|
156
|
+
- `<!-- slot: name -->`, `<!-- slot: name / -->`, `<!-- /slot -->`: Reserved for future named-slot support.
|
|
157
|
+
- `<!-- children -->`: The canonical default-slot placeholder. Use exactly this token; do not invent variants.
|
|
158
|
+
- `<!-- guidance-hook: name -->`: The guidance-hook directive, a separate mechanism with its own grammar. It occupies a full line, its name is kebab-case and letter-led, and a body may declare each hook once. It resolves after includes expand, so a hook declared by a partial is declared by each body that inlines it. A line that resembles the directive but does not match its shape, such as the plural `guidance-hooks:` or a token without a name, is rejected rather than deployed as a stray comment. Because a directive that nothing binds is removed line by line, a blank line separating two directives remains in the unbound render; a new directive goes on the line adjacent to the one that it joins. Keep the two grammars disjoint: A slot token never names a guidance hook, and a guidance-hook directive never takes an include parameter.
|
|
159
|
+
|
|
160
|
+
### Partial or guidance hook
|
|
161
|
+
|
|
162
|
+
Both put shared prose into a body, and they differ in who chooses the prose.
|
|
163
|
+
|
|
164
|
+
A **partial** resolves by path. The author writes `<!-- include: _partials/x.md / -->` and every consumer of the library gets that file, inlined at install time to byte-identical output. Use one for doctrine that the library asserts for everyone: comment discipline, the artifact conventions, anything whose content is not a matter of local taste.
|
|
165
|
+
|
|
166
|
+
A **guidance hook** resolves by binding. The author writes `<!-- guidance-hook: name -->` and leaves the slot empty; a `codeassembly.yaml` names which rulebooks fill it, per project or per machine. Use one when the right content differs by who is running (personal code-style preferences, a project's own glossary), which is exactly what a path fixed at authoring time cannot express.
|
|
167
|
+
|
|
168
|
+
A hook is filled only in a declared skill or subagent, the artifacts that a declaration covers. A directive in a rulebook body, a `skills/_data/` support entry, or a harness guidance file is always stripped, since none of them is rendered against a declaration. Declaring a hook is therefore safe anywhere; it simply does nothing where nothing can bind it. `packages/agents/docs/project-declaration.md` documents the binding syntax and the naming rules.
|
|
169
|
+
|
|
170
|
+
The expander rejects unrecognized parameters following `include:` with an `unrecognized-parameter` error. This stops a typo from being silently ignored.
|
|
171
|
+
|
|
172
|
+
## Frontmatter constraint
|
|
173
|
+
|
|
174
|
+
Partials must not contain YAML frontmatter (a leading `---` block). Subagent install merges frontmatter from a platform overlay file with frontmatter in the source `.md`; if a partial contained its own `---` block, the merge would conflict. The expander does not enforce this constraint at runtime; partial authors must avoid frontmatter explicitly.
|
|
175
|
+
|
|
176
|
+
## Errors
|
|
177
|
+
|
|
178
|
+
The expander reports structured errors for the following conditions. Each error includes the file path and line number of the offending directive (or, for slot-without-children, the caller's open-directive line).
|
|
179
|
+
|
|
180
|
+
| Reason | Cause |
|
|
181
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------- |
|
|
182
|
+
| `cycle` | A partial transitively includes itself. |
|
|
183
|
+
| `not-found` | The resolved path does not exist on disk. |
|
|
184
|
+
| `orphan-close` | A close directive does not have a matching open. |
|
|
185
|
+
| `out-of-tree` | The resolved path is outside `contentDir`. |
|
|
186
|
+
| `slot-without-children` | The caller provided slot content but the partial does not have a `<!-- children -->` placeholder. |
|
|
187
|
+
| `unclosed-open` | An open directive was never followed by a matching close. |
|
|
188
|
+
| `unrecognized-parameter` | A directive uses `include:` syntax but does not match any recognized shape. |
|
|
189
|
+
|
|
190
|
+
## Borrowed content
|
|
191
|
+
|
|
192
|
+
`plain-speech.md` takes the term "mannered prose" and its two example pairs ("a dial worth turning" for "a parameter worth varying", "this point earns its keep" for "this point still matters") from Anthropic's Fable 5.1 prompting documentation, under "Writing density": https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
## Code descriptions
|
|
2
|
+
|
|
3
|
+
- Every function, method, class, and component gets a brief description. One line is usually enough.
|
|
4
|
+
- Do not repeat information already provided by the signature (parameter names, types, return types). In languages with doc-tag conventions (`@param`, `@returns`, `:param`, `Args:`, etc.), omit them: The description alone is sufficient.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
## Style
|
|
2
|
+
|
|
3
|
+
- Code style should adhere to `.editorconfig`, if there is one.
|
|
4
|
+
- Order lists and collections logically (alphabetically unless there is a good reason to sort or group differently).
|
|
5
|
+
- Use long-form CLI options (`--force`, not `-f`) in generated commands and scripts.
|
|
6
|
+
- Structure code so that the primary logic comes first; place helper functions at the end.
|
|
7
|
+
- Name functions with a leading verb (`show_usage`, not `usage`; `build_payload`, not `payload`).
|