jackherd 0.0.1 → 1.0.0

package/kit/workflow/skills/orchestrate/handover/decision.ts

@@ -0,0 +1,247 @@
+/** The herdr agent in the coordinator's pane, as one `herdr agent list` entry shows it. */
+export type PaneAgent = { status: string; sessionId: string | null; name: string | null; seq: number }
+
+/** One look at the pane: its agent, no agent at all, or a listing that could not be read. */
+export type PaneReading =
+  | { kind: 'agent'; agent: PaneAgent }
+  | { kind: 'none' }
+  | { kind: 'unreadable'; reason: string }
+
+/** The herdr agent states the hand-over acts on; herdr knows more (`unknown`), which count as not ready. */
+const AGENT_STATUS = { idle: 'idle', done: 'done', working: 'working', blocked: 'blocked' } as const
+
+export const HANDOVER_PHASE = {
+  waitIdle: 'waitIdle',
+  waitSession: 'waitSession',
+  waitWork: 'waitWork',
+  finished: 'finished',
+  aborted: 'aborted',
+} as const
+
+/** Since when the agent has been ready without a new `state_change_seq`. */
+type Quiet = { since: number; seq: number }
+
+type WaitIdle = {
+  phase: typeof HANDOVER_PHASE.waitIdle
+  since: number
+  sessionId: string
+  name: string | null
+  quiet: Quiet | null
+}
+type WaitSession = { phase: typeof HANDOVER_PHASE.waitSession; since: number; sessionId: string; name: string | null }
+type WaitWork = { phase: typeof HANDOVER_PHASE.waitWork; since: number; sessionId: string }
+type Waiting = WaitIdle | WaitSession | WaitWork
+
+export type HandoverState =
+  | Waiting
+  | { phase: typeof HANDOVER_PHASE.finished }
+  | { phase: typeof HANDOVER_PHASE.aborted; reason: string }
+
+/** `send` restores the herdr name first when `rename` carries one. */
+type HandoverAction =
+  | { kind: 'wait' }
+  | { kind: 'clear' }
+  | { kind: 'send'; rename: string | null }
+  | { kind: 'finish' }
+  | { kind: 'abort'; reason: string }
+
+type HandoverStep = { state: HandoverState; action: HandoverAction }
+
+export type HandoverOptions = { pane: string; send: string; log: string; foreground: boolean }
+
+/**
+ * `settleMs`: how long the agent stays ready with the same `state_change_seq` before `/clear`, so
+ * the turn that started the script has really ended. The timeouts bound each wait in milliseconds.
+ */
+export const HANDOVER_TIMING = {
+  pollMs: 1000,
+  settleMs: 3000,
+  idleTimeoutMs: 15 * 60_000,
+  clearTimeoutMs: 60_000,
+  workTimeoutMs: 60_000,
+} as const
+
+const DEFAULT_HANDOVER_LOG = '.claude/handover/coordinator.log'
+
+const READY_STATUS = new Set<string>([AGENT_STATUS.idle, AGENT_STATUS.done])
+const STARTED_STATUS = new Set<string>([AGENT_STATUS.working, AGENT_STATUS.blocked])
+
+const PHASE_TIMEOUT_MS: Record<Waiting['phase'], number> = {
+  waitIdle: HANDOVER_TIMING.idleTimeoutMs,
+  waitSession: HANDOVER_TIMING.clearTimeoutMs,
+  waitWork: HANDOVER_TIMING.workTimeoutMs,
+}
+const NO_AGENT = 'no agent in the pane'
+const UNEXPECTED_LISTING = 'unexpected herdr agent list'
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null
+
+const stringOrNull = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null)
+
+const toPaneAgent = (entry: Record<string, unknown>): PaneAgent | null => {
+  const { agent_status: status, state_change_seq: seq, agent_session: session, name } = entry
+  if (typeof status !== 'string' || typeof seq !== 'number') return null
+  return { status, sessionId: isRecord(session) ? stringOrNull(session.value) : null, name: stringOrNull(name), seq }
+}
+
+/** Finds the agent of one pane in the JSON of `herdr agent list`. */
+export const paneAgentOf = (listing: unknown, pane: string): PaneReading => {
+  const agents = isRecord(listing) && isRecord(listing.result) ? listing.result.agents : undefined
+  if (!Array.isArray(agents)) return { kind: 'unreadable', reason: UNEXPECTED_LISTING }
+  const entry = agents.find((candidate) => isRecord(candidate) && candidate.pane_id === pane)
+  if (entry === undefined) return { kind: 'none' }
+  const agent = toPaneAgent(entry)
+  return agent ? { kind: 'agent', agent } : { kind: 'unreadable', reason: UNEXPECTED_LISTING }
+}
+
+export const startHandover = (
+  reading: PaneReading,
+  now: number,
+): { ok: true; state: HandoverState } | { ok: false; reason: string } => {
+  if (reading.kind === 'none') return { ok: false, reason: NO_AGENT }
+  if (reading.kind === 'unreadable') return { ok: false, reason: reading.reason }
+  const { sessionId, name } = reading.agent
+  if (sessionId === null) {
+    return {
+      ok: false,
+      reason: 'the agent reports no session id, so a cleared chat could not be told from the old one',
+    }
+  }
+  return { ok: true, state: { phase: HANDOVER_PHASE.waitIdle, since: now, sessionId, name, quiet: null } }
+}
+
+const stay = (state: HandoverState): HandoverStep => ({ state, action: { kind: 'wait' } })
+
+const abort = (reason: string): HandoverStep => ({
+  state: { phase: HANDOVER_PHASE.aborted, reason },
+  action: { kind: 'abort', reason },
+})
+
+const minutes = (milliseconds: number): number => milliseconds / 60_000
+const seconds = (milliseconds: number): number => milliseconds / 1000
+
+/** The one place that decides whether a wait has run out, whatever the pane showed meanwhile. */
+const isPastTimeout = (state: Waiting, now: number): boolean => now - state.since > PHASE_TIMEOUT_MS[state.phase]
+
+const stepWaitIdle = (state: WaitIdle, agent: PaneAgent, now: number): HandoverStep => {
+  if (agent.sessionId !== null && agent.sessionId !== state.sessionId) {
+    return abort(`the session changed before /clear was sent (${state.sessionId} → ${agent.sessionId})`)
+  }
+  if (isPastTimeout(state, now)) {
+    return abort(`the agent was not idle within ${minutes(HANDOVER_TIMING.idleTimeoutMs)} min`)
+  }
+  if (agent.sessionId === null) return stay(state)
+  if (!READY_STATUS.has(agent.status)) return stay({ ...state, quiet: null })
+  if (state.quiet === null || state.quiet.seq !== agent.seq)
+    return stay({ ...state, quiet: { since: now, seq: agent.seq } })
+  if (now - state.quiet.since < HANDOVER_TIMING.settleMs) return stay(state)
+  return {
+    state: { phase: HANDOVER_PHASE.waitSession, since: now, sessionId: state.sessionId, name: state.name },
+    action: { kind: 'clear' },
+  }
+}
+
+const sessionTimeoutReason = (state: WaitSession, sessionId: string | null): string => {
+  const limit = seconds(HANDOVER_TIMING.clearTimeoutMs)
+  if (sessionId === null) return `the agent reported no session ${limit} s after /clear`
+  if (sessionId === state.sessionId)
+    return `the session is still ${state.sessionId} ${limit} s after /clear: the chat was not cleared`
+  return `the new session ${sessionId} was not ready within ${limit} s`
+}
+
+const stepWaitSession = (state: WaitSession, agent: PaneAgent, now: number): HandoverStep => {
+  const { sessionId } = agent
+  if (sessionId !== null && sessionId !== state.sessionId && READY_STATUS.has(agent.status)) {
+    const rename = state.name !== null && agent.name !== state.name ? state.name : null
+    return { state: { phase: HANDOVER_PHASE.waitWork, since: now, sessionId }, action: { kind: 'send', rename } }
+  }
+  return isPastTimeout(state, now) ? abort(sessionTimeoutReason(state, sessionId)) : stay(state)
+}
+
+const stepWaitWork = (state: WaitWork, agent: PaneAgent, now: number): HandoverStep => {
+  if (agent.sessionId !== null && agent.sessionId !== state.sessionId) {
+    return abort(`the session changed again after the command (${state.sessionId} → ${agent.sessionId})`)
+  }
+  if (agent.sessionId !== null && STARTED_STATUS.has(agent.status)) {
+    return { state: { phase: HANDOVER_PHASE.finished }, action: { kind: 'finish' } }
+  }
+  if (isPastTimeout(state, now)) {
+    return abort(`the agent did not start working within ${seconds(HANDOVER_TIMING.workTimeoutMs)} s of the command`)
+  }
+  return stay(state)
+}
+
+/**
+ * One poll of the hand-over: wait until the agent settled, clear, wait for a new session, send the
+ * command, wait for its turn. An unreadable listing waits, but never past the phase's timeout.
+ */
+export const handoverStep = (state: HandoverState, reading: PaneReading, now: number): HandoverStep => {
+  if (state.phase === HANDOVER_PHASE.finished || state.phase === HANDOVER_PHASE.aborted) return stay(state)
+  if (reading.kind === 'none') return abort(NO_AGENT)
+  if (reading.kind === 'unreadable') {
+    return isPastTimeout(state, now)
+      ? abort(`herdr could not be read (${reading.reason}) until the ${state.phase} timeout ran out`)
+      : stay(state)
+  }
+  if (state.phase === HANDOVER_PHASE.waitIdle) return stepWaitIdle(state, reading.agent, now)
+  if (state.phase === HANDOVER_PHASE.waitSession) return stepWaitSession(state, reading.agent, now)
+  return stepWaitWork(state, reading.agent, now)
+}
+
+/** One line for the log: what the pane showed at a step. */
+export const describeReading = (reading: PaneReading): string => {
+  switch (reading.kind) {
+    case 'agent': {
+      const { status, sessionId, name } = reading.agent
+      return `status ${status}, session ${sessionId ?? '(none)'}, name ${name ?? '(none)'}`
+    }
+    case 'none':
+      return 'no agent'
+    case 'unreadable':
+      return `unreadable (${reading.reason})`
+  }
+}
+
+export const manualPath = (pane: string, line: string): string =>
+  `by hand: type /clear in pane ${pane}, then type: ${line}`
+
+const VALUE_OPTIONS = new Set(['--send', '--pane', '--log'])
+
+const readArguments = (argv: string[]): { values: Map<string, string>; foreground: boolean } | { error: string } => {
+  const values = new Map<string, string>()
+  let foreground = false
+  for (let index = 0; index < argv.length; index++) {
+    const option = argv[index]
+    if (option === '--foreground') {
+      foreground = true
+      continue
+    }
+    if (!VALUE_OPTIONS.has(option)) return { error: `unknown option ${option}` }
+    const value = argv[index + 1]
+    if (value === undefined) return { error: `${option} needs a value` }
+    values.set(option, value)
+    index++
+  }
+  return { values, foreground }
+}
+
+/**
+ * `--send <line>` is the one input typed into the cleared chat. `--foreground` runs the hand-over
+ * in this process; without it the script detaches a copy of itself and returns.
+ */
+export const parseHandoverOptions = (
+  argv: string[],
+  env: Record<string, string | undefined>,
+): { ok: true; options: HandoverOptions } | { ok: false; error: string } => {
+  const parsed = readArguments(argv)
+  if ('error' in parsed) return { ok: false, error: parsed.error }
+  const send = parsed.values.get('--send')?.trim() ?? ''
+  if (send === '') return { ok: false, error: '--send <line> is required' }
+  if (/[\r\n]/.test(send)) {
+    return { ok: false, error: '--send must be one line: a line break would submit the rest as a second input' }
+  }
+  const pane = parsed.values.get('--pane') ?? env.HERDR_PANE_ID
+  if (!pane) return { ok: false, error: 'no pane: run inside herdr (HERDR_PANE_ID) or pass --pane <id>' }
+  const log = parsed.values.get('--log') ?? DEFAULT_HANDOVER_LOG
+  return { ok: true, options: { pane, send, log, foreground: parsed.foreground } }
+}

