design

Files (55)

• SKILL.md
• approval-gates-explicit.md · references/
• approval-gates-gate-a.md · references/
• approval-gates-gate-b.md · references/
• approval-gates-gate-c.md · references/
• approval-gates.md · references/
• brainstorm-prompts.md · references/
• brainstorm.md · references/
• decompose-panel.md · references/
• design-outline.md · references/
• dialectic-clarifier.md · references/
• discussion-rounds.md · references/
• finalize-step5-failures.md · references/
• finalize-step5.md · references/
• flags.md · references/
• oos-step5b-dispatch.md · references/
• plan-review-runtime.md · references/
• plan-review.md · references/
• sentinel-host-table.md · references/
• settle-rc-dispatch.md · references/
• step2b-drafter-failsafe.md · references/
• step2b5-rc-handling.md · references/
• validator-failure.md · references/
• check-plan-size.md · scripts/
• _common-tail.txt · scripts/decompose-prompts/
• decomposition-specialist.txt · scripts/decompose-prompts/
• dependency-analyst.txt · scripts/decompose-prompts/
• risk-isolation.txt · scripts/decompose-prompts/
• scope-minimalist.txt · scripts/decompose-prompts/
• design-clarify.md · scripts/
• design-step3-entry.md · scripts/
• design-step3-entry.sh · scripts/
• design-step3-review.md · scripts/
• design-step3-review.sh · scripts/
• design-step35.md · scripts/
• design-step35.sh · scripts/
• design-step3b-tail.md · scripts/
• design-step3b-tail.sh · scripts/
• design-step5b-annotate.md · scripts/
• design-step5b-annotate.sh · scripts/
• design-step5b-prepare.md · scripts/
• design-step5b-prepare.sh · scripts/
• design-step5c.md · scripts/
• scout-plan-archetypes-prompt.txt · scripts/
• step-name-registry.tsv · scripts/
• test-brainstorm-prompts.md · scripts/
• test-brainstorm-prompts.sh · scripts/
• test-check-plan-size.md · scripts/
• test-findings-classification.md · scripts/
• test-findings-classification.sh · scripts/
• test-gate-b-apply-mode.sh · scripts/
• test-step3-orchestrator-fence.md · scripts/
• test-step3-orchestrator-fence.sh · scripts/
• test-step3-review-cap.md · scripts/
• test-step3-review-cap.sh · scripts/

SKILL.md (first lines)

**MANDATORY: `design`: Rust owns lifecycle start/finish (`skills/shared/run-lifecycle-ownership.tsv`). Never run the generic lifecycle (`${CLAUDE_PLUGIN_ROOT}/skills/shared/run-lifecycle.md`). Send `--lifecycle-parent-context` only to Step 0.**
# Design Skill

Design an implementation plan and review it with the mechanical plan-review panel. `skills/design/references/plan-review-runtime.md` owns Step 3 topology, slots, adjudication, and voting; `plan-review.md` is editing-only authority. Flow: Step 2a sentinel prep is folded into the Step 2b drafter wrapper, Step 2b drafts from direct codebase inspection, Step 3 runs review, Step 5b files accepted non-security OOS via `/larch:issue`, and Step 5c writes `larch:plan` with `scripts/larch.sh named-block write --marker plan`. No design manifest export.
**Flags**: Step **0-pre** is authoritative: `scripts/larch.sh design parse-flags` emits parsed KVs; do not re-parse `$ARGUMENTS`. Nested `--lifecycle-parent-context <absolute-context-path>` is internal: the parser removes it and forwards it to lifecycle start. Public argv allows only `-p`, `--partition`, `--brainstorm`, `--per-round-approval`, `--skip-approve`, `-s`, `--no-dedup`, `--run-id`, and `--difficulty`. Boolean flags default to `false`; other leading public `--` flags, including `--hard`, error before Step 0 and are not positional. The parser owns validation and error rendering. The table below is a user-facing index.

