c/claude-archeflow-plugin

Fork 0

Files

Christian Nennemann 8af9db2c12 feat: add test-first validation gate in Do phase

2026-04-04 08:30:31 +02:00

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>

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:

Save output to .archeflow/artifacts/${RUN_ID}/plan-explorer.md

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"

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:

Save output to .archeflow/artifacts/${RUN_ID}/plan-creator.md
Emit agent.complete
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.

Emit decision event with "chosen":"pause"
Display message to user: "Creator rated task understanding at . Clarification needed before proceeding."
Block until the user provides clarification
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.

If fast workflow: upgrade to standard, spawn Explorer, then re-run Creator with Explorer output
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:

Save implementation summary to .archeflow/artifacts/${RUN_ID}/do-maker.md
Capture list of changed files: git diff --name-only on the Maker's branch, save to .archeflow/artifacts/${RUN_ID}/do-maker-files.txt

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"

Record SEQ_MAKER_COMPLETE

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

2a-ii. Test-First Validation

After Maker completes, check do-maker-files.txt for test files:

TEST_FILES=$(grep -iE '(test|spec)' ".archeflow/artifacts/${RUN_ID}/do-maker-files.txt" || true)

If TEST_FILES is empty and domain is not writing:

Check if plan-creator.md contains a ### Test Strategy section
If yes: re-run Maker with targeted test instruction (one retry within Do phase)
If no test strategy specified: emit WARNING event and proceed

./lib/archeflow-event.sh "$RUN_ID" decision do "" \
  '{"what":"test_first_gate","chosen":"<pass|warn|retry>","rationale":"<reason>"}' "$SEQ_MAKER_COMPLETE"

The re-run prompt for the retry case:

"The proposal specified these test cases: . No test files were found in your changes. Add the specified tests before finishing."

This is one retry within the Do phase, not a full PDCA cycle. If the retry also produces no tests, emit WARNING and proceed to Check.

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:

Save to .archeflow/artifacts/${RUN_ID}/check-guardian.md

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"

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

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"

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

Merge the Maker's worktree branch:

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

Post-merge test validation (using the auto-rollback script):

# Run tests and auto-revert if they fail
if ! ./lib/archeflow-rollback.sh "$RUN_ID"; then
  # Rollback script already reverted HEAD and emitted decision event
  # 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

Clean up worktree:

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

Proceed to Completion (step 5)

4d. Branch: Issues Found (cycles remaining)

If any reviewer rejected and CYCLE < MAX_CYCLES:

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
Save to .archeflow/artifacts/${RUN_ID}/act-feedback.md
Save applied fixes log (initially empty, populated during next Do phase):
```
touch .archeflow/artifacts/${RUN_ID}/act-fixes.jsonl
```

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"

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}/

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

4e. Branch: Max Cycles Reached

If CYCLE >= MAX_CYCLES and issues remain:

Report all unresolved findings to the user
Present the best implementation (on its branch, not merged)
Let the user decide: merge as-is, fix manually, or abandon
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:

Run only the Plan phase (Explorer + Creator)

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]

Do NOT emit run.complete — the run is paused, not finished
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

20 KiB Raw Blame History