package/kit/workflow/skills/orchestrate/handover/index.ts

@@ -0,0 +1,171 @@
+// Hands the coordinator over to a fresh chat, shipped by jackherd. Run from the
+// coordinator's own Bash call: it detaches a copy of itself and returns, the copy waits until the
+// coordinator's pane is idle, sends /clear, checks that a new session runs and then types the
+// command. Every step goes to the log; an abort also names the way by hand and shows a herdr notice.
+import { spawn } from 'node:child_process'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import {
+  describeReading,
+  HANDOVER_TIMING,
+  type HandoverOptions,
+  type HandoverState,
+  handoverStep,
+  manualPath,
+  type PaneReading,
+  paneAgentOf,
+  parseHandoverOptions,
+  startHandover,
+} from './decision'
+
+type HerdrResult = { ok: true; stdout: string } | { ok: false; error: string }
+
+const EXIT = { done: 0, aborted: 1, usage: 2 } as const
+
+const ABORT_TITLE = 'Hand-over aborted'
+
+const herdr = async (args: string[]): Promise<HerdrResult> => {
+  try {
+    const child = Bun.spawn(['herdr', ...args], { stdout: 'pipe', stderr: 'pipe' })
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+    return code === 0 ? { ok: true, stdout } : { ok: false, error: (stderr || stdout).trim() || `exit ${code}` }
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const readPane = async (pane: string): Promise<PaneReading> => {
+  const listed = await herdr(['agent', 'list'])
+  if (!listed.ok) return { kind: 'unreadable', reason: `herdr agent list: ${listed.error}` }
+  try {
+    return paneAgentOf(JSON.parse(listed.stdout), pane)
+  } catch {
+    return { kind: 'unreadable', reason: 'herdr agent list answered no JSON' }
+  }
+}
+
+const writeLog = async (path: string, line: string): Promise<void> => {
+  const time = new Date().toTimeString().slice(0, 8)
+  await appendFile(path, `${time} ${line}\n`)
+}
+
+const sleep = (milliseconds: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, milliseconds))
+
+type Log = (line: string) => Promise<void>
+
+/** Returns the reason of a failed herdr call, or null once `/clear` went out. */
+const sendClear = async (options: HandoverOptions, log: Log): Promise<string | null> => {
+  const cleared = await herdr(['agent', 'prompt', options.pane, '/clear'])
+  if (!cleared.ok) return `herdr agent prompt /clear failed: ${cleared.error}`
+  await log('sent /clear')
+  return null
+}
+
+/** A failed rename is only logged: the name is a convenience, the line is the hand-over. */
+const sendCommand = async (rename: string | null, options: HandoverOptions, log: Log): Promise<string | null> => {
+  if (rename !== null) {
+    const renamed = await herdr(['agent', 'rename', options.pane, rename])
+    await log(renamed.ok ? `renamed the agent to ${rename}` : `rename to ${rename} failed: ${renamed.error}`)
+  }
+  const sent = await herdr(['agent', 'prompt', options.pane, options.send])
+  if (!sent.ok) return `herdr agent prompt failed: ${sent.error}`
+  await log(`sent: ${options.send}`)
+  return null
+}
+
+const showAbortNotice = (reason: string, options: HandoverOptions): Promise<HerdrResult> =>
+  herdr([
+    'notification',
+    'show',
+    ABORT_TITLE,
+    '--body',
+    `${reason}. ${manualPath(options.pane, options.send)}`,
+    '--sound',
+    'request',
+  ])
+
+/** Logs the abort and tells the user through a herdr notice: the coordinator's turn has ended, nobody else would. */
+const finishAborted = async (reason: string, options: HandoverOptions, log: Log): Promise<number> => {
+  await log(`aborted: ${reason}`)
+  await log(manualPath(options.pane, options.send))
+  const notice = await showAbortNotice(reason, options)
+  if (!notice.ok) await log(`notice failed: ${notice.error}`)
+  return EXIT.aborted
+}
+
+const runHandover = async (options: HandoverOptions): Promise<number> => {
+  await mkdir(dirname(options.log), { recursive: true })
+  const log: Log = (line) => writeLog(options.log, line)
+  const initialReading = await readPane(options.pane)
+  const started = startHandover(initialReading, Date.now())
+  if (!started.ok) return finishAborted(started.reason, options, log)
+  await log(`pid ${process.pid}: waiting for pane ${options.pane} to settle (${describeReading(initialReading)})`)
+  let state: HandoverState = started.state
+  while (true) {
+    await sleep(HANDOVER_TIMING.pollMs)
+    const reading = await readPane(options.pane)
+    const { state: next, action } = handoverStep(state, reading, Date.now())
+    if (next.phase !== state.phase) await log(`${state.phase} → ${next.phase}: ${describeReading(reading)}`)
+    state = next
+    let failure: string | null = null
+    switch (action.kind) {
+      case 'finish':
+        await log('delivered: the new session is working on the command')
+        return EXIT.done
+      case 'abort':
+        return finishAborted(action.reason, options, log)
+      case 'clear':
+        failure = await sendClear(options, log)
+        break
+      case 'send':
+        failure = await sendCommand(action.rename, options, log)
+        break
+    }
+    if (failure !== null) return finishAborted(failure, options, log)
+  }
+}
+
+/** The detached copy has no terminal: a crash (a log it cannot write) must still reach the user. */
+const runVisibly = async (options: HandoverOptions): Promise<number> => {
+  try {
+    return await runHandover(options)
+  } catch (error) {
+    await showAbortNotice(
+      `the hand-over script failed: ${error instanceof Error ? error.message : String(error)}`,
+      options,
+    )
+    return EXIT.aborted
+  }
+}
+
+/** Starts this script again in a session of its own, so it outlives the Bash call and the /clear. */
+const detach = async (argv: string[], options: HandoverOptions): Promise<number> => {
+  const started = startHandover(await readPane(options.pane), Date.now())
+  if (!started.ok) {
+    console.error(`hand-over not started: ${started.reason}`)
+    return EXIT.aborted
+  }
+  // node:child_process, not Bun.spawn: only it offers `detached`, a session of the child's own.
+  const child = spawn(process.execPath, [import.meta.path, ...argv, '--foreground'], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: process.cwd(),
+    env: process.env,
+  })
+  child.unref()
+  console.log(`hand-over started: pid ${child.pid}, log ${options.log}`)
+  return EXIT.done
+}
+
+const argv = process.argv.slice(2)
+const parsed = parseHandoverOptions(argv, process.env)
+if (!parsed.ok) {
+  console.error(parsed.error)
+  process.exit(EXIT.usage)
+}
+const options = { ...parsed.options, log: resolve(parsed.options.log) }
+process.exit(options.foreground ? await runVisibly(options) : await detach(argv, options))

