flow-cc 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Troy Hoffman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,66 +1,126 @@
-# Flow Plugin
+<p align="center">
+  <h1 align="center">Flow</h1>
+  <p align="center">A structured workflow system for Claude Code.<br/>Spec interviews. Agent-team execution. Session handoffs. Compounding knowledge.</p>
+</p>
 
-**Formalized workflow skills for Claude Code. Turns a proven spec-interview, agent-team-execution, session-handoff pattern into reusable `/flow:*` commands.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/flow-cc"><img src="https://img.shields.io/npm/v/flow-cc.svg" alt="npm version"></a>
+  <a href="https://github.com/troyhoffman-oss/flow-plugin/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/flow-cc.svg" alt="license"></a>
+  <a href="https://www.npmjs.com/package/flow-cc"><img src="https://img.shields.io/npm/dm/flow-cc.svg" alt="downloads"></a>
+</p>
 
-## What It Does
+---
 
-- `/flow:intro` -- Walkthrough of the system — **start here**
-- `/flow:init` -- Initialize a new project or milestone with planning scaffolding
-- `/flow:spec` -- Run a spec interview that produces an executable PRD with wave-based phases
-- `/flow:task` -- Lightweight task execution — bug fixes, cleanup, small features without a PRD
-- `/flow:go` -- Execute the next phase from the PRD using agent teams
-- `/flow:done` -- Session-end docs, lessons refinement, and handoff prompt generation
-- `/flow:status` -- Quick "where am I?" orientation
-- `/flow:update` -- Pull latest and re-install skills from any session
-
-## Installation
+## Install
 
 ```bash
-# Mac/Linux
-git clone https://github.com/troyhoffman/flow-plugin.git && cd flow-plugin && bash setup.sh
-
-# Windows (PowerShell)
-git clone https://github.com/troyhoffman/flow-plugin.git; cd flow-plugin; .\setup.ps1
+npx flow-cc
 ```
 
-**Update:** Run `/flow:update` in any Claude Code session
+One command. Installs skills, hooks, templates, and configures your statusLine. Works on Mac, Linux, and Windows.
+
+## Why Flow?
+
+Claude Code is powerful but unstructured. Without a system, you lose context between sessions, repeat mistakes, and waste tokens re-explaining what you've already decided.
+
+Flow fixes this by giving Claude Code a **memory system and execution framework**:
 
-## Getting Started
+- **Spec interviews** extract decisions upfront so agents execute instead of guessing
+- **PRDs become execution contracts** that agent teams follow phase-by-phase
+- **Session handoffs** preserve context across fresh sessions — no more "where was I?"
+- **Lessons compound** — mistakes get captured, refined, and promoted into permanent rules
 
-After installing, run `/flow:intro` in any Claude Code session. It explains the full lifecycle, what each command does, and typical usage patterns.
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/flow:intro` | Walkthrough of the system — **start here** |
+| `/flow:init` | Initialize a project with `.planning/` scaffolding, CLAUDE.md, templates |
+| `/flow:spec` | Spec interview that produces an executable PRD with phased execution plan |
+| `/flow:go` | Execute the next phase from the PRD using wave-based agent teams |
+| `/flow:task` | Bug fixes, cleanup, small features — no PRD needed |
+| `/flow:done` | Session-end documentation, lessons refinement, handoff prompt |
+| `/flow:status` | Quick orientation — current milestone, phase progress, next actions |
+| `/flow:update` | Update Flow to the latest version |
 
 ## How It Works
 
-Skills install to `~/.claude/commands/flow/` and are immediately available in any Claude Code session. The workflow:
+```
+/flow:init → /flow:spec → /flow:go (repeat per phase) → /flow:done
+                                                            ↓
+                                              handoff prompt for next session
+
+/flow:task  ← standalone path for bug fixes and small features
+```
+
+**The lifecycle in practice:**
 
-1. `/flow:init` -- Creates `.planning/` directory structure, CLAUDE.md, and initial docs
-2. `/flow:spec` -- Interviews you about the milestone, produces PRD.md with wave-based phases
-3. `/flow:go` -- Reads PRD, spawns agent teams per wave structure, verifies, commits
-4. `/flow:task` -- Quick fixes and small features — executes, verifies, commits (no PRD needed)
-5. `/flow:done` -- Updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt
-6. `/flow:status` -- Read-only orientation check
+1. **`/flow:init`** — Creates `.planning/` directory, CLAUDE.md, STATE.md, ROADMAP.md, lessons.md
+2. **`/flow:spec`** — Interviews you about the milestone. Produces a PRD with wave-based phases, acceptance criteria, and agent-team structure
+3. **`/flow:go`** — Reads the PRD, spawns parallel agent teams per wave, builds, verifies, commits
+4. **`/flow:done`** — Updates all planning docs, captures lessons, generates a one-line handoff prompt so the next session starts instantly
+5. **Repeat** — Next session picks up from the handoff. Context lives in the repo, not the conversation.
 
-## Lifecycle
+## What Gets Installed
 
 ```
