Traditional software engineering meets AI.

Claude is brilliant but drifts. It starts with a plan, then improvises. Documentation falls out of sync. Tests get "added later." Direction shifts mid-feature.

autonomous-dev provides macro alignment with micro flexibility:

• Macro: PROJECT.md defines goals, scope, constraints — Claude checks alignment before every feature
• Micro: Claude can still improve the implementation when it finds better patterns

research → plan → test → implement → review → security → docs → commit

Every step. Every feature. Documentation, tests, and code stay in sync automatically.

/auto-implement "issue #72"

# 1. Install
bash <(curl -sSL https://raw.githubusercontent.com/akaszubski/autonomous-dev/master/install.sh)

# 2. Restart Claude Code (required - commands are cached)
# Press Cmd+Q, then reopen

# 3. Use
/auto-implement "your feature description"

Requirements:

• Claude Code 2.0+
• macOS (not tested on Windows/Linux)
• Python 3.9+

System tools (install separately):

• git: xcode-select --install or brew install git
• gh CLI: brew install gh && gh auth login (required for GitHub automation)

For contributors: Development dependencies are in plugins/autonomous-dev/requirements-dev.txt (pytest, coverage, etc.)

Claude working alone drifts. Claude working within a framework stays consistent.

The insight: This isn't about limiting Claude. It's about fusing traditional software engineering discipline with AI capability. Claude brings intelligence; the framework brings consistency.

When you run /auto-implement "add user authentication":

Total: 15-30 minutes depending on complexity.

After completion:

• ✅ Code committed with conventional commit message
• ✅ Changes pushed to your branch
• ✅ Pull request created
• ✅ GitHub issue auto-closed

Most AI coding tools answer from training data. That's fine for "how do I sort a list" but dangerous for "what's the current best practice for JWT authentication."

We force actual web search:

└─ Task (Research best practices) · 5 tool uses ✅
   ⎿  Web Search: JWT authentication best practices 2024...

If you see 0 tool uses, the pipeline blocks:

❌ Web research failed: 0 WebSearch calls made.
   Results would be hallucinated. Retrying...

This validation was added because we caught Claude returning "best practices" that it never actually searched for.

# .claude/PROJECT.md

## GOALS
- Build REST API for user management
- Ship MVP by end of Q1

## SCOPE
IN: User CRUD, authentication, password reset
OUT: Admin dashboard, analytics, billing

## CONSTRAINTS
- Python 3.11+ with FastAPI
- PostgreSQL database
- JWT authentication (no sessions)

Request something IN scope: Claude follows your constraints.

Request something OUT of scope: Blocked immediately.

❌ BLOCKED: Feature not aligned with PROJECT.md

Feature requested: "Add analytics dashboard"
Why blocked: Explicitly OUT of scope

This prevents the "while I'm here, let me also refactor..." drift.

We document typical performance, not marketing claims.

Fully unattended: /batch-implement handles context limits automatically. State persists externally, so when Claude auto-compacts, the next feature bootstraps fresh and continues. No manual intervention needed.

~/.claude/              # Global (shared across projects)
├── hooks/              # Automation hooks
├── lib/                # Shared Python libraries
└── settings.json       # Hook configuration

.claude/                # Per-project
├── commands/           # Slash commands
├── agents/             # AI agents
├── config/             # Policy files
├── scripts/            # Utility scripts
└── PROJECT.md          # Your scope definition

Why global components? Claude Code's settings.json references hooks by absolute path. Global installation ensures hooks work in any project.

After the initial install, adding autonomous-dev to another project is simple:

# 1. Open the new project in Claude Code
cd /path/to/your/other/project

# 2. Sync commands and agents (global hooks already work)
/sync

# 3. Restart Claude Code to load new commands
# Press Cmd+Q, then reopen

# 4. Create PROJECT.md for this repo (optional but recommended)
/setup

What /sync does:

• Pulls commands to .claude/commands/
• Pulls agents to .claude/agents/
• Global hooks already work (installed to ~/.claude/hooks/)

Important: Always restart Claude Code after /sync — commands are cached in memory.

• macOS tested - Primary development platform
• Linux likely works (similar paths) but unverified
• Windows untested

• Restart required after /sync - Commands are cached in memory
• Python 3.9+ required - For library code
• gh CLI required - For GitHub automation features

• Context limits exist - 4-8 features per window, but batch processing handles this
• Complex installation - Can't be marketplace-only due to global hooks requirement

• Not a marketplace plugin - Requires global installation
• Not cross-platform - macOS only (for now)
• Not magic - Claude still makes mistakes, just more consistently
• Not for "vibe coding" - This is for disciplined, production-quality work

• Architecture - How the two-layer system works
• Agents - Specialized AI agents
• Hooks - Automation hooks reference
• Batch Processing - Multi-feature workflows
• Git Automation - Auto-commit, push, PR
• Environment Configuration - All .env variables and settings
• Troubleshooting

Issues and PRs welcome at github.com/akaszubski/autonomous-dev.

This project uses itself for development (dogfooding). Every feature was built using /auto-implement.

MIT License - See LICENSE for details.

autonomous-dev is traditional software engineering discipline for AI-assisted development:

1. Macro alignment - PROJECT.md keeps direction consistent
2. Micro flexibility - Claude improves implementations when it finds better patterns
3. Consistent pipeline - Same 8 steps every time
4. Real web research - Validated, not hallucinated from training data
5. Everything stays in sync - Docs, tests, code updated together
6. Batch processing - 50+ features with crash recovery

The fusion: You define the direction. Claude brings the intelligence. The framework keeps everything consistent.

bash <(curl -sSL https://raw.githubusercontent.com/akaszubski/autonomous-dev/master/install.sh)
# Restart Claude Code (Cmd+Q)
/auto-implement "your feature"