Skip to main content

The eleven operations

The shape of a run

Every pipeline operation is invoked deliberately. No operation invokes another, and none runs because a previous one finished. You choose the fan-out from Epics to Features to Slices one subject at a time.

A run proceeds in four movements:

  1. Admission. The phase gate resolves prerequisites, evaluates the permission policy and confirms the run. Without that confirmation the operation stops.
  2. Bounded reading. Inputs load within declared budgets, and each one receives a recorded disposition, including an input that was read but not used.
  3. Synthesis. Evidence workers answer bounded questions read-only, and the phase controller assembles the result.
  4. Declared writes. Output lands only under the approved output root for that operation and is then sealed into the content-addressed store.

Context first

ingest-workspace-context scans the workspace’s authorized roots and produces a candidate context revision with a validation report. Promoting the candidate is an explicit approval, and the promoted revision is the grounding that later operations read. Operations that require context refuse without it; operations that use it for enrichment prompt first and continue only through an explicitly labeled path.

Product definition

idea-and-research turns an idea into an evidence-backed opportunity and research brief, using the admitted local context and the sources you supply. Every claim carries its actual source, and a claim that could not be sourced is recorded as unsourced rather than dropped. External research is not part of the supported surface.

idea-to-prd produces exactly one PRD revision and its requirements register, bound to the selected research revision by hash. Every input ends with a recorded disposition, so an unaccounted input cannot quietly shape a requirement, and material decisions are settled through a clarification loop before prose is written.

review-prd then issues a verdict for that exact PRD revision. The reviewer reads the sealed bytes and the register, not the authoring run’s working state. Only PASS and PASS_WITH_ADVISORIES make a PRD eligible for acceptance.

Technical design

prd-to-rfc produces one RFC revision for the accepted PRD scope, grounded in the repositories the workspace authorized. It is the first operation that reads code, and it reads it through a read-only probe rather than general shell access. If the accepted PRD is missing, it reports the gap and creates no RFC.

review-rfc issues the RFC verdict and a technical-risk register, on the same independence terms as the PRD review: distinct author and reviewer runs, read-only access to the subject and no inherited author reasoning.

Decomposition

define-epics derives outcome-oriented Epics from the accepted PRD and RFC; one RFC may produce one or more. define-features defines the Features of one selected Epic and records obligations shared across Features, so that readiness can later check they are closed. specify-feature produces the behavioral and technical contract for one selected Feature: exactly one Feature Specification per Feature.

define-feature-slices records either an explicit, reasoned no-slice decision or the Slice definitions, and neither outcome is a default. The decision cites behavior, never size. For each Slice, specify-feature-slice produces the deep technical contract, including the contract semantics owned by the Slice’s dependencies.

Three ways in

Work is organized as one chain per initiative. You do not create or name a chain: the first thing placed in it creates it, and every level above your entry point stays empty.

  • You have an idea. Run idea-and-research, then idea-to-prd.
  • You have a PRD written elsewhere. Register it with the register-artifact command, and the chain starts at the PRD level.
  • You have an RFC written elsewhere. Register it the same way, and the chain starts at the RFC level.

For a PRD or RFC entry, the empty levels above it are the final state of that initiative, not a gap to fill later. Register material further down, such as Epics into a chain with no RFC, and the receipt names a suggested route to fill the gap. It is only a suggestion: nothing runs until you run it.

Where outputs live

Materialized revisions appear under .specgent/out/operations/ in your workspace, one directory per operation, subject and revision. The authoritative bytes are the content-addressed store under .specgent/artifacts/; the output root is a reproducible projection of that store and is deliberately left untracked.

The command reference lists every operation with its result, and reviewing and refining covers the loop beside the pipeline.