Nextjs Project Setup

Next.js Project Setup Skill

Overview

This skill orchestrates complete Next.js project setup from scratch, adapting to project complexity. It handles template selection, specifications, design systems, wireframes, implementation, testing, and documentation following Claude Code best practices with optimal token efficiency through progressive disclosure and sub-agent orchestration.

Outcomes:

• Production-ready Next.js project
• Complete design system
• Comprehensive documentation
• Passing tests with TDD approach
• Clean, audited repository

Prerequisites

This skill leverages three global skills containing 3,316 lines of curated knowledge. Reference these skills BEFORE researching:

Global Skills Available:

1. shadcn-ui (1,053 lines) - Component library, dark mode, forms, theming

   • Installation & setup
   • Component categories (forms, layouts, overlays, display)
   • Dark mode implementation
   • Customization patterns
   • Framework integration

2. nextjs (1,129 lines) - Next.js 15+ framework knowledge

   • App Router architecture
   • Server vs Client Components
   • Routing (static, dynamic, parallel, intercepting)
   • Data fetching patterns
   • Metadata & SEO
   • Image/Font optimization
   • Deployment patterns

3. tailwindcss (1,134 lines) - Design system foundation

   • Utility-first approach
   • Design tokens (colors, spacing, typography)
   • Responsive design patterns
   • Dark mode setup
   • Component examples
   • Framework integration

Usage Pattern:

Research_Flow :=
  Query global skills (300-500 tokens)
    ∘ Query MCP tools (200-400 tokens)
    ∘ Targeted reads (500-1000 tokens)
  vs Spawn research agents (8,000 tokens)

Token_Savings := 6,500+ tokens (81% reduction in research phase)

When to Reference:

