codeassembly-guidance 0.3.0 → 0.5.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 +385 -272
- package/CHANGELOG.md +39 -0
- package/README.md +8 -40
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/codeassembly-content.yaml +2 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/skills/_data/artifact-conventions.md +9 -423
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/plan-template.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +1 -1
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/kb-edit.mjs +61 -61
- package/content/skills/kb-update-events/kb-update-events.mjs +19 -19
- package/content/skills/lesson-clusters/lesson-clusters.mjs +47 -47
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/refine-guidance/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +66 -66
- package/content/skills/save-artifact/SKILL.md +2 -2
- package/content/skills/streamline-guidance/streamline-guidance.mjs +30 -30
- package/content/skills/triage-feedback/SKILL.md +8 -23
- package/content/skills/triage-feedback/triage-feedback.mjs +7 -7
- package/content/skills/triage-spike-findings/SKILL.md +1 -1
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +10 -5
- package/content/subagents/plan-reviewer.md +8 -7
- package/package.json +6 -6
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
|
@@ -65,7 +65,7 @@ root: {repository root}
|
|
|
65
65
|
|
|
66
66
|
**A reply that lacks the `Phase: disposition-challenge` line is a challenger stopped by its turn limit.** Resume it once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. When the resumed challenger still does not return a report, do not dispatch again: Record the challenge as not returned, treat every item as unchallenged, and say so in the record's `challengeSummary`.
|
|
67
67
|
|
|
68
|
-
Save the reply as `challenge.md`. Then take each item in turn: Defend the recommendation when the argument fails on the evidence, modify it when the argument stands in part, and abandon it when the argument stands.
|
|
68
|
+
Save the reply as `challenge.md`. Then take each item in turn: Defend the recommendation when the argument fails on the evidence, modify it when the argument stands in part, and abandon it when the argument stands. A defense answers the argument on the evidence that the argument names; a defense that rests on other grounds fails.
|
|
69
69
|
|
|
70
70
|
Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. Record every such dependency in `blockedBy`, never in `notes`.
|
|
71
71
|
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: feedback-coverage-judge
|
|
3
|
+
description: Sort each feedback event of one curation assignment into covered, duplicate, obsolete, or kept, by reading guidance at pinned commits, and write the bins file. Returns a summary line and writes only its output file.
|
|
4
|
+
disallowedTools: Edit, NotebookEdit, Task
|
|
5
|
+
maxTurns: 60
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Feedback coverage judge
|
|
9
|
+
|
|
10
|
+
You read one assignment of feedback events, grouped by the lesson that they teach, and decide for each event whether it still needs attention. You have not seen the sessions that captured the events, and you do not need to: The assignment contains each event's summary and the opening of its body, the addressed events that a duplicate can point to, and the guidance repositories pinned at a commit. You write one file, the bins file, and nothing else.
|
|
11
|
+
|
|
12
|
+
## Your assignment
|
|
13
|
+
|
|
14
|
+
Your dispatch contains two scalars:
|
|
15
|
+
|
|
16
|
+
- **`assignment`**: The path of the assignment, a JSON file with `clusters` (each with an `id`, a `lesson`, and its `events`), `references` (addressed events, each with an `id`, a `summary`, an `excerpt`, and its `references`), and `pins` (each guidance repository's `repo`, `root`, `branch`, `sha`, and the source directories in it).
|
|
17
|
+
- **`output`**: The path to which you write the bins file.
|
|
18
|
+
|
|
19
|
+
Read the assignment in full before judging. Place every event of every cluster in exactly one bin. An event with `deferredAt` was set aside by an earlier triage; judge it like any other.
|
|
20
|
+
|
|
21
|
+
<HARD-GATE>
|
|
22
|
+
Write only the file at `output`. Do not create, edit, or delete any other file, do not write to a knowledge store or a tracker, and do not run a git command that changes a ref, the index, or the working tree.
|
|
23
|
+
</HARD-GATE>
|
|
24
|
+
|
|
25
|
+
## How to read guidance
|
|
26
|
+
|
|
27
|
+
Read guidance only at the pinned commits, never in a working tree, which may contain unmerged changes:
|
|
28
|
+
|
|
29
|
+
- Search a repository with `git -C {root} grep -n -i -e {pattern} {sha} -- {pathspec}`.
|
|
30
|
+
- Read a file with `git -C {root} show {sha}:{path}`.
|
|
31
|
+
- List files with `git -C {root} ls-tree -r --name-only {sha} -- {pathspec}`.
|
|
32
|
+
- Find the change that removed or renamed a path with `git -C {root} log --first-parent --diff-filter=DR --name-status -1 {sha} -- {path}`, and read its full message with `git -C {root} show --no-patch --format=%B {commit}`. On the first-parent line, the commit is the one whose message contains the change's `change-record` block, when the change has one.
|
|
33
|
+
|
|
34
|
+
Start from the cluster's lesson, then search for the behavior that it names, in the source directories of each pin and anywhere else in its repository that states guidance, such as `AGENTS.md`. Judge a cluster's events together, since they teach one lesson, but place each one on its own: One event of a cluster may be covered while another names a detail that the guidance does not state.
|
|
35
|
+
|
|
36
|
+
## The bins
|
|
37
|
+
|
|
38
|
+
- **`covered`**: A guidance file at its pin states the lesson, so an agent that follows the file behaves as the event asks. A file that only relates to the lesson, or states a broader rule from which the lesson would have to be inferred, does not cover it. Give the pin's `repo` as `source`, the file's path relative to the repository root as `path`, the sentence that states the lesson as `quote`, copied verbatim from the file at the pin, and how that sentence covers the event as `reason`. `validate` rejects a quote that the file does not contain, ignoring only differences in whitespace and in `*`, `_`, and backtick markers.
|
|
39
|
+
- **`duplicate`**: An entry of `references` teaches the same lesson, so the lesson is already addressed by what that entry references. Give the entry's `id` as `duplicateOf`, and state the shared lesson in `reason`.
|
|
40
|
+
- **`obsolete`**: The lesson no longer applies, because its target was removed without a successor, because a later deliberate decision overruled the lesson, or because it concerns a harness or model no longer in use. A removal or a decision must be visible in the guidance or the git history at the pin. State which of the three holds and the evidence in `reason`.
|
|
41
|
+
|
|
42
|
+
Before you choose `obsolete` because the target was removed, find the change that removed it and read its message. The target has a successor when the change renamed or moved it, when a `migration` line of the message's `change-record` block names a replacement, or when the message's prose names one. An event whose target has a successor is not obsolete on the removal ground: Judge its lesson against the successor, and place it in `covered` when guidance about the successor states the lesson, in `kept` otherwise. When the message does not name any replacement, the removal ground stands, and `reason` names the commit.
|
|
43
|
+
|
|
44
|
+
- **`kept`**: Anything else. The event stays in the pool for a triage to weigh.
|
|
45
|
+
|
|
46
|
+
When you are unsure, choose `kept`. A wrong `covered`, `duplicate`, or `obsolete` takes a live lesson out of the pool, and nothing removes the mark afterward; a wrong `kept` costs one more look at a later run.
|
|
47
|
+
|
|
48
|
+
## What you write and return
|
|
49
|
+
|
|
50
|
+
Write the bins file to `output` as JSON:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"events": [
|
|
55
|
+
{
|
|
56
|
+
"id": "01K...",
|
|
57
|
+
"bin": "covered",
|
|
58
|
+
"source": "owner/repo",
|
|
59
|
+
"path": "content/guidance/rulebooks/releases.md",
|
|
60
|
+
"quote": "Tag a release only from the default branch.",
|
|
61
|
+
"reason": "The event asks that a release never be tagged from a feature branch, which the sentence forbids."
|
|
62
|
+
},
|
|
63
|
+
{ "id": "01K...", "bin": "duplicate", "duplicateOf": "01J...", "reason": "Same lesson: headings use sentence case." },
|
|
64
|
+
{ "id": "01K...", "bin": "obsolete", "reason": "The target was removed without a successor: 3f2a1c0 deleted the skill, and its message does not name any replacement." },
|
|
65
|
+
{ "id": "01K...", "bin": "kept" }
|
|
66
|
+
]
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
When the dispatcher resumes you with a list of violations, correct the bins file that you wrote and write it again to the same path.
|
|
71
|
+
|
|
72
|
+
Then return only this block:
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
Phase: feedback-coverage
|
|
76
|
+
Status: completed|failed
|
|
77
|
+
Covered: {count}
|
|
78
|
+
Duplicate: {count}
|
|
79
|
+
Obsolete: {count}
|
|
80
|
+
Kept: {count}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`Status: failed` means that you could not read the assignment or write the bins file; state the path and the reason on the line after the block.
|
|
84
|
+
|
|
85
|
+
## How you write
|
|
86
|
+
|
|
87
|
+
<!-- include: ../_partials/plain-speech.md / -->
|
|
88
|
+
|
|
89
|
+
<!-- include: ../_partials/concision.md / -->
|
|
90
|
+
|
|
91
|
+
<!-- include: ../_partials/file-access.md / -->
|
|
92
|
+
|
|
93
|
+
<!-- include: ../_partials/shell-commands.md / -->
|
|
94
|
+
|
|
95
|
+
<!-- guidance-hook: writing-preferences -->
|
|
@@ -39,13 +39,18 @@ Work in rounds, where a round is one turn of tool calls. Batch every read and ch
|
|
|
39
39
|
For each cluster:
|
|
40
40
|
|
|
41
41
|
1. **Check the target.** Confirm that a named target exists, for `ticket-existing`, or does not, for `ticket-new`. Search the guidance for text that already states the lesson: A lesson that the guidance states and the agent still missed is a different problem from a lesson that the guidance lacks, and the target may then be the place where the rule fails to reach the agent rather than the place where it is stated.
|
|
42
|
-
2. **Check the repository.** An artifact with a `<!-- codeassembly-` marker, or one in the library, belongs to the CodeAssembly repository; a project's `.agents/content` artifact belongs to that project's repository. Search the open issues of the target repository with `gh issue list --repo {repo} --search`: A lesson that an open issue already covers takes the `comment` disposition on that issue, not a new ticket.
|
|
43
|
-
3. **
|
|
44
|
-
4. **Argue against the
|
|
45
|
-
5. **
|
|
42
|
+
2. **Check the repository.** An artifact with a `<!-- codeassembly-` marker, or one in the library, belongs to the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`); a project's `.agents/content` artifact belongs to that project's repository. Search the open issues of the target repository with `gh issue list --repo {repo} --search`: A lesson that an open issue already covers takes the `comment` disposition on that issue, not a new ticket.
|
|
43
|
+
3. **Check the guidance history.** Check whether the guidance that governs the lesson changed after the cluster's latest capture, per [Guidance history](#guidance-history).
|
|
44
|
+
4. **Argue against the priority.** Ask what makes the lesson less pressing than its priority says: few events, low ratings, old captures, a reach limited to one rare skill. When the guidance changed after the latest capture, argue that the events show nothing about the current guidance, name the change in the argument, and propose `low` unless evidence shows the failure recurring under the changed guidance. Argue the priority up when the signals support that instead. Read the three signals separately; do not combine them into one score.
|
|
45
|
+
5. **Argue against the disposition.** Ask whether the cluster is worth a ticket, whether deferral only postpones a lesson that recurs, and whether an impact change is the right response to a lesson that nobody will act on.
|
|
46
|
+
6. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the priority, disposition, and target that you would set.
|
|
46
47
|
|
|
47
48
|
Do not propose a new cluster or a change to a cluster's events: The clustering is settled, and you judge what the triage recommends for each cluster. Do not draft the guidance change.
|
|
48
49
|
|
|
50
|
+
## Guidance history
|
|
51
|
+
|
|
52
|
+
<!-- include: ../_partials/guidance-change-since-capture.md / -->
|
|
53
|
+
|
|
49
54
|
## What you return
|
|
50
55
|
|
|
51
56
|
One section per cluster, in the order of the recommendations file, then the return block. Return nothing else, and do not write any file.
|
|
@@ -54,7 +59,7 @@ One section per cluster, in the order of the recommendations file, then the retu
|
|
|
54
59
|
### {id}: {lesson}
|
|
55
60
|
|
|
56
61
|
- Argument: {the strongest case against the priority and the disposition, in one or two sentences}
|
|
57
|
-
- Evidence: {what the guidance and the tracker show, with paths and issue numbers; `Unverified` when the budget ran out before this cluster}
|
|
62
|
+
- Evidence: {what the guidance, its history, and the tracker show, with paths, commits, and issue numbers; `Unverified` when the budget ran out before this cluster}
|
|
58
63
|
- Proposes: {keep | priority {priority}, {disposition} {target or issue URL, when the disposition has one}}
|
|
59
64
|
```
|
|
60
65
|
|
|
@@ -66,13 +66,14 @@ Each finding is tagged with a resolution type:
|
|
|
66
66
|
|
|
67
67
|
### Correctness criteria (X findings)
|
|
68
68
|
|
|
69
|
-
| Focus | Check
|
|
70
|
-
| ------------------------- |
|
|
71
|
-
| Factual accuracy | Referenced files, utilities, APIs exist?
|
|
72
|
-
| Structural soundness | Dependencies ordered? Steps scoped correctly?
|
|
73
|
-
| Requirements traceability | Every requirement has a step? Every step traces to a requirement?
|
|
74
|
-
| Blocker handling | Does a step or risk accept a degraded fallback when it should ask the user for a resource?
|
|
75
|
-
| Actor assignment | Does a task or verification check name the developer as its actor without a `**Residue:**` line stating what the agent cannot do and why?
|
|
69
|
+
| Focus | Check | Resolution |
|
|
70
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
|
|
71
|
+
| Factual accuracy | Referenced files, utilities, APIs exist? | `auto` |
|
|
72
|
+
| Structural soundness | Dependencies ordered? Steps scoped correctly? | `auto` |
|
|
73
|
+
| Requirements traceability | Every requirement has a step? Every step traces to a requirement? | `user` if intentionally omitted; `auto` if overlooked |
|
|
74
|
+
| Blocker handling | Does a step or risk accept a degraded fallback when it should ask the user for a resource? | `auto` |
|
|
75
|
+
| Actor assignment | Does a task or verification check name the developer as its actor without a `**Residue:**` line stating what the agent cannot do and why? | `auto` |
|
|
76
|
+
| Judged writes | When the change adds or changes a skill that writes to shared state, does `## Verification` run the skill against the real data before merge, stopping before the write at its approval checkpoint or as a dry run? When a verdict from an agent decides that write, does a task's acceptance criteria name the evidence and the script that checks it before the write? | `auto` if the verdict's inputs show what evidence fits; `user` otherwise |
|
|
76
77
|
|
|
77
78
|
<!-- guidance-hook: implementation-preferences -->
|
|
78
79
|
<!-- guidance-hook: writing-preferences -->
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codeassembly-guidance",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -9,13 +9,13 @@
|
|
|
9
9
|
"rulebooks",
|
|
10
10
|
"skills"
|
|
11
11
|
],
|
|
12
|
-
"homepage": "https://github.com/williamthorsen/codeassembly/tree/main/packages/guidance#readme",
|
|
12
|
+
"homepage": "https://github.com/williamthorsen/codeassembly-guidance/tree/main/packages/guidance#readme",
|
|
13
13
|
"bugs": {
|
|
14
|
-
"url": "https://github.com/williamthorsen/codeassembly/issues"
|
|
14
|
+
"url": "https://github.com/williamthorsen/codeassembly-guidance/issues"
|
|
15
15
|
},
|
|
16
16
|
"repository": {
|
|
17
17
|
"type": "git",
|
|
18
|
-
"url": "https://github.com/williamthorsen/codeassembly.git",
|
|
18
|
+
"url": "https://github.com/williamthorsen/codeassembly-guidance.git",
|
|
19
19
|
"directory": "packages/guidance"
|
|
20
20
|
},
|
|
21
21
|
"license": "ISC",
|
|
@@ -43,12 +43,12 @@
|
|
|
43
43
|
"@hyperjump/json-schema": "1.18.0",
|
|
44
44
|
"@types/node": "24.19.2",
|
|
45
45
|
"@williamthorsen/change-grammar": "0.3.0",
|
|
46
|
-
"@williamthorsen/kb": "0.11.
|
|
46
|
+
"@williamthorsen/kb": "0.11.1",
|
|
47
47
|
"@williamthorsen/nmr": "0.53.1",
|
|
48
48
|
"@williamthorsen/toolbelt.errors": "0.9.0",
|
|
49
49
|
"@williamthorsen/toolbelt.terminal": "0.3.0",
|
|
50
50
|
"@williamthorsen/toolbelt.testing": "0.8.0",
|
|
51
|
-
"codeassembly": "0.
|
|
51
|
+
"codeassembly": "0.20.0",
|
|
52
52
|
"esbuild": "0.28.2",
|
|
53
53
|
"eslint": "10.13.0",
|
|
54
54
|
"happy-dom": "21.0.4",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://unpkg.com/codeassembly-guidance@0.
|
|
3
|
+
"$id": "https://unpkg.com/codeassembly-guidance@0.5.0/schemas/preferences.v1.json",
|
|
4
4
|
"title": "Preferences",
|
|
5
5
|
"description": "Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",
|
|
6
6
|
"type": "object",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://unpkg.com/codeassembly-guidance@0.
|
|
3
|
+
"$id": "https://unpkg.com/codeassembly-guidance@0.5.0/schemas/work-types.v1.json",
|
|
4
4
|
"additionalProperties": false,
|
|
5
5
|
"description": "Canonical work-types taxonomy consumed by skill content and downstream changelog/release-notes tooling. Defines the work-type vocabulary, tier grouping, breaking-change policy, changelog-eligibility flags, and cross-cutting section markers (e.g., the breaking-changes indicator).",
|
|
6
6
|
"properties": {
|