# ADW Bootstrap Skill

A Claude skill that intelligently bootstraps **AI Developer Workflows (ADWs)** infrastructure in any codebase, enabling programmatic agent orchestration for automated development.

## What It Does

Transforms a regular project into one where AI agents can be invoked programmatically to plan, implement, test, and deploy features.

**After setup, you can:**
- Execute prompts programmatically: `./adws/adw_prompt.py "implement feature X"`
- Use reusable templates: `./adws/adw_slash_command.py /chore "task"`
- Orchestrate multi-phase workflows: Plan → Implement → Test
- Track agent behavior with structured outputs in `agents/{id}/`
- Scale compute for parallel development

## Installation

### User Skill (Personal Use)

```bash
# Clone or copy this skill to your Claude skills directory
cp -r adw-bootstrap ~/.claude/skills/

# Or create symlink
ln -s /path/to/adw-bootstrap ~/.claude/skills/adw-bootstrap
```

### Verify Installation

The skill should appear when you type `/skills` in Claude Code.

## Usage

### Automatic Trigger

The skill activates when you say:
- "Set up ADWs"
- "Bootstrap agentic workflows"
- "Add AI developer workflows"
- "Enable programmatic agent execution"
- "Initialize ADW infrastructure"

### Manual Invocation

```bash
# In Claude Code
/adw-bootstrap

# Or invoke the skill programmatically
adw-bootstrap
```

### Options

During setup, Claude will:
1. Analyze your project structure
2. Recommend a setup phase (minimal/enhanced/scaled)
3. Ask for confirmation
4. Create adapted infrastructure
5. Validate the setup

## What Gets Created

### Minimal Setup (Always)
```
your-project/
├── adws/
│   ├── adw_modules/
│   │   └── agent.py          # Core subprocess execution
│   └── adw_prompt.py          # CLI wrapper
├── .claude/commands/
│   ├── chore.md              # Planning template
│   └── implement.md          # Implementation template
├── specs/                     # Implementation plans
├── agents/                    # Output observability
└── .env.sample               # Configuration template
```

### Enhanced Setup (Recommended)
Adds:
- `agent_sdk.py` - SDK-based execution
- `adw_slash_command.py` - Command executor
- `adw_chore_implement.py` - Compound workflows
- Additional slash commands (feature.md, prime.md, start.md)

### Scaled Setup (Production)
Adds:
- State management (`state.py`, `adw_state.json`)
- Git operations (`git_ops.py`)
- Worktree isolation (`worktree_ops.py`, `trees/`)
- GitHub integration (`github.py`)
- Workflow orchestration (`workflow_ops.py`)
- Multi-phase workflows (`adw_sdlc_iso.py`, `adw_ship_iso.py`)
- Advanced slash commands (20+ commands)
- Testing infrastructure

## Upgrading Existing ADW Setup

If you already have ADWs in your project, the skill can upgrade to a higher phase:

### Upgrade Triggers

Say:
- "Upgrade my ADWs to enhanced"
- "Add scaled ADW capabilities"
- "Upgrade ADW infrastructure"

### Upgrade Process

The skill will:
1. **Detect** current phase (minimal/enhanced/scaled)
2. **Report** what infrastructure you have
3. **Recommend** available upgrades
4. **Backup** existing setup (`.adw_backups/`)
5. **Add** new capabilities without overwriting customizations
6. **Validate** the upgrade
7. **Report** what was added

**Safety Features:**
- Never overwrites customized files
- Creates timestamped backups
- Shows what will change before upgrading
- Rollback capability if upgrade fails

### Example Upgrade Output

```
🔍 Existing ADW setup detected!

Current Phase: Enhanced

Found infrastructure:
- Core modules: agent.py, agent_sdk.py
- CLI scripts: adw_prompt.py, adw_sdk_prompt.py, adw_slash_command.py
- Slash commands: 7 commands
- Workflows: 2 workflows

Available upgrades:
- Scaled: Adds state management, worktree isolation, GitHub integration,
  multi-phase workflows, and 15+ advanced commands

Would you like to upgrade to Scaled? (y/n)
```

After confirmation:
```
✅ Created backup in .adw_backups/20251103_102530/

Adding Scaled capabilities:
✅ Added adws/adw_modules/state.py
✅ Added adws/adw_modules/git_ops.py
✅ Added adws/adw_modules/worktree_ops.py
✅ Added adws/adw_modules/workflow_ops.py
✅ Added adws/adw_modules/github.py
✅ Added adws/adw_sdlc_iso.py
✅ Added 15 new slash commands
⚠️  Preserved customized: adws/adw_prompt.py

🎉 Upgrade to Scaled completed successfully!

Try the new capabilities:
- ./adws/adw_sdlc_iso.py 123  # Complete SDLC for issue #123
- ./adws/adw_ship_iso.py 123 abc12345  # Ship changes to main
```

## Usage After Bootstrap

### Execute Prompts
```bash
./adws/adw_prompt.py "analyze this code"
./adws/adw_prompt.py "quick syntax check" --model haiku
./adws/adw_prompt.py "refactor for performance" --model opus
```

Three models available:
- `haiku` - Fast & economical (2x speed, 1/3 cost)
- `sonnet` - Balanced excellence (default)
- `opus` - Maximum intelligence

### Use Slash Commands
```bash
# Create a plan
./adws/adw_slash_command.py /chore abc123 "add logging"

# Implement a plan
./adws/adw_slash_command.py /implement specs/chore-abc123-*.md
```

