Larch

Larch is a Claude Code workflow automation framework that orchestrates multi-agent design, code review, and implementation through collaborative AI-driven processes.

Table of Contents

• Setup
  • Installation and Setup — plugin install, local development, agent setup recipes (Claude / Codex / Cursor), clean-main entry contract for /implement and /design, what the plugin provides, the python/cli.py checks run-relevant consumer contract, prerequisites
• Reference
  • Features
  • Skills
  • Aliases
  • Review Agents — the unified code-reviewer archetype
  • Run Logs — committed larch-logs/ batch files, manifest, and tracking-issue comments
  • Topology Projection — stable anchors for cross-doc topology counts
  • Linting — linters, Makefile targets, halt-rate regression harness
  • Issue-Anchored Plan — live wire format for the /design ↔ /implement plan handoff and clarification round-trip
• Architecture and workflow
  • Workflow Lifecycle — how skills compose end-to-end
  • Agent System — parallel subagent orchestration
  • Design Flow — direct plan drafting and plan review
  • Voting Process — the voting panel protocol
  • Point Competition — reviewer scoring system

Features

• Direct design planning and plan reviews — Step 2b drafts the plan directly, then the validation panel reviews it.
• Voting-based review resolution — The YES/NO panel protocol adjudicates plan and code review findings.
• Reviewer competition scoring — Reviewers earn points based on finding quality; a scoreboard tracks accepted, neutral, and rejected findings.
• Tracked runs — /implement writes full run artifacts to committed larch-logs/ files and keeps the tracking issue slim with marker-keyed summary comments.

Skills

larch ships public skills with the plugin (skills/); private skills live under .claude/skills/ and are dev-only (not exported). Both are listed below; shortcut aliases are in the Aliases section. See docs/skills.md for full per-skill detail.

Public skills

