{"id":50803875,"url":"https://github.com/origadmin/team-flow","last_synced_at":"2026-06-12T23:04:59.929Z","repository":{"id":356105575,"uuid":"1217893445","full_name":"origadmin/team-flow","owner":"origadmin","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-27T18:14:07.000Z","size":2023,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T20:05:29.012Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/origadmin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["origadmin"],"open_collective":"origadmin","ko_fi":"origadmin","patreon":"origadmin","custom":["https://origadmin.org/donate"],"github_followers":true}},"created_at":"2026-04-22T10:21:30.000Z","updated_at":"2026-05-27T18:14:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/origadmin/team-flow","commit_stats":null,"previous_names":["origadmin/team-flow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/origadmin/team-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fteam-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fteam-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fteam-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fteam-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/origadmin","download_url":"https://codeload.github.com/origadmin/team-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fteam-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34265521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T23:04:58.882Z","updated_at":"2026-06-12T23:04:59.921Z","avatar_url":"https://github.com/origadmin.png","language":"Go","funding_links":["https://github.com/sponsors/origadmin","https://opencollective.com/origadmin","https://ko-fi.com/origadmin","https://patreon.com/origadmin","https://origadmin.org/donate",true],"categories":[],"sub_categories":[],"readme":"# team-flow — Process-Centric AI Collaboration Framework\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/origadmin/team-flow)](https://goreportcard.com/report/github.com/origadmin/team-flow)\n[![npm version](https://img.shields.io/npm/v/@origadmin/team-flow.svg)](https://www.npmjs.com/package/@origadmin/team-flow)\n\n**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.\n\n\u003e **v3 is the current version.** Process is central — rules, tools, and skills are unified under flow definitions.\n\n## Why team-flow?\n\n| Problem | team-flow Solution |\n|---------|-------------------|\n| AI agents work without structure | **Flow-driven execution** — every task follows a defined process |\n| AI says \"done\" but quality is unknown | **Verification chain** — downstream roles verify upstream deliverables |\n| Multiple AI agents talk to the user | **Principal role** — single user interface, all others execute silently |\n| No quality enforcement | **Gate nodes** — automated quality checks block progress until passed |\n| Prompt engineering is ad-hoc | **Structured rules** — instruction (30 chars) + reference + full description |\n| Work is lost between sessions | **Session persistence** — every session produces traceable logs |\n\n## Key Features\n\n### Flow-Driven Architecture\nEverything starts with a flow definition. A flow specifies:\n1. **What steps to execute** (nodes)\n2. **What order** (edges with conditions)\n3. **What rules apply** per step (components)\n4. **What deliverables to produce** (docs with templates)\n5. **What gates enforce quality** (automated checks)\n\n### Verification Chain\nAI cannot self-verify. Every role does two things: execute work + verify upstream deliverables.\n\n```\nRole A (execute + self-check) → Role B (verify A + execute + self-check) → ... → QA (independent final check) → Done\n```\n\n### Principal Role System\nEvery flow has exactly one **principal** role — the team's public face:\n- Only the principal communicates with the user\n- User input always routes to the principal\n- Sub-roles report results to the principal\n- Interruptions return to the principal for re-assessment\n\n### 5 Preset Teams, 15+ Flows\n\n| Team | Flows | Best For |\n|------|-------|----------|\n| **Dev Team** | 8 flows (dev/feature/bugfix/hotfix/change/release/analysis/batch) | Software development |\n| **Content Team** | 3 flows (content-distribution/novel/promo-video) | Articles, videos, novels |\n| **Game Team** | 1 flow (game-design) | Game design |\n| **Trading Team** | 1 flow (trading) | Trading analysis |\n| **Skill Team** | 2 flows (skill-dev/test-simple) | AI skill development |\n\n### v1/v2/v3 Parallel Coexistence\n\n| Version | Capability | Process Management | Task Management |\n|---------|-----------|-------------------|-----------------|\n| v1 | Document-only workflow | Markdown files | None |\n| v2 | flow task management | Markdown + flow task | beads (bd CLI) |\n| v3 | Full flow engine | JSON process definitions + engine | Config-driven (beads/file/custom) |\n\n## Installation\n\n### Via npm (Recommended for AI tool users)\n\n```bash\nnpx skills add @origadmin/team-flow\n```\n\nThis installs the skill to your IDE's skill directory. Embedded skill files — no network required after install.\n\n### Via Go (For developers)\n\n```bash\ngo install github.com/origadmin/team-flow/cmd/flow@latest\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/origadmin/team-flow.git\ncd team-flow\ngo build -o flow ./cmd/flow/\n```\n\n### Prerequisites\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| Go | 1.21+ | Build and run the CLI |\n| Node.js | 18+ | npm installation method |\n\n## Quick Start\n\n### 1. Initialize a New Project (v3)\n\n```bash\ncd /path/to/your/project\n\n# Interactive setup — choose from 5 preset teams\nflow init --v3\n\n# Or specify a team directly\nflow init --v3 --team dev-team\n\n# Or specify a flow directly (auto-finds the team)\nflow init --v3 --flow dev-flow\n```\n\n`flow init --v3` will:\n1. Create `.team/` directory and configuration files\n2. Show preset team menu (5 teams) — pick the closest match\n3. Install selected team's flows to `.team/flows/`\n4. Set `default_flow` in project configuration\n\n### 2. Start Working\n\n```bash\n# Enter the flow engine — get your work instructions\nflow proc run\n\n# The engine tells you: your role, persona, rules, tools, deliverables\n```\n\n### 3. Check Project Status\n\n```bash\nflow project detect    # Detect project and lock status\nflow config paths      # Show resolved path variables\n```\n\n### 4. Migrate from v2\n\n```bash\n# Migrate to v3 (7-step automatic migration)\nflow migrate v3\n\n# Rollback to v2 if needed (6-step automatic rollback)\nflow migrate rollback\n```\n\n## Commands Reference\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `flow init --v3` | Initialize project with v3 flow system |\n| `flow init --v3 --team \u003cid\u003e` | Initialize with specific team |\n| `flow proc run` | Start flow engine — get work instructions |\n| `flow proc run \u003cnode-id\u003e` | Run a specific flow node |\n| `flow proc list` | List all registered flows |\n| `flow proc validate` | Validate flow definitions |\n| `flow proc rule \u003cid\u003e` | Show full rule description |\n| `flow project detect` | Detect and lock project |\n| `flow version` | Show version info |\n\n### Configuration\n\n| Command | Description |\n|---------|-------------|\n| `flow config paths` | Show resolved path variables |\n| `flow config paths --json` | Show paths in JSON format |\n\n### Task Management\n\n| Command | Description |\n|---------|-------------|\n| `flow task list` | List all tasks |\n| `flow task show \u003cid\u003e` | View task details |\n| `flow task update \u003cid\u003e --claim` | Claim a task |\n| `flow task close \u003cid\u003e` | Close a task |\n| `flow task sync --source github --repo owner/repo` | Sync GitHub Issues |\n\n### Migration\n\n| Command | Description |\n|---------|-------------|\n| `flow migrate v3` | Migrate from v2 to v3 |\n| `flow migrate rollback` | Rollback from v3 to v2 |\n\n## Project Structure\n\n```\nteam-flow/\n├── cmd/flow/                  # CLI entry point\n├── internal/\n│   ├── boot/                  # flow init (v1/v2/v3)\n│   ├── proc/                  # flow proc run (v3 engine)\n│   ├── flow/                  # Flow parser, validator, serializer\n│   ├── config/                # flow config paths\n│   ├── project/               # flow project detect\n│   ├── migrate/               # flow migrate (v2→v3, rollback)\n│   ├── task/                  # flow task management\n│   ├── skill/                 # Skill management\n│   ├── editor/                # flow editor (Web UI)\n│   └── state/                 # Gate state tracking\n├── assets/                    # Unified embed root (skillfs.go)\n│   ├── skill/                 # Skill files (v1/v2/v3 coexist)\n│   │   ├── v3/                # v3: SKILL.md, prompts, templates, references\n│   │   ├── v2/                # v2: fallback (preserved during migration)\n│   │   └── v1/                # v1: legacy (preserved during migration)\n│   ├── orgs/                  # Organization templates (team.json + flows/)\n│   ├── flows/                 # Preset flow definitions\n│   └── schema/                # JSON Schema for flow validation\n├── editor/                    # Flow visual editor (React + TypeScript)\n├── skillfs.go                 # Embedded FS: //go:embed all:assets\n├── go.mod\n├── package.json               # npm package (@origadmin/team-flow)\n└── SKILL.md                   # Root entry point for AI tools\n```\n\n## v2 vs v3\n\n| Aspect | v2 | v3 |\n|--------|----|----|\n| Architecture | Prompt-driven (markdown files) | **Flow-driven** (JSON process definitions) |\n| Execution | AI reads prompts, ad-hoc execution | **Engine-driven** — `flow proc run` provides structured instructions |\n| Quality | Manual review | **Verification chain** — downstream verifies upstream |\n| User interface | Any role can talk to user | **Principal role** — single user interface |\n| Gates | None | **Automated quality gates** block progress |\n| Rules | Scattered in markdown | **Three-layer** — instruction + reference + full description |\n| Teams | Single generic team | **5 preset teams** with domain-specific flows |\n| Configuration | project.md (monolithic) | **project.yaml** (structured, ~100 tokens) |\n| Session tracking | None | **Session logs** for traceability |\n| Migration | v1→v2 manual | **v2→v3 automatic** (7 steps) with rollback |\n\n## Session Startup Protocol\n\nEvery AI session follows this protocol:\n\n```\nStep 1: flow project detect    → Lock the project\nStep 2: flow proc run          → Get work instructions (role, rules, tools, docs)\nStep 3: Adopt principal role   → Start working\n```\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forigadmin%2Fteam-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forigadmin%2Fteam-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forigadmin%2Fteam-flow/lists"}