supi-flow

PI-only workflow package for spec-driven changes backed by TNDM tickets.

supi-flow adds a lightweight workflow on top of tandem's tndm CLI: brainstorm → plan → apply → archive.

It is published as @mrclrchtr/supi-flow and ships inside the tandem repository at plugins/supi-flow/.

Use it when a change needs:

• an approved design before implementation
• a durable TNDM ticket for non-trivial work
• explicit task-by-task verification during implementation
• archived verification evidence at closeout

Trivial changes can still be implemented directly without a ticket.

What ships in the package

supi-flow uses PI's conventional package directories, so PI auto-discovers the resources in:

• extensions/
• skills/
• prompts/

Current package contents:

• 7 custom tools
  • supi_tndm_cli
  • supi_flow_start
  • supi_flow_plan
  • supi_flow_apply
  • supi_flow_task
  • supi_flow_complete_task
  • supi_flow_close
• 5 skills
  • supi-flow-brainstorm
  • supi-flow-plan
  • supi-flow-apply
  • supi-flow-archive
  • supi-flow-debug
• 1 prompt template
  • /supi-coding-retro
• Startup/reload version check
  • on PI session start and reload, the extension compares tndm --version with the package version and warns when they do not match

This package does not rely on a pi manifest in package.json; it uses PI's conventional directory discovery.

Installation and loading

Install from npm

pi install npm:@mrclrchtr/supi-flow

Install from a local checkout

From the tandem repository root:

pi install ./plugins/supi-flow

Or add the package root to PI settings:

{
  "packages": ["./plugins/supi-flow"]
}

Important: prefer the package root, not just the extension entrypoint

If you load only plugins/supi-flow/extensions/index.ts, PI gets the extension entrypoint, but not the package-style resource loading for the bundled skills and prompt template.

Use the package root when you want the full package:

• extension tools
• auto-discovered skills
• auto-discovered prompt template

Dependency: tndm

supi-flow wraps the tandem CLI and expects tndm to be installed and on your PATH. Keep tndm and @mrclrchtr/supi-flow on matching release versions so the startup/reload version check stays quiet.

See the tandem project README for CLI install options: https://github.com/mrclrchtr/tandem

How you use it in PI

This package is primarily used through:

• skills via /skill:<name>
• tools invoked by the model
• prompt template /supi-coding-retro

There is no custom /supi-flow slash command registered by the extension.

Typical workflow

1. Brainstorm — /skill:supi-flow-brainstorm

   • clarify intent
   • inspect the codebase
   • compare approaches
   • approve a design before editing
   • decide whether the change is trivial or non-trivial

2. Plan — /skill:supi-flow-plan TNDM-XXXXXX

   • store the approved overview in content.md
   • author executable tasks one at a time in state.toml via supi_flow_task
   • when revising an existing ticket, list the current tasks first and reconcile them with edit/remove/add instead of blindly appending new ones
   • keep tasks concrete, ordered, and verifiable

3. Apply — /skill:supi-flow-apply TNDM-XXXXXX

   • start with supi_flow_apply to load the approved overview and task manifest
   • review the overview and full task list up front
   • defer linked detail_path doc reads until the corresponding task starts
   • transition planned tickets into flow:applying
   • resume already-applying tickets with their current in_progress or blocked status intact
   • execute tasks in order
   • run fresh verification for each task
   • check off tasks with supi_flow_complete_task

4. Debug when blocked — /skill:supi-flow-debug

   • use the root-cause workflow instead of guessing

5. Archive — /skill:supi-flow-archive TNDM-XXXXXX

   • re-verify the completed change
   • update living docs if needed
   • close the ticket with required archived verification evidence

Flow phases

| Phase | Main skill | Ticket behavior | |---|---|---| | Brainstorm | supi-flow-brainstorm | creates or refines the change definition; non-trivial work starts with supi_flow_start | | Plan | supi-flow-plan | stores the approved overview in content.md, then authors structured tasks one at a time via supi_flow_task | | Apply | supi-flow-apply | starts with supi_flow_apply, loads the approved overview plus task manifest, reviews that overview and full task list up front, reads any linked task detail doc only when that task begins, transitions to flow:applying when needed, preserves the current in_progress or blocked status for already-applying tickets, then executes tasks and verifies each step fresh | | Archive | supi-flow-archive | verifies the final result, writes archive.md, and closes the ticket |

Flow state is tracked with TNDM status/tag combinations:

| Flow phase | Status | Tags | |---|---|---| | Brainstorm | todo | flow:brainstorm | | Plan written | todo | flow:planned | | Implementing | in_progress | flow:applying | | Paused during apply | blocked | flow:applying | | Done | done | flow:done |

Ticket document model

supi-flow uses tandem's registered document model with an overview-first workflow:

