flow-cc 0.1.0

package/skills/flow-init.md

@@ -0,0 +1,218 @@
+---
+name: flow:init
+description: Initialize a new project or start a new milestone with planning scaffolding
+user_invocable: true
+---
+
+# /flow:init — Initialize Project or Milestone
+
+You are executing the `/flow:init` skill. This sets up the planning scaffolding for a new project or a new milestone within an existing project.
+
+## Mode Detection
+
+Check if `.planning/STATE.md` exists:
+- **If it does NOT exist** → New Project Mode
+- **If it exists** → New Milestone Mode
+
+---
+
+## New Project Mode
+
+### Step 1: Ask Setup Questions
+
+Use AskUserQuestion to gather project info. Ask these questions (you may combine into 2-3 AskUserQuestion calls):
+
+**Question 1 — Project basics:**
+- "What is this project?" (one sentence description)
+
+**Question 2 — Tech stack:**
+- "What's the tech stack?" with options like:
+  - "Next.js + TypeScript + PostgreSQL"
+  - "Python + FastAPI + PostgreSQL"
+  - "React + Node.js + MongoDB"
+  - (Other — user types custom)
+
+**Question 3 — Verification commands:**
+- "What commands verify the build?" with options like:
+  - "npx tsc --noEmit && npx biome check"
+  - "pytest && mypy ."
+  - "cargo build && cargo test"
+  - (Other — user types custom)
+
+**Question 4 — First milestone:**
+- "What's the first milestone?" (name + one-sentence goal)
+
+**Question 5 — Brownfield scan:**
+- "Is this an existing codebase I should scan?" with options:
+  - "Yes — scan and catalog existing code"
+  - "No — greenfield project"
+
+### Step 2: Brownfield Scan (if requested)
+
+If the user said yes to scanning:
+1. Use Glob to find key directories: `src/`, `app/`, `lib/`, `components/`, `api/`, `pages/`, `utils/`, `types/`
+2. Use Grep to find patterns: exports, route definitions, database models, config files
+3. Build a brief catalog of what exists (key components, patterns, data layer)
+4. Include this in the CLAUDE.md Quick Context section
+
+### Step 3: Create Project Files
+
+Create these 5 files (create directories as needed):
+
+**`.planning/STATE.md`:**
+```
+# [Project Name] — Project State
+
+## Current Position
+- **Milestone:** [first milestone name] (v1)
+- **Phase:** Not started — run `/flow:spec` to build PRD
+- **Branch:** main
+- **Last Session:** [today's date]
+
+## Milestone Progress
+
+| Phase | Name | Status |
+|-------|------|--------|
+| — | Run `/flow:spec` to define phases | — |
+
+## What Was Built (This Session)
+- Project initialized with `/flow:init`
+- Created: CLAUDE.md, STATE.md, ROADMAP.md, tasks/lessons.md
+
+## Key Decisions
+- (none yet)
+
+## Next Actions
+1. Run `/flow:spec` to interview and generate PRD for [first milestone]
+```
+
+**`.planning/ROADMAP.md`:**
+```
+# [Project Name] — Roadmap
+
+## Milestones
+
+| Version | Milestone | Status | Phases |
+|---------|-----------|--------|--------|
+| v1 | [first milestone] | Pending — needs `/flow:spec` | TBD |
+
+---
+
+## v1: [first milestone]
+
+**Goal:** [milestone goal from user]
+
+**Phases:** Run `/flow:spec` to define implementation phases.
+```
+
+**`CLAUDE.md`:**
+```
+# [Project Name] — Claude Code Instructions
+
+## Quick Context
+[Project description from user]
+
+**Tech Stack:** [tech stack from user]
+[If brownfield: brief catalog of existing code]
+
+### START (Every Session)
+1. Read this file (CLAUDE.md)
+2. Read `.planning/STATE.md` for current status
+3. Read `.planning/ROADMAP.md` for milestone progress
+4. Read `PRD.md` for current execution spec (if one exists)
+
+## Execution Rules
+- **Plan before building.** For non-trivial work, read the PRD phase section before touching anything.
+- **Delegate immediately.** If a task touches 3+ files, spawn an agent team within your first 2 tool calls.
+- **Verify everything.** Run [verification commands from user] after agent work lands. Nothing is done until proven.
+
+## Git Workflow
+- All changes via PR. Never commit directly to main.
+- Branch naming: `fix/short-description` or `feat/short-description`
+
+## Session-End Docs (MANDATORY)
+1. `.planning/STATE.md` — replace session notes (don't append), keep <80 lines
+2. `.planning/ROADMAP.md` — update phase progress
+3. `tasks/lessons.md` — add new lessons, refine existing ones
+4. Commit doc updates to feature branch
+
+## Critical Rules
+- No assumptions — ask if requirements unclear
+- Fight entropy — leave code better than you found it
+```
+
+**`tasks/lessons.md`:**
+```
+# [Project Name] — Lessons Learned
+
+Format: PATTERN → CAUSE → FIX → RULE
+
+## Execution Patterns
+<!-- Lessons about workflow, delegation, verification -->
+
+## Domain Knowledge
+<!-- Lessons about business logic, data models, user behavior -->
+
+## Technical Patterns
+<!-- Lessons about the tech stack, libraries, deployment -->
+```
+
+**`.planning/archive/`** — Create this empty directory (use `mkdir -p` via Bash).
+
+### Step 4: Print Completion Message
+
+```
+Project initialized:
+- CLAUDE.md — project execution rules
+- .planning/STATE.md — session GPS
+- .planning/ROADMAP.md — milestone tracker
+- tasks/lessons.md — anti-pattern catalog
+- .planning/archive/ — for completed milestones
+
+Run `/flow:spec` to plan your first milestone.
+```
+
+---
+
+## New Milestone Mode
+
+### Step 1: Read Context
+
+Read `.planning/STATE.md` and `.planning/ROADMAP.md` to understand:
+- What milestone just completed (or is completing)
+- What version number to use next
+- Current state of the project
+
+### Step 2: Ask Milestone Question
+
+Use AskUserQuestion:
+- "What's the goal of this new milestone?" (free text)
+- "What should it be called?" (free text, or suggest a name based on context)
+
+### Step 3: Archive Completed Milestone
+
+1. Read current ROADMAP.md phase details for the completed milestone
+2. Write them to `.planning/archive/milestones-vX.md` (where X is the completed version)
+3. If `PRD.md` exists, move it to `.planning/archive/PRD-vX.md` (read it, write to archive, delete original)
+4. In ROADMAP.md, replace the completed milestone's phase details with just the summary row (mark as "Complete")
+
+### Step 4: Update Planning Docs
+
+**ROADMAP.md:**
+- Add new milestone row to the table
+- Add new milestone section with goal and "Run `/flow:spec` to define phases"
+
+**STATE.md:**
+- Replace with fresh state for the new milestone
+- Reset phase progress table
+- Note the milestone transition in "What Was Built"
+
+### Step 5: Print Completion Message
+
+```
+Milestone [name] (v[X]) initialized.
+- Archived: previous milestone details + PRD
+- Updated: ROADMAP.md, STATE.md
+
+Run `/flow:spec` to build the PRD for this milestone.
+```

