@locksmithdon/dons-flow 2.0.0

package/skills/setup-dons-flow/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: setup-dons-flow
+description: Use when installing or onboarding @locksmithdon/dons-flow in a repo — checks dependencies, detects Superpowers, and creates repo conventions
+---
+
+# Setup Don's Flow
+
+Onboard a repo to the integrated RPIV + Superpowers + `land` workflow. This skill checks prerequisites, detects what is already installed, creates the repo-owned conventions, and tells you what still needs to be done.
+
+## Announce at start
+
+> "I'm using the `setup-dons-flow` skill to onboard this repo to the integrated workflow."
+
+## When to use
+
+- Right after installing `@locksmithdon/dons-flow` in a repo.
+- When you suspect prerequisites are missing.
+- When setting up a fresh repo for this workflow.
+
+## Process
+
+### Step 1: Detect installed Pi packages
+
+Run:
+
+```bash
+pi list
+```
+
+Look for:
+
+| Package | Required? | If missing |
+|---|---|---|
+| `npm:@juicesharp/rpiv-pi` | Yes | `pi install npm:@juicesharp/rpiv-pi` |
+| `npm:@tintinweb/pi-subagents` | Yes | `pi install npm:@tintinweb/pi-subagents` |
+| `npm:@locksmithdon/dons-flow` | Yes | `pi install npm:@locksmithdon/dons-flow` |
+
+If RPIV is installed, also run `/rpiv-setup` once and restart Pi to install RPIV's sibling plugins.
+
+### Step 2: Detect Superpowers
+
+Superpowers is installed via your agent harness, not as a Pi npm package. Check one of:
+
+- **Claude Code:** `/plugin list` should show `superpowers`
+- **Codex CLI:** `/plugins` should list Superpowers
+- **Gemini CLI:** `gemini extensions list` should show it
+- **Skills directory:** `ls ~/.pi/agent/skills/` may contain Superpowers skills if they were copied manually
+
+If Superpowers is not installed, ask the user which path they prefer:
+
+1. **Harness plugin** (recommended for most users)
+2. **Git URL** — `pi install github:obra/superpowers` if their Pi supports git URLs
+3. **Skip for now** — the closeout workflow still works without Superpowers entry points
+
+Record the choice in `docs/memory/MEMORY.md` if this is a long-lived project.
+
+### Step 3: Check repo conventions
+
+Check whether these project-owned files and folders exist:
+
+```bash
+ls docs/tabled.md docs/status.md docs/memory/MEMORY.md docs/changes docs/retros docs/runbooks AGENTS.md 2>/dev/null
+```
+
+Expected:
+
+| Path | Purpose |
+|---|---|
+| `docs/tabled.md` | Working memory for deferred ideas |
+| `docs/tabled/` | Optional per-item tabled docs |
+| `docs/status.md` | Living status |
+| `docs/memory/` | Persistent memory + `MEMORY.md` index |
+| `docs/changes/` | As-built documentation |
+| `docs/retros/` | Frozen retrospectives |
+| `docs/runbooks/` | Multi-skill processes |
+| `AGENTS.md` | Repo-level agent guidance |
+
+### Step 4: Create missing conventions
+
+If the user approves, create missing conventions:
+
+```bash
+mkdir -p docs/{tabled,memory,changes,retros,runbooks}
+touch docs/tabled.md docs/status.md docs/memory/MEMORY.md AGENTS.md
+```
+
+Seed `docs/status.md` with:
+
+```markdown
+# Status
+
+## Active Work
+
+- Onboarding `@locksmithdon/dons-flow`
+
+## Recently Completed
+
+_None yet._
+
+## What's Next
+
+_None yet._
+```
+
+Seed `docs/memory/MEMORY.md` with:
+
+```markdown
+# Memory Index
+
+Cross-session context for this project.
+
+## Entries
+
+_None yet._
+```
+
+Seed `AGENTS.md` with a minimal entry pointing at this workflow:
+
+```markdown
+# AGENTS.md
+
+This project uses the `@locksmithdon/dons-flow` workflow:
+- RPIV pipeline for discovery, research, design/plan, implement, validate, review, commit.
+- Superpowers-style scope control and verification discipline.
+- `land` skill for 10-step cycle closeout.
+
+See `docs/runbooks/` for detailed processes and `docs/memory/` for project context.
+```
+
+### Step 5: Report status and next steps
+
+Present a concise summary:
+
+```
+Setup status for <repo>:
+
+✓ RPIV installed
+✗ @tintinweb/pi-subagents missing — run: pi install npm:@tintinweb/pi-subagents
+✓ Repo conventions created
+? Superpowers — not detected; install via harness plugin if desired
+
+Next step: /skill:dons-flow to see the workflow map.
+```
+
+## Anti-patterns
+
+- **Creating conventions without asking.** The repo belongs to the team; don't mutate its doc structure unilaterally.
+- **Assuming Superpowers is installed.** It is optional and harness-specific. Always detect or ask.
+- **Installing packages without confirmation.** Present the install commands; let the human run them.
+
+## Integration
+
+- Called automatically on first install if an extension hook is added later.
+- Should be re-run after major RPIV or Superpowers updates to refresh conventions.

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check CLAUDE.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no CLAUDE.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.pi/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Per Jesse's rule "Fix broken things immediately":
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.pi/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.pi/worktrees/*)
+    path="~/.pi/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check CLAUDE.md → Ask user |
+| Directory not ignored | Add to .gitignore + commit |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > CLAUDE.md > ask
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Hardcoding setup commands
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip CLAUDE.md check
+
+**Always:**
+- Follow directory priority: existing > CLAUDE.md > ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+- **dons-flow** — recommended before `/skill:implement` when working on a feature branch
+- **any skill needing an isolated workspace**
+
+**Also pairs with:**
+- RPIV `/skill:implement` — use a worktree for long-running or multi-phase implementation
+- RPIV `/skill:blueprint` or `/skill:plan` — set up the worktree after the plan is ready
+
+**Pairs with:**
+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/skills/writing-retros/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: writing-retros
+description: Use at milestone close to produce a retrospective — four-section format (keep doing / stop or change / promote to artifact / commit to memory) with concrete, owned action items
+---
+
+# Writing Retros
+
+## Overview
+
+A retrospective at milestone close is the culmination of continuous reflection, not a replacement for it. Tabled entries have been processed throughout execution; end-of-artifact checkpoints have fed back into the next artifact. The retro captures what the milestone *as a whole* teaches us, and converts it into concrete, owned action items.
+
+**Announce at start:** "I'm using the writing-retros skill to produce the retro for `<milestone>`."
+
+## Output
+
+One file: `docs/retros/YYYY-MM-DD-<milestone>.md`. **Frozen at commit.** Future amendments go into a new retro, not this one — inline edits to a retro erode its value as an episodic record.
+
+## The four sections
+
+Every retro has exactly these sections, in this order:
+
+1. **Keep doing.** What worked and should continue. Name the practice, not just the outcome. ("Epiphany-tabling to `tabled.md`" is actionable; "M1 went well" is not.)
+2. **Stop or change.** What did not work and should adjust. Be specific about the pain and the proposed change.
+3. **Promote to artifact.** Patterns worth extracting into skills, runbooks, scripts, memory entries, or as-built sections. Cross-reference the **promotion rule** (see `capturing-learnings`) — each item here should have at least one prior sighting the retro can point at.
+4. **Commit to memory.** What, if anything, belongs in the cross-conversation memory system at `docs/memory/`. Often a subset of §3; sometimes its own distinct item. Announce writes (see AGENTS.md).
+
+Optional lightweight sections at the end (appendix-style): headline stats, acknowledgements, historical context. Keep them short.
+
+## Action items
+
+Every retro ends with **concrete, owned action items** — not essays. Each item has:
+
+- A specific outcome (a file to change, an artifact to create, a decision to make).
+- An owner (a session, a date, a person) — or an explicit "by next milestone."
+- Enough context for someone who didn't run the retro to execute the item.
+
+If the action-item list is large enough to risk the retro becoming a working document rather than an episodic record, **split the execution into a separate closeout doc** (e.g., `docs/m1-closeout.md`) and reference it from §5. The retro stays frozen; the closeout doc is the working artifact.
+
+## Process
+
+1. **Gather inputs.**
+   - `docs/tabled.md` — every entry is a candidate for one of the four sections or for processing during retro review.
+   - The as-built (if already drafted) or the spec + plan + git log (if not).
+   - Memory writes made during the milestone.
+   - Any explicit "save this for retro" notes from the user during execution.
+
+2. **Draft top-to-bottom.** Short, specific bullets under each section. Avoid the urge to write prose paragraphs — retros are scannable lists.
+
+3. **Review with the user before committing.** Retros are frozen at commit, so the review *must* happen first. Expect the user to expand the action-item set — that is normal; the retro is a conversation starter, not a monologue.
+
+4. **Commit.** One file, one commit. After this point, do **not** rewrite the retro inline; if paths or references later need updating, add a note at the top and point at the source of truth.
+
+## Common failure modes
+
+- **Meta-theater.** Reflection that produces more reflection rather than better work. If a section has no concrete output, either it does not belong in the retro or the work to produce the output hasn't happened. Name the missing action item; don't paper over it.
+- **Silent drift.** Practices on paper diverging from practices in use. The retro only catches this if honest — don't smooth over what went wrong.
+- **Stale references.** A frozen retro loses value when the paths it references move. Either update the paths at the close *before* commit, or add a dated note at the top after commit — never rewrite inline.
+- **Undifferentiated "stop or change."** Generic complaints without a proposed change aren't retro content. If you can't name what to try differently, that's a candidate for §3 "promote to artifact" or for a deliberate drop.
+
+## Related practices
+
+- `capturing-learnings` — promotion rule; how §3 items become skills/runbooks/memory.
+- `epiphany-tabling` — the in-flight practice that feeds retro content.
+- `as-built-documentation` — the permanent record of what shipped (retros and as-builts are complementary: retros capture *how* we worked; as-builts capture *what* we built).