• Before Phase 1 research (review what's known)
• During design system planning (shadcn + tailwind patterns)
• When selecting components (shadcn workflows)
• For Next.js best practices (nextjs patterns)
• For responsive design (tailwind breakpoints)

Decision Framework

Simple Project Indicators (choose simple path if ≤1 is true):

• Standard website/blog
• No database required
• No custom authentication
• Single tenant
• Simple design requirements

Complex Project Indicators (choose complex path if ≥2 are true):

• Database required (Supabase)
• Custom authentication patterns
• Multi-tenant architecture
• E-commerce features
• Complex/custom design system
• Multiple integrations

User Override: Always ask user to confirm complexity assessment.

Simple Path Workflow

Use when: Quick setup, standard requirements, minimal customization Duration: 15-30 minutes Load: @docs/simple-setup.md

Quick Steps (CoD^Σ)

Template ← Vercel_MCP(search + select)
  ↓
Setup ← {env_vars, config, structure}
  ↓
Components ← Shadcn_MCP(core_components)
  ↓
Design ← {tailwind_config, basic_theme}
  ↓
Docs ← {README, CLAUDE.md}

Execution

1. Assess & Confirm

   • Confirm simple path appropriate
   • Gather basic requirements

2. Load Instructions

   • Follow @docs/simple-setup.md completely
   • Document provides step-by-step guidance

3. Deliverables

   • Installed template
   • Core components configured
   • Basic design system
   • Minimal documentation
   • Ready for development

Complex Path Orchestration

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

MCP Tool Usage Guidelines

Vercel MCP

Purpose: Template discovery, deployment

Workflow:

Search(category, features) → Filter → Compare → Select → Install

Commands:

• List templates: Filter by DB, auth, use case
• Get info: Detailed template features
• Install: npx create-next-app --example <template>

Shadcn MCP

Purpose: Component discovery and installation

Critical Workflow (NEVER skip steps):

Search → View → Example → Install

Registries:

• @ui: Core components (check first always)
• @magicui: Animated components (use sparingly, ≤300ms)
• @elevenlabs: Audio/voice components (if applicable)

Rules:

1. ALWAYS follow Search → View → Example → Install
2. NEVER skip Example step
3. Prioritize @ui for foundation
4. Use @magicui animations sparingly
5. Install one component at a time
6. Verify integration after each install

Example:

# Search
mcp__shadcn__search_items_in_registries([@ui, @magicui], "button")

# View details
mcp__shadcn__view_items_in_registries(["@ui/button"])

# Get example
mcp__shadcn__get_item_examples_from_registries([@ui], "button-demo")

# Install
mcp__shadcn__get_add_command_for_items(["@ui/button"])
# Execute: npx shadcn@latest add button

Supabase MCP

Purpose: Database and auth setup

Critical Rule: NEVER use Supabase CLI, ALWAYS use MCP tools

Workflow:

Schema_Design → Create_Tables → RLS_Policies → Auth_Setup → Edge_Functions

Best Practices:

• Start with staging environment
• Define schema requirements strictly before creating
• Implement RLS policies immediately
• Use server actions for mutations
• Edge functions for API routes
• Follow template auth patterns
• Multi-tenant: additional RLS patterns

21st Dev MCP

Purpose: Component inspiration and discovery

Usage:

• Search for UI inspiration
• Find pre-built components
• Copy-paste-adapt workflow
• Not for installation (manual integration)

Quality Standards & Requirements

Token Efficiency

• Simple path: ≤2000 tokens total
• Complex orchestrator: ≤2500 tokens main context
• Sub-agent reports: ≤2500 tokens each
• Micro-docs: 500-1000 tokens each
• Use CoD^Σ notation where appropriate

TDD Approach

• Iron Law: No code without tests first
• Process: RED (test fails) → GREEN (minimal code) → REFACTOR (improve)
• No Exceptions: "Just this once" is never acceptable
• Validation: All tests must pass before marking complete

Visual Validation

• Required: Every page/component must be visually reviewed
• Check: Render, layout, responsiveness, interactions
• Test: Links, buttons, forms, animations, loading states
• Criteria: Mobile-first, accessible, performant

Documentation

• Comprehensive: CLAUDE.md + folder docs + /docs/*
• Current: Updated continuously throughout project
• Structured: Domain-separated, focused docs
• Referenced: Use @references for cross-linking
• Compressed: Use CoD^Σ where beneficial

Clean Repository

• Organized: Clear folder structure
• Documented: Every folder has purpose
• Audited: Regular cleanup and review
• Tracked: State documented and current

Accessibility

• Standard: WCAG 2.1 AA minimum
• Testing: Use accessibility tools
• Keyboard: Full keyboard navigation
• Screen readers: Proper ARIA labels
• Contrast: Sufficient color contrast

Anti-Patterns (Do NOT Do)

MCP Tools

❌ Using Supabase CLI instead of MCP Why: MCP provides better error messages, type safety, and integrates with Claude Code workflows; CLI bypasses these safeguards and causes integration issues.

❌ Skipping Shadcn Example step Why: Examples reveal real-world usage patterns, edge cases, and integration requirements that prevent bugs discovered only after installation.

❌ Not following Search→View→Example→Install workflow Why: Each step provides critical context (search: availability, view: API, example: usage patterns, install: dependencies); skipping steps causes mismatched expectations and integration failures.

❌ Installing multiple Shadcn components without testing each Why: Components have complex dependencies and theming interactions; testing each individually isolates issues, while bulk installation creates debugging nightmares.

Code Quality

❌ Writing code before writing tests Why: Tests written after code merely confirm existing behavior (not requirements); tests-first ensures implementation meets actual acceptance criteria and catches logic errors early.

❌ Skipping visual validation Why: Automated tests miss layout breaks, responsive issues, animation glitches, and accessibility problems that only appear when humans interact with rendered UI.

❌ Marking tasks complete without verification Why: "Done" without verification creates technical debt and false progress; only passing tests and working demos prove completion.

❌ Using inline custom Tailwind styles Why: Inline styles bypass the design system, create inconsistency, break dark mode, and make theme changes require hunting through every component instead of updating CSS variables.

❌ Hardcoding colors instead of CSS variables Why: Hardcoded colors break theme switching, prevent design system updates, violate accessibility requirements (can't adjust contrast), and create unmaintainable color sprawl.

Documentation

❌ Missing CLAUDE.md files Why: AI agents and developers need project context (conventions, commands, architecture) to work effectively; missing CLAUDE.md causes repeated questions and inconsistent code.

❌ Outdated documentation Why: Stale docs are worse than no docs—they mislead developers into wrong approaches, waste time debugging non-issues, and erode trust in all documentation.

❌ Putting reusable patterns in CLAUDE.md (use skills) Why: CLAUDE.md is project-specific context; reusable patterns belong in skills for discoverability, maintenance, and cross-project sharing. Duplication across projects causes drift.

❌ Force-loading with @path (use skill name references) Why: Direct path references break when files move and bypass progressive disclosure; skill name references enable metadata-first loading and graceful updates.

Project Structure

❌ Monolithic, unorganized code Why: Monoliths slow development (hard to find code), increase bugs (unclear boundaries), prevent parallel work (merge conflicts), and make testing difficult (tangled dependencies).

❌ No clear folder conventions Why: Inconsistent organization wastes time searching for files, creates duplicate implementations (can't find existing code), and makes onboarding painful.

❌ Missing folder-level documentation Why: Folders represent architectural boundaries; undocumented boundaries cause developers to put files in wrong places, violate separation of concerns, and create spaghetti imports.

❌ Bloated, messy repository Why: Repository clutter (unused files, commented code, temp files) obscures actual codebase, slows searches, confuses intent, and signals low quality standards.

Workflow

❌ Sequential execution when parallel is possible Why: Sequential work wastes time (wait for task A to finish B) when tasks are independent; parallel execution uses resources efficiently and delivers faster.

❌ Duplicate research across agents Why: Multiple agents researching same topic wastes tokens, creates inconsistent findings (each agent sees different sources), and delays results unnecessarily.

❌ Bloating main context with research details Why: Main context is finite and expensive; research details (150k token logs, full API docs) crowd out reasoning space. Use subagents for heavy analysis, return summaries only.

❌ Not using sub-agents for isolated tasks Why: Complex tasks in main context pollute with noise (debug logs, search results, intermediate states); subagents isolate noise, return clean summaries, and keep main context focused on high-level coordination.

Sub-Agent Coordination

When to Use Sub-Agents

Use for:

• Parallel research (multiple topics simultaneously)
• Isolated task execution (fresh context)
• Independent feature implementation
• QA validation (continuous monitoring)
• Documentation audit (independent review)

Don't use for:

• Simple linear tasks
• Tasks requiring main conversation context
• Quick one-off operations

Handover Protocol

Pattern:

Main Agent:
  1. Define task clearly
  2. Specify output format and location
  3. List required tools
  4. Set token budget
  5. Dispatch sub-agent
  
Sub-Agent:
  1. Execute task in isolated context
  2. Write concise report
  3. Save to specified location
  4. Signal completion
  
Main Agent:
  1. Read report (not full process)
  2. Continue workflow

Report Template

All sub-agents use this structure:

# [Task Name] Report

## Summary (1-2 sentences)
[Key finding or recommendation]

## Key Findings
- Finding 1
- Finding 2
- Finding 3

## Recommendations
[Specific, actionable recommendations]

## Details
[Supporting information, kept concise]

## References
[Sources, if applicable]

Target: 1500-2500 tokens per report

Agent Token Truncation Protocol

Purpose: Enforce token limits on agent reports to prevent context pollution while preserving critical information

Hard Limit: 2500 tokens per agent report (ENFORCED)

Automatic Truncation Behavior:

When an agent report approaches 2500 tokens:

1. Keep (Priority Order):

   • Executive summary (1-2 sentences)
   • Key findings (bullet points, max 5)
   • Actionable recommendations (specific, concise)
   • Critical errors or blockers
   • File:line references for evidence

2. Truncate (Deprioritize):

   • Detailed examples (keep brief versions only)
   • Verbose explanations (compress to essentials)
   • Redundant context (already in main conversation)
   • Step-by-step process details (unless critical)
   • Extensive code snippets (keep signatures/interfaces only)

3. Truncation Marker:

   [TRUNCATED at 2500 tokens - Request [CONTINUE: section-name] for more details]
   
   Available sections for continuation:
   - detailed-examples: Full code examples with explanations
   - process-steps: Step-by-step implementation details
   - alternative-approaches: Other solutions considered
   - edge-cases: Additional scenarios and handling
   

Continuation Mechanism:

Main agent can request additional details:

[CONTINUE: detailed-examples]

Reason: Need to understand implementation approach
Focus: Color palette generation algorithm

Agent responds with focused continuation (≤1500 tokens):

# Continuation: Detailed Examples

[Focused content for requested section only]

[END CONTINUATION - Request [CONTINUE: section-name] for other sections]

Token Budget Breakdown (for 2500 token reports):

• Executive summary: 100-150 tokens
• Key findings: 300-400 tokens (5 bullets × 60-80 tokens each)
• Recommendations: 200-300 tokens
• Details: 1500-1700 tokens (truncated if needed)
• References: 200-300 tokens

Enforcement Rules:

• Agents MUST check token count before returning report
• IF report > 2500 tokens → automatic truncation with marker
• Main agent CAN request continuation (unlimited follow-ups)
• Each continuation ≤1500 tokens (focused on specific section)
• NO agent report may exceed 2500 tokens in initial response

Example Truncated Report:

# Design System Analysis Report

## Summary
Analyzed 15 design system options. Recommend Option 3 (Tailwind + Shadcn) for token efficiency and flexibility.

## Key Findings
- Option 1 (Material UI): Heavy bundle (250KB), limited customization
- Option 2 (Chakra UI): Good DX, moderate bundle (180KB), theme API verbose
- Option 3 (Tailwind + Shadcn): Minimal bundle (40KB with tree-shaking), full control, CSS variables
- Option 4 (Ant Design): Enterprise features, heavy (300KB), opinionated
- Option 5 (Custom): Maximum flexibility, high maintenance, design debt risk

## Recommendations
1. Use Tailwind CSS + Shadcn UI (Option 3)
   - Rationale: Smallest bundle, full customization, active ecosystem, CSS variables
   - Trade-off: Manual composition vs. pre-built components
2. Initialize with `npx shadcn@latest init` (New York style, CSS variables)
3. Start with 8 core components: button, card, input, label, form, toast, alert, dialog

## Implementation Details

### Color System
CSS variables approach enables theme switching:
```css
:root {
  --primary: 222.2 47.4% 11.2%;
  --secondary: 210 40% 96.1%;
  ...
}

[TRUNCATED at 2500 tokens - Request [CONTINUE: section-name] for more details]

Available sections for continuation:

• component-examples: Full Shadcn component integration examples
• theme-configuration: Complete tailwind.config.ts setup
• dark-mode-implementation: Dark mode strategy with next-themes
• accessibility-patterns: WCAG 2.1 AA compliance approach

References

• Tailwind CSS docs: @global-skills/tailwindcss
• Shadcn UI catalog: @MCP/shadcn
• Analysis file: /tmp/design-system-analysis.json

**Benefits**:
- **Context Efficiency**: Main conversation stays focused (≤2500t per report)
- **Information Preservation**: Full details available on-demand via continuation
- **Clear Signals**: Truncation markers show what's available
- **Flexible Depth**: Main agent controls detail level (request more when needed)

### Agent Clarification Protocol

**Purpose**: Enable agents to request additional information when reports are insufficient

**When Agents Need Clarification**:
- Report lacks critical details for next phase
- Requirements ambiguous or conflicting
- User intent unclear from available context
- Technical approach needs validation
- Edge cases or constraints not specified

**Protocol Markers**:

**1. Request Clarification** (from Agent to Main):
```markdown
[CLARIFY: Specific question here?]

Context: [Brief context why clarification needed]
Options: [If applicable, suggest 2-3 options]
Impact: [What decision this affects]

2. Provide Answer (from Main to Agent):

[ANSWER: Clear, focused response]

Rationale: [Why this decision]
Constraints: [Any limitations or considerations]

3. Request Continuation (for truncated reports):

[CONTINUE: section-name]

Reason: [Why more detail needed]
Focus: [Specific aspect to expand]

Example Exchange:

# Design Agent Report (Phase 4)

## Color Palette Options
... [content truncated at 2500 tokens]

[CLARIFY: Should we prioritize accessibility (WCAG AAA) or brand alignment?]

Context: Brand colors may not meet AAA contrast ratios
Options:
  1. Adjust brand colors slightly for AAA compliance
  2. Use brand colors, meet AA only (still compliant)
  3. Create accessibility-first palette, suggest brand update
Impact: Affects all component theming and documentation

Main Agent Response:

[ANSWER: Prioritize accessibility with Option 1]

Rationale: Accessibility is constitutional requirement (WCAG 2.1 AA minimum)
Constraints: Keep brand colors within 10% adjustment if possible
Next: Proceed with accessibility-first palette, document brand color deltas

Token Limits:

• Clarification request: ≤200 tokens
• Answer: ≤1000 tokens (focused, specific)
• Continuation request: ≤100 tokens
• Continuation response: ≤1500 tokens (additional details)

Rules:

1. One clarification per report maximum (prevents back-and-forth loops)
2. Questions must be specific and actionable
3. Provide 2-3 options when possible (not open-ended)
4. Main agent must answer before agent continues
5. If answer requires user input, main agent queries user first

Handling Edge Cases:

IF agent_needs_clarification AND no_response:
  agent_proceeds_with_best_assumption
  documents_assumption_clearly
  marks_decision_as [ASSUMPTION: rationale]
  enables_easy_rollback

IF multiple_clarifications_needed:
  prioritize_blocking_decisions
  defer_nice-to-have_clarifications
  proceed_with_partial_information

Benefits:

• Prevents agents getting stuck
• Enables informed decision-making
• Documents decision points
• Maintains workflow momentum
• Clear audit trail

Progressive Disclosure Pattern

Principle: Load only what's needed, when needed

Levels:

1. Metadata (always loaded): Skill name/description, available commands
2. Core Instructions (loaded on trigger): This SKILL.md file
3. Phase Docs (loaded on reference): @docs/complex/phase-*.md
4. Templates (loaded as needed): @templates/*.md
5. Sub-agents (dispatched when needed): @agents/*.md

Usage:

# ✓ Correct - reference by name
Use @docs/complex/phase-4-design.md for design system workflow

# ✗ Wrong - don't force-load full paths
Read @~/.claude/skills/nextjs-project-setup/docs/complex/phase-4-design.md

Benefits:

• Minimal token usage
• Focused context
• Faster processing
• Better maintainability

Progressive Loading Budget (Token Allocation):

Total Maximum: ~16,500 tokens (complex path, all levels loaded)

Breakdown by Level:

• Level 1 (Metadata): 30-50 tokens

  • YAML frontmatter (name, description, allowed-tools)
  • Always loaded at session start
  • Cost: Persistent throughout session

• Level 2 (Core Instructions): 2,000-2,500 tokens

  • SKILL.md main body
  • Loaded when skill triggered by description match
  • Cost: One-time per skill invocation

• Level 3 (Phase Docs): 500-1,000 tokens × 4 files = 2,000-4,000 tokens

  • @docs/simple-setup.md (550 lines ~2,500t)
  • @docs/complex/*.md (4 consolidated files, ~1,000t each)
  • Loaded on-demand via @ reference
  • Cost: Only when phase explicitly referenced

• Level 4 (Templates): 200-500 tokens × 5 templates = 1,000-2,500 tokens

  • design-showcase.md, wireframe-template.md, report-template.md, etc.
  • Loaded on-demand when template needed
  • Cost: Only when output format required

• Level 5 (Sub-agents): 2,500 tokens × 3 agents = 7,500 tokens

  • Agent reports (truncated at 2,500t each)
  • Isolated context (100k per agent, returns summary only)
  • Cost: Per agent invocation, main thread receives summary only

Budget Management:

Minimal Path (Simple setup):
  L1 (50t) + L2 (2,500t) + L3 simple-setup (2,500t) = ~5,000t

Typical Path (Complex, 2 phases + 1 agent):
  L1 (50t) + L2 (2,500t) + L3 (2,000t for 2 phases) + L5 (2,500t agent report) = ~7,000t

Maximum Path (Complex, all 8 phases + 3 agents):
  L1 (50t) + L2 (2,500t) + L3 (4,000t all phases) + L4 (2,500t templates) + L5 (7,500t all agents) = ~16,500t

Safety Margin: ~3,500t reserved for user context and conversation

Cost Optimization Strategies:

1. Load Selectively: Only reference phases actually needed (skip irrelevant phases)
2. Template Reuse: One template loaded, reused multiple times (no re-loading)
3. Agent Truncation: 2,500t summaries instead of 100k full context per agent
4. Depth Limiting: Max 5 levels prevents exponential cascade
5. User Context: Reserve tokens for user messages and conversation flow

Token Budget Violations:

• IF budget > 16,500t → review unnecessary imports
• IF agent reports > 2,500t → enforce truncation protocol
• IF depth > 5 → block import with error
• IF conversation approaching context limit → /compact or offload to sub-agents

…(truncated)