AI Agent Workflow Collection

Print the orchestrator's intended approach for an item, slice, or milestone — files it would touch, files it would create, tests it would add, assumptions it's making, known unknowns it would resolve mid-flight. Read-only; writes nothing. Use before /hv-work to verify alignment, especially on size-M+ items where corrections after the fact are expensive.

Per-item design exploration before /hv-plan — Socratic discovery, 2-3 approaches with tradeoffs, sectioned design with per-section approval, writes .hv/designs/ .md, hands off to /hv-plan. Use when a Major feature or P0 bug needs design negotiation before implementation planning.

Shortcut for /hv-capture — forwards verbatim. See hv-capture for behavior.

Capture bugs, features, and tasks into TODO.md without executing them. Classifies each item, assigns priority/size, mints zero-padded IDs ([B01], [F01], [T01]). Records only — for an immediate fix use /hv-go; for items already in TODO use /hv-work.

Change hv-skills configuration interactively — pick which settings to edit from a checklist showing current values, then choose new values from the same options used at init. Use on "change config", "switch to worktree mode", "turn on autonomy", "edit settings".

Capture or refine a domain term in .hv/CONTEXT.md — the project's canonical glossary. Use on "save X as Y", "let's call this X", "by Y I mean...", "add X to context", or to refine an existing term. Distinct from /hv-learn (passive gotchas) and /hv-decide (hard boundaries) — CONTEXT.md is the project's vocabulary, consulted before answering or brainstorming so terms stay consistent.

Systematic root-cause investigation for a bug — reads the TODO entry + detail file, consults KNOWLEDGE.md, reproduces, hypothesizes, verifies, fixes with one atomic commit, and nudges /hv-learn. Use on "debug [B07]", "why is X broken", "investigate the crash", when a bug needs a proper cycle rather than a /hv-go shot.

Capture a hard-boundary decision into .hv/DECISIONS.md — manually confirmed, never auto-invoked. Decisions differ from learnings in KNOWLEDGE.md by being active commitments with explicit forbids/permits. Use on "decide on X", "we're committing to X", "lock in the boundary that Y", or when a session has produced a constraint future work must respect.

Scaffold and maintain a public-facing user guide under / (default docs/) — aimed at consumers, not contributors. Modes — first-run (discovery + scaffold), after-work (post-cycle proposals), restructure (audit + reorganize). Use on "/hv-docs", "update docs"; auto-invoked by /hv-work and /hv-ship post-cycle.

Capture one item and immediately implement it — combines /hv-capture and /hv-work, skipping the /hv-next review. Use when the user wants one specific thing done right now ("fix X", "add Y", "do Z") and it's not yet captured. For brain-dumping use /hv-capture; for items already in TODO.md use /hv-work.

Initialize the .hv/ folder structure with TODO.md, KNOWLEDGE.md, counters.json, config.json, status.json, and CLI helpers. Also seeds a managed knowledge-index block in CLAUDE.md so future /hv-work runs can consult learnings. Called automatically by other hv: skills when the folder doesn't exist, or manually to set up a new project.

Pull open GitHub/GitLab issues into .hv/BACKLOG.md — list candidates from the upstream repo(s), capture selected ones with GH/GL cross-references, label them in-progress upstream so collaborators see they're claimed. Use on "import issues", "pull open issues from GitHub", "list issues", "capture issues from upstream". Round-trip closing is handled separately by /hv-ship and /hv-merge.

Extract durable session learnings (gotchas, conventions, constraints) into .hv/KNOWLEDGE.md grouped by topic, and update the CLAUDE.md topic index. Opus verification is on by default via learn.verify in config.json; set to false for fast/cheap mode.

Maintain the project map of subsystems under .hv/map/. Modes — first-run (scaffold), after-work (update touched subsystems), consolidate (merge stale/duplicate entries). Auto-invoked post-cycle by /hv-work, /hv-debug, /hv-go; run manually for first-run and consolidation.

Review the backlog, reconcile active work against git state, archive old completions, show sorted tables with relationship clusters, suggest the next item, and route to /hv-work. Use on "what should I work on", "pick up the next task", or when the user wants to see their backlog.

Gracefully pause mid-session — writes a handoff note (current hypothesis, next planned step, mid-edit files, uncommitted work strategy) to .hv/handoff/ .md so /hv-resume in a fresh session can pick up with full context, not just git state. Use when the session is approaching a context limit, you need to hand off, or you want to stop a long /hv-work cycle cleanly.

Write an implementation plan as a first-class artifact before execution — keyed by milestone and slice or item (M01-S01.md, M01-B07.md). Captures goal, approach, task decomposition with verifiable outcomes, open questions, and named assumptions. /hv-work consults the plan if present. Use when an item or slice is too big to one-shot, or when alignment matters before code lands.

Run a full architectural refactor cycle — explores the codebase for friction, categorizes dependencies, designs competing approaches for structural changes, then fixes everything with parallel subagents. Use when you want to find and fix architectural issues.

Cut a release — bump version (major/minor/patch), generate categorized release notes from commits since the last tag, prepend a section to CHANGELOG.md, create an annotated git tag, push, and publish a release on GitHub or GitLab if origin is set. Use on "release", "cut a release", "tag a release", "ship X.Y.Z".

Staff-engineer review of a feature branch before merge or PR — reads commits, diff, referenced item IDs, and matching KNOWLEDGE.md topics; dispatches an Opus reviewer that checks intent match, convention compliance, and quality. Returns PASS / CONCERNS / FAIL. Use on "review this", "check before I ship", "look over the branch", or implicitly from /hv-ship.

Remove a captured backlog item and clean up its dependencies — strips the TODO entry, removes Related cross-references, deletes the detail file (.hv/{bugs,features,tasks}/ .md), removes any plan keyed to it (.hv/plans/ - .md), and refuses if the item is active in status.json. Defaults to a dry-run preview; the slash command always asks before applying. Inverse of /hv-capture.

Throwaway feasibility experiment on a dedicated git branch — answers a specific question without polluting main or the backlog. Creates spike/ branch and .hv/spikes/ .md for question + findings + decision. Branch is never merged; only findings come back. Use when you need to try X before committing to it ("can we use SSE?", "does this library handle our scale?").

Guided rollback of the last /hv-work cycle on the base branch — resets the merge commit, restores TODO entries to their type sections, refuses on cycles with post-merge commits unless --allow-post-merge is passed. Direct-merge cycles only (MVP); PR-mode is detected and refused with a manual-recovery pointer. Defaults to a dry-run preview; the slash command always asks before applying. Inverse of /hv-work's commit + completion steps.

Check for a newer hv-skills release on GitHub and tell the user how to update — detects install type (plugin, stow, repo clone), compares plugin.json version against the latest release, and prints the exact update command. Read-only; does not run the update itself. Use on "check for updates", "is hv-skills up to date", before long /hv-work sessions.