package/skills/flow-intro.md

@@ -0,0 +1,92 @@
+---
+name: flow:intro
+description: Introduction to the Flow workflow system — shows all commands and how to use them
+user_invocable: true
+---
+
+# /flow:intro — Welcome to Flow
+
+You are executing the `/flow:intro` skill. Print the following guide EXACTLY as written. Do NOT modify any files. This is purely informational.
+
+Print this:
+
+---
+
+## Flow — Your Workflow System
+
+Flow is 5 commands that turn your specs into shipped code through agent teams. Each command feeds the next.
+
+### The Lifecycle
+
+```
+/flow:init → /flow:spec → /flow:go (repeat) → /flow:done
+                                                    ↓
+                                        handoff prompt for next session
+
+/flow:task ← standalone path for bug fixes, cleanup, small features (no PRD needed)
+```
+
+### Command by Command
+
+**`/flow:init`** — Run once per project (or once per new milestone)
+- New project: asks you 4-5 questions (what is it, tech stack, verify commands, first milestone)
+- Creates the scaffolding: `CLAUDE.md`, `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`
+- Existing project: archives the old milestone + PRD, sets up the next one
+
+**`/flow:task`** — Run anytime for small work
+- Bug fixes, cleanup, one-off features — anything that doesn't need a full PRD
+- Works standalone without `/flow:init` — lowest friction entry to Flow
+- Executes, verifies, commits, and logs to STATE.md (if it exists)
+- Scope guard recommends `/flow:spec` if the task grows beyond 5 files or 3 layers
+
+**`/flow:spec`** — Run once per milestone
+- Interviews you about scope, user stories, technical design, trade-offs, and phasing
+- You can say "done" or "that's enough" anytime to cut the interview short
+- Produces `PRD.md` — the execution contract with wave-based phases, file lists, and acceptance criteria
+- Updates ROADMAP and STATE to reflect the plan
+
+**`/flow:go`** — Run once per phase (this is where the work happens)
+- Reads the PRD, finds the next pending phase
+- Checks for staleness (did prior phases change things this phase references?)
+- Spawns agent teams per the wave structure in the PRD
+- Verifies after each wave, commits when done
+- Updates docs and prints "run `/flow:go` again for the next phase"
+
+**`/flow:done`** — Run at end of every session
+- Replaces STATE.md with current status
+- Updates ROADMAP.md with phase completions
+- Asks about lessons, refines existing ones
+- Commits doc updates
+- Generates a handoff prompt you copy-paste to start the next session
+
+**`/flow:status`** — Run anytime, read-only
+- Quick "where am I?" — milestone, phase progress, next step, lesson count
+
+**`/flow:update`** — Run anytime to update Flow
+- Pulls latest changes from the flow-plugin repo and re-installs all skills
+- No need to remember where you cloned the repo — it finds it automatically
+
+### Typical Session
+
+```
+1. Paste the handoff prompt from last session (or /flow:status to orient)
+2. /flow:go          ← executes the next phase
+3. /flow:go          ← executes the phase after that (if time permits)
+4. /flow:done        ← wraps up, gives you the handoff prompt for tomorrow
+```
+
+**Quick fix mid-session?** Run `/flow:task fix the broken test` — no PRD, no ceremony. It executes, verifies, commits, and you're back to `/flow:go`.
+
+### Starting a Brand New Project
+
+```
+1. /flow:init        ← scaffolds everything
+2. /flow:spec        ← interview → PRD
+3. /flow:go          ← phase 1
+4. /flow:done        ← wrap up
+```
+
+### Learn More
+
+- Full design doc: see `DESIGN.md` in the flow-plugin repo
+- Compatible with GSD: `/gsd:debug` and `/gsd:map-codebase` still work alongside Flow

