Installation

Prerequisites

• Claude Code - Install here
• Node.js 22+
• A project directory

Installation Options

Note: These options are for first-time installation only. If you already have agentful installed, use /agentful-update instead. See When to Use What below.

Local-only: installation configuration is fully local via CLI flags. Remote/shareable --config URLs are no longer supported.

Option 1: Default Installation (CLI)

Install with all components (recommended for most projects):

# Default installation - All components (recommended)
npx @itz4blitz/agentful init
 
# Minimal installation - Backend-only (2 agents, for simple projects)
npx @itz4blitz/agentful init --preset=minimal
 
# View installation options
npx @itz4blitz/agentful presets

Tech stack is auto-detected on first run - no need to specify during installation.

See the Installation Options Guide for details.

Option 2: Custom Configuration (CLI)

Build a custom configuration with specific components:

npx @itz4blitz/agentful init \
  --agents=orchestrator,backend,frontend,tester \
  --skills=validation,testing \
  --hooks=health-check \
  --gates=types,tests,coverage

Available flags:

• --preset=<name> - Use a preset configuration
• --agents=<list> - Comma-separated agent names
• --skills=<list> - Comma-separated skill names
• --hooks=<list> - Comma-separated hook identifiers
• --gates=<list> - Comma-separated quality gate names

This installs:

• .claude/ - Agents, commands, skills
• .agentful/ - Runtime state (gitignored)
• .claude/product/ - Product specification structure
• CLAUDE.md - Project instructions

What Gets Created

your-project/
├── CLAUDE.md               # Project instructions
├── .claude/
│   ├── agents/             # 8 specialized agents
│   ├── commands/           # Command templates (see /commands)
│   ├── skills/             # Domain skills
│   ├── product/            # Product specification
│   │   ├── index.md        # Project overview
│   │   ├── domains/        # Business domains (optional)
│   │   │   └── auth/
│   │   │       ├── index.md
│   │   │       └── features/
│   │   └── README.md
│   └── settings.json
└── .agentful/              # Runtime state (gitignored)
    ├── state.json
    ├── completion.json
    ├── decisions.json
    └── architecture.json

Product Structure

agentful uses .claude/product/index.md for your product specification.

Simple projects:

• Keep all features in index.md

Complex projects:

• Organize into domain subdirectories under domains/
• Each domain has its own index.md and features/

Verify Installation

# Check directories exist
ls -la .claude/
ls -la .agentful/
 
# Check state
cat .agentful/state.json
 
# Check product structure
ls -la .claude/product/
cat .claude/product/index.md

When to Use What

# First-time setup
npx @itz4blitz/agentful init

# In Claude Code
/agentful-update

Updating Your Installation

After initial installation, use the /agentful-update command to get the latest templates:

# In Claude Code
/agentful-update

This command:

• 🔄 Updates agents, commands, and skills to the latest version
• 💾 Preserves your customizations via 3-way merge
• 📦 Creates automatic backups before updating
• 🔒 Safely handles configuration conflicts
• ✨ Adds new features from agentful updates

Update Process

1. Backup: Automatically backs up current configuration
2. Fetch: Downloads latest templates from registry
3. Merge: Intelligently merges changes with your customizations
4. Verify: Validates merged configuration
5. Apply: Updates files if validation passes

When to Update

Run /agentful-update when:

• A new version of agentful is released
• You want new agent capabilities or commands
• Bug fixes are available for existing templates
• You need to sync with upstream improvements

Troubleshooting

Command not found: npx

Install Node.js 22+ from nodejs.org

node --version  # Should be v22+
npx --version

.claude directory already exists

Backup before overwriting:

mv .claude .claude.backup
npx @itz4blitz/agentful init

Permission denied

ls -la
sudo chown -R $USER:$USER .claude .agentful

Network timeout

# Clear cache
npm cache clean --force
npx @itz4blitz/agentful init

Uninstall

rm -rf .claude .agentful CLAUDE.md

Next Steps

After installation:

1. Edit your product spec: .claude/product/index.md (Quick Start)
2. Start Claude Code: claude
3. Begin development: /agentful-start

To update agentful later, use /agentful-update (not npx init)

What's Next