| Flag | Default | Purpose |
|------|---------|---------|
| `-p` / `--partition` | `false` | Route directly to the unified inline Split-path on every plan write when no hard threshold tripped (persisted as `partition_requested` in `run-params.json`; see `references/flags.md` only for background) |
| `--brainstorm` | `false` | Request Step **1d.5** brainstorm ideation before Step 1d.7 outline-approval (Gate A re-entry only post-plan) (persisted as `brainstorm_requested` in `run-params.json`; see `references/flags.md` and `references/brainstorm.md` only for background) |
| `--difficulty <TRIVIAL\|MODERATE\|HARD>` | empty | Sets the starting plan-review tier, beats rating and floors, and logs `override_source=operator`; the 1:30 audit can still upgrade a below-HARD run and logs both fields. |
| `--per-round-approval` | `false` | Restore the explicit per-round Gate B apply prompt (Apply all / Go through each / Switch to discussion mode); default auto-applies accepted in-scope findings (persisted as `approve_requested` in `run-params.json`; see `references/flags.md` only for background) |
| `--skip-approve` / `-s` | `false` | Auto-approve Step 1d.7 outline-approval and Step 4b Gate C final-plan without an `AskUserQuestion`, except Gate C still runs architectural invariant/guideline `present-note` + `persist-design-assessment` and the accepted-findings audit; strong dissent forces the prompt; does not skip any other prompt (persisted as `skip_approve_requested` in `run-params.json`; see `references/flags.md` only for background) |
| `--no-dedup` | `false` | Forward to `/larch:issue` when the verbal path creates a tracking issue |
| `--run-id <ID>` | empty | Optional run identifier |

**Mutual exclusion**: at most one `--per-round-approval` and at most one `--skip-approve` / `-s` may appear on argv; duplicates are hard errors before Step 0. `--per-round-approval` and `--skip-approve` are **not** mutually exclusive: both may appear together. Any other unrecognized or disallowed leading public `--` flag (including retired `--approve` and `--hard`) is a hard error before Step 0 (never swallowed as positional/verbal feature text).
**Positional tail**: Step **0-pre** binds this as `POSITIONAL_KIND=issue|verbal|none` and `POSITIONAL_VALUE=<value>`; see `crates/larch-cli/src/design_commands.rs` for classification details. `POSITIONAL_KIND=verbal` triggers `/larch:issue` first (forward `--no-dedup` when set), then binds `ISSUE_NUMBER` to the created issue and continues as the issue path.
**Anti-halt continuation reminder.** Follow the step-boundary continuation core in `${CLAUDE_PLUGIN_ROOT}/skills/shared/subskill-invocation.md#anti-halt`, plus these `/design` deltas: after every visible output (plans, voting tallies, skip breadcrumbs), IMMEDIATELY continue; never end the turn on a Bash result, status line, deliverable-looking output, summary, handoff, status recap, or "returning to parent" message. This applies from Step 0 through Step 6 and across sub-step transitions (1c→1d→1d.5→1d.7→2a(folded)→2b→2b.5→3→3.5→3b→4→4b→5→5b→5b.5→5c.1→5c.5→5c.7→5c.8→6). Reach Step 1e Gate A only by re-entry from Gate B(c) or Gate C(b) (each → Step 1e, Shape 2); first-time entry skips Step 1e because Step 1d.7 outline-approval replaces Shape 1. After Step 5c `scripts/larch.sh design step5c` returns with `_publish_rc` 0, 1, or 3, or after any cancellation outcome's Final summary block has written a non-empty summary file, NEVER write a free-form natural-language recap summary: no "Design complete." line, no artifact bullet list, no parenthetical cost paraphrase such as `~$10.46`, and no replacement for the structured `## /design run ...` block. The `/design` Read-always readiness profile in `${CLAUDE_PLUGIN_ROOT}/skills/shared/final-summary-emit.md` reads/caches when `_publish_rc` is 0, 1, or 3, including `_publish_rc`=1 after plan-block-write failure; terminal emit follows warning replay, operator lines, footer, and Step 6 cleanup. No tool call, cleanup fence, footer, warning replay, operator line, or recap may follow the terminal summary emit. **Not** gated on `scripts/larch.sh design render-final-summary` exit 0. **Narrow exception: Step 1d.5 and Step 1d.7 only**: after the brainstorm synthesis digest, the free-form discussion loop may yield between operator messages per `references/brainstorm.md`; after the Step 1d.7 design outline, the Refine loop may yield between operator messages per `references/design-outline.md`; never use `ScheduleWakeup`, scripted sleep-polling loops, or Monitor polling on either lane. Gate re-entry and Gate C Approve are explicit non-halt control flow; after Gate C Approve, enter Step 5 immediately with no further user message. **Critical: the implementation plan (Step 2b) is an intermediate deliverable, NOT the end of the design. Plan review (Step 3), Gate B (Step 3.5), Gate C (Step 4b), finalize (Step 5), post-approval diagram (Step 5b.5), and cleanup (Step 6) must still execute.** Architecture diagram work runs only at Step 5b.5 after Gate C Approve or `--skip-approve` auto-approve. **Step 3 MUST NOT start until Step 2b.5 completes** (including any `AskUserQuestion` branches there). This rule is strictly subordinate to any explicit non-sequential control-flow directive in THIS file (e.g., `skip to Step N`, `bail to cleanup`, `jump back`, `proceed to Step N`); a normal sequential `proceed to Step N+1` is the default continuation it reinforces, NOT an exception.

