c/claude-archeflow-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34f101c1666e40df6f65454eaf9454f602d96744
claude-archeflow-plugin/skills/run/SKILL.md

20 KiB
Raw Blame History

name, description
name description
run 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.

# 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)

# 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: 
    ./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).

# 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)

Parsing instructions:

Read plan-creator.md, locate the ### Confidence table. Extract scores for each axis as floats:

CONF_FILE=".archeflow/artifacts/${RUN_ID}/plan-creator.md"

# Extract confidence scores (expects format: "| Task understanding | 0.8 |")
TASK_UNDERSTANDING=$(grep -i "task understanding" "$CONF_FILE" | grep -oE '[0-9]+\.[0-9]+' | head -1)
SOLUTION_COMPLETENESS=$(grep -i "solution completeness" "$CONF_FILE" | grep -oE '[0-9]+\.[0-9]+' | head -1)
RISK_COVERAGE=$(grep -i "risk coverage" "$CONF_FILE" | grep -oE '[0-9]+\.[0-9]+' | head -1)

# Fallback: if unparseable, treat as 0.7 (safe default — proceed but not overconfident)
TASK_UNDERSTANDING="${TASK_UNDERSTANDING:-0.7}"
SOLUTION_COMPLETENESS="${SOLUTION_COMPLETENESS:-0.7}"
RISK_COVERAGE="${RISK_COVERAGE:-0.7}"

Pause branch (Task understanding < 0.5):

The Creator does not sufficiently understand the task. Do not spawn Maker.

  1. Emit decision event with "chosen":"pause"
  2. Display message to user: "Creator rated task understanding at . Clarification needed before proceeding."
  3. Block until the user provides clarification
  4. Re-run Creator with the clarification appended to the task description
./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"pause","rationale":"task_understanding scored '"$TASK_UNDERSTANDING"'"}' "$SEQ_CREATOR_COMPLETE"

Upgrade branch (Solution completeness < 0.5):

The Creator's proposal is incomplete — more research is needed.

  1. If fast workflow: upgrade to standard, spawn Explorer, then re-run Creator with Explorer output
  2. If already standard/thorough: re-run Explorer with a focused prompt targeting the incomplete areas
./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"upgrade","rationale":"solution_completeness scored '"$SOLUTION_COMPLETENESS"'"}' "$SEQ_CREATOR_COMPLETE"

# If fast → standard upgrade:
WORKFLOW="standard"
# Spawn Explorer, then re-run Creator with Explorer findings

Mini-Explorer branch (Risk coverage < 0.5):

The Creator identified risks but lacks confidence in their assessment. Spawn a focused Explorer to investigate.

Agent(
  description: "Mini-Explorer: investigate risk area for <task>",
  prompt: "You are the EXPLORER archetype. The Creator rated risk coverage at <score>.
    Identified risks: <risks from plan-creator.md>
    Research ONLY the risky areas. Answer: Is the risk real? What mitigations exist? What tests/guards would help?
    Limit: focused output only.",
  subagent_type: "Explore"
)

Save output to .archeflow/artifacts/${RUN_ID}/plan-mini-explorer.md. The Maker receives both plan-creator.md and plan-mini-explorer.md as context.

./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"mini_explorer","rationale":"risk_coverage scored '"$RISK_COVERAGE"'"}' "$SEQ_CREATOR_COMPLETE"

Note: The mini-Explorer runs in parallel with Do phase preparation (5 min max). The Maker can proceed once both plan-creator.md and plan-mini-explorer.md are available.

1d. Phase Transition: Plan to Do

# 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
./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: 
    ./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

./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).

./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: 
    ./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:

./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:

# 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.

./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:

    ./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. Pre-merge hook check:

    # Read hooks config if it exists
if [[ -f ".archeflow/hooks.yaml" ]]; then
  PRE_MERGE_HOOKS=$(grep -A5 "pre-merge:" .archeflow/hooks.yaml || true)
  if [[ -n "$PRE_MERGE_HOOKS" ]]; then
    echo "Running pre-merge hooks..."
    # Execute hooks; abort merge if fail_action: abort
    # Hook execution is project-specific — see .archeflow/hooks.yaml
  fi
fi

  3. Merge the Maker's worktree branch:

    ./lib/archeflow-git.sh merge "$RUN_ID" --no-ff

  4. Post-merge test validation:

    # Read test_command from config
TEST_CMD=$(grep -E "^test_command:" .archeflow/config.yaml | sed 's/^test_command:\s*//' | tr -d '"' || true)

if [[ -n "$TEST_CMD" ]]; then
  echo "Running post-merge tests: $TEST_CMD"
  if ! bash -c "$TEST_CMD"; then
    echo "Post-merge tests FAILED — reverting merge..."
    git revert --no-edit HEAD

    # Emit decision event for the revert
    ./lib/archeflow-event.sh "$RUN_ID" decision act "" \
      '{"what":"post_merge_test","chosen":"revert","rationale":"test suite failed after merge"}' "$SEQ_CHECK_TO_ACT"

    # If cycles remain, cycle back with integration test failure feedback
    if [[ "$CYCLE" -lt "$MAX_CYCLES" ]]; then
      echo "Cycling back with integration test failure feedback..."
      # Build act-feedback.md with "integration test failure on main" as top finding
      # Continue to step 4d (Issues Found)
    else
      echo "Max cycles reached. Reporting failure to user."
      # Continue to step 4e (Max Cycles Reached)
    fi
  fi
fi

  5. Clean up worktree:

    ./lib/archeflow-git.sh cleanup "$RUN_ID"

  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):

    touch .archeflow/artifacts/${RUN_ID}/act-fixes.jsonl

  4. Emit cycle.boundary:

    ./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:

    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

# 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:

./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:

{"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
Reference in New Issue View Git Blame Copy Permalink