Autonomous Agent Boilerplate for Claude Code

Build entire projects from a single requirements file. This boilerplate doesn't just provide pre-configured agents — it autonomously generates the skills, agents, hooks, and code your project needs using the Spec-Kit-Plus workflow.

📦 What's Included Out of the Box:

• ✅ Spec-Kit-Plus Pre-Installed - Complete .claude/ and .specify/ framework ready to use
• ✅ 69 Production-Ready Components - 15 skills, 13 agents, 29 commands, 9 rules, 7 scripts, 6 templates
• ✅ Clean Slate - No session data, logs, or artifacts - fresh start for every user
• ✅ Multi-User Collaboration - Intelligent TODO merging, contributor tracking, session recovery
• ✅ Session Isolation - .gitignore configured to exclude all session-specific files
• ✅ Quality Gates - Component utilization enforcement, workflow validation, A-F grading
• ✅ Complete Documentation - 2,343 lines of comprehensive guides

---

🚀 The Core Idea

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   YOU WRITE:                        BOILERPLATE GENERATES:                  │
│   ───────────                       ──────────────────────                  │
│                                                                             │
│   requirements/my-app.md    →→→     ✓ Skills for YOUR tech stack           │
│                                     ✓ Agents for YOUR project needs        │
│                                     ✓ Hooks for YOUR workflow              │
│                                     ✓ Complete project with tests          │
│                                     ✓ 80%+ code coverage                   │
│                                     ✓ Security-reviewed code               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

One command. Full project. No manual setup.

claude "/sp.autonomous requirements/my-app.md"

---

📋 Table of Contents

• How It Works
• Quick Start
• The Spec-Kit-Plus Workflow
  • Phase Details
  • What Gets Generated
  • Architecture: Autonomous Enforcement
  • Workflow Status Commands
• Writing Requirements
• Pre-Loaded Components
• Manual Mode (Optional)
• Understanding the Structure
• Customization
• Troubleshooting
• FAQ

---

🎯 How It Works

Step 1: You Write Requirements

Create a simple markdown file describing what you want to build:

# My E-Commerce API

## Features
- User authentication (JWT)
- Product catalog with search
- Shopping cart
- Order processing

## Technical
- Backend: Node.js + Express
- Database: PostgreSQL + Prisma
- Testing: Jest

Step 2: Run One Command

claude "/sp.autonomous requirements/my-app.md"

Note: Spec-Kit-Plus is pre-installed in this boilerplate. The .claude/ and .specify/ directories contain all necessary templates, scripts, and configurations. No initialization required!

Step 3: Boilerplate Takes Over

The autonomous workflow:

1. Verifies Spec-Kit-Plus installation (pre-installed in this boilerplate)
2. Creates feature branch automatically (if on main/master)
3. Analyzes your requirements file
4. Detects technologies (Node.js, Express, PostgreSQL, Prisma, Jest)
5. Generates custom skills for your stack (if needed)
6. Generates specialized agents for your project (if needed)
7. Generates quality hooks for your workflow (if needed)
8. Creates specification, plan, and task breakdown
9. Implements each feature using TDD
10. Reviews code for security and quality
11. Delivers complete project with tests

Result: A production-ready project with 80%+ test coverage, security-reviewed code, proper documentation, and all work done on a feature branch ready for PR.

Automatic Branch Creation

When you start a new autonomous build:

• Checks if you're on main or master branch
• Automatically creates feature/{project-name} branch
• Switches to the new branch for all work
• Sets up remote tracking if origin exists
• Preserves your main/master branch untouched

This ensures best practices: all development happens on feature branches, keeping your main branch clean.

Session Recovery - TODO Persistence + Multi-User Collaboration

Note for new users: This boilerplate starts with a clean slate. Your first session will create the initial TODO state, which then persists across future sessions.

Problem Solved: TODOs are now saved across conversation sessions AND support multiple developers working on the same project!

When you start a new conversation (days/weeks later):

1. Run: bash .claude/scripts/resume-work.sh
2. See all saved TODOs from previous sessions (yours and your teammates')
3. Ask Claude to restore them to your new session

Multi-User Support:

• Intelligent Merge: When multiple people work on the project, their TODOs are merged automatically
• Conflict Resolution: Status priority (completed > in_progress > pending)
• Contributor Tracking: See who created and contributed to each TODO
• History Snapshots: Every session saves a historical snapshot

How It Works:

• TODOs automatically save to .specify/todos.json when session ends
• Merges with existing TODOs from other sessions
• Tracks contributors and maintains history in .specify/todo-history/
• No more lost context when starting fresh conversations

Quick Commands:

# Resume work and see saved TODOs (with collaboration info)
bash .claude/scripts/resume-work.sh

# See who contributed what
python3 .claude/scripts/sync-todos.py contributors

# View historical snapshots
python3 .claude/scripts/sync-todos.py history

# Check TODO status
python3 .claude/scripts/sync-todos.py status

# Manually save TODOs
python3 .claude/scripts/sync-todos.py save

Example Multi-User Flow:

Developer A → Creates 5 TODOs → Session ends → Auto-saves
Developer B → Resumes work → Sees A's TODOs → Adds 3 more → Marks 2 as completed → Auto-merges
Developer A → Returns → Sees combined work from both sessions

See .claude/docs/SESSION-RECOVERY.md for full documentation.

---

🚀 Quick Start

First-Time Setup

1. Clone this boilerplate:

   git clone https://github.com/your-username/claude-code-autonomous-agent-workflow.git
   cd claude-code-autonomous-agent-workflow

2. Your first session will be clean - no pre-existing TODOs or session state

   • .specify/todos.json will be created when you first use TODOs
   • Historical snapshots save to .specify/todo-history/ automatically
   • See .specify/todos.example.json for the data structure
   • Session Isolation: All session-specific files are excluded by .gitignore
   • You start fresh with no inherited session data

3. Start working:

   # Create your requirements file
   cp requirements/example.md requirements/my-app.md
   # Edit requirements/my-app.md
   
   # Run autonomous build
   claude "/sp.autonomous requirements/my-app.md"

Prerequisites

# Claude Code CLI
claude --version

# Node.js 18+ (if building Node.js projects)
node --version

# Python 3.8+ (for TODO sync scripts)
python3 --version

# Git
git --version

Installation

# Clone the boilerplate
git clone https://github.com/your-username/autonomous-agent-boilerplate.git my-project
cd my-project

# Start Claude Code
claude

Your First Autonomous Build

# Create requirements file
mkdir requirements
cat > requirements/my-app.md << 'EOF'
# My Todo App

## Features
- User registration and login
- Create, edit, delete todos
- Mark todos as complete

## Technical
- Frontend: React
- Backend: Express
- Database: SQLite
EOF

# Run autonomous mode
claude "/sp.autonomous requirements/my-app.md"

# Watch it build your entire project!

---

⚙️ The Spec-Kit-Plus Workflow

PREREQUISITE: Spec-Kit-Plus must be pre-installed (.claude/ and .specify/ directories with templates and scripts).

When you run /sp.autonomous, this workflow executes:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SPEC-KIT-PLUS WORKFLOW                              │
│                       (Assumes Pre-Installed Framework)                     │
│                                                                             │
│  VERIFY → ANALYZE PROJECT → ANALYZE REQUIREMENTS → GAP ANALYSIS            │
│                                                       ↓                     │
│                                          GENERATE → TEST → VERIFY           │
│                                                            ↓                │
│                                               CONSTITUTION (ONE)            │
│                                                       ↓                     │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  SIMPLE (1-3 features):     COMPLEX (4+ features):                     │ │
│  │  SPEC → PLAN → TASKS →      For EACH feature:                          │ │
│  │  IMPLEMENT → QA             SPEC → PLAN → TASKS → IMPLEMENT →          │ │
│  │                             UNIT TESTS → INTER-FEATURE TESTS           │ │
│  │                                         ↓                              │ │
│  │                             INTEGRATION QA (All features)              │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                       ↓                                     │
│                                   DELIVER                                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

SIMPLE vs COMPLEX Mode

The workflow automatically detects project complexity:

Mode	Feature Count	Workflow
SIMPLE	1-3 features	Single spec/plan/tasks cycle
COMPLEX	4+ features	Per-feature iteration with inter-feature testing

COMPLEX Mode ensures:

• ONE constitution for the whole project
• Each feature gets its own spec → plan → tasks → implement cycle
• Unit tests run after each feature
• Inter-feature regression tests after feature 2+
• Full integration testing at the end

Phase Details

Phase	What Happens	Output
1. INIT	Create .specify/ and .claude/ directories, setup git	Project structure
2. ANALYZE PROJECT	Inventory existing skills, agents, hooks	project-analysis.json
3. ANALYZE REQUIREMENTS	Parse requirements file, detect technologies	requirements-analysis.json
4. GAP ANALYSIS	Compare required vs existing, identify gaps	gap-analysis.json
5. GENERATE	Create missing skills, agents, hooks	Custom infrastructure
6. TEST	Validate components execute without errors	Functional test report
6.5. QUALITY VALIDATION	Score components against quality criteria	Quality validation report
7. CONSTITUTION	Define project rules and standards	.specify/constitution.md
7.5. FEATURE BREAKDOWN	(COMPLEX only) Break project into features	Feature list with dependencies
8-10. SPEC/PLAN/TASKS	Per-feature (COMPLEX) or whole project (SIMPLE)	.specify/spec.md, plan.md, tasks.md
11. IMPLEMENT	Build using TDD (write tests first)	Source code + unit tests
11.5. FEATURE QA	Verify feature's unit tests pass	Test report
11.6. INTER-FEATURE TESTS	(COMPLEX, 2+ features) Run ALL unit tests	Regression check
12. INTEGRATION QA	Full test suite: unit + integration + E2E	Complete quality report
13. DELIVER	Commit, generate final report	Complete project

Testing Strategy

The workflow enforces a comprehensive testing strategy:

┌─────────────────────────────────────────────────────────────────────────────┐
│                            TESTING PYRAMID                                  │
│                                                                             │
│    Phase 11    │  Feature N unit tests (TDD - write first, then implement)  │
│    Phase 11.5  │  Feature N unit tests (verify implementation passes)       │
│    Phase 11.6  │  ALL unit tests (Feature 1 → N) - catch regressions       │
│    Phase 12    │  ALL unit + integration + E2E tests                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Coverage Requirements:

• 80% minimum for all code
• 100% required for financial, auth, and security code
• All features must pass inter-feature regression tests

What Gets Generated

your-project/
│
├── .specify/                      # Spec-Kit-Plus artifacts
│   ├── project-analysis.json      # Analysis of existing project
│   ├── requirements-analysis.json # Parsed requirements
│   ├── gap-analysis.json          # Missing skills/agents/hooks
│   ├── constitution.md            # Project rules and standards
│   ├── spec.md                    # Detailed specification
│   ├── plan.md                    # Implementation plan
│   ├── data-model.md              # Database schema
│   └── tasks.md                   # Task checklist [X] marked
│
├── .claude/
│   ├── skills/                    # GENERATED for your tech stack
│   │   ├── express-patterns/      # (if Express detected)
│   │   ├── prisma-patterns/       # (if Prisma detected)
│   │   └── react-patterns/        # (if React detected)
│   │
│   ├── agents/                    # GENERATED for your project
│   │   ├── api-builder.md         # (if API project)
│   │   └── frontend-builder.md    # (if frontend project)
│   │
│   ├── hooks/                     # GENERATED for your workflow
│   │   ├── pre-commit.sh
│   │   └── quality-gate.py
│   │
│   ├── logs/autonomous.log        # Build log
│   └── build-reports/             # Final report
│
└── src/                           # YOUR PROJECT CODE
    ├── (generated source files)
    └── (generated test files)

Architecture: How Autonomous Enforcement Works

The workflow is completely self-enforcing with zero human intervention required during execution.

┌─────────────────────────────────────────────────────────────────────────────┐
│                      AUTONOMOUS ENFORCEMENT ARCHITECTURE                     │
│                                                                             │
│  ┌─────────────┐                                                            │
│  │   START     │                                                            │
│  └──────┬──────┘                                                            │
│         ▼                                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  PHASE 0: PRE-CHECK (Always runs first)                             │   │
│  │  ┌─────────────────────────────────────────────────────────────┐   │   │
│  │  │ • Invoke workflow-validator skill                           │   │   │
│  │  │ • Check all phase artifacts                                 │   │   │
│  │  │ • Detect current state (which phase completed)              │   │   │
│  │  │ • Decision: FRESH START or RESUME                           │   │   │
│  │  │ • Fix any skipped phases (violations)                       │   │   │
│  │  └─────────────────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│         ▼                                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  PHASE N: Execute Phase                                             │   │
│  │  ┌─────────────────────────────────────────────────────────────┐   │   │
│  │  │ • Run phase logic                                           │   │   │
│  │  │ • Create phase artifact                                     │   │   │
│  │  │ • Log progress                                              │   │   │
│  │  └─────────────────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│         ▼                                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  AUTO-VALIDATE (Runs after EVERY phase)                             │   │
│  │  ┌─────────────────────────────────────────────────────────────┐   │   │
│  │  │ • Check artifact exists                                     │   │   │
│  │  │ • Validate content integrity                                │   │   │
│  │  │         │                                                   │   │   │
│  │  │    ┌────┴────┐                                              │   │   │
│  │  │    ▼         ▼                                              │   │   │
│  │  │  PASS      FAIL                                             │   │   │
│  │  │    │         │                                              │   │   │
│  │  │    │    ┌────┴────────────────────┐                         │   │   │
│  │  │    │    │  SELF-HEAL (max 3x)     │                         │   │   │
│  │  │    │    │  • Re-run phase         │                         │   │   │
│  │  │    │    │  • Check again          │                         │   │   │
│  │  │    │    │  • If still fail: STOP  │                         │   │   │
│  │  │    │    └─────────────────────────┘                         │   │   │
│  │  │    ▼                                                        │   │   │
│  │  │  Proceed to Phase N+1                                       │   │   │
│  │  └─────────────────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│         ▼                                                                   │
│  ┌─────────────┐                                                            │
│  │  COMPLETE   │                                                            │
│  └─────────────┘                                                            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Key Features of Autonomous Enforcement

Feature	How It Works
Auto-Detection	Phase 0 checks all artifacts to know current state
Smart Resume	If interrupted, resumes from last completed phase
Self-Healing	Failed phases retry automatically (max 3 attempts)
Violation Detection	Skipped phases are detected and executed
Zero Intervention	No human input needed during execution
Quality Gate Teacher	Grades each phase A/B/C/D/F with APPROVED/REJECTED

Quality Gate Teacher

Every phase is validated by the Quality Gate Teacher before proceeding:

┌─────────────────────────────────────────────────────────────────────────────┐
│                        QUALITY GATE TEACHER                                  │
│                                                                             │
│   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐                │
│   │  Phase N    │ ───▶ │   TEACHER   │ ───▶ │  Grade +    │                │
│   │  Output     │      │   Evaluate  │      │  Decision   │                │
│   └─────────────┘      └─────────────┘      └─────────────┘                │
│                                                    │                        │
│                        ┌───────────────────────────┼──────────────────┐     │
│                        ▼                           ▼                  ▼     │
│                   A (90-100%)                B/C (70-89%)        D/F (<70%) │
│                   APPROVED                   APPROVED            REJECTED   │
│                   Continue                   Continue            Self-Heal  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Grading Criteria (varies by phase):

• Constitution: Clarity, completeness, enforceability
• Spec: Feature coverage, acceptance criteria, technical accuracy
• Plan: Architecture quality, risk assessment, dependency mapping
• Tasks: Granularity, skill mapping, dependency order
• Implementation: Code quality, test coverage, security
• Testing: Pass rate, coverage percentage, regression status

Component Quality Validation (Phase 6.5)

Generated skills, agents, and hooks are validated for production-readiness before use:

┌─────────────────────────────────────────────────────────────────────────────┐
│              COMPONENT QUALITY VALIDATION                                    │
│                                                                             │
│  WHO validates?  → component-quality-validator skill                        │
│  HOW validated?  → Automated quality criteria scoring                       │
│                                                                             │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐                       │
│  │   SKILL     │   │   AGENT     │   │   HOOK      │                       │
│  ├─────────────┤   ├─────────────┤   ├─────────────┤                       │
│  │ ✓ Triggers  │   │ ✓ Model fit │   │ ✓ JSON valid│                       │
│  │ ✓ Workflow  │   │ ✓ Min tools │   │ ✓ Bash valid│                       │
│  │ ✓ Templates │   │ ✓ Clear ins │   │ ✓ Targeted  │                       │
│  │ ✓ Validation│   │ ✓ Fail plan │   │ ✓ No conflict│                      │
│  └─────────────┘   └─────────────┘   └─────────────┘                       │
│         ↓                 ↓                 ↓                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  SCORE: 0-100  →  GRADE: A/B/C/D/F  →  APPROVED or REJECTED         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Rejected Components Regeneration:

• Attempt 1: Apply specific fixes from validation report
• Attempt 2: Simplify scope, focus on core functionality
• Attempt 3: Use template from similar working component
• Attempt 4+: Mark MANUAL_REQUIRED, continue with others

Phase Artifact Detection

Each phase creates a specific artifact. The validator checks these to determine state:

Phase	Artifact	Detection Command
1. INIT	.specify/ directory	[ -d ".specify" ]
2. ANALYZE PROJECT	project-analysis.json	[ -f ".specify/project-analysis.json" ]
3. ANALYZE REQUIREMENTS	requirements-analysis.json	[ -f ".specify/requirements-analysis.json" ]
4. GAP ANALYSIS	gap-analysis.json	[ -f ".specify/gap-analysis.json" ]
5. GENERATE	New skills created	Skill count > baseline
6. TEST	Validation logs	grep "validated" logs
7. CONSTITUTION	constitution.md	[ -f ".specify/constitution.md" ]
7.5 FEATURE BREAKDOWN	features.json	[ -f ".specify/features.json" ] (COMPLEX only)
8. SPEC	spec.md or features/N/spec.md	Spec file exists
9. PLAN	plan.md or features/N/plan.md	Plan file exists
10. TASKS	tasks.md or features/N/tasks.md	Tasks file exists
11. IMPLEMENT	Tasks marked [X]	grep -c "\[X\]" tasks.md
11.5 FEATURE QA	Unit tests pass	Test exit code 0
11.6 INTER-FEATURE	All unit tests pass	Combined test exit code 0
12. INTEGRATION QA	Full test suite pass	Unit + Integration + E2E pass
13. DELIVER	Git commit	Commit message contains "autonomous"

Workflow Status Commands

Check workflow state anytime:

# Quick status check - see which phase you're at
claude "/q-status"

# Full validation - check for violations
claude "/q-validate"

# Reset workflow - start fresh
claude "/q-reset"

Example /q-status output:

╔════════════════════════════════════════════════════════════════╗
║                    WORKFLOW STATUS REPORT                       ║
╠════════════════════════════════════════════════════════════════╣
║  [✓] 1. INIT                                                   ║
║  [✓] 2. ANALYZE PROJECT                                        ║
║  [✓] 3. ANALYZE REQUIREMENTS                                   ║
║  [✓] 4. GAP ANALYSIS                                           ║
║  [→] 5. GENERATE                    ← CURRENT                  ║
║  [ ] 6. TEST                                                   ║
║  [ ] 7. CONSTITUTION                                           ║
║  [ ] 8. SPEC                                                   ║
║  [ ] 9. PLAN                                                   ║
║  [ ] 10. TASKS                                                 ║
║  [ ] 11. IMPLEMENT                                             ║
║  [ ] 12. QA                                                    ║
║  [ ] 13. DELIVER                                               ║
╠════════════════════════════════════════════════════════════════╣
║  Violations: NONE                                              ║
║  Next: Generate missing skills (express-patterns, etc.)        ║
╚════════════════════════════════════════════════════════════════╝

---

🏗️ Complex Projects: Feature Iteration

For complex projects (4+ features), the workflow uses a sophisticated iteration pattern:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    COMPLEX PROJECT FEATURE ITERATION                         │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  CONSTITUTION (ONE for entire project - Phase 7)                        ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                    ↓                                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  FEATURE BREAKDOWN (Phase 7.5)                                          ││
│  │  → Extract features from requirements                                   ││
│  │  → Map dependencies between features                                    ││
│  │  → Order features by dependency graph                                   ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                    ↓                                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  FOR EACH FEATURE (in dependency order):                                ││
│  │  ┌─────────────────────────────────────────────────────────────────────┐││
│  │  │  8. SPEC (feature-specific)                                         │││
│  │  │  9. PLAN (feature-specific)                                         │││
│  │  │ 10. TASKS (feature-specific)                                        │││
│  │  │ 11. IMPLEMENT (TDD: tests first, then code)                         │││
│  │  │ 11.5 FEATURE QA (unit tests for this feature)                       │││
│  │  │ 11.6 INTER-FEATURE TESTS (all unit tests, if feature 2+)            │││
│  │  └─────────────────────────────────────────────────────────────────────┘││
│  │                              ↓ (next feature)                           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                    ↓                                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  12. INTEGRATION QA (Full test suite across all features)               ││
│  │      → Unit tests (all features)                                        ││
│  │      → Integration tests (feature interactions)                         ││
│  │      → E2E tests (user journeys)                                        ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                    ↓                                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  13. DELIVER                                                            ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Example: E-Commerce Platform (5 Features)

Feature 1: User Auth     → Spec → Plan → Tasks → Implement → Unit Tests ✓
Feature 2: Products      → Spec → Plan → Tasks → Implement → Unit Tests → Inter-Feature Tests ✓
Feature 3: Cart          → Spec → Plan → Tasks → Implement → Unit Tests → Inter-Feature Tests ✓
Feature 4: Orders        → Spec → Plan → Tasks → Implement → Unit Tests → Inter-Feature Tests ✓
Feature 5: Payments      → Spec → Plan → Tasks → Implement → Unit Tests → Inter-Feature Tests ✓
                                                    ↓
                         INTEGRATION QA (All features together)
                                                    ↓
                                    DELIVER

---

📝 Writing Requirements

Minimal Requirements File

# Project Name

## Features
- Feature 1
- Feature 2

## Technical
- Stack item 1
- Stack item 2

Comprehensive Requirements File

# E-Commerce Platform

## Overview
A full-featured e-commerce platform for small businesses.

## Features

### User Management
- User registration with email verification
- Login with JWT authentication
- Password reset flow
- User profile management

### Product Catalog
- Product CRUD operations
- Category management
- Search with filters
- Image upload

### Shopping Cart
- Add/remove items
- Quantity management
- Persistent cart (database)

### Orders
- Checkout flow
- Order history
- Order status tracking

## Technical

### Backend
- Runtime: Node.js 20
- Framework: Express
- Database: PostgreSQL
- ORM: Prisma
- Auth: JWT + bcrypt

### Frontend
- Framework: Next.js 14
- Styling: Tailwind CSS
- State: Zustand

### Testing
- Unit: Jest
- E2E: Playwright

### Deployment
- Docker
- Railway/Vercel

## Constraints
- Must be mobile-responsive
- Must support 1000 concurrent users
- Must have 80%+ test coverage

---

📦 Pre-Loaded Components

The boilerplate comes with pre-loaded components that work out of the box:

Agents (13) - With Dynamic Model Selection

Agent	Model	Purpose
architect	Opus	System design decisions
planner	Opus	Creates implementation plans
security-reviewer	Opus	OWASP Top 10 checks
tdd-guide	Opus	Test-driven development
code-reviewer	Sonnet	Quality & security review
build-error-resolver	Sonnet	Fix build errors
e2e-runner	Sonnet	Playwright E2E tests
refactor-cleaner	Sonnet	Remove dead code
doc-updater	Sonnet	Update documentation
test-runner	Sonnet	Run tests
git-ops	Haiku	Git commits, pushes, status
file-ops	Haiku	File listing, searching, moving
format-checker	Haiku	Prettier, ESLint, formatting

Model Selection Strategy

┌─────────────────────────────────────────────────────────────────────────────┐
│                    DYNAMIC MODEL SELECTION                                   │
│                                                                             │
│   OPUS (Complex)          SONNET (Medium)         HAIKU (Light)            │
│   ──────────────          ───────────────         ─────────────            │
│   • Architecture          • Code writing          • Git operations         │
│   • Security analysis     • Code review           • File operations        │
│   • Multi-phase planning  • Test writing          • Formatting             │
│   • Constitution          • Build fixes           • Simple validations     │
│                                                                             │
│   Cost: $$$$$             Cost: $$$$              Cost: $$$                │
│   ~10 calls/project       ~100 calls/project      ~50 calls/project        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Skills (15)

Skill	What It Contains
coding-standards	TypeScript/JS/React patterns, immutability, file organization
backend-patterns	API design, services, repository pattern
testing-patterns	Jest/Vitest/Playwright, TDD workflow, 80% coverage
api-patterns	REST/GraphQL design, input validation
database-patterns	Prisma/SQL/migrations, query optimization
claudeception	Session learning, skill extraction
mcp-code-execution-template	MCP integration, code execution pattern
skill-gap-analyzer	Detect missing skills, auto-generate needed components
workflow-validator	Quality gate teacher, component utilization enforcement
component-quality-validator	Validate generated components (A-F grading)
speckit-initialization	Spec-Kit-Plus setup and verification
workflow-state-manager	Workflow state tracking and persistence
Plus 3 more technology-specific skills that may be generated based on your project requirements

Commands (29 Total)

Core Autonomous Workflow:

Command	What It Does
/sp.autonomous	Full autonomous build from requirements file
/sp.specify	Create feature specification
/sp.plan	Generate implementation plan
/sp.tasks	Break down into actionable tasks
/sp.implement	Execute implementation with TDD
/sp.adr	Create Architecture Decision Record
/sp.phr	Record Prompt History (automatic)
/sp.constitution	Create/update project constitution
/sp.clarify	Ask clarifying questions
/sp.checklist	Generate quality checklist
/sp.analyze	Analyze codebase structure
/sp.reverse-engineer	Generate docs from code
/sp.git.commit_pr	Commit changes and create PR
/sp.taskstoissues	Convert tasks to GitHub issues

Workflow Validation:

Command	What It Does
/q-status	Check workflow state - which phase you're at
/q-validate	Validate workflow order, detect violations, check component utilization
/q-reset	Reset workflow state for fresh start
/validate-workflow	Run full workflow validation with quality gates
/validate-components	Check component quality (A-F grading)

Development Commands:

Command	What It Does
/plan	Create implementation plan
/tdd	Test-driven development
/code-review	Security + quality review
/build-fix	Fix build errors incrementally
/e2e	Generate and run E2E tests
/refactor-clean	Remove dead code safely
/test-coverage	Analyze and improve coverage
/update-codemaps	Update architecture documentation
/update-docs	Sync documentation from source

Plus the FPF (First Principles Framework) commands: /q0-init, /q1-hypothesize, /q2-verify, /q3-validate, /q4-audit, /q5-decide

---

🔧 Manual Mode (Optional)

Don't want full autonomous mode? Use individual commands:

Planning Workflow

# Start with a plan
> /plan I want to add user authentication

# Claude creates plan, WAITS for approval
> looks good, proceed

# Claude implements with TDD
# Then review
> /code-review

# Fix any issues
> /build-fix

# Commit
> commit these changes

TDD Workflow

> /tdd

# Claude:
# 1. Writes failing test (RED)
# 2. Implements code (GREEN)
# 3. Refactors (IMPROVE)
# 4. Verifies 80%+ coverage

---

📁 Understanding the Structure

autonomous-agent-boilerplate/
│
├── CLAUDE.md                      # Instructions for Claude (Golden Rules)
├── README.md                      # This documentation
├── .mcp.json                      # MCP server configuration (6 servers)
│
├── .claude/                       # Claude Code configuration
│   ├── settings.json              # Permissions + environment variables
│   ├── hooks.json                 # Automation hooks (PreToolUse/PostToolUse/Stop)
│   ├── skill-rules.json           # Dynamic skill activation rules (18 patterns)
│   │
│   ├── agents/                    # 13 specialized agents
│   │   ├── architect.md           # (opus) System design
│   │   ├── planner.md             # (opus) Implementation planning
│   │   ├── security-reviewer.md   # (opus) OWASP security analysis
│   │   ├── tdd-guide.md           # (opus) Test-driven development
│   │   ├── code-reviewer.md       # (sonnet) Code quality review
│   │   ├── build-error-resolver.md# (sonnet) Fix build errors
│   │   ├── e2e-runner.md          # (sonnet) Playwright E2E tests
│   │   ├── refactor-cleaner.md    # (sonnet) Dead code removal
│   │   ├── doc-updater.md         # (sonnet) Documentation sync
│   │   ├── test-runner.md         # (sonnet) Test execution
│   │   ├── git-ops.md             # (haiku) Git operations
│   │   ├── file-ops.md            # (haiku) File operations
│   │   └── format-checker.md      # (haiku) Prettier/ESLint
│   │
│   ├── commands/                  # 15 slash commands
│   │   ├── sp.autonomous.md       # Full autonomous build (57KB)
│   │   ├── q-status.md            # Workflow status
│   │   ├── q-validate.md          # Workflow validation
│   │   ├── q-reset.md             # Reset workflow
│   │   ├── plan.md                # Implementation planning
│   │   ├── tdd.md                 # Test-driven development
│   │   ├── code-review.md         # Code review
│   │   ├── build-fix.md           # Build error fixing
│   │   ├── e2e.md                 # E2E testing
│   │   ├── refactor-clean.md      # Dead code cleanup
│   │   ├── test-coverage.md       # Coverage analysis
│   │   ├── update-codemaps.md     # Architecture docs
│   │   ├── update-docs.md         # Documentation sync
│   │   ├── validate-workflow.md   # Workflow validation
│   │   └── validate-components.md # Component quality check
│   │
│   ├── skills/                    # 10 reusable skills
│   │   ├── api-patterns/          # REST/GraphQL patterns
│   │   ├── backend-patterns/      # Backend architecture
│   │   ├── coding-standards/      # Code quality patterns
│   │   ├── database-patterns/     # Database/ORM patterns
│   │   ├── testing-patterns/      # Testing patterns
│   │   ├── claudeception/         # Session learning
│   │   ├── mcp-code-execution-template/  # MCP integration
│   │   ├── skill-gap-analyzer/    # Gap analysis
│   │   ├── workflow-validator/    # Quality gate + component utilization
│   │   └── component-quality-validator/  # Production-readiness check
│   │
│   ├── rules/                     # 8 governance rules
│   │   ├── agents.md              # Agent orchestration
│   │   ├── coding-style.md        # Immutability, file organization
│   │   ├── git-workflow.md        # Conventional commits
│   │   ├── hooks.md               # Hook system docs
│   │   ├── patterns.md            # API/service patterns
│   │   ├── performance.md         # Model selection
│   │   ├── security.md            # OWASP Top 10
│   │   └── testing.md             # 80% coverage, TDD
│   │
│   ├── hooks/                     # Hook scripts
│   │   ├── skill-activator.sh     # Dynamic skill activation
│   │   ├── skill-enforcement-stop.sh  # End-of-session enforcement
│   │   └── claudeception-activator.sh # Session learning
│   │
│   └── logs/                      # Activity logs
│       ├── agent-usage.log        # Task tool invocations
│       ├── skill-invocations.log  # Skill() calls
│       ├── skill-activations.log  # Skill activator output
│       ├── skill-enforcement.log  # Enforcement decisions
│       ├── tool-usage.log         # Write/Edit operations
│       └── file-changes.log       # File modifications
│
├── .specify/                      # Spec-Kit-Plus workflow artifacts
│   ├── project-analysis.json      # Existing project analysis
│   ├── requirements-analysis.json # Requirements parsing
│   ├── gap-analysis.json          # Missing components
│   ├── constitution.md            # Project rules
│   ├── spec.md                    # Specification
│   ├── plan.md                    # Implementation plan
│   ├── tasks.md                   # Task checklist
│   ├── templates/                 # Feature templates
│   └── validations/               # Phase validation reports
│
└── requirements/                  # Your requirements files
    └── my-app.md                  # Example requirements

Rules Enforced

Rule	Enforcement
Immutability	No direct mutation allowed
File Size	Max 800 lines per file
Test Coverage	Minimum 80%
Security	OWASP Top 10 checked
Code Quality	Auto-formatted, reviewed

---

📊 Monitoring & Observability

The boilerplate includes comprehensive logging to track what's happening during autonomous builds.

Log Files

All logs are stored in .claude/logs/:

Log File	What It Tracks	Example Entry
agent-usage.log	Task tool invocations (agent spawning)	[2024-01-21T10:30:00] Agent task invoked
skill-invocations.log	Skill() tool calls	[2024-01-21T10:31:00] Skill invoked: coding-standards
skill-activations.log	Skill activator hook output	Prompt: "build api" | Matched: api-patterns
skill-enforcement.log	Enforcement decisions	MANDATORY skill not used: testing-patterns
tool-usage.log	Write/Edit tool calls	[2024-01-21T10:32:00] Tool: Edit | File: src/api.ts
file-changes.log	File modifications	[2024-01-21T10:32:00] File modified: src/api.ts

Viewing Logs

# View recent skill invocations
tail -20 .claude/logs/skill-invocations.log

# Watch agent usage in real-time
tail -f .claude/logs/agent-usage.log

# Check which skills were activated
cat .claude/logs/skill-activations.log | grep "DETECTED MATCHES"

# See enforcement decisions
cat .claude/logs/skill-enforcement.log

# Count skill usage
wc -l .claude/logs/skill-invocations.log

Component Utilization Check

The workflow-validator skill tracks if custom components are being used:

# Check component utilization during a build
claude "/q-validate"

This shows:

• Skills Used: Which skills were invoked via Skill(name)
• Agents Used: Which agents were spawned via Task(subagent_type)
• Utilization %: Percentage of available components that were used
• Bypass Detection: Warning if general agent did work without using custom components

Phase Validation Reports

After each phase, validation reports are generated in .specify/validations/:

# List validation reports
ls .specify/validations/

# View a specific phase report
cat .specify/validations/phase-11-report.md

Example report structure:

# Phase 11 Validation Report

## Summary
| Field | Value |
|-------|-------|
| Phase | 11: IMPLEMENT |
| Grade | B |
| Score | 85/100 |
| Status | APPROVED |

## Component Utilization
| Category | Available | Used | Percentage |
|----------|-----------|------|------------|
| Skills | 10 | 4 | 40% |
| Agents | 13 | 3 | 23% |

## Issues Found
- Missing skill invocation: testing-patterns

## Decision
✅ APPROVED - Proceeding to Phase 12

Reset Detection

If a phase is reset due to component bypass:

# Check reset counter
cat .specify/validations/reset-counter.json

# View bypass log
cat .specify/validations/bypass-log.json

Environment Variables

The following environment variables control workflow behavior:

Variable	Value	Purpose
AUTONOMOUS_MODE	true	Enable full autonomous execution
MAX_SELF_HEAL_RETRIES	3	Max retry attempts per phase
SKILL_ENFORCEMENT	strict	Enforce skill usage (strict/warn/off)

---

🎨 Customization

Add Your Own Skills

Create .claude/skills/my-skill/SKILL.md:

---
name: my-skill
description: Description of what this skill does
allowed-tools: Read, Write, Edit, Bash
---

# My Custom Skill

## Patterns
...

Add Your Own Agents

Create .claude/agents/my-agent.md:

---
name: my-agent
description: What this agent does
tools: Read, Write, Edit, Bash
model: sonnet
---

Instructions for the agent...

Add Your Own Commands

Create .claude/commands/my-command.md:

---
description: What this command does
---

Instructions executed when /my-command is called...

---

🔧 Troubleshooting

"Command not found"

ls .claude/commands/
# Should show plan.md, tdd.md, sp.autonomous.md, etc.

Fix: Ensure .claude/ folder is in your project.

"Build fails repeatedly"

> /build-fix

Self-heals up to 3 times, then asks for help.

"MCP server error"

Check .mcp.json has correct API keys:

{
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

---

❓ FAQ

Q: What's the difference between this and a normal template?

Normal template: Pre-made files you adapt to your project. This boilerplate: Generates custom infrastructure for YOUR specific requirements.

Q: Do I need to write detailed requirements?

Minimal requirements work, but more detail = better results. The boilerplate extracts technologies, features, and constraints from your requirements file.

Q: Can I use this for existing projects?

Yes! Copy .claude/, CLAUDE.md, and .mcp.json to your project. Then use /plan for new features.

Q: What if autonomous mode fails?

It self-heals up to 3 times. If still failing, it stops and reports what went wrong. You can then use manual commands (/plan, /tdd, /build-fix) to continue.

Q: Can I customize the generated code style?

Yes! Edit .claude/rules/coding-style.md to change patterns, file size limits, naming conventions, etc.

---

📄 License

MIT License - use freely in personal and commercial projects.

---

🙏 Acknowledgments

• Inspired by everything-claude-code by @affaan-m
• Built for Claude Code by Anthropic

---

Write requirements. Run one command. Ship code.

claude "/sp.autonomous requirements/my-app.md"