claude-archeflow-plugin/skills/workflow-design/SKILL.md

---
name: workflow-design
description: Use when designing custom orchestration workflows — choosing which archetypes run in each PDCA phase, setting exit conditions, and configuring PDCA cycles.
---

# Workflow Design — PDCA Cycles

ArcheFlow's PDCA cycles spiral upward through iterations — each cycle incorporates feedback from the previous one, producing progressively better results. Each cycle incorporates feedback from the previous one.

```
        ╱ Act ──────────── Done ✓
       ╱        ↑
      ╱    Check (review)
     ╱         ↑
    ╱      Do (implement)
   ╱           ↑
  ╱       Plan (design)     ← Cycle 2 (with feedback from Cycle 1)
 ╱              ↑
╱          Act ─┘ (issues found → feed back)
│              ↑
│         Check (review)
│              ↑
│          Do (implement)
│              ↑
│         Plan (design)     ← Cycle 1 (initial)
```

## Strategy vs Workflow

A **strategy** defines the execution shape: PDCA is cyclic (Plan-Do-Check-Act with feedback loops), pipeline is linear (Plan-Implement-Review-Verify, no cycle-back). A **workflow** defines the depth: fast uses fewer agents and cycles, thorough uses more. Strategy and workflow are orthogonal — you can run a `fast` workflow with either strategy, though `thorough` always uses PDCA because linear flows cannot iterate on findings.

## Built-in Workflows

### `fast` — Single Turn
```
Plan:  Creator designs
Do:    Maker implements (worktree)
Check: Guardian reviews
Act:   Approve or reject (1 cycle max)
```
**Use for:** Bug fixes, small changes, low-risk tasks.

### `standard` — Two Cycles
```
Plan:  Explorer researches → Creator designs
Do:    Maker implements (worktree)
Check: Guardian + Skeptic + Sage review (parallel)
Act:   Approve or cycle (2 cycles max)
```
**Use for:** Features, refactors, moderate-risk changes.

### `thorough` — Three Cycles
```
Plan:  Explorer researches → Creator designs
Do:    Maker implements (worktree)
Check: Guardian + Skeptic + Sage + Trickster (parallel)
Act:   Approve or cycle (3 cycles max)
```
**Use for:** Security-critical, public APIs, infrastructure changes.

## Designing Custom Workflows

### Step 1: Identify the Concern

What's the primary risk?

| Primary Risk | Emphasize |
|-------------|-----------|
| Security | Guardian + Trickster in Check |
| Correctness | Skeptic + Sage in Check |
| Performance | Custom `perf-tester` archetype |
| Compliance | Custom `compliance-auditor` archetype |
| Data integrity | Custom `db-specialist` archetype |
| User experience | Custom `ux-reviewer` archetype |

### Step 2: Assign Phases

Rules:
- **Plan** always includes Creator (someone must propose)
- **Do** always includes Maker (someone must build)
- **Check** needs at least one reviewer
- Max 3 archetypes per phase (diminishing returns beyond that)
- Explorer goes in Plan only (research before design)
- Maker goes in Do only (build from plan, not from scratch)

### Step 3: Set Exit Conditions

| Condition | When Cycle Ends | Best For |
|-----------|----------------|----------|
| `all_approved` | Every Check reviewer says APPROVED | Consensus-driven (default) |
| `no_critical` | No CRITICAL findings in Check output | Speed with safety net |
| `convergence` | No new issues vs. previous cycle | Diminishing returns detection |
| `always` | Runs all maxCycles unconditionally | Research, exploration |

### Step 4: Set Max Cycles

- **1 cycle:** Fast, low-risk (fast workflow)
- **2 cycles:** Balanced — one shot + one fix (standard workflow)
- **3 cycles:** Thorough — usually converges by cycle 3
- **4+ cycles:** Rarely useful. If 3 cycles don't converge, the task needs human input.

## Example Custom Workflows

