hitl.md

name	hitl
description	Resume work after the user has hand-edited the codebase — treat their commits as frozen ground truth and stitch the rest of the work around them

The user just took the wheel. After a stretch of agent-driven commits, they made their own commits to nudge the codebase toward what they actually want. Now they're handing it back. Your job: read what they changed, treat it as the new source of truth, and finish the work around it.

Mental model

• The user's HITL commits are the spec. They corrected something — direction, taste, naming, structure, behavior. That correction is now load-bearing.
• The agent commits before HITL are drafts. They are negotiable. If they conflict with the user's edits, the user's edits win.
• Your job is to make the whole branch coherent with the HITL commits as anchors. Not to re-do the work, not to re-litigate it.

Phase 1 — Find the HITL commits

Search the branch's commit history (since it diverged from the base branch) for HITL markers. Match liberally — case-insensitive, in subject or body:

• HITL, hitl, HITL phase, HITL: …, (hitl), [hitl], human-in-the-loop, etc.

Commands:

git merge-base HEAD origin/main          # or the actual base branch
git log <base>..HEAD --oneline
git log <base>..HEAD --grep='hitl' -i    # also try '--grep=human-in-the-loop' -i

If you find zero HITL commits: stop and ask the user which commits they consider the human-edited ones. Do not guess from diffs alone.

If you find some: list them back to the user in one line each (<sha> <subject>) so they can confirm before you proceed. Keep this brief.

Phase 2 — Read the HITL commits in full

For each HITL commit:

1. git show <sha> — read the full diff and the message.
2. Note what changed and why (the message often hints at intent).
3. Note what is now frozen: file regions, naming, signatures, structure, behavior choices.

Build a mental list of frozen anchors. These are the constraints for the rest of the work.

Phase 3 — Diagnose the gap

Compare:

