@mrclrchtr/supi-flow 0.6.1

package/README.md

@@ -0,0 +1,175 @@
+# 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
+         Slop-scan docs
+         Quality gate checklist"]
+    ARCHIVE --> SLOP["/skill:supi-flow-slop-detect
+         Tier 1-4 vocabulary
+         11 structural patterns
+         Score target: < 1.5"]
+    SLOP --> QGATE{"Quality gate
+         passes?"}
+    QGATE -->|"No"| SLOP
+    QGATE -->|"Yes"| CLOSE
+
+    CLOSE["supi_flow_close
+         Sets status=done, flow:done
+         Auto-commits .tndm/"]
+
+    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
+```
+
+Non-trivial flows require a TNDM ticket created by `supi_flow_start`. Trivial changes can be implemented directly without a ticket.
+
+## Skills
+
+Six skills ship under `skills/`:
+
+| 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 |
+| `supi-flow-slop-detect` | Loaded on demand during archive | AI-prose detection in docs |
+
+## Tools
+
+Five custom tools registered by the extension:
+
+| 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, write verification results to `archive.md`, and auto-commit `.tndm/` |
+
+Tools should be used instead of calling `tndm` via bash. The agent invokes them with structured parameters.
+
+## Ticket documents
+
+`supi-flow` uses TNDM's registered document model with one canonical ticket body and two phase-specific attachments:
+
+- `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`
+
+Older tickets may still contain a legacy brainstorm sidecar document, but new flow work should not create or depend on it.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/supi-flow` | List available flow commands |
+| `/supi-flow-status` | Query TNDM for active flow tickets and show the next recommended step |
+
+## Prompt templates
+
+| Prompt | Description |
+|---|---|
+| `/supi-coding-retro` | Retrospective on project setup, architecture, tooling, workflows, and conventions |
+
+## Ticket flow phase tracking
+
+Flow phases map to TNDM statuses and tags:
+
+| Flow phase | Status | Tags |
+|---|---|---|
+| Brainstorm | `todo` | `flow:brainstorm` |
+| Plan written | `todo` | `flow:planned` |
+| Implementing | `in_progress` | `flow:applying` |
+| Done | `done` | `flow:done` |
+
+## Dependencies
+
+- **tndm CLI**: required (all ticket operations shell out to `tndm`)
+- **pi**: discovers bundled skills and prompt templates automatically from the package
+
+## Installation
+
+The extension is auto-discovered when the plugin directory is in pi's extension search path:
+
+```bash
+# Option 1: symlink
+ln -s "$(pwd)/plugins/supi-flow" ~/.pi/agent/extensions/supi-flow
+
+# Option 2: settings.json
+# Add to ~/.pi/agent/settings.json:
+# { "extensions": ["./plugins/supi-flow/src/index.ts"] }
+```
+
+## Development
+
+```bash
+cd plugins/supi-flow
+pnpm install
+
+# Type-check
+pnpm exec tsc --noEmit
+
+# Run tests
+pnpm exec vitest run
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mrclrchtr/supi-flow",
+  "version": "0.6.1",
+  "private": false,
+  "description": "SuPi flow extension — spec-driven workflow coupled to TNDM ticket coordination",
+  "license": "Apache-2.0",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "main": "src/index.ts",
+  "dependencies": {
+    "typebox": "^1.1.38"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "prompts/",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^25.6.0",
+    "vitest": "^4.1.4"
+  }
+}

package/prompts/supi-coding-retro.md

@@ -0,0 +1,18 @@
+---
+description: Agent retrospective on project setup, architecture, tooling, and workflows
+---
+
+Agent Retrospective — Project Setup & Tooling
+
+While implementing this feature, what aspects of the project setup, architecture, tooling, workflows, or conventions made development harder than necessary?
+
+Please specifically identify:
+- sources of friction or unnecessary complexity
+- confusing or inconsistent patterns
+- tooling or processes that slowed implementation
+- over-engineered abstractions
+- repetitive manual work that could be automated
+- missing documentation, scripts, or conventions
+- anything that should be simplified, standardized, or removed
+
+Focus on concrete examples and practical improvements that would increase implementation speed, reliability, and developer/agent experience for future work.

package/skills/supi-flow-apply/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: supi-flow-apply
+description: Execute an approved implementation plan task by task — verify each step fresh, stop when blocked, and ask instead of guessing.
+---
+
+# Execute implementation plan
+
+## The Iron Law
+
+```
+EVERY TASK GETS FRESH VERIFICATION BEFORE MARKING DONE
+```
+
+If you haven't run the verification command for this task, you cannot check it off. Previous runs do not count. "Should pass" is not evidence.
+
+## Step 1: Find the plan
+
+- A TNDM-ID was set during plan phase. Read the ticket metadata first:
+  `supi_tndm_cli { action: "show", id: "<ID>" }` — find the registered `plan` document path, then read `plan.md` from that path.
+  Then mark the ticket as in progress and move the flow tag:
+  `supi_tndm_cli { action: "update", id: "<ID>", status: "in_progress", add_tags: "flow:applying", remove_tags: "flow:planned" }`
+- If no plan is available: ask which change to implement.
+
+## Step 2: Review the plan critically
+
+Read the whole plan before starting.
+
+Raise questions before editing if:
+
+- the plan has a gap
+- the instructions are unclear
+- the scope changed
+- a task is missing verification
+- you are unsure whether a task should be test-driven or test-exempt
+
+Do not start implementation until those concerns are resolved.
+
+## Step 3: Execute tasks
+
+For each unchecked task, in order:
+
+1. Announce which task you are working on.
+2. Follow the task as written.
+3. Run the verification for that task and read the result carefully.
+4. If verification passes: call `supi_flow_complete_task { ticket_id: "<ID>", task_number: <N> }` to check the task off in the ticket.
+5. If verification fails: stop, diagnose, fix, and re-verify before moving on.
+6. Record what actually passed.
+
+Do not skip failed checks. Do not collapse several tasks into one vague batch.
+
+### TDD by default, not always
+
+For tasks that involve writing code, prefer TDD when the code is reasonably testable.
+
+```text
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Default flow:
+
+1. Write the test.
+2. Run it and confirm it fails for the right reason.
+3. Write the minimal code to make it pass.
+4. Re-run the test and confirm it passes.
+5. Run any broader regression checks the plan calls for.
+
+### Test-exempt work
+
+If the task is marked test-exempt in the plan, or the work is clearly not practical to drive with TDD, use manual verification instead.
+
+Examples:
+
+- docs-only edits
+- config-only edits
+- trivial changes
+- shell or integration work with no reasonable harness
+
+For test-exempt work:
+
+1. Run the manual verification step from the plan.
+2. If the plan omitted one, add the smallest concrete verification you can justify.
+3. Confirm the actual output matches the claim.
+4. Note the exemption rationale briefly when you report completion.
+
+If you are **uncertain** whether TDD is practical, ask the user instead of guessing.
+
+The hard rule is not "TDD in every case." The hard rule is: **no unverified changes**.
+
+## Step 4: When blocked, load systematic debugging
+
+If verification fails and you do not understand why, load `/skill:supi-flow-debug` and follow it before attempting random fixes.
+
+## When to stop and ask
+
+STOP and ask the user when:
+
+- a verification fails repeatedly and you still do not understand the cause
+- you have tried 3 fixes and none worked
+- a dependency is missing
+- the plan has a critical gap
+- an instruction is unclear
+- you are unsure whether a task should use TDD or a test exemption
+
+Do not guess. Do not force through blockers.
+
+## Rationalization prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should pass now" | Run the verification again. Fresh. |
+| "I'm confident" | Confidence is not evidence. |
+| "Just this once" | Verification still applies. |
+| "Previous run passed" | Code changed. Run it again. |
+| "This task is too simple to need TDD" | TDD is preferred for testable code. If it is not practical, verify it manually and say why. |
+
+## When all tasks are done
+
+- If a ticket exists: summarize what passed in conversation, but do not mark it done yet — `/supi-flow-archive` handles durable verification evidence in `archive.md` and final closeout.
+- Announce: `Implementation complete. Run /supi-flow-archive TNDM-XXXXXX to verify, update docs, and close out.`

package/skills/supi-flow-archive/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: supi-flow-archive
+description: Verify implementation against the plan, update living documentation, run slop detection, and close out the change.
+---
+
+# Archive and document
+
+Use this after `/supi-flow-apply` when implementation is complete. This is a docs-first closeout step, not a repository-cleanup workflow.
+
+## The Iron Law
+
+```text
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+Before claiming the change is done, the docs are accurate, or the ticket can be closed: run the proof fresh, read the result, and check the exit status.
+
+## Step 1: Find the change
+
+- A TNDM-ID was set during plan phase. Read the ticket metadata first:
+  `supi_tndm_cli { action: "show", id: "<ID>" }` — inspect `content_path` and the registered documents, then read `content.md` for the approved design and `plan.md` for the executed checklist.
+- Archive runs only when a ticket exists. Trivial flows that skipped the ticket close out directly in conversation — do not run archive.
+- If nothing is clear: ask which change to archive.
+
+## Step 2: Verify completion
+
+Compare the plan against what was actually done. Fresh checks only.
+
+- [ ] Every planned task is complete, or any deviation is explained.
+- [ ] Tests and verification commands were run fresh.
+- [ ] The implemented result still matches the approved intent.
+- [ ] Any claimed manual verification was actually performed.
+
+If any check fails, stop and fix that first.
+
+### Verification gate
+
+```text
+1. Identify the command or evidence that proves the claim.
+2. Run it fresh.
+3. Read the full result and exit code.
+4. Confirm the claim matches the evidence.
+5. Only then report success.
+```
+
+## Step 3: Update living documentation
+
+Update docs only where the change actually affects them.
+
+1. Review `git diff` to understand the real delta.
+2. Identify the docs that should change.
+3. Update them with grounded, specific language.
+4. Reference actual file paths, commands, settings, or behavior when helpful.
+
+## Step 4: Run slop detection
+
+Load `/skill:supi-flow-slop-detect` and scan every edited documentation file.
+
+Quality checks:
+
+- no tier-1 slop words in edited docs
+- claims are grounded in specifics
+- wording is direct, not formulaic
+- AI-sycophantic filler is removed
+- the slop score is acceptable
+
+If the scan fails, fix the docs and re-scan.
+
+## Step 5: Verify doc accuracy
+
+Do the docs match the actual code and workflow?
+
+- check file paths
+- check command names
+- check settings or behavior descriptions
+- check that new guidance matches the final implementation
+
+Do not assume documentation is correct just because it sounds right.
+
+## Step 6: Close out
+
+- Call `supi_flow_close { ticket_id: "<ID>", verification_results: "..." }` with the full verification evidence.
+  This will set status=done, tags=flow:done, store verification results in archive.md, and auto-commit .tndm/ changes.
+- There is no ticket-less closeout.
+
+## Step 7: Verify commit
+
+Check that the `.tndm/` changes were committed. If `supi_flow_close` did not commit (e.g. no changes to commit), commit any remaining doc changes manually:
+
+```sh
+git commit -m "docs: archive TNDM-XXXXXX"
+```
+
+## Red flags
+
+Stop if you catch yourself:
+
+- claiming success from an old test run
+- saying "should" or "probably" instead of citing evidence
+- updating docs before confirming the implementation
+- treating this as a repository cleanup workflow instead of a verification-and-docs closeout

package/skills/supi-flow-brainstorm/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: supi-flow-brainstorm
+description: You MUST use this before any implementation. Clarify intent, shape the design, and get approval before touching code.
+---
+
+# Flow Brainstorm
+
+Turn an idea into an approved design through focused collaboration. Default to a lightweight conversation. Add more structure only when the change is larger, riskier, or likely to span sessions.
+
+<HARD-GATE>
+Do NOT write code, scaffold anything, or take implementation action until you have presented a design and the user has approved it. This applies even to changes that seem simple.
+</HARD-GATE>
+
+## Core flow
+
+1. **Explore context:** check relevant files, docs, recent commits, and existing tickets.
+2. **Check scope:** if the request really contains multiple independent changes, decompose it before going deeper.
+3. **Ask clarifying questions:** one at a time. Focus on purpose, constraints, and success criteria.
+4. **Propose 2-3 approaches:** include trade-offs and a recommendation.
+5. **Present the design:** scale detail to complexity and get approval.
+6. **Classify and decide:** propose whether this change is trivial or non-trivial.
+   - **Trivial:** single file, no tests/docs needed, one verification step, or user says "just do it".
+     → "This looks trivial — skip ticket and implement directly?"
+     If user agrees: implement directly, verify, done. No ticket.
+   - **Non-trivial:** multi-file, needs tests or docs, multi-step, or likely multi-session.
+     → Call `supi_flow_start` to create a TNDM ticket, then store the approved design in `content.md` via `supi_tndm_cli { action: "update", id: "<ID>", content: "<outcome>" }`.
+7. **Recommend next step:**
+   - If trivial: implement directly by following the approved design.
+   - If non-trivial: `/supi-flow-plan <ID>`
+
+## Understanding the idea
+
+- Check the current project state first. Follow existing patterns before proposing new ones.
+- Assess scope early. If the user is really asking for several subsystems, say so and help break the work into smaller changes.
+- Ask one question per message. Multiple choice is great when it makes the decision easier.
+- Keep refining until you understand the goal, non-goals, constraints, and what success looks like.
+
+## Visual Companion
+
+If upcoming questions would be easier with mockups, diagrams, or visual comparisons, offer a visual companion once:
+
+> "Some of what we're working on could be easier to explain if I can show it to you visually. I can put together mockups, diagrams, comparisons, and other visuals as we go. Want to try it?"
+
+That offer MUST be its own message. Do not combine it with any other content. If the user declines, continue in text.
+
+Even if they accept, use visuals only when seeing the idea would help more than reading it.
+
+## Exploring approaches
+
+- Propose 2-3 approaches with trade-offs.
+- Lead with your recommendation and say why.
+- Prefer simple, well-bounded designs over sprawling ones.
+
+## Presenting the design
+
+Cover the parts that matter for the change, such as:
+
+- approach
+- main components or files
+- data flow or control flow
+- edge cases and error handling
+- testing and verification
+- docs to update, if any
+
+Keep each section proportional to the complexity. A small change may only need a few sentences.
+
+## Working in existing codebases
+
+- Follow established patterns unless there is a strong reason not to.
+- Include targeted cleanup when it directly helps the work.
+- Do not propose unrelated refactors.
+
+## Persistence and tracking
+
+After approval:
+
+- **Default to conversation-first.** The design can live in the chat for small, single-session work.
+- **Offer saving to a ticket** when the work is larger, likely multi-session, or would benefit from a durable reference.
+- If a ticket exists, save the design to the ticket's canonical `content.md` via `supi_tndm_cli { action: "update", id: "<ID>", content: "<outcome>" }`.
+- **Retroactive escalation:** if a trivial change grows in scope mid-implementation, stop, create a retroactive ticket via `supi_flow_start`, and store a summary of completed work + new scope.
+
+## Self-review
+
+Before handing off:
+
+1. Remove placeholders or vague wording.
+2. Check for contradictions.
+3. Make sure the scope still fits a single implementation plan.
+4. Make ambiguous requirements explicit.
+
+Fix issues inline, then continue.
+
+## Handoff
+
+Present the outcome in a compact form:
+
+```markdown
+## Brainstorming Outcome
+**Problem**: ...
+**Recommended approach**: ...
+**Why**: ...
+**Constraints / non-goals**: ...
+**Open questions**: ...
+**Ticket**: TNDM-XXXXXX / none
+```
+
+Then recommend:
+- If non-trivial: `/supi-flow-plan TNDM-XXXXXX`
+- If trivial: proceed with direct implementation
+
+## Key principles
+
+- One question at a time
+- Explore alternatives before settling
+- Scale rigor to risk
+- Default to lightweight collaboration
+- Keep the design clear enough to implement without guessing