### Security-First
```
Plan:  Explorer (threat modeling) → Creator
Do:    Maker
Check: Guardian + Trickster (parallel)
Exit:  all_approved, max 3 cycles
```

### Research-Heavy
```
Plan:  Explorer (deep research) → Creator
Do:    Maker
Check: Skeptic + Sage (parallel)
Exit:  all_approved, max 2 cycles
```

### Domain-Specific (with custom archetypes)
```
Plan:  Explorer → Creator
Do:    Maker
Check: Guardian + db-specialist + compliance-auditor (parallel)
Exit:  all_approved, max 2 cycles
```

### Minimal Validation
```
Plan:  Creator (no research)
Do:    Maker
Check: Guardian
Exit:  no_critical, max 1 cycle
```

## Hook Points

Add project-specific validation at key moments in the PDCA cycle. Define hooks in `.archeflow/hooks.yaml`:

```yaml
# .archeflow/hooks.yaml
pre-plan:
  - command: "npm run lint"
    description: "Ensure clean baseline before planning"
    fail_action: abort  # abort | warn | ignore

post-check:
  - command: "npm test"
    description: "Run tests after review to verify reviewer suggestions"
    fail_action: cycle_back

pre-merge:
  - command: "./scripts/check-migrations.sh"
    description: "Verify migration safety before merging"
    fail_action: abort

post-merge:
  - command: "npm run integration-test"
    description: "Full integration test after merge"
    fail_action: revert
```

**Available hook points:**
| Hook | When | Typical Use |
|------|------|-------------|
| `pre-plan` | Before Explorer/Creator start | Lint, ensure clean baseline |
| `post-plan` | After Creator's proposal | Validate proposal against constraints |
| `pre-do` | Before Maker starts | Check worktree setup |
| `post-do` | After Maker commits | Quick smoke test |
| `post-check` | After reviewers finish | Run test suite |
| `pre-merge` | Before merging to main | Migration safety, API compatibility |
| `post-merge` | After merge completes | Integration tests, deploy checks |

## Workflow Template Library

Pre-built workflows for common scenarios. Use as-is or as starting points for custom workflows.

### API Design
```yaml
name: api-design
description: New or changed API endpoints
plan: [explorer, creator]
do: [maker]
check: [guardian, skeptic]  # Guardian for security, Skeptic for API design assumptions
exit: all_approved
max_cycles: 2
hooks:
  post-check: "npm run api-compatibility-check"
```

### Database Migration
```yaml
name: migration
description: Schema changes and data migrations
plan: [explorer, creator]
do: [maker]
check: [guardian, db-specialist]  # Requires custom db-specialist archetype
exit: all_approved
max_cycles: 2
hooks:
  pre-merge: "./scripts/check-migration-reversibility.sh"
```

### Dependency Upgrade
```yaml
name: dep-upgrade
description: Upgrading dependencies (major versions, security patches)
plan: [creator]  # No Explorer needed — changelog is the research
do: [maker]
check: [guardian]
exit: no_critical
max_cycles: 1
hooks:
  post-do: "npm audit"
  post-merge: "npm test && npm run e2e"
```

### Documentation Rewrite
```yaml
name: docs-rewrite
description: Major documentation changes
plan: [explorer, creator]
do: [maker]
check: [sage]  # Quality/consistency only — no security review needed
exit: all_approved
max_cycles: 1
```

### Hotfix
```yaml
name: hotfix
description: Emergency production fix
plan: [creator]
do: [maker]
check: [guardian]
exit: no_critical
max_cycles: 1
hooks:
  post-merge: "npm test"
```

## Anti-Patterns

- **Kitchen sink:** Putting all 7 archetypes in Check. Most can't add value simultaneously.
- **Runaway cycles:** maxCycles > 4 burns tokens without convergence.
- **Reviewerless Do:** Skipping Check phase "to save time." You'll pay in bugs.
- **Maker in Plan:** Maker should implement from a proposal, not design on the fly.
- **Solo orchestration:** One archetype in every phase. That's just a single agent with extra steps.