Use when: Database, auth, complex design, multi-tenant, or multiple complex features Duration: 2-4 hours (with user feedback iterations) Pattern: Research ∥ → Template → Spec → Design → Wireframes → Implement ∥ → QA ∥ → Docs

Phase 1: Foundation Research

Progress: [█░░░░░░░] 12.5% (1/8 phases)

<research_phase>

**Purpose**: Gather foundational knowledge using global skills + MCP queries

**Workflow** (CoD^Σ):

Foundation_Knowledge := Review_Global_Skills ∘ Query_MCPs ∘ Synthesize_Context

Global_Skills_Review (300-500 tokens):

1. Reference nextjs global skill → App Router patterns, data fetching, routing
2. Reference shadcn-ui global skill → Component workflows, dark mode, forms
3. Reference tailwindcss global skill → Design tokens, responsive patterns

MCP_Queries (200-400 tokens):

1. Vercel MCP → Available templates (filter by DB/auth requirements)
2. Shadcn MCP → Component registry overview (@ui, @magicui catalogs)
3. Supabase MCP (if DB required) → Project setup patterns
4. 21st Dev MCP → Design inspiration (optional)

Synthesis (500-1000 tokens):

1. Document template options → /reports/foundation-research.md
2. Note component patterns → reference global skills
3. Identify setup requirements → specific to project
4. List design considerations → leverage global knowledge

**Token Comparison**:
- OLD: 4 agents × 2000 tokens each = 8,000 tokens
- NEW: Global skills (500t) + MCP queries (300t) + synthesis (700t) = 1,500 tokens
- **SAVINGS**: 6,500 tokens (81% reduction)

**Output**:
- /reports/foundation-research.md (concise, 700-1000 tokens)
  - Available templates summary
  - Component strategy (reference global skills)
  - Database setup approach (if applicable)
  - Design system starting point

**Key Principle**:
Don't duplicate what's in global skills - REFERENCE them. Main agent can load specific sections when needed.

**Rollback Procedure**:
```bash
# If Phase 1 fails or needs to be restarted:
rm -f reports/foundation-research.md
# Phase 1 can now be re-executed cleanly

When to Rollback:

• MCP queries fail repeatedly
• Global skills not loading properly
• Research synthesis incomplete or incorrect
• User requests different project approach

Phase 2: Template Selection

Progress: [██░░░░░░] 25.0% (2/8 phases)

<template_selection>

**Prerequisites**: @reports/foundation-research.md
**Load**: @docs/complex/phase-2-template.md

**Workflow**:
1. Analyze user requirements against template features
2. Use Vercel MCP to filter templates
3. Present top 3 options with rationale
4. User selects template
5. Install: `npx create-next-app --example <template>`
6. Verify installation and structure

**Outputs**:
- Installed template
- /docs/template-selection.md (rationale, features, setup notes)

**Rollback Procedure**:
```bash
# If Phase 2 fails or wrong template selected:
rm -rf * .[^.]* ..?*  # Remove all files (BE CAREFUL - only in project dir)
rm -f docs/template-selection.md
# OR: cd .. && rm -rf project-name && mkdir project-name && cd project-name
# Return to Phase 1 or retry Phase 2 with different template

When to Rollback:

• Template installation fails
• Wrong template selected
• Template doesn't match requirements
• Need to start fresh with different approach

Phase 3: Specification

Progress: [███░░░░░] 37.5% (3/8 phases)

<specification_phase>

**Prerequisites**: Template installed
**Load**: @docs/complex/phase-3-spec.md

**Workflow** (CoD^Σ):

Product_Spec := use(product-skill) → /docs/product-spec.md Constitution := use(constitution-skill) → /docs/constitution.md Features := { ∀feature ∈ requirements: feature → {description, acceptance_criteria, dependencies} } Audit := review ∧ clarify → user_feedback

**Required Skills**:
- REQUIRED SUB-SKILL: product-skill
- REQUIRED SUB-SKILL: constitution-skill

**Outputs**:
- /docs/product-spec.md
- /docs/constitution.md
- /docs/features.md
- /docs/architecture.md