-/flow:init -> /flow:spec -> /flow:go (repeat per phase) -> /flow:done
-                                                               |
-                                                handoff prompt for next session
+~/.claude/
+├── commands/flow/
+│   ├── flow-init.md          # 8 skill files
+│   ├── flow-spec.md
+│   ├── flow-go.md
+│   ├── flow-task.md
+│   ├── flow-done.md
+│   ├── flow-status.md
+│   ├── flow-intro.md
+│   ├── flow-update.md
+│   ├── VERSION
+│   └── templates/            # Project scaffolding templates
+│       ├── CLAUDE.md.template
+│       ├── STATE.md.template
+│       ├── ROADMAP.md.template
+│       └── lessons.md.template
+├── hooks/
+│   ├── flow-check-update.js  # Notifies when updates are available
+│   └── flow-statusline.js    # Shows project context in statusLine
+└── settings.json             # statusLine configured automatically
+```
+
+## Project Structure
 
-/flow:task  ← standalone path for bug fixes, cleanup, small features (no PRD needed)
+Every Flow project gets this structure via `/flow:init`:
+
+```
+your-project/
+├── CLAUDE.md              # Project-specific execution rules
+├── PRD.md                 # Current milestone spec (created by /flow:spec)
+├── .planning/
+│   ├── STATE.md           # Session GPS — current status, next actions
+│   ├── ROADMAP.md         # Milestone phases and progress
+│   └── archive/           # Completed milestones and old PRDs
+└── tasks/
+    └── lessons.md         # Mistake catalog → refined into permanent rules
 ```
 
-## Compatible with GSD
+## The Lessons System
 
-Uses the same `.planning/` directory structure. You can still use `/gsd:debug`, `/gsd:map-codebase`, etc. alongside Flow commands.
+Flow's knowledge compounding is what makes it get better over time:
 
-## Philosophy
+1. **Capture** — Mistake happens, lesson written to `tasks/lessons.md`
+2. **Refine** — Each `/flow:done` merges duplicates, sharpens rules, removes obvious ones
+3. **Promote** — Universal lessons move to `~/.claude/lessons.md` (all projects)
+4. **Permanence** — Recurring patterns become rules in `CLAUDE.md`
 
-- Front-load decisions into the spec interview, making execution simple
-- Knowledge compounds through lessons.md to CLAUDE.md promotion lifecycle
-- Fresh context per session; memory lives in the repo, not the conversation
-- PRD is the execution contract -- agents execute what was specified
+The goal: fewer, sharper lessons over time — not an ever-growing list.
+
+## Compatible With GSD
+
+Flow uses the same `.planning/` directory structure as [GSD](https://github.com/gsd-framework/gsd). You can use `/gsd:debug`, `/gsd:map-codebase`, and other GSD commands alongside Flow.
 
 ## Requirements
 
-Claude Code CLI with skills support.
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI with skills support.
+
+## License
+
+MIT

package/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

package/bin/install.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // Flow plugin installer for Claude Code
 // Usage: npx flow-cc [--uninstall]
 

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "flow-cc",
-  "version": "0.1.0",
-  "description": "Flow workflow plugin for Claude Code",
+  "version": "0.1.1",
+  "description": "Structured workflow system for Claude Code — spec interviews, agent-team execution, session handoffs, compounding knowledge",
+  "author": "Troy Hoffman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/troyhoffman-oss/flow-plugin.git"
+  },
+  "homepage": "https://github.com/troyhoffman-oss/flow-plugin",
+  "bugs": {
+    "url": "https://github.com/troyhoffman-oss/flow-plugin/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "workflow",
+    "ai-agents",
+    "developer-tools",
+    "cli",
+    "skills",
+    "anthropic"
+  ],
   "bin": {
     "flow-cc": "bin/install.js"
   },