## Progress Reporting

**Every step MUST print clearly visible breadcrumb status lines** so the user can instantly see where execution is and which parent steps they are inside. Follow shared/progress-reporting.md rules.

- Print a **start line** when entering a step: e.g., `> **🔶 /design 1c: questions**` (the first numbered step after Step 0 setup).
- Do not print step completion lines; start breadcrumbs are the visible step markers.
- When `STEP_NUM_PREFIX` is non-empty, prepend it to step numbers: `{STEP_NUM_PREFIX}{local_step}`. When `STEP_PATH_PREFIX` is non-empty, prepend it to breadcrumb paths: `{STEP_PATH_PREFIX} | {step_short_name}`. When `PARENT_SKILL_PATH` is non-empty, print the skill path as `{PARENT_SKILL_PATH}:/design`; otherwise print `/design`. **This rule overrides the literal skill paths, step numbers, and names in `Print:` directives and examples throughout this file.** `/design` is always invoked as a standalone skill; `STEP_NUM_PREFIX`, `STEP_PATH_PREFIX`, and `PARENT_SKILL_PATH` are optional env-driven label prefixes from the outer orchestrator only: they are not a nested `/design` transport or a second skill instance.

**MANDATORY at session start**: Read `${CLAUDE_PLUGIN_ROOT}/skills/design/scripts/step-name-registry.tsv` to get the Step Name Registry (step number → short name mapping for progress breadcrumbs).

### Verbosity Control

Follow shared/verbosity-control.md rules.
**Only print:** step breadcrumb lines (start `🔶`, skip `⏩`); plain immediate-background progress breadcrumbs required by specific non-Step-3 fences, such as Step 5c and Final summary; all warning/error lines (`**⚠ ...`); structured summaries (voting tallies, scoreboards, round summaries, findings lists, approach synthesis, implementation plans); and the compact reviewer status table only for the Step 3 review fence and Step 3 resume fences (see below).
**Suppressed output:** explanatory prose, script paths, rationale for decisions between tool calls, per-reviewer individual completion messages. **NEVER** print `$DESIGN_TMPDIR/architecture-diagram.md`, `$DESIGN_TMPDIR/architecture-diagram.candidate.md`, sanitizer marker bodies, or Mermaid diagram bodies to chat; architecture diagram content is issue-only via `larch:diagrams`.
**Compact reviewer status table**: Use the single Step 3 reviewer status cadence only after `bgjob wait` returns `BGJOB_STATUS=DONE` with `BGJOB_RC=0` and the required Step 3 result KVs present. Print the compact table once for those Step 3 waits, only after confirmed completion.
**Step 3 foreground waits**: Use the shared bgjob wait contract before the Step 3 review fence or any Step 3 resume fence.

### Bash block prelude

