codeassembly-guidance 0.0.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +70 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +6 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +214 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +180 -0
- package/content/skills/_data/title-templates.md +632 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +85 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +148 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +71 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +317 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- package/schemas/work-types.v1.json +142 -0
package/README.md
CHANGED
|
@@ -1 +1,195 @@
|
|
|
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.2.0 (2026-10-23)
|
|
9
|
+
|
|
10
|
+
### 🎉 Features
|
|
11
|
+
|
|
12
|
+
- Replaces the list of ideas to adopt in the `comparison` artifact written by `prepare-prototype-brief` with an idea table that lists every distinctive idea of the round, those of rejected and losing prototypes included, with the prototypes that have it and the requirement that it answers. (#2027)
|
|
13
|
+
- Adds a step to `prepare-prototype-brief`, reached also from the verdict read-back of `index-prototypes`, which takes the developer through a keep, adapt, defer, or drop decision on each row of the idea table, accepts new ideas that the developer states while judging, and saves the result as a ticket-level `idea-decisions` artifact. (#2027)
|
|
14
|
+
- Requires, in the product-development stages of the `williamthorsen-workflow-preferences` rulebook, a decision on every prototype idea before the end vision, which cites the `idea-decisions` artifact, and a record of each decision in the design doc. (#2027)
|
|
15
|
+
- Adds a `number` to each `index-prototypes` manifest entry, assigned at a slug's first registration and kept by its later versions, and leads each index card title and the winner summary with it, as in "3. Catalog first". (#2030)
|
|
16
|
+
- Numbers a manifest written before this change in order of each slug's first registration when it is read, and writes those numbers to it at the next registration. (#2030)
|
|
17
|
+
- Updates `index-prototypes` and `prepare-prototype-brief` to name each prototype to the developer as `{number}. {title}` in reports, the comparison, the idea table, and the idea decisions, and to accept a bare number as a reference to a prototype, asking when no prototype has that number. (#2030)
|
|
18
|
+
- Adds the `ui-copy-conventions` rulebook, delivered as the `consult-ui-copy-conventions` skill, which sets rules for labels, buttons, helper text, errors, register, and case, and a copy budget for each page, and which defers to a project's own content guidelines where the two conflict. (#2032)
|
|
19
|
+
- Adds `ui-copy-conventions` to the `recommended` collection, and directs plans to name its copy rules and copy budget in the key decisions of any task that writes interface text or builds a page, a prototype, or a UI component. (#2032)
|
|
20
|
+
- Changes `prepare-prototype-brief` to forbid builders from quoting the brief into the page, to require the demo chrome inside an element marked `data-demo`, and to judge each prototype's product copy against `ui-copy-conventions`. (#2032)
|
|
21
|
+
- Adds the `copy-probe` command to the `index-prototypes` helper, which prints a function for the Playwright MCP's `browser_evaluate` that lists a page's strings of four or more words and skips everything inside `data-demo`. (#2032)
|
|
22
|
+
- Adds the `index-prototypes describe-set` command, which reads a set summary (`shared`, `changes`, `try`) from a JSON file into the manifest; the index page shows that summary below its title, with `try` as a numbered list. (#2034)
|
|
23
|
+
- Adds a repeatable `--note "<label>: <value>"` flag to `index-prototypes register`, which stores each note on the prototype's entry and shows the notes on its card as a definition list in the order given. (#2034)
|
|
24
|
+
- Directs the agent in the `index-prototypes` and `prepare-prototype-brief` skills to choose one list of note labels for the set, to collect a value for each label from every builder, and to write the set summary in a new "Describe the set" step each round. (#2034)
|
|
25
|
+
- Adds drafted titles to `groom-backlog`, which shows a replacement title from the `ticket-assessor` subagent in the digest, applies it with `gh issue edit --title`, and lists "Title" among the parts that the ticket comment reports as revised. (#2038)
|
|
26
|
+
- Adds the `project.maturity` (`hobby`, `early`, `production`), `project.sensitivity` (`low`, `personal`, `confidential`), and `project.audience` (`owner`, `team`, `public`) keys to `.agents/preferences.yaml`, which `derive-session-context` reports as `project_maturity`, `project_sensitivity`, and `project_audience`, or as `null` for a key that the project file does not declare. (#2044)
|
|
27
|
+
- Directs `design-and-plan` and `plan` to treat the declared project stage as the premise of every security, availability, and infrastructure decision, to add machinery beyond that stage only for a named asset or need, and to ask for each undeclared value and then declare it in the project's preferences file. (#2044)
|
|
28
|
+
- Adds the project's declared stage to the design-doc contents that the `williamthorsen-workflow-preferences` rulebook lists for a product's end vision. (#2044)
|
|
29
|
+
- Adds the `check-preferences.mjs` script, which validates a preferences file against the bundled schema, prints its findings as JSON, and exits 1 on an invalid value or a missing required key, reporting an unrecognized key as a warning that names the nearest known key. (#2044)
|
|
30
|
+
- Adds the `refine-prototype` skill, which applies the developer's commands to one prototype page with the development gates off, carries the round's kept and adapted ideas onto it, snapshots each accepted version into the ticket's prototype set, and records every accepted change in a `refinement-log` artifact that the end vision reads. (#2040)
|
|
31
|
+
- Gives each prototype version an id, `{number}.{version}`, that leads the index card and the first line of the page's `data-demo` band, with a `resolve-ids` command on the `index-prototypes` helper that resolves the ids before the prototypes are built and a `--number` flag on `register` that refuses a registration whose number disagrees with the manifest. (#2040)
|
|
32
|
+
- Adds the `assess-usability` skill, available on the Claude harness only, which dispatches a `usability-assessor` subagent for each of three to five lenses in turn and merges their reports into a `usability-findings` artifact that ranks the findings by effect and reach and that `triage-spike-findings` takes as input. (#2045)
|
|
33
|
+
- Adds the `triage-spike-findings` skill, which grades the confidence and value of every item that a findings artifact leaves undisposed, has the new `disposition-challenger` subagent argue against each grade, and then creates the `confidence:`- and `value:`-labelled child tickets under an umbrella ticket and posts every disposition on the triage ticket, on GitHub repositories that have both label families. (#2049)
|
|
34
|
+
- Adds a `--label` argument to `create-ticket`, which applies the given labels on GitHub in addition to the resolved scope and type labels and reports them as skipped on Jira. (#2049)
|
|
35
|
+
- Stops `create-ticket` from asking for confirmation of a relationship supplied through `--parent`, `--blocked-by`, or `--blocking`, and lists that relationship in the completion output. (#2049)
|
|
36
|
+
- Adds the `check-site --target <url-or-host>` subcommand to `manage-jira-ticket.mjs`, which prints `acli`'s active site and the ticket's site as JSON and, when they differ, exits non-zero and names the `acli jira auth switch` command that makes the ticket's site active. (#2052)
|
|
37
|
+
- Adds the `jira-clients` guidance hook to `update-jira-ticket`, through which a machine adds its own Jira client, with the sites that it reaches and its rank, to the clients that the Jira skills read and create through. (#2052)
|
|
38
|
+
- Adds an "External programs" section to the `testing-conventions` skill, which directs that code reach git or another external program through an adapter received as a dependency, that tests of that code pass a fake adapter, and that only the adapter's own test run the real program. (#2055)
|
|
39
|
+
- Adds an "External programs" section to the `typescript-testing-conventions` skill, with an example of an adapter type, a real adapter used as a parameter default, and a test that passes an object literal as the fake, and states a preference for that parameter over `vi.mock`. (#2055)
|
|
40
|
+
- Rewrites the description of the `testing-conventions` skill to name how a test reaches git and other external programs, and to direct agents to consult the skill before writing or changing a test. (#2055)
|
|
41
|
+
- Move kb's git calls behind an injectable adapter (#2077)
|
|
42
|
+
|
|
43
|
+
Adds an optional `git` parameter to `check`, `enumerateNotes`, and `enumerateNotePaths` in `@williamthorsen/kb/check`, which takes a `KbGit` adapter so that a consumer's tests can run these functions without a real git repository. The change also routes every git call inside kb through one such adapter and replaces the repositories that kb's tests built with a fake adapter.
|
|
44
|
+
|
|
45
|
+
- Changes the next-steps menus of the planning, implementation, and review skills to name each skill in the harness's own invocation syntax, such as `/refine-plan` on Claude Code and `!refine-plan` on Rovo, so that a user can paste an option line without retyping it. (#2084)
|
|
46
|
+
- Adds a "Where a test goes" section to the `testing-conventions` skill, which directs each case to the cheapest tier that can observe it, limits an expensive tier (one that spawns a process, starts a runtime, or builds a full fixture) to one smoke example per entry or verb, and requires a change to delete the higher-tier examples that its cheaper coverage supersedes and to justify each expensive-tier example that it adds. (#2086)
|
|
47
|
+
- Adds a "Test placement" section to the `review-criteria` skill, which classes as a Warning an added expensive-tier example that a cheaper tier could observe, and also a higher-tier suite that the change superseded but kept. (#2086)
|
|
48
|
+
- Changes the test criterion in `ticket-criteria-conventions` and `plan-template` to ask for coverage at the cheapest tier that observes the behavior, rather than for coverage by tests alone. (#2086)
|
|
49
|
+
- Changes the `accessibility-conventions` and `shared-data-conventions` rulebooks to `skill` delivery alone, so that they no longer appear in every session's guidance file and are reached through `consult-accessibility-conventions` and `consult-shared-data-conventions`, and adds an "Interfaces" criterion to `review-criteria` that points a review of colour tokens, text styles, pages, or UI components to `accessibility-conventions`. (#2087)
|
|
50
|
+
- Adds an "Always-loaded context" section to `review-criteria`, which classifies a change as a Warning when it makes a rulebook ambient or grows an `AGENTS.md`, a `CLAUDE.md`, or another file loaded at session start, unless nearly every session needs the content. (#2087)
|
|
51
|
+
- Updates `codeassembly-content-specification` to version 30, which states that `delivery` is required and that `ambient` fits only content that nearly every session needs. (#2087)
|
|
52
|
+
- Adds a rule to `prepare-prototype-brief` that directs the brief's author to describe an audience-facing view by what the audience sees, and adds a line to the brief check that has the author rewrite phrases such as "mystery" and "unknown to" without the withheld information. (#2089)
|
|
53
|
+
- Makes `create-gh-pr` assign each pull request that it creates to the authenticated `gh` user, record the applied assignee in the `pull-request` artifact, and report the assignee as skipped when GitHub does not apply it. (#2090)
|
|
54
|
+
- Adds setup rules to the `testing-conventions` skill that count a database engine as an expensive tier, call for the cheapest setup that fits the time budget, keep setup cost independent of the number of test files, and reject a raised hook timeout as a fix. (#2092)
|
|
55
|
+
- Adds a "Code that uses a database" section to the `testing-conventions` skill, which limits database tests to code whose subject is SQL, directs logic that only passes through SQL to a fake client or a mocked module boundary, and rules out a test per constraint. (#2092)
|
|
56
|
+
- Adds four Warnings to the `review-criteria` skill for database and setup defects in tests that the change adds, splits, or modifies, and changes the split that it proposes for a grown test file to share the file's expensive setup first. (#2092)
|
|
57
|
+
- Adds the `cli-conventions` rulebook, delivered as the `consult-cli-conventions` skill, which states that a CLI printing a doc as a help topic renders a link to another topic as the `<bin> help <topic>` command, renders any other link as its absolute URL, and accepts the doc's file stem as a name for the topic. (#2093)
|
|
58
|
+
- Adds `cli-conventions` to the `recommended` collection, so that a project declaring that collection receives the rulebook. (#2093)
|
|
59
|
+
- Adds `--repo OWNER/REPO` to `/create-ticket`, which files the ticket in that GitHub repository and resolves its title format, reference prefix, scope, and labels from the configuration on that repository's default branch. (#2094)
|
|
60
|
+
- Adds `--project-root <dir>` to `describe-change render-titles` and `resolve-labels`, which then read `.agents/preferences.yaml` and `.meta/label-map.json` from that directory in place of the invoking repository's root. (#2094)
|
|
61
|
+
- Makes `describe-change resolve-labels` warn on stderr about each type or scope that a configured label map does not define, where it previously omitted the label without a message. (#2094)
|
|
62
|
+
- Adds a `medium` input to `assess-usability`. When set to `cli`, each `usability-assessor` lens runs the built binary in its own scratch git repository and saves text transcripts as evidence, and the styling-and-access lens is replaced by an output-and-access lens that checks `NO_COLOR`, piped output, 80-column width, and help and error text. (#2095)
|
|
63
|
+
- Orders the `ticket` items of `triage-spike-findings` by value, then confidence, with record order breaking ties, when the skill creates the child tickets and when it lists them in the checkpoint table, the dispositions comment, and the report, so that the children's issue numbers follow that order. (#2096)
|
|
64
|
+
- Adds a rule to the "Technical recommendations" guidance that directs an agent to name the best-practice solutions to a design problem and the conditions under which each one fits before it weighs options, to label an option that departs from all of them as non-standard with the reason that none fits, and to recommend revising an existing API rather than an addition that works around its contract. (#2098)
|
|
65
|
+
- Includes the "Technical recommendations" guidance in the `ticket-assessor` subagent, which validates a ticket's proposed approach. (#2098)
|
|
66
|
+
- Extends the `cli-conventions` rulebook from help topics to the whole interface of a command-line tool in any language, adding rules for `--help` on every command and subcommand, an exit-code table, error messages that name the fix, and step and outcome reports for commands that change state. (#2099)
|
|
67
|
+
- Reduces the `shell-conventions` rulebook to how a bash script implements the `cli-conventions` rules, and changes its `show_usage` template to write requested help to stdout and to exit 2 on an unknown command. (#2099)
|
|
68
|
+
- Adds a "DOM environment" section to the `typescript-testing-conventions` skill, which directs a TypeScript test that renders into a DOM to run under happy-dom and allows jsdom only at an opt-in whose comment names the behavior that happy-dom lacks. (#2101)
|
|
69
|
+
- Adds the `codeassembly-validate-preferences` bin to `codeassembly-guidance`, which validates each named preferences file against the bundled schema without network access, reports a missing or unparsable file as an error, prints text or one JSON object per file under `--json`, and treats warnings such as an unrecognized key as failures under `--strict`. (#2103)
|
|
70
|
+
- Renames the deployed `check-preferences.mjs` helper to `validate-preferences.mjs` and gives it the bin's behavior: several files per run, text output by default, and the `--json`, `--strict`, and `--help` options. (#2103)
|
|
71
|
+
- Directs the agent, in the `williamthorsen-collaboration-preferences` rulebook and the option-format rule, to start each line that states a decision awaiting the checkpoint with ⏳, in a turn's narrative as well as in the plan and spike templates' `## Decisions taken` section, where the marker replaces the `(provisional)` parenthetical. (#2104)
|
|
72
|
+
- Extends `triage-spike-findings` to have the agent decide the blockers of each ticket that it creates, create every blocker before the tickets that it blocks, link them through `create-ticket --blocked-by`, and list them in a "Blocked by" column of the dispositions comment. (#2105)
|
|
73
|
+
- Adds to `williamthorsen-ticketing-preferences` a rule to record a blocker whenever there is some probability that one ticket affects another and should land first, including when one ticket's design takes another ticket's outcome as an input. (#2105)
|
|
74
|
+
- Adds a directive to the "Handoffs" section of `williamthorsen-collaboration-preferences` that tells the agent to hand over a check of more than one command as one paste-ready script, which cleans up after itself and prints only the facts that the agent needs, and to confirm which machine its commands run on, such as by comparing `hostname`, before it runs or hands over a check of a GUI application. (#2106)
|
|
75
|
+
- Adds to `accessibility-conventions` the states that every clickable element shows (a pointer cursor, a hover change, and a focus indicator that meets 3:1 non-text contrast), and requires a browser check of each change to a visible component, with a report that the check did not run when a browser is unavailable. (#2109)
|
|
76
|
+
- Directs `implement-plan` to run that browser check for any change to a visible component, whether or not the plan lists it, and to report what the check found, and adds the interaction states and the check to the plan template's interface guidance. (#2109)
|
|
77
|
+
- Directs `review-criteria` to check each new or changed interactive element in a browser rather than by reading the diff alone, and adds the outcome of that check to the technical assessment in both `review-branch` report templates. (#2109)
|
|
78
|
+
- Makes `design-and-plan`, `plan`, and `refine-plan` report each open blocker of the resolved GitHub or Jira ticket by reference and title, and then continue. (#2113)
|
|
79
|
+
- Makes `implement-plan` ask the user to confirm before it starts the first task when the governing ticket has an open blocker. (#2113)
|
|
80
|
+
- Extends the blocker check to a ticket artifact, which the skills check against the remote ticket named by its `ticket_ref` frontmatter. (#2113)
|
|
81
|
+
- Lets `refine-plan` resolve a Jira ticket by URL or key through the Jira clients that the ticket source resolution ranks, where it previously fetched a Jira URL as a web page. (#2113)
|
|
82
|
+
- Adds a rule to `williamthorsen-tooling-preferences` that directs an agent to log into a local instance of the app under work without asking the developer, and to set a development credential in an untracked local config file when the app needs one, which the rulebook does not count as minting a credential. (#2115)
|
|
83
|
+
- Limits the login that the handoff ladder in `williamthorsen-collaboration-preferences` names among the resources that an agent asks the developer to supply to a login to a remote service, which excludes an app's local development login. (#2115)
|
|
84
|
+
- Adds a step to `design-and-plan`, `plan`, `refine-plan`, and `implement-plan` that checks the branch against the remote's default branch before the work starts, fast-forwarding a branch that lacks commits and uncommitted changes of its own and otherwise listing the gained commits and asking whether to bring them in. (#2119)
|
|
85
|
+
- Adds the `check-branch-currency.mjs` script, which fetches the remote's default branch and reports as JSON how far the checked-out branch is behind and ahead of it, whether its tree is clean, and which gained commits touch the paths passed with `--path`. (#2119)
|
|
86
|
+
- Adds an "Authorship" section to the shared `AGENTS.md`, which states that a creator, reporter, or author field shows the account that made an item rather than who wrote it, and forbids inferring from that field that the developer wrote the item. (#2120)
|
|
87
|
+
- Changes `ticket-evaluation.md` to tell the agent to treat a ticket's content as unsourced, whichever account created the ticket, until the agent traces the content to a source. (#2120)
|
|
88
|
+
- Adds a "Subcommand names" section to the `cli-conventions` rulebook, which requires a subcommand that acts to name its action and its object, prescribes a flat verb-object name such as `show-instance-page` while the object has one action and a noun group such as `instance-page show` once it has several, and rejects an existing name that breaks these rules as precedent. (#2121)
|
|
89
|
+
- Makes `kb-curate` report `missing-destination` when `--kb` is absent and no `.kb/` is discoverable, and `no-default` when `--kb @default` is given without a configured `default_kb`, where both cases previously returned `no-kb-resolvable`. (#2122)
|
|
90
|
+
- Makes `kb-edit` report a note outside any discoverable `.kb/` as `missing-destination` instead of `no-kb-resolvable`, the code that `kb-add` uses for the same condition. (#2122)
|
|
91
|
+
- Rewrites the `.editorconfig` bullet in the shared "Style" guidance to direct agents to follow `.editorconfig` and to fill new comments to the `max_line_length` that it sets. (#2123)
|
|
92
|
+
- Adds rules to `cli-conventions`, each with an example, on when a behavior is a subcommand rather than an option, standard option names such as `--config`, `--dry-run`, and `--write`, the order in which settings resolve, which commands write by default, `--json` output, color, error messages that suggest the nearest valid name and never take a secret as an argument, and keeping a command's logic apart from its presentation. (#2134)
|
|
93
|
+
- Changes the exit code that `cli-conventions` assigns to a usage error, such as bad input or an unknown command or option, from 1 to 2, and adds exit code 1 for a check that ran and found problems. (#2134)
|
|
94
|
+
- Changes the default exit code of the `show_usage` template in `shell-conventions` from 1 to 2, so that a bare `show_usage` call covers every usage error, including an unknown command. (#2134)
|
|
95
|
+
- Makes `select-lede-exemplars.mjs` act on the breaking marker, which it previously discarded: An unmarked request no longer returns a breaking record, and a request marked by a `!` on `--type` returns breaking records before non-breaking ones within each widening step. (#2136)
|
|
96
|
+
- Adds a `--breaking` flag to `select-lede-exemplars.mjs`, which marks a `--type` or `--tier` request as breaking, and adds a `breaking` field to the JSON output, which reports whether the request was marked. (#2136)
|
|
97
|
+
- Changes the `entry-drafter` subagent to request exemplars once per pair of work type and breaking marker, passing `--breaking` for a breaking entry, rather than once per work type. (#2136)
|
|
98
|
+
- Defines the members of the `triage` collection with `'@unclaimed'`, so that `codeassembly` deploys a newly added library artifact through `triage` until the artifact is promoted to another collection or declares `standalone:`. (#2137)
|
|
99
|
+
- Adds the `overused-word` rule to the `revise-prose` sweep, which reports one candidate per sentence that contains a word from the plain-speech calibration's "Words to look for" list or an inflection of one, lists the matched words, and leaves `prose-reviser` to repair the site or reject a use in a sense that the list keeps. (#2139)
|
|
100
|
+
- Adds the `check-prose.mjs` script, which runs every `revise-prose` detector over one Markdown file at any path without reading or writing the sweep record, and exits 1 when it reports candidates and 2 when it cannot read the file. (#2141)
|
|
101
|
+
- Adds a writing-rules check to step 6 of `summarize-change`, which runs `check-prose.mjs` over the lede, each entry's `text` and `migration`, and the "Why" section, and directs the session to redispatch the `entry-drafter` with the new `writing-rule` rejection code for a confirmed violation in a drafted passage. (#2141)
|
|
102
|
+
- Extends `revise-comments` to add a missing description to each function, method, class, and component, test helpers included, and to rewrite a description that misstates its code, with an instruction to ask the user first when the code rather than the description could be wrong. (#2146)
|
|
103
|
+
- Adds a "Test data" section to the `testing-conventions` skill, which requires each test to use the smallest data that proves its behavior and requires code that reads data from a module-level singleton to take it as a parameter or from a context whose default is the real value. (#2167)
|
|
104
|
+
- Extends the "Fix the design, not the timeout" rule in `testing-conventions` from a hook's timeout to a test's and a tier's timeout, set in a test or in config, and permits a raise only when smaller data, injection, and shared setup do not apply and the plan or the pull-request description states why. (#2167)
|
|
105
|
+
- Adds a Warning to `review-criteria` for a raised hook, test, or tier timeout, which a stated reason does not exempt, and a Warning for a test that renders or builds production-scale data, replacing the narrower "A raised hook timeout" item. (#2167)
|
|
106
|
+
|
|
107
|
+
### 🐛 Bug fixes
|
|
108
|
+
|
|
109
|
+
- Fixes the issue that `summarize-change` reported a branch's own steps and a ticket's backstory as what the change did, by having the `entry-drafter` subagent and the summary's audit accept only the diff against the default branch as evidence of what changed. (#2029)
|
|
110
|
+
- Fixes the issue that the `## Why` section of a `summarize-change` summary retold how the need for a change arose, by defining that section as the purpose that the change serves. (#2029)
|
|
111
|
+
- Fixes the issue that `entry-drafter` wrote where code or values were copied from, or why the work is split across pull requests, into the lede and the entries, including when a ticket's `## Problem` section stated it. (#2031)
|
|
112
|
+
- Fixes the issue that `summarize-change` accepted how the work is staged across pull requests as the purpose stated in a change summary's `## Why` section. (#2031)
|
|
113
|
+
- Fixes the issue that `groom-backlog collect` selected a ticket again when its only update was the decision that the sweep itself had applied, because GitHub records that update a moment after the sweep's comment. (#2038)
|
|
114
|
+
- Fixes the issue that `create-ticket` and `design-and-plan`'s Jira write did not direct the agent to flatten task-list syntax before submitting through a Markdown or HTML Jira client, which Jira stores as bullets reading `\[ \]`, on any deployment without `update-jira-ticket`. (#2050)
|
|
115
|
+
- Fixes the issue that `manage-jira-ticket.mjs create` created a Jira work item on `acli`'s active site when that site differed from the host of `ticket.base_url`, and makes it exit with the fallback `wrong-site` or `site-unreadable` without writing to Jira, reading `ticket.base_url` from the repository's preferences or the global file. (#2052)
|
|
116
|
+
- Fixes the issue that ticket resolution, `update-jira-ticket`, and `create-ticket` reported a Jira ticket on another site as missing, by directing each to run `manage-jira-ticket.mjs check-site` before calling `acli` and to report the wrong site and the `acli jira auth switch` command instead. (#2052)
|
|
117
|
+
- Fixes the issue that the `live-worktree-policy` rulebook named the removed `list-repos --tag live` command for listing the repos tagged `live`, and replaces it with `thor-repo list --tag live`. (#2053)
|
|
118
|
+
- Fixes the issue that a `summarize-change` redispatch did not send `entry-drafter` the type corrected by the audit, which left the drafter to rewrite the entry in the form of the old type. (#2058)
|
|
119
|
+
- Fixes the issue that the artifact guidance never stated what the artifact directory is for, by stating that it is the developer's audit trail rather than a source of truth, directing durable instructions to the repository or to a skill or rulebook, and telling the agent to verify what a search of artifacts returns against the repository, the tickets, and the pull requests. (#2070)
|
|
120
|
+
- Fixes the issue that `williamthorsen-workflow-preferences` did not say that the branch and worktree for a ticket's work are settled, which left agents asking the developer which one to use. (#2082)
|
|
121
|
+
- Fixes the issue that `design-and-plan` ended a session that split a ticket without a launch prompt for each resulting ticket, and that its `Next action` menu could offer to implement an umbrella's child in the umbrella's worktree. (#2083)
|
|
122
|
+
- Fixes the issue that the `triage-spike-findings` helper's `check-labels` command crashed with "e is not a function" instead of running `gh label list`, which stopped the skill before triage began. (#2085)
|
|
123
|
+
- Fixes the issue that `williamthorsen-collaboration-preferences` and the `action-items` and `option-format` partials stated many directives in the indicative, which hid whether the agent was to act, by restating them as imperatives addressed to the agent. (#2106)
|
|
124
|
+
- Documents in the `kb-add` skill the `readonly-kb` error code, which its helper already returned, and tells the agent to have the user choose a writable KB. (#2122)
|
|
125
|
+
- Fixes the issue that the rulebooks, skills, subagents, and partials in `codeassembly-guidance` contained sentences that the library's own current writing rules flag, such as figurative verbs, "no" used as a determiner, and reduced object relatives, and keeps each rulebook's `version` because the repairs do not change what it asks. (#2130)
|
|
126
|
+
- Fixes the issue that messages printed by `describe-change`, `index-prototypes`, `resolve-review-run`, `revise-prose`, and `triage-spike-findings` broke the writing rules, for example by saying `no manifest in` a directory rather than that the directory does not contain a manifest, and keeps each message's error code. (#2132)
|
|
127
|
+
- Fixes the issue that the artifact conventions told agents to run `export-ai-artifacts.sh`, which has been deleted, and called a git-ignored `base_dir` the default when the documented default is `~/ai-artifacts`. (#2135)
|
|
128
|
+
- Fixes the issue that `revise-prose` reported a file as swept after its prose was edited, by recording a hash of each file's extracted prose in `.agents/revise-prose.yaml` and reporting the file as unswept when the current hash differs. (#2143)
|
|
129
|
+
- Fixes the issue that the leader check in the option-format contract and the `williamthorsen-collaboration-preferences` rulebook did not cover gated decisions, and adds a first step that searches each alternative for a disqualifying cost, including one that follows from the work's constraints and acceptance criteria. (#2145)
|
|
130
|
+
|
|
131
|
+
### ⚡ Performance
|
|
132
|
+
|
|
133
|
+
- Shortens the `index-prototypes` skill by 675 bytes, cutting explanations that a neighboring sentence restated, and leaves its behavior unchanged. (#2040)
|
|
134
|
+
<!-- /section:release-notes -->
|
|
135
|
+
|
|
136
|
+
## Using the library
|
|
137
|
+
|
|
138
|
+
A declaration names the library as a source and selects artifacts from it, usually through a collection. For the home harness directories, clone the repository and declare its content directory in `~/.agents/codeassembly.yaml`:
|
|
139
|
+
|
|
140
|
+
```yaml
|
|
141
|
+
sources:
|
|
142
|
+
- name: codeassembly-guidance
|
|
143
|
+
path: ~/repos/codeassembly/packages/guidance/content
|
|
144
|
+
collections:
|
|
145
|
+
use:
|
|
146
|
+
- recommended
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
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.
|
|
150
|
+
|
|
151
|
+
## What the content contains
|
|
152
|
+
|
|
153
|
+
`content/` is a content root, laid out as the `codeassembly` tool expects:
|
|
154
|
+
|
|
155
|
+
| Directory | Contains |
|
|
156
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
157
|
+
| `collections/` | Named sets of artifacts: `recommended` is vetted and generally applicable, and `triage` is not yet examined |
|
|
158
|
+
| `guidance/` | Rulebooks, and the harness guidance templates that `install` deploys |
|
|
159
|
+
| `skills/` | Skills, and the support files under `skills/_data/` that they read at runtime |
|
|
160
|
+
| `subagents/` | Subagent definitions |
|
|
161
|
+
| `scripts/` | Shell scripts and helper bundles that `install` deploys into each harness's `scripts/` directory |
|
|
162
|
+
| `_partials/` | Text that the expander inlines into several artifacts at deploy time |
|
|
163
|
+
|
|
164
|
+
## Adding or changing content
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
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.
|
|
169
|
+
|
|
170
|
+
The package's `check` runs the tests, then `codeassembly validate` and `codeassembly bundle-helpers --check`, which fail on content that would be deployed to a consumer broken and on a bundle that is stale.
|
|
171
|
+
|
|
172
|
+
## Preferences
|
|
173
|
+
|
|
174
|
+
Agent behavior is configured through `.agents/preferences.yaml` files. The resolution cascade is:
|
|
175
|
+
|
|
176
|
+
1. **Project**: `.agents/preferences.yaml` in the repository root (committed, shared with team)
|
|
177
|
+
2. **Global**: `~/.agents/preferences.yaml` in the user's home directory (personal defaults)
|
|
178
|
+
3. **Default**: built-in fallback (documented per key in [Preferences](docs/preferences.md))
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
The package publishes a JSON Schema for the file; [Schemas](docs/schemas.md) gives its identifier and versioning. To validate preferences files in a repository's own checks, install this package and run its bin on them; [Validation](docs/preferences.md#validation) states its options and rules.
|
|
183
|
+
|
|
184
|
+
```sh
|
|
185
|
+
codeassembly-validate-preferences --strict .agents/preferences.yaml
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Helper reference
|
|
189
|
+
|
|
190
|
+
- [Prose sweep helper](docs/revise-prose-helper.md): the sweep that the `revise-prose` skill runs.
|
|
191
|
+
- [Backlog sweep helper](docs/groom-backlog-helper.md): the helper that the `groom-backlog` skill runs.
|
|
192
|
+
- [Next-ticket helper](docs/pull-from-backlog-helper.md): the helper that the `pull-from-backlog` skill runs.
|
|
193
|
+
- [Prototype index helper](docs/index-prototypes-helper.md): the helper that the `index-prototypes` skill runs.
|
|
194
|
+
- [Guidance streamlining helper](docs/streamline-guidance-helper.md): the helper that the `streamline-guidance` skill runs.
|
|
195
|
+
- [Findings triage helper](docs/triage-spike-findings-helper.md): the helper that the `triage-spike-findings` skill runs.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// Runs the bundled validate-preferences helper. The bundle is self-contained, so the package doesn't need any runtime
|
|
4
|
+
// dependencies, and its own entry guard stays false here because `process.argv[1]` names this file.
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
import process from 'node:process';
|
|
7
|
+
|
|
8
|
+
import { runValidatePreferences } from '../content/scripts/validate-preferences.mjs';
|
|
9
|
+
|
|
10
|
+
const programName = path.basename(process.argv[1] ?? 'codeassembly-validate-preferences', '.js');
|
|
11
|
+
|
|
12
|
+
try {
|
|
13
|
+
process.exitCode = await runValidatePreferences(process.argv.slice(2), process.cwd(), programName);
|
|
14
|
+
} catch (error) {
|
|
15
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
16
|
+
process.stderr.write(`${programName}: ${message}\n`);
|
|
17
|
+
process.exitCode = 1;
|
|
18
|
+
}
|
|
@@ -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 are delivered to every consumer of the source, whichever rulebooks that consumer declares. The token renders in the skill but breaks the support entry's delivery.
|
|
65
|
+
|
|
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/` is deployed.
|
|
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
|
+
- Follow `.editorconfig`, and fill new comments to its `max_line_length`.
|
|
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`).
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
## Comment discipline
|
|
2
|
+
|
|
3
|
+
These rules apply to every comment that you write **into source**: writing new code, revising it, editing after a review, or **proposing** replacement comment text inside a review finding. A comment drafted for someone else's file is a source comment, and the same audit applies to it.
|
|
4
|
+
|
|
5
|
+
The reader is an engineer six months from now who does not have the transcript, the session, or any memory of the change. Write for that reader.
|
|
6
|
+
|
|
7
|
+
### The baseline
|
|
8
|
+
|
|
9
|
+
Every function, method, class, and component **must** have a description. One line is often enough. Exceed that length only when a reader would be substantially helped by a longer explanation (and don't include anything readily apparent from a quick glance at the code). If in doubt, be terse.
|
|
10
|
+
|
|
11
|
+
The description of a function or method describes what it **does** and leads with a verb; any other opening is nonstandard and should not be emulated. The verb's mood is a project preference and is not set here.
|
|
12
|
+
|
|
13
|
+
The description of a class or component describes what it **is**.
|
|
14
|
+
|
|
15
|
+
Add descriptions of constants only if the description helps a reader understand the code. Constants on which the code's correctness depends are good candidates for description. Most other constants are not; rely on good variable names instead. Do not describe an interface or type unless its purpose is nonobvious.
|
|
16
|
+
|
|
17
|
+
### Four tests
|
|
18
|
+
|
|
19
|
+
Apply all four to every comment that you write or keep. A comment that fails one is cut or rewritten, not softened. Comments are code: read, maintained, and trusted. Each one must justify its place.
|
|
20
|
+
|
|
21
|
+
**1. The stranger test: Would this interest only someone who watched the change happen?** Then cut it.
|
|
22
|
+
|
|
23
|
+
Tells: _rather than_, _instead of_, _deliberately_, _used to_, _previously_, _replaces_, _we discussed_, _as agreed_, _see PR #N_, _added by TICKET-123_, _matches the X precedent_, _future readers should note_. So is any defense of the edit, any counterfactual whose other branch was never possible, and any narration of how or where the code is run.
|
|
24
|
+
|
|
25
|
+
State the code as it **is**, in the present tense; never as it was, as it might have been, or as it is not.
|
|
26
|
+
|
|
27
|
+
**2. The deletion test: Would a reader lose anything if the comment were gone?** Then cut it.
|
|
28
|
+
|
|
29
|
+
A comment tells the reader nothing if it paraphrases the line below it, restates the test's own name, or re-describes what a well-named function that it calls already documents. Inline comments answer _why_, never _what_. One line by default; exceed it only when a genuinely multi-part constraint will not compress.
|
|
30
|
+
|
|
31
|
+
**3. The one-location test: Is this fact already documented where it belongs?** Then cut it.
|
|
32
|
+
|
|
33
|
+
The library's behavior belongs in the library's docs. A helper's contract belongs on the helper. A consumer's name belongs nowhere near the shared code that it consumes. An invariant belongs in a type or an assertion, not in prose about a case that cannot happen.
|
|
34
|
+
|
|
35
|
+
**4. The derivation test: Do the listed cases follow from one rule?** Then state the rule.
|
|
36
|
+
|
|
37
|
+
A comment that enumerates the cases below it copies each case's own description, and the copy drifts: The enumeration keeps a name that the code has since renamed, or it places one case on both sides of a distinction. State the invariant that generates the cases, and let each case's own description state its specifics. An exception is worth naming once, beside the rule.
|
|
38
|
+
|
|
39
|
+
Tells: The same name appearing in two of the comment's lists, a run of backticked member names already documented at their own declarations below, and a list whose length tracks the number of members or branches below it.
|
|
40
|
+
|
|
41
|
+
### Carve-outs
|
|
42
|
+
|
|
43
|
+
These pass the tests. They are permissions, not requirements.
|
|
44
|
+
|
|
45
|
+
- **Test comments**: Non-obvious setup not conveyed by the test name; an indirect assertion, naming the reason for the indirection; the rationale for a skip.
|
|
46
|
+
- **`eslint-disable` rationales**: Why _this_ rule is suppressed _here_, and nothing more: `// eslint-disable-next-line no-explicit-any -- third-party Stripe type ships as any.` The carve-out applies to the comment, not to the suppression; whether to suppress at all is an `anti-patterns` question.
|
|
47
|
+
|
|
48
|
+
### Before and after
|
|
49
|
+
|
|
50
|
+
**Written for the reviewer**: Fails the stranger test. The comment defends the edit and describes what the code is _not_.
|
|
51
|
+
|
|
52
|
+
Before:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// `stdout` is deliberately absent: nothing here reads a captured stdout, so the type does not offer one.
|
|
56
|
+
// Returns null rather than a false pass.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
After:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
// `spawnSync` returns null for a stream redirected to a file descriptor; `runAttw` reads the output back from the file.
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Restating the call below it**: Fails the deletion test. The helper's own contract, re-narrated at the call site.
|
|
66
|
+
|
|
67
|
+
Before:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
// Builds the document title from the page title and employee name, dropping empties and falling back to the app name.
|
|
71
|
+
useDocumentTitle(buildDocumentTitle(EMPLOYEE_COMP_TITLE, data.employee.name));
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
After:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
// Overrides the route wrapper's static title once the name is available.
|
|
78
|
+
useDocumentTitle(buildDocumentTitle(EMPLOYEE_COMP_TITLE, data.employee.name));
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Proposed inside a review finding**: A suggested replacement comment is a source comment. This one restates the lookup already expressed by the code and copies an example ID out of the source.
|
|
82
|
+
|
|
83
|
+
Before:
|
|
84
|
+
|
|
85
|
+
> Looks up the employee by id (e.g. `EMP034`) through the `employees` search query, then maps each row to a `CompRow`.
|
|
86
|
+
|
|
87
|
+
After:
|
|
88
|
+
|
|
89
|
+
> todo: Update stale doc comment; the header still describes the lookup as "via the `employees` search query", which this change replaces.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
## Concision
|
|
2
|
+
|
|
3
|
+
Detail adds value up to a peak, then wastes the reader's attention and hides the signal. Compose tight from the start: Lead with the minimal skeleton and add a sentence only when it changes what the reader does. Never drop a decision, constraint, or actionable fact for brevity. If you find yourself trimming, you started too loose. Full principle: `{harness_home_dir}/skills/_data/concision.md`.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
## Diff audit
|
|
2
|
+
|
|
3
|
+
Before reporting what a change did, read the change back, and repair what you find before writing the report. The input is the hunks that you just wrote, not the change under review: This audit is bounded by your own edit, and one that grows past it becomes a second review pass.
|
|
4
|
+
|
|
5
|
+
- **Claims.** Every statement about the change is read from the diff, not from what you set out to do. A claim that something was left unchanged needs the same evidence as a claim that something changed, and it is the one most often written from memory.
|
|
6
|
+
- **Reach.** What the edit moved beyond its target: a parallel enumeration of the same list elsewhere, such as a README mirroring the edited source doc; sibling wording invalidated by a rename or re-framing, in a test title, a function header, or a neighboring doc; declaration ordering after an insertion; and adjacent behavior that a changed guard now covers or stops covering.
|
|
7
|
+
- **Class.** When the change corrects a defect, the site that you were pointed at is a sample of its class. Audit the other members before reporting, or the next reviewer finds the one that you left.
|
|
8
|
+
|
|
9
|
+
A green gate is not this audit: A suite that passes reports that nothing broke, not that the record which you are about to write is true.
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
## File access
|
|
2
|
+
|
|
3
|
+
- When given an exact file path, use the read tool directly. Do not search for the file first.
|
|
4
|
+
- If the read attempt returns "file does not exist", STOP and report the missing path; do not attempt to find the file by searching. A missing file at an exact path usually indicates a configuration or environment problem, not a wrong filename.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
## Don't test write operations against a live repo
|
|
2
|
+
|
|
3
|
+
Never exercise destructive or side-effecting operations against the user's working repo as verification. If a script's behavior requires running a command that mutates git state (`git tag`, `git commit`, `git push`, `git branch`, `git reset`, `git rebase`), file state, package state, or any other shared resource, exercise it in a disposable environment: a scratch directory (`mktemp -d "${TMPDIR:-/tmp}/probe.XXXXXX"`, since bare `mktemp -d` picks a path denied by the agent sandbox and then leaves the variable empty), a fresh `git init` with minimal fixtures, or a container.
|
|
4
|
+
|
|
5
|
+
Write absolute paths beneath that directory rather than changing into it and writing relative ones, unless the change of directory is chained to the creation succeeding, as `enter_tmpdir` is. `cd ""` returns 0, so a failed `mktemp` otherwise sends every later write into the working repo, which is the outcome that this rule exists to prevent.
|
|
6
|
+
|
|
7
|
+
Why it matters:
|
|
8
|
+
|
|
9
|
+
- Other sessions, file watchers, CI, release tooling, or IDE extensions on the user's machine can observe in-progress mutations, even if you intend to clean up after.
|
|
10
|
+
- Some projects treat new tags/commits as release signals. Once the artifact exists, downstream effects may fire before you can undo it; some release configurations are immutable (published tags produce permanent artifacts).
|
|
11
|
+
- "I can just clean up afterward" is not a substitute for never creating the artifact: Between create and cleanup, anything else on the machine can act on it.
|
|
12
|
+
|
|
13
|
+
Read-only exercises (`--dry-run`, help text, preview tables, `--list`, exit-code checks on pure-read commands) are safe in the working repo. Anything that writes, even "just for a second", is not.
|