@mrclrchtr/supi-flow 0.10.0 → 0.11.0

package/README.md

@@ -1,164 +1,243 @@
 # supi-flow
 
-PI extension for spec-driven workflow with TNDM ticket coordination (optional for trivial changes).
-
-## Flow
-
-```mermaid
-flowchart TD
-    START(["Start a change"]) --> BRAIN
-    BRAIN["/skill:supi-flow-brainstorm
-         HARD-GATE: no code yet
-         Explore, design, approve
-         Classify trivial vs non-trivial"]
-    BRAIN --> APPROVED{Design approved?}
-    APPROVED -->|"No"| BRAIN
-    APPROVED -->|"Yes"| TRIVIAL{Trivial change?}
-
-    TRIVIAL -->|"Yes (skip ticket)"| LIGHT["Implement directly
-         No ticket needed"]
-    TRIVIAL -->|"No"| PLAN
-
-    PLAN["/skill:supi-flow-plan [ID]
-         Bite-sized tasks
-         Exact file paths
-         No placeholders
-         TDD: red-green-refactor
-         Stores plan via supi_flow_plan"]
-    PLAN --> APPROVE2{"Plan approved?"}
-    APPROVE2 -->|"No"| PLAN
-    APPROVE2 -->|"Yes"| APPLY
-
-    APPLY["/skill:supi-flow-apply [ID]
-         Iron Law: fresh verify each task
-         TDD gate: test-first or delete
-         Sets flow:applying at start
-         Checks off tasks via supi_flow_complete_task"]
-    APPLY --> BLOCKED{"Verification
-         failed?"}
-
-    BLOCKED -->|"Yes"| DEBUG["/skill:supi-flow-debug
-         4-phase systematic debugging
-         3-fix → question architecture"]
-    DEBUG --> FIXED{Fixed?}
-    FIXED -->|"Yes"| APPLY
-    FIXED -->|"No"| USER["Talk to user
-         before fix #4"]
-
-    BLOCKED -->|"No"| DONE{"All tasks
-         done?"}
-    DONE -->|"No"| APPLY
-    DONE -->|"Yes"| ARCHIVE
-
-    ARCHIVE["/skill:supi-flow-archive [ID]
-         Fresh verification (gate function)
-         Update living documentation
-         Quality gate checklist"]
-    ARCHIVE --> QGATE{"Quality gate
-         passes?"}
-    QGATE -->|"No"| ARCHIVE
-    QGATE -->|"Yes"| CLOSE
-
-    CLOSE["supi_flow_close
-         Sets status=done, flow:done
-         Writes archive.md"]
-
-    classDef phase fill:#e8f5e9,stroke:#4caf50,stroke-width:2
-    classDef decision fill:#e3f2fd,stroke:#2196f3
-    classDef entry fill:#e8e8e8,stroke:#666
-    classDef blocker fill:#ffebee,stroke:#f44336
-
-    class BRAIN,PLAN,APPLY,ARCHIVE,CLOSE phase
-    class APPROVED,APPROVE2,BLOCKED,FIXED,DONE,TRIVIAL decision
-    class START entry
-    class USER blocker
-    class LIGHT entry
+> **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
+
+```bash
+pi install npm:@mrclrchtr/supi-flow
 ```
 
-Non-trivial flows require a TNDM ticket created by `supi_flow_start`. Trivial changes can be implemented directly without a ticket.
+### Install from a local checkout
 
-## Skills
+From the tandem repository root:
 
-Five skills ship under `skills/`:
+```bash
+pi install ./plugins/supi-flow
+```
 
-| Skill | Trigger | Purpose |
-|---|---|---|
-| `supi-flow-brainstorm` | `/supi-flow-brainstorm` | Explore intent and design, classify trivial vs non-trivial, create ticket if needed |
-| `supi-flow-plan` | `/supi-flow-plan [ID]` | Create bite-sized implementation plan |
-| `supi-flow-apply` | `/supi-flow-apply` | Execute plan task by task |
-| `supi-flow-archive` | `/supi-flow-archive` | Verify, update docs, close out |
-| `supi-flow-debug` | Loaded on demand when blocked | Root-cause debugging protocol |
+Or add the package root to PI settings:
 
-## Tools
+```json
+{
+  "packages": ["./plugins/supi-flow"]
+}
+```
 
-Five custom tools registered by the extension:
+### Important: prefer the package root, not just the extension entrypoint
 
-| Tool | Purpose |
-|---|---|
-| `supi_tndm_cli` | Thin wrapper around the `tndm` CLI with action enum (create/update/show/list/awareness) |
-| `supi_flow_start` | Create a ticket with status=todo, tag=flow:brainstorm, and optional design context in `content.md` |
-| `supi_flow_plan` | Store the executable implementation plan in `plan.md` while leaving `content.md` as the approved design summary |
-| `supi_flow_complete_task` | Check off a numbered task (`**Task N**`) in the registered `plan` document |
-| `supi_flow_close` | Mark done and write verification results to `archive.md` |
+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.
 
-Tools should be used instead of calling `tndm` via bash. The agent invokes them with structured parameters.
+Use the **package root** when you want the full package:
 
-## Ticket documents
+- extension tools
+- auto-discovered skills
+- auto-discovered prompt template
 
-`supi-flow` uses TNDM's registered document model with one canonical ticket body and two phase-specific attachments:
+### Dependency: `tndm`
 
-- `content.md`: approved design summary and durable handoff context
-- `plan.md`: executable checklist used during `/supi-flow-apply`
-- `archive.md`: final verification evidence written during `/supi-flow-archive`
+`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.
 
