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

name, description

name	description
progress	Live progress file for ArcheFlow orchestrations. Regenerates `.archeflow/progress.md` after every event emission, giving users real-time visibility into run status, budget usage, and DAG shape — watchable from a second terminal. <example>User: "What's happening with my run?"</example> <example>watch -n 2 cat .archeflow/progress.md</example>

Live Progress — Real-Time Run Visibility

During long-running orchestrations (Maker drafting, parallel reviews), users have no visibility into what is happening. This skill solves that by maintaining a live progress file that is regenerated after every event.

Progress File

Location: .archeflow/progress.md

Updated after every event emission during a run. Users can watch it from a second terminal:

# Simple polling
watch -n 2 cat .archeflow/progress.md

# Continuous mode (built-in)
./lib/archeflow-progress.sh <run_id> --watch

# Programmatic consumption
./lib/archeflow-progress.sh <run_id> --json

Progress File Format

# ArcheFlow Run: 2026-04-03-der-huster
**Status:** DO phase — maker running (3/6 scenes drafted)
**Started:** 14:32 | **Elapsed:** 8 min
**Budget:** $1.45 / $10.00 (14%)

## Progress
- [x] PLAN: Explorer (87s, 21k tok, $0.02)
- [x] PLAN: Creator (167s, 26k tok, $0.08)
- [x] PLAN -> DO transition
- [ ] **DO: Maker** <- running (5 min elapsed)
- [ ] CHECK: Guardian
- [ ] CHECK: Sage
- [ ] ACT: Apply fixes

## Latest Event
#6 agent.start — maker (do) — 14:40

## DAG (so far)
#1 run.start
├── #2 story-explorer ✓
│   ├── #3 decision ✓
│   └── #4 creator ✓
├── #5 plan→do ✓
└── #6 maker ← running

How to Use

During Orchestration (run skill integration)

The run skill should call archeflow-progress.sh after each event emission. This keeps progress decoupled from the event emitter itself — no modification to archeflow-event.sh is needed.

Add this call after every archeflow-event.sh invocation in the run loop:

# After emitting an event:
./lib/archeflow-event.sh "$RUN_ID" agent.complete plan explorer '{"archetype":"explorer",...}'

# Update progress:
./lib/archeflow-progress.sh "$RUN_ID"

This is a fast operation (reads JSONL, writes one markdown file) and adds negligible overhead.

From a Second Terminal

# One-shot: see current state
./lib/archeflow-progress.sh <run_id>
cat .archeflow/progress.md

# Continuous: auto-refresh every 2 seconds
./lib/archeflow-progress.sh <run_id> --watch

# JSON output for dashboards or scripts
./lib/archeflow-progress.sh <run_id> --json

Reactive Mode (via JSONL tail)

tail -f .archeflow/events/<run_id>.jsonl | while read line; do
  ./lib/archeflow-progress.sh <run_id>
done

Progress Script

Location: lib/archeflow-progress.sh

Usage:
  archeflow-progress.sh <run_id>           # Generate/update progress.md
  archeflow-progress.sh <run_id> --watch   # Continuous update mode (2s interval)
  archeflow-progress.sh <run_id> --json    # Output as JSON (for dashboards)

What the Script Does

1. Read .archeflow/events/<run_id>.jsonl — the event stream for this run
2. Determine current phase and active agent from the latest events
3. Build checklist — mark completed agents with timing/cost data, show pending agents as unchecked
4. Show partial DAG — completed nodes with checkmarks, running node with arrow indicator
5. Calculate budget — sum estimated_cost_usd from agent.complete events, compare to budget from run.start config or .archeflow/config.yaml
6. Compute elapsed time — difference between run.start timestamp and now
7. Write to .archeflow/progress.md

Output Modes

Default (markdown): Writes .archeflow/progress.md and prints the same content to stdout.

--watch: Clears the terminal every 2 seconds, re-reads the JSONL, and regenerates the display. Exits when a run.complete event is found.

--json: Outputs a structured JSON object to stdout (does not write progress.md):

{
  "run_id": "2026-04-03-der-huster",
  "status": "running",
  "phase": "do",
  "active_agent": "maker",
  "elapsed_seconds": 480,
  "budget_used_usd": 1.45,
  "budget_total_usd": 10.00,
  "budget_percent": 14,
  "completed": [
    {"agent": "explorer", "phase": "plan", "duration_s": 87, "tokens": 21000, "cost_usd": 0.02},
    {"agent": "creator", "phase": "plan", "duration_s": 167, "tokens": 26000, "cost_usd": 0.08}
  ],
  "pending": ["guardian", "sage"],
  "latest_event": {"seq": 6, "type": "agent.start", "agent": "maker", "phase": "do"},
  "total_events": 6
}

Checklist Construction

The progress checklist is built from events, not from a predefined workflow definition. Each event type maps to a checklist entry:

Event Type	Checklist Entry
agent.complete	- [x] PHASE: archetype (duration, tokens, cost)
agent.start (no matching complete)	- [ ] **PHASE: archetype** <- running (elapsed)
phase.transition	- [x] PHASE -> PHASE transition
review.verdict	- [x] CHECK: archetype -> VERDICT
fix.applied	- [x] ACT: Fix (source)
cycle.boundary	- [x] Cycle N complete

Pending agents (not yet started) are NOT shown in the checklist — only started or completed agents appear. This avoids guessing which agents will be spawned.

Budget Display

Budget information comes from two sources:

1. run.start event — may contain config.budget_usd
2. .archeflow/config.yaml — global budget.per_run_usd

If no budget is configured, the budget line shows cost only (no percentage):

**Cost:** $1.45 (no budget set)

Integration with Other Skills

• run: Should call archeflow-progress.sh after each event emission
• process-log: Progress reads the same JSONL that process-log defines
• cost-tracking: Budget data and cost calculations follow cost-tracking conventions
• autonomous-mode: Progress file is useful for monitoring autonomous overnight runs

Design Principles

1. Read-only on events. Progress never modifies the JSONL. It is a derived view.
2. Fast. One JSONL read + one markdown write. No jq streaming, no databases.
3. Decoupled. No hooks in archeflow-event.sh. The run skill calls progress explicitly.
4. Optional. If progress is never called, orchestration works fine. No side effects.
5. Terminal-friendly. Output is plain markdown — renders well in cat, bat, glow, or any terminal.