Initial commit
This commit is contained in:
Zhongwei Li
389
skills/adw-bootstrap/README.md
Normal file
389
skills/adw-bootstrap/README.md
Normal file
@@ -0,0 +1,389 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user