Primitive ADWs

Lightweight scripts that run without a GitHub repo or issue. These are the minimal entry point — useful for ad-hoc tasks, quick automation, and learning the ADW system before using the full SDLC pipeline.

adw_prompt.py

Run any Claude Code prompt directly from the command line.

uv run adws/adw_prompt.py "Add logging to the main module"
uv run adws/adw_prompt.py "Refactor this function" --model opus
uv run adws/adw_prompt.py "List files here" --working-dir /path/to/project

When to use: Ad-hoc tasks that don't need a GitHub issue or spec. Good for exploration, quick fixes, and learning.

adw_slash_command.py

Execute any .claude/commands/*.md template directly.

uv run adws/adw_slash_command.py /chore "Add error handling to all endpoints"
uv run adws/adw_slash_command.py /implement specs/my-plan.md --model opus
uv run adws/adw_slash_command.py /feature "Add CSV export to results table"

When to use: When you want the structure of a slash command without going through GitHub issues.

adw_chore_implement.py

Chains /chore (planning) → /implement (execution) in one command.

uv run adws/adw_chore_implement.py "Add a health check endpoint to apps/server.py"
uv run adws/adw_chore_implement.py "Refactor the auth module" --model opus

What it does:

1. Runs /chore to generate a plan
2. Extracts the spec path from output
3. Automatically runs /implement against that spec

Both phases write to agents/{adw_id}/planner/ and agents/{adw_id}/builder/.

When to use: Self-contained tasks that don't need a GitHub issue. Maintenance work, refactoring, technical debt.

adw_sdk_prompt.py

SDK-based interactive CLI using the claude-code-sdk Python package. Supports one-shot queries and multi-turn interactive sessions with session resumption.

# One-shot query
uv run adws/adw_sdk_prompt.py "Explain this codebase"

# Interactive session
uv run adws/adw_sdk_prompt.py --interactive

# Resume a previous session by ID
uv run adws/adw_sdk_prompt.py --interactive --session-id abc12345

# Enable specific tools
uv run adws/adw_sdk_prompt.py "Create hello.py" --tools Write,Read,Bash

# Set initial context
uv run adws/adw_sdk_prompt.py --interactive --context "Debugging the auth middleware"

Advantages over adw_prompt.py:

• Displays cost per turn
• Exposes session IDs for resumption
• Shows which tools were used
• Native async/await
• SDK-typed exceptions

When to use: Debugging sessions, exploratory analysis, any task where you want to continue a conversation across invocations.

Output Files

All primitive ADWs write to agents/{adw_id}/{agent_name}/:

File	Contents
cc_raw_output.jsonl	Raw streaming output (one JSON per line)
cc_raw_output.json	All messages as a parsed JSON array
cc_final_object.json	Last entry — the final result object
custom_summary_output.json	High-level summary with ADW ID, model, success, session ID

Choosing Between Primitives

flowchart TD
    A{Do you need\nmulti-turn?} -->|Yes| SDK[adw_sdk_prompt.py --interactive]
    A -->|No| B{Is it a specific\ntask type?}
    B -->|chore/refactor| CI[adw_chore_implement.py]
    B -->|slash command| SC[adw_slash_command.py]
    B -->|ad-hoc| PR[adw_prompt.py]