Workflow

A citation-grounded, human-in-the-loop authoring pipeline. One natural-language ask is sized and routed by triage, optionally shaped first by brainstorm, then flows through the authoring stages — each produces exactly one approved artifact, and each stage hard-refuses to start until the upstream artifact is approved. Build writes code; an independent code review then gates the Story's completion.

Every authoring stage follows the same shape — context.assemble (deterministic or a coarse handoff to insrc_analyze_step) → N sequential LLM steps → checklist.verify → synthesize — and every claim in every artifact is cited to a step output or an analyze bundle. Ungrounded citations refuse to synthesize. No step is ever skipped to save turns, and no LLM call runs in parallel: accuracy first, cost last.

Brainstorm — shape a rough idea first

When the ask is a vague idea rather than a crisp spec, the brainstorm stage runs before triage. It is a single paused elicit turn: you conduct the whole clarify → fold → show-back → confirm convergence in chat — folding each answer into a running statement, showing it back, re-asking only the open gaps, and at every fork recording the ruled-out choice as a non-goal — then resume once with confirmed: true and no open items. The result is a SpecArtifact you review and approve like any other artifact; it then seeds define (for an epic) or a standalone design.story (for a feature), so the elicited decisions flow straight into the tracked chain instead of being lost in chat.

Bugfix triage — a defect fix, tracked

A defect fix is a first-class triage category, not just a small feature. When triage recognises a bugfix it sizes it by magnitude — small vs sized — and routes it through a dedicated issue stage before any code is written, so even a one-line fix leaves a cited, reviewable record attached to the code it corrects.

Because the ISSUE body is the one source for both records, the GitHub issue never drifts from the internal chain. The whole path stays on the same gh CLI the tracker already uses — no new external surface, no direct cloud REST. The category is feature-flagged (bugfixCategory) and lives in src/workflow/{triage,artifacts/issue.ts,locate,bugfix}/.

Artifacts & approval gates

Each artifact is written twice: a human-readable .md under docs/ and the canonical JSON under .insrc/artifacts/. The JSON is the machine contract downstream stages read; the Markdown is what you review.

The gate is hard, not advisory. Every downstream workflow refuses to run against an unapproved (or rejected) upstream artifact. You approve from the CLI:

$ insrc workflow approve docs/defines/DEF-<h16>.md   # unlocks design.epic

Independent review before approve

Before you approve a design artifact, a second pair of eyes checks it. insrc_review_step extracts the artifact's load-bearing premises and re-verifies each against the real source tree with deterministic probes (ripgrep re-derivations, file:line confirmations), then returns findings graded HIGH / MED / LOW with a block / warn / pass verdict. It is a genuine independent pass — not the model grading its own work — so it routinely catches a stale citation or an under-specified change the author missed. Resolve any HIGH/MED before approving; a block verdict withholds approval unless you pass an explicit override.

Open-question resolution

DEF, HLD, and LLD each surface the questions the stage could not settle. Resolving them is a two-beat contract:

• Optional at the end of the stage that raised them — you can synthesize with questions still open.
• Mandatory at the start of the next stage — the gate is lifted to stage-start and applies to the immediate-upstream artifact. unresolvedOpen must be empty before the next stage proceeds (src/workflow/questions.ts).

For each question you have three moves, recorded by recordResolution as a resolved | ignored | deferred status:

When you resolve, the daemon generates candidate solution options through the shaper LLM (QuestionWithOptions / QuestionOption), so you pick from grounded choices rather than inventing them. Three insrc_workflow_step phases drive this: start runs the stage-start gate, resolve_question records one resolution, and review_deferred walks every parked question across the Epic's DEF + HLD + all LLDs (src/mcp/workflow-step/phases/{start,resolve-question,review-deferred}.ts).

Hierarchical IDs

Every Epic, Story, and Task carries a single canonical identifier that encodes its place in the hierarchy. The separator between levels is :, and the slug form simply swaps each : for - (toCanonical / toSlug in src/workflow/id.ts):

