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

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.

All files in references/ directory.

Agent Tool Requirements

Each agent requires specific tools based on their responsibilities:

Critical Rules

1. PM runs first and last – PM orchestrates the entire build
2. Feature branches, not agent branches – feature/user-auth not feature/backend
3. Multiple agents per feature – Designer + Frontend collaborate on same branch
4. Bugfix branches for failures – Don’t rebuild, fix targeted issues
5. Iteration reads existing code – PM understands what exists before adding
6. 98% threshold – Conductor iterates until quality passes
7. Runtime verification – “Compiles” ≠ “Works”
8. 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