# FLOW — Human-Agent Team Workflow for Claude Code

## What is FLOW?

FLOW is a structured workflow for software teams that combine one human with multiple AI agents. It is GitHub-native, requiring no external tools, dashboards, or middleware. Each agent is bound to a specific role and operates from a named workstation — a persistent git worktree with its own branch, Docker stack, and role-bound CLAUDE.md. Built and battle-tested in production with a single developer and 7 AI agents shipping a multi-module enterprise software suite.

## The 5 Agent Roles

- **Architect** — Designs systems, writes ADRs, triages issues, refines tickets, maintains .context/ health. Does not implement features.
- **Developer** — Implements tickets from refined issues. Writes models, views, tests. Ships code via /flow-start → /flow-ship.
- **Reviewer** — Reviews PRs for correctness, test coverage, and architecture compliance. Applies advisory labels. Does not implement fixes.
- **Data Engineer** — Writes data scripts for enrichment, bootstrap, migration, and audit. Every write has dry-run mode. Every mutation is logged.
- **Content Engineer** — Creates docs, training guides, App Store listings, website content. Validates content against current module state.

## The 4 Core Concepts

1. **.context/ Knowledge System** — Institutional memory that survives context window resets. Each project has a .context/ folder with substrate, ai-rules, glossary, anti-patterns, and per-workstation handover files. Agents read it before working.

2. **Autonomy Levels** — Labels on GitHub issues set the trust boundary. autonomy::0 stops and asks at every decision. autonomy::3 ships and the human merges. Default is autonomy::1. Promoting tickets via thorough refinement doubles effective throughput.

3. **Estimation Model** — The human's attention is the bottleneck, not agent coding speed. Units: Sessions (1–3 hour focused block), Agent-slots (parallelizable work), Gates (points where the human must review).

4. **Completion Standards** — Non-negotiable rules on every workstation: Error Ownership (if you caused it, fix it), Anti-Deferral (flag scope issues before starting), Definition of Done (all ACs checked, no new errors, no bare TODOs, self-review before shipping).

## All 19 Skills (Slash Commands)

Skills are dropped into your project's .claude/skills/ directory and handle the full FLOW lifecycle.

- **/flow-start** — Begin work on a GitHub issue: create branch, load context
- **/flow-ship** — Commit, push, and create PR with self-review gates
- **/flow-handover** — End session and capture state for next session
- **/flow-resume** — Start a new session with full context restored from last handover
- **/flow-reflect** — Capture learnings from recent closed work
- **/flow-refinement** — Architectural analysis to make tickets implementation-ready
- **/flow-runner** — Autonomous ticket processing agent — picks up eligible issues
- **/flow-status** — Show current work state across workstations
- **/flow-triage** — Categorize and prioritize open issues
- **/flow-drop** — Release a ticket back to the pool
- **/flow-objective** — Create a new issue with proper labels and metadata
- **/flow-release** — Tag and create a GitHub release
- **/flow-simplify** — Run code simplification on a module or path
- **/flow-stream** — Manage milestones and streams
- **/flow-worktree** — Manage git worktrees for multi-instance work
- **/gh-bug** — Quick bug report: create a bug issue with structured template
- **/gh-done** — Finish work and create PR
- **/gh-start** — Start work on a GitHub issue
- **/gh-status** — GitHub status overview across issues and PRs

## Links

- GitHub Repository: https://github.com/syntax-sabotage/claude-code-workflow
- Website: https://flow-methodology.com

## Author

Syntax & Sabotage — https://syntaxandsabotage.io