Name	Arguments
/alias	[--merge] [--private] <alias-name> <target-skill> [preset-flags...]
Create an alias for a larch skill with preset flags. Auto-routes to skills/<n>/ in plugin source repos and .claude/skills/<n>/ elsewhere; --private forces the latter.
/cleanup
Remove stale larch session temp directories from ~/.cache/larch/sessions/ and /tmp by bounded nested-activity scan (LARCH_CLEANUP_RETENTION_DAYS, default 7): a directory is deleted only when the find -maxdepth 5 nested scan finds no file newer than the cutoff, so a directory with fresh deep activity is retained even when its top-level mtime is stale. Reaps dangling current-design-env-*.sh symlinks. Always runnable regardless of concurrent Claude sessions.
/gc-run-logs	[--older-than DAYS] [--delete] [--dry-run]
Age-based retention policy for committed larch-logs/ run directories. Slims qualifying dirs (default: older than 90 days) to the consumer-core keep set (token/timing reports, findings, manifest); --delete fully removes them. Creates a log-only PR for operator merge. Operator-invoked only — never runs implicitly.
/block-issue	<ISSUE_A> <ISSUE_B> [--repo owner/name]
Express a native GitHub blocked-by relationship between two issues using the addBlockedBy GraphQL mutation. Repo auto-detected when --repo is omitted.
/bug	<bug description>
Investigate a user-described bug read-only, compose a detailed issue body, then file it via /issue with dedup enabled. Aborts to SECURITY.md disclosure if the report looks security-sensitive; never edits the repo.
/design	[-p|--partition] [--brainstorm] [--per-round-approval] [--skip-approve|-s] [--no-dedup] [--run-id <ID>] <issue-N | feature description>
Author or refresh an issue-anchored implementation plan in GitHub (plan markers in the issue body). -p/--partition routes Step 2b.5 directly to the decomposition panel when no plan-size threshold trips; size triggers show the Override/Cancel prompt. Optional --brainstorm runs Step 1d.5 ideation before the Step 1d.7 outline-approval gate (Gate A re-entry only post-plan) (see docs/skills.md). Gate B auto-applies accepted findings by default; --per-round-approval restores the explicit per-round apply prompt. --skip-approve/-s auto-approves the Step 1d.7 outline and Gate C final plan without an AskUserQuestion (no other prompts are skipped). The old --approve and --hard flags are rejected; use --per-round-approval for explicit Gate B prompts. Finalize runs upstream /larch:issue batch filing for accepted non-security OOS (Step 5b) before writing and publishing the larch:plan block (5c); tmpdir cleanup is Step 6.
/deps	[--repo owner/name] [--pair-cap N]
Audit open issues by in-flight title prefix, conservatively refresh mutable REGULAR bodies, propose stale REGULAR closes, and infer dependencies with an explicit-ref scan plus latent semantic pass. Mutates only after AskUserQuestion approval. Dependency writes use /block-issue. --pair-cap is explicit partial-audit mode.
/pause
Pause a running /design; saves state to GitHub for cross-session resume. Source: skills/pause/SKILL.md.
/implement	[--merge] [--forked] [--draft] [--no-admin-fallback] [--no-logs-commit] [--coder <claude|codex|cursor>] [--run-id <ID>] [--emergency] [--self-review] <issue-N>
End-to-end implementation from the positional GitHub <issue-N> after /design has written larch:plan into that issue's body. Step 5 always runs review-and-fix CLI with the unified internal hard panel (no public --panel argv): up to 5 rounds (fixed hard ceiling), a 3-judge panel on every round (three Cursor archetype voters when Cursor is available; single-Claude fallback when Cursor is unavailable), and the review panel with specialists per vendor (plus optional dynamic archetypes). --merge enables CI+merge; --forked is mutually exclusive with --merge. Use --emergency to skip the item 4 plan-adequacy audit and downgrade only the documented emergency Preflight gates to warn-and-proceed (default off). --self-review skips the external panel for a thorough inline self-review at Step 5. Preflight audit refusal exits 3 (distinct from flag/plan hard errors exit 2).
/issue	[--input-file FILE] [--intra-batch-deps-file FILE] [--blocked-by-issue N] [--title-prefix PREFIX] [--label LABEL]... [--body-file FILE] [--dry-run] [--no-dedup] [--no-dep-llm] [--sentinel-file PATH] [<issue description or title>]
Create one or more GitHub issues with LLM-based semantic duplicate detection and always-on inter-issue blocker-dependency analysis. --no-dedup skips both passes; --no-dep-llm keeps dedup but skips the LLM dependency pass. Batch/wiring flags (--input-file, --body-file, --blocked-by-issue, --intra-batch-deps-file, --sentinel-file) are used mainly by calling skills.
/report-tokens	--skill <design|implement> [--no-issue] [--no-plot] [--run-id <ID>]
Analyze structured token reports from committed larch run logs, price Claude/Codex/Cursor runs through `python/report_tokens_cost.py`, plot skill-aware trends, and print cost-reduction suggestions.
/fluff-analysis	[--include-in-progress] [--cutoff ISO8601] [--since-version X.Y.Z] [--min-group N] [--log-root DIR] [--out FILE]
Characterize review fluff from committed larch run logs — which /design and /implement review suggestions get rejected, deferred to OOS, or accepted-but-low-value — by acceptance baselines, low-acceptance semantic groups, severity cuts, and reviewer-lane splits, then print data-driven recommendations for tightening the reviewer self-filter and judge (voter) instructions.
/voter-calibration	[--log-root DIR] [--min-votes N] [--outlier-threshold R] [--out FILE]
Measure voter agreement and chronic outlier voters from committed larch run logs. Diagnostic only; does not affect spawning, thresholds, tokens, or reviewer points.
/research	[--no-issue] <research question or topic>
Collaborative best-effort read-only research with the fixed-shape topology documented in the research skill — planner pre-pass, Codex-first research lanes by angle, and the validation panel. Every run includes unconditional citation validation (HEAD-fetches cited URLs under SSRF guards, validates DOIs, spot-checks file:line refs) emitted as a fail-soft PASS / FAIL / UNKNOWN ledger spliced into the final report.
/review	[--diff] [--subagent] [--dynamic-archetypes <N>] [--session-env <path>] [--step-prefix <prefix>] [<description>]
Code review with the specialist panel described in docs/review-agents.md. --diff: review branch changes and implement fixes. <description>: review existing code; description mode records voting outcomes and OOS artifacts locally — file follow-up issues with /issue when you want GitHub tracking. --subagent, --dynamic-archetypes, --session-env, and --step-prefix are used mainly by /implement Step 5.
/review-and-fix	--findings-file <path> [--session-env <path>] [--review-tmpdir <path>]
Apply accepted review findings as code fixes via Codex/Cursor/Claude-subagent dispatch. Internal sub-skill invoked by /review in diff mode and by /implement Step 5; not a standalone user entry point.
/set-up-forked-open-source-repo	--upstream <owner/repo> --fork <owner/repo> [--mirror-confirmed] [--init-submodules]
Configure the current checkout for upstream/fork OSS contribution: verify the fork, optionally sync it from upstream, rewire remotes, disable upstream pushes, and set main tracking.
/status	(none)
Print the current larch version and health status of external vendor tools (Codex and Cursor), using the same probe machinery as /implement.
/upgrade-larch	(none)
Upgrade the larch plugin to the latest version by refreshing the sparse marketplace checkout in place when possible, repairing legacy clones when needed, then reinstalling the plugin.

