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

---
name: run
description: |
  Automated PDCA execution loop. Single-command orchestration that initializes a run, flows through
  Plan/Do/Check/Act phases, emits events at every step, saves artifacts to disk, and handles
  cycle-back with structured feedback. Use instead of manually following orchestration steps.
  <example>User: "archeflow:run"</example>
  <example>User: "Run this through ArcheFlow"</example>
  <example>User: "archeflow:run --start-from check"</example>
  <example>User: "archeflow:run --dry-run"</example>
---

# ArcheFlow Run — Automated PDCA Execution Loop

This skill automates the full orchestration cycle. When invoked, Claude executes all PDCA phases end-to-end, emitting events and saving artifacts at every step. No manual phase-by-phase intervention needed.

## Prerequisites

Load these skills (they are referenced throughout):
- `archeflow:orchestration` — agent prompts, workflow selection, adaptation rules
- `archeflow:process-log` — event schema and DAG parent rules
- `archeflow:artifact-routing` — artifact naming, context injection, cycle archiving

## Invocation

```
archeflow:run                           # Full run, auto-select workflow
archeflow:run --workflow standard       # Force a specific workflow
archeflow:run --start-from do           # Resume from Do phase (requires prior artifacts)
archeflow:run --start-from check        # Resume from Check phase
archeflow:run --dry-run                 # Plan phase only, show cost estimate
archeflow:run --max-cycles 1            # Override max cycles
```

---

## Execution Steps

### 0. Initialize

Generate a run ID and set up the artifact directory.

```bash
# Generate run_id
RUN_ID="$(date -u +%Y-%m-%d)-<task-slug>"

# Create artifact directory
mkdir -p .archeflow/artifacts/${RUN_ID}

# Emit run.start event (seq=1, parent=[])
./lib/archeflow-event.sh "$RUN_ID" run.start plan "" \
  '{"task":"<task description>","workflow":"<fast|standard|thorough>","max_cycles":<N>}'
```

**Track state:** Maintain these variables throughout the run:
- `RUN_ID` — unique run identifier
- `SEQ` — current sequence number (read from event file line count after each emit)
- `CYCLE` — current PDCA cycle number (starts at 1)
- `WORKFLOW` — fast/standard/thorough (may change via adaptation rules)
- `ESCALATED` — boolean, set true if A1 triggers

After emitting `run.start`, record `SEQ_RUN_START=1`.

If `--start-from` is specified, verify that the required prior artifacts exist in `.archeflow/artifacts/${RUN_ID}/` before skipping phases. If missing, abort with an error.

---

### 1. Plan Phase

#### 1a. Explorer (if standard or thorough)

```bash
# Emit agent.start
./lib/archeflow-event.sh "$RUN_ID" agent.start plan explorer \
  '{"archetype":"explorer","prompt_summary":"Research codebase context for task"}' "$SEQ_RUN_START"
```

Spawn the Explorer agent using the prompt from `archeflow:orchestration` Step 1.

```
Agent(
  description: "Explorer: research context for <task>",
  prompt: "<Explorer prompt from orchestration skill>",
  subagent_type: "Explore"
)
```

After Explorer returns:
1. Save output to `.archeflow/artifacts/${RUN_ID}/plan-explorer.md`
2. Emit `agent.complete`:
   ```bash
   ./lib/archeflow-event.sh "$RUN_ID" agent.complete plan explorer \
     '{"archetype":"explorer","duration_ms":<ms>,"artifacts":["plan-explorer.md"],"summary":"<1-line summary>"}' "$SEQ_EXPLORER_START"
   ```
3. Record `SEQ_EXPLORER_COMPLETE` for DAG references.

#### 1b. Creator

The Creator receives Explorer output (if it exists) or performs Mini-Reflect (fast workflow).

```bash
# Emit agent.start — parent is explorer.complete (or run.start for fast)
./lib/archeflow-event.sh "$RUN_ID" agent.start plan creator \
  '{"archetype":"creator","prompt_summary":"Design solution proposal"}' "$SEQ_EXPLORER_COMPLETE"
```

Spawn the Creator agent using the prompt from `archeflow:orchestration` Step 1.

**Context injection (from artifact-routing skill):**
- Fast workflow: task description only
- Standard/thorough: task description + contents of `plan-explorer.md`
- Cycle 2+: task description + `plan-explorer.md` + `act-feedback.md` from prior cycle

```
Agent(
  description: "Creator: design proposal for <task>",
  prompt: "<Creator prompt from orchestration skill, with context injected per above>",
  subagent_type: "Plan"
)
```

