Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Quick Start

Get agentful building your project autonomously in 5 minutes.

Overview

This quick start will walk you through:

  1. ✅ Initializing agentful
  2. ✅ Defining your product
  3. ✅ Starting autonomous development
  4. ✅ Monitoring progress
  5. ✅ Understanding the workflow

Time: 5 minutes Prerequisites: agentful installed

Step 1: Initialize agentful (30 seconds)

# In your project directory
npx @itz4blitz/agentful init
What happens:
  • Creates .claude/ with 7 specialized agents
  • Creates .agentful/ for state tracking
  • Creates .claude/product/index.md (hierarchical structure template)
  • Creates CLAUDE.md project instructions
Output: 
✅ agentful initialized successfully!
 
Next steps:
  1. Edit your product specification (see below)
  2. Run: claude
  3. Type: /agentful-start

Step 2: Define Your Product (2 minutes)

agentful supports two ways to define your product. Choose the one that fits your project.

Choose Your Adventure

Simple Projects (recommended for beginners and small apps):

  • Use a flat PRODUCT.md file in your project root
  • Everything in one place
  • Easier to get started
  • Best for: Learning projects, MVPs, single-purpose apps

Complex Projects (for larger applications):

  • Use .claude/product/ directory with multiple files
  • Organize by domains/features
  • Scales better for big projects
  • Best for: Multi-domain apps, large teams, long-term projects

Both work identically - agentful auto-detects which you're using. You can switch anytime.

Option A: Simple Structure (Flat PRODUCT.md)

Create PRODUCT.md in your project root:

# Product Specification
 
## Overview
A simple todo list application.
 
## Tech Stack
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes
- **Database**: None (in-memory for now)
- **Testing**: Vitest
 
## Features
 
### 1. Add Todo - CRITICAL
**Description**: Users can add new todo items
 
**Acceptance Criteria**:
- [ ] Input field for new todos
- [ ] Add button
- [ ] Todo appears in list
 
### 2. Toggle Todo - HIGH
**Description**: Users can mark todos as complete
 
**Acceptance Criteria**:
- [ ] Click todo to toggle completion
- [ ] Visual indicator for completed todos
 
### 3. Delete Todo - MEDIUM
**Description**: Users can delete todos
 
**Acceptance Criteria**:
- [ ] Delete button on each todo
- [ ] Confirmation prompt

That's it! Skip to Step 3.

Option B: Hierarchical Structure (.claude/product/)

Edit .claude/product/index.md (created during init):

# Product Specification
 
## Overview
A simple todo list application.
 
## Domains
- Tasks
- UI
- Storage
 
## Tech Stack
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes
- **Database**: None (in-memory for now)
- **Testing**: Vitest

Then create .claude/product/domains/tasks.md:

# Tasks Domain
 
## Features
 
### 1. Add Todo - CRITICAL
**Description**: Users can add new todo items
 
**Acceptance Criteria**:
- [ ] Input field for new todos
- [ ] Add button
- [ ] Todo appears in list
 
### 2. Toggle Todo - HIGH
**Description**: Users can mark todos as complete
 
**Acceptance Criteria**:
- [ ] Click todo to toggle completion
- [ ] Visual indicator for completed todos
 
### 3. Delete Todo - MEDIUM
**Description**: Users can delete todos
 
**Acceptance Criteria**:
- [ ] Delete button on each todo
- [ ] Confirmation prompt

More domains? Create additional files like ui.md, storage.md, etc.

Key Sections Explained

# Product Specification
 
## Overview
A simple todo list application.
 
## Tech Stack
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes
- **Database**: None (in-memory for now)
- **Testing**: Vitest
 
## Features
 
### 1. Add Todo - CRITICAL
**Description**: Users can add new todo items
 
**Acceptance Criteria**:
- [ ] Input field for new todos
- [ ] Add button
- [ ] Todo appears in list
 
### 2. Toggle Todo - HIGH
**Description**: Users can mark todos as complete
 
**Acceptance Criteria**:
- [ ] Click todo to toggle completion
- [ ] Visual indicator for completed todos
 
### 3. Delete Todo - MEDIUM
**Description**: Users can delete todos
 
**Acceptance Criteria**:
- [ ] Delete button on each todo
- [ ] Confirmation prompt

Key Sections Explained

Overview - 2-3 sentences describing what you're building

Tech Stack - Your technology choices

  • Frontend framework
  • Backend framework
  • Database
  • Testing tools
  • Styling approach

