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
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-workflow-preferences
|
|
3
3
|
description: William Thorsen's personal preferences for how work moves -- scope, branches and worktrees, guidance capture, and the arc of product development.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '12'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's workflow preferences
|
|
@@ -10,14 +10,14 @@ version: '8'
|
|
|
10
10
|
## Workflow
|
|
11
11
|
|
|
12
12
|
- Do not treat a question as an instruction: When the user asks "Did you do X?", answer the question rather than doing X.
|
|
13
|
-
- Treat a ticket as a signal, not a boundary: When work appears that the ticket didn't name, fold it into the current change by default; spin off a separate ticket only for an affirmative reason beyond the ticket's silence, and when you do, create it immediately rather than
|
|
13
|
+
- Treat a ticket as a signal, not a boundary: When work appears that the ticket didn't name, fold it into the current change by default; spin off a separate ticket only for an affirmative reason beyond the ticket's silence, and when you do, create it immediately rather than leaving it in the conversation. Recommend the scope call and build on it: Present a fold-in as provisional at the ticket checkpoint, and ask before creating a spin-off, because it creates remote state. Full doctrine: [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
|
|
14
14
|
- Make changes through branches and pull requests, not by editing the default branch directly.
|
|
15
15
|
- When feedback should change how the agent behaves and generalizes beyond the current task, capture it via {skill:capture-feedback}. The capture records evidence for a later refinement pass; it does not change any behavior until that pass writes the lesson into guidance and the guidance is deployed. Do not record generalizable guidance as a per-project memory.
|
|
16
16
|
- Reserve memories for genuinely local, non-propagating facts (a project-specific deadline or quirk): A memory is scoped to a single project on a single machine, so recording generalizable guidance in one fragments behavior across contexts.
|
|
17
17
|
|
|
18
18
|
## Branch and worktree management
|
|
19
19
|
|
|
20
|
-
Never create a branch or worktree without explicit authorization.
|
|
20
|
+
Never create a branch or worktree without explicit authorization. Each ticket is implemented in its own worktree, and the developer's tooling relies on that: Do all of one ticket's work in that worktree, never switch a worktree to another branch, and start a new session in another ticket's own worktree for work on that ticket. Which branch or worktree a ticket's work uses is settled, so never ask it.
|
|
21
21
|
|
|
22
22
|
After a merge, say nothing about worktree or branch state and never offer to manage it. The worktree stays as long as its branch does, so there is nothing to clean up and nothing to ask about.
|
|
23
23
|
|
|
@@ -36,18 +36,18 @@ When the developer starts a product, move the work through these stages in order
|
|
|
36
36
|
1. Idea: Write the idea back to the developer and record it in the design doc.
|
|
37
37
|
2. Opinions: Evaluate the idea from other roles and record the evaluations with it.
|
|
38
38
|
3. Brief: Flesh the idea out into a brief for a prototype round.
|
|
39
|
-
4. Prototypes: Build competing prototypes of a rich feature set through `prepare-prototype-brief`, judge them through `index-prototypes`, and synthesize
|
|
40
|
-
5. End vision: Write the purpose, the non-goals, the decisions with their reasons, and a rough structure from what the prototypes taught, and get the developer's approval.
|
|
39
|
+
4. Prototypes: Build competing prototypes of a rich feature set through `prepare-prototype-brief`, judge them through `index-prototypes`, decide every idea in the round's idea table through `prepare-prototype-brief`, and synthesize the prototypes through `refine-prototype`, which transfers the kept and adapted ideas to the winner, applies the developer's commands at sketch speed, and records each accepted change in a `refinement-log` artifact. A verdict on a prototype does not decide its ideas: Each idea is kept, adapted, deferred, or dropped by the developer's answer. Prototyping a rich feature set is how the product that could emerge becomes visible, so run the round before writing the vision.
|
|
40
|
+
5. End vision: Write the purpose, the non-goals, the project's declared stage (maturity, sensitivity, and audience), the decisions with their reasons, and a rough structure from what the prototypes taught, citing the round's `idea-decisions` and `refinement-log` artifacts, and get the developer's approval. Record every decision on an idea in the design doc, so that a later session sees why an idea is absent.
|
|
41
41
|
6. MVP: Build the smallest product that does the product's one job. Put a prototype feature in it when the product cannot do that job without the feature, and leave the rest for increments.
|
|
42
42
|
7. Increments: Add features one iteration at a time.
|
|
43
43
|
|
|
44
44
|
Treat the winning prototype as the baseline: the floor on quality and feel against which the finished product is judged, and the reference for what the product does and how it is put together. Read it as evidence of the vision rather than as its specification: Let its structure inform the design doc, and expect to improve on it.
|
|
45
45
|
|
|
46
|
-
Hold the finished product to the baseline, not any one iteration. An iteration may omit a prototype feature or
|
|
46
|
+
Hold the finished product to the baseline, not any one iteration. An iteration may omit a prototype feature or deliver it in a reduced form; treat a reduction as remaining work and give it a one-line sub-issue, which keeps the gap visible. When settling a feature below the prototype's bar or retiring it, record the decision in the design doc with its reason.
|
|
47
47
|
|
|
48
48
|
Write a ticket in detail when its work is about to be implemented. Until then, keep each artifact to one tier:
|
|
49
49
|
|
|
50
|
-
- Keep the vision in a design doc in the repo: the purpose, the non-goals, the decisions with their reasons, and the rough structure. Put a statement there when reversing it later would invalidate completed work, or when a new session needs it to choose a direction, and leave most other detail to its iteration.
|
|
50
|
+
- Keep the vision in a design doc in the repo: the purpose, the non-goals, the declared stage, the decisions with their reasons, and the rough structure. Put a statement there when reversing it later would invalidate completed work, or when a new session needs it to choose a direction, and leave most other detail to its iteration.
|
|
51
51
|
- Have the epic point to the design doc, state what is out of scope, and list the iterations as its sub-issues in order. Keep the vision out of the epic's body, because a ticket's body is frozen once its work starts and the vision is not.
|
|
52
52
|
- Use the milestone to mark the current iteration, which `pull-from-backlog` reads as the Now set.
|
|
53
53
|
- Treat the prototype as the baseline.
|
|
@@ -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
|
|
|
@@ -26,6 +47,10 @@
|
|
|
26
47
|
|
|
27
48
|
When creating an artifact (plan, devlog, review, change summary, chat summary, etc.), invoke the `save-artifact` skill to resolve path and naming. Do not place artifacts in ad-hoc locations.
|
|
28
49
|
|
|
50
|
+
The artifact directory (`~/ai-artifacts` by default) is the developer's audit trail: It records what agents planned, reviewed, summarized, and published, and when. It is not a source of truth. Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories; never save them as an artifact.
|
|
51
|
+
|
|
52
|
+
An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests. A skill that reads an artifact as an input to the same piece of work, such as the plan that `implement-plan` executes or the change summary that `create-pr` publishes, uses the artifact as the workflow intends.
|
|
53
|
+
|
|
29
54
|
A saved artifact records what its author produced at that moment. Correct one that got its own subject wrong; never edit one toward what has happened since, and never report its divergence from current state as a defect or as a repair for the user to weigh.
|
|
30
55
|
|
|
31
56
|
Two artifacts are never edited once written, because a rewrite of either destroys evidence silently: `capture-lede-decision` reads the `pull-request` artifact's `## What` and the `merge` artifact's `## Body` to recover what was published. Each opens with a marker that directs a reading agent to give its own revision a new record and leave the original unedited.
|
|
@@ -38,6 +63,16 @@ Acceptance criteria are the one revisable part, because they alone are the contr
|
|
|
38
63
|
|
|
39
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.
|
|
40
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
|
+
|
|
72
|
+
## Authorship
|
|
73
|
+
|
|
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.
|
|
75
|
+
|
|
41
76
|
## Commits
|
|
42
77
|
|
|
43
|
-
Invoke the `create-commit` skill to make a commit. It states the procedure: what to stage, one commit per logical unit of work, and how the title is rendered. The `consult-commit-conventions` skill states what the message is composed to -- the title and body conventions, the work-type taxonomy, and the branch-naming format -- and is worth consulting on its own before writing a message by hand.
|
|
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.
|
|
@@ -29,12 +29,15 @@ Prose mentions of script names that are not invocations (e.g., ``"the `describe-
|
|
|
29
29
|
|
|
30
30
|
## Scripts
|
|
31
31
|
|
|
32
|
+
- `check-branch-currency.mjs`: Fetches the remote's default branch and reports, as JSON, how far the checked-out branch is behind and ahead of it, whether its tree is clean, whether its upstream contains any of its own commits, and which commits the default branch gained, each marked by whether it touches the given paths. Invoke it as `node {harness_home_dir}/scripts/check-branch-currency.mjs --base <remote>/<branch> [--path <path>]...`; [branch-currency.md](../skills/_data/branch-currency.md) states how a skill acts on the result.
|
|
33
|
+
- `check-prose.mjs`: Runs every `revise-prose` detector over one Markdown file at any path, without reading or writing the sweep record, and prints one line per candidate, or one JSON document `{ file, rules, candidates }` under `--json`. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or an unreadable file. Invoke it as `node {harness_home_dir}/scripts/check-prose.mjs --file <path> [--json]`; `summarize-change` runs it over a change summary's prose.
|
|
32
34
|
- `describe-change.mjs`: Renders titles for commits, tickets, PRs, and merges from declarative templates, the `{breaking}` marker included, reads a rendered title back into its parts, consolidates a commit range's entries into a consolidated record, applies overrides to a record, renders the fenced `change-record` block that ends a pull-request body and the `## Details` body of a change summary, and resolves what a pull request merges as from that block and the pull request's commits. Invoke it as `node {harness_home_dir}/scripts/describe-change.mjs <subcommand>`, where [title-templates.md](../skills/_data/title-templates.md#invoking-the-bundle) names the subcommand for each; the bundle does not have a shebang.
|
|
33
35
|
- `get-ticket-id.sh`: Extracts a ticket ID from a branch name.
|
|
34
|
-
- `manage-jira-ticket.mjs`:
|
|
36
|
+
- `manage-jira-ticket.mjs`: Compares `acli`'s active site with a ticket's site and names the `acli jira auth switch` command on a mismatch (`check-site`), resolves the project key and issue type for a Jira work item from the repository's `.agents/preferences.yaml` (`resolve-target`), converts a Markdown body to ADF with task lists as native task items (`convert-body`), and creates a work item through `acli` exactly once, checking its parent first (`create`). `create` refuses before any other `acli` call when `ticket.base_url` is set, in the repository's preferences or the global file, and `acli`'s active site is another site or cannot be read. Invoke it as `node {harness_home_dir}/scripts/manage-jira-ticket.mjs <subcommand>`.
|
|
35
37
|
- `resolve-review-run.mjs`: Finds a ticket's active review run (its newest `interactive` run directory), opens it for a new review by creating one when none exists, or finds the newest reviewer or overseer review in it. Invoke it as `node {harness_home_dir}/scripts/resolve-review-run.mjs active|open|latest`.
|
|
36
38
|
- `resolve-frontmatter.sh`: Emits canonical artifact frontmatter (YAML or JSON) with provenance, ticket, branch, commit, and PR fields, plus scalar and list extension keys.
|
|
37
|
-
- `select-lede-exemplars.mjs`: Selects author-approved ledes of a given work type from the lede-decision corpus, optionally floored at a quality rating. `--with-pair` reports each record's agent lede, merged lede, and author comment alongside the approved text.
|
|
39
|
+
- `select-lede-exemplars.mjs`: Selects author-approved ledes of a given work type from the lede-decision corpus, optionally floored at a quality rating. `--breaking` marks the request as one for a breaking change, as a `!` on `--type` does: An unmarked request never selects a breaking record, and a marked one prefers breaking records within each widening step. `--with-pair` reports each record's agent lede, merged lede, and author comment alongside the approved text.
|
|
40
|
+
- `validate-preferences.mjs`: Validates `preferences.yaml` files against the schema bundled with this release, defaulting to `.agents/preferences.yaml` under the working directory. It prints one line per finding, or one JSON object per file under `--json`, and exits 1 when any file is invalid. Invoke it as `node {harness_home_dir}/scripts/validate-preferences.mjs [--json] [--strict] [file...]`; [Validation](../../docs/preferences.md#validation) states its rules.
|
|
38
41
|
|
|
39
42
|
## Drift detection
|
|
40
43
|
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
|
+
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
+
var R=Object.defineProperty;var t=(n,e)=>R(n,"name",{value:e,configurable:!0});import g from"node:process";function b(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}t(b,"isError");function f(n){try{return b(n)&&typeof n.message=="string"&&n.message!==""?n.message:String(n)}catch{return"[unstringifiable value]"}}t(f,"describeError");import{realpathSync as y}from"node:fs";import x from"node:process";import{fileURLToPath as O}from"node:url";function w(n,e){let r=x.argv[1];if(r===void 0)return!1;try{return y(O(n))===y(r)}catch(o){return x.stderr.write(`${e}: warning: could not determine entry point: ${f(o)}
|
|
4
|
+
`),!0}}t(w,"isEntryPoint");function E(n,e){let r=[],o=[];for(let s=0;s<n.length;s+=1){let c=n[s];if(c===void 0)continue;if(!c.startsWith("--")){r.push(c);continue}let u=B(c,e);if(u===null)throw new Error(`unknown flag: ${c}`);let{spec:i,inlineValue:a}=u;if(!i.takesValue){if(a!==null)throw new Error(`--${i.name} does not take a value`);o.push({name:i.name,value:null});continue}if(a!==null){o.push({name:i.name,value:a});continue}let l=n[s+1]??null;if(l===null||l.startsWith("--"))throw new Error(`--${i.name} requires a value`);o.push({name:i.name,value:l}),s+=1}return{positionals:r,flags:o}}t(E,"scanFlags");function B(n,e){for(let r of e)for(let o of[r.name,...r.aliases??[]]){let s=`--${o}`;if(n===s)return{spec:r,inlineValue:null};if(n.startsWith(`${s}=`))return{spec:r,inlineValue:n.slice(s.length+1)}}return null}t(B,"matchFlag");import{execFileSync as N}from"node:child_process";import j from"node:process";function k(n){return M(n)&&!Array.isArray(n)}t(k,"isRecord");function M(n){return typeof n=="object"&&n!==null}t(M,"isObject");function $(n){let{base:e,cwd:r,paths:o}=n,{remote:s,branch:c}=h(e),u=A(r,s,c);if(!u.ok)return{fetched:!1,error:u.error};let i=p(r,`HEAD..${e}`),a=p(r,`${e}..HEAD`),l=m(r,["status","--porcelain"])==="",F=G(r,e),S=T(r,e,o);return{fetched:!0,base:e,behind:i,ahead:a,clean:l,pushed:F,gained:S}}t($,"checkBranchCurrency");function h(n){let e=n.indexOf("/"),r=n.slice(0,Math.max(0,e)),o=n.slice(e+1);if(e===-1||r===""||o==="")throw new Error(`--base must name a remote and a branch, such as origin/main: ${n}`);return{remote:r,branch:o}}t(h,"splitBase");var v="@{u}";function p(n,e){return Number.parseInt(m(n,["rev-list","--count",e]),10)}t(p,"countCommits");function C(n){let e=k(n)?n.stderr:void 0;return typeof e=="string"&&e.trim()!==""?e.trim():n instanceof Error?n.message:String(n)}t(C,"describeGitFailure");function A(n,e,r){try{return N("git",["-C",n,"fetch","--quiet",e,r],{encoding:"utf8",env:{...j.env,GIT_TERMINAL_PROMPT:"0"},stdio:["ignore","pipe","pipe"]}),{ok:!0}}catch(o){return{ok:!1,error:C(o)}}}t(A,"fetchBranch");function G(n,e){return P(n)?p(n,e+".."+v)>0:!1}t(G,"hasPushedOwnCommits");function P(n){try{return m(n,["rev-parse","--abbrev-ref","--symbolic-full-name",v]),!0}catch{return!1}}t(P,"hasUpstream");function T(n,e,r){let o=`HEAD..${e}`,s=m(n,["log","--format=%H%x09%s",o]),c=s===""?[]:s.split(`
|
|
5
|
+
`).map(a=>V(a));if(r.length===0)return c.map(a=>({...a,touchesWork:null}));let u=r.map(a=>`:(top,literal)${a}`),i=new Set(m(n,["log","--format=%H",o,"--",...u]).split(`
|
|
6
|
+
`));return c.map(a=>({...a,touchesWork:i.has(a.sha)}))}t(T,"listGainedCommits");function V(n){let e=n.indexOf(" ");return{sha:n.slice(0,e),subject:n.slice(e+1)}}t(V,"parseLogLine");function m(n,e){try{return N("git",["-C",n,...e],{encoding:"utf8",stdio:["ignore","pipe","pipe"]}).trim()}catch(r){throw new Error(`git ${e.join(" ")} failed: ${C(r)}`,{cause:r})}}t(m,"readGit");var I=[{name:"base",takesValue:!0},{name:"path",takesValue:!0}],d="usage: check-branch-currency --base <remote>/<branch> [--path <path>]...";function W(){try{let n=H(g.argv.slice(2));g.stdout.write(`${JSON.stringify(n,null,2)}
|
|
7
|
+
`)}catch(n){g.stderr.write(`check-branch-currency: ${f(n)}
|
|
8
|
+
`),g.exit(1)}}t(W,"main");w(import.meta.url,"check-branch-currency")&&W();function H(n){let{flags:e,positionals:r}=E(n,I);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}
|
|
9
|
+
${d}`);let o=e.filter(i=>i.name==="base").map(i=>i.value??""),[s,...c]=o;if(s===void 0)throw new Error(`--base is required
|
|
10
|
+
${d}`);if(c.length>0)throw new Error(`--base may be given only once
|
|
11
|
+
${d}`);h(s);let u=e.filter(i=>i.name==="path").map(i=>i.value??"");return $({base:s,cwd:g.cwd(),paths:u})}t(H,"runCommand");
|