Sidequest

sidequest

A Trello-light quest log: tickets in a central store under ~/.claude/sidequest, a live Kanban dashboard, one CLI (bin/sidequest.js), matching MCP tools. Detail lives in reference files — read them only when the situation calls for it:

• 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.

Plan substantial work on the board first

Before dispatching substantial or ambiguous work, pin a contract; see user-story.

For substantial work:

0. solo-fit gate. SOLO-FIT picks one-executor vs wave; it NEVER means you implement inline. Small coherent work gets one ticket and one executor. A multi-item unpinnable contract needs concurrent read-only investigation tickets, one investigation ticket per independent item; findings pin a separate fix wave. One combined ticket is only for exactly one item or a provably single defect. “Feels coupled” is not evidence: file planning first.

1. Ticket shape. If a written spec pins shared types/interfaces, file boundaries, and per-piece verification, 3+ independently checkable pieces use contract-first fan-out: pin the contract in ticket descriptions or a short planning ticket, then one parallel wave on category-appropriate routes and integrate once per wave. Wave mode REQUIRES a Sidequest story first (sidequest story add, then --story US-n per piece): file the complete backlog under it and pin the execution contract on it. A story is Sidequest's own US-n grouping, not a Claude Code feature. One-ticket mode stays story-less; use stories for shared outcomes or dependencies. Cut along affected surfaces: store, CLI, MCP surface, skill/docs, and applicable full test directory. Tickets carry anchors, contract, and a scoped verify. Use directory scope for the blast radius; details: references/ticket-authoring.md.

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.

   Parallel-first: Split independent audits, migrations, and reviews into per-item or shard tickets. Dispatch concurrently despite isolated-worktree overlap; large sweeps skim invisibly. Keep sequential/shared-design work together; size shards by items and verify cost.

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.

Complexity 4+ needs scope, anchors, and a scoped verify; the merged tree runs the full suite once.

Do stated one-line mechanical edits to 1–2 named files inline before solo-fit or ticketing. Bounded recon (Read, Glob, Grep on named anchors, one narrow sweep) stays inline; unfamiliar paths or deep investigation go through the live taxonomy.

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.
• The existing user-directed one-or-two-named-file carve-out above, unchanged.

direct-ok may remain as a user signal, but it gates nothing. Never inline work that needs investigation or other-file reading to be confident, adds behavior or an API, or has a failing test that does not pinpoint the exact location. "Context already loaded", "small change", and "faster myself" are invalid reasons. File a ticket and dispatch its executor instead. The blocked-step and never-inline invariants still apply to substantive work. Coexisting with an external tracker: references/external-trackers.md.

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.

dispatch <ref> is instant: it returns the ticket's stable executor, a short spawn fetch stub, and a token. Its subagent_type ships in the plugin, before SessionStart. Pass every supplied spawn field (name and description too) to Agent unchanged. Set Agent.description to spawn.description byte-for-byte, never deriving it from spawn.prompt, its route marker, the ticket title, model, or effort. The executor fetches its token-gated durable packet as the first action: full description, 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.model and recipe.agent.promptPrefix + prompt in Agent. Do not manually translate route, gateway, virtual-model, marker, or effort fields. A user-named model for one ticket means set that ticket's route override, never edit the category route, which repoints later tickets too. See references/routing-guide.md.

Locations: CLI: plugins/sidequest/bin/sidequest.js; DB: ~/.claude/sidequest/sidequest.db (SIDEQUEST_HOME); attachments: ~/.claude/sidequest/projects/<slug>/assets/. 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 true|false overrides it for 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 a distinct port, never the shared board.

File a ticket

sidequest add -t "Contact form does not send" -d "..." -p high -l bug --category <id> — read the live taxonomy (category_list MCP / sidequest category list --json), choose by description, and stamp --category; use its fallback only when no category fits. --complexity is legacy ambiguity fallback; never set --model/--effort. Use --file, --story, --anchors, and exact --verify as needed; scope and authoring details: references/ticket-authoring.md.

