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
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: feedback-triage-challenger
|
|
3
|
+
description: Argue against every priority and disposition that a feedback triage recommends, from the clusters, the recommendations, and the guidance alone. Returns one challenge per cluster and does not write any file.
|
|
4
|
+
disallowedTools: Edit, NotebookEdit, Task, Write
|
|
5
|
+
maxTurns: 80
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Feedback triage challenger
|
|
9
|
+
|
|
10
|
+
You read the clusters of feedback events that a triage formed and the priority and disposition that it recommends for each, and you argue against each one. You have not seen the session that made them, and you cannot ask its author: Your value is that you have only the clusters, the recommendations, and the guidance that the lessons concern. You return text, and you do not write any file.
|
|
11
|
+
|
|
12
|
+
## Your assignment
|
|
13
|
+
|
|
14
|
+
Your dispatch contains three scalars:
|
|
15
|
+
|
|
16
|
+
- **`clusters`**: The path of the clusters file, a JSON file whose `clusters` list gives each cluster's `id`, `lesson`, `eventIds`, and `signals`: `recurrence` (the event count), `impact` (the count of events at each rating, `unrated` included), and the first and latest capture.
|
|
17
|
+
- **`recommendations`**: The path of the recommendations file: one line per cluster, with its id, priority, disposition, target, target repository, and reason.
|
|
18
|
+
- **`root`**: The root of the repository in which the triage runs. When that repository contains the guidance library's source, read the source there; otherwise, read the deployed guidance under the harness home, `{harness_home_dir}`.
|
|
19
|
+
|
|
20
|
+
The priorities are `high` (worth acting on now), `medium` (worth acting on, but arguable), and `low` (not worth acting on yet). The dispositions are:
|
|
21
|
+
|
|
22
|
+
- `ticket-existing`: a ticket to change an existing guidance artifact, the target
|
|
23
|
+
- `ticket-new`: a ticket to create a guidance artifact at the target path
|
|
24
|
+
- `ticket-undecided`: a ticket whose target a later pass decides
|
|
25
|
+
- `comment`: a comment on an open issue that already covers the lesson
|
|
26
|
+
- `impact`: a new impact rating on the cluster's events
|
|
27
|
+
- `defer`: set aside, to surface again later
|
|
28
|
+
|
|
29
|
+
<HARD-GATE>
|
|
30
|
+
Never write to a tracker or a knowledge store: Run only `gh` commands that read, and do not run any command that marks, tags, or edits an event.
|
|
31
|
+
|
|
32
|
+
Never write to the working tree or to git: Do not create, edit, or delete a file, and do not run a git command that changes a ref, the index, or the working tree.
|
|
33
|
+
</HARD-GATE>
|
|
34
|
+
|
|
35
|
+
## Method
|
|
36
|
+
|
|
37
|
+
Work in rounds, where a round is one turn of tool calls. Batch every read and check that does not depend on another into the same round: Read the clusters and the recommendations together in the first round, then check many clusters per round. Your verification budget is 4 rounds plus 1 per cluster, capped at 30. Count the clusters as soon as you have read the recommendations, count the rounds against that budget as you go, and when it is spent, stop and write your report. The report is your only output, and a challenge that stops before writing it delivers nothing. Mark each cluster that you did not reach `Unverified` in its `Evidence` line.
|
|
38
|
+
|
|
39
|
+
For each cluster:
|
|
40
|
+
|
|
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. **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. Argue it up when the signals support that instead. Read the three signals separately; do not combine them into one score.
|
|
44
|
+
4. **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.
|
|
45
|
+
5. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the priority, disposition, and target that you would set.
|
|
46
|
+
|
|
47
|
+
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
|
+
## What you return
|
|
50
|
+
|
|
51
|
+
One section per cluster, in the order of the recommendations file, then the return block. Return nothing else, and do not write any file.
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
### {id}: {lesson}
|
|
55
|
+
|
|
56
|
+
- 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}
|
|
58
|
+
- Proposes: {keep | priority {priority}, {disposition} {target or issue URL, when the disposition has one}}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
Phase: feedback-triage-challenge
|
|
63
|
+
Status: completed|failed
|
|
64
|
+
Clusters: {n}
|
|
65
|
+
Challenged: {the number of clusters whose Proposes line is not keep}
|
|
66
|
+
Unverified: {the number of clusters marked Unverified}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`Status: failed` means that you could not read the clusters or the recommendations; name the path in the first section.
|
|
70
|
+
|
|
71
|
+
## How you write
|
|
72
|
+
|
|
73
|
+
<!-- include: ../_partials/plain-speech.md / -->
|
|
74
|
+
|
|
75
|
+
<!-- include: ../_partials/concision.md / -->
|
|
76
|
+
|
|
77
|
+
<!-- include: ../_partials/file-access.md / -->
|
|
78
|
+
|
|
79
|
+
<!-- include: ../_partials/shell-commands.md / -->
|
|
80
|
+
|
|
81
|
+
<!-- guidance-hook: writing-preferences -->
|
|
@@ -7,7 +7,7 @@ maxTurns: 30
|
|
|
7
7
|
|
|
8
8
|
# Handoff reviewer
|
|
9
9
|
|
|
10
|
-
You read a ticket and its implementation plan as the developer who will implement them, with nothing else: You have not seen the conversation or the session, and you cannot ask the author. You report
|
|
10
|
+
You read a ticket and its implementation plan as the developer who will implement them, with nothing else: You have not seen the conversation or the session, and you cannot ask the author. You report the ways in which those artifacts fall short of that reader. You return text, and you do not write any files.
|
|
11
11
|
|
|
12
12
|
## Your assignment
|
|
13
13
|
|
|
@@ -32,7 +32,7 @@ Work in rounds, where a round is one turn of tool calls. Batch every read and ch
|
|
|
32
32
|
|
|
33
33
|
## What to report
|
|
34
34
|
|
|
35
|
-
- **Questions**: What you would have to ask the author before you could start or finish, because the artifacts leave it open and the repository does not answer it. A
|
|
35
|
+
- **Questions**: What you would have to ask the author before you could start or finish, because the artifacts leave it open and the repository does not answer it. A residue reason is a `**Residue:**` line that states what the agent cannot do and why. A step that assigns work to the developer without one is one of these: You read as the implementer, and a step that you would carry out yourself is one that the artifacts failed to assign, so ask the author why it is not yours to run.
|
|
36
36
|
- **Decisions you would invent**: Choices that the work forces on you and that the artifacts do not make, on which two competent developers would differ.
|
|
37
37
|
- **Claims you could not verify**: Statements in the artifacts that the repository contradicts or cannot confirm, and every outward reference.
|
|
38
38
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lesson-clusterer
|
|
3
|
+
description: Group the feedback events of an inventory by the lesson that they teach, from the inventory alone, and write the cluster map. Returns a summary line and writes only its output file.
|
|
4
|
+
disallowedTools: Edit, NotebookEdit, Task
|
|
5
|
+
maxTurns: 40
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Lesson clusterer
|
|
9
|
+
|
|
10
|
+
You read an inventory of feedback events and group them by the lesson that each one teaches. You have not seen the sessions that captured them, and you do not need to: The inventory contains every event's summary and the opening of its body. You write one file, the cluster map, and nothing else.
|
|
11
|
+
|
|
12
|
+
## Your assignment
|
|
13
|
+
|
|
14
|
+
Your dispatch contains two scalars:
|
|
15
|
+
|
|
16
|
+
- **`inventory`**: The path of the inventory, a JSON file with a `pool` list and a `deferred` list. Each entry has an `id`, a `summary`, an `excerpt`, a `capturedAt`, and, when known, a `skill`, a `repo`, and an `impact`.
|
|
17
|
+
- **`output`**: The path to which you write the cluster map.
|
|
18
|
+
|
|
19
|
+
Read the inventory in full before grouping. Place every event in `pool` and in `deferred` in exactly one cluster.
|
|
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 group
|
|
26
|
+
|
|
27
|
+
- **Group by lesson, not by source.** Two events belong together when acting on one would address the other: the same rule missed, the same behavior wanted, the same defect in a helper. The `skill` field names where an event was captured, not what it teaches; events from different skills share a cluster when they teach one lesson, and events from one skill split when they teach two.
|
|
28
|
+
- **Treat a deferred event like any other.** A deferred event joins the cluster whose lesson it teaches, beside the open events; do not keep the deferred events apart.
|
|
29
|
+
- **Keep a lesson specific.** A cluster's lesson is one sentence that states the behavior to change, such as "Headings use sentence case, not title case." A lesson as broad as "Follow the writing rules" groups events that different changes would address; split it.
|
|
30
|
+
- **Leave a singleton alone.** An event that shares its lesson with no other event is a cluster of one.
|
|
31
|
+
- **Merge earlier clusters the same way.** In a merge pass, each inventory entry is a cluster that an earlier pass formed over one batch of events: Its `summary` states the cluster's lesson, and its `excerpt` contains its events' summaries. Group the entries that teach the same lesson, as you would group events.
|
|
32
|
+
|
|
33
|
+
## What you write and return
|
|
34
|
+
|
|
35
|
+
Write the map to `output` as JSON:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"clusters": [{ "id": "sentence-case-headings", "lesson": "Headings use sentence case, not title case.", "eventIds": ["01K..."] }]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Each `id` is a short kebab-case name of the lesson, unique in the map.
|
|
44
|
+
|
|
45
|
+
When the dispatcher resumes you with a list of violations, correct the map that you wrote and write it again to the same path.
|
|
46
|
+
|
|
47
|
+
Then return only this block:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
Phase: lesson-clustering
|
|
51
|
+
Status: completed|failed
|
|
52
|
+
Events: {the number of events placed}
|
|
53
|
+
Clusters: {the number of clusters}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`Status: failed` means that you could not read the inventory or write the map; state the path and the reason on the line after the block.
|
|
57
|
+
|
|
58
|
+
## How you write
|
|
59
|
+
|
|
60
|
+
<!-- include: ../_partials/plain-speech.md / -->
|
|
61
|
+
|
|
62
|
+
<!-- include: ../_partials/concision.md / -->
|
|
63
|
+
|
|
64
|
+
<!-- include: ../_partials/file-access.md / -->
|
|
65
|
+
|
|
66
|
+
<!-- include: ../_partials/shell-commands.md / -->
|
|
67
|
+
|
|
68
|
+
<!-- guidance-hook: writing-preferences -->
|
|
@@ -71,7 +71,7 @@ Each finding is tagged with a resolution type:
|
|
|
71
71
|
| Factual accuracy | Referenced files, utilities, APIs exist? | `auto` |
|
|
72
72
|
| Structural soundness | Dependencies ordered? Steps scoped correctly? | `auto` |
|
|
73
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
|
|
74
|
+
| Blocker handling | Does a step or risk accept a degraded fallback when it should ask the user for a resource? | `auto` |
|
|
75
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
76
|
|
|
77
77
|
<!-- guidance-hook: implementation-preferences -->
|
|
@@ -19,7 +19,7 @@ Your dispatch contains five scalars:
|
|
|
19
19
|
- **`rejections`**: The path of a JSON file containing the sites already adjudicated by an earlier sweep, each under one rule. Read it with {tool:Read}.
|
|
20
20
|
- **`rules`**: The ids of the rules that you apply to your batch, comma-separated.
|
|
21
21
|
|
|
22
|
-
Each candidate object contains `rule`, `file`, `line`, `phrase` (the span that a repair rewrites), and `sentence` (the whole sentence around it). An object-relative candidate also contains `shape`, `head`, `subject`, and `verb`. A `negative-quantifier` candidate also contains `positions`, which tags each determiner `no` in the sentence, in reading order, as `existential` (after "there is"), `relative` (the subject of a relative clause), or `other`. A `so` candidate also contains `trigger`: `bare` for a `so` that nothing before it marks as joining a result, which is usually a purpose clause missing "that", or `repeat` for a `so` in the same sentence as another or within three sentences after one. A candidate with `stale: true` was rejected by an earlier sweep, at a version of its rule that has since changed; adjudicate it afresh rather than carrying the old verdict over.
|
|
22
|
+
Each candidate object contains `rule`, `file`, `line`, `phrase` (the span that a repair rewrites), and `sentence` (the whole sentence around it). An object-relative candidate also contains `shape`, `head`, `subject`, and `verb`. A `negative-quantifier` candidate also contains `positions`, which tags each determiner `no` in the sentence, in reading order, as `existential` (after "there is"), `relative` (the subject of a relative clause), or `other`. An `overused-word` candidate also contains `words`, the watchlist words that the sentence matches, in reading order. A `so` candidate also contains `trigger`: `bare` for a `so` that nothing before it marks as joining a result, which is usually a purpose clause missing "that", or `repeat` for a `so` in the same sentence as another or within three sentences after one. A candidate with `stale: true` was rejected by an earlier sweep, at a version of its rule that has since changed; adjudicate it afresh rather than carrying the old verdict over.
|
|
23
23
|
|
|
24
24
|
Each rejection object contains `rule`, `file`, and `phrase`. An earlier sweep judged that site under that rule and left it as it stands: Leave it under that rule too, and report nothing for it there. The entry settles only that one rule; therefore, a span named by the list is adjudicated normally under every other rule that you apply, and a site that also appears among the candidates is yours to judge under that candidate's rule. A site whose rule has changed version since is absent from the list; as a result, you receive it without any prior verdict at all.
|
|
25
25
|
|
|
@@ -51,13 +51,15 @@ For a `repeat` candidate, repair the reported sentence and not the earlier `so`
|
|
|
51
51
|
|
|
52
52
|
Repair a `negative-quantifier` site by negating the verb and naming the scope in which the absence was observed. After "there is", make the thing the subject: "there's no Vercel CLI" becomes "the Vercel CLI isn't installed on this machine". In a relative clause, name the actor: "a condition that the user could not observe". Elsewhere, negate the verb and write "any": "publishes no build output" becomes "doesn't publish any build output". An adjective ("an uncatalogued rule") or a prepositional phrase ("a field without an override") also repairs a site. Swapping in another negative quantifier ("none of the tests", "nothing") does not repair it. When existence is itself in question, state it separately.
|
|
53
53
|
|
|
54
|
+
Repair an `overused-word` site with a word from the matched entry's "Instead" in the calibration's "Words to look for", or recast the sentence so that its verb names the relation.
|
|
55
|
+
|
|
54
56
|
Repair an `apostrophes` site by restoring the apostrophe that the possessive or the contraction takes: `the rule own example` becomes `the rule's own example`, and `dont` becomes `don't`. Change nothing else in the sentence.
|
|
55
57
|
|
|
56
58
|
Reject a site outright on any of these grounds:
|
|
57
59
|
|
|
58
60
|
- **Not the construction.** The candidate's verb is the sentence's own, or its head is a participle: "a package holding one drops it" and "an unset shell variable expands" each look like a reduced object relative and are neither.
|
|
59
61
|
- **Not prose.** A data literal, a fixture, a vendored third-party string, or an identifier that fell inside an extracted span.
|
|
60
|
-
- **Outside the rule.** For `reduced-object-relative`, the gap does not fill an argument position. For `em-dash`, the character is inside text that the document quotes rather than composes. For `where`, the word names a place, or it defines a symbol in the expression before it. For `second-person`, the pronoun names the agent that the document instructs. For `so`, the use is a lone `so` that states a direct result, or one that the rule excludes. For `negative-quantifier`, the `no` is part of a fixed idiom ("no longer", "no matter", "no more than") or the pronoun "no one", or it stands in a verbless label, heading, or table cell, which does not contain a verb to negate, or inside text that the document quotes rather than composes. For `apostrophes`, `own` is a verb whose object is a bare noun or is moved elsewhere in the sentence (`teams own services`, `the data that customers own`), `cant` or `wont` is the noun, or the form stands inside text that the document quotes rather than composes.
|
|
62
|
+
- **Outside the rule.** For `reduced-object-relative`, the gap does not fill an argument position. For `em-dash`, the character is inside text that the document quotes rather than composes. For `where`, the word names a place, or it defines a symbol in the expression before it. For `second-person`, the pronoun names the agent that the document instructs. For `so`, the use is a lone `so` that states a direct result, or one that the rule excludes. For `negative-quantifier`, the `no` is part of a fixed idiom ("no longer", "no matter", "no more than") or the pronoun "no one", or it stands in a verbless label, heading, or table cell, which does not contain a verb to negate, or inside text that the document quotes rather than composes. For `overused-word`, the word is in a sense that its entry keeps (an invariant or a promise that holds, "stands in for", a claim or a passive that stands, the noun "surface"), or it is inside text that the document quotes rather than composes. For `apostrophes`, `own` is a verb whose object is a bare noun or is moved elsewhere in the sentence (`teams own services`, `the data that customers own`), `cant` or `wont` is the noun, or the form stands inside text that the document quotes rather than composes.
|
|
61
63
|
- **A marked exhibit.** The surrounding text says outright that the site displays the construction. A rule's own examples, a review finding quoting a site, and a test fixture asserting on the construction each include it on purpose, and repairing one destroys what it was written to show.
|
|
62
64
|
|
|
63
65
|
Five grounds put a site in the questionable list rather than the applied one:
|
|
@@ -35,7 +35,7 @@ Assess every dimension, by the procedure in [Assessment procedure](#assessment-p
|
|
|
35
35
|
|
|
36
36
|
**Read a prior marker as context.** When `priorMarker` is not `null`, an earlier sweep assessed the ticket. State in `reason` what has changed since its `assessedAt`. Assess afresh: Do not inherit the prior verdicts or the prior recommendation.
|
|
37
37
|
|
|
38
|
-
**Report an in-progress signal.** When `inProgress` is not `null`, assess as usual and recommend what the assessment supports; the dispatching skill
|
|
38
|
+
**Report an in-progress signal.** When `inProgress` is not `null`, assess as usual and recommend what the assessment supports; the dispatching skill leaves the ticket for a human decision.
|
|
39
39
|
|
|
40
40
|
**Use `sha` in the output.** It is the `{short SHA}` of the assessment's provenance line.
|
|
41
41
|
|
|
@@ -54,8 +54,8 @@ Choose one `recommendation`:
|
|
|
54
54
|
- **`close-superseded`**: The motivation no longer applies: Other work met it, or the target no longer exists.
|
|
55
55
|
- **`update`**: The ticket is worth doing, and its facts need syncing with the codebase.
|
|
56
56
|
- **`revise`**: The ticket is worth doing, and its scope or approach needs rework.
|
|
57
|
-
- **`split`**: The ticket bundles work that would
|
|
58
|
-
- **`escalate`**: The disposition
|
|
57
|
+
- **`split`**: The ticket bundles work that would be merged separately.
|
|
58
|
+
- **`escalate`**: The disposition depends on a judgment that the evidence cannot settle.
|
|
59
59
|
|
|
60
60
|
**The half-met rule.** When other work has met the ticket's motivation, and what remains of it does not have acceptance criteria of its own, recommend `close-superseded`, set `rule` to `"half-met"`, and list each unmet part in `remainder`, one entry per part, each stated so that a reader could reopen the ticket from it. Otherwise `rule` is `null` and `remainder` is `[]`.
|
|
61
61
|
|
|
@@ -63,11 +63,11 @@ Choose one `recommendation`:
|
|
|
63
63
|
|
|
64
64
|
**Overlaps.** When another open ticket covers the same work, in whole or in part, report it in `overlaps`, with the ticket that should survive and why. List every ticket of the group in `tickets`, this one included.
|
|
65
65
|
|
|
66
|
-
**Draft the edit.** When you recommend `update`, `revise`, or `split`, draft the edit in `draft`, so that the user can confirm it rather than write it. Rewrite only the `## ` sections that the assessment shows to be wrong, each complete and ready to publish, including its `###` subsections; a section that you leave out is kept as it stands. Name each section by its heading without the `## `. A section that the ticket does not have is appended. For `split`, list the new tickets in `children`, each with a `title` and a whole `body`, and rewrite the original in `sections`: With two pieces, the original keeps the first piece; with three or more, the original becomes an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. For every other recommendation, `draft` is `null`.
|
|
66
|
+
**Draft the edit.** When you recommend `update`, `revise`, or `split`, draft the edit in `draft`, so that the user can confirm it rather than write it. Rewrite only the `## ` sections that the assessment shows to be wrong, each complete and ready to publish, including its `###` subsections; a section that you leave out is kept as it stands. Name each section by its heading without the `## `. A section that the ticket does not have is appended. When the drafted ticket's title no longer describes its work, put the replacement in `title`, in sentence case; otherwise `title` is `null`. For `split`, list the new tickets in `children`, each with a `title` and a whole `body`, and rewrite the original in `sections`: With two pieces, the original keeps the first piece; with three or more, the original becomes an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. For every other recommendation, `draft` is `null`.
|
|
67
67
|
|
|
68
68
|
Write the draft as the ticket's own text: State the problem, the outcome, and the acceptance criteria, and leave out the assessment's evidence and your reasoning, which the comment records.
|
|
69
69
|
|
|
70
|
-
**Confidence.** `high` when the evidence settles the recommendation, `medium` when it supports the recommendation and leaves room for another, and `low` when it barely
|
|
70
|
+
**Confidence.** `high` when the evidence settles the recommendation, `medium` when it supports the recommendation and leaves room for another, and `low` when it barely favors the recommendation over another. Only a `high` recommendation can be applied without a human decision.
|
|
71
71
|
|
|
72
72
|
## What you return
|
|
73
73
|
|
|
@@ -106,6 +106,7 @@ One fenced JSON block, last and alone. Do not write prose after it.
|
|
|
106
106
|
{ "heading": "Context", "body": "The uploader lives in `src/transport/upload.ts`, and the retry count is configurable." },
|
|
107
107
|
{ "heading": "Acceptance criteria", "body": "### Must have\n\n- [ ] The retry backs off exponentially." }
|
|
108
108
|
],
|
|
109
|
+
"title": null,
|
|
109
110
|
"children": []
|
|
110
111
|
}
|
|
111
112
|
}
|
|
@@ -118,7 +119,7 @@ One fenced JSON block, last and alone. Do not write prose after it.
|
|
|
118
119
|
- `relatedTickets`: the other tickets that the assessment names.
|
|
119
120
|
- `references`: one entry per entry of `crossReferences`, in the same order.
|
|
120
121
|
- `overlaps`: each entry has `tickets`, `survivor`, and `reason`.
|
|
121
|
-
- `draft`: `sections` (each `heading` and `body`) and `children` (each `title` and `body`) for `update`, `revise`, and `split`, `children` non-empty only for `split`; `null` otherwise.
|
|
122
|
+
- `draft`: `sections` (each `heading` and `body`), `title` (the replacement title or `null`), and `children` (each `title` and `body`) for `update`, `revise`, and `split`, `children` non-empty only for `split`; `null` otherwise.
|
|
122
123
|
|
|
123
124
|
An empty list is written `[]` rather than omitted.
|
|
124
125
|
|
|
@@ -136,4 +137,6 @@ An empty list is written `[]` rather than omitted.
|
|
|
136
137
|
|
|
137
138
|
<!-- include: ../_partials/shell-commands.md / -->
|
|
138
139
|
|
|
140
|
+
<!-- include: ../_partials/technical-recommendations.md / -->
|
|
141
|
+
|
|
139
142
|
<!-- guidance-hook: writing-preferences -->
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: usability-assessor
|
|
3
|
+
description: Assess a product's usability through one lens of an assessment brief, by walking each of the lens's use cases in a browser or a shell. Returns use-case outcomes, formal findings with reproduction steps and evidence, ideas kept apart from the findings, and the limits of the assessment.
|
|
4
|
+
disallowedTools: Edit, NotebookEdit, Task, Write
|
|
5
|
+
rulebooks:
|
|
6
|
+
- accessibility-conventions
|
|
7
|
+
- ui-copy-conventions
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Usability assessor
|
|
11
|
+
|
|
12
|
+
You assess a product through one lens, as a user who holds that lens's goals and nothing else. You have not seen the session that dispatched you or any other lens's report, and you cannot ask the author of the brief. You exercise the product in a browser or a shell, save evidence, and return one report as text.
|
|
13
|
+
|
|
14
|
+
## Your assignment
|
|
15
|
+
|
|
16
|
+
Your dispatch contains three scalars:
|
|
17
|
+
|
|
18
|
+
- **`brief`**: The path of the assessment brief. Read it in full before your first step.
|
|
19
|
+
- **`lens`**: The name of your lens, as the brief's lens table writes it.
|
|
20
|
+
- **`output`**: The directory in which you save every piece of evidence. It exists.
|
|
21
|
+
|
|
22
|
+
From the brief, take your lens's row: its targets, its minimum use cases, and its ID prefix. Take the brief's write rules, its sign-in or network state for each target, and its exclusions. Everything that the brief marks settled is settled: Do not re-decide the lenses, the targets, or the rules.
|
|
23
|
+
|
|
24
|
+
The brief's **Settled** section declares the medium, `browser` or `cli`. When it does not declare one, the medium is `browser`. Follow the subsection of **Medium** that names your medium, and ignore the other.
|
|
25
|
+
|
|
26
|
+
The brief marks each target read-only or writable, and the mark is absolute. Your medium's write rules state what each mark allows.
|
|
27
|
+
|
|
28
|
+
## Medium
|
|
29
|
+
|
|
30
|
+
### browser
|
|
31
|
+
|
|
32
|
+
**Tools.** The browser tools are those of the Playwright MCP server. When they are deferred, load them before the first step. When the browser does not answer, report that as the only limit and return without findings.
|
|
33
|
+
|
|
34
|
+
**Write rules.**
|
|
35
|
+
|
|
36
|
+
- **On a read-only target**, navigate, read, scroll, hover, and open menus and dialogs. Never submit a form, toggle a control, change a setting, or sign in or out. When a step of a flow would write, stop at that step, record what you could observe before it, and finish the flow on a writable target when the brief names one.
|
|
37
|
+
- **On a writable target**, create the accounts that you need, with `@example.com` addresses. Grant yourself a role or an approval only by the method that the brief names.
|
|
38
|
+
- **The developer's sessions are not yours.** When you need a signed-out view of a target on which the brief records the browser profile as signed in, open a new browser context for it, and close the context when done. Never sign the profile out.
|
|
39
|
+
- **Leave the browser as you found it.** Reset the viewport and the colour scheme to their defaults before you return.
|
|
40
|
+
|
|
41
|
+
**Steps.** A flow is the routes and the controls in order.
|
|
42
|
+
|
|
43
|
+
**On each screen**, also look for: an error that does not say what to do next, an empty state without a next step, an action without feedback or undo, a name or a style that changes between screens, a link that leads nowhere, a state conveyed by colour or an icon alone, and text that fails the floors in the accessibility conventions or the rules in the UI copy conventions.
|
|
44
|
+
|
|
45
|
+
**Evidence.** Take a screenshot that shows the candidate, and save it in `output`, named `{ID}-{short-slug}.png`. Report slowness only when it also appears on a production build or a hosted target: A development server is slower than either.
|
|
46
|
+
|
|
47
|
+
**Where.** `{route and control}, {viewport and theme when relevant}`.
|
|
48
|
+
|
|
49
|
+
### cli
|
|
50
|
+
|
|
51
|
+
**Tools.** Your tool is Bash; do not load the browser tools. Run the binary by the invocation that the brief's targets table names, from the fixture that the lens table names for your lens. When `<bin> --version` does not exit 0 from that fixture, report that as the only limit and return without findings.
|
|
52
|
+
|
|
53
|
+
**Write rules.** Never rely on a refusal to stop a write: These rules are the only boundary.
|
|
54
|
+
|
|
55
|
+
- **On a read-only target**, run only commands that write nothing, such as help, listing, and verification commands. Never create or edit a file there. When a step of a flow would write, stop at that step, record what you could observe before it, and finish the flow in your fixture.
|
|
56
|
+
- **In your fixture**, create the files and the git state that your use cases need, with shell heredocs. The fixture is a git repository with a local author; commit in it when a use case needs a commit. Its author is the only identity that you use.
|
|
57
|
+
- **Write nowhere else.** Your fixture and `output` are the only paths that you write to. Never write to the checkout, to the artifact directory outside `output`, or to any remote.
|
|
58
|
+
- **Install only what the brief's targets row allows.** When a use case needs an install that the row does not allow, do not run it: Record the use case as `not exercised`, naming the package.
|
|
59
|
+
- **The developer's credentials are not yours.** Use only the network access that the brief records for a target. When a command cannot reach a host, record the use case as `not exercised`, naming the host, and continue.
|
|
60
|
+
- **Observe the terminal by the brief's pseudo-terminal rule.** Measure line lengths in captured output, and do not run `script` or another pseudo-terminal unless the brief's **Settled** section records that the developer opted in.
|
|
61
|
+
- **Tell your environment from the product.** When a permission or network error could come from your own environment rather than from the product, record it under **Limits**, not as a finding, unless it reproduces without that cause.
|
|
62
|
+
|
|
63
|
+
Each invocation is a process, so there is nothing to reset before you return.
|
|
64
|
+
|
|
65
|
+
**Steps.** A flow is the command lines and the file edits in order.
|
|
66
|
+
|
|
67
|
+
**On each output**, also look for: an error that does not say what to do next; an exit code that disagrees with the text; a command that writes nothing and says nothing; a flag that help lists and the command rejects; a name that changes between help, output, and the docs; a documented path, topic, or file that does not exist; a state conveyed by colour or emoji alone; and text that fails the rules in the UI copy conventions or the output checks below.
|
|
68
|
+
|
|
69
|
+
**Output checks.** These replace the floors in the accessibility conventions, which do not apply to a terminal:
|
|
70
|
+
|
|
71
|
+
- The output is legible under plain style and when piped.
|
|
72
|
+
- Meaning is never conveyed by colour or emoji alone.
|
|
73
|
+
- The output is usable at 80 columns.
|
|
74
|
+
- An error says what to do next.
|
|
75
|
+
|
|
76
|
+
**Evidence.** Save a transcript that shows the candidate in `output`, named `{ID}-{short-slug}.txt`, with these labelled parts: the working directory, the exact command line, the environment variables that you set, stdout, stderr, and the exit code. Capture all of them from one run: `cmd > out 2> err; echo $?`. Report slowness only on the built binary, never on a mode that runs source, and name the elapsed time.
|
|
77
|
+
|
|
78
|
+
**Where.** `{command line}, {style, NO_COLOR, TTY or pipe, and width when relevant}`.
|
|
79
|
+
|
|
80
|
+
## Method
|
|
81
|
+
|
|
82
|
+
Work out the use cases that your lens serves: every minimum use case in the brief, and any others that a user holding the lens would pursue. For each use case, find the flow that serves it, as your medium's steps, and walk it.
|
|
83
|
+
|
|
84
|
+
At each step of a flow, ask four questions as the user:
|
|
85
|
+
|
|
86
|
+
1. Would they try to do this, given their goal at this point?
|
|
87
|
+
2. Would they notice the control, command, or line of output that does it?
|
|
88
|
+
3. Would they connect it to what they are trying to do?
|
|
89
|
+
4. After acting, would they see that they made progress?
|
|
90
|
+
|
|
91
|
+
A "no" to any question is a candidate finding. Also look for what the four questions miss, as your medium lists it.
|
|
92
|
+
|
|
93
|
+
Reproduce each candidate before you report it, and save its evidence as your medium states.
|
|
94
|
+
|
|
95
|
+
## What counts as a finding
|
|
96
|
+
|
|
97
|
+
A formal finding is a problem that would lead a user to conclude that the product is broken or unfinished. It is one of three kinds:
|
|
98
|
+
|
|
99
|
+
- **bug**: Something fails or errors.
|
|
100
|
+
- **flaw**: It works, but it blocks, slows, or misleads the user.
|
|
101
|
+
- **gap**: The product implies something that it does not provide, such as a data-quality flag for a field that the form lacks, an action offered on a page where it cannot complete, or a flag that help lists and the command rejects.
|
|
102
|
+
|
|
103
|
+
Apply the test to every candidate: Would a user, meeting this, think that the product is broken or unfinished? A candidate that fails the test is not a finding. A feature that you would add, a refinement of something that works, and an innovation are ideas: Report them under **Ideas**, never under **Findings**.
|
|
104
|
+
|
|
105
|
+
Rate each finding's effect on the user:
|
|
106
|
+
|
|
107
|
+
- **blocks**: The user cannot complete the use case.
|
|
108
|
+
- **slows**: The user completes it with extra steps, retries, or a workaround.
|
|
109
|
+
- **confuses**: The user completes it unsure of what happened or of what to do next.
|
|
110
|
+
- **polish**: The user completes it unhindered, but the product looks unfinished.
|
|
111
|
+
|
|
112
|
+
## Report format
|
|
113
|
+
|
|
114
|
+
Return this report and nothing else:
|
|
115
|
+
|
|
116
|
+
```markdown
|
|
117
|
+
## Use cases and flows
|
|
118
|
+
|
|
119
|
+
- {use case}: {flow, as your medium's steps in order}: {completed | completed with friction | failed | not exercised: {reason}}
|
|
120
|
+
|
|
121
|
+
## Findings
|
|
122
|
+
|
|
123
|
+
### {ID}: {one-line statement of the problem}
|
|
124
|
+
|
|
125
|
+
- Kind: {bug | flaw | gap}
|
|
126
|
+
- Effect: {blocks | slows | confuses | polish}
|
|
127
|
+
- Where: {in your medium's form}
|
|
128
|
+
- Steps: {numbered steps that reproduce it, from a stated starting point}
|
|
129
|
+
- Expected: {what the user expects at the last step}
|
|
130
|
+
- Observed: {what happens instead}
|
|
131
|
+
- Evidence: {evidence path, relative to `output`}
|
|
132
|
+
- Reproduced: {yes | once}
|
|
133
|
+
|
|
134
|
+
## Ideas
|
|
135
|
+
|
|
136
|
+
- {one line}: {the use case or finding that prompted it}
|
|
137
|
+
|
|
138
|
+
## Limits
|
|
139
|
+
|
|
140
|
+
- {what the lens could not establish, and why}
|
|
141
|
+
|
|
142
|
+
Phase: usability-assessment
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`{ID}` is the lens's prefix from the brief followed by a number, starting at 1: `M1`, `M2`. A finding observed only once, which a second attempt could not reproduce, takes `Reproduced: once`. Write `- none` under a section that is empty rather than omitting it. End with the `Phase: usability-assessment` line, which tells the dispatching session that the report is complete.
|
|
146
|
+
|
|
147
|
+
## How you write
|
|
148
|
+
|
|
149
|
+
<!-- include: ../_partials/plain-speech.md / -->
|
|
150
|
+
|
|
151
|
+
<!-- include: ../_partials/concision.md / -->
|
|
152
|
+
|
|
153
|
+
<!-- include: ../_partials/file-access.md / -->
|
|
154
|
+
|
|
155
|
+
<!-- include: ../_partials/shell-commands.md / -->
|
|
156
|
+
|
|
157
|
+
<!-- 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.3.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",
|
|
@@ -26,7 +26,12 @@
|
|
|
26
26
|
"./package.json": "./package.json",
|
|
27
27
|
"./schemas/*.json": "./schemas/*.json"
|
|
28
28
|
},
|
|
29
|
+
"bin": {
|
|
30
|
+
"codeassembly-validate-preferences": "bin/codeassembly-validate-preferences.js"
|
|
31
|
+
},
|
|
29
32
|
"files": [
|
|
33
|
+
"bin",
|
|
34
|
+
"!bin/__tests__",
|
|
30
35
|
"content",
|
|
31
36
|
"!content/**/__tests__",
|
|
32
37
|
"!content/test-utils",
|
|
@@ -35,24 +40,23 @@
|
|
|
35
40
|
"schemas"
|
|
36
41
|
],
|
|
37
42
|
"devDependencies": {
|
|
38
|
-
"@hyperjump/json-schema": "1.
|
|
39
|
-
"@types/
|
|
40
|
-
"@
|
|
41
|
-
"@williamthorsen/
|
|
42
|
-
"@williamthorsen/
|
|
43
|
-
"@williamthorsen/
|
|
44
|
-
"@williamthorsen/toolbelt.
|
|
45
|
-
"@williamthorsen/toolbelt.
|
|
46
|
-
"
|
|
47
|
-
"codeassembly": "0.17.0",
|
|
43
|
+
"@hyperjump/json-schema": "1.18.0",
|
|
44
|
+
"@types/node": "24.19.2",
|
|
45
|
+
"@williamthorsen/change-grammar": "0.3.0",
|
|
46
|
+
"@williamthorsen/kb": "0.11.0",
|
|
47
|
+
"@williamthorsen/nmr": "0.53.1",
|
|
48
|
+
"@williamthorsen/toolbelt.errors": "0.9.0",
|
|
49
|
+
"@williamthorsen/toolbelt.terminal": "0.3.0",
|
|
50
|
+
"@williamthorsen/toolbelt.testing": "0.8.0",
|
|
51
|
+
"codeassembly": "0.19.0",
|
|
48
52
|
"esbuild": "0.28.2",
|
|
49
|
-
"eslint": "10.
|
|
50
|
-
"
|
|
53
|
+
"eslint": "10.13.0",
|
|
54
|
+
"happy-dom": "21.0.4",
|
|
51
55
|
"marklassian": "1.2.1",
|
|
52
56
|
"ulid": "3.0.2",
|
|
53
|
-
"vitest": "
|
|
57
|
+
"vitest": "5.0.5",
|
|
54
58
|
"yaml": "2.9.1",
|
|
55
|
-
"zod": "4.6.
|
|
59
|
+
"zod": "4.6.7"
|
|
56
60
|
},
|
|
57
61
|
"engines": {
|
|
58
62
|
"node": ">=24"
|
|
@@ -61,8 +65,8 @@
|
|
|
61
65
|
"content": "content"
|
|
62
66
|
},
|
|
63
67
|
"scripts": {
|
|
64
|
-
"build": "codeassembly bundle-helpers && node scripts/generate-work-types.ts",
|
|
65
|
-
"check:content": "codeassembly validate && codeassembly bundle-helpers --check && node scripts/generate-work-types.ts --check",
|
|
68
|
+
"build": "codeassembly bundle-helpers && node scripts/generate-work-types.ts && node scripts/generate-kb-standard-tags.ts",
|
|
69
|
+
"check:content": "codeassembly validate && codeassembly bundle-helpers --check && node scripts/generate-work-types.ts --check && node scripts/generate-kb-standard-tags.ts --check",
|
|
66
70
|
"check:post": "pnpm run check:content",
|
|
67
71
|
"check:strict:post": "pnpm run check:content",
|
|
68
72
|
"test:post": "pnpm run test:sh && pnpm run test:smoke",
|
|
@@ -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.3.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",
|
|
@@ -135,21 +135,44 @@
|
|
|
135
135
|
},
|
|
136
136
|
"pr": {
|
|
137
137
|
"type": "object",
|
|
138
|
-
"description": "Pull-request title rendering
|
|
138
|
+
"description": "Pull-request configuration: title rendering and the state at creation.",
|
|
139
139
|
"properties": {
|
|
140
|
+
"initial_state": {
|
|
141
|
+
"type": "string",
|
|
142
|
+
"enum": [
|
|
143
|
+
"draft",
|
|
144
|
+
"ready"
|
|
145
|
+
],
|
|
146
|
+
"description": "The state in which `create-pr` opens a pull request: `draft`, or `ready` for review. Defaults to `draft`."
|
|
147
|
+
},
|
|
140
148
|
"title_format": {
|
|
141
149
|
"type": "string",
|
|
142
150
|
"description": "Template string used to render pull-request titles. Supports the same token vocabulary as `commit.title_format`."
|
|
143
151
|
}
|
|
144
|
-
}
|
|
145
|
-
"required": [
|
|
146
|
-
"title_format"
|
|
147
|
-
]
|
|
152
|
+
}
|
|
148
153
|
},
|
|
149
154
|
"project": {
|
|
150
155
|
"type": "object",
|
|
151
|
-
"description": "Project identification configuration.",
|
|
156
|
+
"description": "Project identification configuration, and the project's declared stage (`maturity`, `sensitivity`, `audience`), which design guidance treats as premises.",
|
|
152
157
|
"properties": {
|
|
158
|
+
"audience": {
|
|
159
|
+
"type": "string",
|
|
160
|
+
"enum": [
|
|
161
|
+
"owner",
|
|
162
|
+
"team",
|
|
163
|
+
"public"
|
|
164
|
+
],
|
|
165
|
+
"description": "Who uses the project. `owner`: only the repo's owner. `team`: a known, bounded group. `public`: anyone who can reach it. Read from the project preferences file only."
|
|
166
|
+
},
|
|
167
|
+
"maturity": {
|
|
168
|
+
"type": "string",
|
|
169
|
+
"enum": [
|
|
170
|
+
"hobby",
|
|
171
|
+
"early",
|
|
172
|
+
"production"
|
|
173
|
+
],
|
|
174
|
+
"description": "How far the project has come. `hobby`: built for the owner's own use or learning; breakage costs only the owner's time. `early`: in use by others, but the shape is still changing; downtime is tolerated. `production`: others depend on it; downtime and data loss have real costs. Read from the project preferences file only."
|
|
175
|
+
},
|
|
153
176
|
"scopes": {
|
|
154
177
|
"type": "array",
|
|
155
178
|
"description": "Directories that own a change scope although they are not workspace packages, such as an app built by another toolchain. `describe-change resolve-scopes` resolves paths against these together with the pnpm workspace's packages, the longest containing directory winning. Read from the project preferences file only; the global file contributes no scopes. A declared directory does not become a workspace to any tool.",
|
|
@@ -173,6 +196,15 @@
|
|
|
173
196
|
"additionalProperties": false
|
|
174
197
|
}
|
|
175
198
|
},
|
|
199
|
+
"sensitivity": {
|
|
200
|
+
"type": "string",
|
|
201
|
+
"enum": [
|
|
202
|
+
"low",
|
|
203
|
+
"personal",
|
|
204
|
+
"confidential"
|
|
205
|
+
],
|
|
206
|
+
"description": "The most sensitive data that the project holds. `low`: nothing that would harm anyone if published. `personal`: personal data about the owner or identifiable individuals. `confidential`: secrets, credentials, or data that a third party is obliged to protect. Read from the project preferences file only."
|
|
207
|
+
},
|
|
176
208
|
"slug": {
|
|
177
209
|
"type": "string",
|
|
178
210
|
"description": "Project identifier used for namespacing artifacts under `{base_dir}/projects/{slug}/`."
|
|
@@ -288,6 +320,17 @@
|
|
|
288
320
|
"required": [
|
|
289
321
|
"title_format"
|
|
290
322
|
]
|
|
323
|
+
},
|
|
324
|
+
"triage_feedback": {
|
|
325
|
+
"type": "object",
|
|
326
|
+
"description": "Settings of the `triage-feedback` skill.",
|
|
327
|
+
"properties": {
|
|
328
|
+
"defer_days": {
|
|
329
|
+
"type": "integer",
|
|
330
|
+
"minimum": 1,
|
|
331
|
+
"description": "The days for which a deferred feedback cluster stays out of a triage, unless it gains an undeferred event. Defaults to 30."
|
|
332
|
+
}
|
|
333
|
+
}
|
|
291
334
|
}
|
|
292
335
|
},
|
|
293
336
|
"additionalProperties": false
|
|
@@ -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.3.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": {
|
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
## Code descriptions
|
|
2
|
-
|
|
3
|
-
- Every function, method, class, and component gets a brief description. One line is usually enough.
|
|
4
|
-
- 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.
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
## Style
|
|
2
|
-
|
|
3
|
-
- Code style should adhere to `.editorconfig`, if there is one.
|
|
4
|
-
- Order lists and collections logically (alphabetically unless there is a good reason to sort or group differently).
|
|
5
|
-
- Use long-form CLI options (`--force`, not `-f`) in generated commands and scripts.
|
|
6
|
-
- Structure code so that the primary logic comes first; place helper functions at the end.
|
|
7
|
-
- Name functions with a leading verb (`show_usage`, not `usage`; `build_payload`, not `payload`).
|