Sidequest

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.

Plan substantial work on the board first

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. 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. For 3+ independently checkable pieces, pin shared types/interfaces, file boundaries and per-piece verification, then dispatch a category-routed wave. Wave mode REQUIRES a Sidequest story: file the complete backlog and execution contract under Sidequest's US-n grouping. One-ticket mode stays story-less; stories hold shared outcomes/dependencies. Cut along affected store, CLI, MCP, skill/docs and test surfaces. Tickets carry anchors, contract and scoped verify; use directory scope for blast radius (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.

Answer direct questions; do operational requests and stated one-line 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.

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, 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, 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). 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 "..." --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. 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: 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. Require authentic response/activity; 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, including preparing-session authority and deadlines: 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 one pulse still shows alive after its ticket went terminal (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).

Repository publishing is the orchestrator's, alone. Executors stop at verified local commits and submit (claim released, parked in doing); submit.body is the canonical report, so no separate pre-submit report comment; the terminal comment keeps only 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, avoid routine pulses, comment reads and peeks. Explicitly assigned builders and readonly advisors may exchange direct native messages and inspect authorized snapshots under references/readonly-guidance.md. Draft findings are advisory, never acceptance or claim release; this does not authorize orchestrator source peeking or self-review. 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 reading diffs. When sized risk or a weak oracle needs independent review, bind a routed review-audit ticket with reviewTarget; never re-review yourself. 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.