feat: add automated PDCA loop, domain adapters, cost tracking, DAG renderer

- skills/run: automated PDCA execution loop with --start-from, --dry-run - skills/artifact-routing: inter-phase artifact protocol with context injection - skills/act-phase: structured review→fix pipeline with cycle feedback - skills/domains: domain adapter system (writing, code, research) - skills/cost-tracking: per-agent cost estimation, budget enforcement - lib/archeflow-dag.sh: ASCII DAG renderer from JSONL events - lib/archeflow-report.sh: updated with DAG section, cycle diff, --dag/--summary flags
2026-04-03 11:20:14 +02:00
parent 1753e69a9f
commit b6df3d19fd
7 changed files with 2259 additions and 12 deletions
--- a/skills/run/SKILL.md
+++ b/skills/run/SKILL.md
@@ -0,0 +1,460 @@
+---
+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
+```