claude-archeflow-plugin/skills/orchestration/SKILL.md

---
name: orchestration
description: Use when executing a multi-agent orchestration — spawning archetype agents, managing PDCA cycles, coordinating worktrees, and merging results. This is the step-by-step execution guide.
---

# Orchestration Execution

This skill guides you through running a full ArcheFlow orchestration using Claude Code's native Agent tool and git worktrees.

## Step 0: Choose a Workflow

Assess the task and pick:

| Signal | Workflow |
|--------|----------|
| Small fix, low risk, single concern | `fast` (1 cycle) |
| Feature, multiple files, moderate risk | `standard` (2 cycles) |
| Security-sensitive, breaking changes, public API | `thorough` (3 cycles) |

## Step 1: Plan Phase

Spawn agents sequentially — Creator needs Explorer's findings.

### Explorer (if standard or thorough)
```
Agent(
  description: "Explorer: research context",
  prompt: "<task description>
    You are the EXPLORER archetype.
    Research the codebase to understand:
    1. What files and functions are involved
    2. What dependencies exist
    3. What tests currently cover this area
    4. What patterns the codebase uses
    Write your findings as a structured research report.
    Be thorough but focused — no rabbit holes.",
  subagent_type: "Explore"
)
```

### Creator
```
Agent(
  description: "Creator: design proposal",
  prompt: "<task description>
    You are the CREATOR archetype.
    Based on the research findings: <Explorer's output>
    Design a solution proposal including:
    1. Architecture decisions (with rationale)
    2. Files to create/modify (with specific changes)
    3. Test strategy
    4. Confidence score (0.0 to 1.0)
    5. Risks you foresee
    Be decisive. Ship a clear plan, not a menu of options.",
  subagent_type: "Plan"
)
```

## Step 2: Do Phase

Spawn Maker in an **isolated worktree** so changes don't affect main.

```
Agent(
  description: "Maker: implement proposal",
  prompt: "<task description>
    You are the MAKER archetype.
    Implement this proposal: <Creator's output>
    Rules:
    1. Follow the proposal exactly — don't redesign
    2. Write tests for every behavioral change
    3. Commit with descriptive messages
    4. Run existing tests — nothing may break
    5. If the proposal is unclear, implement your best interpretation and note it
    Do NOT skip tests. Do NOT refactor unrelated code.",
  isolation: "worktree",
  mode: "bypassPermissions"
)
```

**Critical:** The Maker MUST commit its changes before finishing. Uncommitted changes in a worktree are lost.

## Step 3: Check Phase

Spawn reviewers **in parallel** — they read the Maker's changes independently.

### Guardian
```
Agent(
  description: "Guardian: security and risk review",
  prompt: "You are the GUARDIAN archetype.
    Review the changes in branch: <maker's branch>
    Assess:
    1. Security vulnerabilities (injection, auth bypass, data exposure)
    2. Reliability risks (error handling, edge cases, race conditions)
    3. Breaking changes (API compatibility, schema migrations)
    4. Dependency risks (new deps, version conflicts)
    Output: APPROVED or REJECTED with specific findings.
    Each finding needs: location, severity (critical/warning/info), description, fix suggestion.
    Be rigorous but practical — flag real risks, not theoretical ones."
)
```

### Skeptic (if standard or thorough)
```
Agent(
  description: "Skeptic: challenge assumptions",
  prompt: "You are the SKEPTIC archetype.
    Review the changes in branch: <maker's branch>
    Challenge:
    1. Assumptions in the design — what if they're wrong?
    2. Alternative approaches not considered
    3. Edge cases not tested
    4. Scalability concerns
    Output: APPROVED or REJECTED with counterarguments.
    Be constructive — every challenge must include a suggested alternative."
)
```

### Sage (if standard or thorough)
```
Agent(
  description: "Sage: holistic quality review",
  prompt: "You are the SAGE archetype.
    Review the changes in branch: <maker's branch>
    Evaluate holistically:
    1. Code quality (readability, maintainability, simplicity)
    2. Test coverage (are the tests meaningful, not just present?)
    3. Documentation (does the change need docs?)
    4. Consistency with codebase patterns
    Output: APPROVED or REJECTED with quality findings.
    Judge like a senior engineer doing a PR review."
)
```

### Trickster (if thorough only)
```
Agent(
  description: "Trickster: adversarial testing",
  prompt: "You are the TRICKSTER archetype.
    Try to break the changes in branch: <maker's branch>
    Attack vectors:
    1. Malformed input, boundary values, empty/null/huge data
    2. Concurrency and race conditions
    3. Error path exploitation
    4. Dependency failure scenarios
    Output: APPROVED or REJECTED with edge cases found.
    Think like a QA engineer who gets paid per bug found."
)
```

## Step 4: Act Phase

Collect all reviewer outputs and decide:

### All Approved
1. Merge the Maker's worktree branch into the target branch
2. Report: what was implemented, what was reviewed, any warnings noted
3. Clean up the worktree

### Issues Found (and cycles remaining)
1. Collect all findings into a feedback summary
2. Go back to Step 1 (Plan) with the feedback
3. Creator revises the proposal based on reviewer findings
4. Maker re-implements in a fresh worktree
5. Reviewers check again

### Max Cycles Reached with Unresolved Issues
1. Report all unresolved findings to the user
2. Present the best implementation so far (on its branch)
3. Let the user decide: merge as-is, fix manually, or abandon

## Orchestration Report

After completion, summarize:

```
## ArcheFlow Orchestration Report
- **Task:** <description>
- **Workflow:** standard (2 cycles)
- **Cycle 1:** Guardian rejected (SQL injection in user input handler)
- **Cycle 2:** All approved after input sanitization added
- **Files changed:** 4 files, +120 -30 lines
- **Tests added:** 8 new tests
- **Branch:** archeflow/maker-<id> → merged to main
```