The Claude Code Bash tool does NOT preserve shell state between calls. Step 0a writes `$DESIGN_TMPDIR/source-env.sh` with `DESIGN_TMPDIR`, `SESSION_TMPDIR`, `SESSION_ID`, `CLAUDE_PLUGIN_ROOT`, and reviewer presence/availability booleans; Step 0b refreshes it after `ISSUE_NUMBER` is known. It also updates `~/.cache/larch/sessions/current-design-env-$PPID.sh` and `~/.cache/larch/sessions/design-run-$PPID.sh` using the root Bash-tool `$PPID`; do not wrap the writer in extra `bash` layers without `--claude-pid`. After Step 0a, ported fences call the typed Rust verb through `scripts/larch.sh`, either via `design-run-$PPID.sh <verb> ...` or with the explicit PID-keyed `--session-env-path` / `--claude-pid` pair. Retained wrapper fences still pass `*.sh` basenames.

```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" design prelude --session-env-path "$HOME/.cache/larch/sessions/current-design-env-$PPID.sh" --claude-pid "$PPID"
```

**Phase 7 exception**: pure-LLM Steps **1c**, **1d**, and **1e** have no standalone prelude fences: their timing marks and absorbed completion sentinels are folded into adjacent real-work hosts (see **Completion sentinels** below). Step **1d.5** is explicitly **retained** as a standalone prelude because brainstorm paths can launch and collect external Bash work. Step **1d.7** is retained with a dedicated read-only fence for `SKIP_APPROVE_REQUESTED`; see the maintainer-only sentinel host-table reference.
Wrapper scripts keep the conditional source behavior internally so pre-upgrade in-progress runs degrade silently and unexpected absence surfaces as the standard `set -u` unbound-variable error rather than a corrupted source call. Step 0 parse/setup wrappers create the env file before requiring it.
Writer: `${CLAUDE_PLUGIN_ROOT}/crates/larch-cli/src/session_env_commands.rs` (`session write-design-env`); tests: `${CLAUDE_PLUGIN_ROOT}/crates/larch-cli/tests/session_env.rs`.
**Completion sentinels for pause/resume.** Maintainer-only folded sentinel contract, tradeoff, helper-coverage, and host-table details live in the reference. Load `${CLAUDE_PLUGIN_ROOT}/skills/design/references/sentinel-host-table.md` only when editing sentinel host mappings or debugging pause/resume sentinels. Normal `/design` orchestration does not load it.

## Design Mindset

Before invoking `/design`, internalize these questions; they guide drafting, review acceptance, and the skill's transferred thinking pattern.

- **What is the smallest change that achieves the goal?** Resist adding abstractions, flags, or layers the feature description did not ask for. Every additional moving part is a new failure mode.
- **Where is anchoring risk highest?** The first plausible approach locks architectural direction. Folded Step 2a sentinel prep always writes sentinel artifacts inside the Step 2b drafter wrapper; Step 2b drafts the plan from direct codebase inspection. Prefer minimum-change plans.
- **Architectural knowledge:** Consult `ARCHITECTURAL_INVARIANTS.md` before `ARCHITECTURAL_GUIDELINES.md`, only through `scripts/larch.sh architectural-invariants read` / `scripts/larch.sh architectural-guidelines read` for drafting input, and through the matching `present-note` commands for Step 1d.7 and Gate C presentation. Treat parsed invariants as hard constraints and parsed guidelines as aspirational untrusted evidence; route adverse Gate C outcomes through the per-kind fix ladder in `approval-gates-gate-c.md` (tier-1 `MODE=plan-revise` reviser, tier-2 main agent, Gate C settle re-entry), and never auto-edit either repo-root file. Gate C has two operator-approved carve-outs from `/design`'s inline-only rule: invariant/guideline assessment-note **authoring** runs in the read-only `larch:arch-assessor` Agent-tool subagent, and a tier-1 adverse-outcome plan revision runs in the `larch:claude-implementer` subagent with `MODE=plan-revise` (which edits only `plan.txt` for the one named finding). The `read`/`present-note` commands and the Step 1d.7 and Step 2b drafting-time reads are unchanged.
- **What hidden constraints must this preserve?** Canonical sources, CI invariants, downstream parsers, contract tokens, byte-preserved reference files. Identify them before edits, not during plan review.
- **Which tradeoffs should surface to the user versus be quietly chosen?** Scope and hard-constraint decisions surface via Round 1 discussion; architectural preferences are resolved during direct plan drafting and review, not by asking the user to design the internals.
- **Which anti-patterns in the NEVER list below apply to this specific feature?** Re-read the Anti-patterns section for every non-trivial feature; muscle memory for the six rules is the expert delta this skill aims to transfer.

