hyper-implement

Plan execution gate. Reads a plan, dispatches a fresh subagent per task, runs two reviews (spec compliance, then code quality) before marking each task complete. Uses our own agents (implementer, verifier) and our own gate skills.

When to use

• User typed /hyperclaude:hyper-implement [path].
• A multi-task plan exists (typically in .hyperclaude/plans/) and you're about to execute it.

Skip when:

• The plan is one step — just do it directly.
• Tasks are tightly coupled and benefit from shared context.
• You're prototyping; reviews are overhead at this stage.

How to invoke

Invocation argument: $ARGUMENTS

Step 1 — Resolve the plan path

In priority order:

1. If $ARGUMENTS is non-empty, treat it as a path and use it.
2. Else, find the most recent plan via the Bash tool:

   ls -1t .hyperclaude/plans/*.md 2>/dev/null | head -1

1. If nothing found, tell the user: "No plan file found. Write your plan to .hyperclaude/plans/<slug>.md first." Stop.

Step 1.5 — Reject epic roadmaps

Read the resolved plan's opening lines. If the file begins with a YAML frontmatter block containing tier: epic, it is an epic roadmap, not an executable task plan (hyper-plan emits these for oversized tasks, under .hyperclaude/epics/). STOP before any branch or git work and tell the user, substituting the resolved roadmap path into the command: "This is an epic roadmap (tier: epic), not an executable task plan. Expand a milestone into a detailed plan first — /hyperclaude:hyper-plan <this roadmap's path> milestone <K> (K is one of the ## Milestone N: entries in this roadmap; passing the path targets THIS epic — omitting it auto-picks the newest roadmap instead, which may be a different file) — then run hyper-implement on that detailed plan." Plans without tier: epic frontmatter (all detailed plans, including the auto-expanded Milestone-1 plan) proceed normally — a detailed plan may carry a hook-stamped plugin-version frontmatter block, but that is not tier: epic, so it is not a roadmap and proceeds. Roadmaps live in .hyperclaude/epics/, not .hyperclaude/plans/, so the newest-plan auto-pick in Step 1 never selects one — this guard only fires when a roadmap path is passed explicitly.

Step 2 — Parse and track

Read the plan with the Read tool. Extract every ## Task N: <title> section with its full text — files-to-create/modify, step-by-step checkboxes, verification commands, commit message.

Track progress in the plan file itself — step 3.5 marks each task's checkboxes - [x] as it completes. That file is the only progress record the loop keeps, so it survives context loss.

Step 2.5 — Clean-tree preflight, then create / switch to the feature branch

Clean-tree preflight (do this FIRST). Per-task commits use git add -A (step 3.6), so the working tree MUST be clean before the loop starts — otherwise pre-existing unrelated edits or untracked files (including local secrets) get swept into the first task's commit. Check:

git status --porcelain

If the output is non-empty (any tracked modification or non-ignored untracked file — .hyperclaude/ is gitignored and never appears, so it's exempt), STOP and tell the user: "Working tree is not clean. hyper-implement commits per task with git add -A; commit, stash, or clean the unrelated changes first, then re-run." Do not branch, do not start the loop. This preflight is what makes per-task git add -A provably scoped: each task starts from a clean tree, so everything added during the task (implementer output + spec/quality fix-loop edits) is exactly that task's work, and the task commit returns the tree to clean for the next task.

Per-task commits never land on the default branch — hyper-implement always commits on a feature branch.

Derive the slug from the plan filename: strip the <YYYYMMDD-HHMM>- timestamp prefix and the .md suffix (e.g. 20260517-1946-hyper-implement-code-review-reviser.md → hyper-implement-code-review-reviser). If the filename has no timestamp prefix, use the basename without .md.

Find the current branch and act on it:

git rev-parse --abbrev-ref HEAD

• Current branch is main or master (the default branch — protected) → create or switch to hyper/<slug>:

  git switch -c "hyper/<slug>" 2>/dev/null || git switch "hyper/<slug>"

(-c creates it from the current HEAD; the || fallback switches to it if it already exists — a resumed run reuses the same branch.)

• Already on a non-default branch → stay on it; the user pre-selected a working branch and per-task commits land there. Do NOT create a nested branch.

Tell the user which branch per-task commits will land on. Never push the branch — push stays a user action (see Step 4 / Rules).

Step 3 — Per-task loop

For EACH task in order:

1. Implementer. Dispatch via the Agent tool. Prefer subagent_type: hyperclaude:implementer, `run_in_background: false` (spec review in Step 3.2 gates on this result). Prompt MUST include:

• The full task text (paste it; do not make the subagent re-read the plan file).
• Project context: where this fits, recent commits, base SHA before this task.
• Global constraints from the plan's preamble (zero deps, sandbox invariant, naming traps, etc.).
• A self-review checklist before reporting back.
• Expected report format: status (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT), files changed, test counts. (No commit SHA — the implementer never commits; the lead commits in step 6 after both reviews pass and records the SHA.)

1. Spec compliance review. Once implementer reports DONE, dispatch a fresh general-purpose subagent (NOT the verifier — verifier runs tests, doesn't compare to spec), `run_in_background: false` (its verdict gates the fix loop and Step 3.3). Prompt:

• The full task text.
• The implementer's report (verbatim).
• The git SHA range (<base>..<head>).
• Instruction: read the actual code; don't trust the report. Look for missing requirements AND unrequested extras.
• Expected outcome: ✅ compliant, or ❌ with specific file:line issues.

If issues found → re-dispatch the implementer with the fix list, `run_in_background: false` (synchronous so re-review sees the fixed tree) → re-review. Loop until ✅.

1. Code quality review. After spec ✅, dispatch another fresh general-purpose subagent, `run_in_background: false` (its approval gates the commit in Step 3.6). Focus on:

• Clarity (names, decomposition, file responsibility).
• Test quality (do tests verify behavior, not types?).
• YAGNI (any unrequested abstractions or features?).
• Consistency with existing codebase style.
• Severity-tagged issues: Critical / Important / Minor.

Loop until reviewer approves (Minor-only is acceptable; Critical/Important must be fixed).

1. Verifier — when tests or build steps changed. If the task added or modified test files (tests/**, *.test.*, *.spec.*) or build/CI configuration (package.json scripts, smoke script, CI workflow), dispatch subagent_type: hyperclaude:verifier, `run_in_background: false` (its PASS/FAIL gates the commit). Verifier runs the project's tests, build, and lint and reports PASS / PARTIAL / FAIL with verbatim output. Verifier never modifies files. Skip the verifier when the task didn't touch tests or build inputs — the spec/quality reviews above already cover code correctness.

1. Mark the task's step checkboxes as `- [x]` in the plan file. After both reviews approve, use the Edit tool to convert every - [ ] inside the current ## Task N: <title> block to - [x]. Scope is the task block only — leave other tasks' boxes alone. This keeps the plan file's checkbox state the durable source of "what's done" — survives context loss and lets a resumed session see exactly which tasks remain. Do this BEFORE the commit so the durable artifact lands first.

1. Commit the task (the lead commits — never the implementer). Only after spec ✅ + quality ✅ (+ verifier PASS when it ran):

Stage, then check whether anything was staged, then commit only if so:

   git add -A
   git diff --cached --quiet && echo "SKIP: nothing staged" || git commit -m "<task commit message>"

• Message: the task block's Commit message line (one-line conventional-commits, emitted by the planner). If the block has none, synthesize a conventional subject from the task title (defensive only — the planner always emits one).
• `git add -A` is intentional and safe here because Step 2.5's clean-tree preflight guaranteed the tree held no unrelated work when the loop started: each task begins from a clean tree, so the entire current diff is exactly this task's work (implementer + fix-loop edits). .hyperclaude/ is gitignored, so plan-file checkbox edits and run artifacts never sweep in. (This is the documented exception to CLAUDE.md's "don't blanket git add -A", which is scoped to the release commit on main.)
• Nothing staged (git diff --cached --quiet exits 0 → no diff, e.g. a pure-verification task) → skip the commit, note "Task N: no file changes — no commit" in the run summary, continue.
• Record the resulting commit SHA (git rev-parse HEAD) for the final summary.
• Never push. Never tag here (tags only per Step 4, still user-pushed).

1. Move on to the next task.

Step 4 — Final pass

After all tasks:

• All tasks are now committed on the feature branch (one commit per task, minus skipped no-change tasks). Run the final acceptance — the plan's own, else the project's full test suite — and confirm 0 failures.
• If /hyperclaude:hyper-code-review is available, run it for a Codex-side review of the entire diff. Useful catch for cross-task issues.
• If the plan's final task includes a tag step (git tag -a vX.Y.Z), do NOT push it; leave that to the user.
• Archive the plan when implementation is complete. "Complete" = every task block executed (committed or skipped-no-change) AND the final acceptance above passed. This is the plan-implemented signal — it does NOT depend on the optional code-review's findings (a code review is downstream hardening; its findings are bug-fix work on already-implemented code, not plan-implementation state) and is NOT the plan's checkbox count (audit / no-op tasks never get a - [x], so a fully-executed plan can still show unchecked boxes). This applies to nested runs too: when hyper-implement-loop invokes this skill the plan is still archived here at implementation completion — the loop's later review/fix rounds operate on already-implemented code and never re-read the plan. Archive only a canonical plan — resolved path is a direct child of .hyperclaude/plans/; an explicit $ARGUMENTS path elsewhere is left untouched (moving it would be destructive and would violate the "only plans/ is archived" contract). Use a plain mv (.hyperclaude/ is gitignored, so git mv fails):

  plan="<resolved plan path>"
  plans_dir=$(cd .hyperclaude/plans 2>/dev/null && pwd)
  plan_parent=$(cd "$(dirname "$plan")" 2>/dev/null && pwd)
  if [ -n "$plans_dir" ] && [ "$plan_parent" = "$plans_dir" ]; then
    mkdir -p .hyperclaude/plans/done && mv "$plan" .hyperclaude/plans/done/
  else
    echo "Plan is not a direct child of .hyperclaude/plans/ — left in place, not archived."
  fi

The guard compares resolved parent dirs, so a path under plans/done/ or plans/<subdir>/ (or any external dir) is left alone — only a true .hyperclaude/plans/<file>.md plan moves. Both the Step 1 newest-plan auto-pick (*.md is non-recursive) and the SessionStart snapshot ignore the done/ subdir for free, so an executed plan stops being surfaced as the "Active plan". Skip the archive on any early STOP before completion (BLOCKED, ambiguity, red acceptance) — leave the plan in .hyperclaude/plans/ so a resumed run can pick it up. Only plans/ is archived; research/ and *-reviews/ stay put (the snapshot shows newest-only, and --resume depends on prior review artifacts remaining in place).

• Report the feature branch name, the per-task commit SHAs (and any "no file changes" skips), and the archived plan path. Do NOT push the branch — pushing stays a user action.

Rules

• Fresh subagent per task. Don't reuse implementer subagents across tasks — context pollution kills focus.
• Two reviews per task. Spec compliance FIRST (catches scope drift), then code quality (catches style/clarity). Skipping either means you'll ship bugs.
• Don't trust implementer self-reports. Reviewers must read the actual code.
• Fix loops are mandatory. Reviewer ❌ → implementer fixes → re-review. No "close enough."
• Continuous execution. Don't pause to ask the user between tasks — execute the whole plan. Stop only on BLOCKED, genuine ambiguity, or all tasks done.
• The lead commits, not the implementer. Per-task commit happens in Step 3.6 after both reviews pass — never inside the implementer subagent (it stays commit-free per agents/implementer.md).
• Feature branch, never the default branch. Step 2.5 creates/uses hyper/<slug> when on main/master; per-task commits never land on the protected default branch.
• Never push. Branch creation, per-task commits, and any tag are all LOCAL. Pushes are user actions. The skill creates a tag locally only if the plan says to.

Anti-patterns

• Using verifier agent for code review. Wrong role — verifier runs tests, doesn't critique code.
• Skipping spec compliance review because "the plan was clear." It never is.
• Single subagent handling multiple tasks (the whole reason we don't do manual orchestration).
• Marking a task complete with reviewer issues still open.
• Committing a task before both reviews pass, letting the implementer commit, or committing on the default branch.
• Pushing the feature branch or pushing a tag. Everything this skill does is local.
• Following the implementer's own model selection. Pick model per task complexity at dispatch time:
• Mechanical (1-2 files, exact spec): haiku
• Standard (multi-file, integration): sonnet
• Architectural / judgment-heavy: opus

Apply the SAME tier to the spec / quality reviewer dispatches in Step 3.2 and 3.3. They're general-purpose subagents that otherwise inherit the lead's model, which over-pays on mechanical / standard tasks. Pass model: on the Agent call to match the implementer tier you just chose. Verifier (Step 3.4) stays on its frontmatter default — no override.