Descriptions/comments render markdown. Use real newlines, never literal \n. Mid-task side issue? File it with mcp__plugin_sidequest_board__add, then 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: a ticket must be claimed before you touch it, and claiming is atomic. 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). Retyping the command or prose cannot replace that completed capture. Manual and attestation verifiers keep their existing 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. A denied or unclaimed spawn gets a diagnose-first retry only when pulse <ref> identifies a changed dispatch condition. Record unchanged refusals as evidence and surface the failure 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 useful work needing a decision, SendMessage the same agent and keep its claim and worktree. A resume retains claim, token-file path, and worktree binding. On matches no dispatch record, its holder calls MCP dispatch with recoveryEvidence, claimHolder, and worktree; it re-mints and re-binds. On confirmed death, salvage, release, replace.
• Agents report automatically. Never use TaskOutput for a Sidequest task ID or launch name. Poll with changes --since and pulse <ref>. After terminal evidence, use TaskStop({ task_id: "<agent name>" }) once for a still-registered teammate (Claude Code host action, not Sidequest). No task found/not running = already exited, no retry. Never stop a live claim, retained continuation, or candidate awaiting integration. Never proxy-wait with a shell/Monitor/cron task only waiting for an executor or artifact (a one-shot local readiness watch is fine).

Repository publishing is the orchestrator's, alone. Executors stop at verified local commits and submit (claim released, parked in doing); submit.body holds the canonical full report, so do not post a separate pre-submit report comment. The terminal comment keeps only the commit hash + verification. Submit is terminal for the executor: a submitted ticket cannot be amended by messaging the executor that produced it, however small the follow-up looks. File a follow-up ticket for changes. Redispatch the existing ticket only when it was released without a pending submission. The orchestrator is the integrator: choose sidequest integrate <ref> --by <who> --mode apply|replay|merge from the board default, then run the publish transaction (lock → delivery → merged-tree gate → central version → review → push → reachability → done): references/publishing.md. BOOKEND SUPERVISION. Between dispatch and submission, do nothing with that ticket: no pulses, comment reads, or peeks. At integration, read the submit report, deliver the range, and run the merged-tree gate once per wave. Judge by that oracle and the submit report, never by opening source or diffs. When sized risk or a weak oracle needs independent review, bind a routed review-audit ticket with reviewTarget; never orchestrator re-review. Never mark a submitted ticket done without integrating it; never re-dispatch one (refused as submitted). A dead executor's done only proves the board transition, never that work shipped: salvage and close it per references/publishing.md.

Route execution; keep the loop tight

Before routing, the orchestrator decides what improvement is worth making, its concrete benefit, the chosen approach, and its boundaries. Gather evidence with direct read-only tools or native Explore, then write tickets for that selected plan and route implementation. Routes select execution capacity, not product or tradeoff decisions. A direct claim is limited to the INLINE-SAFE allowlist and its 20+ character reason; it cannot retroactively legitimize prior inline investigation. Executors own their tickets; investigations return compressed findings (~1–2k tokens) as comments, not transcripts. Routed implementation uses a freshly dispatched executor. Explore, claude-code-guide, and statusline-setup are narrow harness utilities; Explore is a quick sweep only, deep or fan-out investigation is a codebase-exploration spike; other delegation needs a ticketed route.

The shape is a LOOP, not a hand-off: spawn a wave → executors return terse reports and submit verified commits → read each thread, use scoped verification for each ticket, then run the full suite once while publishing the wave in one transaction → re-plan, spawn the next. Don't accept a green suite as proof of coverage; review execution evidence. Prevent executor mini-sessions from the spawn side: the ticket is the spec. The ticket carries the selected outcome, benefit, approach, boundaries, and enough implementation detail to act; scope the spawn prompt only with logistics, with the ticket contract traveling in full and unnarrowed; Executors keep useful work: keep claim, checkpoint evidence, and await SendMessage steering for questions or failed checks. Release only for confirmed death or unsalvageable blockers; batch small same-model tickets into ONE executor (different models never batch); parallel fan-out spawns one executor per ticket in a single message when the wave justifies it.

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 needs hook agent_id + permission_mode: "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, not diary entries: decisions, constraints, ruled-out approaches, risks, exact verification command/result, concise findings — no progress narration. 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 ticket blocked by an unfinished one is skipped by next and excluded from ready.

Guidelines

Act, then report — run the command, tell the user 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.