Initial commit
This commit is contained in:
Zhongwei Li
687
skills/adw-bootstrap/docs/architecture.md
Normal file
687
skills/adw-bootstrap/docs/architecture.md
Normal file
@@ -0,0 +1,687 @@
|
||||
# ADW Architecture Deep Dive
|
||||
|
||||
## System Overview
|
||||
|
||||
ADW infrastructure creates a **programmatic interface** for AI-driven development by wrapping the application layer with an agentic layer that templates engineering patterns.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Agentic Layer │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ ADW Scripts (adws/) │ │
|
||||
│ │ - Execute prompts programmatically │ │
|
||||
│ │ - Orchestrate multi-phase workflows │ │
|
||||
│ │ - Invoke Claude Code CLI or SDK │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Slash Commands (.claude/commands/) │ │
|
||||
│ │ - Reusable prompt templates │ │
|
||||
│ │ - Structured instructions for agents │ │
|
||||
│ │ - Variable substitution │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Specifications (specs/) │ │
|
||||
│ │ - Implementation plans │ │
|
||||
│ │ - Step-by-step tasks │ │
|
||||
│ │ - Validation commands │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Claude Code (subprocess or SDK) │ │
|
||||
│ │ - Executes prompts with tools │ │
|
||||
│ │ - Modifies application code │ │
|
||||
│ │ - Returns structured results │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Observability (agents/) │ │
|
||||
│ │ - Structured outputs │ │
|
||||
│ │ - Execution tracking │ │
|
||||
│ │ - Debug artifacts │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ - Your actual application code (apps/, src/, lib/) │
|
||||
│ - Tests, configs, documentation │
|
||||
│ - What agents read and modify │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Modules
|
||||
|
||||
### agent.py - Subprocess Execution Engine
|
||||
|
||||
**Purpose**: Core module for executing Claude Code CLI as subprocess
|
||||
|
||||
**Key Components**:
|
||||
|
||||
```python
|
||||
# Data Models
|
||||
class AgentPromptRequest(BaseModel):
|
||||
prompt: str # What to execute
|
||||
adw_id: str # Unique workflow ID
|
||||
agent_name: str # Agent identifier
|
||||
model: Literal["sonnet", "opus"]
|
||||
output_file: str # Where to save output
|
||||
working_dir: Optional[str] # Where to run
|
||||
|
||||
class AgentPromptResponse(BaseModel):
|
||||
output: str # Result text
|
||||
success: bool # Did it succeed?
|
||||
session_id: Optional[str] # Claude session ID
|
||||
retry_code: RetryCode # Should we retry?
|
||||
|
||||
# Core Functions
|
||||
def prompt_claude_code(request: AgentPromptRequest) -> AgentPromptResponse
|
||||
def prompt_claude_code_with_retry(request: AgentPromptRequest) -> AgentPromptResponse
|
||||
def execute_template(request: AgentTemplateRequest) -> AgentPromptResponse
|
||||
```
|
||||
|
||||
**Execution Flow**:
|
||||
|
||||
1. **Build Command**
|
||||
```python
|
||||
cmd = [
|
||||
"claude",
|
||||
"-p", prompt,
|
||||
"--model", model,
|
||||
"--output-format", "stream-json",
|
||||
"--verbose"
|
||||
]
|
||||
```
|
||||
|
||||
2. **Filter Environment**
|
||||
```python
|
||||
env = get_safe_subprocess_env()
|
||||
# Only passes essential variables
|
||||
# Prevents environment leakage
|
||||
```
|
||||
|
||||
3. **Execute & Stream**
|
||||
```python
|
||||
subprocess.run(
|
||||
cmd,
|
||||
stdout=output_file, # Stream to file
|
||||
stderr=subprocess.PIPE,
|
||||
env=env
|
||||
)
|
||||
```
|
||||
|
||||
4. **Parse JSONL Output**
|
||||
```python
|
||||
messages = [json.loads(line) for line in f]
|
||||
result_message = find_result_message(messages)
|
||||
```
|
||||
|
||||
5. **Convert to Multiple Formats**
|
||||
- `cc_raw_output.jsonl` - Raw streaming JSONL
|
||||
- `cc_raw_output.json` - Parsed JSON array
|
||||
- `cc_final_object.json` - Final result object
|
||||
|
||||
6. **Return Response**
|
||||
```python
|
||||
return AgentPromptResponse(
|
||||
output=result_text,
|
||||
success=not is_error,
|
||||
session_id=session_id,
|
||||
retry_code=RetryCode.NONE
|
||||
)
|
||||
```
|
||||
|
||||
**Error Handling**:
|
||||
- Retry codes distinguish transient from permanent errors
|
||||
- Output truncation prevents console flooding
|
||||
- Graceful degradation on parse failures
|
||||
|
||||
### agent_sdk.py - SDK Execution Engine
|
||||
|
||||
**Purpose**: Type-safe, async execution using Claude Code Python SDK
|
||||
|
||||
**Key Patterns**:
|
||||
|
||||
```python
|
||||
# One-shot query
|
||||
async def simple_query(prompt: str) -> str:
|
||||
options = ClaudeCodeOptions(model="claude-sonnet-4-20250514")
|
||||
texts = []
|
||||
async for message in query(prompt=prompt, options=options):
|
||||
if isinstance(message, AssistantMessage):
|
||||
texts.append(extract_text(message))
|
||||
return "\n".join(texts)
|
||||
|
||||
# Interactive session
|
||||
@asynccontextmanager
|
||||
async def create_session():
|
||||
client = ClaudeSDKClient(options=options)
|
||||
await client.connect()
|
||||
try:
|
||||
yield client
|
||||
finally:
|
||||
await client.disconnect()
|
||||
```
|
||||
|
||||
**Advantages**:
|
||||
- Native async/await patterns
|
||||
- Typed message objects (AssistantMessage, ResultMessage)
|
||||
- SDK-specific error handling
|
||||
- Interactive session support
|
||||
- Better IDE integration
|
||||
|
||||
**When to Use**:
|
||||
- Interactive multi-turn conversations
|
||||
- Need better type safety
|
||||
- Async workflow integration
|
||||
- Native Python integration preferred
|
||||
|
||||
## Data Flow Patterns
|
||||
|
||||
### Pattern 1: Direct Prompt Execution
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
./adws/adw_prompt.py "analyze this"
|
||||
↓
|
||||
AgentPromptRequest created
|
||||
↓
|
||||
prompt_claude_code_with_retry()
|
||||
↓
|
||||
subprocess: claude -p "analyze this"
|
||||
↓
|
||||
JSONL output streamed to file
|
||||
↓
|
||||
Parse JSONL → JSON conversion
|
||||
↓
|
||||
AgentPromptResponse returned
|
||||
↓
|
||||
Display to user + save summary
|
||||
```
|
||||
|
||||
### Pattern 2: Slash Command Execution
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
./adws/adw_slash_command.py /chore abc123 "task"
|
||||
↓
|
||||
Read .claude/commands/chore.md
|
||||
↓
|
||||
Substitute variables ($1, $2)
|
||||
↓
|
||||
AgentTemplateRequest created
|
||||
↓
|
||||
execute_template() → prompt_claude_code_with_retry()
|
||||
↓
|
||||
subprocess: claude -p "<expanded template>"
|
||||
↓
|
||||
Parse results
|
||||
↓
|
||||
Extract spec path from output
|
||||
↓
|
||||
Display + save
|
||||
```
|
||||
|
||||
### Pattern 3: Compound Workflow
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
./adws/adw_chore_implement.py "feature X"
|
||||
↓
|
||||
Generate unique adw_id
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Phase 1: Planning │
|
||||
├─────────────────────────────────────┤
|
||||
│ execute_template("/chore", args) │
|
||||
│ ↓ │
|
||||
│ Create plan in specs/ │
|
||||
│ ↓ │
|
||||
│ Parse output for plan path │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Phase 2: Implementation │
|
||||
├─────────────────────────────────────┤
|
||||
│ execute_template("/implement", path) │
|
||||
│ ↓ │
|
||||
│ Read plan from specs/ │
|
||||
│ ↓ │
|
||||
│ Execute step by step │
|
||||
│ ↓ │
|
||||
│ Modify application code │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
Workflow summary saved
|
||||
↓
|
||||
Display results to user
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Minimal Setup
|
||||
|
||||
```
|
||||
project/
|
||||
├── adws/
|
||||
│ ├── adw_modules/
|
||||
│ │ └── agent.py # Core execution
|
||||
│ └── adw_prompt.py # CLI wrapper
|
||||
├── .claude/commands/
|
||||
│ ├── chore.md # Planning template
|
||||
│ └── implement.md # Implementation template
|
||||
├── specs/
|
||||
│ └── *.md # Generated plans
|
||||
├── agents/ # Output directory
|
||||
│ └── {adw_id}/
|
||||
│ └── {agent_name}/
|
||||
│ ├── cc_raw_output.jsonl
|
||||
│ ├── cc_raw_output.json
|
||||
│ ├── cc_final_object.json
|
||||
│ └── custom_summary_output.json
|
||||
└── .env.sample # Configuration template
|
||||
```
|
||||
|
||||
### Enhanced Setup
|
||||
|
||||
```
|
||||
project/
|
||||
├── adws/
|
||||
│ ├── adw_modules/
|
||||
│ │ ├── agent.py # Subprocess execution
|
||||
│ │ └── agent_sdk.py # SDK execution
|
||||
│ ├── adw_prompt.py # Direct prompts
|
||||
│ ├── adw_slash_command.py # Command executor
|
||||
│ └── adw_chore_implement.py # Compound workflow
|
||||
├── .claude/commands/
|
||||
│ ├── chore.md
|
||||
│ ├── implement.md
|
||||
│ ├── feature.md # Feature planning
|
||||
│ ├── test.md # Test creation
|
||||
│ ├── prime.md # Context loading
|
||||
│ └── start.md # App startup
|
||||
├── specs/
|
||||
│ ├── chore-*.md
|
||||
│ └── feature-*.md
|
||||
├── agents/
|
||||
│ └── {adw_id}/
|
||||
│ ├── planner/ # Planning agent outputs
|
||||
│ ├── builder/ # Building agent outputs
|
||||
│ └── workflow_summary.json # Overall summary
|
||||
└── CLAUDE.md # Updated with ADW docs
|
||||
```
|
||||
|
||||
### Scaled Setup (Production)
|
||||
|
||||
```
|
||||
project/
|
||||
├── adws/
|
||||
│ ├── adw_modules/
|
||||
│ │ ├── agent.py # Subprocess execution
|
||||
│ │ ├── agent_sdk.py # SDK execution
|
||||
│ │ ├── data_types.py # Type definitions
|
||||
│ │ ├── state.py # State management (adw_state.json)
|
||||
│ │ ├── git_ops.py # Git operations (branch, commit, push, PR)
|
||||
│ │ ├── worktree_ops.py # Worktree isolation management
|
||||
│ │ ├── workflow_ops.py # High-level orchestration
|
||||
│ │ ├── github.py # GitHub integration (gh CLI)
|
||||
│ │ └── utils.py # Shared utilities
|
||||
│ ├── adw_sdlc_iso.py # Complete SDLC (plan→build→test→review→doc)
|
||||
│ ├── adw_plan_build_test_review_iso.py # Compound isolated workflow
|
||||
│ ├── adw_ship_iso.py # Merge validation and shipping
|
||||
│ ├── adw_plan_iso.py # Isolated planning phase
|
||||
│ ├── adw_build_iso.py # Isolated build phase
|
||||
│ ├── adw_test_iso.py # Isolated testing phase
|
||||
│ ├── adw_review_iso.py # Isolated review phase
|
||||
│ └── adw_document_iso.py # Isolated documentation phase
|
||||
├── .claude/commands/
|
||||
│ ├── chore.md
|
||||
│ ├── bug.md
|
||||
│ ├── feature.md
|
||||
│ ├── implement.md
|
||||
│ ├── classify_issue.md # Issue classification
|
||||
│ ├── classify_adw.md # ADW workflow selection
|
||||
│ ├── generate_branch_name.md # Branch naming
|
||||
│ ├── patch.md # Patch planning
|
||||
│ ├── test.md # Test execution
|
||||
│ ├── review.md # Code review
|
||||
│ ├── document.md # Documentation generation
|
||||
│ ├── pull_request.md # PR creation
|
||||
│ ├── install_worktree.md # Worktree environment setup
|
||||
│ ├── cleanup_worktrees.md # Worktree cleanup
|
||||
│ ├── commit.md # Commit message generation
|
||||
│ ├── prime.md
|
||||
│ └── start.md
|
||||
├── specs/
|
||||
│ ├── chore-*.md
|
||||
│ ├── bug-*.md
|
||||
│ ├── feature-*.md
|
||||
│ └── patch/ # Patch plans
|
||||
├── agents/
|
||||
│ └── {adw_id}/
|
||||
│ ├── {agent_name}/ # Per-agent outputs
|
||||
│ ├── adw_state.json # Persistent state
|
||||
│ └── workflow_summary.json
|
||||
├── trees/ # Git worktree isolation
|
||||
│ └── {adw_id}/ # Isolated working directory
|
||||
│ ├── .ports.env # Port configuration
|
||||
│ └── <full repo copy>
|
||||
├── .adw_backups/ # Safety backups during upgrades
|
||||
├── CLAUDE.md # Updated with ADW docs
|
||||
└── .env.sample # Configuration
|
||||
```
|
||||
|
||||
**Key Scaled Phase Features:**
|
||||
|
||||
1. **State Management**: Persistent state across workflow phases via `adw_state.json`
|
||||
2. **Git Worktree Isolation**: Each ADW runs in isolated `trees/{adw_id}/` directory
|
||||
3. **Port Management**: Deterministic port allocation (9100-9114 backend, 9200-9214 frontend)
|
||||
4. **GitHub Integration**: Issue operations, PR management, comment posting via gh CLI
|
||||
5. **Multi-Phase Workflows**: Complete SDLC automation (plan, build, test, review, document, ship)
|
||||
6. **Workflow Composition**: High-level functions for issue classification, branch generation, etc.
|
||||
7. **Advanced Commands**: Rich library of 20+ specialized slash commands
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Observability Artifacts
|
||||
|
||||
Each ADW execution creates:
|
||||
|
||||
**cc_raw_output.jsonl**
|
||||
- Line-delimited JSON
|
||||
- Streaming output from Claude Code
|
||||
- Each line is a message object
|
||||
- Last line is result message
|
||||
|
||||
**cc_raw_output.json**
|
||||
- JSON array of all messages
|
||||
- Easier for programmatic processing
|
||||
- Contains full conversation history
|
||||
|
||||
**cc_final_object.json**
|
||||
- Just the last message (result)
|
||||
- Quick access to final output
|
||||
- Contains success/failure info
|
||||
|
||||
**custom_summary_output.json**
|
||||
- High-level execution summary
|
||||
- Metadata (adw_id, prompt, model)
|
||||
- Success status
|
||||
- Session ID for debugging
|
||||
|
||||
### Workflow Tracking
|
||||
|
||||
For compound workflows:
|
||||
|
||||
**workflow_summary.json**
|
||||
```json
|
||||
{
|
||||
"workflow": "chore_implement",
|
||||
"adw_id": "abc12345",
|
||||
"prompt": "add error handling",
|
||||
"phases": {
|
||||
"planning": {
|
||||
"success": true,
|
||||
"session_id": "session_xyz",
|
||||
"agent": "planner",
|
||||
"output_dir": "agents/abc12345/planner/"
|
||||
},
|
||||
"implementation": {
|
||||
"success": true,
|
||||
"session_id": "session_abc",
|
||||
"agent": "builder",
|
||||
"output_dir": "agents/abc12345/builder/"
|
||||
}
|
||||
},
|
||||
"overall_success": true
|
||||
}
|
||||
```
|
||||
|
||||
## Retry Logic Architecture
|
||||
|
||||
### Retry Code Classification
|
||||
|
||||
```python
|
||||
class RetryCode(str, Enum):
|
||||
CLAUDE_CODE_ERROR = "claude_code_error" # Retry
|
||||
TIMEOUT_ERROR = "timeout_error" # Retry
|
||||
EXECUTION_ERROR = "execution_error" # Retry
|
||||
ERROR_DURING_EXECUTION = "error_during_execution" # Retry
|
||||
NONE = "none" # Don't retry
|
||||
```
|
||||
|
||||
### Retry Decision Flow
|
||||
|
||||
```
|
||||
Execute prompt
|
||||
↓
|
||||
Success? → Return response
|
||||
↓ No
|
||||
Check retry_code
|
||||
↓
|
||||
NONE? → Return response (don't retry)
|
||||
↓ No
|
||||
Retryable error?
|
||||
↓ Yes
|
||||
Attempts < max_retries?
|
||||
↓ Yes
|
||||
Wait (exponential backoff: 1s, 3s, 5s)
|
||||
↓
|
||||
Retry execution
|
||||
↓
|
||||
(Loop back to top)
|
||||
↓
|
||||
Max retries reached? → Return last response
|
||||
```
|
||||
|
||||
### Default Configuration
|
||||
|
||||
```python
|
||||
max_retries = 3
|
||||
retry_delays = [1, 3, 5] # seconds
|
||||
|
||||
# Exponential backoff:
|
||||
# Attempt 1: fail → wait 1s
|
||||
# Attempt 2: fail → wait 3s
|
||||
# Attempt 3: fail → wait 5s
|
||||
# Attempt 4: return failure
|
||||
```
|
||||
|
||||
## Environment Safety
|
||||
|
||||
### Security Model
|
||||
|
||||
```python
|
||||
def get_safe_subprocess_env() -> Dict[str, str]:
|
||||
"""Only pass essential environment variables."""
|
||||
safe_vars = {
|
||||
# Authentication
|
||||
"ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
|
||||
|
||||
# System essentials
|
||||
"HOME": os.getenv("HOME"),
|
||||
"USER": os.getenv("USER"),
|
||||
"PATH": os.getenv("PATH"),
|
||||
"SHELL": os.getenv("SHELL"),
|
||||
|
||||
# Python-specific
|
||||
"PYTHONPATH": os.getenv("PYTHONPATH"),
|
||||
"PYTHONUNBUFFERED": "1",
|
||||
|
||||
# Working directory
|
||||
"PWD": os.getcwd(),
|
||||
}
|
||||
|
||||
# Filter out None values
|
||||
return {k: v for k, v in safe_vars.items() if v is not None}
|
||||
```
|
||||
|
||||
**Why this matters**:
|
||||
- Prevents leaking sensitive variables
|
||||
- Subprocess isolation
|
||||
- Explicit allowlist vs implicit inheritance
|
||||
- Security boundary between layers
|
||||
|
||||
## Subprocess vs SDK: Decision Matrix
|
||||
|
||||
| Criteria | Subprocess (agent.py) | SDK (agent_sdk.py) |
|
||||
|----------|----------------------|-------------------|
|
||||
| **Type Safety** | Basic (dicts) | Strong (typed objects) |
|
||||
| **Error Handling** | Generic exceptions | SDK-specific exceptions |
|
||||
| **Async Support** | Subprocess management | Native async/await |
|
||||
| **Dependencies** | Minimal (subprocess, json) | claude-code-sdk package |
|
||||
| **Debugging** | Read JSONL files | SDK message inspection |
|
||||
| **Interactive Sessions** | ❌ Not supported | ✅ ClaudeSDKClient |
|
||||
| **Shell Compatibility** | ✅ Works everywhere | Python only |
|
||||
| **Use Case** | Simple prompts, automation | Complex workflows, sessions |
|
||||
| **Learning Curve** | Low (familiar subprocess) | Medium (SDK concepts) |
|
||||
| **Performance** | Process spawn overhead | Native Python speed |
|
||||
|
||||
## Scalability Patterns
|
||||
|
||||
### Horizontal Scaling
|
||||
|
||||
Run multiple ADWs in parallel:
|
||||
|
||||
```bash
|
||||
# Terminal 1
|
||||
./adws/adw_chore_implement.py "feature A" &
|
||||
|
||||
# Terminal 2
|
||||
./adws/adw_chore_implement.py "feature B" &
|
||||
|
||||
# Terminal 3
|
||||
./adws/adw_chore_implement.py "feature C" &
|
||||
|
||||
# Each gets unique adw_id
|
||||
# Outputs don't conflict
|
||||
# Scale compute → scale features
|
||||
```
|
||||
|
||||
### Vertical Scaling
|
||||
|
||||
Break complex tasks into phases:
|
||||
|
||||
```
|
||||
Large Feature
|
||||
↓
|
||||
Phase 1: Architecture Design
|
||||
↓
|
||||
Phase 2: Core Implementation
|
||||
↓
|
||||
Phase 3: Testing
|
||||
↓
|
||||
Phase 4: Documentation
|
||||
↓
|
||||
Phase 5: Deployment
|
||||
```
|
||||
|
||||
Each phase is separate ADW execution with clear handoffs.
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### 1. JSONL as Interchange Format
|
||||
- Streamable (process as it arrives)
|
||||
- Line-delimited (easy to parse)
|
||||
- Standard format (widely supported)
|
||||
|
||||
### 2. Unique ID per Execution
|
||||
- Enables parallel execution
|
||||
- Clear output isolation
|
||||
- Audit trail maintenance
|
||||
- Debugging support
|
||||
|
||||
### 3. Multiple Output Formats
|
||||
- JSONL for streaming
|
||||
- JSON for processing
|
||||
- Final object for quick access
|
||||
- Summary for humans
|
||||
|
||||
### 4. Subprocess First, SDK Optional
|
||||
- Lower barrier to entry
|
||||
- Subprocess is universal
|
||||
- SDK adds sophistication later
|
||||
- Progressive enhancement
|
||||
|
||||
### 5. Environment Filtering
|
||||
- Security boundary
|
||||
- Explicit allowlist
|
||||
- Prevents accidents
|
||||
- Isolation guarantee
|
||||
|
||||
## Extension Points
|
||||
|
||||
Where to extend the architecture:
|
||||
|
||||
1. **New ADW Scripts** (`adws/adw_*.py`)
|
||||
- Add new orchestration patterns
|
||||
- Implement domain-specific workflows
|
||||
|
||||
2. **New Slash Commands** (`.claude/commands/*.md`)
|
||||
- Template new engineering patterns
|
||||
- Capture team conventions
|
||||
|
||||
3. **New Agent Modules** (`adws/adw_modules/*.py`)
|
||||
- Add state management
|
||||
- Implement workflow helpers
|
||||
- Add integrations
|
||||
|
||||
4. **Hooks** (`.claude/hooks/*.py`)
|
||||
- Pre/post tool use events
|
||||
- Notification systems
|
||||
- Validation gates
|
||||
|
||||
5. **Triggers** (`adws/adw_triggers/*.py`)
|
||||
- Webhook endpoints
|
||||
- Cron jobs
|
||||
- Event handlers
|
||||
|
||||
6. **Custom Subagents** (`.claude/agents/*.md`)
|
||||
- Specialized agent configurations
|
||||
- Domain experts
|
||||
- Tool restrictions
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Bottlenecks
|
||||
|
||||
1. **Claude Code Execution Time**
|
||||
- Dominant factor
|
||||
- Minutes per complex task
|
||||
- Mitigate: Run in parallel
|
||||
|
||||
2. **Subprocess Spawn Overhead**
|
||||
- Minimal (~100ms)
|
||||
- Negligible compared to execution
|
||||
- SDK slightly faster but not significant
|
||||
|
||||
3. **JSONL Parsing**
|
||||
- Fast (JSON is efficient)
|
||||
- Linear in message count
|
||||
- Not a bottleneck in practice
|
||||
|
||||
### Optimization Strategies
|
||||
|
||||
1. **Parallel Execution**
|
||||
- Run independent tasks concurrently
|
||||
- Each gets own adw_id
|
||||
- No shared state conflicts
|
||||
|
||||
2. **Appropriate Model Selection**
|
||||
- Use Sonnet for most tasks (faster, cheaper)
|
||||
- Use Opus only for complex reasoning
|
||||
- 2-3x speed difference
|
||||
|
||||
3. **Caching**
|
||||
- Claude Code has built-in caching
|
||||
- Repeated prompts are faster
|
||||
- Design for cache reuse
|
||||
|
||||
4. **Progressive Enhancement**
|
||||
- Start minimal (faster setup)
|
||||
- Add features as needed
|
||||
- Don't over-engineer initially
|
||||
81
skills/adw-bootstrap/docs/examples.md
Normal file
81
skills/adw-bootstrap/docs/examples.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# ADW Bootstrap Examples
|
||||
|
||||
This document shows real-world examples of bootstrapping ADW infrastructure in different project types.
|
||||
|
||||
## Example 1: Python FastAPI Project
|
||||
|
||||
### Before Bootstrap
|
||||
```
|
||||
my-api/
|
||||
├── src/
|
||||
│ ├── main.py
|
||||
│ └── routes/
|
||||
├── tests/
|
||||
├── pyproject.toml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### After Bootstrap (Enhanced)
|
||||
```
|
||||
my-api/
|
||||
├── adws/
|
||||
│ ├── adw_modules/
|
||||
│ │ ├── agent.py
|
||||
│ │ └── agent_sdk.py
|
||||
│ ├── adw_prompt.py
|
||||
│ ├── adw_slash_command.py
|
||||
│ └── adw_chore_implement.py
|
||||
├── .claude/commands/
|
||||
│ ├── chore.md # Adapted to FastAPI
|
||||
│ ├── implement.md
|
||||
│ ├── feature.md
|
||||
│ └── prime.md
|
||||
├── specs/
|
||||
├── agents/
|
||||
├── .env.sample
|
||||
└── CLAUDE.md # Updated
|
||||
```
|
||||
|
||||
### Usage
|
||||
```bash
|
||||
# Fast exploration with Haiku
|
||||
./adws/adw_prompt.py "what authentication methods are used?" --model haiku
|
||||
|
||||
# Implementation with Sonnet (default)
|
||||
./adws/adw_chore_implement.py "add JWT authentication"
|
||||
|
||||
# Security review with Opus
|
||||
./adws/adw_prompt.py "review security in auth module" --model opus
|
||||
```
|
||||
|
||||
## Example 2: Next.js TypeScript Project
|
||||
|
||||
### Key Adaptations
|
||||
- ADW scripts remain Python (work on any project)
|
||||
- Validation commands use `npm run type-check`, `npm run build`
|
||||
- start.md uses `npm run dev`
|
||||
|
||||
### Usage
|
||||
```bash
|
||||
./adws/adw_chore_implement.py "add dark mode toggle"
|
||||
./adws/adw_prompt.py "analyze component architecture"
|
||||
```
|
||||
|
||||
## Example 3: Minimal Setup
|
||||
|
||||
Small projects get minimal setup only:
|
||||
- Just agent.py and adw_prompt.py
|
||||
- Basic slash commands
|
||||
- Can upgrade later if needed
|
||||
|
||||
## Testing Your Setup
|
||||
|
||||
Run validation:
|
||||
```bash
|
||||
~/.claude/skills/adw-bootstrap/utils/validator.py
|
||||
```
|
||||
|
||||
Try a simple prompt:
|
||||
```bash
|
||||
./adws/adw_prompt.py "what does this project do?"
|
||||
```
|
||||
300
skills/adw-bootstrap/docs/principles.md
Normal file
300
skills/adw-bootstrap/docs/principles.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# AI Developer Workflows (ADWs): Core Principles
|
||||
|
||||
## What Are ADWs?
|
||||
|
||||
**AI Developer Workflows (ADWs)** are executable scripts that combine deterministic code with non-deterministic, compute-scalable AI agents to perform complex development tasks programmatically.
|
||||
|
||||
Instead of directly modifying code yourself, you **template your engineering patterns** and **teach agents how to operate your codebase**. This allows you to scale impact by scaling compute, not just effort.
|
||||
|
||||
## The Two-Layer Architecture
|
||||
|
||||
### Agentic Layer
|
||||
**Purpose**: Template engineering patterns and teach agents how to operate
|
||||
|
||||
**Components**:
|
||||
- `adws/` - AI Developer Workflow scripts and modules
|
||||
- `.claude/` - Slash commands, skills, hooks, agent configurations
|
||||
- `specs/` - Implementation plans and specifications
|
||||
- `agents/` - Agent execution outputs (observability)
|
||||
|
||||
**Role**: Provides the programmatic interface for AI-driven development
|
||||
|
||||
### Application Layer
|
||||
**Purpose**: The actual application code that agents operate on
|
||||
|
||||
**Components**:
|
||||
- `apps/`, `src/`, `lib/`, etc. - Your application code
|
||||
- `tests/` - Your test suites
|
||||
- Application-specific configuration and resources
|
||||
|
||||
**Role**: What the agents modify, test, and deploy
|
||||
|
||||
## The 12 Leverage Points of Agentic Coding
|
||||
|
||||
### In Agent (Core Four)
|
||||
These directly control agent behavior during execution:
|
||||
|
||||
1. **Context** - What information the agent has access to
|
||||
2. **Model** - Which AI model processes the prompt (Sonnet vs Opus)
|
||||
3. **Prompt** - The specific instructions given to the agent
|
||||
4. **Tools** - What actions the agent can take (Read, Write, Bash, etc.)
|
||||
|
||||
### Through Agent (Structural Eight)
|
||||
These shape how you structure work for agents:
|
||||
|
||||
5. **Standard Output** - Structured agent outputs for observability
|
||||
6. **Types** - Data models and schemas that define interfaces
|
||||
7. **Docs** - Documentation that provides context to agents
|
||||
8. **Tests** - Validation that ensures agent work is correct
|
||||
9. **Architecture** - System design that guides agent decisions
|
||||
10. **Plans** - Specifications that break work into steps
|
||||
11. **Templates** - Reusable prompt patterns (slash commands)
|
||||
12. **AI Developer Workflows** - Orchestrated multi-agent processes
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1: Subprocess-Based Execution
|
||||
|
||||
**When to use**: Simple prompts, shell compatibility, lower dependencies
|
||||
|
||||
```python
|
||||
from agent import prompt_claude_code, AgentPromptRequest
|
||||
|
||||
request = AgentPromptRequest(
|
||||
prompt="Analyze this module",
|
||||
adw_id="abc12345",
|
||||
agent_name="analyzer",
|
||||
model="sonnet",
|
||||
output_file="agents/abc12345/analyzer/cc_raw_output.jsonl"
|
||||
)
|
||||
|
||||
response = prompt_claude_code(request)
|
||||
if response.success:
|
||||
print(response.output)
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- Invokes Claude Code CLI as subprocess
|
||||
- Streams output to JSONL files
|
||||
- Parses results into structured JSON
|
||||
- Implements retry logic for transient failures
|
||||
- Works with both subscription and API modes
|
||||
|
||||
### Pattern 2: SDK-Based Execution
|
||||
|
||||
**When to use**: Interactive sessions, better type safety, async workflows
|
||||
|
||||
```python
|
||||
from agent_sdk import simple_query
|
||||
|
||||
response = await simple_query("Implement feature X")
|
||||
print(response)
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- Native Python async/await
|
||||
- Typed message objects
|
||||
- SDK-specific error handling
|
||||
- Interactive session support
|
||||
- Better IDE integration
|
||||
|
||||
### Pattern 3: Template-Based Development
|
||||
|
||||
**Slash commands** are reusable prompt templates:
|
||||
|
||||
```markdown
|
||||
# .claude/commands/chore.md
|
||||
Create a plan using this format:
|
||||
|
||||
## Variables
|
||||
adw_id: $1
|
||||
description: $2
|
||||
|
||||
## Instructions
|
||||
1. Analyze the codebase starting with README.md
|
||||
2. Create a step-by-step plan
|
||||
3. Save to specs/chore-{adw_id}-{name}.md
|
||||
```
|
||||
|
||||
Execute: `./adws/adw_slash_command.py /chore abc123 "add logging"`
|
||||
|
||||
### Pattern 4: Workflow Orchestration
|
||||
|
||||
**Compound workflows** chain multiple agent invocations:
|
||||
|
||||
```python
|
||||
# Phase 1: Planning
|
||||
chore_response = execute_template(
|
||||
slash_command="/chore",
|
||||
args=[adw_id, description]
|
||||
)
|
||||
|
||||
# Extract plan path from response
|
||||
plan_path = extract_plan_path(chore_response.output)
|
||||
|
||||
# Phase 2: Implementation
|
||||
implement_response = execute_template(
|
||||
slash_command="/implement",
|
||||
args=[plan_path]
|
||||
)
|
||||
```
|
||||
|
||||
## Observability First
|
||||
|
||||
Every ADW execution creates structured outputs:
|
||||
|
||||
```
|
||||
agents/{adw_id}/{agent_name}/
|
||||
cc_raw_output.jsonl # Raw streaming JSONL
|
||||
cc_raw_output.json # Parsed JSON array
|
||||
cc_final_object.json # Final result object
|
||||
custom_summary_output.json # High-level summary
|
||||
```
|
||||
|
||||
**Why this matters**:
|
||||
- Debug agent behavior by reading raw outputs
|
||||
- Programmatically process results from JSON
|
||||
- Track lineage with unique IDs
|
||||
- Audit what agents did and why
|
||||
|
||||
## Progressive Enhancement
|
||||
|
||||
Start simple, add complexity as needed:
|
||||
|
||||
### Minimal (Always)
|
||||
- Core subprocess execution (`agent.py`)
|
||||
- Basic prompt wrapper (`adw_prompt.py`)
|
||||
- Essential slash commands (chore, implement)
|
||||
- Spec directory for plans
|
||||
|
||||
**Good for**: Proof of concepts, simple automation, getting started
|
||||
|
||||
### Enhanced (Recommended)
|
||||
- SDK support (`agent_sdk.py`)
|
||||
- Compound workflows (`adw_chore_implement.py`)
|
||||
- Rich slash commands (feature, test, prime)
|
||||
- Slash command executor
|
||||
|
||||
**Good for**: Active development, team collaboration, feature automation
|
||||
|
||||
### Scaled (Production)
|
||||
- State management across phases
|
||||
- Git worktree isolation
|
||||
- Trigger systems (webhooks, cron)
|
||||
- Testing infrastructure
|
||||
- Comprehensive observability
|
||||
|
||||
**Good for**: Production systems, enterprise teams, complex SDLC
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Environment Safety
|
||||
```python
|
||||
# Filter environment variables
|
||||
def get_safe_subprocess_env():
|
||||
return {
|
||||
"ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
|
||||
"HOME": os.getenv("HOME"),
|
||||
"PATH": os.getenv("PATH"),
|
||||
# Only essential variables
|
||||
}
|
||||
```
|
||||
|
||||
**Why**: Prevents environment variable leakage, security isolation
|
||||
|
||||
### 2. Retry Logic
|
||||
```python
|
||||
def prompt_claude_code_with_retry(request, max_retries=3):
|
||||
for attempt in range(max_retries + 1):
|
||||
response = prompt_claude_code(request)
|
||||
if response.success or response.retry_code == RetryCode.NONE:
|
||||
return response
|
||||
time.sleep(retry_delays[attempt])
|
||||
```
|
||||
|
||||
**Why**: Handle transient failures (network issues, rate limits, timeouts)
|
||||
|
||||
### 3. Error Truncation
|
||||
```python
|
||||
def truncate_output(output, max_length=500):
|
||||
if len(output) <= max_length:
|
||||
return output
|
||||
return output[:max_length-15] + "... (truncated)"
|
||||
```
|
||||
|
||||
**Why**: Prevent console flooding from huge error messages
|
||||
|
||||
### 4. Unique ID Tracking
|
||||
```python
|
||||
def generate_short_id():
|
||||
return str(uuid.uuid4())[:8]
|
||||
|
||||
adw_id = generate_short_id() # abc12345
|
||||
# All outputs go to: agents/abc12345/
|
||||
```
|
||||
|
||||
**Why**: Track execution lineage, associate outputs, debug flows
|
||||
|
||||
### 5. Type Safety
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
|
||||
class AgentPromptRequest(BaseModel):
|
||||
prompt: str
|
||||
adw_id: str
|
||||
model: Literal["sonnet", "opus"]
|
||||
output_file: str
|
||||
```
|
||||
|
||||
**Why**: Catch errors early, better IDE support, self-documenting
|
||||
|
||||
## Usage Modes
|
||||
|
||||
### Mode A: Claude Max Subscription
|
||||
- User has Claude Max subscription
|
||||
- No API key needed
|
||||
- Claude Code authenticates through subscription
|
||||
- Perfect for interactive development
|
||||
|
||||
### Mode B: API-Based Automation
|
||||
- Requires `ANTHROPIC_API_KEY`
|
||||
- Enables headless automation
|
||||
- Required for CI/CD, webhooks, cron jobs
|
||||
- Programmatic agent execution
|
||||
|
||||
**Both modes work with the same ADW infrastructure.** The code detects which mode to use automatically.
|
||||
|
||||
## Philosophy: Scale Compute, Not Just Effort
|
||||
|
||||
Traditional development: **You write the code**
|
||||
- Linear scaling: More features = more time
|
||||
- Bottleneck: Your available hours
|
||||
- Hard to parallelize
|
||||
|
||||
Agentic development: **You template patterns, agents write the code**
|
||||
- Compute scaling: More features = more parallel agents
|
||||
- Bottleneck: Compute availability
|
||||
- Easy to parallelize
|
||||
|
||||
**This is the fundamental shift.** ADWs enable this paradigm.
|
||||
|
||||
## Key Insights
|
||||
|
||||
1. **Separation of Concerns**: Agentic layer (how to operate) vs Application layer (what to operate on)
|
||||
|
||||
2. **Progressive Enhancement**: Start minimal, add features as needed, scale when required
|
||||
|
||||
3. **Observability**: Structured outputs make agent behavior transparent and debuggable
|
||||
|
||||
4. **Intelligence Over Templating**: Provide patterns, let Claude adapt intelligently
|
||||
|
||||
5. **Mode Flexibility**: Support both interactive (subscription) and automated (API) workflows
|
||||
|
||||
6. **Compute as Leverage**: Scale impact by scaling compute, not just working harder
|
||||
|
||||
## Further Reading
|
||||
|
||||
- `architecture.md` - Detailed architecture patterns
|
||||
- `usage-modes.md` - Deep dive on subscription vs API modes
|
||||
- Reference implementations in `reference/` directory
|
||||
- Main skill logic in `SKILL.md`
|
||||
326
skills/adw-bootstrap/docs/upgrades.md
Normal file
326
skills/adw-bootstrap/docs/upgrades.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# ADW Infrastructure Upgrades
|
||||
|
||||
This document explains how to upgrade existing ADW infrastructure from one phase to another.
|
||||
|
||||
## Overview
|
||||
|
||||
ADW Bootstrap supports **progressive enhancement** with three phases:
|
||||
- **Minimal** → **Enhanced** → **Scaled**
|
||||
|
||||
You can upgrade at any time without losing customizations.
|
||||
|
||||
## When to Upgrade
|
||||
|
||||
### Minimal → Enhanced
|
||||
Upgrade when you:
|
||||
- Want SDK-based execution for better type safety
|
||||
- Need compound workflows (plan + implement in one command)
|
||||
- Want interactive session support
|
||||
- Are building a production application
|
||||
|
||||
**What it adds:**
|
||||
- SDK execution module (`agent_sdk.py`)
|
||||
- SDK CLI wrapper (`adw_sdk_prompt.py`)
|
||||
- Slash command executor (`adw_slash_command.py`)
|
||||
- Compound workflow script (`adw_chore_implement.py`)
|
||||
- Richer slash commands (feature.md, prime.md)
|
||||
|
||||
### Enhanced → Scaled
|
||||
Upgrade when you:
|
||||
- Need state management across workflow phases
|
||||
- Want git worktree isolation for parallel development
|
||||
- Require GitHub integration (issues, PRs, comments)
|
||||
- Need complete SDLC automation
|
||||
- Building enterprise/team workflows
|
||||
|
||||
**What it adds:**
|
||||
- State management module (`state.py`)
|
||||
- Git operations module (`git_ops.py`)
|
||||
- Worktree isolation module (`worktree_ops.py`)
|
||||
- Workflow composition module (`workflow_ops.py`)
|
||||
- GitHub integration module (`github.py`)
|
||||
- Multi-phase workflows (`adw_sdlc_iso.py`, `adw_ship_iso.py`, etc.)
|
||||
- 15+ advanced slash commands
|
||||
- Worktree directory structure (`trees/`)
|
||||
|
||||
## Upgrade Process
|
||||
|
||||
### 1. Detection
|
||||
|
||||
The skill automatically detects existing ADW setup by checking for:
|
||||
- `adws/adw_modules/agent.py` (primary indicator)
|
||||
- Other key files to determine current phase
|
||||
|
||||
### 2. Classification
|
||||
|
||||
Based on file presence, classifies as:
|
||||
- **Minimal**: Has agent.py, basic commands, no SDK
|
||||
- **Enhanced**: Has SDK support, compound workflows, no state management
|
||||
- **Scaled**: Has state management, worktree ops, GitHub integration
|
||||
|
||||
### 3. User Confirmation
|
||||
|
||||
Shows current phase and available upgrades:
|
||||
```
|
||||
🔍 Existing ADW setup detected!
|
||||
|
||||
Current Phase: Enhanced
|
||||
|
||||
Available upgrades:
|
||||
- Scaled: Adds state management, worktree isolation, GitHub integration
|
||||
|
||||
Would you like to upgrade to Scaled?
|
||||
```
|
||||
|
||||
### 4. Safety Backup
|
||||
|
||||
Before making changes:
|
||||
```bash
|
||||
mkdir -p .adw_backups
|
||||
cp -r adws .adw_backups/adws_$(date +%Y%m%d_%H%M%S)
|
||||
cp -r .claude .adw_backups/.claude_$(date +%Y%m%d_%H%M%S)
|
||||
```
|
||||
|
||||
### 5. Customization Detection
|
||||
|
||||
Before adding each file:
|
||||
- Check if file already exists
|
||||
- Compare content with reference version
|
||||
- If customized: Preserve and warn user
|
||||
- If not customized: Safe to update
|
||||
- When in doubt: Create `<file>.new` instead of overwriting
|
||||
|
||||
**Files never overwritten:**
|
||||
- Any file with recent modification timestamp
|
||||
- Any file with content differing from reference
|
||||
- Any file in a `custom_` directory
|
||||
|
||||
### 6. Add New Capabilities
|
||||
|
||||
Only adds files that don't exist or aren't customized:
|
||||
- New modules in `adws/adw_modules/`
|
||||
- New workflow scripts in `adws/`
|
||||
- New slash commands in `.claude/commands/`
|
||||
- Directory structure (trees/, .adw_backups/)
|
||||
|
||||
### 7. Dependency Updates
|
||||
|
||||
**For Enhanced:**
|
||||
- Ensure `claude-code-sdk` is in script dependencies
|
||||
- Update inline deps in uv scripts (PEP 723)
|
||||
|
||||
**For Scaled:**
|
||||
- Verify `gh` CLI is available
|
||||
- Add extended data types if needed
|
||||
- Create utility functions
|
||||
|
||||
### 8. Documentation Updates
|
||||
|
||||
Updates CLAUDE.md (if unmodified):
|
||||
- Document new capabilities
|
||||
- Add usage examples
|
||||
- Update command reference
|
||||
|
||||
### 9. Validation
|
||||
|
||||
Runs checks:
|
||||
```bash
|
||||
# Check executability
|
||||
chmod +x adws/*.py
|
||||
|
||||
# Test a simple prompt
|
||||
./adws/adw_prompt.py "test upgrade" --model haiku
|
||||
```
|
||||
|
||||
If validation fails, offers automatic rollback.
|
||||
|
||||
### 10. Report Results
|
||||
|
||||
```
|
||||
🎉 Upgrade to Scaled completed successfully!
|
||||
|
||||
Added:
|
||||
- 5 new modules
|
||||
- 3 new workflows
|
||||
- 15 new slash commands
|
||||
|
||||
Your customizations were preserved:
|
||||
- adws/adw_prompt.py (customized)
|
||||
|
||||
Backup location: .adw_backups/20251103_102530
|
||||
|
||||
Try the new capabilities:
|
||||
- ./adws/adw_sdlc_iso.py 123
|
||||
- ./adws/adw_ship_iso.py 123 abc12345
|
||||
|
||||
To rollback: cp -r .adw_backups/20251103_102530/* ./
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
If upgrade fails or you want to revert:
|
||||
|
||||
```bash
|
||||
# List available backups
|
||||
ls -la .adw_backups/
|
||||
|
||||
# Rollback to specific backup
|
||||
cp -r .adw_backups/adws_20251103_102530 adws/
|
||||
cp -r .adw_backups/.claude_20251103_102530 .claude/
|
||||
|
||||
# Or restore from most recent
|
||||
LATEST=$(ls -t .adw_backups/ | head -1)
|
||||
cp -r .adw_backups/$LATEST/* ./
|
||||
```
|
||||
|
||||
## Skip Phases
|
||||
|
||||
You can jump phases:
|
||||
|
||||
**Minimal → Scaled (skip Enhanced):**
|
||||
The skill adds both Enhanced and Scaled capabilities in one upgrade.
|
||||
|
||||
This is safe because:
|
||||
- All files are additive
|
||||
- No breaking changes between phases
|
||||
- Dependencies are properly managed
|
||||
|
||||
## Customization Preservation
|
||||
|
||||
The skill intelligently preserves customizations:
|
||||
|
||||
**Safe to update:**
|
||||
- Files identical to reference versions
|
||||
- Files with only minor formatting differences
|
||||
- New files being added
|
||||
|
||||
**Preserved:**
|
||||
- Files with significant code changes
|
||||
- Files with custom functionality
|
||||
- Files modified recently (within 7 days)
|
||||
- Files in custom_* directories
|
||||
|
||||
**Resolution options:**
|
||||
1. Keep custom version, skip update
|
||||
2. Create `<file>.new` with new version, let user merge
|
||||
3. Ask user to choose (for important files)
|
||||
|
||||
## Testing Upgrades
|
||||
|
||||
Before upgrading production:
|
||||
|
||||
1. Test on a branch:
|
||||
```bash
|
||||
git checkout -b test-adw-upgrade
|
||||
# Run upgrade
|
||||
# Test new capabilities
|
||||
git checkout main
|
||||
```
|
||||
|
||||
2. Use backup feature:
|
||||
```bash
|
||||
# Upgrade creates automatic backup
|
||||
# If issues: cp -r .adw_backups/latest/* ./
|
||||
```
|
||||
|
||||
3. Validate thoroughly:
|
||||
```bash
|
||||
./adws/adw_prompt.py "test" --model haiku
|
||||
# Try new workflows
|
||||
# Check customizations still work
|
||||
```
|
||||
|
||||
## Upgrade Triggers
|
||||
|
||||
The skill activates upgrade mode when you say:
|
||||
- "Upgrade my ADWs"
|
||||
- "Upgrade ADW infrastructure"
|
||||
- "Add enhanced ADW features"
|
||||
- "Upgrade to scaled ADWs"
|
||||
- "Add scaled capabilities"
|
||||
|
||||
## Advanced: Partial Upgrades
|
||||
|
||||
If you only want specific features:
|
||||
- "Add git worktree support to my ADWs"
|
||||
- "Add state management to my ADWs"
|
||||
- "Add GitHub integration"
|
||||
|
||||
The skill can add individual modules without full phase upgrade.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Upgrade fails mid-process
|
||||
- Automatic rollback to backup
|
||||
- Check error message for specific issue
|
||||
- Common causes: file permissions, missing dependencies
|
||||
|
||||
### New features don't work
|
||||
- Check dependencies installed: `uv pip list`
|
||||
- Verify gh CLI available: `gh --version`
|
||||
- Check file permissions: `chmod +x adws/*.py`
|
||||
|
||||
### Customizations lost
|
||||
- Check `.adw_backups/` directory
|
||||
- Rollback and report issue
|
||||
- Manual merge may be needed
|
||||
|
||||
### Validation fails
|
||||
- Check error output
|
||||
- Verify Claude Code CLI: `claude --version`
|
||||
- Test manually: `./adws/adw_prompt.py "test"`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Commit before upgrading**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Pre-ADW upgrade checkpoint"
|
||||
```
|
||||
|
||||
2. **Review what changed**
|
||||
```bash
|
||||
git diff # After upgrade
|
||||
```
|
||||
|
||||
3. **Test new features**
|
||||
- Try each new capability
|
||||
- Verify existing workflows still work
|
||||
- Update documentation
|
||||
|
||||
4. **Clean up backups periodically**
|
||||
```bash
|
||||
# Keep last 3 backups
|
||||
cd .adw_backups && ls -t | tail -n +4 | xargs rm -rf
|
||||
```
|
||||
|
||||
5. **Document customizations**
|
||||
- Add comments explaining changes
|
||||
- Create custom_* files for major modifications
|
||||
- Keep notes in CLAUDE.md
|
||||
|
||||
## Phase Comparison
|
||||
|
||||
| Feature | Minimal | Enhanced | Scaled |
|
||||
|---------|---------|----------|--------|
|
||||
| Subprocess execution | ✅ | ✅ | ✅ |
|
||||
| Basic CLI | ✅ | ✅ | ✅ |
|
||||
| Basic slash commands | ✅ | ✅ | ✅ |
|
||||
| SDK execution | ❌ | ✅ | ✅ |
|
||||
| Interactive sessions | ❌ | ✅ | ✅ |
|
||||
| Compound workflows | ❌ | ✅ | ✅ |
|
||||
| State management | ❌ | ❌ | ✅ |
|
||||
| Git worktree isolation | ❌ | ❌ | ✅ |
|
||||
| GitHub integration | ❌ | ❌ | ✅ |
|
||||
| Multi-phase workflows | ❌ | ❌ | ✅ |
|
||||
| Port management | ❌ | ❌ | ✅ |
|
||||
| Advanced commands | 2 | 7 | 20+ |
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues during upgrade:
|
||||
1. Check `.adw_backups/` for rollback
|
||||
2. Review error messages carefully
|
||||
3. Verify all dependencies installed
|
||||
4. Test in clean environment
|
||||
5. Report issue with upgrade log
|
||||
504
skills/adw-bootstrap/docs/usage-modes.md
Normal file
504
skills/adw-bootstrap/docs/usage-modes.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# ADW Usage Modes: Subscription vs API
|
||||
|
||||
## Overview
|
||||
|
||||
ADW infrastructure supports two distinct usage modes, enabling both interactive development and automated workflows without code changes.
|
||||
|
||||
## Mode A: Claude Max Subscription
|
||||
|
||||
### What It Is
|
||||
|
||||
Run Claude Code through your Claude Max subscription without needing API keys.
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
User with Claude Max subscription
|
||||
↓
|
||||
Logged in to Claude Code CLI
|
||||
↓
|
||||
ADW executes: claude -p "prompt"
|
||||
↓
|
||||
Claude Code uses subscription auth
|
||||
↓
|
||||
Prompt executed, results returned
|
||||
```
|
||||
|
||||
No API key configuration needed - authentication happens automatically through your subscription.
|
||||
|
||||
### Setup
|
||||
|
||||
**Zero configuration required:**
|
||||
|
||||
```bash
|
||||
# Just run the ADWs
|
||||
./adws/adw_prompt.py "analyze this code"
|
||||
|
||||
# No .env file needed
|
||||
# No API key needed
|
||||
# Works immediately
|
||||
```
|
||||
|
||||
### Requirements
|
||||
|
||||
- Active Claude Max subscription
|
||||
- Claude Code CLI installed and logged in
|
||||
- User must be authenticated
|
||||
|
||||
### Advantages
|
||||
|
||||
✅ **Simple** - No configuration, just works
|
||||
✅ **Secure** - No API keys to manage
|
||||
✅ **Interactive** - Perfect for development
|
||||
✅ **Immediate** - No setup friction
|
||||
|
||||
### Limitations
|
||||
|
||||
❌ **User presence required** - Can't run headless
|
||||
❌ **Single user** - Tied to your subscription
|
||||
❌ **Limited automation** - Not ideal for CI/CD
|
||||
❌ **Session-dependent** - Must be logged in
|
||||
|
||||
### Perfect For
|
||||
|
||||
- Interactive development
|
||||
- Local experimentation
|
||||
- Learning ADWs
|
||||
- Personal projects
|
||||
- Quick prototyping
|
||||
|
||||
### Example Workflow
|
||||
|
||||
```bash
|
||||
# Morning: Start development
|
||||
./adws/adw_chore_implement.py "add user authentication"
|
||||
|
||||
# Afternoon: Create another feature
|
||||
./adws/adw_chore_implement.py "implement password reset"
|
||||
|
||||
# Evening: Code review
|
||||
./adws/adw_prompt.py "review security in auth module"
|
||||
|
||||
# All executed through your subscription
|
||||
# No API key management
|
||||
# Just works
|
||||
```
|
||||
|
||||
## Mode B: API-Based Programmatic Execution
|
||||
|
||||
### What It Is
|
||||
|
||||
Run Claude Code programmatically using API keys for automated, headless workflows.
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
Environment has ANTHROPIC_API_KEY
|
||||
↓
|
||||
ADW reads API key from environment
|
||||
↓
|
||||
ADW executes: claude -p "prompt"
|
||||
↓
|
||||
Claude Code uses API key for auth
|
||||
↓
|
||||
Prompt executed, results returned
|
||||
```
|
||||
|
||||
API key is passed through filtered environment to subprocess.
|
||||
|
||||
### Setup
|
||||
|
||||
**Step 1: Create .env file**
|
||||
|
||||
```bash
|
||||
# Copy template
|
||||
cp .env.sample .env
|
||||
|
||||
# Edit .env
|
||||
nano .env
|
||||
```
|
||||
|
||||
**Step 2: Add your API key**
|
||||
|
||||
```bash
|
||||
# .env file
|
||||
ANTHROPIC_API_KEY=sk-ant-api03-...
|
||||
|
||||
# Optional configurations
|
||||
CLAUDE_CODE_PATH=claude
|
||||
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=true
|
||||
```
|
||||
|
||||
**Step 3: Secure the file**
|
||||
|
||||
```bash
|
||||
# Never commit .env
|
||||
echo ".env" >> .gitignore
|
||||
|
||||
# Restrict permissions
|
||||
chmod 600 .env
|
||||
```
|
||||
|
||||
### Requirements
|
||||
|
||||
- Anthropic API key (from console.anthropic.com)
|
||||
- API access enabled on account
|
||||
- Claude Code CLI installed
|
||||
|
||||
### Advantages
|
||||
|
||||
✅ **Headless** - Runs without user interaction
|
||||
✅ **Automatable** - Perfect for CI/CD
|
||||
✅ **Multi-user** - Not tied to single subscription
|
||||
✅ **Scriptable** - Full programmatic control
|
||||
✅ **Reliable** - No session dependencies
|
||||
|
||||
### Limitations
|
||||
|
||||
❌ **Requires API key** - Additional setup
|
||||
❌ **Costs** - API usage charges
|
||||
❌ **Key management** - Security consideration
|
||||
❌ **Environment config** - Must configure .env
|
||||
|
||||
### Perfect For
|
||||
|
||||
- CI/CD pipelines
|
||||
- Webhook handlers
|
||||
- Scheduled tasks (cron jobs)
|
||||
- Server-side automation
|
||||
- Team automation workflows
|
||||
- Production deployments
|
||||
|
||||
### Example Workflows
|
||||
|
||||
#### CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# .github/workflows/ai-review.yml
|
||||
name: AI Code Review
|
||||
|
||||
on: [pull_request]
|
||||
|
||||
jobs:
|
||||
review:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
- name: Set up environment
|
||||
run: |
|
||||
echo "ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}" > .env
|
||||
|
||||
- name: Run AI review
|
||||
run: |
|
||||
./adws/adw_prompt.py "review this PR for security issues"
|
||||
```
|
||||
|
||||
#### Webhook Handler
|
||||
|
||||
```python
|
||||
# webhook_server.py
|
||||
from flask import Flask, request
|
||||
import subprocess
|
||||
|
||||
app = Flask(__name__)
|
||||
|
||||
@app.route('/webhook/feature-request', methods=['POST'])
|
||||
def handle_feature_request():
|
||||
data = request.json
|
||||
description = data['description']
|
||||
|
||||
# Execute ADW with API key from environment
|
||||
subprocess.run([
|
||||
'./adws/adw_chore_implement.py',
|
||||
description
|
||||
])
|
||||
|
||||
return {'status': 'processing'}
|
||||
```
|
||||
|
||||
#### Cron Job
|
||||
|
||||
```bash
|
||||
# crontab -e
|
||||
|
||||
# Run daily code quality check at 2 AM
|
||||
0 2 * * * cd /path/to/project && ./adws/adw_prompt.py "analyze code quality and suggest improvements" >> /var/log/adw-daily.log 2>&1
|
||||
```
|
||||
|
||||
## Mode Detection
|
||||
|
||||
The ADW infrastructure automatically detects which mode to use:
|
||||
|
||||
```python
|
||||
# In agent.py
|
||||
def get_safe_subprocess_env():
|
||||
env = {
|
||||
# System variables
|
||||
"HOME": os.getenv("HOME"),
|
||||
"PATH": os.getenv("PATH"),
|
||||
# ...
|
||||
}
|
||||
|
||||
# Only add API key if it exists
|
||||
api_key = os.getenv("ANTHROPIC_API_KEY")
|
||||
if api_key:
|
||||
env["ANTHROPIC_API_KEY"] = api_key
|
||||
|
||||
# If no API key, Claude Code uses subscription
|
||||
return env
|
||||
```
|
||||
|
||||
**Detection logic:**
|
||||
1. Check if `ANTHROPIC_API_KEY` exists in environment
|
||||
2. If yes → API mode (pass key to subprocess)
|
||||
3. If no → Subscription mode (Claude Code uses logged-in session)
|
||||
|
||||
**No code changes needed** - same scripts work in both modes.
|
||||
|
||||
## Comparison Matrix
|
||||
|
||||
| Feature | Subscription Mode | API Mode |
|
||||
|---------|------------------|----------|
|
||||
| **Setup Complexity** | None | Moderate (API key) |
|
||||
| **User Presence** | Required | Not required |
|
||||
| **CI/CD Integration** | ❌ Difficult | ✅ Easy |
|
||||
| **Cost** | Subscription price | API usage charges |
|
||||
| **Security** | No key to manage | Must secure API key |
|
||||
| **Automation** | Limited | Full |
|
||||
| **Interactive Use** | ✅ Excellent | ✅ Works fine |
|
||||
| **Headless Use** | ❌ Not practical | ✅ Perfect |
|
||||
| **Multi-user** | Per subscription | Shared key possible |
|
||||
| **Session Management** | Must stay logged in | None needed |
|
||||
|
||||
## Switching Between Modes
|
||||
|
||||
### Subscription → API
|
||||
|
||||
```bash
|
||||
# Create .env file
|
||||
cat > .env << 'EOF'
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
EOF
|
||||
|
||||
# Secure it
|
||||
chmod 600 .env
|
||||
|
||||
# Now all ADW executions use API
|
||||
./adws/adw_prompt.py "test"
|
||||
```
|
||||
|
||||
### API → Subscription
|
||||
|
||||
```bash
|
||||
# Remove .env file
|
||||
rm .env
|
||||
|
||||
# Or comment out API key
|
||||
# ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# Now all ADW executions use subscription
|
||||
./adws/adw_prompt.py "test"
|
||||
```
|
||||
|
||||
**Same scripts work in both modes** - just change environment.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Subscription Mode
|
||||
|
||||
1. **Stay logged in**
|
||||
```bash
|
||||
# Check auth status
|
||||
claude --version
|
||||
```
|
||||
|
||||
2. **Personal projects**
|
||||
- Use for local development
|
||||
- No .env file needed
|
||||
|
||||
3. **Quick iteration**
|
||||
- Fast setup
|
||||
- Immediate feedback
|
||||
|
||||
### For API Mode
|
||||
|
||||
1. **Secure your keys**
|
||||
```bash
|
||||
# Never commit
|
||||
echo ".env" >> .gitignore
|
||||
|
||||
# Restrict permissions
|
||||
chmod 600 .env
|
||||
|
||||
# Use secrets management in production
|
||||
```
|
||||
|
||||
2. **Rotate regularly**
|
||||
```bash
|
||||
# Update API key periodically
|
||||
# Revoke old keys
|
||||
```
|
||||
|
||||
3. **Monitor usage**
|
||||
- Track API consumption
|
||||
- Set up billing alerts
|
||||
- Monitor costs
|
||||
|
||||
4. **Use environment-specific keys**
|
||||
```bash
|
||||
# Development
|
||||
ANTHROPIC_API_KEY=sk-ant-dev-...
|
||||
|
||||
# Production
|
||||
ANTHROPIC_API_KEY=sk-ant-prod-...
|
||||
```
|
||||
|
||||
### For Both Modes
|
||||
|
||||
1. **Document which mode you're using**
|
||||
```markdown
|
||||
# README.md
|
||||
|
||||
## Setup
|
||||
|
||||
This project uses Claude Max subscription mode by default.
|
||||
For CI/CD, configure ANTHROPIC_API_KEY in .env.
|
||||
```
|
||||
|
||||
2. **Test in both modes**
|
||||
- Ensure portability
|
||||
- Validate automation path
|
||||
- Document differences
|
||||
|
||||
3. **Choose based on use case**
|
||||
- Interactive development → Subscription
|
||||
- Automation/CI/CD → API
|
||||
- Both are valid
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Subscription Mode Issues
|
||||
|
||||
**Problem**: "Authentication failed"
|
||||
```bash
|
||||
# Solution: Re-login to Claude Code
|
||||
claude login
|
||||
```
|
||||
|
||||
**Problem**: "Command not found: claude"
|
||||
```bash
|
||||
# Solution: Install Claude Code CLI
|
||||
# [Installation instructions]
|
||||
```
|
||||
|
||||
**Problem**: "Session expired"
|
||||
```bash
|
||||
# Solution: Re-authenticate
|
||||
claude logout
|
||||
claude login
|
||||
```
|
||||
|
||||
### API Mode Issues
|
||||
|
||||
**Problem**: "Invalid API key"
|
||||
```bash
|
||||
# Solution: Check .env file
|
||||
cat .env | grep ANTHROPIC_API_KEY
|
||||
|
||||
# Verify key format: sk-ant-api03-...
|
||||
# Get new key from console.anthropic.com
|
||||
```
|
||||
|
||||
**Problem**: "API key not found"
|
||||
```bash
|
||||
# Solution: Ensure .env is loaded
|
||||
# Check file location
|
||||
ls -la .env
|
||||
|
||||
# Verify environment
|
||||
echo $ANTHROPIC_API_KEY
|
||||
```
|
||||
|
||||
**Problem**: "Rate limit exceeded"
|
||||
```bash
|
||||
# Solution: Implement backoff or use subscription mode
|
||||
# Reduce parallel executions
|
||||
# Contact Anthropic for higher limits
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Subscription Mode
|
||||
|
||||
✅ **Secure by default** - No secrets to manage
|
||||
✅ **Session-based** - Expires automatically
|
||||
✅ **User-specific** - Can't be shared accidentally
|
||||
|
||||
⚠️ **Physical access** - Anyone with terminal access can use
|
||||
⚠️ **Session hijacking** - Theoretical risk in shared environments
|
||||
|
||||
### API Mode
|
||||
|
||||
✅ **Revocable** - Can disable keys anytime
|
||||
✅ **Trackable** - Monitor usage per key
|
||||
✅ **Rotatable** - Easy to update
|
||||
|
||||
⚠️ **Key exposure** - Must protect .env file
|
||||
⚠️ **Commit risk** - Can accidentally commit
|
||||
⚠️ **Scope risk** - Key has broad permissions
|
||||
|
||||
### Protection Strategies
|
||||
|
||||
1. **For .env files**
|
||||
```bash
|
||||
# Always in .gitignore
|
||||
echo ".env" >> .gitignore
|
||||
|
||||
# Restrict permissions
|
||||
chmod 600 .env
|
||||
|
||||
# Use git secrets scanning
|
||||
git secrets --scan
|
||||
```
|
||||
|
||||
2. **For production**
|
||||
```bash
|
||||
# Use secrets managers
|
||||
- AWS Secrets Manager
|
||||
- HashiCorp Vault
|
||||
- GitHub Secrets
|
||||
|
||||
# Not .env files in production
|
||||
```
|
||||
|
||||
3. **For CI/CD**
|
||||
```yaml
|
||||
# Use repository secrets
|
||||
secrets:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
|
||||
# Never hardcode
|
||||
# Never commit
|
||||
```
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Start with Subscription Mode**
|
||||
- Simpler setup
|
||||
- Perfect for learning
|
||||
- Great for development
|
||||
- Zero configuration
|
||||
|
||||
**Migrate to API Mode when needed**
|
||||
- Adding CI/CD
|
||||
- Implementing webhooks
|
||||
- Scheduling tasks
|
||||
- Production deployment
|
||||
|
||||
**Keep both available**
|
||||
- Developers use subscription
|
||||
- Automation uses API
|
||||
- Best of both worlds
|
||||
|
||||
Same ADW infrastructure supports both - choose based on context.
|
||||
Reference in New Issue
Block a user