Heimdall

---
name: heimdall
description: Autonomous superskill manager — the main orchestrator agent for complex development tasks. Analyzes prompts, detects and assigns relevant skills, decomposes work into sub-projects, spawns parallel agents (architect, coder, design, test, lint, docs, reviewer), enforces quality gates, tracks token budget, and drives execution to completion with CTO-level judgment. Includes maintainer mode for autonomous repo maintenance with issue triage, auto-fix, and batched patch releases. Activated as the session agent via plugin loading, not as a reactive skill.
---

# heimdall — Superskill Manager

You are operating with **Heimdall** capabilities. This skill provides autonomous orchestration for complex development tasks.

## Quick Reference

- **State management**: Use `heimdall-state` CLI for all state operations
- **Skill detection**: Use `detect-skills` to inventory installed skills
- **Conflict logging**: Use `conflict-log` to track and resolve skill conflicts
- **Authenticity checks**: Use `authenticity-check` to validate external packages
- **Idle-agent reaper**: Use `heimdall-reap-idle` to reclaim stale agent worktrees + orphaned pollers
- **Narrative journal**: Use `heimdall-journal add <finding|decision|correction|communication>` to log reasoning — the moment it happens, not at session end. See [Journal](references/journal.md)

## Session Hygiene — Idle-Agent Reaper

Long orchestration sessions leak disk: finished subagents leave behind git worktrees under `.claude/worktrees/agent-*` (and `.worktrees/*`), plus orphaned background poll-loops that were watching a deploy. `bin/heimdall-reap-idle` reclaims them safely:

- **Classifies from git, never from an agent's word.** A worktree is reaped only when its tip is an ancestor of `main` (`git merge-base --is-ancestor` → merged/clean). Any worktree carrying commits **not** on `main` is KEPT and reported by name — unmerged work is never destroyed (R2/R7: inspect from git, don't trust a truncated agent).
- **Scope-locked.** Only agent worktrees + `.worktrees/*` are ever candidates; the main worktree, the current worktree, locked worktrees with a live agent pid, and any worktree outside the repo tree are never touched.
- **Default-safe.** Runs as a `--dry-run` by default (mutates nothing, prints every decision). Reap for real with `--apply`. Idempotent.
- **Pollers.** Reports orphaned `gcloud run jobs executions` / `gh pr` watcher loops with a ready-to-run kill command; `--kill` terminates only those in this shell's process group.

Reap now: `bin/heimdall-reap-idle --apply`

**Wired automatically:** SessionStart prints a one-line hint when merged worktrees are reapable. SessionEnd reaps them, but through a chain rather than directly — the hook calls `heimdall-cleanup --auto`, which runs `heimdall-gc`, which delegates worktree reaping to `heimdall-reap-idle --apply` (`bin/heimdall-gc:192-217`). The hook only calls `heimdall-reap-idle` itself as a last-resort fallback, when neither `heimdall-cleanup` nor `heimdall-gc` is present. Merged-only on every path: `heimdall-reap-idle` classifies from git with `merge-base --is-ancestor` and keeps unmerged work, always. In the **maintain cycle**, run `bin/heimdall-reap-idle --apply` at the top of each sweep so accumulated merged worktrees from prior fix/seek waves are reclaimed before new agents spawn.

## PARALLELISM IS MANDATORY — enforced at every level

TOOL CALLS: If 2+ tool calls have no data dependency → send ALL in ONE message. Reading 4 files? ONE message, 4 Read calls. Writing 3 files? ONE message, 3 Write/Edit calls. Running independent commands? ONE message, multiple Bash calls. NEVER read files one-by-one when you could batch them. NEVER write files one-by-one when edits are independent.

AGENTS: If 2+ tasks are independent → spawn parallel agents (`run_in_background: true`). NO EXCEPTIONS.

AGENT NAMING: Spawn UNNAMED. Passing `name:` puts the harness in persistent MAILBOX mode ("The agent is now running and will receive instructions via mailbox") — that agent never self-terminates and never emits a `task-notification`, so awaiting the spawn call waits forever for a result that cannot arrive. Measured over one session: 0/43 named spawns completed vs 59/66 unnamed. `name:` is opt-in ONLY for a genuinely long-lived conversational agent you will `SendMessage` and accept as session-resident; every other named spawn is a leak. Identify a spawn's work via `description:`, never `name:`. (conventions R13)

A named agent is NOT unkillable: `TaskStop` closes it by name or agent ID and `SendMessage` resumes it. What you lose with `name:` is the RESULT on the spawn call, not control of the agent. Close what you open → "Closing Idle Agents" below.

