sidequest

---
name: sidequest
description: >-
  Use for delegated work and board lifecycle; small bounded fixes may stay inline without a ticket. Use for
  tickets, board lifecycle, planning substantial or ambiguous work, and dispatch/integration/recovery.
---

# sidequest

A central ticket store (`~/.claude/sidequest`), live Kanban dashboard, CLI (`bin/sidequest.js`) and
matching MCP tools. Read references only when needed:

- `references/orchestration.md` — decomposition depth, fan-out waves, checkpoints, background
  execution, cost levers, agent teams.
- `references/experiment-loop.md` — oracle rounds, branches, verdicts, promotion.
- `references/publishing.md` — delivery modes, publish transaction.
- `references/routing-details.md`, `references/routing-guide.md` — routes and wiring.
- `references/high-stakes.md`
- `references/external-trackers.md`, `references/board-features.md`, `references/category-links.md`, `references/ticket-authoring.md`, `references/invocation-contracts.md`.
- `references/readonly-guidance.md` — candidate reviews, repository audits, shortcut debt, and measurement claims.
- `references/external-trackers.md` — ticket `refs`, `add --github`.

For a bounded catch-up list, use MCP `changes {since, view:"catchup"}` or CLI `changes --since <iso> --catchup`, which lists only changed tickets with their stage and next action.

## Choose one owner before adding ceremony

Before dispatching substantial or ambiguous work, pin a contract; see `user-story`. Check feasibility
before expensive implementation or tests for substantial/safety-sensitive work
(`references/ticket-authoring.md`). Small deterministic fixes keep one owner and a focused check;
a plan advisor needs a named architectural risk or contested approach, no mandatory panel.

For substantial work:

0. **One owner by default.** A bounded fix keeps one owner and a focused check; a small fix in a few known files may run inline without a ticket. Read-only investigations need no ticket: on a routed project spawn `route_recipe(category).research` so they run on the category route; native Explore only for unrouted projects.
1. **Story or wave only with a reason.** Require 3+ independently checkable pieces and a stated reason for separate owners. Pin shared interfaces, file boundaries and per-piece verification, then file the complete backlog under a Sidequest story. One-ticket mode stays story-less. A review panel needs a named risk for each lens.
2. **Link dependencies** (`link SQ-4 depends-on SQ-3`); shape a story as design → wave(s) →
   integrate so `ready` serializes the phases.
3. **File the whole planned wave backlog before dispatching.** Give every ticket scope, dependencies, and
   per-ticket verification; dispatch each ready wave concurrently. Do not drip-file a serial chain.

   Dispatch independent pieces together only after the story or wave meets that threshold.
4. **Execute proportionally** — "Route execution down" below.

Trace the real flow, question necessity, then reuse local code, stdlib, native features or installed
dependencies before fixing the shared root. Prefer measured deletion; avoid hypothetical guards,
compulsory extractions and unrelated cleanup. Preserve trust-boundary validation, data-loss prevention,
accessibility, permissions and immutable candidate/review authority.

Answer direct questions and operational requests inline. Small bounded fixes in a few known files may stay inline without tickets; read-only investigations use `route_recipe(category).research` as above.

Isolated dispatches, read-only included, base at the recorded integration branch under the board's `worktreeBase` policy, and the dispatch result, spawn prompt and briefing name that base commit and branch. Read-only shared-checkout Git access and its write boundaries are in `references/readonly-guidance.md`.

### INLINE-SAFE direct work

If inline-safe work was already ticketed, the orchestrator may claim `--direct` and edit inline after annotating the ticket, giving a 20+ character reason, and matching this allowlist:

- A failing integration gate pinpoints an exact, known small diff: a strict-TS null guard, an
  assertion string synced after a deliberate reword, byte-checked golden regeneration, or a
  merge-conflict resolution that preserves both sides' intent.
- Release bookkeeping: release fragments, the cut flow, or closing tickets with evidence.
- A small bounded fix in a few files at known locations, with a focused check.

`direct-ok` is a user signal that gates nothing. Use routed execution when the work exceeds the small bounded path or needs an independent candidate review; dispatched executors keep their claim, scope, verification and submission lifecycle.

## MCP is the executor board interface

