team-flow is a process-driven AI collaboration framework that transforms chaotic AI interactions into structured, verifiable workflows. Define your team, define your process, and let AI execute with quality gates and verification chains.
v3 is the current version. Process is central — rules, tools, and skills are unified under flow definitions.
| Problem | team-flow Solution |
|---|---|
| AI agents work without structure | Flow-driven execution — every task follows a defined process |
| AI says "done" but quality is unknown | Verification chain — downstream roles verify upstream deliverables |
| Multiple AI agents talk to the user | Principal role — single user interface, all others execute silently |
| No quality enforcement | Gate nodes — automated quality checks block progress until passed |
| Prompt engineering is ad-hoc | Structured rules — instruction (30 chars) + reference + full description |
| Work is lost between sessions | Session persistence — every session produces traceable logs |
Everything starts with a flow definition. A flow specifies:
- What steps to execute (nodes)
- What order (edges with conditions)
- What rules apply per step (components)
- What deliverables to produce (docs with templates)
- What gates enforce quality (automated checks)
AI cannot self-verify. Every role does two things: execute work + verify upstream deliverables.
Role A (execute + self-check) → Role B (verify A + execute + self-check) → ... → QA (independent final check) → Done
Every flow has exactly one principal role — the team's public face:
- Only the principal communicates with the user
- User input always routes to the principal
- Sub-roles report results to the principal
- Interruptions return to the principal for re-assessment
| Team | Flows | Best For |
|---|---|---|
| Dev Team | 8 flows (dev/feature/bugfix/hotfix/change/release/analysis/batch) | Software development |
| Content Team | 3 flows (content-distribution/novel/promo-video) | Articles, videos, novels |
| Game Team | 1 flow (game-design) | Game design |
| Trading Team | 1 flow (trading) | Trading analysis |
| Skill Team | 2 flows (skill-dev/test-simple) | AI skill development |
| Version | Capability | Process Management | Task Management |
|---|---|---|---|
| v1 | Document-only workflow | Markdown files | None |
| v2 | flow task management | Markdown + flow task | beads (bd CLI) |
| v3 | Full flow engine | JSON process definitions + engine | Config-driven (beads/file/custom) |
npx skills add @origadmin/team-flowThis installs the skill to your IDE's skill directory. Embedded skill files — no network required after install.
go install github.com/origadmin/team-flow/cmd/flow@latestgit clone https://github.com/origadmin/team-flow.git
cd team-flow
go build -o flow ./cmd/flow/| Tool | Version | Purpose |
|---|---|---|
| Go | 1.21+ | Build and run the CLI |
| Node.js | 18+ | npm installation method |
cd /path/to/your/project
# Interactive setup — choose from 5 preset teams
flow init --v3
# Or specify a team directly
flow init --v3 --team dev-team
# Or specify a flow directly (auto-finds the team)
flow init --v3 --flow dev-flowflow init --v3 will:
- Create
.team/directory and configuration files - Show preset team menu (5 teams) — pick the closest match
- Install selected team's flows to
.team/flows/ - Set
default_flowin project configuration
# Enter the flow engine — get your work instructions
flow proc run
# The engine tells you: your role, persona, rules, tools, deliverablesflow project detect # Detect project and lock status
flow config paths # Show resolved path variables# Migrate to v3 (7-step automatic migration)
flow migrate v3
# Rollback to v2 if needed (6-step automatic rollback)
flow migrate rollback| Command | Description |
|---|---|
flow init --v3 |
Initialize project with v3 flow system |
flow init --v3 --team <id> |
Initialize with specific team |
flow proc run |
Start flow engine — get work instructions |
flow proc run <node-id> |
Run a specific flow node |
flow proc list |
List all registered flows |
flow proc validate |
Validate flow definitions |
flow proc rule <id> |
Show full rule description |
flow project detect |
Detect and lock project |
flow version |
Show version info |
| Command | Description |
|---|---|
flow config paths |
Show resolved path variables |
flow config paths --json |
Show paths in JSON format |
| Command | Description |
|---|---|
flow task list |
List all tasks |
flow task show <id> |
View task details |
flow task update <id> --claim |
Claim a task |
flow task close <id> |
Close a task |
flow task sync --source github --repo owner/repo |
Sync GitHub Issues |
| Command | Description |
|---|---|
flow migrate v3 |
Migrate from v2 to v3 |
flow migrate rollback |
Rollback from v3 to v2 |
team-flow/
├── cmd/flow/ # CLI entry point
├── internal/
│ ├── boot/ # flow init (v1/v2/v3)
│ ├── proc/ # flow proc run (v3 engine)
│ ├── flow/ # Flow parser, validator, serializer
│ ├── config/ # flow config paths
│ ├── project/ # flow project detect
│ ├── migrate/ # flow migrate (v2→v3, rollback)
│ ├── task/ # flow task management
│ ├── skill/ # Skill management
│ ├── editor/ # flow editor (Web UI)
│ └── state/ # Gate state tracking
├── assets/ # Unified embed root (skillfs.go)
│ ├── skill/ # Skill files (v1/v2/v3 coexist)
│ │ ├── v3/ # v3: SKILL.md, prompts, templates, references
│ │ ├── v2/ # v2: fallback (preserved during migration)
│ │ └── v1/ # v1: legacy (preserved during migration)
│ ├── orgs/ # Organization templates (team.json + flows/)
│ ├── flows/ # Preset flow definitions
│ └── schema/ # JSON Schema for flow validation
├── editor/ # Flow visual editor (React + TypeScript)
├── skillfs.go # Embedded FS: //go:embed all:assets
├── go.mod
├── package.json # npm package (@origadmin/team-flow)
└── SKILL.md # Root entry point for AI tools
| Aspect | v2 | v3 |
|---|---|---|
| Architecture | Prompt-driven (markdown files) | Flow-driven (JSON process definitions) |
| Execution | AI reads prompts, ad-hoc execution | Engine-driven — flow proc run provides structured instructions |
| Quality | Manual review | Verification chain — downstream verifies upstream |
| User interface | Any role can talk to user | Principal role — single user interface |
| Gates | None | Automated quality gates block progress |
| Rules | Scattered in markdown | Three-layer — instruction + reference + full description |
| Teams | Single generic team | 5 preset teams with domain-specific flows |
| Configuration | project.md (monolithic) | project.yaml (structured, ~100 tokens) |
| Session tracking | None | Session logs for traceability |
| Migration | v1→v2 manual | v2→v3 automatic (7 steps) with rollback |
Every AI session follows this protocol:
Step 1: flow project detect → Lock the project
Step 2: flow proc run → Get work instructions (role, rules, tools, docs)
Step 3: Adopt principal role → Start working
MIT License