Private skills

Dev-only: not shipped with the plugin; runnable only inside the larch source tree.

Name	Arguments
/agnix-fix	<upstream-issue-number> [extra-flags...]
Fix an open agent-sh/agnix issue end-to-end via fork-CI dry-run: fetch the upstream issue body, provision the skip-changelog label on the fork, then forward to /implement --forked with the positional upstream issue number.
/analyze-issues	[--limit N] [--span-days N] [--top-K N] [--categories=auto|default] [--lenient]
Generate a backlog-and-process insight report from a repo's GitHub issues: coverage stats, category breakdown, cumulative-growth chart, wasteful-work signatures, and reviewer/persona effectiveness.
/audit-runs	--skill <design|implement> [<verbal-description>] [--repo owner/name] [--allow-concurrent]
Audit recently-merged larch run logs for anomalies, file the chain-of-history audit-report issue, and propose bug-issue follow-ups that require explicit user direction before any filing.
/combine-issues	[--oos]
Combine related open issues into fewer broader ones (closing the sources) to reduce token spend. --oos operates only on [OOS]-prefixed issues, discards stale items, and proposes an aggressive combination scheme.
/larch-size	(none)
Report larch repository line counts (Bash, Python, Markdown) and larch-logs size breakdowns. Takes no flags.
/rebalance-tests	[--kind {harness,python,all}] [--repo owner/name] [--n-runs N] [--branch-prefix PREFIX] [--n-python-shards N]
Rebalance CI test harness shards, Python unit-test shards, or both from recent CI timings; create one PR and trigger verification CI. Harness verification is warning-only; Python timing verification fails closed.
/release	[--dry-run] [--bump major|minor|patch] [--repo OWNER/REPO]
Operator-run release cut (model cannot auto-invoke): gather merged PRs since the last Latest release, generate notes, decide the semver bump, open and merge the plugin.json bump PR, tag and create the GitHub Release, promote to Latest, then run /upgrade-larch.

Non-skill entrypoints

Name	Arguments
python/cli.py checks run-relevant	(none)
Consumer-provided validation entrypoint (not a SlashCommand skill). Orchestrators call it through python/cli.py checks run-relevant. Not part of the plugin surface; each consuming repo provides its own executable script.

See docs/skills.md for full details on each skill.

Aliases

Shortcut skills shipped with the plugin. Each alias forwards to an existing skill with preset flags.

Alias	Equivalent
/im	/implement --merge (same public flags as /implement; requires positional <issue-N>)