composable-step-design

# Composable Step Design

Design the four composable workflow steps (Plan/Build/Review/Fix) that form the backbone of AI Developer Workflows.

## When to Use

- Creating new workflow step primitives
- Defining step input/output contracts
- Implementing step isolation patterns
- Designing step composition strategies
- Building ADW workflow variations

## Prerequisites

- Understanding of @composable-steps.md memory file
- Familiarity with @adw-framework.md patterns
- Knowledge of deterministic vs non-deterministic execution

## SDK Requirement

> **Implementation Note**: Full step orchestration requires Claude Agent SDK. This skill provides step design patterns and contracts.

## The Four Steps

| Step | Type | Output | Characteristic |
| --- | --- | --- | --- |
| `/plan` | Deterministic output | Spec file | Known path, structured content |
| `/build` | Non-deterministic | Code changes | Creative, adaptive |
| `/review` | Deterministic output | PASS/FAIL report | Structured, parseable |
| `/fix` | Non-deterministic | Targeted fixes | Focused, corrective |

## Step Design Process

### Step 1: Define the Contract

Each step needs a clear contract:

```python
# Plan Step Contract
class PlanContract:
    inputs = {
        "task_description": str,      # What to implement
        "issue_context": str | None,  # Optional context
        "project_path": str           # Where to work
    }
    outputs = {
        "spec_file_path": str,        # Path to generated spec
        "success": bool
    }
```text

### Step 2: Ensure Isolation

Each step must be runnable independently:

**Isolation Requirements:**

1. Accept inputs via arguments or file paths (not workflow state)
2. Produce outputs to known, predictable locations
3. Not depend on other steps having run
4. Complete or fail cleanly (no partial states)
5. Be testable in isolation

### Step 3: Define Success Criteria

Each step needs clear success indicators:

**Plan Step:**

- [ ] Spec file created at expected path
- [