After Creator returns:
1. Save output to `.archeflow/artifacts/${RUN_ID}/plan-creator.md`
2. Emit `agent.complete`
3. Record `SEQ_CREATOR_COMPLETE`

#### 1c. Confidence Gate (Adaptation Rule A3)

Read Creator's confidence scores from `plan-creator.md`. Apply A3 per `archeflow:orchestration`:
- Task understanding < 0.5 → **Pause**, ask user
- Solution completeness < 0.5 → **Upgrade** to standard, spawn Explorer
- Risk coverage < 0.5 → **Spawn mini-Explorer** for risky area (parallel, 5 min max)

If A3 triggers, emit a `decision` event:
```bash
./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"<action>","rationale":"<axis> scored <score>"}' "$SEQ_CREATOR_COMPLETE"
```

#### 1d. Phase Transition: Plan to Do

```bash
# Parent = all completing events in Plan phase
./lib/archeflow-event.sh "$RUN_ID" phase.transition do "" \
  '{"from":"plan","to":"do","artifacts_so_far":["plan-explorer.md","plan-creator.md"]}' "$SEQ_CREATOR_COMPLETE"
```

Record `SEQ_PLAN_TO_DO`.

---

### 2. Do Phase

#### 2a. Maker

**Context injection (from artifact-routing skill):**
- Contents of `plan-creator.md` (the proposal)
- Cycle 2+: also contents of `act-feedback.md` filtered to Maker-routed findings only

```bash
./lib/archeflow-event.sh "$RUN_ID" agent.start do maker \
  '{"archetype":"maker","prompt_summary":"Implement proposal in isolated worktree"}' "$SEQ_PLAN_TO_DO"
```

```
Agent(
  description: "Maker: implement <task>",
  prompt: "<Maker prompt from orchestration skill, with Creator proposal injected>
    <if cycle 2+: Implementation feedback: <Maker-routed findings from act-feedback.md>>",
  isolation: "worktree",
  mode: "bypassPermissions"
)
```

After Maker returns:
1. Save implementation summary to `.archeflow/artifacts/${RUN_ID}/do-maker.md`
2. Capture list of changed files: `git diff --name-only` on the Maker's branch, save to `.archeflow/artifacts/${RUN_ID}/do-maker-files.txt`
3. Emit `agent.complete`:
   ```bash
   ./lib/archeflow-event.sh "$RUN_ID" agent.complete do maker \
     '{"archetype":"maker","duration_ms":<ms>,"artifacts":["do-maker.md","do-maker-files.txt"],"summary":"<files changed, tests added>"}' "$SEQ_MAKER_START"
   ```
4. Record `SEQ_MAKER_COMPLETE`

**Critical:** Verify the Maker committed its changes before proceeding. If uncommitted changes exist, instruct the Maker to commit.

#### 2b. Phase Transition: Do to Check

```bash
./lib/archeflow-event.sh "$RUN_ID" phase.transition check "" \
  '{"from":"do","to":"check","artifacts_so_far":["plan-explorer.md","plan-creator.md","do-maker.md","do-maker-files.txt"]}' "$SEQ_MAKER_COMPLETE"
```

Record `SEQ_DO_TO_CHECK`.

---

### 3. Check Phase

**Important:** Spawn Guardian FIRST, then evaluate A2 before spawning other reviewers.

#### 3a. Guardian (always first)

**Context injection:** Maker's git diff + proposal risk section only (not full proposal, not Explorer research).

```bash
./lib/archeflow-event.sh "$RUN_ID" agent.start check guardian \
  '{"archetype":"guardian","prompt_summary":"Security and risk review of changes"}' "$SEQ_DO_TO_CHECK"
```

```
Agent(
  description: "Guardian: security review for <task>",
  prompt: "<Guardian prompt from orchestration skill, with Maker's diff injected>"
)
```

After Guardian returns:
1. Save to `.archeflow/artifacts/${RUN_ID}/check-guardian.md`
2. Emit `review.verdict`:
   ```bash
   ./lib/archeflow-event.sh "$RUN_ID" review.verdict check guardian \
     '{"archetype":"guardian","verdict":"<approved|rejected|approved_with_fixes>","findings":[...]}' "$SEQ_GUARDIAN_START"
   ```
3. Record `SEQ_GUARDIAN_VERDICT`

#### 3b. Guardian Fast-Path Check (Adaptation Rule A2)

