Code the Origin, Forge the App. 15 AI coworkers · Agile + Scrum + TDD backbone · ship a feature overnight · watch it all in one browser tab.
简体中文 · English
📖 Reading path (Setup → Detail → Wrap):
- Setup (conclusion first) ── 💡 Conclusion → 🧠 Philosophy
- Detail (3 pillars + onboarding) ── 🏢 Organization → 🔄 Process → ⚙️ Mechanism → ⏱ Day 1 → 🛠️ Tools
- Wrap (closing) ── 🔍 Comparison → ✨ Summary
AppGenesisForge is an AI team scaffold on Claude Code Agent Teams — not a prompt collection, not a roster of agent personalities, but a virtual AI team with Agile + Scrum + TDD backbone, defined workflow + standards, and acceptance gates.
Agile + Scrum + TDD principles are wired into the skill / hook / DoD enforcement path — never relying on agent self-discipline.
- 🧠 Methodology backbone is non-negotiable — Agile + Scrum + TDD (see §Philosophy)
- 🏢 Clear organization — 15 AI coworkers with role contracts (see §Organization)
- 🔄 Closed-loop process — PRD → UAT 6 stage gates, no skipping on failure (see §Process)
- 🚀 Controllable parallelism — Multi-instance Worker Pool (ADR-001): ≥2 same-type pending tasks → Dev / Reviewer / QA three-layer auto fan-out; PL fans-in with
agf-matrix.sh - ⚙️ Mechanism backstop — skill enforcement / hook block / DoD checklist, three layers (see §Mechanism)
- 🇨🇳 China-native ecosystem — DeepSeek / Doubao / Qwen / MiniMax + WeChat Mini Program (see §Tools)
✅ Built for: React + FastAPI + Postgres · AI Agent / RAG / multimodal · WeChat Mini Programs (native + Taro fallback) · full PRD → UAT loop
❌ Not built for: native iOS / Android · desktop GUI · large-model training
📝 Default backend is Python (FastAPI + SQLAlchemy + Alembic), frontend React + Vite, extensible to Java / Go / Rust and other backend stacks — OpenAI-compatible LLM wiring / Agile + Scrum + TDD principles / 4-layer hook defense / 15-coworker role contracts are all language-agnostic. To swap stacks,
tech-leadrewritesADR-000+ the Python examples inbackend-dev/testing.md/agf-wiring-multi-llm-sdk.
AI agents have two natural weaknesses: lost context + over-confidence. Scrum stage gates + Agile iterative feedback + TDD red-green-refactor are the mature disciplines against both, and this project lands them across three layers — Organization + Process + Mechanism. This section covers WHAT/WHY; the next three cover HOW.
Full decision log: product-workflow.md §4.4 + team-capability-map.md §1.6.
Three-layer landing at a glance: TDD / AC / DoD / DoR / User Story (⚙️ Mechanism) · PO+SM = product-lead, 15 cross-functional roles (🏢 Organization) · Sprint = feature stream / async standup = progress + SendMessage / Retro = /agf-release-retro (🔄 Process). Full principles checklist + Scrum vocabulary substitution map: see the §4.4 / §1.6 links above.
Scrum 3-role mapping + 15 AI coworkers. Self-managed, cross-functional — devs self-run Unit + SIT, Reviewers don't touch source, QA doesn't sign business off.
| Scrum role | Project carrier | Notes |
|---|---|---|
| Product Owner | product-lead |
PRD / priority P0/P1 / UAT business signoff |
| Scrum Master | product-lead (PO+SM merged) |
Workflow orchestration / skill enforcement / retro chairing. Agent has no human conflict of interest; merging is reasonable. |
| Development Team | 12 execution / review / QA / post-launch roles (see below) | Self-managed; devs self-run Unit + SIT; ≥2 same-type pending tasks auto fan-out into a Pool (ADR-001) |
| Technical Advisor (not a Scrum role) | tech-lead |
Only intervenes for missing baseline / new tech selection / architecture risk escalation |
| # | Coworker | Personality + responsibility |
|---|---|---|
| 🟠 001 | product-lead |
PO + SM — never codes, only signs. PRD / task assignment / UAT signoff / retro chair |
| 🔵 002 | tech-lead |
Battle-scarred veteran — no alternatives = no decision. Only enters for missing baseline / new tech selection / architecture risk |
| 🟢 003 | frontend-dev |
Components are contracts — React+Vite + Unit + SIT self-run |
| 🟢 004 | backend-dev |
Schema migration PTSD — FastAPI / SQLAlchemy + Unit + SIT self-run |
| 🟢 005 | ai-agent-dev |
Prompts are code — LLM / RAG / Agent + Unit + SIT self-run |
| 🟢 006 | ml-engineer |
Quality-latency-cost triangle — multimodal inference + Unit + SIT self-run |
| 🟢 007 | uiux-designer |
spec.md + index.html dual delivery + AC coverage table |
| 🟢 008 | miniapp-dev |
Native-first, Taro fallback — setData 256KB is the hard wall |
| 🟡 009 | code-reviewer |
Writes only to docs/reviews/ — code review + SIT Audit (4 checks + 3-tier verdict) |
| 🟡 010 | miniapp-code-reviewer |
Zero tolerance for review red lines — wx.* + bundle size + privacy + SIT Audit |
| 🔴 011 | qa-engineer |
Default verdict ❌ — no curl/screenshot/DB diff = no Pass. E2E + UAT |
| 🔴 012 | miniapp-qa-engineer |
E2E without real-device QR scan = no signoff |
| 🟪 013 | content-writer |
Numbers over adjectives, hook in first sentence — release notes / blog |
| 🟪 014 | growth-analyst |
Metrics before instinct — North Star / OMTM / A/B experiments |
| 🩶 015 | deploy-engineer |
Hands on only after merge to main — UAT stack deployment / container orchestration / smoke self-check |
Capability baseline (model / tools / preloaded skills): team-roles.md; end-to-end message flow: team-capability-map.md §2.
Full chain for a feature from requirement to delivery. 6 stage gates progress in order; no skipping on failure.
flowchart LR
U([👤 User]) --> S1["S1 Discovery<br/>brainstorming → PRD"]
S1 --> S2["S2 Dispatch<br/>6-section schema + AC quote"]
S2 --> POOL{"≥2 same-type<br/>pending tasks?"}
POOL -->|yes| FANOUT["⚙️ Pool fan-out<br/>spawn type-1 / type-2 / ...<br/>ADR-001"]
POOL -->|no| S3
FANOUT --> S3["S3 TDD Implementation<br/>red→green→refactor<br/>+ Unit + SIT self-run"]
S3 --> FANIN["agf-matrix.sh<br/>PL fan-in aggregation<br/>(pool mode only)"]
FANIN --> S4["S4 Code Review<br/>+ SIT Audit<br/>3-tier verdict"]
S4 --> S5["S5 E2E<br/>chrome-devtools-mcp<br/>3-tier verdict"]
S5 --> S6["S6 UAT<br/>P0 case pass^2<br/>PL business signoff"]
S6 --> D([🎁 Delivery])
S6 -.->|optional| POST["Post-Launch<br/>content + growth"]
S4 -.block / Redo SIT.-> S3
S5 -.Block.-> S3
S6 -.request changes.-> S3
style U fill:#3b82f6,color:#fff
style S6 fill:#f97316,color:#fff
style D fill:#22c55e,color:#fff
style FANOUT fill:#7c3aed,color:#fff
style FANIN fill:#7c3aed,color:#fff
Full diagram (with subgraphs + mini-program variant + post-launch chain + stage × Hook + stage × Skill + full Pool quick-reference): team-capability-map.md §1.1-§1.7.
| Sprint stage | Who + what | Artifact |
|---|---|---|
| Planning | #001 brainstorming clarifies → PRD → writing-plans plan |
docs/prd/<feature>-<date>.md (10 sections / AC P0/P1) |
| Design | #007 spec.md + standalone HTML prototype + AC coverage table | docs/design/<feature>/{spec.md,index.html} |
| TDD Implementation | #003 + #004 parallel (separate worktrees) → red → green → refactor; ≥2 same-type pending tasks → auto fan-out into a Pool (instances named <type>-N) |
code + tests/sit/ |
| Async Standup | After each Task → append progress/<role>{-N}.md (5 sections: state / Skills / SIT evidence [with AC [x]/[ ] inline] / quality gate / next step); in Pool mode PL fans-in with agf-matrix.sh --type=progress |
progress/*.md |
| Code Review + SIT Audit | #009 dual verdict (code approve / approve with changes / block + SIT Audit Pass / Pass with concerns / Redo SIT); Pool mode -r<N> |
docs/reviews/<feature>(-r<N>)-<date>.md |
| Sprint Review (E2E + UAT) | #011 runs E2E (verdict Promote / Conditional promote / Block) → UAT (P0 case pass^2 / passes 2 times in a row before business signoff approve / request changes); Pool mode -e2e-q<N> / -uat-q<N> |
docs/qa/<feature>-{e2e,uat}(-q<N>)-<date>.md |
| Signoff + archive | #001 business signoff → archive-progress.sh archives progress |
docs/qa/<feature>-process-log.md |
| Retrospective (MAJOR/MINOR) | #001 /agf-release-retro vX.Y.Z (7 steps + §5 Owner+Due mandatory) |
docs/reviews/retro-vX.Y.Z-<date>.md |
- 1 User Story = 1~N Tasks, split by role boundary (FE/BE/AI/ML), not by AC; each Task has ≥1 AC, quoted verbatim in SendMessage
- Task granularity = closed-loop within one session (implement + Unit + AC self-check)
- AC is a leaf, not splittable — if too large, split its "observable outcome"
4 verdict vocabularies (code review / SIT Audit / QA report-level / UAT business signoff; team convention, no improvisation) — see
workflow.md §Verdict 词表.
| Stage gate | Failure verdict | Failure action | Returns to |
|---|---|---|---|
| Code Review | block |
PL re-dispatches execution layer to fix | S3 |
| SIT Audit | Redo SIT |
PL combines re-dispatch (with code fix) | S3 (does not progress to E2E) |
| E2E | Block / Conditional promote |
qa reports → PL re-dispatches | S3 (does not progress to UAT) |
| UAT business signoff | request changes |
PL re-dispatches | S3 |
| P0 case pass^2 | fails to pass twice in a row | qa withholds signoff, returns to S3 (agf-writing-qa-report enforced) |
S3 |
| Pool single-instance fail | a single -N instance is blocked |
PL respawns that instance (other instances keep running) | local rollback of that -N |
| Pool ≥50% fail | widespread failure | PL aborts the whole batch + PRD review | S1 |
code-reviewer / qa-engineer never touch source directly.
Agile + Scrum + TDD principles are wired into skill / hook / DoD three-layer enforcement — never relying on agent self-discipline.
flowchart LR
PL([🟠 PL dispatches<br/>new feature / bugfix]) --> HOOK["validate-task-schema<br/>6 sections complete"]
HOOK --> SKILL["invoke skill<br/>test-driven-development"]
SKILL --> RED["🔴 red<br/>write failing test<br/>commit: test:"]
RED --> GREEN["🟢 green<br/>minimal impl turns test green<br/>commit: feat: / fix:"]
GREEN --> REFACTOR["🔵 refactor<br/>tidy code, keep green<br/>commit: refactor:"]
REFACTOR --> PR["PR commit history<br/>first test before first impl"]
PR --> CR["code-reviewer<br/>order check"]
CR --> PASS([✅ Proceed to<br/>code review + SIT Audit])
REFACTOR -.iterate.-> RED
CR -.violation = block.-> RED
style PL fill:#f97316,color:#fff
style PASS fill:#22c55e,color:#fff
Skip condition: pure refactor / docs / config tasks can skip TDD order (ac-lifecycle.md DoD line 81–85).
| Layer | Trigger | Action |
|---|---|---|
| 🚫 | Dangerous commands: rm -rf / DROP TABLE / git push --force / git reset --hard |
Hard block |
| 🚫 | Secret leaks: 10 vendor tokens + PEM/SSH/PuTTY/BIP39 mnemonics | Hard block |
| 🚫 | Prompt-injection in external content | Soft warning |
| 🚫 | commit-time staged-diff secret scan | Hard block (Edit/Write bypass backstop) |
| 💡 | Teammate wants idle but task list has pending | Reminder to stay and finish |
| 💡 | Execution layer exits without writing progress/<role>.md |
Block (Daily Standup backstop) |
| 💡 | TaskCreate 6-section schema incomplete |
Block (AC quote enforcement) |
| 💡 | Pre-work skill check | Reminder (if not invoked) |
| Stage | Hook (🛑 hard block / |
Skill (mandatory / recommended) |
|---|---|---|
| prompt submit | 🛑 scan-secrets (10 vendor secrets + PEM/SSH/PuTTY/BIP39) |
— |
| S1 discovery + PRD | — | brainstorming (mandatory if vague/multi-option)agf-writing-prd |
| S2 dispatch | 🛑 validate-task-schema (6 sections + AC quote) |
writing-plans (≥3 AC / cross-role)using-git-worktrees (≥2 dev parallel mandatory)Pool fan-out (≥2 same-type pending tasks / ADR-001) |
| S3 implementation tool use | 🛑 block-dangerous-bashBash: rm -rf / DROP TABLE / push --force / reset --hardsanitize-tool-outputWebFetch/WebSearch/Read/Bash/mcp__* output prompt-injection warning |
test-driven-development mandatory (new feature/bugfix)agf-running-sit-tests (after Unit)systematic-debugging (on bug)verification-before-completion (before report) |
| S3 exit/idle | 🛑 check-progress-file (no progress entry → block)🛑 teammate-keepalive (idle while pending → block) |
— |
| git commit | 🛑 scan-commit (staged diff same secret regex) |
— |
| S4 review | — | requesting-code-review (before trigger)receiving-code-review (when bounced back) |
| S5/S6 testing | — | agf-writing-qa-report (E2E/UAT report) |
| post-release (MAJOR/MINOR) |
— | agf-running-release-retro (PATCH auto-aborts) |
Release discipline: MAJOR/MINOR must be tagged in the same session + tag annotation lists tagged-along commits + must run /agf-release-retro. See versioning.md.
Hard block hit → No Equivalent Bypass (must not find equivalent workaround; must SendMessage PL and wait for authorization). See security.md.
Collaboration actions (frequent at runtime): dispatch · fan-out/fan-in · pass^2 · escalate · halt/STOP ⛔ · verify-before-assert · push back · ghost mailbox · spec drift · sweep · mock-first — definitions in product-workflow.md §4.5.
Status indicators (no improvisation): ✅ done · product-workflow.md §4.7.
Prerequisite: Claude Code ≥ v2.1.154 + Agent Teams enabled (setup/init-team.sh validates).
# Unified entry for new & existing projects — interactive TUI (version selection + target dir + preset + confirmation)
# Brand-new projects use the same path: missing dir / non-git target gets mkdir + git init automatically
# git clone this repo first, then run from the AGF repo root:
bash setup/agf-install.sh
# No TTY / CI / scripted — equivalent non-interactive path (also starts from the AGF repo root)
# (for a brand-new project: mkdir -p <dir> && git -C <dir> init first)
bash setup/install-to-existing.sh ~/path/to/your-repo # target must already be a git repo
cd ~/path/to/your-repo
# Optional preset trimming:
# bash setup/customize.sh --preset minimal --yes # remove mini-program trio
# bash setup/customize.sh --preset miniapp-only --yes # remove web execution layer
bash setup/init-team.sh # Day-1 health check
# Try it
/agf-team-start <your first feature>Full Day-1 checklist + prerequisites + pitfalls: docs/FIRST_RUN.md. CLAUDE.md — the installer starts brand-new projects from CLAUDE.example.md automatically.
| Command | Scrum ceremony |
|---|---|
/agf-team-start |
Sprint kickoff |
/agf-uat |
Sprint Review (business signoff) |
/agf-team-stop |
Sprint wrap-up (close execution-layer teammates after UAT) |
/agf-release-retro |
Sprint Retrospective (PATCH auto-aborts) |
/agf-tasks |
Sprint Backlog view |
| Skill | Who / when |
|---|---|
agf-writing-prd |
#001 writing PRD (10 sections + 5 AC rules + completion checklist) |
agf-writing-adr |
#002 recording architecture decisions (alternatives mandatory + version verification) |
agf-wiring-multi-llm-sdk |
#005 integrating DeepSeek/Doubao/Qwen/MiniMax |
agf-running-sit-tests |
Execution-layer devs self-running SIT |
agf-writing-qa-report |
#011 writing E2E/UAT reports |
agf-running-release-retro |
#001 running MAJOR/MINOR retros |
agf-writing-docx-reports |
Programmatic Chinese .docx reports (resolutions / reviews / RFPs) |
agf-writing-pptx-reports |
Programmatic Chinese .pptx decks (policy / public-sector / training) |
agf-writing-github-issue |
File issues in the repo (QA auto-path + locked labels) |
Superpowers suite (everyone can invoke): brainstorming / writing-plans / test-driven-development / systematic-debugging / verification-before-completion / requesting-code-review / receiving-code-review / using-git-worktrees — enforcement points see superpowers.md.
| Script | Who / when |
|---|---|
agf-tasks.sh |
PL views the task-list table (invoked internally by slash /agf-tasks) |
agf-matrix.sh |
PL Pool fan-in aggregation: --type=progress|review|qa three modes, merging N <role>-N.md / -r<N> / -q<N> reports into one table |
archive-progress.sh |
PL archives progress/<role>{-N}.md → docs/qa/<feature>-process-log.md after UAT signoff (supports pool multi-instance merge) |
lint-all.sh |
Repo-wide bash/JSON/YAML lint entry; chained by the pre-commit hook |
| AppGenesisForge | Generic prompt lib | Role-persona lib | Single-agent toolchain | |
|---|---|---|---|---|
| Methodology backbone | ✅ Agile + Scrum + TDD (Organization / Process / Mechanism three layers) | ❌ | ❌ | ❌ |
| Organization | ✅ 15 coworkers + Scrum role mapping | ❌ | ❌ | |
| Process | ✅ PL + 6 stage gates | ❌ | ❌ | |
| Mechanism (TDD enforcement) | ✅ commit order + skill + DoD | ❌ | ❌ | ❌ |
| Mechanism (Hook defense) | ✅ 4 layers | ❌ | ❌ | ❌ |
| Retrospective | ✅ 7 steps + Owner+Due mandatory | ❌ | ❌ | ❌ |
| China LLMs | ✅ DeepSeek/Doubao/Qwen/MiniMax | ❌ | ❌ | depends |
- What it is: 15 AI coworkers + Agile + Scrum + TDD workflow + 4-layer hook defense
- What's unique: Agile + Scrum + TDD principles wired into Organization + Process + Mechanism three-layer landing, never relying on agent self-discipline
- How to use:
/agf-team-start <feature>→ 15 coworkers run the Sprint flow → watch in one tab - Your benefit: ship a feature overnight; artifacts are traceable; stage-gate skipping = failure of duty
Core trade-off: Wire Agile + Scrum + TDD into the enforcement path, not a wiki — the system's most important design choice. Rules forged from real iteration: early on PL raced to write code, Reviewer out-aggressed Dev, QA delivered no evidence — every hook, standard, and skill comes from a real stumble.
| You want to | How |
|---|---|
| Try a fresh project | gh repo create --template pcliangx/AppGenesisForge → ⏱ Day 1 |
| Embed into existing repo | bash setup/agf-install.sh (interactive TUI, all-in-one; neither method overwrites your CLAUDE.md/ADR-000/settings.json); no-TTY fallback: bash setup/install-to-existing.sh ~/your-repo |
| See a real feature with full artifacts | ls docs/training/samples/postcard-feature/ — PRD → ADR → Dispatch → Progress → Review → UAT → Retro → Release notes (illustrative training paths) |
| Give feedback / open PR | 🐛 Issue · 🍴 PR |
| See what changed each release | 📒 CHANGELOG |
.claude/ agents · standards · skills · hooks · commands · scripts · rules
docs/ product-workflow / team-capability-map / PRD·QA·ADR·Review·Retro templates
docs/training/samples/ · evals/ end-to-end worked example (postcard-feature) + per-role baseline JSONL
progress/ execution-layer Self-Reporting drafts (Async Daily Standup)
setup/ install / launch scripts (repo root has zero .sh): agf-install.sh (TUI all-in-one install entry) · install-to-existing.sh (non-interactive core installer, orchestrated by agf-install.sh) · customize.sh (preset trimming) · init-team.sh (Day-1 health check, 10 checks + auto pre-commit install) · agf-team-start.sh (interactive Agent Team launcher)
CLAUDE.example.md project-level CLAUDE.md template (don't confuse with this repo's CLAUDE.md)
Done: see CHANGELOG for per-version details.
Up next:
- More skills: test cases / commit messages / release notes
- More eval baselines: remaining role JSONL coverage
- CI/CD: wire
setup/init-team.shinto GitHub Actions - feature cycle time trend visualization (enabled after ≥3 retros)
MIT — free for commercial use. Structural inspiration from The Agency.
15 AI coworkers · Agile + Scrum + TDD (Organization / Process / Mechanism three-layer landing) · ship a feature overnight
⭐ Star · 🍴 Fork · 🐛 Issue · 📒 CHANGELOG · 🇨🇳 简体中文