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

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:
2026-06-13 16:30:02 +02:00
parent 268ee705f4
commit 26e9630496
40 changed files with 752 additions and 894 deletions
+20 -18
View File
@@ -1,6 +1,6 @@
---
name: planner
description: Use when a cycle spec exists under paths.spec_dir and a new iteration is starting. Produces a placeholder-free, bite-sized implementation plan under paths.plan_dir that the implement skill can execute task-by-task. Hard-gate before any implementation work.
description: Use when a cycle spec exists under docs/specs and a new iteration is starting. Produces a placeholder-free, bite-sized implementation plan under docs/plans that the implement skill can execute task-by-task. Hard-gate before any implementation work.
---
# planner — spec → executable plan
@@ -15,9 +15,9 @@ file that will be created or modified, and decomposes work
into bites small enough that a subagent can execute one in
2-5 minutes without making judgement calls outside its remit.
Plans live under the project's `paths.plan_dir` with a name
shape governed by the project's `naming.policy` (see profile
schema). The header references the parent spec. The plan
Plans live under `docs/plans` with the fixed name shape
`NNNN-slug.md` — a 4-digit counter per directory (see
`docs/conventions.md`). The header references the parent spec. The plan
decomposes work into tasks; each task is the unit of review
(spec-compliance and quality gates inside `implement`), not
the unit of commit. Commits are an orchestrator-only decision
@@ -28,7 +28,7 @@ diff.
Triggers:
- A spec under `paths.spec_dir` for the active cycle is
- A spec under `docs/specs` for the active cycle is
approved.
- A new iteration within an active cycle is starting.
@@ -62,7 +62,7 @@ Non-negotiable.
### Step 1 — Read the parent spec
Read the spec under `paths.spec_dir` in full. NOT from memory.
Read the spec under `docs/specs` in full. NOT from memory.
Even if the spec is recent and you wrote it yourself, re-read
it before planning.
@@ -120,7 +120,7 @@ action that takes 2-5 minutes:
- [ ] **Step 2: Run test to verify it fails**
Run: `<the project's test command from commands.test, scoped to this test>`
Run: `<the project's test command (its CLAUDE.md project facts), scoped to this test>`
Expected: FAIL with "<exact expected message>"
- [ ] **Step 3: Write minimal implementation**
@@ -144,7 +144,7 @@ Every plan starts with this header:
```markdown
# <Iteration Title> — Implementation Plan
> **Parent spec:** `<path under paths.spec_dir>`
> **Parent spec:** `<path under docs/specs>`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use the
> `implement` skill to run this plan. Steps use `- [ ]`
@@ -223,10 +223,11 @@ Before handing the plan off, run this checklist inline:
every Run step whose assertion lives in a filter string.
9. **Parse-the-bytes-you-inline gate.** Every verbatim code body
the plan inlines into a task step must be run through the
`spec_validation` gate defined in `docs/profile-schema.md`
(which owns the parser-invocation protocol, the noted
no-parser skip, the malformed-entry failure, and the no-op
when the profile declares no `spec_validation`) before
spec-validation parsers the project declares in its CLAUDE.md
project facts, following the parser-invocation protocol in
`docs/conventions.md` (which owns the no-parser skip, the
malformed-entry failure, and the no-op when the project
declares no spec-validation parsers) before
hand-off. The target is the surface-language snippets the plan
lifts verbatim (example programs, fixtures); the project's
source-language test / implementation bodies are NOT the
@@ -242,7 +243,7 @@ Fix issues inline.
### Step 6 — Hand off
The plan sits in the working tree as an unstaged file under
`paths.plan_dir`. Hand off to `implement` with: path to the
`docs/plans`. Hand off to `implement` with: path to the
plan file + optional task focus ("only Tasks 1-3 this run").
The orchestrator commits the plan when handing it forward
@@ -253,8 +254,8 @@ The planner skill does not perform the commit itself.
| Direction | Carrier |
|-----------|---------|
| `specify``planner` | path to the spec under `paths.spec_dir` + iteration scope ("this iteration covers spec section X+Y") |
| `planner``implement` | path to the plan under `paths.plan_dir` + optional task-range focus |
| `specify``planner` | path to the spec under `docs/specs` + iteration scope ("this iteration covers spec section X+Y") |
| `planner``implement` | path to the plan under `docs/plans` + optional task-range focus |
| `planner``specify` (bounce) | spec contains placeholders or contradictions: name the offending section, request revision |
## Common Rationalisations
@@ -267,7 +268,7 @@ The planner skill does not perform the commit itself.
| "Step 5 'implement the parser' is fine, I'll detail it at execution time" | Then it's not a step, it's a wish. Steps are bite-sized OR the plan isn't done. |
| "Task 7 is similar to Task 4, just say so" | The executor may read tasks out of order. Repeat the code. |
| "The spec has a TBD too, I can pass it through" | Bounce back to `specify`. Plans inherit spec gaps; spec gaps are not plan placeholders. |
| "The example program came straight from the spec, it must be valid" | The spec's code blocks are hypotheses, not verified bytes — specify's parse gate can be skipped and a post-spec edit can break them. Re-parse every surface-language body you inline; this is the last line before the implementer hits it (issue #1 Fix 4). |
| "The example program came straight from the spec, it must be valid" | The spec's code blocks are hypotheses, not verified bytes — specify's parse gate can be skipped and a post-spec edit can break them. Re-parse every surface-language body you inline against the spec-validation parsers the project declares in its CLAUDE.md project facts; this is the last line before the implementer hits it (issue #1 Fix 4). |
## Red Flags — STOP
@@ -279,8 +280,9 @@ The planner skill does not perform the commit itself.
- Header missing parent spec reference
- Self-review skipped because "the plan looks fine"
- A task step inlining a surface-language code body whose fence
label has a configured `spec_validation` parser, handed off
without a parse-trace in the planner session
label has a project-declared spec-validation parser (its
CLAUDE.md project facts), handed off without a parse-trace in
the planner session
## Cross-references
+8 -8
View File
@@ -32,21 +32,21 @@ naming where work lands.
## Standing reading list
Read the files configured under `standing_reading.always`
plus `standing_reading.by_role.plan-recon` in the project
profile.
The standing reading is `CLAUDE.md` plus
`git log -10 --format=full`, then the per-role standing
reading the project lists in its CLAUDE.md project facts.
In addition:
- If the project has a design ledger configured under
`paths.design_ledger`, walk it to the contracts the carrier
- If the project has a design ledger (its CLAUDE.md project
facts), walk it to the contracts the carrier
flags or that the spec touches; do not skim sections the
spec does not touch.
- `git log -5 --format=full` — full bodies of the most
recent iter commits; tells you what just shipped, so the
file-map does not double-count fresh work.
- `../SKILL.md` (the planner SKILL) — the role the recon
serves. Do NOT open files under `paths.plan_dir`; plan
serves. Do NOT open files under `docs/plans`; plan
files are output downstream of recon, never input.
## Carrier contract — what the controller hands you
@@ -58,7 +58,7 @@ it.
| Field | Content |
|-------|---------|
| `spec_path` | Path to the spec under `paths.spec_dir` (mandatory) |
| `spec_path` | Path to the spec under `docs/specs` (mandatory) |
| `iteration_scope` | Which sections of the spec this dispatch covers (mandatory) |
| `focus_hint` | Optional: orchestrator may flag a specific subsystem or symbol to prioritise |
@@ -85,7 +85,7 @@ never to fix or write.
2. Read the spec in full. Note every reference to a path,
type, function, or invariant.
3. Read the standing list in order, plus the design ledger's
relevant contracts (if configured).
relevant contracts (if the project has one).
4. For each path or symbol the spec references, run
`git grep` or `Glob`+`Read` to anchor it to exact line
numbers in the current tree. Record: