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 -
.gitignoreconfigured to exclude all session-specific files - ✅ Quality Gates - Component utilization enforcement, workflow validation, A-F grading
- ✅ Complete Documentation - 2,343 lines of comprehensive guides
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ 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"- How It Works
- Quick Start
- The Spec-Kit-Plus Workflow
- Writing Requirements
- Pre-Loaded Components
- Manual Mode (Optional)
- Understanding the Structure
- Customization
- Troubleshooting
- FAQ
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: Jestclaude "/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!
The autonomous workflow:
- Verifies Spec-Kit-Plus installation (pre-installed in this boilerplate)
- Creates feature branch automatically (if on main/master)
- Analyzes your requirements file
- Detects technologies (Node.js, Express, PostgreSQL, Prisma, Jest)
- Generates custom skills for your stack (if needed)
- Generates specialized agents for your project (if needed)
- Generates quality hooks for your workflow (if needed)
- Creates specification, plan, and task breakdown
- Implements each feature using TDD
- Reviews code for security and quality
- 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.
When you start a new autonomous build:
- Checks if you're on
mainormasterbranch - 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.
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):
- Run:
bash .claude/scripts/resume-work.sh - See all saved TODOs from previous sessions (yours and your teammates')
- 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.jsonwhen 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 saveExample 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.
-
Clone this boilerplate:
git clone https://github.com/your-username/claude-code-autonomous-agent-workflow.git cd claude-code-autonomous-agent-workflow -
Your first session will be clean - no pre-existing TODOs or session state
.specify/todos.jsonwill be created when you first use TODOs- Historical snapshots save to
.specify/todo-history/automatically - See
.specify/todos.example.jsonfor the data structure - Session Isolation: All session-specific files are excluded by
.gitignore - You start fresh with no inherited session data
-
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"
# 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# Clone the boilerplate
git clone https://github.com/your-username/autonomous-agent-boilerplate.git my-project
cd my-project
# Start Claude Code
claude# 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!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 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
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 | 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 |
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
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)
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 │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| 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 |
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
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
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" |
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.) ║
╚════════════════════════════════════════════════════════════════╝
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 ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
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
# Project Name
## Features
- Feature 1
- Feature 2
## Technical
- Stack item 1
- Stack item 2# 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 coverageThe boilerplate comes with pre-loaded components that work out of the box:
| 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 |
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| 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 |
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
Don't want full autonomous mode? Use individual commands:
# 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
# Claude:
# 1. Writes failing test (RED)
# 2. Implements code (GREEN)
# 3. Refactors (IMPROVE)
# 4. Verifies 80%+ coverageautonomous-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
| 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 |
The boilerplate includes comprehensive logging to track what's happening during autonomous builds.
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 |
# 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.logThe 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
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.mdExample 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 12If 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.jsonThe 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) |
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
...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...Create .claude/commands/my-command.md:
---
description: What this command does
---
Instructions executed when /my-command is called...ls .claude/commands/
# Should show plan.md, tdd.md, sp.autonomous.md, etc.Fix: Ensure .claude/ folder is in your project.
> /build-fixSelf-heals up to 3 times, then asks for help.
Check .mcp.json has correct API keys:
{
"mcpServers": {
"github": {
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
}
}
}
}Normal template: Pre-made files you adapt to your project. This boilerplate: Generates custom infrastructure for YOUR specific requirements.
Minimal requirements work, but more detail = better results. The boilerplate extracts technologies, features, and constraints from your requirements file.
Yes! Copy .claude/, CLAUDE.md, and .mcp.json to your project. Then use /plan for new features.
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.
Yes! Edit .claude/rules/coding-style.md to change patterns, file size limits, naming conventions, etc.
MIT License - use freely in personal and commercial projects.
- 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"