---
name: supi-flow-plan
description: Create an implementation plan for an approved design with exact file paths, ordered tasks, concrete verification, and no placeholders.
disable-model-invocation: true
---

# Create implementation plan

## Step 1: Find the design

- If a TNDM-ID was given as argument: `supi_tndm_cli { action: "show", id: "<ID>" }` — inspect `content_path`, then read the approved design from `content.md`.
- If no TNDM-ID was given and no active ticket exists: ask the user to run `/skill:supi-flow-brainstorm` first, or provide an existing ticket ID.
- If no design is available: ask which change to plan.

## Step 2: Scope check

If the design covers multiple independent subsystems, suggest splitting it into separate plans. Each plan should produce a coherent, testable result.

## Step 3: Choose the right detail level

Use **adaptive detail by complexity**:

- **Light plan** for small or familiar changes: clear tasks, files, verification, and constraints.
- **Fuller executable plan** for risky, unfamiliar, multi-file, or high-impact changes: more explicit steps, commands, and snippets when they reduce ambiguity.

Do not add ceremony for its own sake.

## Step 4: Map file structure

Before writing tasks, list which files will be created or modified and what each is responsible for.

- Use exact file paths.
- Prefer focused units with clear responsibilities.
- Follow existing codebase patterns.
- Include doc targets when the change affects user-facing or maintainer-facing behavior.

## Step 5: Write the overview, then define ordered tasks separately

The approved overview belongs in `content.md`. It can be pure design / plan prose and may contain zero tasks.

After the overview is approved and persisted, define executable tasks separately in `state.toml`. Start by inspecting the current manifest with `supi_tndm_cli { action: "task_list", id: "<ID>" }`.

For the normal path, use `supi_flow_task` to add, edit, or remove **one task at a time** instead of building raw `task_json` or managing `detail_path` manually:

- **Empty ticket / no tasks yet:** create the manifest with repeated `supi_flow_task { operation: "add", ... }` calls.
- **Replan / tasks already exist:** reconcile the existing manifest to the new final shape.
  - same task, new details → `supi_flow_task { operation: "edit", task_number: <N>, ... }`
  - task no longer belongs in the plan → `supi_flow_task { operation: "remove", task_number: <N> }`
  - genuinely new task → `supi_flow_task { operation: "add", ... }`

For each task, include:

- the goal
- exact file paths
- the change to make
- how to verify it
- whether it is test-driven or explicitly test-exempt

Use enough detail that an agent can execute without guessing, but do not force huge code blocks into every step.

**Always make the final task a verification task.** This task confirms the whole change works end-to-end — run the full test suite, exercise the changed behavior manually, or both. It is not task-specific unit verification (each task already carries its own); it is the integration gate that proves the assembled change is correct.

**Task numbering convention**: On an empty ticket, adds through `supi_flow_task` start at 1 and increase sequentially. On a ticket that already has tasks, `add` returns the next available task number. Always use the returned task number for later edits, removals, and completion.

Every task gets a canonical `tasks/task-XX.md` detail doc automatically at creation time. When a task needs real implementation detail or notices, pass `detail` markdown through `supi_flow_task` to write the full content; omit `detail` to keep the minimal template.

## TDD by default

For testable code changes, prefer red-green-refactor:

```text
RED → write the failing test → verify it fails for the right reason
GREEN → write the minimal code to pass → verify it passes
REFACTOR → clean up while staying green
```

Critical rule: if you did not watch the test fail, you do not know whether it proves the behavior.

### Test exemptions

TDD is the default, not an absolute rule.

A task may be marked **test-exempt** when TDD is not practical, such as:

- docs-only changes
- config-only changes
- trivial edits
- shell or integration work with no reasonable harness

Every test-exempt task MUST include:

- a brief rationale
- a concrete manual verification step
- the exact command and expected result when possible

Do not use test exemptions to avoid testing logic that could reasonably be tested.

## Rules

- **No placeholders.** Never write `TBD`, `TODO`, `implement later`, or vague instructions like `add error handling`.
- **Exact file paths** always.
- **Specific and unambiguous language.** Every task, file path, and verification step must be precise enough that another agent can execute it without asking clarifying questions. Prefer concrete commands over descriptions of intent.
- **Verification is mandatory.** Every task needs a concrete check.
- **Final task is always verify/test.** Every plan ends with a dedicated verification task that confirms the whole change works end-to-end (full test suite, manual smoke test, or both). This is in addition to each task's own verification.
- **No code before test or verification.** Testable code starts with a failing test. Test-exempt work starts with manual verification.
- **Include doc updates** when the change affects docs, help text, architecture notes, or workflow guidance.

## Self-review

After writing the plan, check it against the approved design:

1. **Coverage:** does every important requirement map to a task?
2. **Placeholder scan:** remove vague or incomplete instructions.
3. **Consistency:** do names, types, files, and steps line up across tasks?
4. **Right-sized detail:** is the plan clear without being bloated?
5. **Final verify task:** does the last task confirm the whole change works end-to-end?

Fix issues inline before handing off.

## Output and persistence

Write the plan in the lightest form that will still survive execution:

- **If a ticket exists:** use `supi_flow_plan { ticket_id: "<ID>", plan_content: "..." }` to store the approved overview in `content.md`. Then list the current tasks. If the manifest is empty, build it with repeated `supi_flow_task { operation: "add", ... }` calls. If tasks already exist, reconcile them to the new final plan with `supi_flow_task` edit/remove/add operations. Keep `supi_tndm_cli` task_* actions as lower-level escape hatches for advanced/manual repair cases.
- **If no ticket exists:** default to conversation-first. Offer saving to a ticket or file if the work is larger or likely multi-session.
- Close with: `Plan ready. Review it and approve before we start. Then run /skill:supi-flow-apply TNDM-XXXXXX.`