agentful

A carrot on a stick for Claude Code

Overview

agentful is a Claude Code configuration that provides structured development through specialized AI agents. It coordinates multiple agents to implement features, write tests, and validate code quality according to a defined product specification.

Web Configurator

Configure your agentful installation with an interactive web interface:

agentful.app

• Visual component selection
• 2 optimized presets
• Custom configurations
• Shareable setup URLs
• No CLI required

Installation

Default Installation (Recommended)

Install agentful with all components - works with any tech stack:

npx @itz4blitz/agentful init

This installs:

• 8 agents: orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
• 6 skills: product-tracking, validation, testing, conversation, product-planning, deployment
• Quality gates: types, tests, coverage, lint, security, dead-code

Tech stack is auto-detected on first run (TypeScript, Python, React, etc.) - no need to specify.

Minimal Installation

For simple scripts/CLIs that only need backend code:

npx @itz4blitz/agentful init --preset=minimal

This installs only:

• 2 agents: orchestrator, backend
• 1 skill: validation

Custom Installation

Specify exactly what you want:

# Custom agents and skills
npx @itz4blitz/agentful init --agents=orchestrator,backend,frontend --skills=validation,testing

# View installation options
npx @itz4blitz/agentful presets

Shareable Configurations

Use a configuration from the web configurator:

npx @itz4blitz/agentful init --config=<shareable-url>

Available Flags:

• --preset=<name> - Use a preset configuration
• --agents=<list> - Comma-separated list of agents (orchestrator, backend, frontend, tester, reviewer, fixer, architect, product-analyzer)
• --skills=<list> - Comma-separated list of skills (validation, testing, product-tracking, conversation, product-planning, deployment)
• --gates=<list> - Comma-separated list of quality gates (types, tests, coverage, lint, security, dead-code)

Flags override preset values when both are specified.

Updating

After initial installation, use the /agentful-update command to update your configuration:

claude  # Start Claude Code
/agentful-update

This command:

• Fetches the latest templates from the current agentful version
• Performs a 3-way merge to preserve your customizations
• Creates backups before applying changes
• Gracefully handles conflicts and reports issues

Important: Run npx @itz4blitz/agentful init only once during initial setup. For all subsequent updates, use /agentful-update instead of re-running init.

Usage

1. Define Product Specification

After initialization, define your product requirements:

Option A: Interactive Planning (Recommended)

claude  # Start Claude Code

Use /agentful-product for guided product planning:

• New projects: Interactive Q&A creates your product spec
• Existing specs: Analyzes for gaps, ambiguities, blocking issues
• Readiness scoring: Get a score (0-100) before development
• Issue resolution: Walk through blocking issues with smart suggestions
• Q&A mode: Ask planning questions in context

Option B: Manual Creation

Create your specification manually in .claude/product/:

Flat structure (single file):

• .claude/product/index.md - All features in one file

Hierarchical structure (organized by domain):

