Supi Flow Plan

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:

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.