git:20260519.a169a22 to git:20260609.d617e1b

- <<<<<<< HEAD

- =======

- description: "Canonical planning entry point. Routes high-level planning intent to new-track, decompose, change, or adr, and provides a planning checkpoint when the next planning step depends on track state. Use when the user says 'plan this', 'scope this work', 'start a feature', 'continue planning', or wants one command to handle planning and design flow."

- ---

-

- # Plan Work

-

- `/draft:plan` is the **parent planning command**.

-

- It exists to remove planning command soup from the developer experience.

-

- Do not treat this command as a static menu. It must either:

-

- - route to the correct planning workflow, or

- - produce a useful planning checkpoint that tells the developer the next best planning action

-

- Specialist planning skills remain available:

-

- - `/draft:new-track`

- - `/draft:decompose`

- - `/draft:change`

- - `/draft:adr`

-

- But `/draft:plan` is now the canonical entry point for planning intent.

-

- ## Red Flags - STOP if you're:

-

- - dumping a list of planning commands instead of routing

- - creating a new track without reading existing Draft context

- - mutating a track plan without first checking whether the request is actually a requirement change

- - sending the user to `/draft:decompose` or `/draft:adr` without explaining why

- - overriding explicit user intent for a named planning mode

-

- **Route first. Explain why. Then execute the chosen planning workflow.**

-

- ---

-

- ## Parent Contract

-

- `/draft:plan` owns four planning jobs:

-

- 1. **Create work** → `/draft:new-track`

- 2. **Break work into modules and architecture** → `/draft:decompose`

- 3. **Amend planned work safely** → `/draft:change`

- 4. **Capture a durable technical decision** → `/draft:adr`

-

- The parent command should absorb the choice burden whenever the intent is obvious.

-

- ---

-

- ## Step 1: Parse Intent

-

- Inspect `$ARGUMENTS` and classify the request into one of these buckets.

-

- ### Explicit Named Modes

-

- If the command already names a specialist mode, route directly:

-

- - `new-track`

- - `decompose`

- - `change`

- - `adr`

-

- Examples:

-

- - `/draft:plan new-track add user auth`

- - `/draft:plan decompose`

- - `/draft:plan change support JSON export`

- - `/draft:plan adr choose outbox pattern`

-

- ### High-Signal Natural Language

-

- Route by intent when the user did not name the specialist command explicitly.

-

- | Intent Pattern | Route To |

- |---|---|

- | "start a feature", "plan this feature", "scope this work", "I want to build X", "fix Y bug", "create a track" | `/draft:new-track` |

- | "break into modules", "architecture this", "decompose", "design boundaries", "need HLD/LLD" | `/draft:decompose` |

- | "requirements changed", "scope changed", "update the plan", "we also need X", "adjust the spec" | `/draft:change` |

- | "document decision", "write an ADR", "record the tradeoff", "capture this architecture decision" | `/draft:adr` |

-

- ### Bare `/draft:plan`

-

- If there are no meaningful arguments, do not fall back to a command list.

-

- Instead, inspect Draft state and determine the next planning action.

-

- ---

-

- ## Step 2: Verify Draft Context

-

- Run this check first:

-

- ```bash

- ls draft/tracks.md 2>/dev/null

- ```

-

- If `draft/` does not exist:

-

- - If the user is trying to create new planned work, stop and say: `No Draft context found. Run /draft:init first.`

- - Do not continue into planning without initialized context.

-

- ---

-

- ## Step 3: Inspect Current Planning State

-

- For bare `/draft:plan`, or when intent is ambiguous, inspect current project state before routing.

-

- ### 3.1 Active Track Detection

-

- Read `draft/tracks.md`.

-

- Find:

-

- - first `[~]` In Progress track

- - otherwise first `[ ]` Pending track

-

- If no track exists:

-

- - default to `/draft:new-track`

-

- Announce:

-

- ```text

- Planning mode selected: new-track

- Reason: no active Draft track exists yet.

- ```

-

- Then follow the `/draft:new-track` workflow.

-

- ### 3.2 Track Artifact Inspection

-

- For the active track, inspect:

-

- - `draft/tracks/<id>/spec.md`

- - `draft/tracks/<id>/plan.md`

- - `draft/tracks/<id>/hld.md` if present

- - `draft/tracks/<id>/lld.md` if present

- - `draft/tracks/<id>/metadata.json` if present

-

- Extract:

-

- - track name and status

- - whether architecture artifacts already exist

- - whether the plan appears structurally complex

- - whether there are recent planning amendments or unresolved scope drift

-

- ### 3.3 Complexity Signals

-

- Treat these as signals that `/draft:decompose` is likely the next best planning step:

-

- - plan spans multiple phases or modules

- - spec mentions migrations, concurrency, background jobs, external systems, or multi-service boundaries

- - work touches auth, payments, persistence, or public APIs

- - user explicitly asks for module boundaries, interfaces, implementation order, HLD, or LLD

- - `hld.md` is absent for clearly non-trivial work

-

- ### 3.4 Change Signals

