git:20260517.c05498a to git:20260519.a169a22

---

name: plan

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`.

```