Parse Guardian's output. If **0 CRITICAL and 0 WARNING** AND workflow is not escalated AND not first cycle of thorough:

```bash
./lib/archeflow-event.sh "$RUN_ID" decision check "" \
  '{"what":"guardian_fast_path","chosen":"skip_remaining_reviewers","rationale":"0 CRITICAL, 0 WARNING"}' "$SEQ_GUARDIAN_VERDICT"
```

Skip to Phase Transition (3d). Log "Guardian fast-path taken" in report.

Otherwise, proceed to spawn remaining reviewers.

#### 3c. Remaining Reviewers (in parallel)

Spawn these based on workflow (see `archeflow:orchestration` for which reviewers apply):

**Skeptic** (standard/thorough):
- Context: Creator's proposal (assumptions section focus)
- Save to: `check-skeptic.md`

**Sage** (standard/thorough):
- Context: Creator's proposal + Maker's diff + implementation summary
- Save to: `check-sage.md`

**Trickster** (thorough only):
- Context: Maker's diff only
- Save to: `check-trickster.md`

Spawn all applicable reviewers in parallel (multiple Agent calls in one message). For each:

```bash
# Emit agent.start with parent = SEQ_DO_TO_CHECK
./lib/archeflow-event.sh "$RUN_ID" agent.start check <archetype> \
  '{"archetype":"<archetype>","prompt_summary":"<review focus>"}' "$SEQ_DO_TO_CHECK"
```

After each returns, emit `review.verdict` and save artifact.

#### 3d. Phase Transition: Check to Act

Collect all verdict seq numbers for the parent array.

```bash
./lib/archeflow-event.sh "$RUN_ID" phase.transition act "" \
  '{"from":"check","to":"act"}' "<all_verdict_seqs>"
```

Record `SEQ_CHECK_TO_ACT`.

---

### 4. Act Phase

#### 4a. Collect Verdicts

Read all `check-*.md` artifacts. Tally findings:
- Count CRITICAL, WARNING, INFO per reviewer
- Check for unanimous approval

#### 4b. Escalation Check (Adaptation Rule A1)

If workflow is `fast` and Guardian found 2+ CRITICAL:
- Set `ESCALATED=true`
- Upgrade next cycle to `standard` (add Skeptic + Sage)
- Emit decision event

#### 4c. Branch: All Approved

If all reviewers approved (and completion criteria met, if defined):

1. Emit `cycle.boundary`:
   ```bash
   ./lib/archeflow-event.sh "$RUN_ID" cycle.boundary act "" \
     '{"cycle":<N>,"max_cycles":<M>,"exit_condition":"all_approved","met":true,"next_action":"complete"}' "$SEQ_CHECK_TO_ACT"
   ```

2. Run pre-merge hooks (check `.archeflow/hooks.yaml`)
3. Merge Maker's worktree branch: `git merge --no-ff <branch>`
4. Run post-merge hooks + test suite
   - Tests pass → continue
   - Tests fail → auto-revert, cycle back with "integration test failure" feedback
5. Clean up worktree
6. Proceed to Completion (step 5)

#### 4d. Branch: Issues Found (cycles remaining)

If any reviewer rejected and `CYCLE < MAX_CYCLES`:

1. Build structured feedback using the Cycle Feedback Protocol from `archeflow:orchestration`:
   - Extract findings from all `check-*.md` artifacts
   - Route findings: Guardian/Skeptic issues → Creator, Sage issues → Maker
   - Check convergence: same finding in 2 consecutive cycles → escalate to user
   - Dedup cross-archetype findings

2. Save to `.archeflow/artifacts/${RUN_ID}/act-feedback.md`

3. Save applied fixes log (initially empty, populated during next Do phase):
   ```bash
   touch .archeflow/artifacts/${RUN_ID}/act-fixes.jsonl
   ```

4. Emit `cycle.boundary`:
   ```bash
   ./lib/archeflow-event.sh "$RUN_ID" cycle.boundary act "" \
     '{"cycle":<N>,"max_cycles":<M>,"exit_condition":"all_approved","met":false,"next_action":"cycle_back"}' "$SEQ_CHECK_TO_ACT"
   ```

5. Archive current cycle artifacts:
   ```bash
   mkdir -p .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}
   cp .archeflow/artifacts/${RUN_ID}/plan-*.md .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}/
   cp .archeflow/artifacts/${RUN_ID}/do-*.md .archeflow/artifacts/${RUN_ID}/do-*.txt .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}/ 2>/dev/null || true
   cp .archeflow/artifacts/${RUN_ID}/check-*.md .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}/
   ```

