codeassembly-guidance 0.1.0 → 0.3.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 +984 -0
- package/CHANGELOG.md +240 -0
- package/README.md +45 -99
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +21 -5
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +17 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +206 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
- package/content/guidance/rulebooks/commit-conventions.md +5 -4
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +39 -4
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +98 -98
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +64 -16
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +15 -4
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +22 -12
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +11 -11
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +7 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
- package/content/skills/anti-patterns/SKILL.md +1 -1
- 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 +98 -0
- package/content/skills/capture-event/SKILL.md +4 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +3 -3
- 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 +28 -10
- package/content/skills/create-pr/SKILL.md +7 -6
- package/content/skills/create-ticket/SKILL.md +64 -23
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
- package/content/skills/design-and-plan/SKILL.md +17 -18
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +27 -23
- package/content/skills/index-prototypes/SKILL.md +86 -31
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +4 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +5 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
- package/content/skills/kb-retrieve-events/SKILL.md +20 -11
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
- package/content/skills/kb-update-events/SKILL.md +10 -7
- package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +2 -2
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +354 -3
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +3 -1
- package/content/skills/streamline-guidance/SKILL.md +11 -16
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +23 -14
- package/content/skills/testing-conventions/SKILL.md +81 -8
- package/content/skills/triage-feedback/SKILL.md +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +12 -12
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/feedback-triage-challenger.md +81 -0
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/lesson-clusterer.md +68 -0
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +21 -17
- package/schemas/preferences.v1.json +50 -7
- 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
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -1,8 +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
|
+
standalone: wanted by repositories that author CodeAssembly content, which declare it directly
|
|
4
5
|
delivery: skill
|
|
5
|
-
version: '
|
|
6
|
+
version: '32'
|
|
6
7
|
---
|
|
7
8
|
|
|
8
9
|
# CodeAssembly content specification
|
|
@@ -13,7 +14,7 @@ The declaration contract for CodeAssembly artifacts -- skills, subagents, rulebo
|
|
|
13
14
|
|
|
14
15
|
Every rule below belongs to one of three classes, marked where it appears.
|
|
15
16
|
|
|
16
|
-
**Validated on parse.** A malformed `slug` or `skill-name`, a `delivery` value outside `ambient`/`hook`/`skill`, an empty `delivery` list, an unknown artifact-type key, a non-list value under one,
|
|
17
|
+
**Validated on parse.** A malformed `slug` or `skill-name`, a rulebook without `delivery`, a `delivery` value outside `ambient`/`hook`/`skill`, an empty `delivery` list, an unknown artifact-type key, a non-list value under one, a `members:` block or a `disposition:` on anything but a collection, and a `standalone:` on a collection each fail the run with an error naming the source file. Seven more fail outside the parser: a token naming an artifact that does not exist fails the run with an error naming the slug and the directories searched, whether it names that artifact as a dependency or optionally; a rulebook link target outside a linkable root fails the run before anything is written; a rulebook token naming a target that does not deploy a skill to invoke fails the same pre-write pass, and so does a rulebook token written in the optional form, which does not have a name to render; an anchor-only link target that does not name any heading in its own body fails wherever that body is rendered or installed, and so does a code fence that nothing closes; and a harness that does not declare a sigil is a type error at its `HarnessConfig` literal, so the build fails.
|
|
17
18
|
|
|
18
19
|
**Enforced by `validate`.** `codeassembly validate` checks a content root against these rules without deploying it. Such a rule names `validate`.
|
|
19
20
|
|
|
@@ -45,13 +46,13 @@ Slugs are kebab-case and letter-led (`[a-z][a-z0-9-]*`). The sigils are a typed
|
|
|
45
46
|
|
|
46
47
|
A token is also a dependency edge: `sync` extracts the tokens from a rulebook's, skill's, or subagent's include-expanded body and pulls each target into the deploy closure. An inline invocation is therefore expressed once, as the token -- it does not need a duplicate `dependencies:` entry, and a token naming a non-existent artifact fails the run just as a missing `dependencies:` edge does. Because extraction runs on the include-expanded body, a token inside a shared `_partials` file becomes an edge for every artifact that inlines it.
|
|
47
48
|
|
|
48
|
-
A skill or subagent token has an optional form, marked `?` before the colon: `{skill?:<slug>}` and `{subagent?:<slug>}`. It renders exactly as the required form does, so an invocation reads the same wherever the target deploys. Its target must still exist: `sync` resolves one, and a rename or a deletion fails the run. Because it does not contribute an edge, the target deploys only if a declaration
|
|
49
|
+
A skill or subagent token has an optional form, marked `?` before the colon: `{skill?:<slug>}` and `{subagent?:<slug>}`. It renders exactly as the required form does, so an invocation reads the same wherever the target deploys. Its target must still exist: `sync` resolves one, and a rename or a deletion fails the run. Because it does not contribute an edge, the target deploys only if a declaration includes it some other way. Use it when a body names an artifact that a consumer may not want, such as a platform delegate for an ecosystem not used by the consumer.
|
|
49
50
|
|
|
50
51
|
`{rulebook?:<slug>}` fails the run: A rulebook token renders the skill name under which its target deploys, and an undeployed target supplies that name nowhere. `dependencies:` does not have an optional counterpart, because a frontmatter entry exists to pull an artifact in; a body that names one without pulling it in is the only case that the marker addresses. A content root declares content format 2 if any body that it contains, a `_partials` file included, uses an optional token. _(Enforced by `validate`.)_
|
|
51
52
|
|
|
52
53
|
A support entry under `skills/` does not contribute an edge: It is linked to rather than inlined, so `sync` never reads it. Each skill or subagent that links into the section containing a required `{skill:<slug>}` or `{subagent:<slug>}` token declares its target under `dependencies:`. An optional token there is exempt, since asserting the target may be absent is the opposite of guaranteeing its presence. The requirement depends on the fragment: A bare link to the file does not have a requirement, and a link to an enclosing heading has the requirements of its subsections. _(Enforced by `validate`, which also reports a support-entry token naming an artifact that the content root does not contain, optional or required.)_
|
|
53
54
|
|
|
54
|
-
Rulebooks, skills, and subagents all support tokens; collections do not have a body to render. `{rulebook:<slug>}` has one restriction that the others do not: It renders only if a declaration supplies the deployed rulebook set, which is true for every body that `sync` and `validate` render but not for a support entry under `skills/`, since a source's support entries
|
|
55
|
+
Rulebooks, skills, and subagents all support tokens; collections do not have a body to render. `{rulebook:<slug>}` has one restriction that the others do not: It renders only if a declaration supplies the deployed rulebook set, which is true for every body that `sync` and `validate` render but not for a support entry under `skills/`, since a source's support entries are delivered to every consumer of the source, whichever rulebooks that consumer declares. A rulebook token in a support entry fails the run, as does one naming a rulebook that does not deploy a skill -- an `ambient`-only target is already in the reader's context, so there is nothing to invoke. Express that relationship with `dependencies:` instead.
|
|
55
56
|
|
|
56
57
|
That boundary decides what a shared partial may contain. A partial inlined by both a skill body and a support entry cannot contain a `{rulebook:<slug>}` token: It renders in the skill but breaks the support entry's delivery.
|
|
57
58
|
|
|
@@ -87,7 +88,10 @@ A heading containing a token cannot be anchored: It renders to a different slug
|
|
|
87
88
|
|
|
88
89
|
## Collections
|
|
89
90
|
|
|
90
|
-
A collection's
|
|
91
|
+
A collection's payload is a `members:` block -- the constituents that it pulls into the deployed closure -- and an optional `disposition:`. List the members per type (the same shape that `dependencies:` uses), or name a computed token, which expands within the content root to which the collection belongs, the source from which it resolved:
|
|
92
|
+
|
|
93
|
+
- `'@library'`: every rulebook, skill, and subagent in that root.
|
|
94
|
+
- `'@unclaimed'`: every rulebook, skill, and subagent in that root that does not declare `standalone:` and is not enumerated by any collection with a `disposition:`. The root must declare content format 3 or later.
|
|
91
95
|
|
|
92
96
|
```yaml
|
|
93
97
|
members:
|
|
@@ -99,16 +103,35 @@ members:
|
|
|
99
103
|
|
|
100
104
|
`members:` is collections-only; rulebooks, skills, and subagents use `dependencies:` instead. Declaring `dependencies:` on a collection, or `members:` on any other type, is an error. The resolver follows both keys identically -- the split is semantic: A collection contains members, an artifact depends on prerequisites.
|
|
101
105
|
|
|
106
|
+
### Dispositions
|
|
107
|
+
|
|
108
|
+
A `disposition:` states what membership in a collection that enumerates its members claims about them, and `codeassembly validate` holds the root to that claim. A collection without one is a plain bundle: Its membership does not claim anything, so it neither covers an artifact nor conflicts with a disposition.
|
|
109
|
+
|
|
110
|
+
- `public`: Its members are generally fit. Its closure may reach only the members of public collections.
|
|
111
|
+
- `personal`: Its members are fitted to one author. Its closure may reach the members of personal and public collections.
|
|
112
|
+
- `opt-in`: Its members are fitted to one vendor ecosystem. Its closure may reach its own members and the members of public collections, and the closure of every other collection, other than an `'@library'` one, must not reach its members, so that only a consumer declaring it deploys them.
|
|
113
|
+
|
|
114
|
+
An artifact that is deliberately outside every collection declares `standalone:` in its own frontmatter, with the reason as the value. A collection must not enumerate it, and the closure of a collection, other than an `'@library'` one, must not reach it. An artifact that several collections claim is within a closure's reach when any one of its claims is. `disposition:` on a collection whose members are computed, `standalone:` on a collection, and `disposition:` on any other type are errors.
|
|
115
|
+
|
|
116
|
+
`validate` checks a root that declares a disposition, a standalone artifact, or an `'@unclaimed'` collection, and reports each of these as a `disposition` defect:
|
|
117
|
+
|
|
118
|
+
- a standalone artifact that a collection enumerates, or that the closure of a collection other than an `'@library'` one reaches
|
|
119
|
+
- a collection with a disposition whose closure reaches an artifact outside its reach
|
|
120
|
+
- a collection, other than an `'@library'` one, whose closure reaches a member of an opt-in collection other than itself
|
|
121
|
+
- in a root without an `'@unclaimed'` collection, an artifact that is not covered by any disposition
|
|
122
|
+
- a `disposition:` or `standalone:` value that cannot be read
|
|
123
|
+
|
|
102
124
|
## Frontmatter fields
|
|
103
125
|
|
|
104
|
-
- **Rulebooks:** `slug`, optional `description`,
|
|
105
|
-
- **Skills:** `name`, `description`, optional `user-invocable` (defaults to `true`), optional `supported-harnesses` (a harness id or list restricting deployment to those harnesses; absent deploys to all). The deploy writes every other key to every harness unchanged, so a key that only one harness reads, such as Claude's `context` or `model`,
|
|
126
|
+
- **Rulebooks:** `slug`, optional `description`, required `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; `ambient` only when nearly every session needs the content, since an ambient rulebook is loaded by every session that declares it, and `skill` or `hook` otherwise), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every route that delivers the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A route omits the line for a rulebook that does not declare a version. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
|
|
127
|
+
- **Skills:** `name`, `description`, optional `user-invocable` (defaults to `true`), optional `supported-harnesses` (a harness id or list restricting deployment to those harnesses; absent deploys to all). The deploy writes every other key to every harness unchanged, so a key that only one harness reads, such as Claude's `context` or `model`, is also written to the others, which ignore it.
|
|
106
128
|
- **Subagents:** `name`, `description`, optional `tools`, optional `disallowedTools`, optional `maxTurns`, optional `skills` (skills injected into the subagent's context), optional `rulebooks` (rulebooks injected the same way, named by slug rather than by deploy name, so that a `skill-name` override on the target stays correct). `sync` pulls both lists into the deploy closure, merges each injected rulebook's deploy name into the deployed `skills:`, and drops the `rulebooks:` key from what it writes.
|
|
107
|
-
- **Collections:** `name`, `description`,
|
|
129
|
+
- **Collections:** `name`, `description`, a `members:` block, and an optional `disposition`; see [Dispositions](#dispositions).
|
|
130
|
+
- **Rulebooks, skills, and subagents** also take an optional `standalone`, the reason that the artifact is outside every collection; see [Dispositions](#dispositions).
|
|
108
131
|
|
|
109
132
|
A subagent's tool grant is either named or inherited. `tools` names the grant outright; a subagent that omits it inherits the harness's whole subagent tool pool, and `disallowedTools` then removes names from whatever pool results. Use inheritance when the subagent needs a tool that an allowlist cannot name -- an MCP tool whose name varies by machine -- and weigh the consequence: A denylist names tools the same way an allowlist does, so it removes the listed names and nothing else. The residual grant is whatever the machine supplies, and the subagent's own instructions limit the rest. Choose inheritance when that residual is acceptable, and name a `tools` allowlist when it is not. Claude applies the denylist. Rovo does not read it, and its overlay names a `tools` allowlist for every subagent, so a subagent relying on inheritance states its Rovo grant in that overlay. _(Convention; not enforced.)_
|
|
110
133
|
|
|
111
|
-
Only the rulebook row is validated on parse; a `members:` block is validated wherever it appears. The other rows are read leniently: A field consumed by a deploy pass takes effect, and an absent one falls back to a default rather than failing. A skill without a `description` appears in Rovo's prompt index with an empty one. _(Convention; not enforced.)_
|
|
134
|
+
Only the rulebook row is validated on parse; a `members:` block is validated wherever it appears, and `validate` reads every `disposition` and `standalone` in the root. The other rows are read leniently: A field consumed by a deploy pass takes effect, and an absent one falls back to a default rather than failing. A skill without a `description` appears in Rovo's prompt index with an empty one. _(Convention; not enforced.)_
|
|
112
135
|
|
|
113
136
|
### Version bumps
|
|
114
137
|
|
|
@@ -134,6 +157,23 @@ A proposal justifies its breadth rather than assuming it. A contributing surface
|
|
|
134
157
|
|
|
135
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.)_
|
|
136
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
|
+
|
|
137
177
|
## Procedures in helpers
|
|
138
178
|
|
|
139
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
|
|
@@ -26,7 +27,7 @@ The branch name records the ticket. Include the ID at the end of the commit body
|
|
|
26
27
|
|
|
27
28
|
## Commit body
|
|
28
29
|
|
|
29
|
-
**Body voice.** The body is a source that the entry drafter reads, not an entry that a reader meets. Report what the commit did, completely and factually, and leave the selecting to the drafter: It drops what the change's reader would not act on. The drafter also reads the diff, so what the body adds is the intent behind an edit, which the hunks do not
|
|
30
|
+
**Body voice.** The body is a source that the entry drafter reads, not an entry that a reader meets. Report what the commit did, completely and factually, and leave the selecting to the drafter: It drops what the change's reader would not act on. The drafter also reads the diff, so what the body adds is the intent behind an edit, which the hunks do not show.
|
|
30
31
|
|
|
31
32
|
### Body mechanics
|
|
32
33
|
|
|
@@ -60,7 +61,7 @@ See [`work-types.json`](../../skills/_data/work-types.json) for the canonical ta
|
|
|
60
61
|
|
|
61
62
|
This section governs every work-type resolution: one commit, a multi-commit pull request, and a merge commit alike.
|
|
62
63
|
|
|
63
|
-
Pick the type that best describes the change's dominant purpose. A type applies only when the change meets that type's own description in `work-types.json`; a type whose description the change does not meet is
|
|
64
|
+
Pick the type that best describes the change's dominant purpose. A type applies only when the change meets that type's own description in `work-types.json`; a type whose description the change does not meet is excluded, and the tiebreak below never considers it. When more than one type genuinely applies, tiebreak in favor of the higher tier (public > internal > process), then by earlier listing within a tier. The tiebreak is not a promotion rule: Raising the tier raises both the audience and the strength of the claim.
|
|
64
65
|
|
|
65
66
|
The tiebreak resolves the type. Having applied it, act on the result: A rule that resolves an input determines it, and re-presenting its output as a choice spends the developer's attention on a settled decision. When the result looks wrong for a specific change, apply it, state the outcome and the reservation in one sentence, and continue.
|
|
66
67
|
|
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
slug: live-worktree-policy
|
|
3
3
|
description: How a repository with a `live` worktree deploys, and where changes to it are authored.
|
|
4
|
+
standalone: wanted in the repositories that have a `live` worktree, which declare it directly
|
|
4
5
|
delivery: ambient
|
|
5
|
-
version: '
|
|
6
|
+
version: '3'
|
|
6
7
|
---
|
|
7
8
|
|
|
8
9
|
# Live worktree policy
|
|
9
10
|
|
|
10
11
|
A repository that keeps a worktree on a `live` branch deploys from that worktree, and never from the main one. Deployed configuration, installed commands, and loaded extensions all resolve through it, so a path derived from the main worktree names a file that nothing on the machine reads.
|
|
11
12
|
|
|
12
|
-
Because `git worktree list` reports every worktree of a repository from any one of them, a `live` row identifies a participating repository and gives the deployment worktree's path in the same line. That worktree is named `{path}.live`, where `{path}` is the main worktree's path: `~/repos/projects/codeassembly` is accompanied by `~/repos/projects/codeassembly.live`. If the machine has the repo registry, `
|
|
13
|
+
Because `git worktree list` reports every worktree of a repository from any one of them, a `live` row identifies a participating repository and gives the deployment worktree's path in the same line. That worktree is named `{path}.live`, where `{path}` is the main worktree's path: `~/repos/projects/codeassembly` is accompanied by `~/repos/projects/codeassembly.live`. If the machine has the repo registry, `thor-repo list --tag live` enumerates the tagged set; for a registry whose entries do not have the tag, it returns nothing, which is not evidence that a repository does not deploy from a `live` worktree.
|
|
13
14
|
|
|
14
15
|
A merged change is deployed to the machine only once `live` is advanced to it. Until then the deployed behavior is the old one, so a change is not live while `live` still points at its predecessor.
|
|
15
16
|
|
|
@@ -11,7 +11,7 @@ A README answers two questions for a reader who arrived a moment ago: whether th
|
|
|
11
11
|
|
|
12
12
|
## Audience
|
|
13
13
|
|
|
14
|
-
A README is written for people. `AGENTS.md` is the agent-facing companion, and it
|
|
14
|
+
A README is written for people. `AGENTS.md` is the agent-facing companion, and it contains the context that an agent needs and a human reader does not: exact test invocations, constraints on what to modify, conventions that a contributor absorbs from the code but that an agent must be told.
|
|
15
15
|
|
|
16
16
|
The split is not a matter of taste. An agent loads `AGENTS.md` in full at every session, so a line there takes up context every time, whereas a human reads a README once and skims it later. Assigning content to a file by who reads it keeps both files short.
|
|
17
17
|
|
|
@@ -47,7 +47,7 @@ The opening makes up to three moves, in order. The first applies to every type;
|
|
|
47
47
|
2. **How to get it running.** The install command, the import line, or the bootstrap command, whichever the type calls for.
|
|
48
48
|
3. **The smallest thing that works.** One example, short enough to read without scrolling, that a reader can run unchanged.
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
If the moves that apply to a README come after its second heading, the README presents its answer too late.
|
|
51
51
|
|
|
52
52
|
## Moving detail out of the README
|
|
53
53
|
|
|
@@ -71,4 +71,4 @@ These share a failure mode: Each stays wrong without a test failing or a reader
|
|
|
71
71
|
|
|
72
72
|
## Adding a type
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
Extend the table by adding a row. A new row is justified when it produces a README that its neighbors would get wrong, and it states four things: the slug that its marker takes, what the README leads with, what it keeps that the others drop, and what it omits that the others keep. A row differing from its neighbor only in wording is evidence that the distinction is not real; merge the two.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
slug: shared-data-conventions
|
|
3
3
|
description: 'Changes to shared data: unmerged code never writes to a shared store, and a change to the shape of persisted data proceeds as expand, migrate, contract. Consult before planning, implementing, or reviewing a change that alters the shape of persisted data or writes to a shared store.'
|
|
4
|
-
delivery: [
|
|
4
|
+
delivery: [skill]
|
|
5
5
|
version: '1'
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -10,5 +10,5 @@ version: '1'
|
|
|
10
10
|
Shared state is any store that a deployed product or another person reads, such as a production database or a content dataset. A local or disposable copy is not shared. The repository's `AGENTS.md` names which stores are shared and how their migrations run.
|
|
11
11
|
|
|
12
12
|
- **Writes.** Unmerged code never writes to shared state, even when a plan or a ticket directs it. Asked to run a migration or another write against shared state from a branch, decline and name the route: Merge, then run it from merged code.
|
|
13
|
-
- **Sequence.** A change to the shape of data proceeds as expand, migrate, contract. Expand adds the new shape alongside the old one, migrate moves the data, and contract removes the old shape once
|
|
13
|
+
- **Sequence.** A change to the shape of data proceeds as expand, migrate, contract. Expand adds the new shape alongside the old one, migrate moves the data, and contract removes the old shape once the deployed code no longer reads it. Each step is its own change, merged and deployed before the next begins, so that every order of deploy and migration leaves the product working.
|
|
14
14
|
- **Migrations.** A migration runs from merged code, by automation or by the developer, and by an agent only when the developer directs that run. It defaults to a dry run and is idempotent.
|
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
slug: shell-conventions
|
|
3
3
|
description: Conventions for writing production-quality bash scripts in this repository.
|
|
4
4
|
delivery: skill
|
|
5
|
-
version: '
|
|
5
|
+
version: '6'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Shell script conventions
|
|
9
9
|
|
|
10
|
-
Conventions for writing production-quality bash scripts in this repository. These complement the universal style rules (verb-led function names, primary logic first, long-form CLI options).
|
|
10
|
+
Conventions for writing production-quality bash scripts in this repository. These complement the universal style rules (verb-led function names, primary logic first, long-form CLI options). A script's interface, meaning its help, exit codes, error messages, and progress reports, follows {rulebook:cli-conventions}; this rulebook states how a bash script implements it.
|
|
11
11
|
|
|
12
12
|
## Script anatomy
|
|
13
13
|
|
|
@@ -59,9 +59,11 @@ main() {
|
|
|
59
59
|
|
|
60
60
|
# region | Helper functions
|
|
61
61
|
|
|
62
|
-
# Displays command-line syntax
|
|
62
|
+
# Displays command-line syntax: to stdout for a help request (exit 0), to stderr otherwise.
|
|
63
63
|
show_usage() {
|
|
64
|
-
|
|
64
|
+
local code="${1:-2}" fd=2
|
|
65
|
+
((code == 0)) && fd=1
|
|
66
|
+
cat >&"$fd" <<USAGE
|
|
65
67
|
One-line purpose.
|
|
66
68
|
|
|
67
69
|
Usage:
|
|
@@ -81,7 +83,7 @@ Examples:
|
|
|
81
83
|
$PROG my-value
|
|
82
84
|
result=\$($PROG my-value) && echo "\$result"
|
|
83
85
|
USAGE
|
|
84
|
-
exit "$
|
|
86
|
+
exit "$code"
|
|
85
87
|
}
|
|
86
88
|
# endregion | Helper functions
|
|
87
89
|
|
|
@@ -106,25 +108,20 @@ Read a path that must be non-empty as `${dir:?message}`, which aborts, whereas t
|
|
|
106
108
|
|
|
107
109
|
## Help and exit codes
|
|
108
110
|
|
|
109
|
-
|
|
110
|
-
| ---------------------------------------- | ---------------------- |
|
|
111
|
-
| `--help` or `-h` (explicit help request) | 0 |
|
|
112
|
-
| Bad input, missing arguments | 1 |
|
|
113
|
-
| Unknown command / subcommand | 2 |
|
|
114
|
-
| Required external command not found | 127 (POSIX convention) |
|
|
115
|
-
|
|
116
|
-
`show_usage` accepts an optional exit code parameter, defaulting to 1:
|
|
111
|
+
The exit codes and the destination of help output are stated in the CLI conventions linked above. `show_usage` takes the exit code as an optional parameter, defaulting to 2, and chooses the stream from it:
|
|
117
112
|
|
|
118
113
|
```bash
|
|
119
114
|
show_usage() {
|
|
120
|
-
|
|
115
|
+
local code="${1:-2}" fd=2
|
|
116
|
+
((code == 0)) && fd=1
|
|
117
|
+
cat >&"$fd" <<USAGE
|
|
121
118
|
...
|
|
122
119
|
USAGE
|
|
123
|
-
exit "$
|
|
120
|
+
exit "$code"
|
|
124
121
|
}
|
|
125
122
|
```
|
|
126
123
|
|
|
127
|
-
Call sites: `show_usage 0` for help
|
|
124
|
+
Call sites: `show_usage 0` for a help request, and `show_usage` (bare) for a usage error.
|
|
128
125
|
|
|
129
126
|
### `--help` must be handled manually
|
|
130
127
|
|
|
@@ -173,9 +170,7 @@ esac
|
|
|
173
170
|
|
|
174
171
|
## Error messages
|
|
175
172
|
|
|
176
|
-
|
|
177
|
-
- **Prefix with `$PROG:`**, so that a reader of piped output can tell which script wrote the message.
|
|
178
|
-
- **Be actionable**: Tell the user what to do, not just what went wrong.
|
|
173
|
+
Write each message to stderr with `>&2`, and prefix it with `$PROG:`, so that it meets the error rules in the CLI conventions:
|
|
179
174
|
|
|
180
175
|
```bash
|
|
181
176
|
# Bad
|
|
@@ -188,7 +183,7 @@ echo "Create it with: git worktree add $path main" >&2
|
|
|
188
183
|
|
|
189
184
|
## Dependency checks
|
|
190
185
|
|
|
191
|
-
Preflight-check external commands before using them:
|
|
186
|
+
Preflight-check external commands before using them, exiting with the missing-command code:
|
|
192
187
|
|
|
193
188
|
```bash
|
|
194
189
|
for cmd in wt jq; do
|
|
@@ -260,7 +255,7 @@ setup_workspace() {
|
|
|
260
255
|
}
|
|
261
256
|
```
|
|
262
257
|
|
|
263
|
-
Return non-zero rather than calling `exit`:
|
|
258
|
+
Return non-zero rather than calling `exit`: Shellspec reads a non-zero `return` as a failed hook. Because a failed `BeforeEach` aborts the example body and `AfterEach` does not run after one, a cleanup helper never sees a half-built workspace.
|
|
264
259
|
|
|
265
260
|
Build the workspace through the shared helpers in `spec/spec_helper.sh` rather than calling `mktemp` in the hook. `make_tmpdir` and `remove_tmpdir` create and remove a temporary directory; `enter_tmpdir` and `leave_tmpdir` additionally make it the working directory and restore the previous one.
|
|
266
261
|
|
|
@@ -270,9 +265,8 @@ Build the workspace through the shared helpers in `spec/spec_helper.sh` rather t
|
|
|
270
265
|
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
271
266
|
| `set -e` alone | Use `set -euo pipefail`: `-u` catches typos in variable names, `pipefail` catches mid-pipeline failures |
|
|
272
267
|
| `usage()` as function name | Use `show_usage()`: Functions start with verbs |
|
|
273
|
-
| `show_usage` always exits 1 | Accept exit
|
|
268
|
+
| `show_usage` always exits 1 | Accept an exit-code parameter, and write to stdout when it is 0 |
|
|
274
269
|
| `which cmd` to check availability | Use `command -v cmd` (POSIX-portable) |
|
|
275
|
-
| Error messages to stdout | Always `>&2` |
|
|
276
270
|
| Interpolating user input into `jq` | Use `jq --arg name "$value"` for safe binding |
|
|
277
271
|
| `${var//pat/repl}` with dynamic `repl` | Add `shopt -u patsub_replacement 2>/dev/null \|\| true`; bash 5.2+ expands `&` in `repl` to the matched text |
|
|
278
272
|
| Hard-coded values that vary | Accept as arguments or use `readonly` defaults at the top |
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: ui-copy-conventions
|
|
3
|
+
description: 'Text in a product surface: written for the person who returns to the page, with rules for labels, helper text, errors, and empty states, and a copy budget. Consult before writing labels, helper text, messages, or empty states for a page, a prototype, or a UI component.'
|
|
4
|
+
delivery: [skill]
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# UI copy conventions
|
|
9
|
+
|
|
10
|
+
A tool page is written for the person who uses it every week, not for a first-time visitor. Copy that introduces the page, sells it, or walks through it is text that this person reads past on every visit, and a sentence that declares the task finished decides something that is theirs to decide. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
|
|
11
|
+
|
|
12
|
+
When a project names its own content guidelines, such as a design system's, those guidelines take precedence when the two conflict.
|
|
13
|
+
|
|
14
|
+
## Rules
|
|
15
|
+
|
|
16
|
+
- **Labels** are nouns. **Buttons** are verbs that name the action that they perform.
|
|
17
|
+
- **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes.
|
|
18
|
+
- **An error** names the problem and the fix.
|
|
19
|
+
- **Register.** A sentence never explains the page, reassures, congratulates, or narrates the reader ("you are done", "you can…").
|
|
20
|
+
- **Minimizers.** Leave out "simply" and "just".
|
|
21
|
+
- **Case.** Labels, buttons, headings, and messages take sentence case.
|
|
22
|
+
|
|
23
|
+
## Copy budget
|
|
24
|
+
|
|
25
|
+
- A page does not open with an intro paragraph.
|
|
26
|
+
- A control has at most one line of helper text.
|
|
27
|
+
- An empty state has one line.
|
|
28
|
+
|
|
29
|
+
## Example
|
|
30
|
+
|
|
31
|
+
Under the heading of an API-token page:
|
|
32
|
+
|
|
33
|
+
- ❌ "Make a token from a preset or one of your sets, give it a name, and you are done."
|
|
34
|
+
- ✅ Nothing under the heading. Under the name field: "Shown in the token list. Not secret."
|
|
@@ -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
|
|
@@ -11,40 +11,46 @@ version: '10'
|
|
|
11
11
|
|
|
12
12
|
Always act as a conscientious and courteous collaborator. Follow best practices and maintain high standards, avoiding any behavior that would endanger your reputation as a highly competent engineer. Be deferential but not sycophantic: Do not hesitate to challenge questionable decisions; proactively suggest improvements. The developer relies on you to be a trusted advisor and sounding board.
|
|
13
13
|
|
|
14
|
-
Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them
|
|
14
|
+
Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them. Do not restate the verdict after correcting a fact on which the case rested. Treat a concession under protest or a sign of fatigue as a decision to move on. When something is genuinely expensive to undo later, say so once, so that revisiting it is an informed choice rather than a hidden cost.
|
|
15
15
|
|
|
16
16
|
## Handoffs
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Perform every step yourself, at design, planning, execution, and review time alike. Hand a step over only by climbing this ladder, and try each rung before the next:
|
|
19
19
|
|
|
20
20
|
1. Do it.
|
|
21
21
|
2. When the step needs authorization, such as a gated action or a command that the sandbox refused and the permission gate can approve, ask for the authorization, then do it.
|
|
22
|
-
3. When the step needs a resource that
|
|
23
|
-
4. When
|
|
22
|
+
3. When the step needs a resource that you cannot obtain, such as a credential, a login to a remote service, or a sandbox grant, ask once for that resource, naming the command that will run once it arrives, propose the durable grant that removes the block for later sessions, and do it when the resource arrives. The routes to try before asking are in the "Missing tools and resources" section of William Thorsen's tooling preferences.
|
|
23
|
+
4. When you cannot perform part of the step after those routes are exhausted, hand that part over, naming what you cannot do and why ("how the rating control feels on a physical phone"), after performing every part that you can.
|
|
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
|
-
|
|
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
|
+
|
|
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.
|
|
30
|
+
|
|
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.
|
|
28
32
|
|
|
29
33
|
## Prompt formatting
|
|
30
34
|
|
|
31
|
-
Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class.
|
|
35
|
+
Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class. Decide every other field: State the decision in one line with its reason, record it, and proceed, putting the rejected alternative in a clause rather than a numbered option. Decide a determination that has one right answer under a governing document, such as a change's work type under the work-type test, by applying the test and picking, even when two candidates are close: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact.
|
|
32
36
|
|
|
33
|
-
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.
|
|
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.
|
|
34
38
|
|
|
35
|
-
Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only
|
|
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.
|
|
36
40
|
|
|
37
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.
|
|
38
42
|
|
|
39
43
|
An ask costs the developer a context switch and idles the session until the answer arrives; a recorded decision costs them a word to overrule. Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
|
|
40
44
|
|
|
41
|
-
|
|
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).
|
|
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.
|
|
42
48
|
|
|
43
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:
|
|
44
50
|
|
|
45
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 `👍🏼👎🏼`.
|
|
46
52
|
- **All other questions** (open-ended, clarifications): End with `🤔`
|
|
47
|
-
- **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently.
|
|
53
|
+
- **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. State in a `➖` what breaks or what it costs, and for whom; cut one that you cannot state that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or reach parity between options. Leave an option without a real bullet bare, and when every option lacks one, let the markers alone convey the recommendation. Before rendering, check the leader, in a gated decision as in any other, because the marker tells the developer how much deliberation the ask needs: State as an alternative's `➖` any cost that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand, cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
|
|
48
54
|
|
|
49
55
|
Examples:
|
|
50
56
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-ticketing-preferences
|
|
3
3
|
description: William Thorsen's preferences for how work is split across tickets, how the relationships between them are recorded, and which figures a ticket body states.
|
|
4
4
|
delivery: hook
|
|
5
|
-
version: '
|
|
5
|
+
version: '6'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's ticketing preferences
|
|
@@ -11,11 +11,11 @@ version: '5'
|
|
|
11
11
|
|
|
12
12
|
When work deserves more than one pull request, give each pull request its own ticket. When splitting a ticket into two, keep the first piece in the originating ticket. When splitting into more, make the originating ticket an umbrella.
|
|
13
13
|
|
|
14
|
-
A piece
|
|
14
|
+
A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. When the count is a judgment, cut finer: Merging two tickets that turned out to be one costs an edit and a close, while splitting one that turned out to be four costs a rewrite of the original, new children, a re-cut plan, and whatever was committed against the superseded contract.
|
|
15
15
|
|
|
16
16
|
This governs work already judged to need more than one pull request. Whether work discovered mid-change becomes a ticket at all is decided first by the fold-in default in [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
|
|
17
17
|
|
|
18
|
-
Record the relationships natively when the tracker supports them -- blockers, and parent to child -- rather than as prose in a body.
|
|
18
|
+
Record the relationships natively when the tracker supports them -- blockers, and parent to child -- rather than as prose in a body. Record a blocker when there is some probability that one ticket affects another and should be merged first, not only when that is certain: A ticket whose design takes another ticket's outcome as an input is blocked by it.
|
|
19
19
|
|
|
20
20
|
## Counts in a ticket body
|
|
21
21
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-tooling-preferences
|
|
3
3
|
description: William Thorsen's preferences for which command-line tool an agent reaches for, how it invokes it, and how it obtains a tool or resource that is missing.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '4'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's tooling preferences
|
|
@@ -25,12 +25,12 @@ Before reporting a tool, dependency, or service as missing, exhaust the routes t
|
|
|
25
25
|
- Call the service's API when the CLI is only a wrapper over it.
|
|
26
26
|
- Start a stopped service that the project defines, through its compose stack or its start script.
|
|
27
27
|
|
|
28
|
-
Never hand over a command that the sandbox refuses. When the resource that it
|
|
28
|
+
Never hand over a command that the sandbox refuses. When the resource that it accesses is within what the task was given, retry the command through the permission gate, which approves or refuses the retry. When the resource is not within the task, or when the retry is refused, ask once for the grant that clears it, propose the durable grant that removes the block for later sessions, with its tradeoff in one line (the grant widens what every later sandboxed command may reach), and run the command once the grant is in place.
|
|
29
29
|
|
|
30
|
-
Ask for the resource when none of those routes works, when the missing resource is a credential or access, or when the stopped service is one that the project does not define. Name the resource and the command that will run once it arrives, and keep the task: Never restate the task as an action item for the developer. The "Handoffs" section of William Thorsen's collaboration preferences states the ladder on which this ask is the third rung. A credential or access that is already present is the task's to use only when the task's plan or the developer names the command that reads it. Never look for or use any other: It belongs to the developer.
|
|
30
|
+
Ask for the resource when none of those routes works, when the missing resource is a credential or access, or when the stopped service is one that the project does not define. Name the resource and the command that will run once it arrives, and keep the task: Never restate the task as an action item for the developer. The "Handoffs" section of William Thorsen's collaboration preferences states the ladder on which this ask is the third rung. A credential or access that is already present is the task's to use only when the task's plan or the developer names the command that reads it. Never look for or use any other: It belongs to the developer. An app's local development login is not such a credential: Log into a local instance of the app under work without asking, and set a development credential in an untracked local config file when the app needs one.
|
|
31
31
|
|
|
32
|
-
This rule
|
|
32
|
+
This rule applies before any fallback that a skill names for an unavailable tool. A skill's "unavailable" means unavailable once these routes are exhausted, and the skill's fallback applies from that point.
|
|
33
33
|
|
|
34
|
-
The rule does not license any write. Acquiring a resource in a way that mutates shared state, such as installing a tool globally, restarting a service that the project does not define, minting a credential, or widening a sandbox grant, still needs the developer's authorization, and the ask is how to obtain it.
|
|
34
|
+
The rule does not license any write. Acquiring a resource in a way that mutates shared state, such as installing a tool globally, restarting a service that the project does not define, minting a credential, or widening a sandbox grant, still needs the developer's authorization, and the ask is how to obtain it. Setting that local development credential is not minting one.
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
If a `sandbox-conventions` rulebook is deployed, consult it first for a denial that misreports itself as a missing resource.
|
|
@@ -47,7 +47,7 @@ function isConfig(value: unknown): value is Config {
|
|
|
47
47
|
}
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
-
Two exceptions, each with a comment saying why: a TypeScript limitation in which the type is guaranteed but uninferable, such as `Object.keys()`; and test code
|
|
50
|
+
Two exceptions, each with a comment saying why: a TypeScript limitation in which the type is guaranteed but uninferable, such as `Object.keys()`; and test code in which precise typing of an external API would obscure the test.
|
|
51
51
|
|
|
52
52
|
Never use `any`, a non-null assertion (use a runtime assertion instead), or a generic parameter that claims a guarantee that the function cannot deliver. Model known variants as a union, and validate external data with a type guard or a schema library.
|
|
53
53
|
|