codeassembly-guidance 0.4.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 +329 -280
- package/CHANGELOG.md +16 -0
- package/README.md +7 -22
- package/content/_partials/guidance-change-since-capture.md +1 -1
- 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/skills/_data/artifact-conventions.md +2 -421
- package/content/skills/_partials/plan-template.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +1 -1
- package/content/skills/refine-guidance/SKILL.md +1 -1
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/triage-feedback/SKILL.md +1 -1
- package/content/subagents/feedback-triage-challenger.md +1 -1
- package/content/subagents/plan-reviewer.md +8 -7
- package/package.json +4 -4
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.5.0 â 2026-11-02
|
|
6
|
+
|
|
7
|
+
### ð Features
|
|
8
|
+
|
|
9
|
+
- Adds rules to the `shared-data-conventions` rulebook stating that an agent's verdict that decides a write to shared state includes evidence that a script checks before the write, and that a skill writing to shared state runs against the real data before merge, stopping at its approval checkpoint or in a dry run. (#2245)
|
|
10
|
+
- Extends the data-change guidance in `create-ticket`, `design-and-plan`, `plan`, and `align-ticket-with-implementation` to require an acceptance criterion for the evidence check and a `## Verification` step that runs the skill against the real data without writing. (#2245)
|
|
11
|
+
- Adds a "Judged writes" check to `plan-reviewer`, which reports a plan for a skill that writes to shared state when the plan does not run the skill against the real data before merge or does not name the script that checks a verdict's evidence. (#2245)
|
|
12
|
+
|
|
13
|
+
### ðĶ Dependencies
|
|
14
|
+
|
|
15
|
+
- Pins `codeassembly` and `@williamthorsen/kb` in guidance to their published releases `0.20.0` and `0.11.1` in place of `workspace:*`, and exempts both from the 24-hour `minimumReleaseAge` in `pnpm-workspace.yaml` so that guidance can install a release as soon as this repository's CI publishes it. (#2246)
|
|
16
|
+
|
|
17
|
+
### ð Documentation
|
|
18
|
+
|
|
19
|
+
- Moves the `run-index.json`, `run-log.jsonl`, and `status.json` specification from guidance's `artifact-conventions.md` to `packages/run-core/docs/run-data-format.md`, beside the Zod schemas that implement it. (#2246)
|
|
20
|
+
|
|
5
21
|
## 0.4.0 â 2026-11-02
|
|
6
22
|
|
|
7
23
|
### ð Features
|
package/README.md
CHANGED
|
@@ -2,31 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
# codeassembly-guidance
|
|
4
4
|
|
|
5
|
-
The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](
|
|
5
|
+
The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](https://github.com/williamthorsen/codeassembly/blob/main/packages/agents/README.md) CLI deploys into Claude Code and Rovo Dev.
|
|
6
6
|
|
|
7
7
|
<!-- section:release-notes -->
|
|
8
|
-
## Release notes â v0.
|
|
8
|
+
## Release notes â v0.5.0 (2026-11-02)
|
|
9
9
|
|
|
10
10
|
### ð Features
|
|
11
11
|
|
|
12
|
-
- Adds the `
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
### ðŠĶ Removed
|
|
16
|
-
|
|
17
|
-
- Remove the factory and the demos (#2234)
|
|
18
|
-
|
|
19
|
-
Removes the dormant factory visualization package and the catwalk demos, together with the docs, repo-local skills, dependencies, and configuration that only they used. Adds to `docs/repository-split.md` the command that finds the last commit containing the factory, which is the commit from which a revival restores it.
|
|
20
|
-
|
|
21
|
-
### ð Bug fixes
|
|
22
|
-
|
|
23
|
-
- Fixes the issue that the `feedback-coverage-judge` subagent of `curate-feedback` marked a feedback event `obsolete` when the change that removed the event's target had renamed or moved it, or had named a replacement for it. (#2233)
|
|
24
|
-
- Fixes the issue that `curate-feedback validate` accepted a `covered` entry after checking only that the cited guidance file existed, by requiring a verbatim `quote` of the stating sentence and rejecting the entry when the file at the pin does not contain it, ignoring differences in whitespace and in `*`, `_`, and backtick markers. (#2236)
|
|
25
|
-
- Fixes the issue that `triage-feedback` ranked a feedback cluster by its events even when all of them predated a change to the guidance that governs its lesson, and directs the skill and its `feedback-triage-challenger` subagent to check that guidance's commit history and set such a cluster to `low` unless evidence shows the failure recurring under the changed guidance. (#2243)
|
|
26
|
-
- Fixes the issue that `triage-feedback` and `triage-spike-findings` accepted a defense against the challenger that rested on grounds other than the evidence named by the challenger's argument. (#2243)
|
|
27
|
-
- Remove the unshipped `source` export condition from the published packages (#2244)
|
|
28
|
-
|
|
29
|
-
Removes the `source` export condition from `codeassembly`, `@williamthorsen/kb`, and `codeassembly-run-core`, because it pointed at TypeScript files that their tarballs don't contain, so that a consumer that enables the condition resolves the shipped `dist/` output instead of failing.
|
|
12
|
+
- Adds rules to the `shared-data-conventions` rulebook stating that an agent's verdict that decides a write to shared state includes evidence that a script checks before the write, and that a skill writing to shared state runs against the real data before merge, stopping at its approval checkpoint or in a dry run. (#2245)
|
|
13
|
+
- Extends the data-change guidance in `create-ticket`, `design-and-plan`, `plan`, and `align-ticket-with-implementation` to require an acceptance criterion for the evidence check and a `## Verification` step that runs the skill against the real data without writing. (#2245)
|
|
14
|
+
- Adds a "Judged writes" check to `plan-reviewer`, which reports a plan for a skill that writes to shared state when the plan does not run the skill against the real data before merge or does not name the script that checks a verdict's evidence. (#2245)
|
|
30
15
|
<!-- /section:release-notes -->
|
|
31
16
|
|
|
32
17
|
## Using the library
|
|
@@ -36,13 +21,13 @@ A declaration names the library as a source and selects artifacts from it, usual
|
|
|
36
21
|
```yaml
|
|
37
22
|
sources:
|
|
38
23
|
- name: codeassembly-guidance
|
|
39
|
-
path: ~/repos/codeassembly/packages/guidance/content
|
|
24
|
+
path: ~/repos/codeassembly-guidance/packages/guidance/content
|
|
40
25
|
collections:
|
|
41
26
|
use:
|
|
42
27
|
- recommended
|
|
43
28
|
```
|
|
44
29
|
|
|
45
|
-
Then run `codeassembly install` and `codeassembly sync --global`. A project declares the same in its own `.agents/codeassembly.yaml` and runs `codeassembly sync`. [Project declaration](
|
|
30
|
+
Then run `codeassembly install` and `codeassembly sync --global`. A project declares the same in its own `.agents/codeassembly.yaml` and runs `codeassembly sync`. [Project declaration](https://github.com/williamthorsen/codeassembly/blob/main/packages/agents/docs/project-declaration.md) documents the declaration format.
|
|
46
31
|
|
|
47
32
|
## What the content contains
|
|
48
33
|
|
|
@@ -2,7 +2,7 @@ A cluster whose events all predate a change to the guidance that governs its les
|
|
|
2
2
|
|
|
3
3
|
Check each artifact that states or should state the lesson: the target, every artifact that your search found stating the lesson, and every partial that one of them includes.
|
|
4
4
|
|
|
5
|
-
1. Find the artifact's source file in the repository that owns it. A guidance-library artifact's source is under `packages/guidance/content/` in the CodeAssembly repository, at its path relative to the content root, such as `subagents/entry-drafter.md`.
|
|
5
|
+
1. Find the artifact's source file in the repository that owns it. A guidance-library artifact's source is under `packages/guidance/content/` in the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`), at its path relative to the content root, such as `subagents/entry-drafter.md`.
|
|
6
6
|
2. List the commits on the owning repository's default branch that touched the source file after the latest capture: `gh api 'repos/{owner}/{repo}/commits?path={path}&since={latestCapturedAt}' --jq '.[] | [.sha[0:8], .commit.committer.date, (.commit.message | split("\n")[0])] | @tsv'`. Only when `gh` cannot reach the repository, read a local clone of it at its remote's default branch, never at the checked-out branch, which may predate the change: `git -C {clone} log --first-parent --since={latestCapturedAt} --format='%h %cs %s' origin/HEAD -- {path}`. The clone shows history only up to its last fetch.
|
|
7
7
|
3. Read the message of each listed commit, with `gh api repos/{owner}/{repo}/commits/{sha} --jq .commit.message`, or with `git -C {clone} show --no-patch --format=%B {sha}` on the fallback route. A commit changed the guidance when it changed what the artifact tells the agent to do about the lesson. A commit that only repairs prose, reformats, or renames does not.
|
|
8
8
|
|
|
@@ -36,6 +36,6 @@ The skills belong here on different grounds. A rulebook of the personal collecti
|
|
|
36
36
|
|
|
37
37
|
Adding a skill that declares a guidance hook has a drawback that the current members do not have. A project declaring this collection deploys its own copy of that skill, and that copy shadows the user's home-bound one. Because guidance-hook bindings do not cross the boundary between the user-global and project domains, guidance bound globally by the developer goes missing in that repository until the project binds it too. Weigh that against the general applicability claimed by membership before admitting such a skill.
|
|
38
38
|
|
|
39
|
-
`shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract,
|
|
39
|
+
`shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract, the rule that unmerged code does not write to shared state, and the checks that a skill writing to shared state needs before merge, and it does not name any author, platform, or store: Each repository's `AGENTS.md` names its own. Its body does not contain any invocation token, so its closure is empty.
|
|
40
40
|
|
|
41
41
|
`ui-copy-conventions` qualifies on its own terms as well. What it asks of the text on a page follows from who reads that text, the person who returns to the page every week, rather than from a preference, and it does not name any author, repository, product, or tool. A project that has content guidelines of its own names them, and they take precedence. Its body does not contain any invocation token, so its closure is empty.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
slug: shared-data-conventions
|
|
3
|
-
description: 'Changes to shared data: unmerged code never writes to a shared store, and a change to the shape of persisted data proceeds as expand, migrate, contract. Consult before planning, implementing, or reviewing a change that alters the shape of persisted data or writes to a shared store.'
|
|
3
|
+
description: 'Changes to shared data: unmerged code never writes to a shared store, a verdict that decides such a write includes evidence that a script checks, a skill that makes such writes runs read-only against the real data before merge, and a change to the shape of persisted data proceeds as expand, migrate, contract. Consult before planning, implementing, or reviewing a change that alters the shape of persisted data or writes to a shared store.'
|
|
4
4
|
delivery: [skill]
|
|
5
|
-
version: '
|
|
5
|
+
version: '2'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Shared data conventions
|
|
@@ -10,5 +10,7 @@ version: '1'
|
|
|
10
10
|
Shared state is any store that a deployed product or another person reads, such as a production database or a content dataset. A local or disposable copy is not shared. The repository's `AGENTS.md` names which stores are shared and how their migrations run.
|
|
11
11
|
|
|
12
12
|
- **Writes.** Unmerged code never writes to shared state, even when a plan or a ticket directs it. Asked to run a migration or another write against shared state from a branch, decline and name the route: Merge, then run it from merged code.
|
|
13
|
+
- **Judged writes.** When the verdict of an agent or a subagent decides a write to shared state, the verdict includes evidence that a script checks before the write, such as a quote that the script finds in the cited file, a commit that exists, or a date that it compares with history. The script refuses a verdict whose evidence fails the check. A prose instruction to the judge does not replace the check: Fixtures exercise the mechanics around a verdict, not the judgment on real data.
|
|
14
|
+
- **Real-data run.** Before merge, a skill that writes to shared state runs against the real data in a mode that stops before the write: its approval checkpoint, or a dry run. The agent reviews each verdict that the run would act on, and a wrong verdict is fixed on the branch. The run only reads, so **Writes.** still holds.
|
|
13
15
|
- **Sequence.** A change to the shape of data proceeds as expand, migrate, contract. Expand adds the new shape alongside the old one, migrate moves the data, and contract removes the old shape once the deployed code no longer reads it. Each step is its own change, merged and deployed before the next begins, so that every order of deploy and migration leaves the product working.
|
|
14
16
|
- **Migrations.** A migration runs from merged code, by automation or by the developer, and by an agent only when the developer directs that run. It defaults to a dry run and is idempotent.
|