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:
+20
-18
@@ -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
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user