zhongwei/gh-joshuaoliphant-claude-plugins-plugins-adw-bootstrap

Files

Zhongwei Li 8a4be47b6e Initial commit

2025-11-30 08:28:42 +08:00

8.5 KiB

Raw Blame History

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:

Context - What information the agent has access to
Model - Which AI model processes the prompt (Sonnet vs Opus)
Prompt - The specific instructions given to the agent
Tools - What actions the agent can take (Read, Write, Bash, etc.)

Through Agent (Structural Eight)

These shape how you structure work for agents:

Standard Output - Structured agent outputs for observability
Types - Data models and schemas that define interfaces
Docs - Documentation that provides context to agents
Tests - Validation that ensures agent work is correct
Architecture - System design that guides agent decisions
Plans - Specifications that break work into steps
Templates - Reusable prompt patterns (slash commands)
AI Developer Workflows - Orchestrated multi-agent processes

Core Patterns

Pattern 1: Subprocess-Based Execution

When to use: Simple prompts, shell compatibility, lower dependencies

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

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:

# .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:

# 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

# 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

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

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

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

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

Separation of Concerns: Agentic layer (how to operate) vs Application layer (what to operate on)
Progressive Enhancement: Start minimal, add features as needed, scale when required
Observability: Structured outputs make agent behavior transparent and debuggable
Intelligence Over Templating: Provide patterns, let Claude adapt intelligently
Mode Flexibility: Support both interactive (subscription) and automated (API) workflows
Compute as Leverage: Scale impact by scaling compute, not just working harder

8.5 KiB Raw Blame History