hm-l2-phase-execution

Files (7)

• SKILL.md
• evals.json · evals/
• rich-gate-scorecard.md · metrics/
• checkpoint-recovery.md · references/
• execution-state-template.md · references/
• wave-protocol.md · references/
• validate-skill.sh · scripts/

SKILL.md (first lines)

## Overview

Execute phase plans with wave-based parallelization and checkpoint recovery. Use when running multi-plan phases, managing plan dependencies, recovering from mid-phase interruptions, or coordinating parallel plan execution across sessions. Produces completed phase plans with per-task verification and atomic commits.

## The Iron Law

```
A phase is not a todo list. A phase is a directed acyclic graph of plans grouped into waves.
```

# Phase Execution
## On Load

1. Read `references/wave-protocol.md` — how to group plans into waves
2. Read `references/checkpoint-recovery.md` — mid-phase interruption recovery

## Phase Execution Protocol

## File-Backed Execution State Machine

Adapted from Nanostack conductor's claim/dependency/artifact/stale-lock pattern, but mapped to HiveMind/OpenCode project conventions. Use durable state files so a later agent can recover without trusting chat history.

| State artifact | Purpose | Notes |
|----------------|---------|-------|
| `.opencode/state/hivemind/phase-execution/<phase>/claims/<plan>.json` | Records active executor, started time, wave, dependencies | Atomic creation preferred; never overwrite another active claim without stale evidence |
| `.opencode/state/hivemind/phase-execution/<phase>/artifacts/<plan>.md` | Handoff summary, files changed, validations, blockers | Written before checkpoint or completion |
| `.opencode/state/hivemind/phase-execution/<phase>/done/<plan>.json` | Completion marker with verification evidence | Created only after plan verification passes |
| `.opencode/state/hivemind/phase-execution/<phase>/failures/<plan>.json` | Failure/blocker evidence | Blocks downstream waves until resolved |

Do not import `.nanostack/` paths. If the end-user project has a different state root, use it and document the adapter path in the artifact.

### Step 1: Load Plan Index

```bash
# Read phase plan index
ls .planning/phases/${PHASE}/
# Identify all PLAN.md files and their wave numbers
```

### Step 2: Validate Dependencies

```bash
# Check for circular dependencies
# Verify all depends_on references exist
# Confirm wave numbers are monotonic
```

**Gate:** If validation fails, STOP. Fix plans before executing.

### Step 2.5: Claim Runnable Plans

Before dispatching a plan in a wave, create a claim record with executor identity, command/session id if available, dependency list, and stale-after timestamp. If claim creation fails because another live executor owns it, skip that plan and report the owner. If a claim is stale, record the stale evidence before taking over.

### Step 3: Execute Wave by Wave

```
Wave 1: Plans with no dependencies → parallel dispatch
  → Wait for all to complete
  → Validate results
Wave 2: Plans depending on Wave 1 → parallel dispatch
  → Wait for all to complete
  → Validate results
...
Wave N: Final plans → parallel dispatch
  → Wait for all to complete
  → Final validation
```

### Step 4: Handle Failures

| Scenario | Action |
|----------|--------|
| Plan in wave fails | Abort subsequent waves; log failure; return DONE_WITH_CONCERNS |
| Plan returns BLOCKED | Escalate to orchestrator; do not proceed |
| Plan returns NEEDS_CONTEXT | Provide context; re-dispatch same plan |
| All plans succeed | Proceed to verification |

Every failure writes `failures/<plan>.json` with the failed command, output path, affected dependencies, and next recovery action. Never let a downstream wave consume a failed or missing upstream artifact.

### Step 5: Verify and Commit

```bash
# Run phase verification script if available
bash .planning/phases/${PHASE}/verify.sh 2>/dev/null

# Commit all changes with phase-scoped message
git add <phase-files>
git commit -m "phase: ${PHASE} — <summary>"
```

## Checkpoint Recovery

If interrupted mid-phase:

```bash
# Read phase state
.cat .planning/phases/${PHASE}/STATE.md 2>/dev/null

# Identify incomplete plans
# Re-execute only incomplete plans
# Do NOT re-execute completed plans
```

Recovery order:

1. Trust `done/*.json` markers with verification evidence.
2. Inspect `failures/*.json` and return blockers before executing downstream waves.
3. Inspect active claims; only resume/take over if the stale-after time has passed or the coordinator explicitly authorizes recovery.
4. Reconstruct missing artifacts from commits/files only when state markers are absent, and label reconstruction as degraded evidence.

## RICH Gate Source Decisions

| Source | Decision | Local adaptation |
|--------|----------|------------------|
| `garagon/nanostack` conductor | ADAPT | File-backed claims, dependency checks, artifacts, and stale-lock recovery mapped to `.opencode/state/hivemind/`. |
| `github/awesome-copilot` create-implementation-plan | ADAPT | Deterministic plan identifiers and measurable validation criteria are reinforced in wave artifacts. |
| GitHub agent skill resource model | ADAPT | State template and evals are bundled resources; SKILL.md remains the execution index. |

## Independence Notes

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin