A structured workflow for software teams that combine one human with multiple AI agents. GitHub-native. No external tools. No dashboards. No middleware. Built and battle-tested in production with a single developer and 7 AI agents shipping a multi-module enterprise software suite.
Team Model
A FLOW team has one human and multiple agents, each bound to a specific role. Each agent gets a named workstation — a persistent git worktree with its own branch, Docker stack, and role-bound CLAUDE.md.
Designs systems, writes ADRs, triages issues, refines tickets, maintains .context/ health. Creates epics and breaks them into implementable tickets. Does not implement features.
Implements tickets from refined issues. Writes models, views, wizards, tests. Ships code via /flow-start → /flow-ship. Follows existing architecture and ADRs.
Reviews PRs for correctness, test coverage, architecture compliance. Applies advisory labels. Validates that PRs match their linked issues. Does not implement fixes found during review.
Writes data scripts: enrichment, bootstrap, reconciliation, migration, audit. Every write has dry-run mode. Every mutation is logged. External systems are READ-ONLY unless explicitly authorized.
Creates docs, training guides, App Store listings, website content. Validates content against current module state. Does not write modules or make architecture decisions.
Core Concepts
Four ideas that make human+agent teams actually functional at production scale.
01
.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. Knowledge stays in the repo, not in the model's weights.
02
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.
03
FLOW doesn't use story points or developer days. The human's attention is the bottleneck. Units: Sessions (1–3 hour focused block), Agent-slots (parallelizable work), Gates (points where the human must review). A size::m ticket takes an agent 30–60 minutes. The constraint is how many gates the human can process.
04
Non-negotiable rules on every workstation. Error Ownership: if you caused it, fix it before moving on. Anti-Deferral: "too much work" is not valid — flag scope issues before starting. Definition of Done: all acceptance criteria checked, no new errors, no bare TODOs, self-review before shipping.
Skills
Drop these into your project's .claude/skills/ directory. They handle the full FLOW lifecycle.
| Skill | What it does |
|---|---|
| /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 — 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 |
Quick Start
No installation required beyond Claude Code. Copy the templates and start.
Clone the workflow repo and copy the templates directory.
git clone https://github.com/syntax-sabotage/claude-code-workflow
cp -r claude-code-workflow/templates/.context your-project/
cp -r claude-code-workflow/templates/.claude your-project/
cp -r claude-code-workflow/templates/.flow your-project/Replace [PLACEHOLDERS] in three files:
.context/substrate.md # project overview and navigation
.context/ai-rules.md # coding standards, naming, architecture
.context/glossary.md # domain-specific terminologyFor multi-agent teams, create named git worktrees with role-bound CLAUDE.md files.
git worktree add ../your-project-Dev1 dev1
git worktree add ../your-project-Reviewer reviewer
# Copy CLAUDE.md.workstation to each, customize the roleFLOW uses labels to coordinate work. Add these to your repository:
autonomy::0 autonomy::1 autonomy::2 autonomy::3
size::xs size::s size::m size::l size::xl
status::backlog status::ready status::active status::review
role::developer role::architect role::reviewerUse /flow-resume at the start of every session. Use /flow-handover to end. Full walkthrough in the repo's GUIDE.md.