-

- Treat these as signals that `/draft:change` is likely the next step:

-

- - user asks to revise scope of an existing active track

- - user adds or removes acceptance criteria after planning already exists

- - completed or in-progress work may be invalidated by a new requirement

-

- ### 3.5 ADR Signals

-

- Treat these as signals that `/draft:adr` is likely the next step:

-

- - a durable architecture decision is being proposed

- - multiple viable options exist and the tradeoff matters long-term

- - the team wants the rationale preserved independently of the track

-

- ---

-

- ## Step 4: Route Deterministically

-

- Apply these routing rules in order.

-

- ### Rule 1: Explicit Mode Wins

-

- If the user invoked:

-

- - `/draft:plan new-track`

- - `/draft:plan decompose`

- - `/draft:plan change`

- - `/draft:plan adr`

-

- route directly and follow that specialist workflow.

-

- ### Rule 2: Requirement Drift Beats Architecture Work

-

- If an active track exists and the request changes already-planned work, prefer `/draft:change` before `/draft:decompose` or `/draft:adr`.

-

- Reason:

-

- - spec/plan truth must be corrected before deeper design artifacts are regenerated

-

- ### Rule 3: Architecture Work Beats New Feature Intake

-

- If a track already exists and complexity signals show the next planning bottleneck is structure, route to `/draft:decompose`.

-

- ### Rule 4: Decision Capture Is Explicit or Triggered by a Confirmed Tradeoff

-

- Route to `/draft:adr` when:

-

- - the user asked for an ADR, or

- - planning analysis exposes a material architectural fork that should be recorded

-

- ### Rule 5: Otherwise Default to New Track Intake

-

- If no stronger signal exists, route to `/draft:new-track`.

-

- This is the default parent behavior for feature, bugfix, and refactor planning requests.

-

- ---

-

- ## Step 5: Announce the Selected Planning Mode

-

- Before executing the chosen workflow, tell the user what `/draft:plan` decided.

-

- Use this format:

-

- ```text

- Planning mode selected: <mode>

- Reason: <short reason grounded in track state or user intent>

- ```

-

- Examples:

-

- ```text

- Planning mode selected: new-track

- Reason: this is a fresh feature request and no active matching track exists.

- ```

-

- ```text

- Planning mode selected: change

- Reason: an active track already exists and the request alters approved scope.

- ```

-

- ```text

- Planning mode selected: decompose

- Reason: the track is multi-phase, crosses service boundaries, and has no HLD yet.

- ```

-

- ---

-

- ## Step 6: Execute the Specialist Workflow

-

- After routing, fully follow the corresponding specialist skill as the canonical implementation:

-

- - `/draft:new-track` for intake, spec, plan, and metadata creation

- - `/draft:decompose` for architecture/module decomposition

- - `/draft:change` for scoped amendments to an existing track

- - `/draft:adr` for decision records

-

- Do not partially imitate those commands. Route, announce, then execute their workflow.

-

- ---

-

- ## Bare `/draft:plan` Fallback Output

-

- If `/draft:plan` is bare and the next planning step is genuinely ambiguous even after inspecting context, produce a short planning checkpoint instead of a command list.

-

- Format:

-

- ```text

- Planning checkpoint: <track_id> - <track_name>

- - Current state: <one-line summary>

- - Next recommended planning action: <new-track|decompose|change|adr>

- - Why: <short reason>

- ```

-

- Then proceed with the recommended action unless the user objects.

-

- The parent command should still move planning forward.

-

- ---

-

- ## Examples

-

- ### Example 1: Fresh feature request

-

- Input:

-

- ```text

- /draft:plan add user authentication

- ```

-

- Route:

-

- - `/draft:new-track`

-

- ### Example 2: Existing track got new scope

-

- Input:

-

- ```text

- /draft:plan we also need JSON export

- ```

-

- Context:

-

- - active track already exists for CSV export

-

- Route:

-

- - `/draft:change`

-

- ### Example 3: Complex track needs structure

-

- Input:

-

- ```text

- /draft:plan

- ```

-

- Context:

-

- - active track exists

- - plan spans multiple modules

- - no `hld.md`

-

- Route:

-

- - `/draft:decompose`

-

- ### Example 4: Decision needs durable record

-

- Input:

-

- ```text

- /draft:plan should we use the outbox pattern here?

- ```

-

- If the tradeoff is real and decision-worthy:

-

- - `/draft:adr`

-

- Otherwise:

-

- - discuss briefly during planning, then continue with the best planning workflow

-

- ---

-

- ## Compatibility Notes

-

- The following specialist commands remain valid and should continue to work:

-

- - `/draft:new-track`

- - `/draft:decompose`

- - `/draft:change`

- - `/draft:adr`

-

- `/draft:plan` is the canonical parent.

-

- When helpful, reinforce the canonical form in output:

-

- ```text

- `/draft:new-track` remains supported. Canonical parent: `/draft:plan new-track`.

- ```

- >>>>>>> a79c14023e16774c77463870ac3510b728e8a91c