Turkey Build
⚡ Quick Start (REQUIRED)
First time in a new project? Two-step process:
Step 1: Bootstrap
/turkey-build
# Creates: .claude/settings.local.json, git init, branches
# Then tells you to restart
Step 2: Restart & Build
# Exit Claude Code (Ctrl+C or /exit)
claude
/turkey-build
# Now agents have permissions and will work!
Why restart? Permissions load when Claude Code starts, not mid-session.
If agents fail with "Permission denied" → You skipped the restart. Exit and re-run claude.
STOP. READ THESE FILES FIRST.
Before writing ANY code, you MUST read these files in order:
1. references/ORCHESTRATION.md ← HOW to run the build (features, branches, flow)
2. references/PM-AGENT.md ← PM orchestrates everything
3. references/AIMEM-INTEGRATION.md ← HOW agents coordinate through memory
DO NOT use the summaries below as your guide. They are overviews only.
DO read the full reference files - they contain the actual implementation details.
What This Skill Does
Say "build me X" → Get production-ready, runtime-verified code.
Key Differentiators:
- Feature branches - Branches per feature, not per agent
- PM orchestration - PM scopes features, assigns agents, delivers release
- Greenfield + iteration - Same workflow for new builds and adding features
- aimem coordination - Agents signal completion, PM coordinates
- 98% quality gate - Conductor won't ship below threshold
- Runtime verification - Actually starts the app, hits endpoints, verifies
- Bugfix branches - Runtime/Conductor failures get targeted fixes
Execution Flow
🦃 BOOTSTRAP (runs first!)
- Create .claude/settings.local.json with agent permissions
- Initialize git, set user config
- Create main + develop branches
- Initial commit if empty
│
▼
PM Agent reads requirements (or existing code + request)
│
▼
PM outputs scope.yaml with features:
- feature/core-daemon (backend)
- feature/api-server (backend, devops)
- feature/web-dashboard (designer, frontend)
- feature/documentation (docs)
│
▼
For each feature (in dependency order):
┌─────────────────────────────────────┐
│ Create feature/* branch │
│ Dispatch assigned agents │
│ Agents collaborate on same branch │
│ Merge to develop when complete │
└─────────────────────────────────────┘
│
▼
Review Wave (parallel on develop):
QA, Security, CodeReview, Performance
│
▼
Runtime Verification:
Start server → Hit endpoints → Verify responses
Failures → BUGFIX-AGENT → Trace → Fix → Re-verify
│
▼
Data Flow Verification:
Schema sync → Placeholder detection → Data trace
Verify real data flows DB → API → UI (no "Unknown")
Failures → BUGFIX-AGENT → Trace → Fix → Re-verify
│
▼
E2E Browser Testing:
Open browser → Click through UI → Verify user flows
Verify ACTUAL DATA displayed (not just elements exist)
Capture screenshots (3 viewports × all pages × states)
Failures → BUGFIX-AGENT → Trace → Fix → Re-test
│
▼
Visual QA Analysis:
Demo Agent calls Visual QA Agent
Analyze screenshots using Claude vision
Detect CSS bugs, layout issues, responsive problems
Critical issues → BUGFIX-AGENT → Fix CSS → Re-capture
│
▼
Conductor Score:
< 98% → BUGFIX-AGENT → Trace → Fix → Re-score
≥ 98% → merge develop → main → tag release
Branch Types
| Prefix |
Purpose |
Example |
feature/* |
New functionality |
feature/user-auth |
bugfix/* |
Runtime/Conductor failures |
bugfix/empty-dashboard |
develop |
Integration branch |
Always deployable |
main |
Production releases |
Tagged versions only |
Seven Modes
Greenfield (New Build)
User: "Build a clipboard history manager"
PM: Scopes 5 features → Builds each → Review → Ship v1.0.0
Iteration (Add Features)
User: "Add date filtering and export to the clipboard manager"
PM: Reads existing code → Scopes 2 new features → Builds each → Review → Ship v1.1.0
Bugfix (Fix Issues)
User: "Cards not showing in battle view"
PM: Creates bugfix branch → BUGFIX-AGENT traces → Finds root cause → Fixes → Verifies
Refactor (Restructure Code)
User: "Clean up the auth code" / "Split the god file"
PM: Analyzes structure → Plans refactor → Restructures → Verifies behavior unchanged
UI Polish (Visual Cleanup)
User: "Make the UI look better" / "Fix the messy CSS"
PM: Visual QA scan → Designer reviews → CSS cleanup → Component polish → Responsive fixes
Migration (Upgrade Dependencies)
User: "Upgrade to React 19" / "Move from Express to Hono"
PM: Audit current → Plan migration → Update incrementally → Test each step → Verify
Audit (Analysis Only)
User: "Review security" / "Check performance" / "Analyze code quality"
PM: Runs relevant agents → Produces report → No code changes unless requested
Same workflow. PM routes to different agents based on task type.
Agent Reference Files
PM reads all agent files. Other agents read their own file.
| Agent |
File |
Role |
| PM |
PM-AGENT.md |
Orchestrator - Scopes features, assigns agents |
| Discovery |
DISCOVERY-AGENT.md |
Requirements → scope.yaml (called by PM) |
| Designer |
DESIGNER-AGENT.md |
Design tokens, component specs |
| Backend |
BACKEND-AGENT.md |
API, database, services |
| Frontend |
FRONTEND-AGENT.md |
UI components |
| Docs |
DOCS-AGENT.md |
README, API docs, CLAUDE.md |
| DevOps |
DEVOPS-AGENT.md |
Docker, CI/CD |
| QA |
QA-AGENT.md |
Unit/integration tests |
| Security |
SECURITY-AGENT.md |
Vulnerability scanning |
| Code Review |
CODE-REVIEW-AGENT.md |
Quality analysis |
| Performance |
PERFORMANCE-AGENT.md |
Optimization |
| Demo |
DEMO-AGENT.md |
User perspective critique (calls Visual QA) |
| E2E |
E2E-AGENT.md |
Browser testing - Playwright, real user flows, screenshot capture |
| Visual QA |
VISUAL-QA-AGENT.md |
Screenshot analysis - Claude vision, CSS bugs, layout issues |
| Data Flow |
DATA-FLOW-VERIFICATION.md |
Schema sync, placeholder detection, data trace |
| Bugfix |
BUGFIX-AGENT.md |
Systematic debugging - Reproduce, trace, isolate, fix, verify |
| Conductor |
CONDUCTOR-AGENT.md |
Quality gate (98/100 with visual QA dimension) |
All files in references/ directory.
Agent Tool Requirements
Each agent requires specific tools based on their responsibilities:
| Agent |
Required Tools |
Purpose |
| PM |
Bash, Read, Write, Edit |
Git operations, file management, orchestration |
| Discovery |
Read |
Analyze existing code for iteration mode |
| Designer |
Write, Edit |
Create design tokens, semantic registry |
| Backend |
Bash, Read, Write, Edit |
Run migrations, create APIs, database setup |
| Frontend |
Read, Write, Edit |
Read registry/contracts, build UI components |
| Docs |
Read, Write, Edit |
Create README, API docs, CLAUDE.md |
| DevOps |
Bash, Write, Edit |
Docker setup, CI/CD configuration |
| QA |
Bash, Read, Write, Edit |
Run tests, create test files |
| Security |
Bash, Read |
Run security scans, analyze code |
| Code Review |
Read, Edit |
Analyze and refactor code |
| Performance |
Bash, Read, Edit |
Profile code, optimize queries |
| Demo |
Read |
Analyze from user perspective |
| E2E |
Bash, Read, Write, Edit |
Playwright setup, browser tests, add data-testid |
| Bugfix |
Bash, Read, Write, Edit |
Trace data flow, diagnose root cause, apply fixes |
| Conductor |
Read |
Score quality, make ship decisions |
Critical Rules
- PM runs first and last - PM orchestrates the entire build
- Feature branches, not agent branches -
feature/user-auth not feature/backend
- Multiple agents per feature - Designer + Frontend collaborate on same branch
- Bugfix branches for failures - Don't rebuild, fix targeted issues
- Iteration reads existing code - PM understands what exists before adding
- 98% threshold - Conductor iterates until quality passes
- Runtime verification - "Compiles" ≠ "Works"
- Data flow verification - No "Unknown" or placeholder data in UI
File Structure
auto-app-builder/
├── SKILL.md # This file (entry point)
├── README.md
├── LICENSE
└── references/
├── ORCHESTRATION.md # ← READ FIRST
├── PM-AGENT.md # ← PM orchestrates
├── AIMEM-INTEGRATION.md # ← Agent coordination
├── DISCOVERY-AGENT.md
├── DESIGNER-AGENT.md
├── BACKEND-AGENT.md
├── FRONTEND-AGENT.md
├── QA-AGENT.md # ← Includes schema sync checks
├── DEVOPS-AGENT.md
├── DEMO-AGENT.md # ← Calls Visual QA for screenshot analysis
├── E2E-AGENT.md # ← Browser testing + screenshot capture
├── VISUAL-QA-AGENT.md # ← NEW: Claude vision screenshot analysis
├── DATA-FLOW-VERIFICATION.md # ← Schema sync, placeholder detection
├── BUGFIX-AGENT.md # ← Systematic debugging methodology
├── CONDUCTOR-AGENT.md # ← Quality gate with Visual QA dimension
├── SECURITY-AGENT.md
├── CODE-REVIEW-AGENT.md
├── PERFORMANCE-AGENT.md
├── DOCS-AGENT.md
├── MEMORY-COORDINATION.md
├── QA-SCORING.md
└── RUNTIME-VERIFICATION.md
License
MIT • TurkeyCode.ai
1---2name: turkey-build3description: Multi-agent app builder with 7 modes - greenfield, iteration, bugfix, refactor, UI polish, migration, and audit. PM orchestrates specialized agents with feature branches. 98%+ quality gate, runtime verified, visual QA.4license: MIT5---67# Turkey Build89## ⚡ Quick Start (REQUIRED)1011**First time in a new project?** Two-step process:1213### Step 1: Bootstrap14```bash15/turkey-build16# Creates: .claude/settings.local.json, git init, branches17# Then tells you to restart18```1920### Step 2: Restart & Build21```bash22# Exit Claude Code (Ctrl+C or /exit)23claude24/turkey-build25# Now agents have permissions and will work!26```2728**Why restart?** Permissions load when Claude Code starts, not mid-session.2930**If agents fail with "Permission denied"** → You skipped the restart. Exit and re-run `claude`.3132---3334## STOP. READ THESE FILES FIRST.3536Before writing ANY code, you MUST read these files in order:3738```391. references/ORCHESTRATION.md ← HOW to run the build (features, branches, flow)402. references/PM-AGENT.md ← PM orchestrates everything413. references/AIMEM-INTEGRATION.md ← HOW agents coordinate through memory42```4344**DO NOT** use the summaries below as your guide. They are overviews only.45**DO** read the full reference files - they contain the actual implementation details.4647---4849## What This Skill Does5051Say "build me X" → Get production-ready, runtime-verified code.5253**Key Differentiators:**54- **Feature branches** - Branches per feature, not per agent55- **PM orchestration** - PM scopes features, assigns agents, delivers release56- **Greenfield + iteration** - Same workflow for new builds and adding features57- **aimem coordination** - Agents signal completion, PM coordinates58- **98% quality gate** - Conductor won't ship below threshold59- **Runtime verification** - Actually starts the app, hits endpoints, verifies60- **Bugfix branches** - Runtime/Conductor failures get targeted fixes6162---6364## Execution Flow6566```67🦃 BOOTSTRAP (runs first!)68 - Create .claude/settings.local.json with agent permissions69 - Initialize git, set user config70 - Create main + develop branches71 - Initial commit if empty72 │73 ▼74PM Agent reads requirements (or existing code + request)75 │76 ▼77PM outputs scope.yaml with features:78 - feature/core-daemon (backend)79 - feature/api-server (backend, devops)80 - feature/web-dashboard (designer, frontend)81 - feature/documentation (docs)82 │83 ▼84For each feature (in dependency order):85┌─────────────────────────────────────┐86│ Create feature/* branch │87│ Dispatch assigned agents │88│ Agents collaborate on same branch │89│ Merge to develop when complete │90└─────────────────────────────────────┘91 │92 ▼93Review Wave (parallel on develop):94 QA, Security, CodeReview, Performance95 │96 ▼97Runtime Verification:98 Start server → Hit endpoints → Verify responses99 Failures → BUGFIX-AGENT → Trace → Fix → Re-verify100 │101 ▼102Data Flow Verification:103 Schema sync → Placeholder detection → Data trace104 Verify real data flows DB → API → UI (no "Unknown")105 Failures → BUGFIX-AGENT → Trace → Fix → Re-verify106 │107 ▼108E2E Browser Testing:109 Open browser → Click through UI → Verify user flows110 Verify ACTUAL DATA displayed (not just elements exist)111 Capture screenshots (3 viewports × all pages × states)112 Failures → BUGFIX-AGENT → Trace → Fix → Re-test113 │114 ▼115Visual QA Analysis:116 Demo Agent calls Visual QA Agent117 Analyze screenshots using Claude vision118 Detect CSS bugs, layout issues, responsive problems119 Critical issues → BUGFIX-AGENT → Fix CSS → Re-capture120 │121 ▼122Conductor Score:123 < 98% → BUGFIX-AGENT → Trace → Fix → Re-score124 ≥ 98% → merge develop → main → tag release125```126127---128129## Branch Types130131| Prefix | Purpose | Example |132|--------|---------|---------|133| `feature/*` | New functionality | `feature/user-auth` |134| `bugfix/*` | Runtime/Conductor failures | `bugfix/empty-dashboard` |135| `develop` | Integration branch | Always deployable |136| `main` | Production releases | Tagged versions only |137138---139140## Seven Modes141142### Greenfield (New Build)143```144User: "Build a clipboard history manager"145PM: Scopes 5 features → Builds each → Review → Ship v1.0.0146```147148### Iteration (Add Features)149```150User: "Add date filtering and export to the clipboard manager"151PM: Reads existing code → Scopes 2 new features → Builds each → Review → Ship v1.1.0152```153154### Bugfix (Fix Issues)155```156User: "Cards not showing in battle view"157PM: Creates bugfix branch → BUGFIX-AGENT traces → Finds root cause → Fixes → Verifies158```159160### Refactor (Restructure Code)161```162User: "Clean up the auth code" / "Split the god file"163PM: Analyzes structure → Plans refactor → Restructures → Verifies behavior unchanged164```165166### UI Polish (Visual Cleanup)167```168User: "Make the UI look better" / "Fix the messy CSS"169PM: Visual QA scan → Designer reviews → CSS cleanup → Component polish → Responsive fixes170```171172### Migration (Upgrade Dependencies)173```174User: "Upgrade to React 19" / "Move from Express to Hono"175PM: Audit current → Plan migration → Update incrementally → Test each step → Verify176```177178### Audit (Analysis Only)179```180User: "Review security" / "Check performance" / "Analyze code quality"181PM: Runs relevant agents → Produces report → No code changes unless requested182```183184Same workflow. PM routes to different agents based on task type.185186---187188## Agent Reference Files189190**PM reads all agent files. Other agents read their own file.**191192| Agent | File | Role |193|-------|------|------|194| **PM** | `PM-AGENT.md` | **Orchestrator** - Scopes features, assigns agents |195| Discovery | `DISCOVERY-AGENT.md` | Requirements → scope.yaml (called by PM) |196| Designer | `DESIGNER-AGENT.md` | Design tokens, component specs |197| Backend | `BACKEND-AGENT.md` | API, database, services |198| Frontend | `FRONTEND-AGENT.md` | UI components |199| Docs | `DOCS-AGENT.md` | README, API docs, CLAUDE.md |200| DevOps | `DEVOPS-AGENT.md` | Docker, CI/CD |201| QA | `QA-AGENT.md` | Unit/integration tests |202| Security | `SECURITY-AGENT.md` | Vulnerability scanning |203| Code Review | `CODE-REVIEW-AGENT.md` | Quality analysis |204| Performance | `PERFORMANCE-AGENT.md` | Optimization |205| Demo | `DEMO-AGENT.md` | User perspective critique (calls Visual QA) |206| **E2E** | `E2E-AGENT.md` | **Browser testing** - Playwright, real user flows, screenshot capture |207| **Visual QA** | `VISUAL-QA-AGENT.md` | **Screenshot analysis** - Claude vision, CSS bugs, layout issues |208| **Data Flow** | `DATA-FLOW-VERIFICATION.md` | **Schema sync, placeholder detection, data trace** |209| **Bugfix** | `BUGFIX-AGENT.md` | **Systematic debugging** - Reproduce, trace, isolate, fix, verify |210| Conductor | `CONDUCTOR-AGENT.md` | Quality gate (98/100 with visual QA dimension) |211212All files in `references/` directory.213214---215216## Agent Tool Requirements217218Each agent requires specific tools based on their responsibilities:219220| Agent | Required Tools | Purpose |221|-------|---------------|---------|222| **PM** | Bash, Read, Write, Edit | Git operations, file management, orchestration |223| **Discovery** | Read | Analyze existing code for iteration mode |224| **Designer** | Write, Edit | Create design tokens, semantic registry |225| **Backend** | Bash, Read, Write, Edit | Run migrations, create APIs, database setup |226| **Frontend** | Read, Write, Edit | Read registry/contracts, build UI components |227| **Docs** | Read, Write, Edit | Create README, API docs, CLAUDE.md |228| **DevOps** | Bash, Write, Edit | Docker setup, CI/CD configuration |229| **QA** | Bash, Read, Write, Edit | Run tests, create test files |230| **Security** | Bash, Read | Run security scans, analyze code |231| **Code Review** | Read, Edit | Analyze and refactor code |232| **Performance** | Bash, Read, Edit | Profile code, optimize queries |233| **Demo** | Read | Analyze from user perspective |234| **E2E** | Bash, Read, Write, Edit | Playwright setup, browser tests, add data-testid |235| **Bugfix** | Bash, Read, Write, Edit | Trace data flow, diagnose root cause, apply fixes |236| **Conductor** | Read | Score quality, make ship decisions |237238---239240## Critical Rules2412421. **PM runs first and last** - PM orchestrates the entire build2432. **Feature branches, not agent branches** - `feature/user-auth` not `feature/backend`2443. **Multiple agents per feature** - Designer + Frontend collaborate on same branch2454. **Bugfix branches for failures** - Don't rebuild, fix targeted issues2465. **Iteration reads existing code** - PM understands what exists before adding2476. **98% threshold** - Conductor iterates until quality passes2487. **Runtime verification** - "Compiles" ≠ "Works"2498. **Data flow verification** - No "Unknown" or placeholder data in UI250251---252253## File Structure254255```256auto-app-builder/257├── SKILL.md # This file (entry point)258├── README.md259├── LICENSE260└── references/261 ├── ORCHESTRATION.md # ← READ FIRST262 ├── PM-AGENT.md # ← PM orchestrates263 ├── AIMEM-INTEGRATION.md # ← Agent coordination264 ├── DISCOVERY-AGENT.md265 ├── DESIGNER-AGENT.md266 ├── BACKEND-AGENT.md267 ├── FRONTEND-AGENT.md268 ├── QA-AGENT.md # ← Includes schema sync checks269 ├── DEVOPS-AGENT.md270 ├── DEMO-AGENT.md # ← Calls Visual QA for screenshot analysis271 ├── E2E-AGENT.md # ← Browser testing + screenshot capture272 ├── VISUAL-QA-AGENT.md # ← NEW: Claude vision screenshot analysis273 ├── DATA-FLOW-VERIFICATION.md # ← Schema sync, placeholder detection274 ├── BUGFIX-AGENT.md # ← Systematic debugging methodology275 ├── CONDUCTOR-AGENT.md # ← Quality gate with Visual QA dimension276 ├── SECURITY-AGENT.md277 ├── CODE-REVIEW-AGENT.md278 ├── PERFORMANCE-AGENT.md279 ├── DOCS-AGENT.md280 ├── MEMORY-COORDINATION.md281 ├── QA-SCORING.md282 └── RUNTIME-VERIFICATION.md283```284285---286287## License288289MIT • [TurkeyCode.ai](https://turkeycode.ai)
diegosouzapw