-Older tickets may still contain a legacy brainstorm sidecar document, but new flow work should not create or depend on it.
+See the tandem project README for CLI install options:
+<https://github.com/mrclrchtr/tandem>
 
-## Prompt templates
+## How you use it in PI
 
-| Prompt | Description |
-|---|---|
-| `/supi-coding-retro` | Retrospective on project setup, architecture, tooling, workflows, and conventions |
+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
+   - 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
 
-## Ticket flow phase tracking
+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 map to TNDM statuses and tags:
+## 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, 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` |
 
-## Dependencies
+## Ticket document model
 
-- **tndm CLI** (`tandem-cli`): required (all ticket operations shell out to `tndm`)
+`supi-flow` uses tandem's registered document model with an overview-first workflow:
 
-  ```sh
-  brew install mrclrchtr/tap/tandem-cli
-  ```
+| Artifact | Role |
+|---|---|
+| `content.md` | Canonical approved overview / design / plan prose |
+| `state.toml` tasks | Structured execution manifest used during apply |
+| `tasks/task-XX.md` | Optional task detail attachment for tasks that need more than a headline/files/verification/notes |
+| `archive.md` | Final verification evidence written during archive/closeout |
 
-- **pi**: discovers bundled skills and prompt templates automatically from the package
+Key rules from the current implementation:
 
-## PI package
+- `content.md` is **overview-first** and may contain zero tasks.
+- Executable tasks live in `state.toml`, not in checklist blocks parsed from markdown.
+- Headline-only tasks are preferred when they are clear enough.
+- 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.
+- Task detail docs are optional and attached only when a task needs extra implementation detail.
+- Older tickets may still contain a legacy brainstorm sidecar document, but new flow work should not depend on it.
 
