🤖 Agentful

One-Command Autonomous Product Development Kit for Claude Code

⚠️ WARNING: Alpha Release (v0.1.0)

This software is EXPERIMENTAL and UNTESTED. Use at your own risk! Not recommended for production projects.

Agentful is an opinionated starter template for Claude Code that transforms it into an autonomous development system. It's a pre-packaged .claude/ configuration that supercharges Claude Code with specialized agents, skills, and commands for accelerated development.

✨ Features

• Zero Config Drop-In - Just run npx agentful init in any project
• Autonomous Development - Works 24/7 with Ralph Wiggum loops
• Specialized Agents - Backend, Frontend, Tester, Reviewer, Fixer, Architect
• Dynamic Tech Stack Detection - Automatically generates agents for your stack
• Quality Gates - Type checking, Linting, Tests, Coverage, Security, Dead code detection (adapts to YOUR stack)
• Progress Tracking - See exactly what's done and what's next
• Decision Handling - Agentful asks, you answer, it continues

🚀 Quick Start

1. Initialize in Your Project

npx agentful init

This creates:

• .claude/ - Pre-configured agents, commands, skills (committed to git)
• .agentful/ - Runtime state only (gitignored, auto-created)
  • state.json - Current work state
  • completion.json - Progress tracking
  • decisions.json - Pending user decisions
  • architecture.json - Detected tech stack
• PRODUCT.md - Your product spec template
• CLAUDE.md - Project instructions

Note: .agentful/ is gitignored and will be populated automatically during runtime.

2. Edit Your Product Spec

Open PRODUCT.md and describe what you want to build:

## Overview
A task management app for teams.

## Tech Stack
- Next.js 14 + TypeScript
- Prisma + PostgreSQL
- Tailwind CSS
- Vitest + Playwright

## Features
1. Authentication (CRITICAL)
2. Project management (HIGH)
3. Task assignment (MEDIUM)

3. Start Claude Code

claude

4. Begin Autonomous Development

/agentful-start

That's it! Agentful will:

1. Analyze your PRODUCT.md
2. Detect your tech stack
3. Generate specialized agents
4. Start building autonomously

🌙 24/7 Development

For fully autonomous overnight development, use the Ralph Wiggum plugin:

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

Agentful will work while you sleep, only stopping when:

• All features are complete (100%)
• All quality gates pass
• Or max iterations reached

📋 Commands

🤖 Agents

Agentful includes specialized agents that work together:

📊 Quality Gates

Code must pass ALL gates before completion:

• ✅ All tests passing
• ✅ No TypeScript errors
• ✅ No lint errors
• ✅ No dead code (unused exports, files, dependencies)
• ✅ Test coverage ≥ 80%
• ✅ No security issues

🎯 How It Works

graph LR
    A[Initialize] --> B[Define Product]
    B --> C[Start Building]

    A --> A1[npx agentful init]
    B --> B1[Edit PRODUCT.md]
    C --> C1[/agentful-start]

    B1 --> B2[Your specs + tech stack]
    C1 --> C2[Autonomous development]
    C2 --> C3[24/7 Ralph Wiggum loops]
    C3 --> C4[100% complete]

📁 Project Structure

After initialization, your project will have:

your-project/
├── PRODUCT.md              # ← Edit this: your product spec
├── CLAUDE.md               # Project instructions for Claude
├── .claude/                # Agentful configuration (version control)
│   ├── agents/             # Specialized agents
│   │   ├── orchestrator.md
│   │   ├── architect.md
│   │   ├── backend.md
│   │   ├── frontend.md
│   │   ├── tester.md
│   │   ├── reviewer.md
│   │   └── fixer.md
│   ├── commands/           # Slash commands
│   │   ├── agentful-start.md
│   │   ├── agentful-status.md
│   │   ├── agentful-decide.md
│   │   └── agentful-validate.md
│   ├── skills/             # Domain skills
│   │   ├── product-tracking/
│   │   └── validation/
│   └── settings.json       # Hooks and permissions
├── .agentful/              # Runtime state (gitignored)
│   ├── state.json          # Current work state
│   ├── completion.json     # Progress tracking
│   ├── decisions.json      # Pending/resolved decisions
│   └── architecture.json   # Detected tech stack
└── src/                    # Your code (generated by Agentful)

🎨 Customization

All of Agentful is customizable. Edit files in .claude/ to:

• Add agents - Create new .claude/agents/your-agent.md
• Modify commands - Edit .claude/commands/*.md
• Add skills - Create .claude/skills/your-skill/SKILL.md
• Change hooks - Edit .claude/settings.json

🔧 Requirements

• Claude Code - Install here
• Node.js 18+ - For CLI tool

Optional: 24/7 Autonomous Development

For fully autonomous overnight development, install the Ralph Wiggum plugin inside Claude Code:

# 1. Start Claude Code in your project
claude

# 2. Inside Claude Code, install the plugin
/plugin install ralph-wiggum@anthropics

# 3. Then run autonomous loops
/ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"

📚 Example PRODUCT.md

# Product Specification

## Overview
A modern task management application for remote teams.

## Tech Stack
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes, Prisma
- **Database**: PostgreSQL (Supabase)
- **Auth**: JWT with httpOnly cookies
- **Testing**: Vitest, Playwright

## Features

### Domain 1: Authentication & Authorization
#### 1.1 User Authentication - CRITICAL
**Description**: User registration and login

**Acceptance Criteria**:
- [x] Registration with email/password
- [x] Login with email/password
- [x] JWT token generation
- [x] Protected routes
- [x] Logout functionality

#### 1.2 Session Management - HIGH
**Description**: Manage user sessions and tokens

**Acceptance Criteria**:
- [ ] Token refresh mechanism
- [ ] Session timeout handling
- [ ] Multi-device session management
- [ ] Logout from all devices

### Domain 2: Project & Workspace Management
#### 2.1 Project Management - HIGH
**Description**: Create and manage projects

**Acceptance Criteria**:
- [ ] Create project
- [ ] Edit project
- [ ] Delete project
- [ ] List all projects
- [ ] Project membership

#### 2.2 Workspace Organization - MEDIUM
**Description**: Organize projects into workspaces

**Acceptance Criteria**:
- [ ] Create workspace
- [ ] Add projects to workspace
- [ ] Workspace settings
- [ ] Member invitations

### Domain 3: Task & Collaboration Management
#### 3.1 Task Management - HIGH
**Description**: Create and manage tasks within projects

**Acceptance Criteria**:
- [ ] Create task
- [ ] Assign task to user
- [ ] Set task status (todo, in progress, done)
- [ ] Set task priority
- [ ] Add task comments

#### 3.2 Team Collaboration - MEDIUM
**Description**: Real-time collaboration features

**Acceptance Criteria**:
- [ ] Real-time task updates
- [ ] Team activity feed
- [ ] @mentions and notifications
- [ ] Comments and discussions

## Success Criteria
- All features implemented and tested
- 80%+ test coverage
- No TypeScript errors
- Deployed to production

🤝 Contributing

Contributions welcome! Read CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🌐 Links

• Website: agentful.app
• GitHub: github.com/itz4blitz/agentful
• Issues: github.com/itz4blitz/agentful/issues
• Discord: Join Community

Made with ❤️ for autonomous development