**Rollback Procedure**:
```bash
# If Phase 3 fails or specifications need major revision:
rm -f docs/product-spec.md
rm -f docs/constitution.md
rm -f docs/features.md
rm -f docs/architecture.md
# Keep template and template-selection.md
# Return to Phase 3 start or Phase 2 if template needs change

When to Rollback:

• Specifications fundamentally flawed
• Major scope change required
• User rejects specification direction
• Need to restart specification from scratch

Phase 4: Design System Ideation

Progress: [████░░░░] 50.0% (4/8 phases)

<design_system_phase>

**Prerequisites**: Specifications, shadcn-ui global skill, tailwindcss global skill
**Load**: @docs/complex/phase-4-design.md

**Tools**: Shadcn MCP, 21st Dev MCP
**Pattern**: Brainstorm → Showcase → Iterate → Finalize

**Workflow**:
1. **Brainstorm** (reference global skills + dispatch @.claude/agents/nextjs-design-ideator.md):
   - Review tailwindcss global skill → color systems, design tokens, responsive patterns
   - Review shadcn-ui global skill → component theming, dark mode, customization
   - Create design options:
     - Color palettes (3-4 options based on tailwind patterns)
     - Typography systems (2-3 options using tailwind scales)
     - Component styles (2-3 directions leveraging shadcn customization)
     - Layout patterns (referencing tailwind grid/flex utilities)

2. **Showcase**:
   - Create design-showcase page
   - Display all variations visually
   - Use @templates/design-showcase.md

3. **User Feedback Loop** (max 3 iterations):
   - Present showcase to user
   - Gather specific feedback
   - Refine based on feedback
   - **Iteration Limit**: Maximum 3 iterations
   - **If iteration 3 reached AND not approved**:
     - Proceed with best available option from iterations
     - Document user concerns in /docs/design-system.md
     - Mark concerns for future improvement
     - DO NOT continue iterating indefinitely

4. **Finalize**:
   - Document chosen system in /docs/design-system.md
   - Configure Tailwind (CSS variables only)
   - Set up Shadcn component structure
   - Import base components via Shadcn MCP

**Critical Rules**:
- Use global Tailwind CSS variables ONLY
- No inline custom styles
- Follow Shadcn workflow: Search → View → Example → Install
- Prioritize @ui registry for core components
- Use @magicui sparingly (subtle animations ≤300ms)

**Outputs**:
- /docs/design-system.md
- tailwind.config.ts with CSS variables
- components.json configured
- Base components installed

**Rollback Procedure**:
```bash
# If Phase 4 fails or design direction needs complete change:
rm -f docs/design-system.md
git checkout tailwind.config.ts  # Restore to template default
git checkout components.json     # Restore to template default
rm -rf components/ui/*           # Remove installed Shadcn components
# OR: git reset --hard HEAD      # If all design work needs rollback
# Return to Phase 4 start with fresh design direction

When to Rollback:

• Design direction rejected by user
• Shadcn components incompatible
• Need to restart with different design system
• Tailwind configuration conflicts

Phase 5: Wireframes & Asset Management

Progress: [█████░░░] 62.5% (5/8 phases)

<wireframes_phase>

**Prerequisites**: Design system, specifications
**Load**: @docs/complex/phase-5-wireframes.md

**Pattern**: Assets → Wireframes → Iterate

**5.1 Image Asset Management**:

IF user_provides_images THEN:

1. Inventory ← list(all_images)
2. ∀image:
   • Describe(image)
   • Rename(descriptive_name)
   • Categorize(purpose)
3. Document → /assets/inventory.md
4. Reference in wireframes ELSE: Note missing assets in wireframes

**5.2 Wireframe Generation**:
1. **Brainstorm Options**:
   - Create 2-3 layout variations per major page
   - Use text-based wireframes (detailed)
   - Reference design system components
   - Include image placeholders with @asset references

2. **Template**: Use @templates/wireframe-template.md

3. **User Feedback Loop** (max 3 iterations):
   - Present wireframe options to user
   - Discuss pros/cons of each approach
   - Refine based on UX/conversion/accessibility feedback
   - **Iteration Limit**: Maximum 3 iterations
   - **If iteration 3 reached AND not approved**:
     - Proceed with best available option from iterations
     - Document user concerns in /docs/wireframes/concerns.md
     - Mark layout decisions as "provisional, pending future refinement"
     - DO NOT continue iterating indefinitely

4. **Expert Evaluation** (for each option):
   - UX best practices
   - Conversion optimization
   - Accessibility (WCAG 2.1 AA)
   - Mobile-first approach
   - SEO considerations

**Outputs**:
- /docs/wireframes/*.md (one file per page/section)
- /assets/inventory.md (if images provided)
- Finalized layouts approved by user

**Rollback Procedure**:
```bash
# If Phase 5 fails or wireframes need major revision:
rm -rf docs/wireframes/
rm -f assets/inventory.md
# Keep design system from Phase 4
# Return to Phase 5 start or Phase 4 if design system also needs revision

When to Rollback:

• Wireframe layouts rejected
• Asset management issues
• Need to restart with different layout approach
• Major UX/accessibility concerns discovered

Phase 6: Implementation

Progress: [██████░░] 75.0% (6/8 phases)

<implementation_phase parallel="true">

**Prerequisites**: Wireframes, design system, template
**Load**: @docs/complex/phase-6-implement.md

**Pattern**: TDD + Parallel + Visual Validation

**Core Principles**:
1. **TDD Mandatory**: Tests before implementation, no exceptions
2. **Visual Validation**: Every page reviewed before marking complete
3. **Interaction Testing**: All links, buttons, animations validated
4. **Parallel Execution**: Independent features via sub-agents

**Workflow** (CoD^Σ):

∀feature ∈ features: Tests ← define(acceptance_criteria) FIRST Implementation ← code(feature) | tests_pass Components ← Shadcn_MCP(Search → View → Example → Install) Visual_Review ← validate(render ∧ interactions ∧ responsiveness) âœ" ⇔ (tests_pass ∧ visual_validated ∧ interactions_work)

Parallel := { features[independent] ∥ via sub-agents, qa_agent ∥ validation }

Database (if applicable): Supabase_MCP ONLY (never CLI) Schema → RLS → Edge_Functions Server_Actions for mutations

**Component Management**:
- Use Shadcn MCP for all components
- Prefer Magic UI registry for enhanced components
- Follow: Search → View → Example → Install (never skip Example)
- Global Tailwind CSS variables (no hardcoded colors)

**Database Setup** (if applicable):
- Use Supabase MCP tools ONLY
- Start with staging environment
- Define schema requirements strictly
- Implement RLS policies
- Follow template auth patterns
- Multi-tenant: additional patterns per template

**Testing Setup**:
- Linting configuration
- GitHub workflows / CI/CD
- Test framework setup
- Visual regression testing

**Outputs**:
- Complete codebase
- Passing test suite
- Visually validated pages
- Database schema (if applicable)
- CI/CD configured

**Rollback Procedure**:
```bash
# If Phase 6 fails or implementation needs restart:
# Option 1: Soft rollback (keep some work)
git status                          # Review changes
git stash                           # Stash current work
git reset --hard HEAD~N             # Reset N commits back
git stash pop                       # Optionally restore parts

# Option 2: Hard rollback (nuclear option)
git reset --hard <commit-before-phase-6>  # Reset to before Phase 6
git clean -fd                             # Remove untracked files

# Option 3: Selective rollback
git revert <commit-hash>            # Revert specific commits

# After rollback:
npm install                         # Restore dependencies if needed
# Return to Phase 6 start with clean state

When to Rollback:

• Tests failing consistently
• Implementation approach fundamentally flawed
• Database schema needs complete redesign
• Need to restart with different architecture

Phase 7: Quality Assurance (Parallel)

Progress: [███████░] 87.5% (7/8 phases)

<qa_phase parallel="true">

**Prerequisites**: Implementation in progress
**Load**: @docs/complex/phase-7-qa.md
**Agent**: @.claude/agents/nextjs-qa-validator.md (runs continuously)

**Validation Checklist**:

**Critical (Must Fix)**:
- [ ] All tests passing
- [ ] Visual validation complete
- [ ] All links functional
- [ ] All buttons working
- [ ] All forms submitting
- [ ] All animations smooth (≤300ms)
- [ ] Mobile responsive
- [ ] Accessibility compliant (WCAG 2.1 AA)

**Important (Should Fix)**:
- [ ] Performance optimized
- [ ] SEO meta tags
- [ ] Error handling
- [ ] Loading states
- [ ] Empty states

**Process**:
1. QA agent validates continuously
2. Reports issues immediately
3. Implementation agents fix
4. Re-validate
5. No task marked complete until QA ✓

**Outputs**:
- QA report
- Issue tracking
- Resolution verification

**Rollback Procedure**:
```bash
# If Phase 7 identifies critical issues requiring major rework:
# Option 1: Fix issues incrementally (preferred)
git commit -am "WIP: Before QA fixes"  # Save current state
# Fix issues one by one
# Re-run QA validation after each fix

# Option 2: Rollback to last stable state
git log --oneline                   # Find last stable commit
git reset --hard <last-stable-commit>

# Option 3: Return to Phase 6
# Use Phase 6 rollback procedures
# Re-implement with QA feedback in mind

# After rollback:
# Address root causes identified by QA
# Return to implementation with fixes

When to Rollback:

• Too many critical QA failures
• Implementation needs fundamental architectural change
• Accessibility issues require major refactor
• Performance issues require complete redesign

Phase 8: Documentation & Audit

Progress: [████████] 100% (8/8 phases)

<documentation_phase>

**Prerequisites**: Implementation complete, QA passing
**Load**: @docs/complex/phase-8-docs.md
**Agent**: @.claude/agents/nextjs-doc-auditor.md

**Documentation Structure**:

project-root/ ├── CLAUDE.md # Main context (comprehensive) │ ├── Overview (2-3 sentences) │ ├── Tree structure │ ├── Tech stack │ ├── Development workflow │ ├── Skills/commands to use │ ├── MCP tool usage │ ├── Conventions │ └── Anti-patterns ├── /docs/ │ ├── architecture.md # System architecture │ ├── design-system.md # Design tokens │ ├── database-schema.md # DB structure │ ├── product-spec.md # Product requirements │ ├── constitution.md # Project principles │ └── features.md # Feature specifications ├── /components/CLAUDE.md # Component conventions ├── /app/CLAUDE.md # Routing conventions └── /lib/CLAUDE.md # Utility conventions

**CLAUDE.md Template**: Use @templates/claude-md-template.md

**Audit Process**:
1. Doc auditor agent reviews all documentation
2. Checks completeness, accuracy, consistency
3. Verifies file structure compliance
4. Identifies missing docs
5. Cleans up messy files
6. Validates all references work
7. Ensures CoD^Σ used appropriately

**Outputs**:
- Complete documentation hierarchy
- Clean, organized repository
- Audit report
- All references functional

**Rollback Procedure**:
```bash
# If Phase 8 documentation needs complete overhaul:
# Option 1: Restore from backup (if created before Phase 8)
cp -r ../project-backup/* .         # Restore entire project
# OR: git worktree for backup
# git worktree add ../backup <commit-before-phase-8>

# Option 2: Selective documentation rollback
rm -f CLAUDE.md
rm -rf docs/
git checkout HEAD~N -- CLAUDE.md docs/  # Restore N commits ago
# OR: Use git reflog to find exact state

# Option 3: Keep code, regenerate docs
# Keep all implementation and QA work
# Delete only documentation files
rm -f CLAUDE.md
rm -rf docs/*.md
# Return to Phase 8 start with fresh documentation

# Create backup before Phase 8 (prevention):
git tag phase-8-start
git archive --format=tar.gz -o ../project-phase-7-complete.tar.gz HEAD

When to Rollback:

• Documentation structure fundamentally wrong
• Audit reveals major inconsistencies
• Need to restart documentation from scratch
• References broken beyond repair

Prevention (Recommended):

• Create git tag before Phase 8: git tag phase-8-start
• Create backup: tar -czf ../backup-$(date +%Y%m%d).tar.gz .
• Enables safe documentation experimentation