codeassembly-guidance 0.5.0 → 0.7.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 +491 -0
- package/CHANGELOG.md +118 -0
- package/README.md +33 -4
- package/content/_partials/finding-grades.md +4 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/codeassembly-content.yaml +4 -0
- package/content/collections/recommended.md +5 -2
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/guidance/shared/AGENTS.md +1 -1
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/describe-change.mjs +88 -88
- package/content/scripts/manage-jira-ticket.mjs +113 -113
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +38 -38
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +20 -10
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +20 -7
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/next-steps-after-plan.md +6 -5
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +5 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +122 -122
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
- package/content/skills/design-and-plan/SKILL.md +6 -4
- package/content/skills/implement-plan/SKILL.md +4 -29
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +31 -8
- package/content/skills/merge-gh-pr/SKILL.md +25 -12
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +55 -20
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +3 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
- package/content/skills/refine-plan/SKILL.md +9 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +8 -8
- package/content/skills/review-criteria/SKILL.md +4 -4
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +111 -111
- package/content/skills/save-plan/SKILL.md +2 -0
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
- package/content/skills/summarize-change/SKILL.md +27 -9
- package/content/skills/testing-conventions/SKILL.md +14 -3
- package/content/skills/triage-feedback/SKILL.md +4 -0
- package/content/skills/triage-spike-findings/SKILL.md +36 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/skills/wrap-up/SKILL.md +4 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +11 -10
- package/schemas/preferences.v1.json +74 -8
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: convert-agent-prompt
|
|
3
|
+
description: Convert an agent's prompt file into an agent-logic file, which an agent-logic viewer renders as a statechart. Use when asked to convert, chart, or extract the logic of an agent prompt.
|
|
4
|
+
standalone: wanted only in projects that convert agent prompts, too rarely to justify a standing skill-index line
|
|
5
|
+
user-invocable: true
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Convert an agent prompt
|
|
9
|
+
|
|
10
|
+
Convert a prompt file into an agent-logic file: an XState v5 machine config that contains the prompt's logic and nothing else. You write a draft that quotes the prompt; the `convert` command of the `codeassembly-agent-logic` package turns it into the config, deriving offsets and ids, and refuses to write a config that is not valid.
|
|
11
|
+
|
|
12
|
+
Every command runs version 0.1.0 of the package through `pnpm dlx`, so that the extraction rules that you read match the procedure below.
|
|
13
|
+
|
|
14
|
+
## Arguments
|
|
15
|
+
|
|
16
|
+
- The prompt file (required).
|
|
17
|
+
- The output path (optional). Default: beside the prompt, `<base>.agent-logic.json`, where `<base>` is the prompt file's name without its extension.
|
|
18
|
+
- The problems path (optional): where the script writes the problems of a draft that it cannot convert, or the out-of-scope verdict.
|
|
19
|
+
|
|
20
|
+
## Prerequisites
|
|
21
|
+
|
|
22
|
+
- `pnpm` on the path.
|
|
23
|
+
- Access to the npm registry, from which `pnpm dlx` fetches the package on its first run.
|
|
24
|
+
- Write access to pnpm's dlx cache. A sandbox that denies it fails the first command with `Operation not permitted`; retry the command outside the sandbox through the permission gate.
|
|
25
|
+
|
|
26
|
+
## Procedure
|
|
27
|
+
|
|
28
|
+
1. Read the prompt file in full.
|
|
29
|
+
2. Print the extraction rules, and read them in full:
|
|
30
|
+
|
|
31
|
+
```shell
|
|
32
|
+
pnpm dlx codeassembly-agent-logic@0.1.0 rules
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Judge whether the prompt is out of scope by their condition, then write the draft that they describe, or the out-of-scope draft, to `$TMPDIR/<base>.draft.json`.
|
|
36
|
+
|
|
37
|
+
3. Unless the draft is out of scope, check it against the prompt before running the script, and correct it where the check fails:
|
|
38
|
+
- **Coverage.** Read the prompt again from the top, one paragraph or list item at a time, and write a coverage map to `$TMPDIR/<base>.coverage-map.json`: a JSON array with an entry `{ "quote": "...", "element": "..." }` for each instruction in it. The `quote` copies the instruction verbatim and occurs in the prompt exactly once. The `element` names the state, action, or transition that holds it, or is `ambient`, `unconverted`, or `none`. A list item or paragraph that states three instructions takes three entries. Include the instructions inside a dense step, each of which is an action of that step's state, and the rules of a section that states how to format output, such as an option format. Add each instruction whose entry names `none` to the draft where the rules' "What to extract", "Ambient instructions", and "Passages you cannot convert" place it, and name its element in the entry.
|
|
39
|
+
- **Map check.** Run the coverage check:
|
|
40
|
+
|
|
41
|
+
```shell
|
|
42
|
+
pnpm dlx codeassembly-agent-logic@0.1.0 check-coverage {prompt file} {map file}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
If it exits 1, it lists each block of the prompt that no entry quotes, as `line <N>: <opening words>`, and each entry whose quote does not occur exactly once. Map every instruction of each listed block, holding it in the draft as the Coverage bullet says, lengthen each listed quote until it occurs once, and run the check again. After the third run, go on to the next check, whatever the map check reports, and keep the `line` lines of its last run for the report. If it exits 2, handle it as step 7 states.
|
|
46
|
+
|
|
47
|
+
- **Inputs.** List each input that the prompt tells the agent to read, fetch, or receive, such as a page, a list, or a field of the request. For each one, find an element that uses what the input supplies: a later action, a guard, or an ambient rule. Record an `unused-input` finding, as the rules' "Findings" section states, for each input that no element uses.
|
|
48
|
+
- **Inferred quotes.** Read the quote of each element that has `meta.inferred` on its own, and ask whether those words name the element, as the rules' "Quotes" section requires. Replace a quote that names a neighbouring step or the question that precedes the element.
|
|
49
|
+
4. Run the script:
|
|
50
|
+
|
|
51
|
+
```shell
|
|
52
|
+
pnpm dlx codeassembly-agent-logic@0.1.0 convert {prompt file} {draft file} {output file}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
When a problems path is given, add `--problems-file {problems path}` before `{prompt file}`.
|
|
56
|
+
|
|
57
|
+
5. If the script exits 1, it lists each problem by its path in the draft. Correct every listed entry in the draft and run it again. Repeat until it exits 0 or 3, for at most 5 runs. If the fifth run exits 1, stop, delete the draft file and the map file, and report the problems that it listed.
|
|
58
|
+
6. If the script exits 3, it wrote no config. Do not run it again: Delete the draft file, then report that the prompt is out of scope, with the reason.
|
|
59
|
+
7. If either command exits 2, an argument or file is wrong, and it names the problem on stderr. Correct the argument or file and run the command again; if you cannot correct it, stop, delete the draft file and the map file, and report the message.
|
|
60
|
+
8. If the script exits 0, delete the draft file and the map file, then report the output path, the number of ambient instructions, the number of findings of each kind, the passages listed under `meta.unconverted`, and the blocks that the map check still listed on its last run, as it printed them.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: create-commit
|
|
3
|
-
description: Compose and record a commit for one logical unit of work. Pass the paths to stage
|
|
3
|
+
description: Compose and record a commit for one logical unit of work. Pass the paths to stage, a one-line statement of the change's purpose, and, when the change is in a worktree other than the session's cwd, that worktree's path.
|
|
4
4
|
background: false
|
|
5
5
|
context: fork
|
|
6
6
|
model: sonnet
|
|
@@ -17,9 +17,14 @@ The conventions to which the message is composed -- title format, body voice and
|
|
|
17
17
|
|
|
18
18
|
- **Paths**: The paths that this commit records. When the arguments do not name any, the candidates are every changed path in the working tree.
|
|
19
19
|
- **Purpose**: One line stating why the change was made. The diff shows what changed; the purpose is the only source of why. When the arguments do not state one, compose the body from the diff alone, and never state a reason that the diff does not show.
|
|
20
|
+
- **Working directory**: The worktree that contains the change, `{dir}` below. When the arguments do not name one, it is the directory in which this procedure starts. Every command below runs against it: each git call as `git -C {dir}`, the session-context deriver with `--cwd {dir}`, and the title renderer with `--project-root {dir}`, so that the branch, the ticket ref, and the title format all come from the worktree that is committed.
|
|
20
21
|
|
|
21
22
|
Everything else comes from the repository: This procedure may run without the conversation that produced the change, so it never relies on anything that only that conversation contains.
|
|
22
23
|
|
|
24
|
+
## What this procedure writes
|
|
25
|
+
|
|
26
|
+
It writes the commit message file and the commit, and nothing else. It never edits, creates, or deletes any other file, and never installs or builds anything: A commit records work that is already done, so a change missing from the working tree is a reason to stop, never one to produce it.
|
|
27
|
+
|
|
23
28
|
## What one commit contains
|
|
24
29
|
|
|
25
30
|
One logical unit of work, together with whatever that unit needs to stand on its own. Work that does not stand alone -- a scaffold filled in by a later change -- goes into the change that completes it rather than becoming a commit of its own.
|
|
@@ -28,9 +33,9 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
28
33
|
|
|
29
34
|
## Process
|
|
30
35
|
|
|
31
|
-
1. **Read what changed.** Run `git status --short` for which paths changed, then `git diff` and `git diff --cached` for what changed in them. The message reports the diff, so compose it from the diff rather than from what the work set out to do.
|
|
36
|
+
1. **Read what changed.** Run `git -C {dir} status --short` for which paths changed, then `git -C {dir} diff` and `git -C {dir} diff --cached` for what changed in them. The message reports the diff, so compose it from the diff rather than from what the work set out to do.
|
|
32
37
|
|
|
33
|
-
2. **Stage the unit.**
|
|
38
|
+
2. **Stage the unit.** First confirm that the working tree contains the change that the arguments describe. When a path that the arguments name is unchanged, or when none of the changed paths matches the stated purpose, stop without committing and without staging, and report `{dir}` and what `git -C {dir} status --short` showed there. Otherwise, stage the paths that the arguments name, then confirm that the message will describe exactly the staged set. When the arguments do not name any, stage every changed path, but only if those changes form one unit per [What one commit contains](#what-one-commit-contains); if they don't, stop without committing and report the units that you found.
|
|
34
39
|
|
|
35
40
|
3. **Resolve the title's fields.** The scope and the work type per the conventions, choosing the type by [Work type test](#work-type-test); the title text per [`title-voice.md`](../_data/title-voice.md), with any backticks stripped.
|
|
36
41
|
|
|
@@ -43,7 +48,7 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
43
48
|
```bash
|
|
44
49
|
body_path="{absolute path from the write step}"
|
|
45
50
|
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
46
|
-
git commit --file "$body_path"
|
|
51
|
+
git -C "{dir}" commit --file "$body_path"
|
|
47
52
|
```
|
|
48
53
|
|
|
49
54
|
7. **Report the result**: the new commit's short SHA and title, or, when step 2 stopped or the commit failed, why nothing was committed. Do not comment on the title's format. The template sets which tokens the title contains, a ticket reference among them, so neither a token that the title omits nor a difference from earlier commits is a finding.
|
|
@@ -54,7 +59,7 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
54
59
|
|
|
55
60
|
## Rendering the title
|
|
56
61
|
|
|
57
|
-
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash for `ticket_ref`, then render
|
|
62
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --cwd {dir}` via Bash for `ticket_ref`, then render, passing `{dir}` as `{project_root}`:
|
|
58
63
|
|
|
59
64
|
<!-- include: ../_partials/commit-title-rendering.md / -->
|
|
60
65
|
|
|
@@ -125,16 +125,16 @@ If the change summary's body does not end with a block, append the closing line
|
|
|
125
125
|
|
|
126
126
|
Pass the following inputs to the selected delegate per the delegate interface:
|
|
127
127
|
|
|
128
|
-
| Input | Value
|
|
129
|
-
| ------------------- |
|
|
130
|
-
| `title` | Rendered `pr_title` from step 6 (or bare `title` if the script was unavailable)
|
|
131
|
-
| `body` | Content from `## What` onward in the change summary, with the closing line inserted per step 9
|
|
132
|
-
| `labels` | Resolved label names (may be empty list)
|
|
133
|
-
| `base_branch` | Bare branch name derived from `default_branch` (strip remote prefix, e.g., `origin/main` -> `main`)
|
|
134
|
-
| `ticket_id` | From session context
|
|
135
|
-
| `project_slug` | From session context
|
|
136
|
-
| `artifact_base_dir` | From session context
|
|
137
|
-
| `initial_state` | `pr_initial_state` from session context: `draft` or `ready`
|
|
128
|
+
| Input | Value |
|
|
129
|
+
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
130
|
+
| `title` | Rendered `pr_title` from step 6 (or bare `title` if the script was unavailable) |
|
|
131
|
+
| `body` | Content from `## What` onward in the change summary, `## Notes for reviewers` and `## How to test` included when the summary has them, with the closing line inserted per step 9 |
|
|
132
|
+
| `labels` | Resolved label names (may be empty list) |
|
|
133
|
+
| `base_branch` | Bare branch name derived from `default_branch` (strip remote prefix, e.g., `origin/main` -> `main`) |
|
|
134
|
+
| `ticket_id` | From session context |
|
|
135
|
+
| `project_slug` | From session context |
|
|
136
|
+
| `artifact_base_dir` | From session context |
|
|
137
|
+
| `initial_state` | `pr_initial_state` from session context: `draft` or `ready` |
|
|
138
138
|
|
|
139
139
|
### 11. Persist the PR URL
|
|
140
140
|
|
|
@@ -148,4 +148,4 @@ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
|
|
|
148
148
|
|
|
149
149
|
- The orchestrator makes all decisions (scope, type, title rendering, labels). Delegates only make the platform API calls.
|
|
150
150
|
- Strip the remote prefix from `default_branch` (e.g., `origin/main` -> `main`) before passing to the delegate.
|
|
151
|
-
-
|
|
151
|
+
- The body consists of the change summary's sections, which `summarize-change` writes under its reader test; never add a section, a note, or a test plan of your own.
|
|
@@ -383,6 +383,7 @@ Relationships: {list} <- only if any were created
|
|
|
383
383
|
Relationships skipped: {list with reasons} <- only if any were skipped
|
|
384
384
|
Labels skipped: {labels} <- only when `--label` was given on the Jira path
|
|
385
385
|
Branch association skipped: {reason} <- only when the step-6 guard skipped the persist
|
|
386
|
+
Start in its worktree: {skill?:start-ticket} <- omitted for a ticket in another repository
|
|
386
387
|
Target configuration missing: {files} <- only when the target's default branch lacks a file in `missing`
|
|
387
388
|
```
|
|
388
389
|
|