Features - What you want built, ordered by priority

  • CRITICAL - Must have for MVP
  • HIGH - Important but can wait
  • MEDIUM - Nice to have
  • LOW - Future improvements

For each feature, include:

  • Description - What it does
  • Acceptance Criteria - Specific requirements (checkboxes)
  • User Stories (optional) - Who wants what and why

Step 3: Start Claude Code (10 seconds)

claude

This starts the Claude Code CLI with agentful's specialized agents loaded.

Step 4: Begin Autonomous Development (30 seconds)

In the Claude Code prompt, type:

/agentful-start
What happens next:

Phase 1: Architecture Analysis (10 seconds)

🏗️  Architect Agent analyzing...
 
Detected tech stack:
- Next.js 14
- TypeScript
- Tailwind CSS
 
Generated specialized agents:
✓ nextjs-agent
✓ typescript-agent
✓ tailwind-agent
✓ vitest-agent

Phase 2: Planning (10 seconds)

📋 Orchestrator planning work...
 
Priority queue:
1. Add Todo feature (CRITICAL)
2. Toggle Todo feature (HIGH)
3. Delete Todo feature (MEDIUM)
 
Starting: Add Todo feature

Phase 3: Implementation (varies)

🔧 Frontend Agent implementing...
 
Created:
- src/app/page.tsx (main page)
- src/components/TodoList.tsx
- src/components/TodoInput.tsx
- src/hooks/useTodos.ts

Phase 4: Testing (varies)

🧪 Tester Agent writing tests...
 
Created:
- src/components/__tests__/TodoList.test.tsx
- src/hooks/__tests__/useTodos.test.ts
 
Running tests...
✓ All tests passing

Phase 5: Validation (20 seconds)

🔍 Reviewer Agent validating...
 
Quality Gates:
✅ All tests passing
✅ No type errors (adapts to stack)
⚠️  Test coverage: 65% (target: 80%)
✅ No dead code
✅ No security issues
 
Coverage below 80%, continuing...

Phase 6: Iteration (continues)

🔄 Fixer Agent improving coverage...
 
Added tests for edge cases...
Coverage now: 82% ✅
 
Feature complete: Add Todo (100%)
 
Next: Toggle Todo feature...

Step 5: Monitor Progress (ongoing)

Check progress anytime:

/agentful-status
Output: 
🔧 Working on: Toggle Todo feature
   Phase: implementation
   Iterations: 8
 
Progress:
   ████████░░░░░░░░░░░ 40%
 
Quality Gates:
   ✅ Tests Passing
   ✅ No Type Errors
   ✅ Coverage 82%
   ✅ No Dead Code
   ⚠️  1 pending decision:
      1. Should completed todos move to bottom?
 
Next Actions:
   • /agentful-start    - Continue development
   • /agentful-decide  - Answer pending decision
   • /agentful-validate- Run quality checks

Step 6: Handle Decisions (if needed)

Sometimes agentful needs your input:

⚠️  Decision needed:
Should completed todos move to the bottom of the list?
 
Options:
1. Yes, move to bottom
2. No, keep in place
3. Sort by completion date
To answer: 
/agentful-decide

Then provide your answer:

Option 1: Yes, move to bottom

agentful will immediately resume with your decision.

Understanding the Workflow

The Development Loop

┌─────────────────────────────────────────┐
│  1. Architect: Analyze tech stack       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  2. Orchestrator: Plan next task        │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  3. Specialist: Implement feature       │
│     (@frontend, @backend, @tester)      │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  4. Reviewer: Validate quality          │
└─────────────────────────────────────────┘
              ↓
         Issues found?
              ↓
       ┌──────┴──────┐
       ↓             ↓
┌─────────────┐  ┌─────────────┐
│ 5. Fixer    │  │ 6. Complete │
│    Fix issues│  │    Update   │
└─────────────┘  │  Progress   │
       │         └─────────────┘
       └─────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  7. Loop again until 100% complete      │
└─────────────────────────────────────────┘

Agent Roles

AgentWhen it activatesWhat it does
@architectOnce at startAnalyzes tech stack, generates specialized agents
@orchestratorEvery iterationPlans work, delegates to specialists
@frontendBuilding UIComponents, pages, hooks, styling
@backendBuilding APIsServices, repositories, controllers
@testerAfter implementationWrites unit, integration, E2E tests
@reviewerAfter testingValidates quality gates, finds issues
@fixerWhen issues foundAuto-fixes validation failures

Common Commands

Start/Resume Development

/agentful-start