package/kit/workflow/skills/plan/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: plan
+description: 'Create structured concept/plan documents for {{kit.planDirectory}}/. Use when planning new features or architectural changes.'
+---
+
+If `.claude/project/plan.md` exists, read it first. It extends this skill for this project (where to look in the pre-scan, which documents carry product context, extra review-gate items) and wins where the two disagree.
+
+You create a structured concept/plan document in `{{kit.planDirectory}}/`.
+
+> **Output language: {{kit.planLanguage}}.** These instructions are English; the plan document is
+> written in {{kit.planLanguage}}. Keep the section headings of the template **verbatim** — the plan
+> parser, `/implement` and `spec-review` find `## {{kit.heading.decisions}}`,
+> `## {{kit.heading.implementation}}` and `## {{kit.heading.documentation}}` by those exact names.
+
+## Your Workflow
+
+### 0. Are the decisions actually made?
+
+A plan records decisions; it is not where they get taken. If the `## {{kit.heading.decisions}}` table would end up holding your guesses rather than the user's answers, **stop and recommend `/grill`** — name the open questions you would otherwise have to invent answers for, and let the user decide whether to run it. Entering clarification mode is the user's call, so you recommend it and leave the invocation to them. It works the questions in rounds and hands back rows in this table's format.
+
+Skip this when the request already carries its decisions (a plan for a bug fix with one obvious approach, a change the user has already specified).
+
+### 1. Pre-Scan (before a single word of the plan is written)
+
+- [ ] Read the relevant files in their **current** state, from disk
+- [ ] Search the project's shared components and utilities for what covers 80%+ of the need. 80%+ match → the plan specifies reuse or an override; 60–80% → the plan extends the shared piece; below 60% → new code, with the rationale under the rejected alternatives
+- [ ] Read related plans in `{{kit.planDirectory}}/` — check dependencies and open TODOs
+- [ ] Read the architecture documentation the change touches — understand what is already documented before you plan
+
+### 2. Create the Document
+
+**Filename:** `{{kit.planDirectory}}/YYYY-MM-DD-<kebab-case-title>.md`
+
+**Structure:** copy the template in [`references/template-{{kit.planLanguage}}.md`](references/template-{{kit.planLanguage}}.md) and fill it in. Every section stays, in its order, with its heading verbatim.
+
+The closing documentation section reads `## N — …` with rows `N.1` to `N.5`: replace `N` with the number of that phase (`## 10 — …`, `10.1`). A literal `N` is no phase to the plans view, which shows it as "not in the plan".
+
+A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The plans view counts it neither as open nor as done in its own phase and lists it as open in phase 9, so a phase whose only open box was moved on reads as finished. The arrow counts only at the end of the line; `jh check` refuses an open box in a changed plan that carries it anywhere else (`- [ ] → P9 Update …`). Once a phase's tasks are ticked on the base branch and the change does not tick it further, every box still open in it, gate boxes included, is ticked or moved on this way: `jh check` warns on a changed plan that leaves one.
+
+What the template's tables mean:
+
+- **Model recommendations per phase** — one row per phase, judged by **error cost × complexity**. The project's default model for implementation (`{{kit.model.implement}}`) is the default of every row. A phase moves up to the planning model (`{{kit.model.plan}}`) when its rationale names a concrete error cost: a breakable invariant, possible data loss, security or tenant isolation, a migration without a way back, distributed state across systems. "Complex" or "many files" alone keeps the default. Review gates with `/security-audit` always get the strongest model.
+- **Dependencies and parallelization** (from three phases) — `/implement` reads it and starts every phase whose dependencies are done and that shares no written path with another, at the same time.
+  - **{{kit.heading.dependsOn}}:** phases of this plan (numbers) or external gates (`User: mockups`). A phase is ready when everything here is done.
+  - **{{kit.heading.writes}}:** the directories or files the phase creates or changes, as narrow as possible. Shared files many phases touch (barrels, translation files, `package.json`, generated types, architecture docs) are listed explicitly, so the overlap is visible.
+  - **{{kit.heading.serialMarker}}:** `Migration`, `<collection> schema bump`, `Event <type>`, a generator run. Two phases with a migration never run at the same time; neither do two that bump the same schema.
+
+### 3. Architecture Review
+
+Apply `/uncle-bob` to the created plan. Additionally check:
+
+- **Interfaces:** Are the boundaries between modules/services clear? Who consumes what?
+- **Blast radius:** Which existing consumers are affected? Are tests needed in all consuming packages?
+
+### 4. Anchor the Review Gate in the Plan
+
+Every phase gets the review gate block from the template at its end. Add the reviewers the project supplement names for its areas (a UI review for UI phases, for instance). A phase with tasks that genuinely needs no gate (documentation only, a draft) says so and why in a line of its own, in the plan's language: `**No review gate:** <reason>` (`en`), `**Kein Review-Gate:** <Grund>` (`de`). `jh check` refuses a phase the change adds with tasks and neither line.
+
+### 5. Quality Checks
+
+- **Focus:** Does the plan solve a concrete problem? No "would be nice to have".
+- **Scope:** Is the scope clearly bounded? No feature-creep risk?
+- **Feasibility:** Can the phases be split into individual PRs/commits?
+- **References:** Are related plans in `{{kit.planDirectory}}/` linked?
+- **Current state is fact-based:** Read code, count files, verify architecture; every claim has a source.
+- **Shared code checked:** For every planned component it is documented why it is built new instead of reused or extended.
+- **Tests defined:** The tests section is filled in or carries an explicit rationale why none are needed (decision tree in `.claude/rules/kit/testing.md`).
+- **Model recommendations defined:** `## {{kit.heading.implementation}}` starts with the model table, one row per phase, justified by error cost × complexity.
+- **Parallelism defined (3+ phases):** the dependencies table follows it. Check it against the phase bodies: every migration, schema bump and new event in a phase appears as a serial marker; every shared file appears under {{kit.heading.writes}}. A dependency that exists only in your head lets `/implement` start two phases that collide.
+- **arc42 check (after the plan exists):** apply the filter in `.claude/rules/kit/arc42.md` to the finished plan and **ask the user concretely** which sections should be extended. On "yes", add a concrete task to `## {{kit.heading.documentation}}`.
+- **Architecture check (after the plan exists):** apply the filter in `.claude/rules/kit/architecture-files.md` — new ownership, a new invariant or an accepted risk each trigger a concrete question about the unit's `ARCHITECTURE.md`.
+- **arc42 closing phase (3+ phases or a new service/package):** end the plan with the architecture documentation phase from the template. Add arc42 sections beyond it only when they deliver real value.
+- **Documentation planned:** `## {{kit.heading.documentation}}` names concretely what will be created or updated after completion.
+
+### 6. Propose the board rows
+
+A **board** gathers the lanes one coordinator runs with `/orchestrate`: `{{kit.board.file}}` in a directory
+matching `{{kit.planDirectory}}/{{kit.board.pattern}}` (this project calls it a "{{kit.board.term}}"). The plan
+already holds what a lane row needs, so end by proposing the rows; `/orchestrate` then starts the lanes from them.
+Skip this step for a plan of one phase that nobody runs as a lane, and say so.
+
+Derive the rows from the dependencies table and the model table, nothing else:
+
+- **Own lane:** a phase that can run beside the others: no path under {{kit.heading.writes}} in common with a phase
+  of another lane, and no serial marker that another lane carries at the same time.
+- **Continuation:** a phase that shares a written path or a serial marker with an earlier phase, or depends on it,
+  is a `↳` row under that phase's lane, in the same worktree.
+- **Starts after:** from the phase's {{kit.heading.dependsOn}} cell, as the board reads it (`P2 merged`, an external
+  gate such as `User: mockups`); a phase without one starts at once.
+- **Model:** the full model ID from the model table (`{{kit.model.implement}}`, `{{kit.model.plan}}`), never an alias.
+- **Plan:** a Markdown link to the plan, its path relative to the board's directory (`../<file>.md` for a plan
+  directly under `{{kit.planDirectory}}`).
+  Plans stay where they are; the row only links them.
+- **Lane name:** short kebab case, unique on the board. `/orchestrate` names the worktree directory and the herdr
+  agent after it, so the worktree directory and the herdr agent carry the same name; a name that differs leaves the
+  watcher reporting the lane as `no agent`.
+- **Port:** `–`; the coordinator sets it when the lane starts, unless the project supplement assigns ports here.
+
+Show the rows as the table they become: `## {{kit.heading.lanes}}` with the columns lane, port, plan, phases, starts
+after, model, in this order and headed in {{kit.planLanguage}} (the plans view reads them by position). Then ask
+where they go:
+
+- **The newest board**, by name: the newest `{{kit.planDirectory}}/{{kit.board.pattern}}/{{kit.board.file}}`. The
+  rows are appended to its `## {{kit.heading.lanes}}` table.
+- **A new board.** Ask for its name and propose one: the year and month or the topic, in the pattern's shape. Check
+  that the directory name matches `{{kit.board.pattern}}` before writing; if it does not, say why and ask again.
+  Create `{{kit.planDirectory}}/<name>/{{kit.board.file}}` with a `#` title and the `## {{kit.heading.lanes}}`
+  table holding the proposed rows.
+- **Not now:** the rows stay in your answer, for `/orchestrate` to write when it starts the lanes.
+
+Nothing is written without that answer. The board is a file like the plan: it goes into the same commit, under the
+same approval.
+
+After writing the rows, name the next step in one line: `/orchestrate <board path>`, from a Claude Code session
+inside herdr. A plan or board that is not on `origin/{{kit.baseBranch}}` yet needs no merge first: `/orchestrate`
+asks to commit it on a documentation branch and starts the lanes from there.
+
+Ask every question with a fixed set of answers through the `AskUserQuestion` tool, in {{kit.responseLanguage}}.