-This extension is published as a [`pi-package`](https://pi.dev/packages) — listed in the PI package gallery. Install directly:
+## Tools
 
-```bash
-pi install npm:@mrclrchtr/supi-flow
-```
+The extension registers seven custom tools.
 
-## Installation
+| 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`, and preserves the current `in_progress` or `blocked` status for already-applying tickets |
+| `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` |
 
-The extension is auto-discovered when the plugin directory is in pi's extension search path:
+### `supi_tndm_cli` at a glance
 
-```bash
-# Option 1: symlink
-ln -s "$(pwd)/plugins/supi-flow" ~/.pi/agent/extensions/supi-flow
+`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:
+
+- `task_add` can stay manifest-only for headline tasks
+- when `task_detail` is provided, the tool ensures the canonical task detail doc, writes the markdown body, and runs `tndm ticket sync`
+- `task_edit` can also write or clear linked 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 |
 
-# Option 2: settings.json
-# Add to ~/.pi/agent/settings.json:
-# { "extensions": ["./plugins/supi-flow/extensions/index.ts"] }
+## Prompt template
+
+| Prompt | Purpose |
+|---|---|
+| `/supi-coding-retro` | Retrospective on setup, architecture, tooling, workflow, and conventions |
+
+## Package layout
+
+```text
+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
@@ -170,6 +249,29 @@ pnpm install
 # Type-check
 pnpm exec tsc --noEmit
 
-# Run tests
+# Run the full test suite
 pnpm exec vitest run
 ```
+
+Useful targeted checks from the current package guidance:
+
+```bash
+# 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.

package/extensions/index.ts

@@ -1,17 +1,21 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ToolExecutionMode } from "@earendil-works/pi-coding-agent";
 
 import { tndmVersion } from "./cli.js";
 import { supi_tndm_cli_params, executeTndmCli } from "./tools/tndm-cli.js";
 import {
   supiFlowStartParams,
   supiFlowPlanParams,
+  supiFlowApplyParams,
+  supiFlowTaskParams,
   supiFlowCompleteTaskParams,
   supiFlowCloseParams,
   executeFlowStart,
   executeFlowPlan,
+  executeFlowApply,
+  executeFlowTask,
   executeFlowCompleteTask,
   executeFlowClose,
 } from "./tools/flow-tools.js";
