codeassembly-guidance 0.0.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +70 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +6 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +214 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +180 -0
- package/content/skills/_data/title-templates.md +632 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +85 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +148 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +71 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +317 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
<!-- unit-version: plain-speech 9 -->
|
|
2
|
+
|
|
3
|
+
## Plain-speech sweep calibration
|
|
4
|
+
|
|
5
|
+
How one sweep applies the rule above, so that two sweepers give the same verdict on the same sentence. The rule decides what counts as plain; this section decides what a sweeper rewrites and what it leaves.
|
|
6
|
+
|
|
7
|
+
### Rewrite these
|
|
8
|
+
|
|
9
|
+
1. **A figurative verb when a plain one exists.** "detail taxes the reader" becomes "detail wastes the reader's attention". "the lede writes itself" becomes "the lede follows".
|
|
10
|
+
2. **A verb that does not fit its subject.** "the file carries a section" becomes "the file contains a section". "the block governs" becomes "the block takes precedence".
|
|
11
|
+
3. **A subject that does not perform the action, or a missing actor that the reader needs.** Rewrite when the sentence gives an action to something that does not perform it, or omits an actor that the reader must know and cannot recover from context. "Findings arrive as warnings" becomes "The function reports warnings": Findings arrive nowhere, and the original drops the function that produced them. In a skill body, "the parent rides the creation call" becomes "Set the parent in the creation call", because the agent sets it. "Refinement happens later, in bulk" becomes "A later pass refines them in bulk", because the point is which pass does it.
|
|
12
|
+
4. **A constructed figure when a literal phrase exists.** The rule's mannered-prose test, applied to a site. Only a figure is a candidate under this case, so plain technical vocabulary ("renders as a subsection", "inlines the partial", "the test fails") is not one. `gate`, `sweep`, `tier`, `lede`, `drift`, and `live` are figures on which this corpus has settled, and they stay.
|
|
13
|
+
|
|
14
|
+
Passive voice is not a defect on its own, and case 3 does not license converting it. Keep the passive when the actor is obvious or beside the point, when the patient is the paragraph's topic, or when it puts a long phrase at the end of the sentence.
|
|
15
|
+
|
|
16
|
+
### Leave these
|
|
17
|
+
|
|
18
|
+
- A term on the settled list in case 4 above. That list is closed: A term absent from it is a candidate. Neither its frequency, nor a neighboring file, nor its survival of an earlier sweep settles a term, and a sweeper citing one is reporting what the corpus does rather than what the rule requires. Extending the list is the author's decision, taken in this calibration, never a sweeper's.
|
|
19
|
+
- Any rewrite that would change what the text directs. When the plain wording would resolve an ambiguity that the original left open, leave the text and report the site as questionable.
|
|
20
|
+
|
|
21
|
+
### Worked example
|
|
22
|
+
|
|
23
|
+
A paragraph of this library's own guidance. Before:
|
|
24
|
+
|
|
25
|
+
> Behavioral rules that govern an agent's output -- such as the recommendation gradient and the action-items block -- are stated once in `AGENTS.md` and the shared `_data` specs. Where the boundary below calls for a restatement, it lands at the step that produces the output. An agent follows a rule more reliably when it sits beside the action it governs than when it must be fetched through a link.
|
|
26
|
+
|
|
27
|
+
After:
|
|
28
|
+
|
|
29
|
+
> Behavioral rules for an agent's output -- such as the recommendation gradient and the action-items block -- are stated once in `AGENTS.md` and the shared `_data` specs. When the boundary below requires a restatement, put it at the step that produces the output. An agent follows a rule more reliably when the rule appears next to the action that it governs than when the agent must follow a link to read it.
|
|
30
|
+
|
|
31
|
+
Three edits fall under cases 1 and 2, and two under case 3: "lands" gives the placement to the restatement rather than to the agent that places it, and "must be fetched" drops the agent from a sentence whose point is which party fetches. The first sentence's passive stands, because the paragraph's topic is the rules rather than the files that state them. Two edits do not belong to any case here: The "When" that replaces "Where" and the relativizer restored in "the action that it governs" come from the writing preferences, which a sweep applies in the same pass.
|
|
32
|
+
|
|
33
|
+
### Shapes to look for
|
|
34
|
+
|
|
35
|
+
Nine shapes recur in this corpus. Each is a search pattern rather than a rule: A sentence matching one is a candidate for the rule's tests, and a sentence matching none can still fail them.
|
|
36
|
+
|
|
37
|
+
1. **The cleft construction.** "Segment anchoring is what admits the branch form" becomes "Segment anchoring admits the branch form".
|
|
38
|
+
2. **Appositives stacked on the subject.** "The record, a file that one run writes and the next reads, is keyed on the phrase" becomes "The record is keyed on the phrase. One run writes it and the next reads it."
|
|
39
|
+
3. **"Not X, but Y" when Y alone says it.** "The default is not a report, but an applied repair" becomes "The default applies the repair".
|
|
40
|
+
4. **A nominalized gerund standing in for the actor.** "Five filters separate needing coverage from a particular test being worth writing" becomes "A change can need coverage even when no particular test is worth writing".
|
|
41
|
+
5. **A long subject with an embedded clause before its main verb.** "A change that needs coverage but finds no candidate clearing the bar ships without a test" becomes "A change is merged without a test when it needs coverage and no candidate clears the bar".
|
|
42
|
+
6. **Personification of an inanimate subject.** "The queue now reads as one set behind the blocking ticket" becomes "All four tickets are now marked as blocked by that ticket".
|
|
43
|
+
7. **An abstract noun standing in for a small concrete set.** "The suite covers the boundary cases" becomes "The suite covers an empty list, one entry, and a list past the budget".
|
|
44
|
+
8. **A concrete metaphor standing in for the literal abstraction.** The inverse of shape 7. "attrition rather than advocacy" becomes "tiring the developer rather than persuading them". "priced on your ledger" becomes "measured by you".
|
|
45
|
+
9. **"No" as a determiner.** "publishes no build output" becomes "doesn't publish any build output". "there's no Vercel CLI" becomes "the Vercel CLI isn't installed on this machine". "a skill that no task invokes" becomes "a skill that the plan does not invoke".
|
|
46
|
+
|
|
47
|
+
### The negative-quantifier rule
|
|
48
|
+
|
|
49
|
+
<!-- rule: negative-quantifier 2 -->
|
|
50
|
+
|
|
51
|
+
The helper reports every determiner "no" under this rule, as shape 9, in any position. Report a site of that shape under `negative-quantifier`, and every other site that breaks the plain-speech rule under `plain-speech`.
|
|
52
|
+
|
|
53
|
+
### Words to look for
|
|
54
|
+
|
|
55
|
+
<!-- rule: overused-word 1 -->
|
|
56
|
+
|
|
57
|
+
The helper reports every sentence that contains one of these words or an inflection of one under this rule. Report a site of a listed word under `overused-word`, and every other site that breaks the plain-speech rule under `plain-speech`.
|
|
58
|
+
|
|
59
|
+
Ten words recur in this corpus in uses for which a word naming the relation exists. Each is a search term rather than a rule, as a shape is: A match is a candidate for the rule's tests. When an entry names a sense that stays, a use in that sense is not a candidate.
|
|
60
|
+
|
|
61
|
+
- **carry**: "the change carries a flag". Instead: has, includes, declares, sets, states.
|
|
62
|
+
- **cost**: "a cost to you", "the token cost". Instead: the unit itself, as in "takes 12 ms", "one round trip", "spends the reader's attention".
|
|
63
|
+
- **hold**: "the caller holds the state". Instead: owns, stores, keeps. Stays when a promise or an invariant holds.
|
|
64
|
+
- **land**: "the fix lands in this PR". Instead: is merged, is committed.
|
|
65
|
+
- **reach**: "the change reaches the machine". Instead: is deployed to, is installed on, is available to, arrives in.
|
|
66
|
+
- **route**: "route the finding to PR-prep". Instead: send to, assign to, report to.
|
|
67
|
+
- **ship**: "ships without a test". Instead: is merged, is released.
|
|
68
|
+
- **sit**: "sits outside the body". Instead: is, is in, is next to.
|
|
69
|
+
- **stand**: "stands up a fixture". Instead: builds, creates. Stays as "stands in for", and when a claim or a passive stands.
|
|
70
|
+
- **surface**: "a review surfaces findings". Instead: reports, raises, reveals. Stays as the noun: a documentation surface.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
Speak plainly in practical documentation, in code comments, and in chat. The one carve-out is presentational text, the kind traditionally reviewed by a copy editor, such as marketing and website copy.
|
|
2
|
+
|
|
3
|
+
Write for a reader who does not share the author's first language, and test each sentence by asking whether that reader parses it on one pass. The test is about structure, not vocabulary: A domain term stays. Use the clearest verb: A file **contains** a section (not "bears" or "carries"), a function **returns** a result (not "the function answers with the result"), a tool **reports** its findings (not "the findings arrive").
|
|
4
|
+
|
|
5
|
+
A sentence can pass that test and still be **mannered prose**: a figure built for the sentence when a direct statement would do. "a dial worth turning" becomes "a parameter worth varying"; "this point earns its keep" becomes "this point still matters". A figure also adds connotations that the writer did not choose and cannot control. When a literal phrase is available, use it.
|
|
6
|
+
|
|
7
|
+
A verb that fits any subject and object does not state any relation between them. "The file carries a section", "the record carries a version", "the change carries a flag": One verb covers three relations and therefore names none of them. Write the verb that names this one: contains, declares, sets. Such a verb passes both tests above, because it is common rather than built for the sentence; therefore, test for it separately.
|
|
8
|
+
|
|
9
|
+
When a sentence makes data, a file, or a part of a document the subject of an action that an agent or a command performs, the reader cannot tell who acts: "the roots join the recorded ones", "the body reaches the approval gate". A passive that omits an actor that the reader needs hides the actor in the same way. Make the actor the subject. In instructions to an agent, the actor is usually the agent, and the sentence is an imperative: "Show the body to the user at the approval gate." In a document that describes code, the actor is the command or function that acts: "`record` adds the roots to the recorded ones"; an imperative there would give the action to the reader. A subject stays when it performs its verb, animate or not, or when its verb states a relation: A function returns a result, and a file contains a section.
|
|
10
|
+
|
|
11
|
+
"No" used as a determiner, in any position, leaves the reader unable to tell whether the thing does not exist or exists and fails the condition, and it hides where the absence was observed: "There's no Vercel CLI" was meant as "the Vercel CLI isn't installed on this machine" and read as "the Vercel CLI doesn't exist". As the subject of a relative clause, it also hides the actor and states a claim about every actor when the sentence is about one. Negate the verb, and name the scope in which the absence was observed: "the Vercel CLI isn't installed on this machine", "doesn't publish any build output", "a field not covered by any of the tests", "a condition that the user could not observe". Swapping in another negative quantifier is not a repair, because "a field that none of the tests names" keeps the construction. When existence is itself in question, state it separately: "the package doesn't have any tests". A site stays when it is a fixed idiom, such as "no longer", "no matter", or "no more than"; the pronoun "no one"; a hyphenated compound, such as "no-op"; a verbless label, heading, or table cell, which does not contain a verb to negate; or code, a quotation, or a marked exhibit.
|
|
12
|
+
|
|
13
|
+
This rule takes precedence over the register of the surrounding documents, this guidance included.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
**No hard line breaks.** Write each paragraph and each list item as a single line. Do not insert newlines to wrap at a column width. Every surface that renders this text wraps it, and GitHub turns a newline inside a paragraph into a literal line break, so hand-wrapped prose renders ragged.
|
|
2
|
+
|
|
3
|
+
This rule applies to text composed for a rendering surface: a commit body, a PR or issue body, a comment, a saved artifact. Inside the repository, the project's formatter decides instead; if the project has none, follow the convention already in the file.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<!-- Point-in-time record, read by capture-lede-decision to recover what was published. A revision that you publish gets a new record; leave this one unedited, and say nothing about leaving it. -->
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
## Reduced object relatives
|
|
2
|
+
|
|
3
|
+
<!-- rule: reduced-object-relative 1 -->
|
|
4
|
+
|
|
5
|
+
A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`. This is a house convention, not a claim about ordinary English, which permits the contact clause freely.
|
|
6
|
+
|
|
7
|
+
**Repairs, in preference order.** Choose per site; restored relativizers stacked across a passage read as a tic of their own.
|
|
8
|
+
|
|
9
|
+
1. **Reduce to a passive participle** if the actor is worth naming: "a dependency imported by every exported tier module".
|
|
10
|
+
2. **Restore the relativizer** if the passive reads worse: "the ticket that the branch name encodes".
|
|
11
|
+
3. **Recast** if neither fits: Promote the embedded clause to a main clause, or replace the relative with a prepositional phrase.
|
|
12
|
+
|
|
13
|
+
**A gap in a prepositional phrase takes its own order.** Pied-pipe the preposition first: "the level against which it is probed", preferred over the stranded "the level that it is probed against". If pied-piping reads stiffly, the stranded relativizer is the second choice and a recast the third. The passive participle is last here rather than first, since the actor is already inside the clause.
|
|
14
|
+
|
|
15
|
+
**A predicate-nominal gap takes the restored relativizer.** "the throwing mock that it is", never "the throwing mock it is". Neither of the other repairs applies to it: A copula does not have a preposition to pied-pipe or an actor to promote into a participle. If the restored relativizer reads stiffly, recast.
|
|
16
|
+
|
|
17
|
+
**A coordinated gap takes a doubled relative or one shared stranded relativizer.** When a direct-object gap coordinates with an oblique one, pied-piping cannot reach the first, which does not have a preposition to pipe. The parallel forms are "the error which it threw or with which it rejected" and "the error that it threw or rejected with".
|
|
18
|
+
|
|
19
|
+
**The shapes, ranked by cost.** The rank follows the embedded subject's form, since the reader must keep that form in mind until the verb appears. Each is an exhibit of the construction, not a model to copy.
|
|
20
|
+
|
|
21
|
+
1. **Quantified noun phrase** (worst): "a dependency every exported tier module imports". The reader absorbs a quantifier and a full noun phrase before any verb discharges the head.
|
|
22
|
+
2. **Definite noun phrase**: "the ticket the branch name encodes".
|
|
23
|
+
3. **Bare noun**: "an idiom developers recognize".
|
|
24
|
+
4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
|
|
25
|
+
|
|
26
|
+
**The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same breath; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does. This rule breaks the habit of reaching for a contact clause to dodge a passive that was never the target.
|
|
27
|
+
|
|
28
|
+
**Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). The anaphoric one-series heads a relative clause under the rule too, though it is not a lexical noun, because a relativizer restores to it: "one that the spy carries". Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. The boundary keys on head type and gap role. Neither a short embedded subject nor a tight word budget exempts anything.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
## Target file set
|
|
2
|
+
|
|
3
|
+
Before reading any file, resolve once the set of files that the run may edit, and never widen it afterwards.
|
|
4
|
+
|
|
5
|
+
**Expanding a path argument.** A path naming a file adds that file. A path naming a directory adds what git lists beneath it:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
git ls-files -- <path>
|
|
9
|
+
git ls-files --others --exclude-standard -- <path>
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The two forms together cover what git tracks plus what it would track, and both honor `.gitignore`, so `node_modules/`, `dist/`, and every other non-authored tree are excluded without any further configuration.
|
|
13
|
+
|
|
14
|
+
**What never enters the set.** Three kinds of file are excluded, each because an edit to it would be discarded or would rewrite a record:
|
|
15
|
+
|
|
16
|
+
- **Deployed output.** A file containing a `GENERATED FILE` or `<!-- codeassembly-` marker, and anything beneath a harness's own `skills/` or `scripts/` directory. Because the next sync overwrites it, the edit belongs to the source from which it was copied.
|
|
17
|
+
- **Saved artifacts.** Anything beneath the artifact base directory, typically `~/ai-artifacts/`.
|
|
18
|
+
- **Text that nobody here authored.** Vendored third-party sources, generated data, and test fixtures, whatever they contain.
|
|
19
|
+
|
|
20
|
+
<HARD-GATE>
|
|
21
|
+
Never edit a file outside the resolved set. Do not follow imports, expand to siblings, or touch a file merely reachable from one already in the set. Report a hit outside the set to the user alongside the summary; never repair it.
|
|
22
|
+
</HARD-GATE>
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
## Technical recommendations
|
|
2
|
+
|
|
3
|
+
- Default to current best practices. Before recommending an approach, verify it reflects the current state of the ecosystem, not a pattern that was standard two years ago.
|
|
4
|
+
- When unsure whether your knowledge is current, say so and look it up rather than presenting a possibly outdated approach as the answer.
|
|
5
|
+
- Before weighing options for a design problem, name the solutions that current best practice applies to that kind of problem and the conditions under which each one fits, then start from the one whose conditions hold. Label an option that departs from all of them as non-standard, and state why none of them fits. When the standard solution requires revising an existing API, recommend the revision rather than an addition that works around the current contract.
|
|
6
|
+
- Prefer CLI tools over web UI instructions. When a task can be done via a CLI command (e.g., `npm trust`, `gh repo edit`, `gh secret set`), recommend the command, not manual steps in a browser. When multiple commands need to be run, offer to write a script in the most suitable language (other things being equal, prefer bash and TypeScript), following the relevant coding conventions.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
Before saving a spec file, scan adjacent tests for shared-setup runs.
|
|
2
|
+
|
|
3
|
+
- **Parameterize** with `it.each` when the variation is small and the test body is structurally identical.
|
|
4
|
+
- **Extract a named helper** when the variation is bigger, when shared setup belongs behind a helper signature, or when assertion shapes differ per case.
|
|
5
|
+
- **Check the assertions, too.** When the rule is a count or predicate, specific-fixture-label assertions should not repeat per row. Assert specific data flow _once_ in a focused test; assert structurally for the rest.
|
|
6
|
+
|
|
7
|
+
Three or more `it` blocks with identical setup and a single varying input is the most common failure mode in interactive sessions. That material belongs behind a helper or a parameterized table, not in N copies of the same shape.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
A verdict is **baseline** when it does not indicate any concern or needed action:
|
|
2
|
+
|
|
3
|
+
| Dimension | Baseline verdict |
|
|
4
|
+
| ------------ | ---------------- |
|
|
5
|
+
| Drift | `none` |
|
|
6
|
+
| Relevance | `relevant` |
|
|
7
|
+
| Progress | `none` |
|
|
8
|
+
| Advisability | `advisable` |
|
|
9
|
+
|
|
10
|
+
An umbrella's `partial` progress is also baseline. An umbrella is a ticket that has open children and whose only unchecked criterion is "Every child is closed", so it is expected to be partly done until its last child closes. Any other unchecked criterion keeps `partial` progress a concern.
|
|
11
|
+
|
|
12
|
+
Complexity verdicts are purely informational and do not have a baseline.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
The assessment covers five dimensions: drift, relevance, progress, advisability, and complexity. Each produces a constrained verdict and supporting evidence.
|
|
2
|
+
|
|
3
|
+
### Investigation order
|
|
4
|
+
|
|
5
|
+
When assessing every dimension, investigate them in the order below. Advisability is investigated after progress, synthesizing the prior dimensions' context, and complexity is investigated last so that it benefits from context gathered during drift, relevance, progress, and advisability analysis. **Skip both advisability and complexity when progress is `complete`**; neither has value for finished work.
|
|
6
|
+
|
|
7
|
+
### Drift
|
|
8
|
+
|
|
9
|
+
Determine whether the ticket's factual assumptions still match the codebase.
|
|
10
|
+
|
|
11
|
+
1. Extract file paths, module names, API references, and structural assumptions from the ticket body. A measured count in the body is not an assumption: A figure that has changed since the ticket was written is not drift.
|
|
12
|
+
2. Check whether referenced files and paths still exist.
|
|
13
|
+
3. If the ticket has a last-updated date, examine commits since that date in affected areas: `git log --oneline --no-merges --after="{date}" -- {paths}`
|
|
14
|
+
4. If the ticket does not have a last-updated date, compare the ticket's assumptions against the current state of the affected files.
|
|
15
|
+
5. Assess whether the assumptions hold, have partially drifted, or are no longer valid.
|
|
16
|
+
|
|
17
|
+
**Verdicts:**
|
|
18
|
+
|
|
19
|
+
- 🟢 `none`: All factual assumptions hold; referenced files, APIs, and structures match the ticket's description
|
|
20
|
+
- 🟠 `partial`: Some assumptions are wrong but the ticket is salvageable; the core approach still applies with adjustments
|
|
21
|
+
- 🔴 `severe`: The ticket's factual premise no longer applies; referenced modules have been restructured, removed, or fundamentally changed
|
|
22
|
+
|
|
23
|
+
### Relevance
|
|
24
|
+
|
|
25
|
+
Determine whether the motivation for the ticket still applies.
|
|
26
|
+
|
|
27
|
+
1. Identify the problem or need that the ticket was created to address.
|
|
28
|
+
2. Look at broader codebase changes (not limited to paths mentioned in the ticket). Was the problem solved by a different approach? Was the feature or system targeted by the ticket removed or replaced?
|
|
29
|
+
3. Check whether the conditions that motivated the ticket still exist.
|
|
30
|
+
|
|
31
|
+
This dimension requires understanding intent, not just facts. When signals are ambiguous, prefer `uncertain` over a stronger verdict.
|
|
32
|
+
|
|
33
|
+
**Verdicts:**
|
|
34
|
+
|
|
35
|
+
- 🟢 `relevant`: The motivation still applies; the problem or need described in the ticket still exists
|
|
36
|
+
- 🟠 `uncertain`: Signals suggest the need may have changed but human judgment is required to confirm
|
|
37
|
+
- 🔴 `superseded`: The need has been addressed by other means or the target system no longer exists
|
|
38
|
+
|
|
39
|
+
### Progress
|
|
40
|
+
|
|
41
|
+
Determine whether the described work has been implemented. The output format depends on whether the ticket has acceptance criteria.
|
|
42
|
+
|
|
43
|
+
**When the ticket has acceptance criteria:**
|
|
44
|
+
|
|
45
|
+
1. Extract acceptance criteria from the ticket. These may be checkboxes, numbered lists, or prose descriptions of expected behavior.
|
|
46
|
+
2. For each criterion, examine the codebase to determine whether it has been met.
|
|
47
|
+
3. Present the verdict with a count summary (e.g., "4 of 7 criteria met"), followed by each criterion as a checklist item.
|
|
48
|
+
|
|
49
|
+
**When the ticket does not have acceptance criteria:**
|
|
50
|
+
|
|
51
|
+
1. Identify what the ticket's solution describes: new files, modified APIs, added tests, changed behavior.
|
|
52
|
+
2. Search the codebase for evidence of these artifacts.
|
|
53
|
+
3. Present the verdict followed by evidence bullets describing what has and hasn't been done.
|
|
54
|
+
|
|
55
|
+
**Verdicts:**
|
|
56
|
+
|
|
57
|
+
- 🟢 `complete`: All described work (or all acceptance criteria) has been done
|
|
58
|
+
- 🟠 `partial`: Some of the described work has been done but significant portions remain
|
|
59
|
+
- 🔴 `none`: None of the described work is present in the codebase
|
|
60
|
+
|
|
61
|
+
### Advisability
|
|
62
|
+
|
|
63
|
+
Determine whether the ticket should be implemented as written. Synthesize the four facets defined in `{harness_home_dir}/skills/_data/ticket-evaluation.md` (problem reality, scope correctness, solution soundness, title accuracy) against the codebase and ticket text.
|
|
64
|
+
|
|
65
|
+
1. Apply each facet in turn. Does the underlying observation hold? Is scope right at the appropriate class? Does the proposed solution treat the cause? Does the title accurately describe the work?
|
|
66
|
+
2. Synthesize a verdict from the facet results.
|
|
67
|
+
3. Emit one prose evidence bullet per concern raised by the facets. Do not prefix a bullet with its facet name. Omit bullets entirely when the verdict is `advisable`.
|
|
68
|
+
|
|
69
|
+
Bias toward `advisable`: For a recommendation dimension, false-positive concerns are noisier than false-negative passes. Default to `advisable` unless the codebase shows specific evidence of a facet concern.
|
|
70
|
+
|
|
71
|
+
**Verdicts:**
|
|
72
|
+
|
|
73
|
+
- 🟢 `advisable`: Recommend implementing as written; all four facets pass scrutiny
|
|
74
|
+
- 🟠 `questionable`: Recommend with concerns; one or more facets raise issues warranting human review
|
|
75
|
+
- 🔴 `inadvisable`: Recommend against implementing as written; rework needed before proceeding
|
|
76
|
+
|
|
77
|
+
### Complexity
|
|
78
|
+
|
|
79
|
+
Classify how complex the described work is relative to the current codebase. Reference the complexity classification rubric in `{harness_home_dir}/skills/_data/complexity-classification.md` for level definitions.
|
|
80
|
+
|
|
81
|
+
1. Identify the work surface: files, modules, packages, APIs, interfaces, and dependencies that the ticket describes changing or creating. Verify against the codebase.
|
|
82
|
+
2. Assess cross-cutting extent: how many modules or packages are touched, whether changes cross package boundaries, and whether shared interfaces or data structures are affected.
|
|
83
|
+
3. Assess decision density: whether the work follows established patterns or requires new ones, and whether design choices could go multiple ways.
|
|
84
|
+
4. Classify against the rubric. When characteristics span two levels, prefer the higher level.
|
|
85
|
+
|
|
86
|
+
**Verdicts:**
|
|
87
|
+
|
|
88
|
+
- ⚪ `trivial`: Single-line or purely mechanical; does not require judgment
|
|
89
|
+
- 🟢 `mechanical`: Follows an obvious pattern; single module, without API or behavioral changes
|
|
90
|
+
- 🟠 `involved`: Requires understanding context; touches multiple files or modules; may involve design decisions
|
|
91
|
+
- 🔴 `architectural`: Cross-cutting concerns, new patterns, dependency boundary changes, or far-reaching consequences
|
|
92
|
+
|
|
93
|
+
### Output format
|
|
94
|
+
|
|
95
|
+
Format the assessment using the structure below, with the dimensions in order and advisability and complexity omitted when progress is `complete`.
|
|
96
|
+
|
|
97
|
+
**When the ticket has acceptance criteria:**
|
|
98
|
+
|
|
99
|
+
```markdown
|
|
100
|
+
## Assessment: {ticket title} (#{number})
|
|
101
|
+
|
|
102
|
+
Assessed at {YYYYMMDD-HHMMSSZ} against {short SHA}
|
|
103
|
+
|
|
104
|
+
Δ **Drift:** {emoji} `{verdict}`
|
|
105
|
+
|
|
106
|
+
- {Evidence bullet}
|
|
107
|
+
- {Evidence bullet}
|
|
108
|
+
|
|
109
|
+
🎯 **Relevance:** {emoji} `{verdict}`
|
|
110
|
+
|
|
111
|
+
- {Evidence bullet}
|
|
112
|
+
- {Evidence bullet}
|
|
113
|
+
|
|
114
|
+
📶 **Progress:** {emoji} `{verdict}` ({N} of {M} criteria met)
|
|
115
|
+
|
|
116
|
+
- ✅ {Criterion met}
|
|
117
|
+
- ✅ {Criterion met}
|
|
118
|
+
- ❌ {Criterion not met}
|
|
119
|
+
|
|
120
|
+
🧭 **Advisability:** {emoji} `{verdict}`
|
|
121
|
+
|
|
122
|
+
- {Evidence bullet}
|
|
123
|
+
- {Evidence bullet}
|
|
124
|
+
|
|
125
|
+
🧩 **Complexity:** {emoji} `{label}`
|
|
126
|
+
|
|
127
|
+
- {Evidence bullet}
|
|
128
|
+
- {Evidence bullet}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**When the ticket does not have acceptance criteria:**
|
|
132
|
+
|
|
133
|
+
```markdown
|
|
134
|
+
## Assessment: {ticket title} (#{number})
|
|
135
|
+
|
|
136
|
+
Assessed at {YYYYMMDD-HHMMSSZ} against {short SHA}
|
|
137
|
+
|
|
138
|
+
Δ **Drift:** {emoji} `{verdict}`
|
|
139
|
+
|
|
140
|
+
- {Evidence bullet}
|
|
141
|
+
- {Evidence bullet}
|
|
142
|
+
|
|
143
|
+
🎯 **Relevance:** {emoji} `{verdict}`
|
|
144
|
+
|
|
145
|
+
- {Evidence bullet}
|
|
146
|
+
- {Evidence bullet}
|
|
147
|
+
|
|
148
|
+
📶 **Progress:** {emoji} `{verdict}`
|
|
149
|
+
|
|
150
|
+
- {Evidence bullet}
|
|
151
|
+
- {Evidence bullet}
|
|
152
|
+
|
|
153
|
+
🧭 **Advisability:** {emoji} `{verdict}`
|
|
154
|
+
|
|
155
|
+
- {Evidence bullet}
|
|
156
|
+
- {Evidence bullet}
|
|
157
|
+
|
|
158
|
+
🧩 **Complexity:** {emoji} `{label}`
|
|
159
|
+
|
|
160
|
+
- {Evidence bullet}
|
|
161
|
+
- {Evidence bullet}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Emoji mapping
|
|
165
|
+
|
|
166
|
+
Drift, relevance, progress, and advisability use a **concern scale**, on which green means no concern and red means high concern:
|
|
167
|
+
|
|
168
|
+
| Verdict position | Emoji |
|
|
169
|
+
| ---------------- | ----- |
|
|
170
|
+
| No concern | 🟢 |
|
|
171
|
+
| Mixed / unclear | 🟠 |
|
|
172
|
+
| High concern | 🔴 |
|
|
173
|
+
|
|
174
|
+
Complexity uses a **size scale**, on which emojis represent effort and scope, not concern:
|
|
175
|
+
|
|
176
|
+
| Level | Emoji |
|
|
177
|
+
| ----- | ----- |
|
|
178
|
+
| 1 | ⚪ |
|
|
179
|
+
| 2 | 🟢 |
|
|
180
|
+
| 3 | 🟠 |
|
|
181
|
+
| 4 | 🔴 |
|
|
182
|
+
|
|
183
|
+
### Verdict reference
|
|
184
|
+
|
|
185
|
+
| Dimension | ⚪ | 🟢 | 🟠 | 🔴 |
|
|
186
|
+
| ---------------- | --------- | ------------ | -------------- | --------------- |
|
|
187
|
+
| **Drift** | n/a | `none` | `partial` | `severe` |
|
|
188
|
+
| **Relevance** | n/a | `relevant` | `uncertain` | `superseded` |
|
|
189
|
+
| **Progress** | n/a | `complete` | `partial` | `none` |
|
|
190
|
+
| **Advisability** | n/a | `advisable` | `questionable` | `inadvisable` |
|
|
191
|
+
| **Complexity** | `trivial` | `mechanical` | `involved` | `architectural` |
|
|
192
|
+
|
|
193
|
+
### Baseline verdicts
|
|
194
|
+
|
|
195
|
+
<!-- include: ticket-assessment-baseline.md / -->
|
|
196
|
+
|
|
197
|
+
### Assessment principles
|
|
198
|
+
|
|
199
|
+
- **Evidence over opinion**: Every verdict must be supported by specific evidence (file paths, commit SHAs, code references)
|
|
200
|
+
- **Prefer caution on relevance**: Use `uncertain` when signals are ambiguous rather than committing to `superseded`
|
|
201
|
+
- **Bias `advisable` absent evidence**: Every non-baseline advisability verdict calls for a follow-up action; default to `advisable` unless the codebase shows specific evidence of a facet concern
|
|
202
|
+
- **Scale to ticket complexity**: A simple ticket gets a brief assessment; a complex ticket with many acceptance criteria gets a thorough one
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
**Choosing a work type.** Whom a change affects decides its type, not the format of its files. Apply the descriptions in `{harness_home_dir}/skills/_data/work-types.json` to the change itself. Never infer a type from how earlier changes were typed, because many were typed wrongly.
|
|
2
|
+
|
|
3
|
+
**`fix` requires a defect that a consumer meets.** Two questions decide it, in order.
|
|
4
|
+
|
|
5
|
+
1. **Does a consumer meet the behavior that changed?** When none does, the type is the one for that audience (`tests`, `tooling`, `ci`, `internal`), whatever the change repaired. A lint rule, a build script, and a test helper are not consumer-facing, so a repair to one is never `fix`. The same question settles a latent condition: When it could not be observed by any consumer, the change does not repair any defect, and evidence that the condition pre-dated the change is not evidence that it was one.
|
|
6
|
+
2. **Did the effect differ from what its author intended?** Compare the intended effect with the actual one. That the code or the text was written deliberately does not settle it, because a deliberate rule can still produce an effect that its author did not intend. When the effect diverged from the intent, the type is `fix`. When it matched, and the change reflects a new decision about what the intent should be, the type is `feat`. When intent and effect are both unchanged and only the construction differs, the type is `refactor`.
|
|
7
|
+
|
|
8
|
+
The test runs in both directions. `fix` is public tier, so typing an improvement `fix` publishes a "Bug fixes" entry telling every reader that something was broken, and typing a genuine defect `refactor` withholds a repair that a reader needs. A defect in consumer-facing behavior is `fix` whatever else the change does, and neither the branch's bulk nor the ticket's subject displaces it.
|
|
9
|
+
|
|
10
|
+
- **Repo-agnostic guidance is source code.** Skills, skill data, partials, subagent definitions, and rulebooks written for use in any repository take the type that the same change to source code would take. A wording correction is `fix` when the text failed to say what its author already intended, and `feat` when it states a new decision; the repair of a writing-rule violation is the former. A restructuring is `refactor` only when it leaves the text read by the agent unchanged, as extracting a partial does. A token cut that does not change any behavior is `perf`.
|
|
11
|
+
- **Guidance on working in one repository is `ai`.** That repository's `AGENTS.md`, its repo-local skills, and its agent configuration take `ai`.
|
|
12
|
+
- **Guidance to agents is never `docs`.** `docs` is documentation for human readers, and a change confined to code comments is `docs`.
|
|
13
|
+
- **Content decides.** What guidance says decides whether it is repo-agnostic, not its file name, location, or format.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# The content-format contract against which this root is authored; see "Content-format version" in packages/agents/docs/project-declaration.md.
|
|
2
|
+
format: 3
|
|
3
|
+
|
|
4
|
+
# The TypeScript helpers that `codeassembly bundle-helpers` bundles into this root, both paths relative to this file.
|
|
5
|
+
helpers:
|
|
6
|
+
- entry: ../src/kb-add/cli.ts
|
|
7
|
+
out: skills/kb-add/kb-add.mjs
|
|
8
|
+
- entry: ../src/kb-edit/cli.ts
|
|
9
|
+
out: skills/kb-edit/kb-edit.mjs
|
|
10
|
+
- entry: ../src/kb-curate/cli.ts
|
|
11
|
+
out: skills/kb-curate/kb-curate.mjs
|
|
12
|
+
- entry: ../src/kb-retrieve/cli.ts
|
|
13
|
+
out: skills/kb-retrieve/kb-retrieve.mjs
|
|
14
|
+
- entry: ../src/kb-retrieve-events/cli.ts
|
|
15
|
+
out: skills/kb-retrieve-events/kb-retrieve-events.mjs
|
|
16
|
+
- entry: ../src/update-jira-ticket/cli.ts
|
|
17
|
+
out: skills/update-jira-ticket/update-jira-ticket.mjs
|
|
18
|
+
- entry: ../src/derive-session-context/cli.ts
|
|
19
|
+
out: skills/derive-session-context/derive-session-context.mjs
|
|
20
|
+
- entry: ../src/capture-event/cli.ts
|
|
21
|
+
out: skills/capture-event/capture-event.mjs
|
|
22
|
+
- entry: ../src/capture-lede-decision/cli.ts
|
|
23
|
+
out: skills/capture-lede-decision/capture-lede-decision.mjs
|
|
24
|
+
- entry: ../src/kb-update-events/cli.ts
|
|
25
|
+
out: skills/kb-update-events/kb-update-events.mjs
|
|
26
|
+
- entry: ../src/feedback-memories/cli.ts
|
|
27
|
+
out: skills/migrate-feedback-memories/feedback-memories.mjs
|
|
28
|
+
- entry: ../src/groom-backlog/cli.ts
|
|
29
|
+
out: skills/groom-backlog/groom-backlog.mjs
|
|
30
|
+
- entry: ../src/pull-from-backlog/cli.ts
|
|
31
|
+
out: skills/pull-from-backlog/pull-from-backlog.mjs
|
|
32
|
+
- entry: ../src/revise-prose/cli.ts
|
|
33
|
+
out: skills/revise-prose/revise-prose.mjs
|
|
34
|
+
- entry: ../src/streamline-guidance/cli.ts
|
|
35
|
+
out: skills/streamline-guidance/streamline-guidance.mjs
|
|
36
|
+
- entry: ../src/validate-preferences/cli.ts
|
|
37
|
+
out: scripts/validate-preferences.mjs
|
|
38
|
+
- entry: ../src/describe-change/cli.ts
|
|
39
|
+
out: scripts/describe-change.mjs
|
|
40
|
+
- entry: ../src/select-lede-exemplars/cli.ts
|
|
41
|
+
out: scripts/select-lede-exemplars.mjs
|
|
42
|
+
- entry: ../src/resolve-review-run/cli.ts
|
|
43
|
+
out: scripts/resolve-review-run.mjs
|
|
44
|
+
- entry: ../src/manage-jira-ticket/cli.ts
|
|
45
|
+
out: scripts/manage-jira-ticket.mjs
|
|
46
|
+
- entry: ../src/merge-gh-pr/cli.ts
|
|
47
|
+
out: skills/merge-gh-pr/merge-gh-pr.mjs
|
|
48
|
+
- entry: ../src/index-prototypes/cli.ts
|
|
49
|
+
out: skills/index-prototypes/index-prototypes.mjs
|
|
50
|
+
- entry: ../src/select-pr-ticket/cli.ts
|
|
51
|
+
out: skills/review-gh-pr/select-pr-ticket.mjs
|
|
52
|
+
- entry: ../src/resolve-ticket-target/cli.ts
|
|
53
|
+
out: skills/create-ticket/resolve-ticket-target.mjs
|
|
54
|
+
- entry: ../src/triage-spike-findings/cli.ts
|
|
55
|
+
out: skills/triage-spike-findings/triage-spike-findings.mjs
|
|
56
|
+
- entry: ../src/check-branch-currency/cli.ts
|
|
57
|
+
out: scripts/check-branch-currency.mjs
|
|
58
|
+
- entry: ../src/check-prose/cli.ts
|
|
59
|
+
out: scripts/check-prose.mjs
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: all
|
|
3
|
+
description: The whole content library (every rulebook, skill, and subagent), computed automatically.
|
|
4
|
+
members: '@library'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# All
|
|
8
|
+
|
|
9
|
+
The whole-catalog collection. `members: '@library'` resolves to every rulebook, skill, and subagent in the content library, computed at resolution time so that the resolver includes a newly added artifact automatically, without an edit here. Collections are excluded: The resolver never emits them, and "every collection" would be self-referential.
|
|
10
|
+
|
|
11
|
+
This is the fallback, not the expected declaration. It does not make any claim about its members: It deploys the vetted, the unexamined, and the artifacts deliberately left out of every collection alike, and it includes a newly added artifact before anyone has read it. A consumer should declare the collections whose dispositions it wants instead, and declare this one only to deploy the whole catalog.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: atlassian
|
|
3
|
+
description: Skills that act on Bitbucket pull requests and Jira work items.
|
|
4
|
+
disposition: opt-in
|
|
5
|
+
members:
|
|
6
|
+
skills:
|
|
7
|
+
- create-bitbucket-pr
|
|
8
|
+
- merge-bb-pr
|
|
9
|
+
- review-bb-pr
|
|
10
|
+
- update-jira-ticket
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Atlassian
|
|
14
|
+
|
|
15
|
+
Every member acts on one of Atlassian's hosted products: creating, reviewing, and merging Bitbucket pull requests, and creating and updating Jira work items. A consumer should declare this collection only if one of those products is in use.
|
|
16
|
+
|
|
17
|
+
Artifacts outside this collection do not require any member. `create-pr`, `merge-pr`, `review-pr`, and `create-ticket` each name one through an optional invocation token, and `codeassembly validate` reports a token naming a member that is written in its required form.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: recommended
|
|
3
|
+
description: The vetted, generally applicable set (artifacts any project can declare).
|
|
4
|
+
disposition: public
|
|
5
|
+
members:
|
|
6
|
+
rulebooks:
|
|
7
|
+
- accessibility-conventions
|
|
8
|
+
- cli-conventions
|
|
9
|
+
- command-output-conventions
|
|
10
|
+
- generated-content-policy
|
|
11
|
+
- readme-conventions
|
|
12
|
+
- shared-data-conventions
|
|
13
|
+
- ui-copy-conventions
|
|
14
|
+
skills:
|
|
15
|
+
- capture-event
|
|
16
|
+
- capture-feedback
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
# Recommended
|
|
20
|
+
|
|
21
|
+
The public collection. Membership claims that an artifact was examined and found generally applicable: It names nothing specific to one author's environment, does not state any personal doctrine, declares its prerequisites where a reader looks before invoking, and deploys only where it works.
|
|
22
|
+
|
|
23
|
+
Membership is per-artifact and enumerated in full rather than by dependency root, so the closure check notices every member that an artifact's dependency edges would add.
|
|
24
|
+
|
|
25
|
+
The skills belong here on different grounds. A rulebook of the personal collection names `capture-feedback` in a body token, and `capture-feedback` names `capture-event` in another. Because a collection cannot be closed over an artifact of lesser standing, both were promoted. `capture-event`'s promotion was forced by that chain rather than chosen on its own merits. It is the one member to re-examine first. `capture-feedback` qualifies on its own terms: It does not name any store, declares the registry needed by a capture, and sends a record to the store that the registry's `feedback_kb` names.
|
|
26
|
+
|
|
27
|
+
`generated-content-policy` qualifies on its own terms too: What it states is a mechanism that every consumer meets, not a preference, and the guidance that a reader needs beyond the trigger is in the linked reference rather than in the ambient body loaded by every session.
|
|
28
|
+
|
|
29
|
+
`accessibility-conventions` also qualifies on its own terms. It states an external standard, WCAG 2.2 AA, and floors that do not name any author, repository, or tool. Its body does not contain any invocation token, so its closure is empty.
|
|
30
|
+
|
|
31
|
+
`cli-conventions` qualifies on its own terms as well. What it asks of a CLI's options, configuration, help, exit codes, errors, JSON output, and progress reports, and of the split between its logic and its presentation, follows from who reads them, a person at a terminal that cannot follow a link and a script or an agent that reads the exit code and the streams, rather than from a preference. It does not name any author, repository, language, or tool. Its body does not contain any invocation token, so its closure is empty.
|
|
32
|
+
|
|
33
|
+
`command-output-conventions` qualifies on its own terms too. What it states follows from a mechanism that every agent session meets, the context-window space that retained output takes up, rather than from a preference, and it does not name any tool, host, or store. Its body does not contain any invocation token, so its closure is empty.
|
|
34
|
+
|
|
35
|
+
`readme-conventions` qualifies on its own terms as well. It does not name any repository, tool, or path belonging to one author, and what it asks of a README follows from who reads the file rather than from a preference about how a README should read. Its body does not contain any invocation token, so its closure is empty and admitting it does not add any other artifact to what this collection deploys.
|
|
36
|
+
|
|
37
|
+
Adding a skill that declares a guidance hook has a drawback that the current members do not have. A project declaring this collection deploys its own copy of that skill, and that copy shadows the user's home-bound one. Because guidance-hook bindings do not cross the boundary between the user-global and project domains, guidance bound globally by the developer goes missing in that repository until the project binds it too. Weigh that against the general applicability claimed by membership before admitting such a skill.
|
|
38
|
+
|
|
39
|
+
`shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract, and the rule that unmerged code does not write to shared state, and it does not name any author, platform, or store: Each repository's `AGENTS.md` names its own. Its body does not contain any invocation token, so its closure is empty.
|
|
40
|
+
|
|
41
|
+
`ui-copy-conventions` qualifies on its own terms as well. What it asks of the text on a page follows from who reads that text, the person who returns to the page every week, rather than from a preference, and it does not name any author, repository, product, or tool. A project that has content guidelines of its own names them, and they take precedence. Its body does not contain any invocation token, so its closure is empty.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: triage
|
|
3
|
+
description: The not-yet-examined set, the default home for library content awaiting a disposition.
|
|
4
|
+
members: '@unclaimed'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Triage
|
|
8
|
+
|
|
9
|
+
The not-yet-examined collection, and where new content starts. Membership claims nothing about an artifact beyond its existence: Nobody has yet read it for personal doctrine or for coupling to one author's environment, so it can be neither offered as generally applicable nor vouched for as deliberately personal.
|
|
10
|
+
|
|
11
|
+
`members: '@unclaimed'` computes the membership: every artifact of this content root that no collection with a `disposition:` enumerates and that does not declare `standalone:`. A newly added artifact is therefore a member without an edit here. Declaring the collection is the honest way to keep everything while the vetting proceeds, and it is why the vetted collections are usable before the vetting examines a single artifact.
|
|
12
|
+
|
|
13
|
+
An artifact leaves this collection by promotion into a public or personal collection, by moving into an opt-in collection once it turns out to be wanted often but only on the machines using one vendor's ecosystem, or by declaring `standalone:` once it turns out to be deliberate but rarely wanted. Nothing that has left is ever moved back in. Several members contain general and personal guidance in one file and become decidable only after a rewrite splits them.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: williamthorsen
|
|
3
|
+
description: The vetted personal set (artifacts that deliberately encode William Thorsen's preferences, environment, and domain).
|
|
4
|
+
disposition: personal
|
|
5
|
+
members:
|
|
6
|
+
rulebooks:
|
|
7
|
+
- williamthorsen-code-layout-preferences
|
|
8
|
+
- williamthorsen-collaboration-preferences
|
|
9
|
+
- williamthorsen-comment-preferences
|
|
10
|
+
- williamthorsen-subagent-model-preferences
|
|
11
|
+
- williamthorsen-ticketing-preferences
|
|
12
|
+
- williamthorsen-tooling-preferences
|
|
13
|
+
- williamthorsen-typescript-preferences
|
|
14
|
+
- williamthorsen-workflow-preferences
|
|
15
|
+
- williamthorsen-writing-preferences
|
|
16
|
+
skills:
|
|
17
|
+
- people-report
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# William Thorsen
|
|
21
|
+
|
|
22
|
+
The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The nine rulebooks state one author's preferences as rules that another team would decide differently, and `people-report` serves a domain in which one author works rather than one that every project shares.
|
|
23
|
+
|
|
24
|
+
Its closure contains `capture-feedback` and `capture-event` in `recommended` and nothing else, which makes declaring it safe alongside the public collection.
|
|
25
|
+
|
|
26
|
+
Every member is invoked often enough to justify its standing line in the skill index. An artifact that is deliberate but rarely wanted belongs outside every collection, declared directly where it is needed.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Agent guidance content
|
|
2
|
+
|
|
3
|
+
This directory contains the source-of-truth guidance content that `codeassembly install` renders into platform-specific files (`~/.claude/CLAUDE.md`, `~/.rovo/AGENTS.md`).
|
|
4
|
+
|
|
5
|
+
This README is for maintainers of this directory. It is not referenced by any `<!-- include: -->` directive and is not part of the rendered output.
|
|
6
|
+
|
|
7
|
+
## `shared/AGENTS.md`
|
|
8
|
+
|
|
9
|
+
Inlined into every rendered platform guidance file via the directive expander, which puts it in every session that loads one of those files. It does not have a destination of its own; `install` deployed a copy to `~/.agents/AGENTS.md` until that tier was retired, and both `install` and `uninstall` now remove what it left there.
|
|
10
|
+
|
|
11
|
+
A subagent does not load any platform guidance file, so a section that its role's work needs is inlined from `_partials/` instead. This file composes from those same partials rather than restating them, which keeps the two routes from drifting: A section delivered to some subagent is in a partial included by both hosts, and one not delivered to any subagent stays written out here. `content/test-utils/shared-doctrine-carriers.ts` records the per-role coverage, and `content/__tests__/shared-doctrine-reach.unit.test.ts` asserts it along with the order in which the sections render.
|
|
12
|
+
|
|
13
|
+
## Ambient delivery: Harness regions
|
|
14
|
+
|
|
15
|
+
A rulebook with `delivery: ambient` is delivered by `sync` into the ambient region (`<!-- codeassembly-ambient:start -->` / `<!-- codeassembly-ambient:end -->`) of a per-harness guidance file, wrapped in `<!-- rulebook:<slug> -->` sentinels, with `<!-- rulebook-version: <version> -->` directly below the open sentinel if the rulebook declares a version. The region opens with a comment naming its content generated and warning that edits inside the region are overwritten; the comment is part of the rendered body, so a region without ambient content does not have one. Both domains work this way, and both are mechanical end to end: Every host is a file loaded by its harness at launch, without any agent-elective read anywhere on the path. They differ in which file, and in who creates the region.
|
|
16
|
+
|
|
17
|
+
- **Home / all-projects scope** (`sync --global`): The host is each targeted harness's guidance file under its home directory (`~/.claude/CLAUDE.md`, and the equivalent under each other harness's home). The templates in `_harnesses/` contain the empty region, so the region's location is `install`'s decision while its content is `sync`'s: `sync --global` regenerates the region wholesale each run, and `install` splices the region's content into every re-render and excludes it from drift hashing (`ambient-region.ts`). Hand edits outside the region still count as drift. Run `install` before the first `sync --global`; a guidance file that is missing or does not have a region is skipped with a warning naming the fix.
|
|
18
|
+
- **Project scope** (`sync`): The host is each targeted harness's machine-local project guidance file at the project root (`CLAUDE.local.md`, `AGENTS.local.md`). `install` does not manage user-local files, so `sync` owns region creation here: An absent host is created with the region, and a host that already exists keeps everything it contains and gains the region below it. A host is materialized only when the scope declares an ambient rulebook. A project that declares none is left without a file. A host with a half-written region fails the run rather than being appended to, since appending beside a stray marker would delete the text between them on the following sync. Because the host is gitignored, it exists only in the worktree in which it was created. A multi-worktree checkout needs a sync per worktree; `sync` warns when a host that it writes is not git-ignored.
|
|
19
|
+
|
|
20
|
+
**Destination tiers.** Harness-neutral and per-harness destinations are not interchangeable. A project's root `AGENTS.md` is the one neutral destination: One body of text serves every harness, so it cannot contain a harness-scoped path, and content that needs one belongs in an ambient rulebook instead. Every generated destination has a known target harness: skills, subagents, and both ambient tiers. The root `AGENTS.md` does not receive any generated content at all. It is hand-authored, and `sync` strips the rulebook blocks that a previous version left there or in the `.agents/PROJECT.md` that it superseded.
|
|
21
|
+
|
|
22
|
+
Two files under `~/.agents/` are retired. `GLOBAL.md` was the home ambient host: `sync --global` strips the sync-owned blocks from a legacy copy and deletes the file once nothing hand-written remains. `AGENTS.md` was a verbatim copy of `shared/AGENTS.md`: `install` and `uninstall` each remove a copy deployed by the CLI, keep one containing hand-written content, and leave alone a copy that it never deployed. For machine-local guidance that should stay out of source control, declare a machine-local source in `~/.agents/codeassembly.yaml` (a directory shaped like the library's `content/`, with rulebooks at `guidance/rulebooks/<slug>.md`) and give the rulebook `delivery: ambient`; it then uses the same injection as library rulebooks.
|