package/kit/workflow/skills/plan/references/template-English.md

@@ -0,0 +1,92 @@
+# Title
+
+**{{kit.heading.date}}:** YYYY-MM-DD
+**{{kit.heading.status}}:** Draft / In Progress / Done / Abandoned
+**{{kit.heading.scope}}:** `affected/paths`
+
+## Problem / Context
+
+What is the trigger? Why now? One paragraph.
+
+## Current State
+
+Fact-based: code analysis, file counts, current architecture. Tables preferred.
+
+## Target State
+
+What changes concretely? Files, modules, flows.
+
+## {{kit.heading.decisions}}
+
+| Decision | Rationale |
+| -------- | --------- |
+
+## {{kit.heading.implementation}}
+
+### {{kit.heading.modelRecommendations}}
+
+| {{kit.heading.phase}} | Model | Rationale |
+| ----- | ----- | --------- |
+| 1 — ... | {{kit.model.implement}} | Error cost × complexity |
+
+> **Applying the models:** `/implement` applies this table on its own (step 0, model gate): it runs every phase whose recommendation differs from the running model through a subagent with the recommended model, in both directions. Whoever implements **without** `/implement` sets the model themselves at the start.
+
+### {{kit.heading.dependencies}}
+
+| {{kit.heading.phase}} | {{kit.heading.dependsOn}} | {{kit.heading.writes}} | {{kit.heading.serialMarker}} |
+| ----- | ------------ | -------- | -------------- |
+| 1 — ... | — | `path/to/module/` | Migration |
+| 2 — ... | 1 | `other/module/` | — |
+
+> **Applying the parallelism:** `/implement` starts ready phases without a shared written path and without colliding serial markers at the same time (step 0b), each with its model from the table above. Whoever implements without `/implement` reads here which sessions may run in parallel.
+
+### {{kit.heading.phase}} 1: ...
+
+- [ ] Step 1
+- [ ] Step 2
+
+**Review gate {{kit.heading.phase}} 1:**
+
+- [ ] Pre-scan: [the files and modules to read before starting]
+- [ ] Implementation complete and committable
+- [ ] Tests written (or the reason none are needed)
+- [ ] `/uncle-bob` — Clean Architecture review
+- [ ] Documentation updated or created
+- [ ] Plan and roadmap in sync
+
+## Tests
+
+Which tests are needed? Decide with the decision tree in `.claude/rules/kit/testing.md`.
+
+| File | Kind | Why |
+| ---- | ---- | --- |
+
+> No tests needed → give the reason explicitly (e.g. "layout only, no logic branch").
+
+## {{kit.heading.documentation}}
+
+What gets documented after completion?
+
+- [ ] ...
+
+## Rejected Alternatives
+
+| Idea | Reason |
+| ---- | ------ |
+
+## Risks
+
+| Risk | Severity | Mitigation |
+| ---- | -------- | ---------- |
+
+## N — Architecture documentation (arc42 light)
+
+> After the implementation: derive the architecture docs from the finished code.
+
+| #   | Task | Status |
+| --- | ---- | ------ |
+| N.1 | Context: external systems and interfaces | ⬜ |
+| N.2 | Building blocks: services, packages, apps | ⬜ |
+| N.3 | Runtime: significant flows as sequence diagrams | ⬜ |
+| N.4 | Decisions: ADRs from the decisions table | ⬜ |
+| N.5 | `ARCHITECTURE.md` of the touched units: new invariants and risks | ⬜ |