The date prefix plus 8-hex hash is separator-free, so E<8><8> parses unambiguously. The levels nest: an Epic is E…, a Story is E…:S…, and a Task is E…:S…:T…. This gives a clean two-way Epic → Story → Task relationship — parseWorkflowId reads any string back into its level, and parentId / epicOf walk upward. The minting helpers are epicWorkflowId, storyWorkflowId, and taskWorkflowId. The same ID appears in issue titles and in the stored docs, so a glance at an issue tells you exactly where it sits.

The GitHub tracker

The tracker is opt-in and never stores a token — it shells out to gh, which owns your OAuth session. When enabled, approval-time auto-push turns each approved artifact into a typed, natively-nested GitHub issue (src/workflow/tracker-auto.ts):

The nesting is real GitHub sub-issue linkage via ghLinkSubIssue, not just a label convention. Alongside the issues, the tracker commits the artifact docs and links the committed blobs back from each issue, and can seed a GitHub Projects v2 dashboard so you get Epic → Story → Task drill-down on a board. Issue-type names and Task pushing are configurable per repo via src/workflow/config/github.ts (epicIssueType / storyIssueType / taskIssueType, pushTasks, useMilestones); types fail open to untyped issues when the org lacks them.

Bootstrap the automatable GitHub setup once with:

$ insrc tracker setup # config + labels + issue types
$ insrc tracker setup --project   # also create a Projects v2 board

runTrackerSetup (src/workflow/tracker/setup.ts) checks that gh is authenticated, verifies the OAuth scopes it needs (admin:org for issue types, project for the board), writes the resolved config, upserts the fixed tracker labels, ensures the Epic/Story issue types exist, and — behind --project — creates the board. Steps whose prerequisite is missing come back as manual with the exact command to run, so nothing is done behind your back.

The build stage

Build is a controller-driven MCP tool, insrc_build_step, with two phases (src/mcp/build-step/):

• implement — the daemon resolves the Task, runs the admission gate, then hands the controller LLM a templated implement prompt pointed at that Task. The daemon does not edit code here; your controller performs the edits.
• validate — the daemon itself runs a read-only agentic verdict session over the result.

The admission gate is strict: admitBuild (src/workflow/runners/build/admission.ts) requires an approved PLAN for the Story. An unapproved or rejected plan short-circuits to plan-unapproved; only an approved plan reaches the freshness/drift check. Because a PLAN carries no open questions, build inherits the decisions already settled at plan-start rather than re-litigating them.

# controller calls insrc_build_step { phase: 'implement', ref: 'E…:S001:T003' }
▚ admission  plan E20260717185807ba:S001 approved · fresh
▚ task      T003  add tag index to the query planner
▚ next      implement → controller runs the templated prompt
# …controller edits files, then:
# insrc_build_step { phase: 'validate', ref: 'E…:S001:T003' }
▚ verdict   read-only session · PASS

Code review & the completion gate

Once a build has produced its changes, insrc_code_review_step reviews the changed code — distinct from the design review above, which reviews the artifact. It grounds on the Story's real changed files and judges four independent dimensions, each returning block / warn / pass:

The step runs start → judgements → done and writes a CR record. Crucially, approving the BUILD artifact is the code-review-gated completion act for the Story: under codeReview.enforce a block verdict — or no review having run at all — withholds completion unless you pass an explicit override. The gate defaults to advisory (off) and can be turned to enforcing in config.

Two ways to run

The same five stages run either from your MCP client turn-by-turn, or entirely inside the daemon over the socket. The only visible difference in the output is what meta.model gets stamped with.

# in your MCP client:
> Use insrc_workflow_step to define an Epic for "Add tag filtering to todos".

phase=start      → decomposer prompt
phase=plan       → 4-step plan  · context.assemble uses insrc_analyze_step
phase=step ×N    → epic.frame → stories.compose → checklist.verify
phase=synthesize → docs/defines/DEF-3f9c…e2.md   meta.model: client

$ insrc workflow approve docs/defines/DEF-3f9c…e2.md
  approved · design.epic unlocked

Where next