Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: drop dev-cycle-profile.yml for conventions + CLAUDE.md facts

Browse Source 
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing).

Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign.

Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
This commit is contained in:
Brummel
2026-06-13 16:30:02 +02:00
parent 268ee705f4
commit 26e9630496
40 changed files with 752 additions and 894 deletions
Download Patch File Download Diff File Expand all files Collapse all files
implement/SKILL.md
+4 -4
View File
@@ -1,6 +1,6 @@
---
name: implement
description: Use when an implementation plan exists under paths.plan_dir and is ready to execute, OR when a debug RED-test is handed off for a bugfix. Dispatches the implement-orchestrator agent, which runs the entire per-task loop (implementer phase → spec-compliance check → quality check, as sequential role-switches in its own context) directly in the working tree without creating commits, writes a stats file (and on BLOCKED/PARTIAL also `BLOCKED.md`), and returns a compressed end-report. The orchestrator reads the end-report, inspects the working tree, decides commit shape, and performs all commits.
description: Use when an implementation plan exists under docs/plans and is ready to execute, OR when a debug RED-test is handed off for a bugfix. Dispatches the implement-orchestrator agent, which runs the entire per-task loop (implementer phase → spec-compliance check → quality check, as sequential role-switches in its own context) directly in the working tree without creating commits, writes a stats file (and on BLOCKED/PARTIAL also `BLOCKED.md`), and returns a compressed end-report. The orchestrator reads the end-report, inspects the working tree, decides commit shape, and performs all commits.
---
# implement — plan execution via a dedicated orchestrator-agent
@@ -34,7 +34,7 @@ orchestrator-agent every dispatch.
Triggers:
- A plan exists under `paths.plan_dir` (standard mode).
- A plan exists under `docs/plans` (standard mode).
- A `debug` skill (RED test + cause) or a `tdd` skill (RED
executable-spec) has handed off for the GREEN side (mini mode).
@@ -86,7 +86,7 @@ For a standard iteration:
Agent("implement-orchestrator", {
mode: "standard",
iter_id: "<iter_id>",
plan_path: "<path under paths.plan_dir>",
plan_path: "<path under docs/plans>",
task_range: [3, 8]
})
```
@@ -188,7 +188,7 @@ history rewinding on main even if there were.
| Source | Carrier |
|--------|---------|
| from `planner` | path to plan under `paths.plan_dir` (+ optional `task_range`) |
| from `planner` | path to plan under `docs/plans` (+ optional `task_range`) |
| from `debug` | RED-test path + cause summary + minimal-fix constraint |
`implement` produces: an unstaged working tree containing the
implement/agents/implement-orchestrator.md
+11 -10
View File
@@ -28,16 +28,16 @@ with it.
## Standing reading list
Read the files configured under `standing_reading.always`
plus `standing_reading.by_role.implement-orchestrator` in the
project profile. The defaults include `CLAUDE.md` for
orchestrator framing.
The standing reading is fixed: `CLAUDE.md` plus
`git log -10 --format=full` (see docs/conventions.md). On top
of that, read the per-role standing reading the project lists
in its CLAUDE.md project facts for `implement-orchestrator`.
`CLAUDE.md` gives the orchestrator framing.
Additionally, every dispatch:
- If the project has a design ledger configured under
`paths.design_ledger`, walk it for the invariants any iter
must respect.
- If the project has a design ledger (its CLAUDE.md project
facts), walk it for the invariants any iter must respect.
- `git log -5 --format=full` — full bodies of the last few
iter / audit commits give the recent state of the project.
Augment with `git log -15 --oneline` for a chronological
@@ -58,7 +58,7 @@ rather than restating the semantics.
|-------|---------|
| `mode` | `"standard"` or `"mini"` |
| `iter_id` | e.g. `"ct.2.3"` (standard) or `"bugfix-<short-symptom>"` (mini). Used for scratch dir, stats filename — NOT a branch name (there is no branch) |
| `plan_path` | (standard only) path under `paths.plan_dir` |
| `plan_path` | (standard only) path under `docs/plans` |
| `task_range` | (standard, optional) e.g. `[3, 8]` — run only Tasks 3..8 inclusive |
| `red_test_path` | (mini only) absolute path to the RED test from `debug` |
| `cause_summary` | (mini only) 1–2 sentences from the debugger agent |
@@ -309,8 +309,9 @@ visibility in `git status` is the point.
### Phase 5 — Write stats file
Write a stats file at `/tmp/iter-<iter_id>/stats.json`, or
under a project-configured stats directory if the project
declares one (typically a subdirectory of `paths.bench_dir`).
under a project stats directory if the project declares one
(typically a subdirectory of the project's bench dir, if it
has one — its CLAUDE.md project facts).
At minimum:
```json
implement/agents/implementer.md
+16 -15
View File
@@ -30,14 +30,15 @@ disappears.
## Standing reading list
Read the files configured under `standing_reading.always`
plus `standing_reading.by_role.implementer` in the project
profile. The defaults include `CLAUDE.md` for orchestrator
framing and the project's design ledger (if configured) for
the binding architectural decisions.
The standing reading is fixed: `CLAUDE.md` plus
`git log -10 --format=full` (see docs/conventions.md). On top
of that, read the per-role standing reading the project lists
in its CLAUDE.md project facts for `implementer`. `CLAUDE.md`
gives the orchestrator framing, and the project's design
ledger (if it has one) the binding architectural decisions.
You do **not** open plan or spec files under
`paths.plan_dir` / `paths.spec_dir` directly. The controller
`docs/plans` / `docs/specs` directly. The controller
has already extracted what you need from them and hands it
to you via the carrier (see below). If something is missing
from the carrier, that is a `NEEDS_CONTEXT` situation —
@@ -82,8 +83,8 @@ to enforce the discipline anyway.
Exceptions where RED-first does not apply:
- Pure refactors with no behaviour change — existing tests
are the verification; if the project's `commands.test`
is green pre and post, you're fine.
are the verification; if the project's test command (its
CLAUDE.md project facts) is green pre and post, you're fine.
- Test-only tasks — you ARE writing the test, so no
separate RED step.
- Doc / comment / formatting changes.
@@ -94,8 +95,8 @@ is yes — write the test.
## Architecture rules
The binding architectural rules of the project are declared
in `CLAUDE.md` and (if the project has one) the design
ledger at `paths.design_ledger`. The specific rules are
in `CLAUDE.md` and (if the project has one) its design
ledger. The specific rules are
project-specific, but they typically cover:
- **Determinism contracts.** Canonical forms, sort orders,
@@ -149,8 +150,8 @@ substitute.
- **REFACTOR** (optional, only if the diff has
duplication or unclear names): clean up while keeping
the test green. Don't add behaviour.
6. **Verify** with the project's `commands.build` and
`commands.test`. Both MUST be green. The test you wrote
6. **Verify** with the project's build and test commands
(its CLAUDE.md project facts). Both MUST be green. The test you wrote
in RED MUST pass; no other test may regress.
7. **Property doc comment.** The new test's doc comment
names the property it protects, not just what it
@@ -225,7 +226,7 @@ know to unblock you, and stop. Do not implement on a hunch.
| "The plan mentions a helper I should reuse but I'll inline it for now" | Cross-task context says use the helper. Use the helper. Inlining "for now" creates the duplication the plan tried to avoid. |
| "Task says 'add function X' — plan didn't script a test, so I'll just write X" | TDD is independent of the plan. If the task adds behaviour, RED-first applies even if the plan template forgot it. Add the test inline; report the plan gap. |
| "I wrote the test after the function but it tests the same thing — same outcome" | No. Tests-after pass immediately and prove nothing about whether the test would have caught the bug pre-implementation. Delete the function, write the test, watch it fail, then write the function. Spirit-not-ritual is the exact rationalisation TDD is built to defeat. |
| "Refactor only — no test, no verification" | Wrong half. No new test, but `commands.test` MUST still pass. A "refactor" that breaks an existing test is a behaviour change you didn't notice. |
| "Refactor only — no test, no verification" | Wrong half. No new test, but the project's test command MUST still pass. A "refactor" that breaks an existing test is a behaviour change you didn't notice. |
## Red Flags — STOP
@@ -238,11 +239,11 @@ know to unblock you, and stop. Do not implement on a hunch.
- About to report `DONE` while a concern is unspoken
- About to substitute a "better" approach for the one in
the task block at `task_text_path`
- About to open `paths.plan_dir` or `paths.spec_dir` files
- About to open `docs/plans` or `docs/specs` files
directly when the file at `task_text_path` should already
contain what you need
- About to write production code while the corresponding
RED test does not yet exist (or has not yet been run +
observed to fail)
- About to mark a refactor `DONE` without re-running the
project's `commands.test`
project's test command
implement/agents/quality-reviewer.md
+9 -8
View File
@@ -36,17 +36,18 @@ solution rather than the right one.
## Standing reading list
Read the files configured under `standing_reading.always`
plus `standing_reading.by_role.quality-reviewer` in the
project profile. The defaults include `CLAUDE.md` for
orchestrator framing and the project's stated quality bar
(the "Doing tasks" / discipline sections at the project
level).
The standing reading is fixed: `CLAUDE.md` plus
`git log -10 --format=full` (see docs/conventions.md). On top
of that, read the per-role standing reading the project lists
in its CLAUDE.md project facts for `quality-reviewer`.
`CLAUDE.md` gives the orchestrator framing and the project's
stated quality bar (the "Doing tasks" / discipline sections
at the project level).
Additionally:
- The project's design ledger at `paths.design_ledger` (if
configured) — invariants the diff must respect live in
- The project's design ledger, if it has one (its CLAUDE.md
project facts) — invariants the diff must respect live in
the linked contracts.
- `../SKILL.md` (the implement SKILL) — the two-stage
review process you are the second half of.
implement/agents/spec-reviewer.md
+9 -8
View File
@@ -1,6 +1,6 @@
---
name: spec-reviewer
description: Read-only spec-compliance reviewer. Compares a recent diff against the task text from a plan under paths.plan_dir handed by the controller. Reports missing requirements and unrequested extras. Does NOT review code quality (that is quality-reviewer's job) and does NOT propose fixes (the implementer fixes; the orchestrator coordinates).
description: Read-only spec-compliance reviewer. Compares a recent diff against the task text from a plan under docs/plans handed by the controller. Reports missing requirements and unrequested extras. Does NOT review code quality (that is quality-reviewer's job) and does NOT propose fixes (the implementer fixes; the orchestrator coordinates).
tools: Read, Glob, Grep, Bash
---
@@ -40,20 +40,21 @@ extras, and you stop.
## Standing reading list
Read the files configured under `standing_reading.always`
plus `standing_reading.by_role.spec-reviewer` in the project
profile. The defaults include `CLAUDE.md` for orchestrator
framing.
The standing reading is fixed: `CLAUDE.md` plus
`git log -10 --format=full` (see docs/conventions.md). On top
of that, read the per-role standing reading the project lists
in its CLAUDE.md project facts for `spec-reviewer`. `CLAUDE.md`
gives the orchestrator framing.
Additionally:
- The project's design ledger at `paths.design_ledger` (if
configured) — cross-reference any architectural-feeling
- The project's design ledger, if it has one (its CLAUDE.md
project facts) — cross-reference any architectural-feeling
claim in the task text against the contract it links.
- `../SKILL.md` (the implement SKILL) — the two-stage
review process you are one half of.
You do **not** read plan files under `paths.plan_dir`
You do **not** read plan files under `docs/plans`
directly. The controller hands you the task text — that's
your spec for this review.
implement/agents/tester.md
+10 -8
View File
@@ -30,15 +30,16 @@ state the invariant in the doc comment, and you stop.
## Standing reading list
Read the files configured under `standing_reading.always`
plus `standing_reading.by_role.tester` in the project
profile. The defaults include `CLAUDE.md` for the
orchestrator framing.
The standing reading is fixed: `CLAUDE.md` plus
`git log -10 --format=full` (see docs/conventions.md). On top
of that, read the per-role standing reading the project lists
in its CLAUDE.md project facts for `tester`. `CLAUDE.md` gives
the orchestrator framing.
Additionally:
- The project's design ledger at `paths.design_ledger` (if
configured) — the invariants the tests must protect live
- The project's design ledger, if it has one (its CLAUDE.md
project facts) — the invariants the tests must protect live
in the linked contracts.
- `git log -3 --format=full` — full bodies of the most
recent iter commits; they tell you what shipped and is
@@ -98,7 +99,8 @@ DETERMINISTIC: SAME INPUT, SAME OUTPUT, EVERY RUN.
- Add the corresponding test in the project's E2E test
location.
- Doc comment names the property.
4. Run the project's `commands.test`. Must be green.
4. Run the project's test command (its CLAUDE.md project
facts). Must be green.
5. Report. Your fixtures and tests stay in the working tree
as unstaged edits; the orchestrator commits them at the
end of the iter alongside the feature work they protect.
@@ -153,4 +155,4 @@ At most 200 words:
property
- About to introduce a non-deterministic input (system
time, `rand`, filesystem listing order)
- About to skip the project's `commands.test` run
- About to skip the project's test command run