package/skills/flow-spec.md

@@ -0,0 +1,235 @@
+---
+name: flow:spec
+description: Spec interview that produces an executable PRD with wave-based phases and testable acceptance criteria
+user_invocable: true
+---
+
+# /flow:spec — Spec Interview → Executable PRD
+
+You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow system. You will interview the user about their milestone, then produce a detailed PRD that agents can execute without ambiguity.
+
+**Interview mode:** Always thorough by default. The user can say "done", "finalize", "that's enough", or "move on" at ANY time to wrap up early. Respect their signal and finalize with whatever depth has been achieved.
+
+## Phase 1 — Context Gathering (automatic, no user input needed)
+
+1. Read `.planning/STATE.md` and `.planning/ROADMAP.md` — understand current milestone and what's done
+2. Read `CLAUDE.md` — understand project rules and tech stack
+3. Read `PRD.md` if it exists — check for existing spec to build on
+4. **Codebase scan** (brownfield projects):
+   - Use Glob to find: components, pages/routes, API endpoints, types, utilities, config files, database models
+   - Use Grep for: export patterns, route definitions, key function signatures
+   - Build internal summary: "Here's what exists that we can reuse"
+5. Print a brief context summary to the user: "Here's what I found in the codebase: [key components, patterns, data layer]. Starting the spec interview."
+
+## Phase 2 — Adaptive Interview
+
+### CRITICAL RULES (follow these exactly)
+
+1. **USE AskUserQuestion FOR ALL QUESTIONS.** Never just print questions as text. Always use the AskUserQuestion tool so the user gets structured prompts with selectable options. Provide 2-4 concrete options per question based on what you learned in Phase 1.
+
+2. **ASK NON-OBVIOUS QUESTIONS.** Don't just ask "what features do you want?" — you already read the codebase. Ask questions that PROBE deeper:
+   - "I see you have [existing pattern]. Should we extend that or build a new approach?"
+   - "What happens when [edge case] occurs?"
+   - "You mentioned [X] — does that mean [Y] is also needed, or is that separate?"
+   - "What's the failure mode here? What does the user see when things go wrong?"
+   - "Who else touches this data/workflow? Any downstream effects?"
+   - "What's the minimum version of this that would be useful?"
+
+3. **CONTINUE UNTIL THE USER SAYS STOP.** Do NOT stop after covering all 7 areas once. After each answer, immediately ask the next question. Keep going deeper until the user says "done", "finalize", "that's enough", "ship it", or similar. A thorough interview is 15-30 questions, not 5.
+
+4. **MAINTAIN A RUNNING DRAFT.** Every 2-3 questions, update PRD.md with what you've learned so far. Print: "Updated PRD draft — added [brief summary]." The user should see the spec taking shape in real-time, not all at the end.
+
+5. **BE ADAPTIVE.** Base your next question on the previous answer. If the user reveals something surprising, probe deeper on THAT — don't robotically move to the next category. The best specs come from following interesting threads.
+
+### First-Principles Mode (optional)
+
+If the user says "challenge this", "first principles", or "push back" — start with 3-5 challenge questions before detailed spec gathering:
+- "Why build this at all? What's the cost of NOT building it?"
+- "Is there a simpler way to achieve 80% of this value?"
+- "What assumptions are we making that might be wrong?"
+- "Who is this really for, and have they asked for it?"
+- "What would you cut if you had half the time?"
+
+Then proceed to the coverage areas below.
+
+### Coverage Areas
+
+Cover these areas thoroughly. There are no "rounds" — move fluidly between areas based on the conversation. Circle back to earlier areas when later answers reveal new information.
+
+**1. Scope Definition**
+- What features are IN scope for this milestone? What's the MVP vs. the full vision?
+- What is explicitly OUT of scope / deferred to a future milestone?
+- Is there any code that is sacred (must NOT be touched)? Why?
+- What existing code/features should we ignore entirely (not break, not improve, not touch)?
+
+**2. User Stories (CRITICAL — spend the most time here)**
+- What does the user actually DO? Walk through the key workflows step by step.
+- What should they see at each step? What feedback do they get?
+- Frame as: "As [role], I want [action], so that [outcome]"
+- **Story-splitting:** If a story has more than 3-4 acceptance criteria, split it into smaller stories. Each story should be independently deliverable.
+- **Anti-vagueness enforcement:**
+  - BAD acceptance criteria: "Works correctly", "Is fast", "Handles errors well", "Looks good"
+  - GOOD acceptance criteria: "Returns 200 with JSON body for valid input", "Shows error toast with message for invalid email format", "Page renders in < 200ms on 3G", "Matches Figma comp within 4px"
+  - If the user gives vague criteria, push back: "How would you specifically test that? What would you check?"
+- **Verification per story:** Each story must have at least one concrete verification step (a command to run, a page to visit, a state to check)
+
+**3. Technical Design**
+- What database changes are needed? (new tables, columns, indexes, migrations)
+- What API endpoints? (method, path, request/response shape, auth requirements)
+- What new files need to be created? What existing files get modified?
+- What existing utilities/components/DAL queries should be reused (not rebuilt)?
+- What's the data flow? Where does data originate, transform, and render?
+- Any wave-parallelization opportunities? (independent agents building separate files)
+
+**4. User Experience**
+- What are the key user flows? Walk through click-by-click.
+- What edge cases exist? (empty states, error states, loading states, partial data)
+- Accessibility requirements? (keyboard navigation, screen readers, ARIA labels)
+- Mobile/responsive behavior? (breakpoints, touch targets, layout shifts)
+- What does the user see while waiting? (loading spinners, skeletons, optimistic updates)
+
+**5. Trade-offs & Constraints**
+- Performance vs. simplicity? What's good enough for v1?
+- Any security considerations? (auth, data access, input validation)
+- Any third-party dependencies or integrations?
+- What technical debt is acceptable for now vs. must be done right?
+- Any browser/device support requirements?
+
+**6. Implementation Phases**
+- How should this break into sequential phases?
+- What can be parallelized within each phase? (wave-based agent structure)
+- What's the critical path — what must be built first?
+- What's the minimum viable first phase? (what gives us something testable fastest?)
+- Any phases that could be cut if time runs short?
+
+**7. Verification & Feedback Loops**
+- What commands verify the build works? (`tsc`, `biome`, test suite)
+- What does "done" look like for each phase? How do we know it worked?
+- Are there integration points that need end-to-end testing?
+- What should we check after each phase before moving to the next?
+- Any monitoring or logging needed to confirm production behavior?
+
+**User signals done:** If the user says "done", "finalize", "that's enough", "ship it", or similar — immediately stop interviewing and go to Phase 3. Finalize the PRD with whatever depth has been achieved.
+
+## Phase 3 — PRD Generation
+
+Write `PRD.md` to the project root with this EXACT structure:
+
+```markdown
+# [Milestone Name] — Specification
+
+**Status:** Ready for execution
+**Branch:** feat/[milestone-slug]
+**Created:** [today's date]
+
+## Overview
+[One paragraph summary of the milestone]
+
+## Problem Statement
+[Why this work exists — what problem does it solve?]
+
+## Scope
+
+### In Scope
+- [Bullet list of what ships in this milestone]
+
+### Out of Scope
+- [Explicitly deferred items]
+
+### Sacred / Do NOT Touch
+- [Code paths that must not be modified, with reasons]
+
+## User Stories
+
+### US-1: [Feature Name]
+**Description:** As [role], I want [action], so that [outcome].
+**Acceptance Criteria:**
+- [ ] Specific, testable requirement (names actual functions/components)
+- [ ] Another requirement
+- [ ] [Verification command] passes
+
+### US-2: [Feature Name]
+...
+
+## Technical Design
+
+### New Database Tables
+[SQL DDL or schema description, with indexes]
+
+### New API Endpoints
+[Method + path + request/response shape for each]
+
+### New Files to Create
+[Grouped by phase. Absolute paths with one-line descriptions]
+
+### Existing Files to Modify
+[Paths + what changes in each]
+
+### Key Existing Code (DO NOT recreate — use as-is)
+[Functions, utilities, DAL queries, components that agents should import/reuse]
+
+## Implementation Phases
+
+### Phase 1: [Name]
+**Goal:** [One sentence]
+
+**Wave 1 — [Theme] (N agents parallel):**
+1. agent-name: Creates file1.ts, file2.ts — [what it does]
+2. agent-name: Modifies file3.ts — [what changes]
+
+**Wave 2 — [Theme] (N agents parallel):**
+3. agent-name: Creates file4.ts — [what it does]
+4. agent-name: Wires component into page — [specifics]
+
+**Wave 3 — Integration:**
+5. Integration check, responsive verification, cleanup
+
+**Verification:** [Exact commands to run]
+**Acceptance:** US-1 criteria [list which], US-2 criteria [list which]
+
+### Phase 2: [Name]
+...
+
+## Execution Rules
+1. DELEGATE EVERYTHING. Lead context is sacred — do not read implementation files into it.
+2. Verify after every phase: [verification commands from CLAUDE.md]
+3. Atomic commits after each agent's work lands
+4. Never `git add .` — stage specific files only
+5. Read `tasks/lessons.md` before spawning agents — inject relevant anti-patterns
+
+## Definition of Done
+- [ ] All user story acceptance criteria pass
+- [ ] All phases verified with [verification commands]
+- [ ] Branch pushed and PR opened
+- [ ] STATE.md and ROADMAP.md updated
+```
+
+## Phase 4 — Post-PRD Updates
+
+After writing PRD.md:
+
+1. **Update ROADMAP.md:** Add phase breakdown under the current milestone section. Each phase gets a row in the progress table with status "Pending".
+
+2. **Update STATE.md:** Set current phase to "Phase 1 — ready for `/flow:go`". Update "Next Actions" to reference the first phase.
+
+3. **Generate Phase 1 handoff prompt:**
+   ```
+   Phase 1: [Name] — [short description]. Read STATE.md, ROADMAP.md, and PRD.md.
+   [One sentence of context about what Phase 1 builds].
+   ```
+
+4. Print the handoff prompt in a fenced code block.
+
+5. Print: "PRD ready. Run `/flow:go` to execute Phase 1, or review PRD.md first."
+
+## Quality Gates
+
+Before finalizing, self-check the PRD:
+- [ ] Every phase has wave-based agent assignments with explicit file lists
+- [ ] Every user story has checkbox acceptance criteria that are testable
+- [ ] Every phase has verification commands
+- [ ] "Key Existing Code" section references actual files/functions found in the codebase scan
+- [ ] No phase has more than 5 agents in a single wave (too many = coordination overhead)
+- [ ] Sacred code section is populated (even if empty with "None identified")
+
+If any gate fails, fix the PRD before presenting it.