• The state of the branch as of the last HITL commit (the user's intended direction).
• The state of the branch at HEAD (which may equal the last HITL commit, or have agent commits after it).
• What the original task/plan was trying to achieve (read recent non-HITL commit messages and any plan/PRD context the conversation provides).

Identify what's left to do so the branch lands in a coherent, finished state that respects the HITL anchors. Examples of typical gaps:

• The user renamed a concept; call sites elsewhere still use the old name.
• The user simplified a component; downstream code still expects the old API.
• The user removed a layer; tests or types still reference it.
• The user reshaped data; serialization, validation, or storage didn't follow.
• The user's edits exposed an inconsistency in a sibling module that was never updated.

Phase 4 — The freeze rule

HITL commits are frozen. You may not revert, undo, or "fix" what the user did inside them, even if you think it's wrong, suboptimal, or inconsistent.

The only exception is a major technical blocker: the HITL change makes something genuinely impossible (won't compile, breaks an invariant the runtime requires, contradicts another HITL change, etc.). In that case:

• Stop. Do not modify the HITL commit's content.
• Surface the blocker to the user with a precise description of what conflicts and why.
• Propose options. Let the user choose.

Taste, style, and "I'd have done it differently" are not blockers. Adapt the surrounding code to fit.

Phase 5 — Stitch

Make the rest of the codebase coherent with the frozen anchors. Be proactive:

• Update call sites, types, tests, fixtures, translations, and docs to match the HITL shape.
• Drop or rewrite agent-era code that is now redundant or contradicted.
• If an agent commit before HITL is now dead code, remove it cleanly rather than leaving it stranded.
• Keep the public surface (exports, routes, schemas) consistent with what the HITL commits imply.

Use the conventions from the project's CLAUDE.md (lint, format, naming, commit style). Match them — don't introduce a new style.

Phase 6 — When to ask

Default to acting. Only ask the user when there's a genuine fork in the road that the HITL commits don't resolve and that materially changes the outcome. Examples worth asking:

• Two HITL commits imply different directions and you can't tell which to favor.
• A frozen anchor forces a choice with visible product impact (e.g. a removed field is referenced by an external consumer).
• The remaining work could be scoped narrowly (just stitch) or broadly (also redo adjacent agent work) — and the answer changes meaningfully.

Don't ask:

• Naming nits, formatting, file placement, import order.
• "Should I update the tests?" — yes, always.
• "Should I keep this old code?" — if it's contradicted by HITL, no.
• Anything you can verify by reading the code or running a check.

When you do ask, batch questions into one short message. Don't drip-feed.

Phase 7 — Verify

Before declaring done, run the project's standard checks (typecheck, lint, test — detect from CLAUDE.md and package.json the way /ship-it does). Fix what you broke; surface unrelated pre-existing failures.

Phase 8 — Report

One concise message to the user:

• Which commits you treated as HITL anchors.
• What you stitched (one line per area touched).
• Anything you deliberately did not change because it was frozen.
• Any blockers you hit, if any.

Then stop. Do not push or open a PR — that's /ship-it's job.

Red flags — STOP if you catch yourself thinking any of these

Thought	Reality
"The user's HITL change is wrong, let me fix it"	Frozen. Adapt around it.
"I'll just revert this HITL commit and redo it cleaner"	Never. New commits only, around the anchors.
"I'll ask the user to confirm each small adaptation"	Be proactive. Ask only at genuine forks.
"The agent commits before HITL look fine, I'll keep them as-is"	Check whether HITL contradicts them. If so, rewrite them.
"I'll just match the HITL style and not touch the rest"	Stitching means making the whole branch coherent, not just the diff.
"Tests are failing because of HITL, the user should fix that"	No — the user's edits are the spec; you fix the tests to match.

ship-it.md

name	ship-it
description	Finalize the current branch — commit pending work, run repo checks, push, and open a PR with automerge

The user is signalling that the codebase is in a good state and wants to ship the current branch. Your job: commit any pending work, run all checks the repo expects, then push and open a PR.

Trust the user that the code is good. Do not second-guess the work itself. Do not run /review, do not refactor, do not "improve" anything. Your job is the finish line, not the race.

Rules of engagement

• No confirmation gates between phases as long as checks pass. Once you start, drive through commit → checks → push → PR without asking.
• Split commits by concern, using your judgment. Group changes that belong together; separate unrelated changes. Use Conventional Commits prefixes (feat:, fix:, chore:, refactor:, docs:) to match each commit's intent. Never amend. The PR will be squashed on merge, so don't fret over micro-tidiness, but don't lump unrelated changes either.
• On lint/format failure: auto-fix without asking. Run the available autofix (--fix, --write). If autofix succeeds, commit the result as a new commit and continue. If autofix fails (errors remain, or the autofix command itself errors), stop and surface the output to the user.
• On any other check failure (typecheck, test, build): stop and ask. Do not attempt fixes without explicit approval.
• Auto-detect what to run. Don't hardcode commands.

Phase 1 — Detect what checks this repo expects

Look in this order, stop once you have a clear answer:

1. Root CLAUDE.md — search for "pre-push", "pre-commit", "checks", "before pushing", "lint", "test". Quote the section back to yourself. If it lists explicit commands, those are the source of truth.
2. Nearest workspace CLAUDE.md for any modified file — workspace-specific rules can override root.
3. package.json scripts of affected workspaces — look for lint, format, typecheck, test, check, ci. In a pnpm/turbo monorepo, prefer the root-level filtered command (e.g. pnpm --filter='...[origin/main]...' --parallel --if-present <script>).
4. CI config (.github/workflows/*.yml, .gitlab-ci.yml, etc.) — last resort, mirror what CI runs.

State the detected check list to the user in one sentence before running anything: "Detected checks: lint, format, typecheck, test (per CLAUDE.md). Running now."

Phase 2 — Format and lint BEFORE staging

If the repo has an autoformatter that modifies files (format --write, prettier --write, oxfmt --write, gofmt -w, etc.), run it first, before any git add. This avoids re-staging churn.

Do the same for autofixable lint if the repo's convention runs lint with --fix. If lint is run without --fix (i.e. report-only), defer it to Phase 4.

Phase 3 — Commit

1. git status and git diff (staged + unstaged) to see everything pending.
2. Read each untracked file briefly to confirm it's intentional (not a stray scratch file, lockfile, or secret). Skip binaries.
3. Match the style of recent git log --oneline -10 for commit message format.
4. Group changes into commits by concern. Examples:
   • Feature code + its tests → one feat: commit.
   • Unrelated tooling/config tweak → its own chore: commit.
   • A bugfix in a different area → its own fix: commit. When in doubt, keep things together — don't make trivial commits just to split.
5. Never git add -A or git add . — list paths explicitly. Skip anything that looks like secrets (.env*, credentials*, key files), build artifacts, or node_modules.
6. If a Co-Authored-By: trailer is conventional in this repo (check recent commits), include it.
7. Commit using a HEREDOC for clean formatting. Never amend; always create new commits.
8. If there are no pending changes, skip Phase 3 entirely — go straight to checks on the existing branch state.

Phase 4 — Run checks

Run the detected checks. Run independent checks in parallel. Surface output verbatim on failure.

On lint or format failure:

• Run the autofix variant immediately, no confirmation needed (pnpm lint --fix, pnpm format --write, prettier --write, eslint --fix, gofmt -w, ruff check --fix, etc.).
• If the autofix command errors out, or if errors remain after it runs, stop and surface the output to the user.
• If the autofix succeeds and the working tree changed, create a new commit (chore: apply lint autofix or chore: format) and re-run all checks from the top.
• If the autofix succeeds with no changes, just continue.

On typecheck, test, or build failure:

• Stop. Do not push. Do not open a PR.
• Surface the output to the user and ask how to proceed. Do not attempt a fix without explicit approval.

Pre-existing failures unrelated to the branch: if a test was already failing on main, surface it and ask the user whether to ship anyway. Do not silently push past red.

Phase 5 — Push

Once all checks are green:

• If the branch has an upstream: git push.
• If not: git push -u origin <branch>.
• Do not force-push. If push is rejected, stop and ask.

Phase 6 — Open the PR

1. Determine the base branch (usually main, but check git symbolic-ref refs/remotes/origin/HEAD or the repo's default).

2. Title: derive from the branch's commits (git log <base>..HEAD --oneline). Keep under 70 chars. Use the dominant Conventional Commits prefix.

3. Body: generate from git log <base>..HEAD and git diff <base>...HEAD --stat. Use the repo's PR template if .github/pull_request_template.md exists; otherwise:

   ## Summary
   <1-3 bullets describing what changed and why, derived from commits/diff>
   
   ## Test plan
   - [ ] <derived from the changes — what should a reviewer verify?>
   

4. Create the PR with gh pr create --title "..." --body "$(cat <<'EOF' ... EOF)".

5. Enable automerge: gh pr merge --auto --squash.

6. Add the no-deployment label only if the PR clearly requires no deployment for review (e.g. docs-only, dev-tooling-only). When in doubt, skip it.

Phase 7 — Report

One concise message to the user with:

• The PR URL
• The detected checks that ran
• Anything notable (skipped tests, pre-existing failures the user approved, autofixes applied)

Edge cases

• gh not installed or not authenticated: do the push, then stop and tell the user. Don't try to install it.
• No remote / no origin: stop after the commit. Tell the user; don't guess a remote.
• Detached HEAD or on main/master: stop immediately. Ask the user what branch to ship from.
• Diff vastly exceeds ~1500 lines: surface this once, then proceed if the user confirms; don't auto-split.
• Merge conflicts with base: stop. Ask the user to resolve; don't auto-rebase.

Red flags — STOP if you catch yourself thinking any of these

Thought	Reality
"I'll fix this typecheck/test error real quick"	Ask first. Lint/format autofix is the only auto-allowed fix.
"I'll lump unrelated changes into one commit, it'll squash anyway"	Split by concern. The PR squashes; intermediate commits are still readable history during review.
"I'll amend the previous commit"	Never amend. New commit.
"Tests are flaky, skip them"	Surface the failure, ask.
"I should run /review first to be safe"	The user said ship. Ship.
"Let me also tidy up this unrelated thing"	Out of scope. Ship only what's pending.

to-impl.md

name	to-impl
description	Orchestrate AFK implementation of a PRD's issues by dispatching subagents according to the plan in README.md (sequential, parallel, or mixed)
argument-hint	<prd-name>

The user has a PRD whose issues have already been broken down by /to-issues and live under docs/$1/issues/. Your job: drive the AFK portion to completion by dispatching subagents according to the plan-of-action laid out in docs/$1/issues/README.md. The plan is mixed: some steps run sequentially, others run as parallel waves. The README is the source of truth for the topology.

You are the orchestrator. You do not implement. You do not read issue file contents. You read the plan, list the files, decide which specific issue file each subagent should work on, dispatch them according to the topology, observe, and move on. Subagents never self-select — every dispatch is scoped to exactly one issue file that you assigned, based on the README's step ordering.

Phase 1 — Locate the PRD

The PRD name is $1.

Verify the expected layout exists:

• docs/$1/issues/README.md — the plan of action (sequential / parallel structure)
• docs/$1/issues/*.md — individual issue files
• docs/$1/issues/done/ — created on demand by subagents as they complete tasks

If docs/$1/ or docs/$1/issues/README.md is missing, stop and tell the user. Do not guess a different path.

Phase 2 — Read the plan, parse the topology

1. Read docs/$1/issues/README.md in full. Identify:
   • The ordered steps of the plan.
   • For each step, whether it is sequential (one issue at a time) or parallel (a group of issues that can run simultaneously).
   • The mapping of step → issue file(s) under docs/$1/issues/.
   • Which issues are HITL vs AFK. AFK only — skip HITL steps entirely (they're for human handling, not this command).
2. List docs/$1/issues/*.md (top-level only, not done/). Do not read their contents. The subagents read them.
3. State to the user, in three short lines:
   • The number of issue files found and how many are AFK.
   • The topology you parsed (e.g. "Step 1 sequential → Step 2 parallel(3) → Step 3 sequential").
   • That you're starting the loop.

If the README's structure is ambiguous (you cannot confidently tell what's sequential, what's parallel, or which files belong to which step), stop and ask the user before dispatching anything. Do not guess.

Phase 3 — Walk the plan

For each step in order:

• Skip the step if it is HITL.
• Sequential step → go to Phase 3a.
• Parallel step → go to Phase 3b.

After a step completes, advance to the next step. The plan is done when every AFK step has been walked.

3a. Sequential step

A sequential step contains one or more issue files that must be done one at a time, in the order the README implies.

For each issue file in the step, in order:

1. Skip the file if it has already been moved into done/ (re-check docs/$1/issues/done/ before each dispatch).
2. Gather inputs:
   • Recent commits: git log <base>..HEAD --oneline -20 where <base> is git merge-base HEAD origin/main.
3. Dispatch one subagent using the Agent tool with subagent_type: "general-purpose", using the prompt format in the Subagent prompt format section below. The # Open issue files section contains exactly the one issue file path you assigned to this dispatch — nothing else.
4. Observe: when the subagent returns:
   • If its final message contains <promise>NO MORE TASKS</promise>, that means it considered its assigned file already done — verify the file is actually in done/, then advance.
   • Otherwise, confirm something happened: a new commit (git log -1 --oneline), the assigned file moved into done/, or an annotation was appended to the file. If nothing changed, stop and surface to the user — do not re-dispatch the same file blindly.
5. Advance to the next file in the step. When all files in the step are done, advance to the next step.

3b. Parallel step

A parallel step contains N issues that the README says can run simultaneously. Dispatch all N subagents in a single message (multiple Agent tool calls in one assistant turn — that's how parallel dispatch works).

Each parallel subagent gets a single specific issue file assigned by you (the orchestrator) in its prepended context. The verbatim "Pick the next task" prompt then resolves trivially to that one issue. Two parallel agents never see overlapping work because you assigned them disjoint files.

Worktree isolation is required for parallel waves. Two subagents committing to the same working tree will race. For each parallel subagent, allocate an isolated worktree:

• Use the Agent tool's isolation: "worktree" parameter when dispatching. The worktree is created off the current branch and merged back afterward.
• If isolation: "worktree" is not available in the current environment, fall back to creating worktrees manually with git worktree add and instruct each subagent (via prepended context only — not by modifying the verbatim prompt) which path to cd into. Then merge back.

Steps:

1. Gather inputs once (same <base> and recent commits for all parallel subagents — they all branch from the same starting point).
2. For each issue file in the parallel group, dispatch one subagent with:
   • Open issue files scoped to just that one file's path.
   • Recent commits as gathered.
   • The verbatim prompt body unchanged.
   • isolation: "worktree" so it works in its own copy.
3. All dispatches in a single assistant message so they run concurrently.
4. When all N return:
   • For each subagent: if it produced commits, merge its worktree branch back into the current branch (git merge --no-ff <worktree-branch> or follow whatever the worktree tooling reports back). Resolve conflicts the simple way: if a conflict surfaces, stop and ask the user — do not auto-resolve, since each subagent's commit is the spec for its issue.
   • For each subagent: confirm its assigned issue moved into done/ or got an annotation. If nothing changed for an issue, surface it to the user.
   • If any subagent emitted <promise>NO MORE TASKS</promise> instead of working (because its single assigned issue was already in done/, etc.), that's fine — it's a no-op for that slot.
5. Advance to the next step.

3c. Communication discipline

Token budget matters. A long run means many subagent returns flowing into your context. Keep things tight:

• Each subagent must be a low-key communicator. Append the following sentence to the prepended context (just above the --- separator), so it lands before the verbatim body:

  Communicate tersely. Your final message should be at most 3 short lines: what you did, what you committed (1 line), and either <promise>NO MORE TASKS</promise> or "done — see commit". Do not summarize the diff, do not restate the task, do not explain reasoning. The orchestrator will read commits and file moves directly.

• Your own narration during the loop should be minimal. Between dispatches, output one short line per dispatch: Step N (sequential|parallel) → assigned <file> and after return, one line: <file>: committed <sha> or <file>: stuck — <one-phrase reason>. No section headers, no recaps, no "great, moving on", no inter-step preambles. Save prose for the Phase 4 final report.
• Do not echo subagent output back to the user. If a subagent returns more than the budget, distill it to one line in your own log and move on.

3d. Safety rails

• Hard cap: 30 dispatches across the whole run. If you reach 30 without finishing the plan, stop and ask the user whether to continue. Long runs without progress usually mean a stuck task or a misclassified HITL.
• Do not edit issue files yourself. Subagents own issues/.
• Do not run tests, lint, or typecheck yourself. Subagent's job (per its prompt's "FEEDBACK LOOPS" section).
• Do not modify the verbatim prompt. Only the two prepended context sections vary per dispatch.
• Do not invent parallelism. If the README says a step is sequential, do it sequentially even if the issues look independent. The README is the spec.

Subagent prompt format

Every dispatch — sequential or parallel — uses the same prompt structure: two prepended context sections, then the verbatim body.

# Open issue files (paths only — read them yourself)

docs/$1/issues/<assigned-file>.md

# Recent commits on this branch

<sha> <subject>
<sha> <subject>
...

---

# ISSUES

Local issue files from `issues/` are provided at start of context. Parse them to understand the open issues.

You will work on the AFK issues only, not the HITL ones.

You've also been passed a file containing the last few commits. Review these to understand what work has been done.

If all AFK tasks are complete, output <promise>NO MORE TASKS</promise>.

# TASK SELECTION

Pick the next task. Prioritize tasks in this order:

1. Critical bugfixes
2. Development infrastructure

Getting development infrastructure like tests and types and dev scripts ready is an important precursor to building features.

3. Tracer bullets for new features

Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.

TL;DR - build a tiny, end-to-end slice of the feature first, then expand it out.

4. Polish and quick wins
5. Refactors

# EXPLORATION

Explore the repo.

# IMPLEMENTATION

Use /tdd to complete the task.

# FEEDBACK LOOPS

Before committing, run the feedback loops:

- `npm run test` to run the tests
- `npm run typecheck` to run the type checker

# COMMIT

Make a git commit. The commit message must:

1. Include key decisions made
2. Include files changed
3. Blockers or notes for next iteration

# THE ISSUE

If the task is complete, move the issue file to `issues/done/`.

If the task is not complete, add a note to the issue file with what was done.

# FINAL RULES

ONLY WORK ON A SINGLE TASK.

The only parts that vary across dispatches:

• The single path under # Open issue files — exactly one file per dispatch, the one you (the orchestrator) assigned. Sequential and parallel both work this way.
• The list under # Recent commits on this branch — re-gathered before each dispatch (or before each wave, for parallel).

Everything from the --- separator onwards is verbatim. Do not paraphrase, do not add framing, do not summarize.

Phase 4 — Report

When the plan is fully walked (or you stopped early), give the user one concise message:

• How many subagents you dispatched, broken down by step.
• How many issue files moved into done/.
• Any issues still in docs/$1/issues/ top-level (HITL, deferred, stuck — name them).
• The list of new commits on the branch (git log <base>..HEAD --oneline).
• Any merge conflicts or stuck dispatches you surfaced along the way.

Then stop. Do not push, do not open a PR — that's /ship-it's job.

Red flags — STOP if you catch yourself thinking any of these

Thought	Reality
"Let me read the issue file to give the subagent more context"	No. Subagents read the file themselves. You only pass the path.
"I'll let the subagent pick which file from a list of three"	No. You assign exactly one file per dispatch. The subagent never self-selects.
"Let me echo back what the subagent did so the user can follow along"	No. One line per dispatch in your own log. The Phase 4 report is where prose lives.
"I'll write a short paragraph between steps to recap progress"	No. Loop comms are one line per event. Recaps live only in the final report.
"This step looks like it could parallelize, I'll dispatch in parallel"	No. The README defines the topology. Follow it.
"Two parallel subagents are about to commit to the same tree, it'll be fine"	No. Parallel waves require worktree isolation.
"There's a merge conflict from a parallel wave, I'll resolve it"	No. Stop and ask the user. Each subagent's commit is the spec for its issue.
"I'll tweak the subagent prompt to be clearer"	No. The prompt is verbatim by design. Only the two prepended sections vary.
"I'll dispatch a subagent for a HITL step too, just in case"	No. HITL steps are skipped entirely.
"All AFK tasks look done to me, I'll skip the final dispatch"	No. The plan terminates when every AFK step in the README has been walked, not when you eyeball completion.