Check Progress

/agentful-status

Answer Pending Decisions

/agentful-decide

Run Quality Checks

/agentful-validate

Tips for Success

1. Start Small

Your first time? Build something simple:

✅ Good first projects:

  • Todo app
  • Blog with markdown
  • Contact form
  • Weather widget

❌ Avoid for first time:

  • Real-time collaboration
  • Payment processing
  • Complex authentication

2. Be Specific in Your Product Spec

The more specific your requirements, the better agentful understands:

For simple projects (PRODUCT.md): Vague: 
## Features
1. User management
Specific: 
### 1. User Registration - CRITICAL
**Description**: Users can register with email/password
 
**Acceptance Criteria**:
- [ ] Email validation (required, valid format)
- [ ] Password min 8 characters, 1 uppercase, 1 number
- [ ] Unique email check
- [ ] Success: redirect to dashboard
- [ ] Error: show inline error message
For complex projects (.claude/product/): Vague: 
# .claude/product/domains/users.md
## Features
1. Registration
Specific: 
# .claude/product/domains/users.md
## Features
 
### 1. User Registration - CRITICAL
**Description**: Users can register with email/password
 
**Acceptance Criteria**:
- [ ] Email validation (required, valid format)
- [ ] Password min 8 characters, 1 uppercase, 1 number
- [ ] Unique email check
- [ ] Success: redirect to dashboard
- [ ] Error: show inline error message

3. Use Priority Levels

Order features by priority:

### 1. Core feature - CRITICAL
### 2. Important feature - HIGH
### 3. Nice to have - MEDIUM
### 4. Future enhancement - LOW

agentful works CRITICAL → HIGH → MEDIUM → LOW

4. Let It Run

Don't micromanage. agentful works best when you:

✅ Do:

  • Start it and let it run
  • Check in periodically with /agentful-status
  • Answer decisions when prompted
  • Review code at milestones

❌ Don't:

  • Interrupt after every file
  • Change your product spec mid-development
  • Manually edit files agentful created
  • Stop and start repeatedly

Switching structures? You can change between flat (PRODUCT.md) and hierarchical (.claude/product/) anytime. agentful auto-detects the change.

5. Use 24/7 Mode for Big Projects

For complex projects, use Ralph Wiggum loops:

/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"

Let it run overnight, wake up to progress.

What to Expect

Timeline Examples

Simple Project (Todo App)
  • 5-10 minutes
  • 3-5 iterations
  • 1-2 features
Medium Project (Blog)
  • 30-60 minutes
  • 10-20 iterations
  • 5-10 features
Complex Project (SaaS MVP)
  • 2-4 hours (or overnight with Ralph)
  • 50-100 iterations
  • 10-20 features

Quality Expectations

agentful aims for:

  • ✅ All tests passing
  • ✅ No type errors (adapts to stack)
  • ✅ 80%+ test coverage
  • ✅ No dead code
  • ✅ No security issues

Note: Code may need refactoring for production. agentful builds working MVPs, not production-optimized code.

Troubleshooting

Issue: agentful seems stuck

Solution: Check status

/agentful-status

If iterations > 20 without progress:

  1. Check for pending decisions
  2. Run /agentful-decide
  3. Or restart: /agentful-start

Issue: Not making progress on features

Solution: Review PRODUCT.md

  • Are acceptance criteria clear?
  • Is tech stack specified?
  • Try breaking features into smaller chunks

Issue: Too many validation errors

Solution: Let Fixer work

  • agentful will auto-fix most issues
  • If stuck, run /agentful-validate to see specific errors
  • Some errors may require manual intervention

Next Steps

Build Your First Project

Create a complete autonomous project → First Project Guide

Configuration

Customize agentful for your needs → Configuration Guide

Quick Reference

Essential Commands:
  • /agentful-start - Begin autonomous development
  • /agentful-status - Check progress
  • /agentful-decide - Answer decisions
  • /agentful-validate - Run quality checks
Key Files:
  • PRODUCT.md - Your product spec (simple structure)
  • .claude/product/index.md - Main product spec (hierarchical structure)
  • .claude/product/domains/*.md - Domain-specific specs (hierarchical structure)
  • CLAUDE.md - Project instructions
  • .agentful/state.json - Current state
  • .agentful/completion.json - Progress tracking
Choose Your Structure:
  • Simple: Create PRODUCT.md in project root
  • Complex: Use .claude/product/ with domain files
  • Switch anytime: agentful auto-detects both
24/7 Development: 
/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"