Quick Start

Build your project in 5 minutes.

Step 1: Install agentful

First, install agentful in your project:

npx @itz4blitz/agentful init

For custom configurations, see the Installation Guide.

This creates .claude/product/index.md for your product specification.

Optional: Enable Pattern Learning so agents compound knowledge across sessions:

# Project scope (default)
claude mcp add agentful -- npx -y @itz4blitz/agentful-mcp-server
 
# Or global scope (available in all projects)
claude mcp add -s user agentful -- npx -y @itz4blitz/agentful-mcp-server

Step 2: Define Your Product

Edit .claude/product/index.md.

Simple Projects

# Product Specification
 
## Overview
A todo list application.
 
## Tech Stack
- Frontend: Next.js 15, TypeScript, Tailwind CSS
- Backend: Next.js API Routes
- Database: None (in-memory)
- Testing: Vitest
 
## Features
 
### 1. Add Todo - CRITICAL
**Description**: Users can add new todos
 
**Acceptance Criteria**:
- [ ] Input field for new todos
- [ ] Add button
- [ ] Todo appears in list
- [ ] Input clears after adding
- [ ] Validation: empty todos not allowed
 
### 2. Toggle Todo - CRITICAL
**Description**: Users can mark todos complete
 
**Acceptance Criteria**:
- [ ] Click to toggle completion
- [ ] Visual indicator for completed todos
 
### 3. Delete Todo - HIGH
**Description**: Users can delete todos
 
**Acceptance Criteria**:
- [ ] Delete button on each todo
- [ ] Task removes from list

For complex projects with multiple domains, see the First Project guide for a complete product spec example with domains.

Step 3: Start Claude

claude

Step 4: Start Development

/agentful-start

This will automatically:

• Analyze your codebase and tech stack
• Generate specialized agents on first run (same as running /agentful-generate)
• Begin structured development

Note: On first run, /agentful-start automatically triggers /agentful-generate - you don't need to run it separately unless your tech stack changes later.

The orchestrator:

• Reads your product specification
• Picks the highest-priority incomplete feature
• Delegates to appropriate specialist agents
• Validates quality gates
• Tracks progress
• Repeats until 100% complete

Common Commands

/agentful-start     - Start or continue development
/agentful-status    - Check progress
/agentful-decide    - Answer pending decisions
/agentful-validate  - Run quality checks
/agentful-generate  - Re-generate agents (optional, after codebase changes)

Note: Agents are generated automatically on first run of /agentful-start. Only re-run /agentful-generate if your tech stack changes significantly.

Tips

Start Small

Good first projects:

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

Avoid for first time:

• Real-time collaboration
• Payment processing
• Complex authentication

Be Specific

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 message

Use Priority Levels

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

agentful works CRITICAL → HIGH → MEDIUM → LOW.

Add Domain Organization

For growing projects, organize into domains:

mkdir -p .claude/product/domains/authentication
# Move authentication features to domain directory
# Create domains/authentication/index.md

What to Expect

Timeline Examples

• 5-10 minutes
• 3-5 iterations
• 1-2 features

• 30-60 minutes
• 10-20 iterations
• 5-10 features

• 2-4 hours
• 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

Code may need refactoring for production. agentful builds working MVPs.

Troubleshooting

agentful seems stuck

Check status:

/agentful-status

If iterations > 20 without progress:

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

Not making progress

Review your product spec:

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

Too many validation errors

Let Fixer work. agentful auto-fixes most issues. If stuck, run /agentful-validate to see specific errors.

Next Steps

Quick Reference

Essential Commands:

• /agentful-start - Start or continue development
• /agentful-status - Check progress
• /agentful-decide - Answer pending decisions
• /agentful-validate - Run quality checks

Key Files:

• .claude/product/index.md - Product spec
• .claude/product/domains/* - Domain specs (optional)
• .agentful/state.json - Current state
• .agentful/architecture.json - Detected tech stack

Structure:

• Simple projects → .claude/product/index.md
• Complex projects → Add domains/ subdirectories