### Compound Workflows
```bash
# Plan + implement in one command
./adws/adw_chore_implement.py "add error handling to API"
```

## Validation

After setup, validate with:

```bash
# Run validation suite
~/.claude/skills/adw-bootstrap/utils/validator.py

# With test execution
~/.claude/skills/adw-bootstrap/utils/validator.py --test
```

## Documentation

- **SKILL.md** - Main skill logic and instructions
- **docs/principles.md** - Core ADW concepts and philosophy
- **docs/architecture.md** - Technical architecture deep dive
- **docs/usage-modes.md** - Subscription vs API modes
- **docs/examples.md** - Real-world bootstrap examples
- **reference/** - Working code examples for adaptation

## Key Features

### 1. Intelligent Adaptation
- Analyzes project structure and conventions
- Adapts reference code to fit the target project
- Handles novel structures without rigid templates

### 2. Progressive Enhancement
- Start minimal, add features as needed
- Clear upgrade path (minimal → enhanced → scaled)
- No over-engineering

### 3. Mode Flexibility
- **Subscription Mode**: No API key needed, perfect for development
- **API Mode**: Headless automation for CI/CD, webhooks, cron jobs
- Same infrastructure supports both

### 4. Project Agnostic
- Works on Python, TypeScript, Go, Rust, polyglot projects
- Adapts to any framework or structure
- Handles monorepos and single packages

### 5. Built-in Observability
- Structured outputs in `agents/{id}/`
- Multiple formats (JSONL, JSON, summaries)
- Debug agent behavior easily

## Architecture

### Two-Layer Model

**Agentic Layer** (`adws/`, `.claude/`, `specs/`)
- Templates engineering patterns
- Teaches agents how to operate
- Orchestrates workflows

**Application Layer** (`apps/`, `src/`, etc.)
- Your actual application code
- What agents read and modify

### Subprocess vs SDK

- **Subprocess** (agent.py): Simple, universal, minimal dependencies
- **SDK** (agent_sdk.py): Type-safe, async/await, interactive sessions

Both work seamlessly in the same infrastructure.

## Requirements

- **Claude Code CLI** installed and accessible
- **Python 3.10+** for ADW scripts
- **ANTHROPIC_API_KEY** (optional, for API mode)
- **uv** (recommended) or other Python package manager

## Troubleshooting

### Skill doesn't trigger
- Check skill is in `~/.claude/skills/adw-bootstrap/`
- Verify SKILL.md has frontmatter with trigger phrases
- Try manual invocation: `/adw-bootstrap`

### Bootstrap fails
- Ensure Claude Code CLI is installed: `claude --version`
- Check project directory is readable
- Look for error messages in Claude's response

### Validation fails
- Run: `~/.claude/skills/adw-bootstrap/utils/validator.py`
- Check specific failures and fix issues
- Ensure scripts are executable: `chmod +x adws/*.py`

### Scripts don't execute
- Make executable: `chmod +x adws/adw_prompt.py`
- Check Python version: `python --version` (need 3.10+)
- For uv scripts, ensure uv is installed: `uv --version`

## Examples

### Bootstrap Python Project
```
"Set up ADWs in this FastAPI project"
→ Analyzes pyproject.toml, detects FastAPI
→ Creates enhanced setup with uv
→ Adapts validation to use pytest, ruff
→ Ready to use!
```

### Bootstrap TypeScript Project
```
"Initialize AI developer workflows"
→ Analyzes package.json, detects Next.js
→ Creates enhanced setup
→ Adapts validation to use npm scripts
→ Python ADWs work on TypeScript code!
```

### Upgrade Existing Setup
```
"Upgrade my ADW setup to enhanced"
→ Detects existing minimal setup
→ Adds SDK support and compound workflows
→ Preserves existing customizations
→ Enhanced features now available!
```

## Development

### Testing the Skill

```bash
# Test on this project (dog-fooding)
cd /path/to/project
# In Claude Code:
"Set up ADWs here"

# Validate
~/.claude/skills/adw-bootstrap/utils/validator.py

# Try it
./adws/adw_prompt.py "test prompt"
```

### Modifying Reference Code

Reference implementations in `reference/` are copied to target projects. To update:

1. Modify files in `reference/`
2. Test changes in a sample project
3. Update SKILL.md instructions if needed
4. Document changes in this README

### Adding New Features

To add new capabilities:

1. **New ADW script**: Add to `reference/enhanced/` or `reference/scaled/`
2. **New slash command**: Add to `reference/*/commands/`
3. **Update SKILL.md**: Add instructions for adaptation
4. **Update docs**: Document the feature

## Philosophy

> "Template your engineering patterns, teach agents how to operate your codebase, scale compute to scale impact."

ADWs represent a paradigm shift from **writing code yourself** to **teaching agents to write code**. This skill makes that paradigm accessible to any project.

## License

This skill is part of the ADW framework project.

## Contributing

Improvements welcome! Key areas:

- Additional reference implementations
- Project type adapters
- Enhanced validation
- More examples
- Better documentation

## Support

- Check documentation in `docs/`
- Review examples in `docs/examples.md`
- Validate setup with `utils/validator.py`
- Read generated CLAUDE.md in target projects

## Version

1.0.0 - Initial release

## Credits

Built from the patterns developed in the tac8_app1__agent_layer_primitives project, extracting universal patterns for any codebase.