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

Configuration Overview

agentful provides a flexible configuration system that lets you customize every aspect of autonomous product development. Configuration is split between project-level settings and agentful's internal configuration.

Configuration Structure

.your-project/
├── .claude/                    # Claude Code + agentful config
│   ├── settings.json           # Global settings (hooks, permissions)
│   ├── agents/                 # Agent definitions
│   ├── commands/               # Slash command definitions
│   └── skills/                 # Reusable skill modules
├── .agentful/                  # Runtime state (gitignored)
│   ├── state.json              # Current work state
│   ├── completion.json         # Progress tracking
│   ├── decisions.json          # Pending/resolved decisions
│   └── architecture.json       # Tech stack detection
├── PRODUCT.md                  # Your product specification
└── CLAUDE.md                   # agentful usage guide

Configuration Files

Core Files

FilePurposeEdit?
.claude/settings.jsonHooks, permissions, global settingsYes
PRODUCT.mdProduct requirements and tech stackYes (required)
CLAUDE.mdProject-specific agentful instructionsOptional
.agentful/*.jsonRuntime state (auto-generated)No

Generated Files

FilePurposeGenerated By
.agentful/state.jsonCurrent work stateCLI init
.agentful/completion.jsonFeature progressOrchestrator
.agentful/decisions.jsonUser decisionsOrchestrator
.agentful/architecture.jsonTech stack infoArchitect agent
.agentful/last-validation.jsonValidation resultsReviewer agent

Quick Start Configuration

1. Initialize agentful

npx @itz4blitz/agentful init

This creates:

  • .claude/ directory with all agents and commands
  • .agentful/ directory for runtime state
  • PRODUCT.md template
  • CLAUDE.md usage guide
  • Updates .gitignore to exclude .agentful/

2. Configure Your Product

Edit PRODUCT.md with your product details:

# Product Specification
 
## Overview
A task management application for teams.
 
## Tech Stack
 
### Frontend
- **Framework**: Next.js 14
- **Language**: TypeScript
- **Styling**: Tailwind CSS
 
### Backend
- **Framework**: Next.js API Routes
- **Database**: PostgreSQL + Prisma
- **Auth**: JWT
 
## Features
 
### 1. Authentication - CRITICAL
- Login with email/password
- JWT token generation
- Session management

3. Customize Agents (Optional)

Edit agents in .claude/agents/ to match your preferences:

# Customize backend agent patterns
edit .claude/agents/backend.md
 
# Add custom validation rules
edit .claude/skills/validation/SKILL.md

4. Adjust Settings

Edit .claude/settings.json for hooks and permissions:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(git:*)"
    ]
  }
}

Configuration Layers

agentful configuration applies in layers (highest priority first):

  1. Project-level - PRODUCT.md, CLAUDE.md
  2. Agent-level - Individual agent definitions in .claude/agents/
  3. Skill-level - Reusable skills in .claude/skills/
  4. Global-level - .claude/settings.json

Environment-Specific Configuration

Development

# Use default settings
npx @itz4blitz/agentful init
 
# Edit PRODUCT.md for dev-specific features
# - Enable debug mode
# - Use mock services
# - Add dev tools

Production

# Update PRODUCT.md with production requirements
# - Set production API endpoints
# - Enable all security features
# - Configure performance monitoring
 
# Adjust permissions in settings.json
{
  "permissions": {
    "deny": [
      "Bash(npm:dev*)",
      "Bash(npm:test*)"
    ]
  }
}

Staging

Create environment-specific config:

# Copy PRODUCT.md
cp PRODUCT.md PRODUCT.staging.md
 
# Use staging-specific config
claude --config PRODUCT.staging.md

Next Steps