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.
Files changed (110) hide show
  1. package/.meta/changelog.json +491 -0
  2. package/CHANGELOG.md +118 -0
  3. package/README.md +33 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  6. package/content/codeassembly-content.yaml +4 -0
  7. package/content/collections/recommended.md +5 -2
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  13. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  17. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  20. package/content/guidance/shared/AGENTS.md +1 -1
  21. package/content/scripts/check-prose.mjs +1 -1
  22. package/content/scripts/describe-change.mjs +88 -88
  23. package/content/scripts/manage-jira-ticket.mjs +113 -113
  24. package/content/scripts/select-lede-exemplars.mjs +85 -85
  25. package/content/scripts/validate-preferences.mjs +38 -38
  26. package/content/skills/_data/action-items.md +2 -2
  27. package/content/skills/_data/artifact-conventions.md +20 -10
  28. package/content/skills/_data/concision.md +1 -1
  29. package/content/skills/_data/entry-points.md +37 -0
  30. package/content/skills/_data/project-stage.md +9 -5
  31. package/content/skills/_data/recommendation-gradient.md +6 -6
  32. package/content/skills/_data/spike-conventions.md +20 -7
  33. package/content/skills/_data/ticket-source-resolution.md +21 -4
  34. package/content/skills/_data/title-templates.md +4 -4
  35. package/content/skills/_partials/commit-title-rendering.md +2 -1
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/next-steps-after-plan.md +6 -5
  38. package/content/skills/_partials/option-format.md +8 -8
  39. package/content/skills/_partials/plan-template.md +5 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  41. package/content/skills/_partials/split-launch-prompts.md +2 -2
  42. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  43. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  44. package/content/skills/analyze-performance/SKILL.md +102 -0
  45. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  46. package/content/skills/assess-code-health/SKILL.md +16 -14
  47. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  48. package/content/skills/assess-usability/SKILL.md +5 -3
  49. package/content/skills/capture-event/SKILL.md +20 -11
  50. package/content/skills/capture-event/capture-event.mjs +122 -122
  51. package/content/skills/capture-feedback/SKILL.md +2 -1
  52. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  53. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  54. package/content/skills/create-commit/SKILL.md +10 -5
  55. package/content/skills/create-pr/SKILL.md +11 -11
  56. package/content/skills/create-ticket/SKILL.md +1 -0
  57. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  58. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  59. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  60. package/content/skills/design-and-plan/SKILL.md +6 -4
  61. package/content/skills/implement-plan/SKILL.md +4 -29
  62. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  63. package/content/skills/index-prototypes/SKILL.md +36 -17
  64. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  65. package/content/skills/investigate-spike/SKILL.md +48 -0
  66. package/content/skills/kb-add/SKILL.md +12 -3
  67. package/content/skills/kb-add/kb-add.mjs +88 -88
  68. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  69. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  70. package/content/skills/kb-retrieve/SKILL.md +8 -3
  71. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  72. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  73. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  74. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  75. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  76. package/content/skills/list-implementation-order/SKILL.md +23 -0
  77. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  78. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  79. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  80. package/content/skills/merge-pr/SKILL.md +55 -20
  81. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  82. package/content/skills/plan/SKILL.md +3 -1
  83. package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
  84. package/content/skills/refine-plan/SKILL.md +9 -4
  85. package/content/skills/refine-prototype/SKILL.md +5 -5
  86. package/content/skills/review-branch/SKILL.md +8 -8
  87. package/content/skills/review-criteria/SKILL.md +4 -4
  88. package/content/skills/review-gh-pr/SKILL.md +1 -1
  89. package/content/skills/revise-prose/SKILL.md +9 -8
  90. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  91. package/content/skills/save-plan/SKILL.md +2 -0
  92. package/content/skills/start-ticket/SKILL.md +27 -0
  93. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  94. package/content/skills/summarize-change/SKILL.md +27 -9
  95. package/content/skills/testing-conventions/SKILL.md +14 -3
  96. package/content/skills/triage-feedback/SKILL.md +4 -0
  97. package/content/skills/triage-spike-findings/SKILL.md +36 -12
  98. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  99. package/content/skills/wrap-up/SKILL.md +4 -0
  100. package/content/subagents/_data/claude.yaml +3 -0
  101. package/content/subagents/code-health-assessor.md +4 -4
  102. package/content/subagents/disposition-challenger.md +3 -4
  103. package/content/subagents/entry-drafter.md +2 -2
  104. package/content/subagents/handoff-reviewer.md +1 -1
  105. package/content/subagents/prototype-builder.md +69 -0
  106. package/content/subagents/usability-assessor.md +1 -1
  107. package/package.json +11 -10
  108. package/schemas/preferences.v1.json +74 -8
  109. package/schemas/work-types.v1.json +1 -1
  110. 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 and a one-line statement of the change's purpose.
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.** 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.
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
- - Never list automated checks (formatting, linting, typechecking, unit tests) in a test plan. They run automatically in CI.
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