| name | decompose |
| description | Decompose the active Architect workflow's plan.md into a runnable tracer and dependency-ordered vertical tickets. Use only when the user invokes $decompose. |
Operate in the main thread as Architect. Decompose the reviewed plan into
independently implementable tickets under tickets/. Do not write product code.
Draft and validate the cut before asking for approval.
Use any path accompanying the invocation to resolve the plan:
- A named Markdown file is the plan path.
- A named directory resolves to
<directory>/plan.md.
- Otherwise use
plan.md in the current working directory.
Read the plan first. If it is missing, tell the user to invoke $plan-feature
and stop. Read decision-brief.md next to it when present. Tickets live in
tickets/ next to the plan.
Existing Tickets
If the tickets directory already contains files:
- Derive completed ids from commit messages with a full line exactly equal to
Ticket: <id>.
- Classify the request as an accidental collision, a full replacement with no
completed work, or an incremental re-decomposition.
- Stop and explain the proposed treatment.
- Get explicit approval before writing or removing ticket files.
For a full replacement, replace open or blocked tickets with fresh ids. For an
incremental re-decomposition, preserve completed ticket files and ids unchanged,
replace only open or blocked tickets with fresh ids, and add corrective tickets
when the new plan invalidates accepted behavior. Never rewrite an accepted
ticket or reuse its id.
This approved replacement is part of the active workflow. It does not authorize
end-of-workflow cleanup or replacement of artifacts from a different workflow.
Cut Rules
Every ticket must be implementable by a fresh developer from only the ticket,
plan, brief, repository seeds, and an optional correction brief.
- Start with a runnable tracer. The first behavior ticket has
tracer: true and delivers the smallest observable path through the system.
It proves the path at the closest real browser, CLI, API, integration, or
public library boundary. Every later behavior ticket depends on it directly
or transitively.
- Use a contract ticket only when justified. It may precede the tracer only
for a narrow, stable external or shared boundary that consumers require
first, such as a schema, protocol, or ABI. State the justification. Typed
code and easy stubs are not justification.
- Cut later work vertically. Each behavior ticket owns observable behavior
end to end and carries a subset of the plan's Gherkin scenarios.
- Size for review and proof. Prefer a diff one person can review in one
sitting, roughly 100-200 hand-written changed lines when practical. Explain
larger slices that cannot split without losing end-to-end proof.
- Declare ownership. Each ticket has a
scope. Inspect sibling overlap;
deliberate serial overlap can be valid for routers, schemas, and registries.
- Place checkpoints. The tracer always has
checkpoint: human. In a
high-risk workflow, mark load-bearing, migration, security, persistence, and
hard-to-reverse slices the same way. Final human review remains required.
- Preserve effective history. Keep a completed tracer if it still proves
the path. If invalidated, create a fresh correcting behavior ticket with
tracer: true and corrects: [<old-tracer>].
Proposed Cut And Approval
Draft the full cut in memory. Present each ticket's id, title, type, tracer,
checkpoint, dependencies, expected scope, scenarios, and Observable Proof.
Present preliminary gate results. Wait for explicit user approval before
creating, changing, or removing ticket files.
Ticket Schema
After approval, write one file per new ticket at tickets/<id>.md:
---
id: auth-001
title: <short imperative title>
type: behavior
tracer: true
checkpoint: human
status: open
deps: []
corrects: []
scope:
- Sources/Auth/Login.swift
- Tests/AuthTests/LoginTests.swift
gherkin:
- "@must Login succeeds with valid credentials"
seeds:
- Sources/Auth/AuthService.swift
verification: test-first
---
## Goal
One or two sentences.
## Contract
The interface slice this ticket materializes, referencing the plan's Execution
Sketch. A contract ticket also justifies its behaviorless predecessor.
## Acceptance Criteria
Concrete criteria derived from the assigned scenarios.
## Observable Proof
How to exercise the slice through a real boundary. A public-interface test is
acceptable for pure library work. A contract ticket names its compile, schema,
or compatibility check.
## Notes
(left empty at creation; escalation notes only)
Allowed frontmatter values:
type: behavior or contracttracer: exactly one effective behavior ticket is truecheckpoint: human or nonestatus: open or blocked; never store done, ready, or in-progressverification: test-first, implementation-first,
characterization-first, or manual-verification, plus a command when useful
A contract ticket owns no Gherkin scenarios and normally has tracer: false.
corrects retires each named completed ticket from current-plan ownership in
full. A correcting behavior ticket carries every still-current, non-deferred
scenario from the historical ticket plus the corrected behavior. Use an
extension ticket without corrects when old behavior remains current. Only the
tip of a correction chain is effective.
Mechanical Gate
Run these checks before presenting the cut and again against disk after writing:
- Coverage: every non-deferred scenario belongs to exactly one effective
behavior ticket; deferred scenarios belong to none.
- Tracer: exactly one effective behavior ticket is the first observable
slice, and later behavior reaches it through dependencies.
- Contract justification: any predecessor is narrow, stable, and has named
consumers.
- DAG and references: dependency and correction graphs are acyclic. Deps
resolve to effective or preserved completed tickets.
corrects resolves only
to preserved completed tickets.
- Observable proof: every behavior ticket reaches a real boundary.
- Human review: tracer and high-risk checkpoints match the plan.
- Reviewability: likely large tickets are flagged and justified.
- Scope overlap: every sibling overlap is reported as deliberate and serial
or corrected as a bad cut.
- Verifiability: every ticket declares a method.
- Seeds exist: check every seed path mechanically against the current disk.
Future files belong in Contract, not seeds.
- Scope sanity: flag scope paths whose parent directory is also missing.
- Id hygiene: filename stem equals frontmatter id; new ids are unique and do
not already appear as an exact
Ticket: <id> trailer. Preserved completed ids
are exempt.
Write And Re-check
After approval, preserve completed files, write the approved fresh files, and
remove only replaced open or blocked files from this active workflow. Rerun the
gate against disk and full commit messages.
Ticket files are temporary and remain uncommitted. Never stage or commit the
brief, plan, or tickets. The user owns final cleanup.
If decomposition reveals a wrong program design, stop and send the user back to
$plan-feature. Do not hide the flaw in ticket wording.
Final Response
Report:
- plan and tickets paths
- preserved, created, replaced, and removed tickets
- coverage, tracer, DAG, proof, review, scope, seed, and id gate results
- open questions
- the next explicit invocation:
$start-work
