codeassembly-guidance 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: williamthorsen-workflow-preferences
|
|
3
|
+
description: William Thorsen's personal preferences for how work moves -- scope, branches and worktrees, guidance capture, and the arc of product development.
|
|
4
|
+
delivery: ambient
|
|
5
|
+
version: '8'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# William Thorsen's workflow preferences
|
|
9
|
+
|
|
10
|
+
## Workflow
|
|
11
|
+
|
|
12
|
+
- Do not treat a question as an instruction: When the user asks "Did you do X?", answer the question rather than doing X.
|
|
13
|
+
- Treat a ticket as a signal, not a boundary: When work appears that the ticket didn't name, fold it into the current change by default; spin off a separate ticket only for an affirmative reason beyond the ticket's silence, and when you do, create it immediately rather than parking it in the conversation. Recommend the scope call and build on it: Surface a fold-in as provisional at the ticket checkpoint, and ask before creating a spin-off, because it creates remote state. Full doctrine: [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
|
|
14
|
+
- Make changes through branches and pull requests, not by editing the default branch directly.
|
|
15
|
+
- When feedback should change how the agent behaves and generalizes beyond the current task, capture it via {skill:capture-feedback}. The capture records evidence for a later refinement pass; it does not change any behavior until that pass writes the lesson into guidance and the guidance is deployed. Do not record generalizable guidance as a per-project memory.
|
|
16
|
+
- Reserve memories for genuinely local, non-propagating facts (a project-specific deadline or quirk): A memory is scoped to a single project on a single machine, so recording generalizable guidance in one fragments behavior across contexts.
|
|
17
|
+
|
|
18
|
+
## Branch and worktree management
|
|
19
|
+
|
|
20
|
+
Never create a branch or worktree without explicit authorization. Never switch a worktree to another branch: Do all of one ticket's work in one worktree, and start a new session in another ticket's own worktree for work on that ticket.
|
|
21
|
+
|
|
22
|
+
After a merge, say nothing about worktree or branch state and never offer to manage it. The worktree stays as long as its branch does, so there is nothing to clean up and nothing to ask about.
|
|
23
|
+
|
|
24
|
+
## Cross-repo sequencing
|
|
25
|
+
|
|
26
|
+
When the work would be better done upstream, in a package or repository on which this one depends, default to upstream first: Merge the upstream change, publish it, upgrade the dependency here, then make the downstream change against the upgraded version. Propose that order rather than merging a downstream workaround ahead of it.
|
|
27
|
+
|
|
28
|
+
Downstream first reads as faster because something is merged sooner, but it requires two downstream changes rather than one: the workaround, then its removal once the upstream change is merged. It also forces upstream to decide without the downstream requirement in hand, so upstream cannot weigh that requirement against its own constraints, and may settle on a shape that the consumer keeps working around.
|
|
29
|
+
|
|
30
|
+
Let a condition displace the default: an upstream that is unowned, unresponsive, or on a release cadence that will not accommodate the work. When one applies, name it, recommend the order, build on the recommendation, and leave the veto to the developer.
|
|
31
|
+
|
|
32
|
+
## Product development
|
|
33
|
+
|
|
34
|
+
When the developer starts a product, move the work through these stages in order, each producing one thing. Skip a stage when the product is small enough that its output is already obvious, and say which stage and why.
|
|
35
|
+
|
|
36
|
+
1. Idea: Write the idea back to the developer and record it in the design doc.
|
|
37
|
+
2. Opinions: Evaluate the idea from other roles and record the evaluations with it.
|
|
38
|
+
3. Brief: Flesh the idea out into a brief for a prototype round.
|
|
39
|
+
4. Prototypes: Build competing prototypes of a rich feature set through `prepare-prototype-brief`, judge them through `index-prototypes`, and synthesize them. Prototyping a rich feature set is how the product that could emerge becomes visible, so run the round before writing the vision.
|
|
40
|
+
5. End vision: Write the purpose, the non-goals, the decisions with their reasons, and a rough structure from what the prototypes taught, and get the developer's approval.
|
|
41
|
+
6. MVP: Build the smallest product that does the product's one job. Put a prototype feature in it when the product cannot do that job without the feature, and leave the rest for increments.
|
|
42
|
+
7. Increments: Add features one iteration at a time.
|
|
43
|
+
|
|
44
|
+
Treat the winning prototype as the baseline: the floor on quality and feel against which the finished product is judged, and the reference for what the product does and how it is put together. Read it as evidence of the vision rather than as its specification: Let its structure inform the design doc, and expect to improve on it.
|
|
45
|
+
|
|
46
|
+
Hold the finished product to the baseline, not any one iteration. An iteration may omit a prototype feature or ship it in a reduced form; treat a reduction as remaining work and give it a one-line sub-issue, which keeps the gap visible. When settling a feature below the prototype's bar or retiring it, record the decision in the design doc with its reason.
|
|
47
|
+
|
|
48
|
+
Write a ticket in detail when its work is about to be implemented. Until then, keep each artifact to one tier:
|
|
49
|
+
|
|
50
|
+
- Keep the vision in a design doc in the repo: the purpose, the non-goals, the decisions with their reasons, and the rough structure. Put a statement there when reversing it later would invalidate completed work, or when a new session needs it to choose a direction, and leave most other detail to its iteration.
|
|
51
|
+
- Have the epic point to the design doc, state what is out of scope, and list the iterations as its sub-issues in order. Keep the vision out of the epic's body, because a ticket's body is frozen once its work starts and the vision is not.
|
|
52
|
+
- Use the milestone to mark the current iteration, which `pull-from-backlog` reads as the Now set.
|
|
53
|
+
- Treat the prototype as the baseline.
|
|
54
|
+
- Make each iteration a sub-issue of the epic, and create every iteration's sub-issue when the epic is created rather than as each iteration starts. Specify the current iteration in detail. Write each later one as a one-line outcome, what the user can newly do, rather than as a feature, and refine it against the design doc when its iteration starts.
|
|
55
|
+
|
|
56
|
+
Once the developer approves the end vision, propose that shape rather than drafting every ticket in detail up front.
|
|
57
|
+
|
|
58
|
+
Expect the vision to change. At the end of each iteration, re-read the design doc, revise what the iteration disproved, and refine the next sub-issue against the revised doc. The documents exist so that a new session knows the vision without being told.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: williamthorsen-writing-preferences
|
|
3
|
+
description: William Thorsen's personal writing preferences for agent-authored prose.
|
|
4
|
+
delivery: [ambient, hook]
|
|
5
|
+
version: '11'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# William Thorsen's writing preferences
|
|
9
|
+
|
|
10
|
+
## Apostrophes
|
|
11
|
+
|
|
12
|
+
<!-- rule: apostrophes 1 -->
|
|
13
|
+
|
|
14
|
+
Keep every apostrophe that a possessive or a contraction takes. Writing `the rule own example` for `the rule's own example`, or `dont` for `don't`, corrupts the text. When a command's quoting cannot hold a character, pass the content through a file written with the Write tool or through a quoted heredoc (`<<'EOF'`), and never drop or replace the character.
|
|
15
|
+
|
|
16
|
+
## Capitalization after a colon
|
|
17
|
+
|
|
18
|
+
<!-- rule: capitalization-after-colon 1 -->
|
|
19
|
+
|
|
20
|
+
Read what appears left of the colon. A label (such as a short tag naming a field, a category, or an option) is transparent: Capitalize what follows as though the label were absent. A clause puts the colon mid-sentence: Capitalize a complete sentence, keep a fragment or list lowercase. A lowercase code identifier keeps its own case on either branch.
|
|
21
|
+
|
|
22
|
+
- **Label, fragment follows:** "Exception: Trivial predicate callbacks whose type is obvious."
|
|
23
|
+
- **Clause, sentence follows:** "The cache is not the problem: The transport reconnects on every request."
|
|
24
|
+
- **Clause, fragment follows:** "Two directories stay out of the sweep: fixtures and generated output."
|
|
25
|
+
- **Code identifier:** "Run the formatter: `nmr fmt`."
|
|
26
|
+
|
|
27
|
+
## Em-dashes
|
|
28
|
+
|
|
29
|
+
<!-- rule: em-dash 1 -->
|
|
30
|
+
|
|
31
|
+
Don't use em-dashes; use appropriate punctuation instead. A dash separating an identifier from its label is a delimiter rather than punctuation: Use a colon. If an em-dash is genuinely best, write it as `--`.
|
|
32
|
+
|
|
33
|
+
<!-- include: ../../_partials/reduced-object-relative.md / -->
|
|
34
|
+
|
|
35
|
+
## Second person
|
|
36
|
+
|
|
37
|
+
<!-- rule: second-person 1 -->
|
|
38
|
+
|
|
39
|
+
Documentation describes; it does not address. Never write `you`, `your`, `yours`, or `yourself`, and never the contractions `you're`, `you've`, `you'll`, or `you'd`.
|
|
40
|
+
|
|
41
|
+
Imperative mood is untouched, because it does not contain a pronoun: "Run the formatter" directs the reader without naming one.
|
|
42
|
+
|
|
43
|
+
**The addressee decides.** Ask who the pronoun names. If it names the agent that the document instructs, a skill body or a subagent body directing its own executor, the pronoun is that document's address and stays. If it names a reader of documentation, someone using the package or working on it, the pronoun goes.
|
|
44
|
+
|
|
45
|
+
**The replacement names an actor.** Say who or what acts: "the config sets a cap on the rule" rather than "you cap the rule". If an actor does not belong in the sentence, recast so that the artifact is the subject of a verb that it performs or one that states a relation, as plain speech requires: "the flag takes a path" rather than "you pass it a path".
|
|
46
|
+
|
|
47
|
+
A naive substitution fails in two ways:
|
|
48
|
+
|
|
49
|
+
- **The agentless passive.** Dropping the pronoun by hiding who acted trades one defect for another: "your rules are capped" becomes "the rules are capped", which names nobody. Plain speech rejects that passive; name the actor instead.
|
|
50
|
+
- **The surviving object gap.** "the cap you set" and "the cap the config sets" are the same reduced object relative; therefore, the substitution leaves the second defect in place. Restore the relativizer, or apply the repairs in "Reduced object relatives" above.
|
|
51
|
+
|
|
52
|
+
## Sentence case
|
|
53
|
+
|
|
54
|
+
<!-- rule: sentence-case 1 -->
|
|
55
|
+
|
|
56
|
+
Use sentence case for titles, headings, section headers, steps, labels, and interface elements. Never use title case. Preserve the case of proper nouns, named entities, and the actual titles of books and movies.
|
|
57
|
+
|
|
58
|
+
- "Backend: Express API routes and server" not "Backend: Express API Routes And Server"
|
|
59
|
+
- "Frontend: Static Excalibur scene" not "Frontend: Static Excalibur Scene"
|
|
60
|
+
- "Customizing the Status Adapter for a new backend", not "Customizing the Status Adapter for a New Backend"
|
|
61
|
+
|
|
62
|
+
## `so` and other connectives
|
|
63
|
+
|
|
64
|
+
<!-- rule: so 1 -->
|
|
65
|
+
|
|
66
|
+
Join two clauses with `so` only when the second states a direct result of the first: "The entry is not a top-level segment, so the exclusion does not cover it." For a purpose, write "so that" or "to": "The link points to `.live` so that apps read the stable worktree." If the second clause follows only through a step that the sentence leaves out, state that step rather than change the conjunction.
|
|
67
|
+
|
|
68
|
+
Use connectives sparingly. When most sentences in a paragraph end with a consequence, the paragraph reads as a chain of justifications, and the repeated word distracts even when each use is correct. Keep a connective only when a reader would not infer the link from the order of the sentences. Leave at least three sentences between one clause-joining `so` and the next, and do not meet that limit by swapping in another connective: Split the sentence, lead with "because", or drop the link.
|
|
69
|
+
|
|
70
|
+
A degree adverb ("so many") and a `so` that stands for a clause ("do so", "if so") are outside the rule.
|
|
71
|
+
|
|
72
|
+
## `where`
|
|
73
|
+
|
|
74
|
+
<!-- rule: where 2 -->
|
|
75
|
+
|
|
76
|
+
Use `where` for a place, or after an expression to state what a symbol, variable, placeholder, or value in it stands for; for any other relation, use the word that most clearly expresses it.
|
|
77
|
+
|
|
78
|
+
- **Definition:** "`{NN+1}`, where `{NN}` is the run-summary sequence number"
|
|
79
|
+
- **Condition (a violation):** "the entry where `role` is `coder`" becomes "the entry whose `role` is `coder`"
|
|
80
|
+
- **Event (a violation):** "Fixes an issue where the report cut a subject" becomes "Fixes the issue that the report cut a subject"
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Shared agent instructions
|
|
2
|
+
|
|
3
|
+
## Interactive work
|
|
4
|
+
|
|
5
|
+
- Invoke the `collaborate` skill when working interactively with the user (not applicable to dispatched subagent work)
|
|
6
|
+
|
|
7
|
+
<!-- include: ../../_partials/code-style.md / -->
|
|
8
|
+
|
|
9
|
+
<!-- include: ../../_partials/concision.md / -->
|
|
10
|
+
|
|
11
|
+
## Plain speech
|
|
12
|
+
|
|
13
|
+
<!-- include: ../../_partials/plain-speech.md / -->
|
|
14
|
+
|
|
15
|
+
<!-- include: ../../_partials/code-descriptions.md / -->
|
|
16
|
+
|
|
17
|
+
<!-- include: ../../_partials/file-access.md / -->
|
|
18
|
+
|
|
19
|
+
<!-- include: ../../_partials/shell-commands.md / -->
|
|
20
|
+
|
|
21
|
+
<!-- include: ../../_partials/live-repo-writes.md / -->
|
|
22
|
+
|
|
23
|
+
<!-- include: ../../_partials/technical-recommendations.md / -->
|
|
24
|
+
|
|
25
|
+
## Artifacts
|
|
26
|
+
|
|
27
|
+
When creating an artifact (plan, devlog, review, change summary, chat summary, etc.), invoke the `save-artifact` skill to resolve path and naming. Do not place artifacts in ad-hoc locations.
|
|
28
|
+
|
|
29
|
+
A saved artifact records what its author produced at that moment. Correct one that got its own subject wrong; never edit one toward what has happened since, and never report its divergence from current state as a defect or as a repair for the user to weigh.
|
|
30
|
+
|
|
31
|
+
Two artifacts are never edited once written, because a rewrite of either destroys evidence silently: `capture-lede-decision` reads the `pull-request` artifact's `## What` and the `merge` artifact's `## Body` to recover what was published. Each opens with a marker that directs a reading agent to give its own revision a new record and leave the original unedited.
|
|
32
|
+
|
|
33
|
+
That restraint on editing a record applies to the remote ticket as well, from the point its work is handed to implementation. Design comes before that point: `design-and-plan` refines a raw ticket, and it may rewrite any section or the whole ticket.
|
|
34
|
+
|
|
35
|
+
From that point on, the ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the work began, so they are never revised toward the outcome: A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. Report a divergence between one of those sections and the implementation in the pull-request description, whose job is to describe the change under review.
|
|
36
|
+
|
|
37
|
+
Acceptance criteria are the one revisable part, because they alone are the contract that an implementation can falsify. Align them to the implementation only when the two conflict, or when the gap would mislead a reviewer. Small improvements are made as a matter of course, and the ticket is not rewritten to pretend they were foreseen.
|
|
38
|
+
|
|
39
|
+
A write that this section rules out is not a skipped step, because nobody asked for it, and it does not produce any user-facing text: Do not mention the doctrine or the marker, do not report the write that was not made, and do not offer to reconcile the record with current state. When the user asks for such a write, decline it in one line and name the alternative: for a revision that you publish, a new record; for a divergence from the ticket, the pull-request description; for a lede that the records do not contain, `capture-lede-decision`'s `--agent-lede-file` and `--merged-lede-file`. A human's later edit to a published body does not need a record, because the `merge` record captures what merged.
|
|
40
|
+
|
|
41
|
+
## Commits
|
|
42
|
+
|
|
43
|
+
Invoke the `create-commit` skill to make a commit. It states the procedure: what to stage, one commit per logical unit of work, and how the title is rendered. The `consult-commit-conventions` skill states what the message is composed to -- the title and body conventions, the work-type taxonomy, and the branch-naming format -- and is worth consulting on its own before writing a message by hand.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
<!-- readme-type: content -->
|
|
2
|
+
|
|
3
|
+
# Helper scripts
|
|
4
|
+
|
|
5
|
+
Shared helpers installed into every platform target. The install pipeline copies (or symlinks) each `.sh` and `.mjs` file in this directory into `~/<platform_home>/scripts/` (e.g., `~/.claude/scripts/`, `~/.codex/scripts/`).
|
|
6
|
+
|
|
7
|
+
This directory contains two kinds of helper, distinguished by who invokes them:
|
|
8
|
+
|
|
9
|
+
- **Agent-invoked.** Helpers run by a skill or subagent, via the `{harness_home_dir}/scripts/` prefix documented below.
|
|
10
|
+
- **Harness-invoked.** Helpers wired into a harness's own configuration, without an agent in the loop.
|
|
11
|
+
|
|
12
|
+
The extension says how a helper is written, not who runs it: A `.sh` is a shell script kept in this directory, while a `.mjs` is a bundled TypeScript helper whose source is in `src/`. The bundles are tracked build output, generated here by `codeassembly bundle-helpers` from the `helpers:` list in `codeassembly-content.yaml`, so a source edit is committed together with its rebuilt bundle. Either kind serves either invoker.
|
|
13
|
+
|
|
14
|
+
Files of any other extension (such as this README) are not installed.
|
|
15
|
+
|
|
16
|
+
## Invocation convention
|
|
17
|
+
|
|
18
|
+
Agent-facing content must invoke these scripts using the `{harness_home_dir}/scripts/` template prefix:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill my-skill --interactive false` via Bash.
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
At install time, `{harness_home_dir}` expands to `~/.claude`, `~/.codex`, `~/.opencode`, or the equivalent per target platform, producing an explicit absolute path that the agent can execute.
|
|
25
|
+
|
|
26
|
+
Bare invocations (e.g., `` Run `resolve-frontmatter.sh ...` ``) do not resolve at runtime: The install directory is not on `$PATH`, and only `feedback-memories.sh` is symlinked into `/usr/local/bin`. An agent that encounters a bare invocation typically guesses a path and fails before succeeding, wasting tool calls.
|
|
27
|
+
|
|
28
|
+
Prose mentions of script names that are not invocations (e.g., ``"the `describe-change.mjs` script renders titles"``) do not need the prefix. `validate` recognizes an invocation by what surrounds the name: a flag, line continuation, quoted argument, shell variable, or shell operator after it, or an interpreter word (`bash`, `node`, `sh`, `source`, `zsh`) directly before it. Write a bundle's invocation as `node <path> <subcommand>`, which the interpreter word marks.
|
|
29
|
+
|
|
30
|
+
## Scripts
|
|
31
|
+
|
|
32
|
+
- `describe-change.mjs`: Renders titles for commits, tickets, PRs, and merges from declarative templates, the `{breaking}` marker included, reads a rendered title back into its parts, consolidates a commit range's entries into a consolidated record, applies overrides to a record, renders the fenced `change-record` block that ends a pull-request body and the `## Details` body of a change summary, and resolves what a pull request merges as from that block and the pull request's commits. Invoke it as `node {harness_home_dir}/scripts/describe-change.mjs <subcommand>`, where [title-templates.md](../skills/_data/title-templates.md#invoking-the-bundle) names the subcommand for each; the bundle does not have a shebang.
|
|
33
|
+
- `get-ticket-id.sh`: Extracts a ticket ID from a branch name.
|
|
34
|
+
- `manage-jira-ticket.mjs`: Resolves the project key and issue type for a Jira work item from the repository's `.agents/preferences.yaml` (`resolve-target`), converts a Markdown body to ADF with task lists as native task items (`convert-body`), and creates a work item through `acli` exactly once, checking its parent first (`create`). Invoke it as `node {harness_home_dir}/scripts/manage-jira-ticket.mjs <subcommand>`.
|
|
35
|
+
- `resolve-review-run.mjs`: Finds a ticket's active review run (its newest `interactive` run directory), opens it for a new review by creating one when none exists, or finds the newest reviewer or overseer review in it. Invoke it as `node {harness_home_dir}/scripts/resolve-review-run.mjs active|open|latest`.
|
|
36
|
+
- `resolve-frontmatter.sh`: Emits canonical artifact frontmatter (YAML or JSON) with provenance, ticket, branch, commit, and PR fields, plus scalar and list extension keys.
|
|
37
|
+
- `select-lede-exemplars.mjs`: Selects author-approved ledes of a given work type from the lede-decision corpus, optionally floored at a quality rating. `--with-pair` reports each record's agent lede, merged lede, and author comment alongside the approved text.
|
|
38
|
+
|
|
39
|
+
## Drift detection
|
|
40
|
+
|
|
41
|
+
`codeassembly validate` walks every `.md` file under `skills/` and `subagents/` and reports each executable invocation of a known helper script that lacks the `{harness_home_dir}/scripts/` prefix. Every file directly in this directory other than Markdown is a known script, so a new script is covered once it is added here.
|