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:
+32
-35
@@ -72,10 +72,10 @@ skill does not restate them.
|
||||
### Step 1 — Read the queue
|
||||
|
||||
The project's issue tracker is the forward queue. Read open
|
||||
issues via the command configured under
|
||||
`git.issue_tracker.list_cmd` in the project profile. If that
|
||||
slot is empty, the project does not have an autonomously
|
||||
addressable queue — bounce back to the user with that diagnosis.
|
||||
issues via the list command in the project's CLAUDE.md project
|
||||
facts. If the project names no issue tracker there, it does not
|
||||
have an autonomously addressable queue — bounce back to the user
|
||||
with that diagnosis.
|
||||
|
||||
If the entire open backlog is empty: skip to Step 5
|
||||
(done-state). Do not invent work; an empty queue is a real
|
||||
@@ -98,7 +98,7 @@ brainstorm → specify → planner → implement → audit → fieldtest
|
||||
+
|
||||
debug (bug-triggered)
|
||||
+
|
||||
tdd → implement (mini) (test-specifiable feature, if profile enables it)
|
||||
tdd → implement (mini) (test-specifiable feature)
|
||||
+
|
||||
docwriter (post-stability)
|
||||
```
|
||||
@@ -110,9 +110,9 @@ new feature work with no spec or plan yet, run the **Entry-path
|
||||
reflection** below before dispatching anything. Read each skill's
|
||||
`SKILL.md` trigger section if unsure.
|
||||
|
||||
**Entry-path reflection (feature work).** When the profile enables the
|
||||
`tdd` phase, there are **three** entry paths for new feature work, and
|
||||
the choice is made by reflection every time, not by habit. Before
|
||||
**Entry-path reflection (feature work).** There are **three** entry
|
||||
paths for new feature work, and the choice is made by reflection every
|
||||
time, not by habit. Before
|
||||
dispatching, decide which fits the item in hand and record the one-line
|
||||
verdict ("test-specifiable → `tdd`" / "design settled → `specify`" /
|
||||
"design fork → `brainstorm`") in the loop. The discriminator is the
|
||||
@@ -126,9 +126,9 @@ verdict ("test-specifiable → `tdd`" / "design settled → `specify`" /
|
||||
exhaustive issue body, a long in-context discussion — then the design
|
||||
is **settled** and `specify` owns it. Dispatch `specify`
|
||||
autonomously: it is bounded (no interview), produces the spec through
|
||||
all the gates, and — unless the profile enables auto-sign (see below)
|
||||
— pauses at its own user-review gate (a problem-state notify, not a
|
||||
pre-dispatch checkpoint).
|
||||
all the gates, and — unless the project enables spec auto-sign (see
|
||||
below) — pauses at its own user-review gate (a problem-state notify,
|
||||
not a pre-dispatch checkpoint).
|
||||
- Writing the spec would force a choice between two or three plausible
|
||||
designs with real trade-offs — a genuine design fork — then discovery
|
||||
must resolve it first, and `brainstorm` owns it. Starting a fresh
|
||||
@@ -143,13 +143,13 @@ both bounded (no open Q&A), whereas a fresh `brainstorm` is high-context
|
||||
discovery the orchestrator cannot compact on its own (see trigger 4).
|
||||
`specify` dispatched in `/boss` pauses at its own Step-6 user-review
|
||||
gate to take sign-off — that is a final-sign-off notify, not a
|
||||
pre-dispatch checkpoint. The one exception is the opt-in auto-sign
|
||||
slot (`pipeline.boss.spec_auto_sign`): when a project enables it, a
|
||||
pre-dispatch checkpoint. The one exception is spec auto-sign: when a
|
||||
project enables it in its CLAUDE.md project facts, a
|
||||
spec that clears all objective gates AND a unanimous adversarial
|
||||
`spec-skeptic` panel is signed by the orchestrator without pausing,
|
||||
and the run continues to `planner` — see §"Spec auto-sign" below. The
|
||||
gate is built so that the orchestrator's own confidence is never what
|
||||
signs; absent the slot, the human signature stays mandatory. Do not
|
||||
signs; absent that, the human signature stays mandatory. Do not
|
||||
let the asymmetry harden into a reflex
|
||||
of routing borderline items to `brainstorm` "to be safe" — that is the
|
||||
exact bias this reflection exists to break; apply the design-line test
|
||||
@@ -163,11 +163,10 @@ design was not settled / not test-specifiable after all, that escalation
|
||||
routes to `brainstorm` and — being a new cycle needing a fresh
|
||||
discovery — is a bounce-back to the user per the same trigger 4.
|
||||
|
||||
If the profile does **not** enable the `tdd` phase, the reflection is
|
||||
two-way — `specify` for a settled design, `brainstorm` for an open one.
|
||||
`specify` is a core node (never profile-gated), so the settled-design
|
||||
path is always available; only the `tdd` test-specifiable branch is
|
||||
opt-in.
|
||||
All three entry paths are always available — none is profile-gated.
|
||||
The reflection is therefore always three-way: `tdd` for
|
||||
test-specifiable behaviour, `specify` for a settled design,
|
||||
`brainstorm` for an open one.
|
||||
|
||||
If the working tree is mid-flight (uncommitted changes left over
|
||||
from a previous session): inspect first, then resume the right
|
||||
@@ -228,8 +227,7 @@ Bounce back to the user only when:
|
||||
dependency failure, a discovered invariant violation).
|
||||
- The user has explicitly asked for a checkpoint.
|
||||
- **The next item on the queue is a new cycle** — i.e. a top-
|
||||
level work container (in the project's vocabulary: milestone,
|
||||
epic, release, sprint root) that has no spec file yet and
|
||||
level work container (a milestone) that has no spec file yet and
|
||||
would require dispatching `brainstorm` to even begin.
|
||||
Continuing an open cycle (next iteration, audit, fieldtest,
|
||||
post-audit tidy) is autonomous; *starting* a new cycle is a
|
||||
@@ -274,7 +272,7 @@ narrow one that exists only when spec auto-sign is enabled:
|
||||
the next backlog item is a new cycle (no spec yet) and
|
||||
starting it would force a fresh `brainstorm`.
|
||||
|
||||
3. **Auto-sign (only with `pipeline.boss.spec_auto_sign`).** The
|
||||
3. **Auto-sign (only when the project enables spec auto-sign).** The
|
||||
orchestrator signed a spec in the user's place and is
|
||||
continuing the run — see §"Spec auto-sign". This is the one
|
||||
sanctioned mid-flow notify, and it is sanctioned *because it
|
||||
@@ -296,10 +294,9 @@ Mid-flow progress notifications burn the user's attention
|
||||
without giving them a decision to make. When in doubt,
|
||||
continue.
|
||||
|
||||
The notification command is configured under
|
||||
`notifications.command` in the project profile and receives the
|
||||
message text as a single argument. If the profile does not
|
||||
configure one, fall back to printing the notification in chat.
|
||||
The notification command is `~/.claude/notify.sh` (the user-level
|
||||
convention); it receives the message text as a single argument. If it
|
||||
is unavailable, fall back to printing the notification in chat.
|
||||
|
||||
When notifying, the message body should be the actionable
|
||||
summary: what the orchestrator needs from the user, in one
|
||||
@@ -342,8 +339,8 @@ actionable ask, not a wrap-up summary.
|
||||
|
||||
## Spec auto-sign
|
||||
|
||||
Off by default. A project turns it on with
|
||||
`pipeline.boss.spec_auto_sign: true`. With it off, a `specify`
|
||||
Off by default. A project turns it on in its CLAUDE.md project facts
|
||||
(spec auto-sign: enabled). With it off, a `specify`
|
||||
dispatch in `/boss` always pauses for the user's signature — the
|
||||
conservative default, unchanged.
|
||||
|
||||
@@ -409,7 +406,7 @@ and defined there. The boss-side contract is just this:
|
||||
| "It's the same broad area as the cycle I just closed, that's not really a new cycle" | If there is no spec file for it yet and it would route through `brainstorm` to get one, it IS a new cycle for this rule's purposes. The rule keys on "needs a fresh spec", not on subjective continuity. |
|
||||
| "Feature work, so route it to `brainstorm` — that's the safe default" | `brainstorm`, `specify`, and `tdd` are co-equal entry paths; none is the default. Routing a settled design to `brainstorm` re-litigates decided choices; routing a test-specifiable item there wastes the test path. Run the Entry-path reflection and pick by the design line. The only tilt toward `brainstorm` is a genuinely unresolved fork — and that is a fork, not a default. |
|
||||
| "The issue is exhaustive but it's a new cycle, so bounce to the user before `specify`" | `specify` direct-entry is bounded and autonomously dispatchable — it is NOT the high-context `brainstorm` cycle that trigger 4 reserves for the user. Dispatch it; it will pause at its own user-review gate for sign-off. The pre-dispatch bounce is for an *open* design that needs discovery, not for a settled one that needs only production. |
|
||||
| "`tdd` is opt-in / profile-gated, so it's the secondary skill" | Profile-gating is about whether the path is *available*, not about rank. Once enabled, the choice between the two is decided by fit per item, reflected on each time — not by treating `brainstorm` as primary and `tdd` as the exception. |
|
||||
| "`tdd` is the secondary skill, `brainstorm` is the real entry" | All three entry paths are always available and co-equal. The choice among them is decided by fit per item, reflected on each time — not by treating `brainstorm` as primary and `tdd` as the exception. |
|
||||
| "Auto-sign is on and this spec is clearly good — I'll sign it and skip the panel" | The panel IS how a spec gets signed under auto-sign; there is no signing on judgement. Your sense that it is clearly good is the precise signal the gate is built not to trust. Run the objective gates, dispatch the five jurors, require unanimity. |
|
||||
| "Four jurors said SOUND, one blocked on something I think is wrong — I'll sign" | Unanimous-or-nothing. You never sign over a `BLOCK`. If it is an editorial lens, repair it and re-run the whole panel (≤ 2 rounds); if it is a design lens or the budget is spent, it routes to the human sign-off it would have had anyway. Signing because *you* think the juror is wrong is overruling the panel — confidence by the back door. |
|
||||
| "Auto-sign let me continue, so I don't need to notify — it's just progress" | The auto-sign notify is mandatory and carries a decision (the user's veto over a signature made without them). It is the one sanctioned mid-flow notify precisely because it is not progress — it is the audit trail for a delegated gate. |
|
||||
@@ -424,7 +421,7 @@ and defined there. The boss-side contract is just this:
|
||||
- About to dispatch `brainstorm` on a backlog issue that does not yet have a spec file, without first bouncing back to the user. New cycles never start autonomously.
|
||||
- About to route feature work to `brainstorm` without running the Entry-path reflection — defaulting to it because it "feels safer" than `specify` or `tdd`, rather than applying the design-line test. The three are co-equal; the choice is reflected on each time. Routing a *settled* design to `brainstorm` (re-litigating decided choices) is as much a failure as skipping discovery on an open one.
|
||||
- About to sign a spec under auto-sign on confidence — without all objective gates green and a unanimous `spec-skeptic` panel; signing over any `BLOCK`; self-correcting a *design*-lens (`scope-fork` / `grounding`) `BLOCK` instead of escalating; or looping past the 2-round budget. The gate exists so the orchestrator's confidence never signs.
|
||||
- About to run the auto-sign path at all when `pipeline.boss.spec_auto_sign` is not enabled, or to skip the mandatory auto-sign notify after signing.
|
||||
- About to run the auto-sign path at all when the project has not enabled spec auto-sign, or to skip the mandatory auto-sign notify after signing.
|
||||
|
||||
## Cross-references
|
||||
|
||||
@@ -437,17 +434,17 @@ and defined there. The boss-side contract is just this:
|
||||
layer, loaded in every session, above the project file) — it
|
||||
carries constraints that bind autonomous runs too, including
|
||||
external-service-consent rules that `/boss` does not lift.
|
||||
- **Queue:** the URL configured under `git.issue_tracker.url` in
|
||||
the profile; CLI command at `git.issue_tracker.list_cmd`.
|
||||
- **Queue:** the project's issue tracker — its CLAUDE.md project
|
||||
facts name the repo slug, the browsable URL, and the list command.
|
||||
- **Glossary write-rule:** `../docs/glossary-convention.md` —
|
||||
record-reality discipline for the only autonomous glossary writer.
|
||||
- **Spec auto-sign gate:** owned by `../specify` Step 6; the
|
||||
adversarial juror is `../specify/agents/spec-skeptic.md` (dispatched
|
||||
five times, one per lens). Enabled per project by
|
||||
`pipeline.boss.spec_auto_sign` — see `../docs/profile-schema.md`.
|
||||
five times, one per lens). Enabled per project in its CLAUDE.md
|
||||
project facts — see `../docs/conventions.md`.
|
||||
- **Downstream skills dispatched:** `../brainstorm`,
|
||||
`../specify` (spec-production core; autonomously dispatchable for a
|
||||
settled design), `../planner`, `../implement`, `../audit`,
|
||||
`../fieldtest`, `../debug`, `../tdd` (test-specifiable feature,
|
||||
profile-gated; autonomously dispatchable like `../debug`),
|
||||
always available; autonomously dispatchable like `../debug`),
|
||||
`../docwriter`.
|
||||
|
||||
Reference in New Issue
Block a user