hashharness-pm

Run N worker agents in parallel that drain the planning queue. Each worker loops: pull next task -> claim it (executing) -> do the work -> submit a report -> finish the task. Use when the user says "execute the plan", "run the queue", "spawn workers", or asks for parallel execution with a specific agent count.

Planning-board skill bundle for coordinating parallel coding agents with hashharness-backed append-only task, status, and report chains. Use this as the entry point to the bundled pm subskills under this directory, such as `plan`, `next`, `executing`, `report`, `finished`, `execute`, `replan`, `cancel`, `reclaim`, `sweep`, `dashboard`, `install`, `extract-steps`, and the `*-skill-execution` variants.

Cryptographic integrity attestation of a planning queue or the whole pm instance via hashharness `verify_work_package`. Re-checks every record's content hash, chain links, and schema binding across the queue's Task records plus each per-task TaskStatus / TaskReport / TaskHeartbeat chain — catching orphan records, tampered payloads, and `done` slipped in without proof. Unlike `verify_chain` (which followed a single named root), this covers every record in scope, closing the gap that pm's per-task chains have no common root. Use as a supervisor sweep before trusting a batch of agent output, or as a periodic integrity check.

Enqueue a new task on the planning board backed by hashharness. Creates an immutable Task record plus an initial TaskStatus(new). Supports subtasks (link to parent + parent's status at decision point) and dependency links to other tasks. Use when the user says "plan", "queue", "enqueue", "add task", or "create subtask".

Install the hashharness MCP backend that pm uses for its append-only storage. Bootstraps an isolated Python venv, installs hashharness from git, generates a launcher script and a source-able env file. Four install locations: ~/.hashharness/ (per-user, recommended), ~/.codex/hashharness/ (alongside Codex state), ~/.claude/hashharness/ (alongside Claude Code skills), or ./.hashharness/ (per-project at git root). Idempotent — re-running reports the existing install and exits 0. Use when a fresh workstation needs hashharness, when "pm setup" fails because no MCP server is reachable, or when you want a sandboxed second instance for testing.

Extract the major workflow steps from another skill's SKILL.md, with bash-side validation that every extracted step's anchor is verbatim in the source (catches LLM hallucination), and optional recursion into nested skill invocations (step X of skill A invoking skill B yields nested steps named `X.B.S1`, `X.B.S2`, ...). Two modes — llm (semantic, default when a supported LLM CLI is on PATH) and regex (pattern- matching fallback). Used internally by pm-auto-skill-execution, pm-assisted-skill-execution, pm-guided-skill-execution; also callable standalone for inspecting a skill's structure.

Mark a task as done (or rejected) on the planning board. Appends a terminal TaskStatus that links proof -> latest TaskReport on the task. Refuses if no TaskReport exists, enforcing "task to be finished requires proof of work/report". If the Task declares a verifier at plan time, this script runs it before allowing `done`. Use when an agent has submitted its final report and wants to close the task; pass --rejected to close as failed instead.

Drive another skill step-by-step through the planning queue, with the user in the loop at every gate. Extracts the target skill's steps from its SKILL.md, plans one task per step (chained by dependsOn), and executes them one at a time — pausing after each step to surface decisions, accept user-supplied subtask requests, and confirm before moving on. Use when the user says "guided run", "step through skill X", "drive skill X with user-in-the-loop", or asks for an execution that respects a skill's prescribed dialogue gates.

Drive another skill through the planning queue with a "default + escalate" policy: routine gates pick the documented default and continue silently (like auto), but gates the skill marks critical or where no default exists pause and ask the user (like guided) — and never auto-reject a step just because a decision is required. Use when you want hands-off batch progress on the easy parts but real human input on the hard ones, especially for partially-understood skills or runs where some inputs only the user knows.

Drive another skill end-to-end through the planning queue without user dialogue. Extracts the target skill's steps from its SKILL.md, plans one task per step (chained by dependsOn), and executes them sequentially — picking the documented default for every choice the skill would normally ask the user about, recording the choice + reasoning in each task report. Use when the user says "auto-run skill X", "execute skill X without prompts", or wants a hands-off application of a well-understood skill.

Return the next runnable planning task as JSON, or "null" if the queue is empty / blocked. A task is runnable when its current TaskStatus is "new", every task in its dependsOn list has status "done", and (if it has a parentTask) the parent's status is non-"new" — i.e. the parent's lifecycle has begun. Parents must be claimed before their children; the rollup-after-children invariant is enforced at finish-time, not next-time. Use when the user says "next task", "what's next", "pull next", or before spawning a worker.

Cancel a task as a supervisor or planner override. Writes a synthetic TaskReport carrying the cancel reason, then appends a terminal TaskStatus(rejected, cancelled=true) linked to that proof. Use when a task should be stopped regardless of current ownership, or when a parent task's cancellation should cascade into unfinished subtasks.

Claim a task for execution. Appends a TaskStatus(working) chained to the previous status of that task. Refuses if the task is not currently in state "new" (prevents two workers claiming the same task). Use when an agent picks up a task returned by pm:next.

Replan a task — restart it (and by default all its dependency-chain ancestors) so a fresh worker can pick the chain up from the start. Use when a task was interrupted, rejected, or completed-but-wrong, especially when the user says "replan", "restart from", "redo this", "start over", or "the chain was broken — try again". Supports body/verifier adjustments to the target via --text / --verifier.

Start a minimal HTTP dashboard showing the planning board's current state — workdirs grouped by queue, with task trees (parent/subtask hierarchy via parentTask), each task's status, owner, sticky binding, verifier, and dep count. Stdlib-only Python; no JS, no external deps. Use when you want a live view of a hashharness-pm instance ("show me what's queued / working / stuck"), or a JSON endpoint to scrape from another tool.

Force-reclaim a stuck working task — append TaskStatus(new, reclaimed=true) so a fresh worker can pick it up. Supervisor / human override; refuses if the task isn't currently working. With --cascade also reclaims every working descendant via parentTask reverse-links. Use when a worker died holding a claim (and you don't want to wait for sweep TTL), or when a sticky chain's session needs to be released as a subtree.

Append a TaskHeartbeat for a task currently in working phase. Workers call this periodically to signal they're still alive on a claim; sweep uses heartbeat freshness to detect dead claimants. Refuses if the task isn't working (exit 6) or if the current working status is owned by a different agent (exit 12 — lease lost). Use from a worker loop while holding a claim, on an interval shorter than the configured sweep TTL.

Scan a queue for zombie tasks (working but stale) and reclaim them. A task is stale when its last activity (latest TaskStatus / TaskReport / TaskHeartbeat by created_at) is older than --ttl seconds. Each reclaim is race-safe against a still-live worker via a preempt heartbeat (chain_predecessor on prevHeartbeat). Use when a queue has been running long enough that some workers may have died holding working leases, or as a periodic supervisor task.

Append a TaskReport (proof of work / progress note) to a task. Reports are immutable and chained: each new report links prevReport to the previous one. A report is required before pm:finished will accept the task. Use when an agent finishes its work and produces output, or when capturing partial progress mid-execution.