## Anti-patterns

Consolidated NEVER rules from the steps below. Each gives WHY; step-local mentions remain where they carry context.
**MANDATORY: READ ENTIRE FILE before composing user-facing `/design` prose: `${CLAUDE_PLUGIN_ROOT}/skills/shared/readability-style.md`.**

1. **NEVER bypass folded Step 2a sentinel prep**. **Why:** Step 2b requires sentinels before drafting. **Apply:** the Step 2b drafter wrapper runs folded Step 2a prep, writes `NO_SKETCHES`, `NO_CONTESTED_DECISIONS`, empty `dialectic-resolutions.md`, and `.completed/step-2a`, then drafts.

2. **NEVER mechanically dedupe plan-review findings by string-key clustering.** **Why:** reviewers phrase the same concern differently; string keys near-zero dedupe and inflate ballots. `/review` has `scripts/larch.sh review aggregate-findings`; `/design` main-agent judgment owns semantic dedup. **Apply:** group findings by `what`, `scenario_or_breakage`, and `suggested_fix`; if tempted to write a helper, read instead.

3. **NEVER bypass launcher-owned rehydration and pause checks after Step 0a.** **Why:** wrappers must self-terminate at Bash boundaries so pause/resume keeps pause requests and current-env paths. **Apply:** every post-Step-0a Bash fence invokes the launcher with a bare ported Step 0/1 verb or unported `*.sh` basename. The launcher supplies source-env and Claude PID; wrappers own source-env, pause checks, folded sentinel ordering, and the Step 6 cleanup exception. Harness: `make test-design-structure` `assert_wrapper_pause_before_work`.

4. **NEVER use the `Monitor` tool anywhere within the `/design` orchestrator.** Use the shared bgjob wait contract for migrated long helpers, not Bash polling loops. NEVER launch a background recovery waiter. Do NOT fall back to Monitor.
5. **NEVER act on launcher stdout, `DONE` alone, or legacy milestones during `/design` bgjob waits.** `BGJOB_STATUS=WAIT` means run the identical `bgjob wait` again with no intervening prose or tools. `BGJOB_STATUS=DONE` permits normal continuation only when `BGJOB_RC=0` and the required KVs are present in the bgjob result env.
6. **NEVER treat an AskUserQuestion no-response fallback as an operator answer.** **Why:** a 60-second platform fallback is no answer. **Apply:** when a `/design` `AskUserQuestion` returns the no-response fallback, do not choose, infer consent or cancellation, refine, or use "best judgment." Re-fire the identical `AskUserQuestion`, retry without a cap, and keep repeats quiet unless the tool must show the prompt. Terse real answers still count.

<!-- step:0: Session Setup -->
## Step 0: Session Setup

Print: `> **🔶 /design 0: setup**`

### 0-pre: Public argv validation (before session setup)

**When**: immediately before Step 0a. No `session setup`, `DESIGN_TMPDIR`, or Final summary block on this path.
Do not run a separate `scripts/larch.sh design parse-flags` fence. Step 0a's `design step0-session` wrapper runs Step 0-pre before `session setup`: it renders shell-quoted `<PUBLIC_ARGV_WORDS>`, keeps verbal tails positional, and aborts on parse failure. For manual debugging, invoke the raw parser with no leading `--`; a leading `--` stops flag parsing and forces the rest into verbal text.
On success, Step 0b consumes the bound booleans, optional `run_id`, `POSITIONAL_KIND`, and `POSITIONAL_VALUE`.

### 0a: Reviewer session (`DESIGN_TMPDIR`)

`/design` requires the default gate: `main`, clean tree, empty stash. Call `design step0-session` without `--skip-branch-check`; keep the single Bash block so setup stdout and `session write-design-env` share one subshell.

Setup KV contract pointer (maintainer only): `${CLAUDE_PLUGIN_ROOT}/skills/shared/session-setup-output.md`. Parse `SESSION_TMPDIR`, `SESSION_ID`, `CONTEXT_FILE`, `CODEX_BINARY_FOUND`, `CURSOR_BINARY_FOUND`, `CODEX_PRESENT`, and `CURSOR_PRESENT`; set `DESIGN_TMPDIR=SESSION_TMPDIR`. Preserve `CONTEXT_FILE` for every nested Skill-tool lifecycle handoff. Execution-issues logging targets `$DESIGN_TMPDIR/execution-issues.md`.

```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" design step0-session \
  --claude-pid "$PPID" \
  --plugin-root "${CLAUDE_PLUGIN_ROOT}" \
  -- <PUBLIC_ARGV_WORDS>
```

If `session setup` exits non-zero, the block prints its captured stdout/stderr first (including any raw `PREFLIGHT_ERROR=...` line). Then print the normalized skill-level message and abort:
**⚠ /design: session setup failed. Investigate `PREFLIGHT_ERROR` and re-run.**
This writes `$DESIGN_TMPDIR/source-env.sh`, refreshes the stable symlink `~/.cache/larch/sessions/current-design-env-$PPID.sh`, and writes `~/.cache/larch/sessions/design-run-$PPID.sh` so later launcher fences resolve on every Bash block. `--issue-number "$ISSUE_NUMBER"` should be appended on the Step 0b follow-up writer invocation once that value is bound. The writer accepts a re-invocation to refresh keys.
**Execution-issues logging**: capture failing Bash, reviewer/collector, and Agent fallback output in `$DESIGN_TMPDIR/*-failure.log`, then append it verbatim with `"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" run-log append-failure` under `External Reviewer Issues`; include `${OUTPUT}.diag` for collector failures. Exception: Step 5b.5 may log only bounded diagram-generation warnings through `crates/larch-core/src/report/diagram_log.rs`; Step 5c owns sanitizer-rejection warnings/logging. Never log diagram bodies or raw generator/sanitizer output.
**Degraded-tools gate (#3207).** The Step 0a session wrapper owns the design degraded-tools gate immediately after `session write-design-env` succeeds. Maintainer contract pointer: `${CLAUDE_PLUGIN_ROOT}/skills/shared/external-reviewers.md`. It invokes `"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" agent degraded-tools-gate` with explicit `--codex-binary-found` / `--codex-present` / `--cursor-binary-found` / `--cursor-present` flags from the session setup envelope and `--skill design`.
Parse `STEP0_STATUS`, `DEGRADED`, `BOTH_DOWN`, optional `DEGRADED_HARD_FAIL`, and optional `DEGRADED_PROMPT_REQUIRED` from the Step 0a wrapper stdout (ignore unrelated lines). Branch on `STEP0_STATUS` before any later Step 0 work:

- **`ok`** or **`degraded-one-down`**: proceed to Step 0b sub-step 1 (argv/issue binding). `degraded-one-down` means a prior explicit Continue sentinel exists.
- **`needs-degraded-decision`**: this must be accompanied by `DEGRADED_PROMPT_REQUIRED=true`; the wrapper already printed the explanation block. Fire `AskUserQuestion` with **Continue (reduced panel: unavailable tools dropped, no cross-tool or Claude padding)** / **Abort**; on **Continue**, write `$DESIGN_TMPDIR/.degraded-tools-gate-prompted` and proceed with reduced-panel dispatch; on **Abort**, run:

```bash
"$HOME/.cache/larch/sessions/design-run-$PPID.sh" step0-abort-cleanup \
  --reason 'external tool unhealthy; re-run once it recovers.' \
  --tool degraded-tools-gate
```

and stop (run no further steps). The explicit flags match the degraded-tools fallback defaults for backward-compatible launcher reuse. Any non-degraded abort or operator-postpone path that reuses `step0-abort-cleanup` must pass caller-specific `--reason` and `--tool` values; for example, pass `--reason 'operator postpone; resume later' --tool operator-postpone`. Without explicit flags, the verb falls back to degraded-tools messaging even when tools are healthy. **`degraded-both-down-hard-fail`** stops the skill in every mode with no Continue path. The `.degraded-tools-gate-prompted` sentinel is created only after an explicit Continue on the one-down path, and stale sentinels never permit both-down continuation.

From character-ai/larch, MIT.

More from character-ai/larch