A structured workflow template for building applications with multi-model AI pair programming. Features a multi-session architecture where AI handles design, implementation, and review in separate contexts.
A project scaffold and workflow system for developers who want to:
- Build full-stack applications with AI assistance
- Maintain code quality through structured AI collaboration
- Keep AI context focused and manageable
- Scale from solo development to team workflows
- Use spec-driven development with OpenSpec integration
| Feature | Description |
|---|---|
| Three-Session Model | A (Architect) → B (Implementer) → C (Reviewer) |
| Discovery Framework | A Session interviews users before designing |
| State Tip System | All sessions display workflow status on start |
| Self-Test Workflow | B Session runs servers and tests like a real developer |
| MCP/agent Testing | Prefer MCP/agent browser tools for frontend visual checks |
| PR & Bugfix Mode | B Session creates PR, then fixes issues until approved |
| OpenSpec Integration | Spec-driven development with detailed specifications |
| Model-agnostic | A/B/C roles are independent of any specific vendor |
┌─────────────────────────────────────────────────────────────────────┐
│ DESIGN_STATE.yaml │
│ (Single Source of Truth) │
│ │
│ Sections: │
│ • workflow_state - Current phase & session status │
│ • project_analysis - Auto-detected frontend/backend/env │
│ • discovery - User interview results │
│ • architecture - Tech stack decisions │
└───────────────────────────────┬─────────────────────────────────────┘
│
╔═══════════════════════════╧═══════════════════════════╗
║ PHASE 0: SESSION START ║
║ All sessions display STATE TIP on start ║
╚═══════════════════════════╤═══════════════════════════╝
│
╔═══════════════════════════╧═══════════════════════════╗
║ PHASE 1: DISCOVERY (New Projects) ║
║ A Session asks about: users, tech, vision, constraints║
╚═══════════════════════════╤═══════════════════════════╝
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ A SESSION │ │ B SESSION │ │ C SESSION │
│ (Reasoning) │ │ (Execution) │ │ (Review) │
│ │ │ │ │ │
│ • Discovery │──────▶│ • Fill TODOs │──────▶│ • Review │
│ • Design │ │ • Self-Test │ │ • Validate │
│ • Skeleton │◀──────│ • Create PR │◀──────│ • Report │
│ │ │ • Bugfix │ │ │
└───────────────┘ └───────────────┘ └───────────────┘
| Session | Model | Role | Responsibilities |
|---|---|---|---|
| A | Reasoning model | Architect | Discovery interview, design, skeleton code with TODOs, user-friendly error UX |
| B | Execution model | Implementer | Fill TODOs, self-test (incl. invalid inputs), create PR, bugfix mode |
| C | Review model | Reviewer | Validate constraints, find issues, approve PR |
Before designing, A Session conducts a discovery interview to understand:
📱 WHO WILL USE THIS APP?
• Age range, tech level, accessibility needs
🔧 YOUR TECHNICAL BACKGROUND
• Frontend/backend experience, existing resources
🎯 YOUR PRODUCT VISION
• Core problem, MVP scope, design style
⚠️ CONSTRAINTS
• Budget, compliance, integrations
Results are stored in discovery section of DESIGN_STATE.yaml.
Every session displays workflow status on start:
╔══════════════════════════════════════════════════════════════════╗
║ 🚀 AI DEVELOPMENT WORKFLOW ║
╠══════════════════════════════════════════════════════════════════╣
║ Current Phase: implementation ║
║ Project: My Awesome App ║
╠══════════════════════════════════════════════════════════════════╣
║ SESSION STATUS ║
║ ┌────────────┬────────────┬────────────┐ ║
║ │ A Session │ B Session │ C Session │ ║
║ │ waiting │ ▶ ACTIVE │ pending │ ║
║ └────────────┴────────────┴────────────┘ ║
╠══════════════════════════════════════════════════════════════════╣
║ 👉 NEXT: B Session should implement and self-test ║
╚══════════════════════════════════════════════════════════════════╝
B Session works like a real developer:
┌─────────────────────────────────────────────────────────────────┐
│ COMPLETE B SESSION WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 0: Display State Tip │
│ ↓ │
│ PHASE 1: Environment Check (pause if env vars missing) │
│ ↓ │
│ Fill TODOs + Commit WIP │
│ ↓ │
│ PHASE 2: Backend Self-Test (run server, test APIs) │
│ ↓ │
│ PHASE 3: Frontend Self-Test (MCP/agent) [preferred] │
│ ↓ │
│ PHASE 4: Commit Working Code │
│ ↓ │
│ PHASE 5: Create Pull Request │
│ ↓ │
│ PHASE 6: Bugfix Mode ◄─────────────────────┐ │
│ ↓ (wait for feedback) │ │
│ Fix Issue → Self-Test → Push ──────────────┘ │
│ ↓ (repeat until approved) │
│ PR Approved & Merged → Task Complete │
│ │
└─────────────────────────────────────────────────────────────────┘
If B Session needs environment variables to run:
╔══════════════════════════════════════════════════════════════════╗
║ ⚠️ MISSING ENVIRONMENT VARIABLE - ACTION REQUIRED ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ Variable: DATABASE_URL ║
║ Purpose: PostgreSQL database connection ║
║ Example: postgresql://user:password@localhost:5432/mydb ║
║ ║
║ Please add this to your .env file. ║
║ Reply "ready" when done. ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
⏸️ PAUSED - Waiting for user to configure environment
MCP (Model Context Protocol) is a standard protocol that allows AI assistants to interact with external tools and services, including browser automation for testing.
For projects with frontend (project_analysis.has_frontend: true), B Session should prefer MCP-compatible browser tooling for visual testing:
- Navigate to pages
- Fill forms with mock data
- Click buttons and verify responses
- Test responsive design (mobile/tablet/desktop)
Recommended tools:
- Playwright MCP Server - Browser automation for testing
- Other MCP-compatible browser agents
Fallback: If MCP is unavailable, document the limitation and ask the user to verify manually
After self-test passes, B Session:
- Creates PR with detailed description and self-test results
- Enters bugfix mode - waits for C Session review and user feedback
- Fixes issues → Re-runs self-test → Pushes to PR
- Repeats until PR is approved and merged
your-project/
├── .claude/ # AI Collaboration Hub
│ ├── DESIGN_STATE.yaml # Single source of truth
│ ├── prompts/ # Session system prompts
│ │ ├── A_SESSION.md # Discovery + Design
│ │ ├── B_SESSION.md # Self-test + PR + Bugfix
│ │ └── C_SESSION.md # Review
│ ├── templates/
│ │ ├── INDEX.md # Template guide
│ │ ├── session_start.md # State tip template (NEW)
│ │ ├── discovery_questions.md # Discovery interview (NEW)
│ │ ├── task_handoff.md # A → B
│ │ ├── implementation_report.md
│ │ ├── review_report.md
│ │ └── ...
│ └── handoffs/ # Active iteration docs
│
├── openspec/ # Spec-driven development
│ ├── specs/ # Completed specifications
│ └── changes/ # Active proposals
│
├── apps/
│ ├── backend/ # NestJS backend
│ ├── admin-web/ # Admin dashboard (React)
│ ├── user-web/ # User web app (React)
│ └── mobile/ # Android/iOS
│
└── packages/ # Shared code
├── types/
├── utils/
└── api-client/
git clone https://github.com/yourusername/ai-develop-template.git my-project
cd my-project
pnpm installEdit .claude/DESIGN_STATE.yaml with your project details.
npm install -g @fission-ai/openspec@latestA Session (Reasoning model):
- Open a new AI assistant session
- Paste content from
.claude/prompts/A_SESSION.md - A Session displays state tip, runs discovery interview
- Creates skeleton with TODOs
B Session (Execution model):
- Open new chat
- Paste content from
.claude/prompts/B_SESSION.md - B Session displays state tip, fills TODOs
- Runs self-test (backend API, frontend visual)
- Creates PR, enters bugfix mode
C Session (Review model):
- Open new chat
- Paste content from
.claude/prompts/C_SESSION.md - Reviews code against constraints
- Approves or requests changes
| Template | Purpose |
|---|---|
session_start.md |
State tip display for all sessions (NEW) |
discovery_questions.md |
Discovery interview questions (NEW) |
task_handoff.md |
A → B: Assign tasks with skeleton code |
implementation_report.md |
B → C: Report completed work |
review_report.md |
C → A: Code review results |
question_feedback.md |
B → A: Questions and blockers |
bug_report.md |
Human → A: Testing feedback |
openspec_integration.md |
Spec-driven development guide |
Only DESIGN_STATE.yaml defines the project.
- A Session: Decisions only, no implementation
- B Session: Implementation only, no design changes
- C Session: Review only, no code modifications
B Session works like a real developer:
- Write code → Run server → Test → Fix → Commit working code
B Session pauses and asks user when environment variables are missing.
Fix → Self-test → Push → Repeat until approved.
This template does not lock in any frontend/backend/mobile stack. Instead:
- Respect user preference when specified.
- Recommend (don’t enforce) 1–2 viable stacks if the user asks for guidance.
- Use latest stable/LTS versions and follow official best practices.
- Maintain AGENTS.md/AGENT.md in module directories so other models can collaborate cleanly.
When a feature spans frontend/backend:
- Minimum: Provide Docker deployment guidance (Dockerfile/compose).
- Preferred: Provide Vercel deployment guidance when a web frontend exists.
- Environment Variables: Document required env vars for each runtime (local, Docker, Vercel).
- Code Review: Verify env var list and deployment notes are present before merge.
| Layer | Technology |
|---|---|
| Backend | NestJS (TypeScript) |
| Frontend | React 18 + Tailwind |
| State | Zustand |
| API Client | TanStack Query |
| Mobile | Kotlin Compose / SwiftUI |
| Database | PostgreSQL + Prisma |
| Visual Testing | MCP/agent browser tools (preferred) |
All choices are customizable in DESIGN_STATE.yaml.
- Templates INDEX - All templates explained
- Session Start - State tip template
- Discovery Questions - Interview framework
- OpenSpec Integration - Spec-driven development
Contributions welcome! Please read the templates to understand the workflow before submitting PRs.
MIT License - feel free to use for personal or commercial projects.
Built for developers who want AI to enhance, not replace, their workflow.