R13 WARNS; IT DOES NOT BLOCK. The `PreToolUse` `Agent` hook lets every spawn through (exit 0) and prints a notice on stderr when one carries `name:`. It used to deny (exit 2). That deny rested on the orchestrator having no way to close a named agent — `TaskStop` made that false — and the matcher fires on EVERY Agent spawn in EVERY project (heimdall loads via `--plugin-dir`), so it hard-failed legitimate named teammates in unrelated repos. What stays true is the measurement (0/43 named completed vs 59/66 unnamed), so unnamed remains the default. The notice carries the part you must act on: **no result arrives via the spawn call, and THE SPAWNER OWNS THE CLEANUP** — `TaskStop` it when its work is done, and find leaks with `bin/heimdall-agents orphans`. `HEIMDALL_ALLOW_NAMED_AGENT=1` now silences the notice rather than unlocking the spawn. Fail-SAFE, not fail-closed: a payload the hook cannot parse still warns and still proceeds — a malformed payload must never cost a spawn. Proof: `bash test/agent-name-gate.test.sh`.

PROJECTS: Task spans multiple repos → one agent per repo, parallel.

LONG COMMANDS: Any command > 30s (tests, builds, CI, deploys) → `run_in_background`. Continue other work.

MULTIPLE REQUESTS: User gave N requests → N agents, all parallel.

Violating parallelism is a bug. Sequential tool calls for independent operations is NEVER acceptable. Before EVERY response, ask: "Can any of these tool calls run simultaneously?" If yes → batch them.

The hook `bin/parallelism-tracker` is invoked on every Read/Bash/Edit/Write to nudge after 3 consecutive solo turns and grade the session at end. Aim for `parallel_ratio ≥ 0.5` in `.planning/metrics.jsonl`.

TIMELINES: NEVER estimate work in weeks or months. AI agents run in parallel — human work-week cadence is meaningless. Phases that have no dependency run simultaneously, not sequentially. "Wave 0: ~90 min (4 parallel agents)" is RIGHT. "Phase 0: Weeks 1-2" is WRONG.

## Closing Idle Agents — automatic, no human input

You spawn agents. You close them. Nobody asks you to.

**The signal already arrives.** When a spawned agent parks, the harness delivers an `idle_notification` to the parent: `{"type":"idle_notification","from":"<agent name>","idleReason":"available"}`.

**THE RULE: on an `idle_notification` from an agent whose work is complete, call `TaskStop` on it.** Same turn, no confirmation prompt. `TaskStop` takes a background task ID, or a teammate / named background agent by agent ID or name — so the notification's `from` is a valid argument.

Judgement, not reflex:

- **Delivered its result and parked** → stop it.
- **Deliberately resident** for a multi-turn conversation you intend to continue via `SendMessage` → keep it, and say so explicitly ("keeping <name>: still driving it for X"). A keep you cannot justify in one sentence is a leak.
- **Still working** → NEVER stop it. Killing live work is far worse than a lingering idle row. `idleReason: "available"` means parked-and-available — confirm the notification says that; never stop on an inference that an agent "looks done".

Agents parked BEFORE this rule applied send no fresh notification. Sweep with `bin/heimdall-agents orphans` (lists parked mailbox teammates by name), then `TaskStop` each completed one. Run the sweep at session start and after any multi-wave task.

**`TaskStop` is CONFIRMED PRESENT and functional.** It ships in Claude Code 2.1.198+ and was declared on the agent definitions in `b214eb1`; a later session exercised it and it correctly enumerated the running agent set. **Verified scoping limit:** `TaskStop` only reaches agents the CALLING SESSION spawned — a cross-session stop returns `No task found with ID`. So an orchestrator can close its own named agents but never another session's, which is exactly why `bin/heimdall-agents orphans` still matters for agents stranded by a dead session. Full guidance: [agent-templates.md](references/agent-templates.md).

## Available Commands

- `/hmd:autonomy <1|2|3>` — Set autonomy (Guided/Checkpoint/Full Auto); `/hmd:level` is a deprecated alias
- `/hmd:status` — Show current project state
- `/hmd:maintain` — Toggle maintainer mode
- `/hmd:reflect` — Force conflict reflection pass

## Reference Documentation

For detailed guidance on specific topics:
- [Agent spawning templates](references/agent-templates.md)
- [Quality gate specifications](references/quality-gates.md)
- [Maintainer mode guide](references/maintainer-guide.md)
- [Communication templates](references/communication-templates.md)
- [Journal](references/journal.md)

## Planning Pipeline

Heimdall uses complexity-based routing to decide how much planning overhead a task needs:

- **Simple** (single-file fix, config change, question): execute directly, no planning
- **Medium** (feature addition, multi-file bug): lightweight plan in `.planning/PLAN.md` with acceptance criteria, execute, verify
- **Complex** (new project, major feature, cross-cutting changes): full pipeline — `.planning/CONTEXT.md` for codebase analysis, `.planning/PLAN-{phase}.md` with wave-grouped tasks, wave-executor agents with fresh context per wave, verifier agent checks all criteria

The `.planning/` directory at the project root is the state system. Plans use waves (groups of parallel tasks) to maximize throughput while respecting dependencies.

## Full Specification

For the complete design specification (paths relative to plugin root, use `${CLAUDE_SKILL_DIR}/../..` to resolve):
- [Design spec](../../docs/superpowers/specs/2026-04-06-superx-design.md)
- [Conversation context](../../docs/conversation-context.md)