@@ -56,7 +60,13 @@ export default function (pi: ExtensionAPI) {
       "- update: id (required), title, status, priority, type, tags, add_tags, remove_tags, depends_on, effort, content\n" +
       "- show: id (required)\n" +
       "- list: all (boolean), definition (ready|questions|unknown)\n" +
-      "- awareness: against (git ref, required)",
+      "- awareness: against (git ref, required)\n" +
+      "- task_add: id (required), task_title (required), task_files, task_verification, task_notes, task_detail\n" +
+      "- task_list: id (required)\n" +
+      "- task_complete: id (required), task_number (required)\n" +
+      "- task_remove: id (required), task_number (required)\n" +
+      "- task_edit: id (required), task_number (required), task_title, task_files, task_clear_files, task_verification, task_notes, task_detail, task_clear_detail\n" +
+      "- task_set: id (required), task_json (required)",
     promptSnippet: "Execute tndm ticket operations via supi_tndm_cli",
     promptGuidelines: [
       "Use supi_tndm_cli for direct tndm operations instead of running tndm via bash",
@@ -76,9 +86,10 @@ export default function (pi: ExtensionAPI) {
       "Stores known design context in content.md and returns the ticket ID.",
     promptSnippet: "Begin a new flow by creating a TNDM ticket",
     promptGuidelines: [
-      "Use supi_flow_start at the beginning of every brainstorm to create the required ticket",
+      "Use supi_flow_start when a brainstorm becomes non-trivial and needs a durable ticket",
       "Always include context (design intent/summary) when known",
     ],
+    executionMode: "sequential" as ToolExecutionMode,
     parameters: supiFlowStartParams,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       return executeFlowStart(params);
@@ -90,31 +101,70 @@ export default function (pi: ExtensionAPI) {
     name: "supi_flow_plan",
     label: "Flow Plan",
     description:
-      "Store an implementation plan in a ticket's plan.md while keeping content.md as the canonical design summary. " +
-      "Updates tags from flow:brainstorm to flow:planned. Tasks must be numbered as '**Task {N}**' in the plan.",
+      "Store the approved overview / plan in the ticket's canonical content.md. " +
+      "Updates tags from flow:brainstorm to flow:planned. Task authoring happens separately in state.toml.",
     promptSnippet: "Store a plan in a TNDM ticket",
     promptGuidelines: [
-      "Use supi_flow_plan after creating a plan to persist it in the ticket",
-      "Number tasks sequentially as **Task 1**, **Task 2**, etc.",
+      "Use supi_flow_plan after creating a plan to persist the approved overview in content.md",
+      "Create execution tasks separately after the overview exists; do not rely on supi_flow_plan to parse task blocks into state.toml",
     ],
+    executionMode: "sequential" as ToolExecutionMode,
     parameters: supiFlowPlanParams,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       return executeFlowPlan(params);
     },
   });
 
+  // ── Tool: supi_flow_apply ───────────────────────────────────
+  pi.registerTool({
+    name: "supi_flow_apply",
+    label: "Flow Apply",
+    description:
+      "Start the apply phase for a planned ticket. " +
+      "Loads the approved content.md overview, returns the structured task manifest, transitions flow:planned tickets to status=in_progress with flow:applying, and preserves the current in_progress/blocked status for already-applying tickets.",
+    promptSnippet: "Start the apply phase for a TNDM flow ticket",
+    promptGuidelines: [
+      "Use supi_flow_apply at the beginning of implementation to load the approved overview and task manifest, and to move a planned ticket into flow:applying when needed.",
+    ],
+    executionMode: "sequential" as ToolExecutionMode,
+    parameters: supiFlowApplyParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeFlowApply(params);
+    },
+  });
+
+  // ── Tool: supi_flow_task ────────────────────────────────────
+  pi.registerTool({
+    name: "supi_flow_task",
+    label: "Flow Task",
+    description:
+      "Manage one structured task in a flow ticket. " +
+      "Operation determines which params apply: add requires title; edit/remove require task_number; optional detail writes or clears the canonical task detail doc.",
+    promptSnippet: "Manage one task at a time in a TNDM flow ticket",
+    promptGuidelines: [
+      "Use supi_flow_task for the common plan-time path to add, edit, or remove one structured task at a time",
+      "Prefer supi_flow_task over raw task_json or detail_path handling when authoring normal flow tasks",
+    ],
+    executionMode: "sequential" as ToolExecutionMode,
+    parameters: supiFlowTaskParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeFlowTask(params);
+    },
+  });
+
   // ── Tool: supi_flow_complete_task ───────────────────────────
   pi.registerTool({
     name: "supi_flow_complete_task",
     label: "Flow Complete Task",
     description:
-      "Mark a task as done in a ticket's plan.md by task number (1-based). " +
-      "Finds '- [ ] **Task N:**' and changes to '- [x] **Task N:**'.",
+      "Mark a task as done in a ticket by task number (1-based). " +
+      "Calls 'tndm ticket task complete' to update the structured task in state.toml.",
     promptSnippet: "Check off a completed plan task in a TNDM ticket",
     promptGuidelines: [
       "Use supi_flow_complete_task after each task's verification passes during apply",
       "Call this with the task number, not the description text",
     ],
+    executionMode: "sequential" as ToolExecutionMode,
     parameters: supiFlowCompleteTaskParams,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       return executeFlowCompleteTask(params);
@@ -127,12 +177,13 @@ export default function (pi: ExtensionAPI) {
     label: "Flow Close",
     description:
       "Close a ticket and finalize the flow. " +
-      "Writes verification results to archive.md, sets status=done, and tags=flow:done.",
+      "Requires flow:applying with a non-empty all-done task list, writes verification results to archive.md, sets status=done, and tags=flow:done.",
     promptSnippet: "Close a TNDM ticket after implementation and verification",
     promptGuidelines: [
       "Use supi_flow_close at the end of the archive phase after all verification is complete",
       "Pass the full verification evidence as verification_results",
     ],
+    executionMode: "sequential" as ToolExecutionMode,
     parameters: supiFlowCloseParams,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       return executeFlowClose(params);