Routed executors use **only** the `mcp__plugin_sidequest_board__*` tools for their lifecycle
(`commit`/`submit` take the executor's absolute worktree path). Missing tools → report the
blocker and release through an available board tool, never a command-line fallback.

MCP is the normal interface for board admin/config; the CLI is fallback for git-context operations.
Apply board-only admin changes directly through an available MCP tool, never as a ticket or dispatch. Live
category/profile edits affect only that board, not installation defaults unless the user asks. After a
schema-bumping release, reload plugins before MCP writes. Commands default to the current project;
`--project "<path-or-slug>"` (MCP: `project`) targets another board (creation rules: `references/board-features.md`).

`dispatch <ref>` is **instant**: it returns the ticket's stable executor, a short `spawn` fetch
stub, and a token. Pass every supplied `spawn` field (`name` and `description` too) to Agent
unchanged. Set `Agent.description` to `spawn.description` byte-for-byte, never derived from the
prompt, route marker, title, model, or effort. The executor fetches its
token-gated durable packet as the first action: full description, anchors, category route and contract, scope,
state, comment metadata, and absolute attachment paths. It must inspect every readable
attachment and report missing or unreadable ones, while the spawn keeps that content out of this
transcript. Never trust a worker's self-report — the
claim's token and exact executor name are the evidence.

**Workflow callers:** call `route_recipe` or `sidequest route <category> --json`; wire only `recipe.agent` in Agent: `model` and `subagentType` when set, `promptPrefix + prompt`. Never hand-translate route, gateway, marker or effort fields. For a ticketless read-only investigation spawn `recipe.research` (`references/routing-guide.md`). A user-named model for one ticket is that ticket's `route` override; never edit the category route (`references/routing-guide.md`).

**Locations:** CLI: `plugins/sidequest/bin/sidequest.js`; DB: `~/.claude/sidequest/sidequest.db`
(`SIDEQUEST_HOME`). Never scan from root.

## Routing profiles

A board selects one profile plus local ADD/OVERRIDE/DETACH/DISABLE rows. Mutations take one of
`--profile`/`--project`; details: `references/routing-details.md`. Category `readonly` selects the
restricted executor and `done` closeout. `--readonly` and `--no-shared-tree` override a prepared dispatch.
Read-only files or changes warn before dispatch. Resolve or override.

## Open the dashboard

`sidequest dashboard` starts the local server and prints the URL. Verify server changes in an isolated
`SIDEQUEST_HOME` on another port, never the shared board.

## File a ticket

`sidequest add -t "Contact form does not send" -d "..." --category <id>` — read the live taxonomy
(`category_list` MCP / `sidequest category list --json`), choose by description and persist its ID.
Use the fallback only when no category fits. `--complexity` is legacy ambiguity fallback;
never set `--model`/`--effort`. Scope, anchors, stories and exact verify: `references/ticket-authoring.md`.

Descriptions/comments render markdown with real newlines, never literal `
`. File a mid-task side issue
with `mcp__plugin_sidequest_board__add` and keep going; filing a ticket is not a request to work it.

## List / update / close

`sidequest list` (this project; `--status todo` for one column) · `projects` (every board) ·
`update SQ-3 --status done` (move; also `-p -t -d -l`) · `rm SQ-3` (delete). `--json` reads data;
`--brief` on `list`/`ready` implies `--json` and drops bodies. **Default to
`--brief` for routine orchestration reads.** "Close / ship it" → `--status done`.

## Work a ticket (safe with other agents)

The board may be shared: claim a ticket before touching it, atomically. **Never work a ticket you
haven't successfully claimed**, even one you just filed.
Lifecycle (executors use the matching MCP tools; CLI forms for inline/admin work):
`next`/`claim SQ-3 --by <you> --direct --reason "why this is inline-safe"` (only for the
INLINE-SAFE allowlist) → `commit` (declared ticket paths only) → run the briefing-supplied `verify-capture` wrapper after the final commit (it records the ticket, command, and checked candidate) → `submit --commit <hash> --verify
"<declared cmd>"` (parks the verified LOCAL commit). Retyped commands or prose cannot replace that capture. Manual and attestation verifiers keep their evidence flow.
or `done --model <model> --effort <level>` (inline/non-repo only) or `release` (drop unfinished,
optionally `--status todo`).

- **`--by` must be genuinely unique to this session** — a random token generated once (e.g.
  `claude-<8 hex>`); a generic label lets two sessions silently coexist as one worker.
- **If a claim fails, do not work that ticket.** Retry a denied or unclaimed spawn only when `pulse <ref>`
  shows a changed dispatch condition; otherwise record the refusal and surface it to the user. Never both
  resume a prior executor and spawn a fresh one for the same ticket.
- **Read the thread before working a ticket** (`sidequest comments <ref>`). Default reads retain all
  metadata; pass `--full` only for needed elided bodies.
- **Claims release on observed death, not age**: use `pulse`, never a clock. For work needing a decision, `SendMessage` the same agent. If its name fails, only the ORIGINAL matching host session may send once to authentic `dispatch.agentId` or its exact original Agent-returned identifier; never `claim.by` or a guessed/replacement address. Honor user Pause retries. Missing/mismatched identity stays continuation UNVERIFIED; preserve claim/work. A resume keeps claim, token-file path, and worktree binding. Queued/unknown/completed/absent/failed-send is not death. Never restart terminal executors; confirmed death requires salvage before replacement. Lost binding and died-before-claim recovery: `references/orchestration.md`.
- Agents report automatically. **Never use `TaskOutput`** for a Sidequest task ID or launch name. Liveness comes only from `pulse <ref>` and `changes --since`, read on a notification or user prompt, never right after spawning; a process list is never dispatch evidence. **No TaskStop after terminal evidence**: an executor ends its own run at submit, done, or release. `TaskStop({ task_id: "<agent name>" })` once is host cleanup only for a terminal ticket whose executor the host still lists running (host action, not Sidequest). Never stop a live claim, retained continuation, or candidate awaiting integration; never wake a completed executor or build a cleanup loop. **Never proxy-wait** with a shell/`Monitor`/cron task for an executor or artifact (a one-shot local readiness watch is fine).

**Publishing belongs to the orchestrator:** executors stop at terminal `submit`. Integration measures the exact delivery tree with the configured quality gate and refuses measured failures. UNVERIFIED rows record debt automatically. Executors need no capture import. See `references/publishing.md`. Read `completion <ref>` for the human account of a finished ticket.

**BOOKEND SUPERVISION.** Avoid routine mid-flight reads and peeks; bounded live advice follows `references/readonly-guidance.md`, and integration uses the submit report and merged-tree gate, with independent review when needed.

## Route execution; keep the loop tight

Use read-only recon to pin the improvement, benefit, approach, and boundaries before routing;
routes select execution capacity, not product decisions. Investigations return compressed findings
(~1–2k tokens) as comments. Dispatch implementation fresh; executors own their tickets.
Direct claims require an INLINE-SAFE reason (20+ characters); they cannot legitimize prior investigation.
Native `Explore`, `claude-code-guide`, `Plan`, `statusline-setup`, and any general-purpose or custom
agent whose prompt and description carry no write intent run without a ticket. Ticket refs, route
markers, executor types, and resumed denied writes need a prepared dispatch.

**Loop:** spawn a wave, read executor reports and verified submissions, run each ticket's scoped
verification, then publish with one full-suite gate. Re-plan for the next wave.
Don't accept a green suite as proof of coverage; review execution evidence.
**The ticket is the spec:** include outcome, benefit, approach, boundaries, and implementation detail.
Spawn prompts add logistics; carry the full ticket contract without narrowing it.
**Keep useful work:** retain claims and checkpoints, await `SendMessage` steering for questions or
failed checks, and release only on confirmed death or unsalvageable blockers.
Batch small same-model tickets in one executor, never mix models. Parallel waves spawn one executor
per ticket in a single message.

**Ready** = unclaimed, unblocked, not done, not archived — `sidequest ready --json
--brief` lists exactly this set, partitioned into **parallel-safe waves** by declared file scope.
Fan out one wave at a time; worktrees isolate files, not runtime resources (ports, servers,
databases), so serialize those collisions even inside a wave. A claim under a `--by` you don't
recognize means another session may be working the board; flag it first. With
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` on, executors ARE teammates — use the teammate
affordances, don't ignore them: answer scope requests over the mailbox, steer and resume with
`SendMessage`, and never stop→redispatch work a message can fix. Wave mechanics,
liveness, salvage, cost levers, agent teams:
`references/orchestration.md`.

## Category-first routing (ENFORCED)

Sidequest owns ticket routing. Do not recreate a standalone Switchboard (a split-out router could
only ever be a shared library imported by Sidequest). The live taxonomy is the routing authority:
classify from it, persist the ID, and the category route resolves model and effort — never
hand-pick either. Legacy complexity maps to bands at read time (1–3/4–6/7–10 →
`coding.easy`/`normal`/`hard`) without persisting a category.

1. **Classify before claim.** A `category: null` ticket gets stamped via `update --category <id>`
   **before** claim or spawn, then re-read. Reads never silently persist a classification.
2. **Trust the category projection.** Inject the read's category contract verbatim into the spawn
   prompt alongside the ticket contract; do not narrow, rewrite, or invent around it.
3. **The ticket read tells you exactly what to spawn.** Print `SQ-n · category · Model · effort`,
   then spawn the exact `agent` a fresh `dispatch <ref>` returned through native Agent,
   pass returned fields unchanged. If Agent omits `name`/`mode`, dispatch `reducedAgentSchema: true`; don't
   restore them. First claim: hook `agent_id` + `permission_mode: auto|bypassPermissions`. **Claude routes**:
   `model: exec.model` (otherwise it inherits the pricey session model), including Haiku. Use the dispatched
   executor/model, never generic Agent. **Codex routes** (`exec.model` null): omit `model`; the route marker
   carries the real model and any value runs Anthropic. Effort is verbatim; mismatched claims are refused.
   Details: `references/routing-details.md`.
4. **Claim by resolved route:** `next --model X` / `ready --model X` filter by resolved route.

## Comments

`comment SQ-3 -m` (durable handoff, keep working) · `comments SQ-3` (read the thread).
**Comments are cross-actor handoffs**: decisions, constraints, ruled-out approaches, risks, exact
verification command/result, concise findings. **Write findings back after an investigation**: root
cause with evidence (`file:line`), the fix, verification.

## Link tickets

`sidequest link SQ-4 depends-on SQ-3` (stored on both sides) · `blocks` · `related` (non-blocking) ·
`unlink` removes. A blocked ticket is skipped by `next` and excluded from `ready`.

## Guidelines

**Act, then report** the result (ref, status, or URL). **Keep titles tight**; detail goes in `-d`.
**Don't invent tickets**: only file what the user raised. Reminders, stories, human assignment:
`references/board-features.md`.


## Frozen work provenance

Only the main thread can set MCP `dispatch.workProvenance` before preparation. Its `kind` is
`new-behavior`, `behavior-preserving-refactor`, `inherited-read-only`, `docs`, `type-annotation-only`,
`fixture-only` or `builds-on` (a follow-up carrying pending submitted candidates whole; see `publishing.md`). Each source names a native producer ref, its exact `preparedAt` (current dispatch
or an archived attempt) and an immutable owned `commit`, optionally a `captureId`. Missing
`baseCommit`/`sanctionedCommits` derive from its captures; ambiguity, other gaps or a
submission naming another candidate refuse by name. The board freezes base, scope, byte
and capture identity. The source stays unaccepted on its producer.

Unchanged inherited work and a declared GREEN behavior-preserving refactor do not need invented
new reds. New owned behavior keeps its own control requirements. Source/test byte drift, changed
producer generations, incompatible captures, worker self-grants and late declarations refuse.
The declaration is factual provenance only: execution, quality and admission remain UNVERIFIED.
It cannot rebind an old receipt or exempt held authored code. While its sources match, the
dispatch submits normally with the frozen record; integration runs the pinned verifier.

• SKILL.md 18 KB
• references/board-features.md 5 KB
• references/category-links.md 3 KB
• references/experiment-loop.md 4 KB
• references/external-trackers.md 4 KB
• references/high-stakes.md 1 KB
• references/invocation-contracts.md 15 KB
• references/orchestration.md 79 KB
• references/orchestrator-checkpointing.md 2 KB
• references/publishing.md 49 KB
• references/readonly-guidance.md 6 KB
• references/routing-details.md 9 KB
• references/routing-guide.md 9 KB
• references/ticket-authoring.md 10 KB