6. Increment `CYCLE`, go back to Step 1 (Plan Phase)

#### 4e. Branch: Max Cycles Reached

If `CYCLE >= MAX_CYCLES` and issues remain:

1. Report all unresolved findings to the user
2. Present the best implementation (on its branch, not merged)
3. Let the user decide: merge as-is, fix manually, or abandon
4. Emit `cycle.boundary` with `"met": false, "next_action": "user_decision"`

---

### 5. Completion

```bash
# Emit run.complete
./lib/archeflow-event.sh "$RUN_ID" run.complete act "" \
  '{"status":"completed","cycles":<N>,"agents_total":<count>,"fixes_total":<count>,"shadows":0,"artifacts":[<list>]}'

# Generate report
./lib/archeflow-report.sh .archeflow/events/${RUN_ID}.jsonl

# Update run index
echo '{"run_id":"'$RUN_ID'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task":"<task>","workflow":"<wf>","status":"completed","cycles":<N>}' \
  >> .archeflow/events/index.jsonl
```

Display the orchestration report to the user (see `archeflow:orchestration` report format).

---

## Fix Tracking

When the Maker addresses review findings in cycle 2+, emit `fix.applied` for each:

```bash
./lib/archeflow-event.sh "$RUN_ID" fix.applied act "" \
  '{"source":"<reviewer>","finding":"<description>","file":"<path>","line":<n>}' "$SEQ_OF_REVIEW"
```

Also append to `.archeflow/artifacts/${RUN_ID}/act-fixes.jsonl`:
```jsonl
{"source":"guardian","finding":"SQL injection","file":"src/auth.ts","line":48,"fixed_in_cycle":2}
```

---

## Dry-Run Mode

When `--dry-run` is specified:

1. Run **only the Plan phase** (Explorer + Creator)
2. Display:
   ```
   Dry run for: "<task>"
     Workflow: <standard> (<N> cycles max)
     Agents per cycle: <count>
     Max agents total: <count * cycles>
     Plan phase result: see .archeflow/artifacts/<run_id>/plan-creator.md
     Creator confidence: <scores>
     Estimated phases: Plan (done) -> Do -> Check -> Act
     Proceed with full run? [y/n]
   ```
3. Do NOT emit `run.complete` — the run is paused, not finished
4. If user says yes, continue from `--start-from do` using the saved artifacts

---

## Start-From Mode

When `--start-from <phase>` is specified:

| Start from | Required artifacts in `.archeflow/artifacts/<run_id>/` |
|------------|-------------------------------------------------------|
| `plan` | None (equivalent to full run) |
| `do` | `plan-creator.md` |
| `check` | `plan-creator.md`, `do-maker.md`, `do-maker-files.txt` |
| `act` | All `check-*.md` files |

Validate required artifacts exist. If missing, error:
```
Cannot start from <phase>: missing artifact <name>. Run the prior phase first.
```

When resuming, emit a `run.start` event with `{"resumed_from":"<phase>"}` in data.

---

## Error Handling

- **Agent fails to return:** Wait up to 5 minutes. If no response, emit `agent.complete` with `"error": true`, log the failure, and abort the run. Do not retry blindly.
- **Event emitter fails:** Log a warning but do not block orchestration. Events are observation, not control flow.
- **Artifact write fails:** This IS blocking. Artifacts are required for phase handoff. Abort and report.
- **Merge conflict:** Do not force-resolve. Report the conflict, leave the branch intact, let the user decide.

---

## Progress Display

Throughout the run, display live progress using the format from `archeflow:using-archeflow`:

```
━━━ ArcheFlow Run: <task> ━━━━━━━━━━━━━━━━━━━
Run ID: <run_id> | Workflow: <standard> | Cycle: 1/<max>

[Plan]  Explorer researching...        -> done (35s)
[Plan]  Creator designing proposal...  -> done (25s, confidence: 0.8)
[Do]    Maker implementing...          -> done (90s, 4 files, 8 tests)
[Check] Guardian reviewing...          -> APPROVED
[Check] Skeptic challenging...         -> APPROVED (1 INFO)
[Check] Sage reviewing...             -> APPROVED
[Act]   All approved — merging...      -> merged to main

━━━ Complete: 3m 10s, 1 cycle ━━━━━━━━━━━━━━━
Artifacts: .archeflow/artifacts/<run_id>/
Report: .archeflow/events/<run_id>.jsonl
```