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

---
name: progress
description: |
  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:

```bash
# 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

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

```bash
# 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

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

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

```json
{
  "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.