| Artifact | Role | |---|---| | content.md | Canonical approved overview / design / plan prose | | state.toml tasks | Structured execution manifest used during apply | | tasks/task-XX.md | Canonical task detail doc — every task gets one automatically at creation time | | archive.md | Final verification evidence written during archive/closeout |

Key rules from the current implementation:

• content.md is overview-first and may contain zero tasks.
• Executable tasks live in state.toml, not in checklist blocks parsed from markdown.
• Every task gets a canonical tasks/task-XX.md detail doc automatically at creation time.
• The common plan-time task-authoring path is supi_flow_task; low-level task_* actions remain available as escape hatches.
• When revising a ticket that already has tasks, list the current manifest first and reconcile it with edit / remove / add operations instead of treating replanning as repeated append-only adds.
• Older tickets may still contain a legacy brainstorm sidecar document, but new flow work should not depend on it.

Tools

The extension registers seven custom tools.

| Tool | What it does | |---|---| | supi_tndm_cli | Structured wrapper around tndm for ticket create/update/show/list/awareness plus lower-level task add/list/complete/remove/edit/set actions | | supi_flow_start | Creates a ticket with status=todo and tag flow:brainstorm, optionally persisting initial context into content.md | | supi_flow_plan | Stores the approved overview in content.md and replaces flow-state tags with flow:planned | | supi_flow_apply | Loads the approved overview from content.md, returns the structured task manifest, transitions flow:planned tickets into status=in_progress with flow:applying, preserves the current in_progress or blocked status for already-applying tickets, and is used with apply guidance that reads linked task detail docs only when the active task begins | | supi_flow_task | Adds, edits, or removes one structured task at a time and optionally manages the canonical tasks/task-XX.md detail doc; use it to reconcile existing task manifests during replans as well as to create new ones | | supi_flow_complete_task | Marks one numbered task as done in the structured task manifest | | supi_flow_close | Requires verification evidence, refuses to close unless the ticket is in flow:applying with a non-empty all-done structured task list, writes archive.md, syncs documents, and closes the ticket with status=done and flow:done |

supi_tndm_cli at a glance

supi_tndm_cli is intentionally thinner than the flow skills. Use supi_flow_task for the normal plan-time path to author tasks one at a time. Reach for supi_tndm_cli when you need direct ticket operations or lower-level task repair.

Current action groups:

• ticket actions — create, update, show, list, awareness
• task actions — task_add, task_list, task_complete, task_remove, task_edit, task_set
  • these are lower-level escape hatches; normal plan-time task authoring should prefer supi_flow_task

Task-detail behavior worth knowing:

• every task_add automatically creates the canonical tasks/task-XX.md detail doc via the Rust CLI
• when task_detail is provided, the tool writes the full markdown body and runs tndm ticket sync
• task_edit can also write updated task detail docs and clear file lists

Skills

The package ships five skills under skills/.

| Skill | Use it for | |---|---| | supi-flow-brainstorm | Clarify intent, inspect context, compare approaches, and get approval before implementation | | supi-flow-plan | Turn the approved design into an executable plan with exact files and verification | | supi-flow-apply | Execute the approved plan task by task with fresh verification gates | | supi-flow-archive | Re-verify the completed change, update living docs, and close the ticket | | supi-flow-debug | Systematic root-cause debugging when verification fails or the cause is unclear |

Prompt template

| Prompt | Purpose | |---|---| | /supi-coding-retro | Retrospective on setup, architecture, tooling, workflow, and conventions |

Package layout

plugins/supi-flow/
├── extensions/
│   ├── index.ts
│   ├── cli.ts
│   └── tools/
├── skills/
│   ├── supi-flow-brainstorm/
│   ├── supi-flow-plan/
│   ├── supi-flow-apply/
│   ├── supi-flow-archive/
│   └── supi-flow-debug/
├── prompts/
│   └── supi-coding-retro.md
└── __tests__/

Development

cd plugins/supi-flow
pnpm install

# Type-check
pnpm exec tsc --noEmit

# Run the full test suite
pnpm exec vitest run

Useful targeted checks from the current package guidance:

# Version-check / tool registration behavior
pnpm exec vitest run __tests__/index.test.ts __tests__/resources.test.ts

# CLI wrapper behavior
pnpm exec vitest run __tests__/cli.test.ts

# Flow tools
pnpm exec vitest run __tests__/flow-tools.test.ts

# TNDM CLI tool behavior
pnpm exec vitest run __tests__/tndm-cli-tool.test.ts

Validation notes while developing

• After changing extensions/, skills/, or prompts/, use /reload or restart PI before validating behavior.
• Use the plugin source and tests as the source of truth for README claims.
• Keep runtime PI packages in peerDependencies with "*" ranges and non-PI runtime deps in dependencies.
• Do not add resources_discover for skills/ or prompts/; PI already auto-discovers them from the conventional directories.