codeassembly-guidance 0.2.0 β 0.4.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 +291 -0
- package/CHANGELOG.md +82 -0
- package/README.md +20 -121
- package/content/_partials/README.md +19 -3
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/cli-conventions.md +16 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
- package/content/guidance/rulebooks/commit-conventions.md +3 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +31 -4
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +69 -69
- package/content/scripts/manage-jira-ticket.mjs +73 -73
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/scripts/validate-preferences.mjs +1 -1
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +24 -3
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +12 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/title-templates.md +3 -1
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/next-steps-after-plan.md +1 -1
- package/content/skills/_partials/option-format.md +2 -2
- package/content/skills/_partials/plan-template.md +4 -2
- package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +3 -1
- package/content/skills/capture-event/SKILL.md +2 -0
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/collaborate/SKILL.md +2 -2
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +4 -1
- package/content/skills/create-pr/SKILL.md +2 -1
- package/content/skills/create-ticket/SKILL.md +3 -7
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
- package/content/skills/design-and-plan/SKILL.md +5 -9
- package/content/skills/implement-plan/SKILL.md +2 -2
- package/content/skills/index-prototypes/SKILL.md +1 -1
- package/content/skills/kb-add/SKILL.md +2 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/SKILL.md +2 -0
- package/content/skills/kb-edit/kb-edit.mjs +59 -59
- package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
- package/content/skills/kb-retrieve-events/SKILL.md +19 -10
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
- package/content/skills/kb-update-events/SKILL.md +9 -6
- package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/review-branch/SKILL.md +350 -1
- package/content/skills/revise-prose/revise-prose.mjs +103 -103
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/streamline-guidance/SKILL.md +10 -15
- package/content/skills/streamline-guidance/streamline-guidance.mjs +74 -74
- package/content/skills/summarize-change/SKILL.md +1 -1
- package/content/skills/testing-conventions/SKILL.md +7 -1
- package/content/skills/triage-feedback/SKILL.md +135 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +6 -6
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
- package/content/skills/update-project-guidance/SKILL.md +10 -10
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +86 -0
- package/content/subagents/lesson-clusterer.md +68 -0
- package/package.json +13 -13
- package/schemas/preferences.v1.json +22 -6
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
|
@@ -25,13 +25,27 @@ Inline a spec **once per skill, as a section**, and point every use site at it w
|
|
|
25
25
|
|
|
26
26
|
Several skill bodies (`collaborate`, `design-and-plan`, and `refine-plan` among them) contain a pointer to the option-format rules at their question-asking steps, duplicating the universal rule in `AGENTS.md`. That duplication is intentional, and a DRY-driven refactor must not strip it. The rule and its rationale are stated in the repo-local `codeassembly-repo-conventions` rulebook (`.agents/content/guidance/rulebooks/`), under "Skill-local reinforcement".
|
|
27
27
|
|
|
28
|
+
## When content becomes a partial
|
|
29
|
+
|
|
30
|
+
A partial exists to share text. Content becomes a partial when two or more files include it, another partial or a `_data` doc counting as a file that includes it, and a partial that only one file includes is inlined back into that file. Write a doctrine in its one host until a second file needs it.
|
|
31
|
+
|
|
32
|
+
Partials that the same files include are one partial when every one of those files includes them at one point, with none of its own text between them. When a host's own text separates them, they stay apart: Passing that text through the `<!-- children -->` slot would change the rendered whitespace, as [Verbatim slot substitution](#verbatim-slot-substitution) explains. The list below names each such group and the text that separates it.
|
|
33
|
+
|
|
34
|
+
`content/__tests__/partial-consumers.unit.test.ts` fails when a partial is included by fewer than two files, or when partials that the same files include are missing from the list.
|
|
35
|
+
|
|
36
|
+
### Partials kept apart
|
|
37
|
+
|
|
38
|
+
- `skills/_partials/ticket-skeleton.md`, `skills/_partials/ticket-composition.md`, `skills/_partials/ticket-criteria-conventions.md`: Each host closes the skeleton's code fence, which `design-and-plan` opens with a title line, before the composition; `create-ticket` adds its spike-mode paragraph there, and `align-ticket-with-implementation` its `## Guidance` heading. Each host then follows the composition with its own sentence on what _the implementation_ is.
|
|
39
|
+
- `skills/_partials/plan-template.md`, `skills/_partials/ticket-and-plan-completeness.md`: Each host places them in different sections.
|
|
40
|
+
- `skills/_partials/split-ticket-compose.md`, `skills/_partials/split-ticket-create.md`, `skills/_partials/split-launch-prompts.md`: Each host puts its own steps before and after `split-ticket-create.md`.
|
|
41
|
+
|
|
28
42
|
## Directive grammar
|
|
29
43
|
|
|
30
44
|
Three include shapes are recognized. Each must occupy a full line, with optional leading and trailing whitespace. That whitespace affects recognition alone; injected lines keep the partial's own indentation rather than the directive's, so a directive cannot appear inside a list item. Inline directives inside prose or code spans are not expanded.
|
|
31
45
|
|
|
32
46
|
| Shape | Syntax | Use |
|
|
33
47
|
| ------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
|
|
34
|
-
| Self-close | `<!-- include: path / -->` | Inline a partial without slot content (or use the partial's empty-slot defaults).
|
|
48
|
+
| Self-close | `<!-- include: path / -->` | Inline a partial without slot content (or use the partial's empty-slot defaults). |
|
|
35
49
|
| Open + close | `<!-- include: path -->` ... `<!-- /include -->` | Inline a partial and pass slot content into its `<!-- children -->` placeholder. |
|
|
36
50
|
| Children slot | `<!-- children -->` | Inside a partial: Marks where the caller's slot content is substituted. |
|
|
37
51
|
|
|
@@ -79,7 +93,7 @@ Partials are stored in `_partials/` directories. The directory is recognized at
|
|
|
79
93
|
|
|
80
94
|
- `content/_partials/`: Cross-cutting partials shared across skills, subagents, and platform guidance.
|
|
81
95
|
- `content/skills/_partials/`: Partials shared across skills.
|
|
82
|
-
- `content/skills/{name}/_partials/`: Partials
|
|
96
|
+
- `content/skills/{name}/_partials/`: Partials shared by one skill's own files.
|
|
83
97
|
|
|
84
98
|
The `_partials` directory itself never appears in installed output.
|
|
85
99
|
|
|
@@ -108,7 +122,7 @@ When a placeholder names a tool outside that set, the rewriter aborts install wi
|
|
|
108
122
|
|
|
109
123
|
**Authoring guidance:**
|
|
110
124
|
|
|
111
|
-
- Use `{tool:NAME}` for body prose that names a tool
|
|
125
|
+
- Use `{tool:NAME}` for body prose that names a tool _as a tool_, not for English verbs ("Read the file", "Write a paragraph", "Read project guidelines" are not migrated).
|
|
112
126
|
- Preserve surrounding context: `` `Write` `` becomes `` `{tool:Write}` ``; bare `Write` becomes `{tool:Write}`.
|
|
113
127
|
- Do **not** use placeholders in frontmatter `tools:` values. Frontmatter is replaced wholesale by the overlay merger; placeholders there would create two overlapping mechanisms.
|
|
114
128
|
- The placeholder mechanism is body-only, applied to subagent and skill `.md` files. Guidance files (`content/guidance/`) are not passed through the rewriter.
|
|
@@ -119,6 +133,8 @@ When a partial contains `<!-- children -->`, expansion removes that line and ins
|
|
|
119
133
|
|
|
120
134
|
A consequence: Avoid placing blank lines on both sides of a `<!-- children -->` boundary. If the partial has a blank line above `<!-- children -->` and the caller's slot content begins with a blank line, the result is two consecutive blank lines.
|
|
121
135
|
|
|
136
|
+
Prettier sets part of that spacing on both sides: It puts a blank line after an open directive, so slot content begins with one, and it puts one before `<!-- children -->` unless a paragraph line precedes the placeholder. A partial that keeps its placeholder directly under a paragraph line therefore renders one blank line at the boundary, and any other placement renders two.
|
|
137
|
+
|
|
122
138
|
## Common patterns
|
|
123
139
|
|
|
124
140
|
### Bare self-close: No slot
|
|
@@ -4,6 +4,7 @@ Before reporting what a change did, read the change back, and repair what you fi
|
|
|
4
4
|
|
|
5
5
|
- **Claims.** Every statement about the change is read from the diff, not from what you set out to do. A claim that something was left unchanged needs the same evidence as a claim that something changed, and it is the one most often written from memory.
|
|
6
6
|
- **Reach.** What the edit moved beyond its target: a parallel enumeration of the same list elsewhere, such as a README mirroring the edited source doc; sibling wording invalidated by a rename or re-framing, in a test title, a function header, or a neighboring doc; declaration ordering after an insertion; and adjacent behavior that a changed guard now covers or stops covering.
|
|
7
|
+
- **Placement.** Each hunk that writes guidance or documentation states a fact only where the fact is defined, such as the config that declares it, the code, its owning README section, or a rulebook, and elsewhere points to that source. A list copied from a config, or a paragraph that restates a rulebook, is a copy that drifts.
|
|
7
8
|
- **Class.** When the change corrects a defect, the site that you were pointed at is a sample of its class. Audit the other members before reporting, or the next reviewer finds the one that you left.
|
|
8
9
|
|
|
9
10
|
A green gate is not this audit: A suite that passes reports that nothing broke, not that the record which you are about to write is true.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
A cluster whose events all predate a change to the guidance that governs its lesson is evidence about guidance that no longer exists: It does not show that the failure recurs under the current guidance. Before you judge a cluster's priority, check whether that guidance changed after the cluster's latest capture, `signals.latestCapturedAt` in the clusters file.
|
|
2
|
+
|
|
3
|
+
Check each artifact that states or should state the lesson: the target, every artifact that your search found stating the lesson, and every partial that one of them includes.
|
|
4
|
+
|
|
5
|
+
1. Find the artifact's source file in the repository that owns it. A guidance-library artifact's source is under `packages/guidance/content/` in the CodeAssembly repository, at its path relative to the content root, such as `subagents/entry-drafter.md`.
|
|
6
|
+
2. List the commits on the owning repository's default branch that touched the source file after the latest capture: `gh api 'repos/{owner}/{repo}/commits?path={path}&since={latestCapturedAt}' --jq '.[] | [.sha[0:8], .commit.committer.date, (.commit.message | split("\n")[0])] | @tsv'`. Only when `gh` cannot reach the repository, read a local clone of it at its remote's default branch, never at the checked-out branch, which may predate the change: `git -C {clone} log --first-parent --since={latestCapturedAt} --format='%h %cs %s' origin/HEAD -- {path}`. The clone shows history only up to its last fetch.
|
|
7
|
+
3. Read the message of each listed commit, with `gh api repos/{owner}/{repo}/commits/{sha} --jq .commit.message`, or with `git -C {clone} show --no-patch --format=%B {sha}` on the fallback route. A commit changed the guidance when it changed what the artifact tells the agent to do about the lesson. A commit that only repairs prose, reformats, or renames does not.
|
|
8
|
+
|
|
9
|
+
The guidance changed after the latest capture when at least one commit changed it; name the latest such commit by its short SHA, date, and subject. Otherwise, it did not change.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
## Standard tags
|
|
2
|
+
|
|
3
|
+
Every knowledge store shares these tags. Tag a record's disposition with one of these names, never with a variant spelling:
|
|
4
|
+
|
|
5
|
+
- `deferred`: Reviewed and set aside, to surface again later rather than act on now.
|
|
6
|
+
- `obsolete`: Valid when recorded, but no longer applies.
|
|
7
|
+
- `rejected`: Judged incorrect, or declined.
|
|
@@ -51,6 +51,14 @@ helpers:
|
|
|
51
51
|
out: skills/review-gh-pr/select-pr-ticket.mjs
|
|
52
52
|
- entry: ../src/resolve-ticket-target/cli.ts
|
|
53
53
|
out: skills/create-ticket/resolve-ticket-target.mjs
|
|
54
|
+
- entry: ../src/assess-code-health/cli.ts
|
|
55
|
+
out: skills/assess-code-health/assess-code-health.mjs
|
|
56
|
+
- entry: ../src/curate-feedback/cli.ts
|
|
57
|
+
out: skills/curate-feedback/curate-feedback.mjs
|
|
58
|
+
- entry: ../src/lesson-clusters/cli.ts
|
|
59
|
+
out: skills/lesson-clusters/lesson-clusters.mjs
|
|
60
|
+
- entry: ../src/triage-feedback/cli.ts
|
|
61
|
+
out: skills/triage-feedback/triage-feedback.mjs
|
|
54
62
|
- entry: ../src/triage-spike-findings/cli.ts
|
|
55
63
|
out: skills/triage-spike-findings/triage-spike-findings.mjs
|
|
56
64
|
- entry: ../src/check-branch-currency/cli.ts
|
|
@@ -28,7 +28,7 @@ The skills belong here on different grounds. A rulebook of the personal collecti
|
|
|
28
28
|
|
|
29
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
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,
|
|
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, progress reports, and check results, 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
32
|
|
|
33
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
34
|
|
|
@@ -8,7 +8,7 @@ This README is for maintainers of this directory. It is not referenced by any `<
|
|
|
8
8
|
|
|
9
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
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
|
|
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, `content/__tests__/doctrine-reach.unit.test.ts` asserts that each section reaches its carriers, and `content/__tests__/shared-doctrine-reach.unit.test.ts` asserts that it reaches no other subagent and the order in which the sections render.
|
|
12
12
|
|
|
13
13
|
## Ambient delivery: Harness regions
|
|
14
14
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
slug: cli-conventions
|
|
3
|
-
description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, JSON output, progress and outcome reports, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
|
|
3
|
+
description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, JSON output, progress and outcome reports, check results, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
|
|
4
4
|
delivery: skill
|
|
5
|
-
version: '
|
|
5
|
+
version: '5'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# CLI conventions
|
|
@@ -151,6 +151,20 @@ Example, for `<bin> deploy`:
|
|
|
151
151
|
- β `<bin> deploy: deployed 20261012-142530Z-a10a17e`
|
|
152
152
|
- β
One line for each step (pull, build, stage, restart, readiness check), then `<bin> deploy: replaced 20261009-091200Z-4c2e8b1 with 20261012-142530Z-a10a17e (3 commits)`
|
|
153
153
|
|
|
154
|
+
## Check results
|
|
155
|
+
|
|
156
|
+
These rules apply to a command that checks state without changing it: a `check` or `verify` mode, a health probe, a pre-flight.
|
|
157
|
+
|
|
158
|
+
- **Each item's line states what it checked and the state that it found**, on a pass as well as on a failure. A bare `PASS` does not say what was compared with what, so a reader cannot tell a check that verified something from one that compared nothing.
|
|
159
|
+
- **A failure shows its evidence in the default output**: a diff for a file compared with its definition, the actual state otherwise. A reader who sees only the verdict must run the check again, or reproduce it by hand, to learn what is wrong.
|
|
160
|
+
- **A check whose items read only configuration also probes the function that the configuration serves, end to end.** Configuration that matches its definition does not show that the service works: A resolver can match its config file and still fail to answer a query.
|
|
161
|
+
- **`--verbose` adds only detail too long to print on every run.** The per-item lines and a failure's evidence belong in the default output. The exit code stays the contract for scripts, as "Exit codes" states.
|
|
162
|
+
|
|
163
|
+
Example, for `<bin> check` on a host whose hosts file matches its definition and whose resolver config does not:
|
|
164
|
+
|
|
165
|
+
- β `PASS hosts`, then `FAIL resolver`
|
|
166
|
+
- β
`PASS hosts: /etc/hosts matches hosts.conf`, then `FAIL resolver: /etc/resolv.conf differs from resolver.conf`, followed by the diff
|
|
167
|
+
|
|
154
168
|
## Color
|
|
155
169
|
|
|
156
170
|
- **Color and other terminal styling appear only when the stream is a terminal.** Escape codes written to a file or a pipe corrupt the text that the reader receives.
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
slug: codeassembly-content-specification
|
|
3
|
-
description: The declaration contract and authoring doctrine for CodeAssembly skills, subagents, rulebooks, and collections -- frontmatter, dependencies, invocation tokens, how broad a guidance change goes, and when a procedure belongs in a helper.
|
|
3
|
+
description: The declaration contract and authoring doctrine for CodeAssembly skills, subagents, rulebooks, and collections -- frontmatter, dependencies, invocation tokens, how broad a guidance change goes, which kind of artifact it goes in, and when a procedure belongs in a helper.
|
|
4
4
|
standalone: wanted by repositories that author CodeAssembly content, which declare it directly
|
|
5
5
|
delivery: skill
|
|
6
|
-
version: '
|
|
6
|
+
version: '32'
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# CodeAssembly content specification
|
|
@@ -157,6 +157,23 @@ A proposal justifies its breadth rather than assuming it. A contributing surface
|
|
|
157
157
|
|
|
158
158
|
Before making any change to a guidance file, identify whether the new text makes any existing text redundant (whether in that file or any other) and trim the redundancy in the same change. If the file is larger after the change than before, offer to run {skill:streamline-guidance} against it. _(Convention; not enforced.)_
|
|
159
159
|
|
|
160
|
+
## Choosing a kind
|
|
161
|
+
|
|
162
|
+
A lesson goes into the kind of artifact that puts it in the agent's context at the moment the agent needs it:
|
|
163
|
+
|
|
164
|
+
- An `ambient` rulebook: a rule that nearly every session needs, per the `delivery` row of "Frontmatter fields".
|
|
165
|
+
- A `skill`-delivered rulebook: a rule that a class of tasks consults, such as the conventions for a commit message.
|
|
166
|
+
- A `hook`-delivered rulebook: local taste that a project or a machine binds, as "Guidance hooks" states.
|
|
167
|
+
- A skill: a procedure that runs when it is invoked.
|
|
168
|
+
- A subagent: work that needs a context of its own, such as a review that must not share the author's view.
|
|
169
|
+
- A partial: text that two or more artifacts must contain. `content/_partials/README.md` states when content becomes a partial and when it stays in a `_data/` document.
|
|
170
|
+
- A section of a repository's `AGENTS.md`: a fact about that one repository that every session in it needs.
|
|
171
|
+
- A helper: a step whose result is fixed by its inputs, as "Procedures in helpers" states.
|
|
172
|
+
|
|
173
|
+
A lesson specific to one repository belongs in that repository's own content root or its `AGENTS.md`; any other lesson belongs in the library.
|
|
174
|
+
|
|
175
|
+
When an existing rule already states the lesson, change that rule rather than add a parallel one, which would leave two statements to drift apart. Strengthen its wording when the agent reads the rule and still misses it; relocate it, or restate it at the step at which the agent acts, when the agent does not have it in context at that step; illustrate it with an example when the agent follows the directive but produces the wrong shape. _(Convention; not enforced.)_
|
|
176
|
+
|
|
160
177
|
## Procedures in helpers
|
|
161
178
|
|
|
162
179
|
A step whose result is fixed by its inputs belongs in a helper that emits JSON, and the skill or subagent invokes the helper and reads its output. Such steps include parsing a file or a command's output, walking a fallback cascade, matching by pattern or timestamp, and converting a format. A prose description of such a step is a copy that the agent re-executes on every run, and it drifts from any helper that performs the same step. Judgment stays in prose: choosing among options, composing text, and deciding what a result means.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: commit-conventions
|
|
3
3
|
description: Commit title and body conventions, the work-type taxonomy, and branch naming. Consult before writing a commit message or naming a branch.
|
|
4
4
|
delivery: skill
|
|
5
|
-
version: '
|
|
5
|
+
version: '11'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Git commit conventions
|
|
@@ -15,9 +15,10 @@ A commit on the default branch is extracted into the changelog and, for release-
|
|
|
15
15
|
|
|
16
16
|
## Commit title
|
|
17
17
|
|
|
18
|
-
Voice, length, content discipline, and the ticket-reference rule are stated in [`title-voice.md`](../../skills/_data/title-voice.md), which governs the authored string across every surface into which it is rendered.
|
|
18
|
+
Voice, length, content discipline, and the ticket-reference rule are stated in [`title-voice.md`](../../skills/_data/title-voice.md), which governs the authored string across every surface into which it is rendered. Three rules are commit-specific:
|
|
19
19
|
|
|
20
20
|
- Render via `describe-change.mjs`; see [`title-templates.md`](../../skills/_data/title-templates.md) for the full template syntax, supported tokens, and rendering pipeline.
|
|
21
|
+
- Take the title's format from the configured `commit.title_format` alone. When that template is empty or unset, the title is the bare title text. Never infer a format from `git log` or from other commits: The default branch's subjects are squash-merge titles rendered by `merge.title_format`, and earlier branch commits may have been written by hand. A rendered title that differs from earlier commits is not a defect.
|
|
21
22
|
- Mark breaking changes by appending `!` to the work type: `agents|feat!: Remove deprecated API`. See [Breaking changes](#breaking-changes) below for which types are eligible.
|
|
22
23
|
|
|
23
24
|
## Ticket ID
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-collaboration-preferences
|
|
3
3
|
description: William Thorsen's personal preferences for how an agent collaborates -- the persona that it adopts, and the form that its prompts take.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '16'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's collaboration preferences
|
|
@@ -24,6 +24,8 @@ Perform every step yourself, at design, planning, execution, and review time ali
|
|
|
24
24
|
|
|
25
25
|
Never hand a step over because of a sandbox denial alone: Treat the denial as a case for rung 2 or rung 3. Verify yourself: Run a check that a command, a test, or a browser could settle rather than ask for it, and cut a check whose observable outcome a test or an earlier gate already asserts rather than run it or ask for it. When a blocker remains after you climb the ladder, report what the weaker evidence shows rather than report the step as done.
|
|
26
26
|
|
|
27
|
+
A question receives an answer, not a procedure for the developer to run: When the developer asks what something is or why it behaves as it does, explain it, and when the answer needs a check, run the check and report what it shows. The records of a step, such as a log entry or a ticket comment, are never handed over. Count the commands that you hand over across the session, not per turn: Each one is a cost that the developer pays, and a design that needs one on each machine is a defect to raise at design time, per the "Who applies the change" section of design priorities.
|
|
28
|
+
|
|
27
29
|
Hand over a part that takes more than one command as one paste-ready script, which runs every step, cleans up after itself, and prints only the facts that you need, so that the developer pastes once and replies once. Never build up a check by asking for one command per turn. When the developer's shell can read your files, also write the script to a file and give its path, so that the developer can rerun the check without pasting it again. Before running or handing over a check of a GUI application, confirm which machine your commands run on, such as by comparing `hostname` with the machine that displays the application, rather than assume that the two are the same.
|
|
28
30
|
|
|
29
31
|
The handoff has a recognizable sign. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. Give a decision your recommendation and its reason, per "Prompt formatting" below, and take a task up the ladder. Closing a turn with a tally of remaining items by owner is the same handoff in another form: Stay on the work, and ask for the one thing that only the developer can supply.
|
|
@@ -34,7 +36,7 @@ Mark the options before asking, and read the markers: Render a menu only when th
|
|
|
34
36
|
|
|
35
37
|
The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not hold any evidence, which includes a templated next-steps menu. Decide everything else yourself by default; verification is never in the class. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it.
|
|
36
38
|
|
|
37
|
-
Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the checkpoint. In a skill without a phase structure, or in work outside a skill, treat the skill's own approval gate, or the end of the work, as the checkpoint. Collect the asks that survive the gate into one review at the checkpoint, never one per turn. Write every decision that you take in place of an ask into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan; a silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with
|
|
39
|
+
Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the checkpoint. In a skill without a phase structure, or in work outside a skill, treat the skill's own approval gate, or the end of the work, as the checkpoint. Collect the asks that survive the gate into one review at the checkpoint, never one per turn. Write every decision that you take in place of an ask into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan; a silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with π², in the record and in a turn's narrative alike, and drop the marker once the developer approves the checkpoint at which you presented the decision.
|
|
38
40
|
|
|
39
41
|
Never rank the options by your own elapsed time, round trips, or effort. You measure these costs yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the cost, render the options unmarked, and put the choice at the checkpoint.
|
|
40
42
|
|
|
@@ -42,6 +44,8 @@ An ask costs the developer a context switch and idles the session until the answ
|
|
|
42
44
|
|
|
43
45
|
End every response that asks for something with a labelled action-items block that contains every ask and nothing else; when a skill defines its own canonical block for asks, use that block instead. Prose above may discuss; only the block may ask. Before ending a turn, sweep the draft for anything that invites a response: A soft offer -- "let me know if", "say the word and I will", "worth knowing", "I can also" -- is an ask, and leaving it in the narrative is how asks get missed. So is an environment blocker that remains once you climb the ladder in "Handoffs": Ask for the resource that its third rung names, and a blocker left in the prose is a defect. Do not add a block to a response without an ask. When the block has more than one ask, or more than one independently-numbered list, label each with its identifier (`A` for an action, `Q` for a question); a single ask needs none. Full spec: [action-items.md](../../skills/_data/action-items.md).
|
|
44
46
|
|
|
47
|
+
When the developer signals overload, such as "I can't do this any more" or a count of the commands that they have run, stop adding asks: Do what you can, say once what is left undone, and end the turn without an ask and without an action-items block. Hold that mode in every later turn until the developer asks for something.
|
|
48
|
+
|
|
45
49
|
When prompting the user for input, never use interactive UI controls (pop-up, arrow-key, or structured-choice selectors); use plain text, with options as a numbered list. Use visual markers to make prompts more noticeable:
|
|
46
50
|
|
|
47
51
|
- **Confirmation prompts** (the user's response is approve-or-redirect; "no" means "let's adjust or discuss," not a concrete alternative action): End with `ππΌππΌ`.
|
|
@@ -30,7 +30,34 @@ Read what appears left of the colon. A label (such as a short tag naming a field
|
|
|
30
30
|
|
|
31
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
32
|
|
|
33
|
-
|
|
33
|
+
## Reduced object relatives
|
|
34
|
+
|
|
35
|
+
<!-- rule: reduced-object-relative 1 -->
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
**Repairs, in preference order.** Choose per site; restored relativizers stacked across a passage read as a tic of their own.
|
|
40
|
+
|
|
41
|
+
1. **Reduce to a passive participle** if the actor is worth naming: "a dependency imported by every exported tier module".
|
|
42
|
+
2. **Restore the relativizer** if the passive reads worse: "the ticket that the branch name encodes".
|
|
43
|
+
3. **Recast** if neither fits: Promote the embedded clause to a main clause, or replace the relative with a prepositional phrase.
|
|
44
|
+
|
|
45
|
+
**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.
|
|
46
|
+
|
|
47
|
+
**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.
|
|
48
|
+
|
|
49
|
+
**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".
|
|
50
|
+
|
|
51
|
+
**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.
|
|
52
|
+
|
|
53
|
+
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.
|
|
54
|
+
2. **Definite noun phrase**: "the ticket the branch name encodes".
|
|
55
|
+
3. **Bare noun**: "an idiom developers recognize".
|
|
56
|
+
4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
|
|
57
|
+
|
|
58
|
+
**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.
|
|
59
|
+
|
|
60
|
+
**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.
|
|
34
61
|
|
|
35
62
|
## Second person
|
|
36
63
|
|
|
@@ -4,7 +4,13 @@
|
|
|
4
4
|
|
|
5
5
|
- Invoke the `collaborate` skill when working interactively with the user (not applicable to dispatched subagent work)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Style
|
|
8
|
+
|
|
9
|
+
- Follow `.editorconfig`, and fill new comments to its `max_line_length`.
|
|
10
|
+
- Order lists and collections logically (alphabetically unless there is a good reason to sort or group differently).
|
|
11
|
+
- Use long-form CLI options (`--force`, not `-f`) in generated commands and scripts.
|
|
12
|
+
- Structure code so that the primary logic comes first; place helper functions at the end.
|
|
13
|
+
- Name functions with a leading verb (`show_usage`, not `usage`; `build_payload`, not `payload`).
|
|
8
14
|
|
|
9
15
|
<!-- include: ../../_partials/concision.md / -->
|
|
10
16
|
|
|
@@ -12,13 +18,28 @@
|
|
|
12
18
|
|
|
13
19
|
<!-- include: ../../_partials/plain-speech.md / -->
|
|
14
20
|
|
|
15
|
-
|
|
21
|
+
## Code descriptions
|
|
22
|
+
|
|
23
|
+
- Every function, method, class, and component gets a brief description. One line is usually enough.
|
|
24
|
+
- Do not repeat information already provided by the signature (parameter names, types, return types). In languages with doc-tag conventions (`@param`, `@returns`, `:param`, `Args:`, etc.), omit them: The description alone is sufficient.
|
|
16
25
|
|
|
17
26
|
<!-- include: ../../_partials/file-access.md / -->
|
|
18
27
|
|
|
19
28
|
<!-- include: ../../_partials/shell-commands.md / -->
|
|
20
29
|
|
|
21
|
-
|
|
30
|
+
## Don't test write operations against a live repo
|
|
31
|
+
|
|
32
|
+
Never exercise destructive or side-effecting operations against the user's working repo as verification. If a script's behavior requires running a command that mutates git state (`git tag`, `git commit`, `git push`, `git branch`, `git reset`, `git rebase`), file state, package state, or any other shared resource, exercise it in a disposable environment: a scratch directory (`mktemp -d "${TMPDIR:-/tmp}/probe.XXXXXX"`, since bare `mktemp -d` picks a path denied by the agent sandbox and then leaves the variable empty), a fresh `git init` with minimal fixtures, or a container.
|
|
33
|
+
|
|
34
|
+
Write absolute paths beneath that directory rather than changing into it and writing relative ones, unless the change of directory is chained to the creation succeeding, as `enter_tmpdir` is. `cd ""` returns 0, so a failed `mktemp` otherwise sends every later write into the working repo, which is the outcome that this rule exists to prevent.
|
|
35
|
+
|
|
36
|
+
Why it matters:
|
|
37
|
+
|
|
38
|
+
- Other sessions, file watchers, CI, release tooling, or IDE extensions on the user's machine can observe in-progress mutations, even if you intend to clean up after.
|
|
39
|
+
- Some projects treat new tags/commits as release signals. Once the artifact exists, downstream effects may fire before you can undo it; some release configurations are immutable (published tags produce permanent artifacts).
|
|
40
|
+
- "I can just clean up afterward" is not a substitute for never creating the artifact: Between create and cleanup, anything else on the machine can act on it.
|
|
41
|
+
|
|
42
|
+
Read-only exercises (`--dry-run`, help text, preview tables, `--list`, exit-code checks on pure-read commands) are safe in the working repo. Anything that writes, even "just for a second", is not.
|
|
22
43
|
|
|
23
44
|
<!-- include: ../../_partials/technical-recommendations.md / -->
|
|
24
45
|
|
|
@@ -42,10 +63,16 @@ Acceptance criteria are the one revisable part, because they alone are the contr
|
|
|
42
63
|
|
|
43
64
|
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.
|
|
44
65
|
|
|
66
|
+
## Documentation placement
|
|
67
|
+
|
|
68
|
+
A fact goes where it is defined: in the config that declares it, the code that implements it, the README section that owns it, or the rulebook that states it. When prose that you write into a file read for guidance, such as `AGENTS.md`, a README, `docs/`, or a rulebook, needs such a fact, write a pointer to its source and add only what the source does not state. A copy drifts from its source, and nothing reports the drift.
|
|
69
|
+
|
|
70
|
+
Look for the source in two places before writing the fact: the repository's own files, and the guidance that the harness loads into every session in the repository, which includes the global guidance file, the rulebooks rendered into it, and the project's guidance files. A copy shows itself as a list whose entries mirror a config's entries, such as the hosts that a tool's user config declares, as a value taken from a config, or as a paragraph that restates a rulebook. A copy that a repository maintains on purpose, such as a mirror that a check keeps in sync, is outside this rule.
|
|
71
|
+
|
|
45
72
|
## Authorship
|
|
46
73
|
|
|
47
74
|
Agents write most of what appears under the developer's account, so a creator, reporter, or author field shows which account made an item, not who wrote it. Never infer from such a field that the developer wrote an item, and never rest a conclusion on that premise unless the developer has said so. When provenance matters, say that the item was created under the developer's account and trace its content to a source; otherwise omit attribution.
|
|
48
75
|
|
|
49
76
|
## Commits
|
|
50
77
|
|
|
51
|
-
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.
|
|
78
|
+
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. A title rendered from the configured template is correct: Never propose changing it to match other commits, and do not comment on whether it contains a ticket reference.
|