• .claude/product/index.md - Product overview
• .claude/product/domains/*/features/ - Feature definitions organized by domain

2. Start Development

claude  # Start Claude Code

Then use the /agentful-start command to begin structured development.

New Projects (No Existing Code)

For brand new projects with no code yet:

1. Tech Stack Selection: On first run, the architect agent will ask about your tech stack:

   • Frontend framework (React, Vue, Next.js, etc.)
   • Backend framework (Express, Django, Spring Boot, etc.)
   • Database (PostgreSQL, MongoDB, MySQL, etc.)
   • Additional tools (ORM, testing framework, styling)

2. Initial Agent Generation: Specialized agents are generated using best practices for your chosen stack:

   • Based on official framework documentation
   • Using common patterns and conventions
   • Marked with confidence: 0.4 (template-based)

3. First Feature Implementation: The system builds your first feature using these template agents

4. Automatic Re-Analysis: After the first feature is complete:

   • Architect re-analyzes your actual code
   • Updates agents with your project's specific patterns
   • Confidence increases (0.4 → 0.8+)
   • Remaining features use refined, project-specific agents

Benefits:

• ✅ Start immediately without existing code
• ✅ No blocking on pattern detection
• ✅ Learns and adapts after first implementation
• ✅ Continuously improving agent quality

Existing Projects (With Code)

For projects with existing code:

1. Pattern Detection: Architect samples your codebase to detect:

   • Language and framework
   • File organization patterns
   • Coding conventions
   • Import/export styles
   • Error handling patterns

2. Agent Generation: Creates specialized agents matching your exact conventions

   • Real code examples from your project
   • Your specific patterns and styles
   • High confidence (0.8-1.0)

3. Monitor Progress

• /agentful-status - View completion percentage and current work
• /agentful-validate - Run quality checks
• /agentful-decide - Answer blocking questions

Architecture

Agent System

agentful uses eight specialized agents:

Quality Gates

Code changes are validated against 6 automated quality gates:

• Type checking (TypeScript, Flow, etc.)
• Linting (ESLint, Biome, etc.)
• Test execution
• Code coverage
• Security scanning
• Dead code detection

State Tracking

Runtime state is stored in .agentful/ (gitignored, managed by npm package):

• state.json - Current task and phase
• completion.json - Feature completion status
• decisions.json - Pending and resolved decisions
• architecture.json - Technology stack (declared or detected)
  • New projects: Starts with declared stack (confidence: 0.4)
  • Existing projects: Detected from code (confidence: 0.8-1.0)
  • Re-analyzed after first implementation in new projects
• conversation-history.json - Session tracking

User configuration is stored in .claude/ (version controlled):

• agents/ - Agent definitions
• commands/ - Slash commands
• product/ - Product specifications
  • index.md - Main product spec (user editable)
  • domains/ - Optional hierarchical structure
• skills/ - Reusable skill modules
  • conversation/ - Intent classification and context management
  • product-tracking/ - Progress calculation and state tracking
  • product-planning/ - Product specification guidance
  • validation/ - Quality gate checks and tool detection
  • testing/ - Test strategy and coverage
  • deployment/ - Deployment preparation and validation
• settings.json - Project configuration

Commands

CI/CD Integration

Run agentful agents in GitHub Actions, GitLab CI, Jenkins, or Bitbucket Pipelines.

# Generate workflow files for your CI platform
agentful ci --generate-workflow

# Or use the interactive command
agentful ci

See examples/ for sample workflow configurations (GitHub Actions, GitLab CI).

Remote Execution

Run agentful agents on remote servers via secure HTTP API.

# Start server with Tailscale (most secure, recommended)
agentful serve

# Start server with HMAC authentication and HTTPS
agentful serve --auth=hmac --secret=$SECRET --https --cert=cert.pem --key=key.pem

# Start server for local SSH tunnel access
agentful serve --auth=none

Three authentication modes: Tailscale (WireGuard encryption), HMAC (signature-based with replay protection), SSH tunnel (localhost-only).

Technology Support

agentful detects and adapts to your technology stack automatically:

• Languages: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, Elixir
• Frontend: React, Vue, Angular, Svelte, Next.js, Astro, SolidJS
• Backend: Express, Fastify, NestJS, Hono, Next.js API Routes
• Databases: PostgreSQL, MySQL, SQLite, MongoDB
• ORMs: Prisma, Drizzle, TypeORM, Mongoose
• Testing: Jest, Vitest, Playwright, Cypress, Pytest, JUnit

Requirements

• Claude Code (code.anthropic.com)
• Node.js 22 or higher
• Git

Documentation

Documentation: agentful.app

Project Structure

your-project/
├── CLAUDE.md                       # Project instructions
├── .claude/
│   ├── product/                    # Product specification
│   │   ├── index.md                # Product spec (flat or hierarchical)
│   │   └── domains/                # Optional: hierarchical structure
│   ├── agents/                     # Agent definitions
│   ├── commands/                   # Slash commands
│   ├── skills/                     # Reusable skills
│   └── settings.json               # Configuration
├── .agentful/                      # Runtime state (gitignored)
│   ├── state.json
│   ├── completion.json
│   ├── decisions.json
│   ├── architecture.json
│   └── conversation-history.json
└── src/                            # Source code

License

MIT

Links

• GitHub: github.com/itz4blitz/agentful
• Issues: github.com/itz4blitz/agentful/issues
• NPM: npmjs.com/package/@itz4blitz/agentful