package/skills/flow-status.md

@@ -0,0 +1,72 @@
+---
+name: flow:status
+description: Quick orientation — shows current milestone, phase progress, and next actions
+user_invocable: true
+---
+
+# /flow:status — Quick Orientation
+
+You are executing the `/flow:status` skill. This is a READ-ONLY operation. Do NOT modify any files.
+
+## Step 1 — Read Context Files
+
+Read ALL of the following in parallel:
+- `.planning/STATE.md`
+- `.planning/ROADMAP.md`
+- `PRD.md` (if exists)
+- Count lessons in `tasks/lessons.md` (if exists)
+
+IF both STATE.md AND ROADMAP.md are missing:
+- Print: "No flow project found. Run `/flow:init` to set up, or `/flow:task` for a quick standalone fix."
+- STOP here.
+
+IF only one file exists, continue with what's available.
+
+## Step 2 — Analyze Phase Status
+
+Parse ROADMAP.md to determine phase progress:
+- Count total phases
+- Count phases marked "Complete", "Done", or containing a completion date (e.g., `✓`, `[x]`, `completed`)
+- Count phases marked "Pending", "In Progress", or not yet started
+- Identify the FIRST phase that is NOT complete — this is the **next phase**
+
+RULE: Determine the next action from ROADMAP.md phase statuses, NOT from STATE.md "Next Actions" text. STATE.md may be stale from a previous session. ROADMAP.md is the source of truth for phase progress.
+
+## Step 3 — Determine Routing
+
+Use this explicit decision tree:
+
+**IF pending phases exist in ROADMAP AND PRD.md exists:**
+→ Primary: `/flow:go` to execute Phase [N]: [name]
+→ Alt: `/flow:done` if wrapping up the session
+→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+
+**IF pending phases exist in ROADMAP BUT PRD.md is missing:**
+→ Primary: `/flow:spec` to create the execution plan
+→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+
+**IF all phases are complete:**
+→ Primary: `/flow:done` to finalize this milestone
+→ Then: `/flow:init` to start the next milestone
+→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+
+**IF no phases exist in ROADMAP (milestone defined but not planned):**
+→ Primary: `/flow:spec` to plan this milestone
+→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+
+## Step 4 — Print Status Block
+
+```
+Milestone: [name] ([X/Y] phases complete)
+Last session: [date] — [what was built]
+Next: Phase [N] — [name] ([short description])
+Lessons: [N] rules
+
+[routing recommendations from Step 3]
+```
+
+Adapt the block based on available information. If STATE.md is missing, omit "Last session". If ROADMAP.md is missing, omit phase counts and say "Run /flow:init to set up tracking."
+
+## Step 5 — No File Writes
+
+This is purely informational. Do not modify any files.