Releases

A spec-recall rule in the engineer persona. Before asking the user any design question, the engineer re-opens the governing spec — the feature's arch.md (its ## Logic section resolves exactly these edge cases), its prd.md acceptance criteria, and architecture.md. A question the spec already answers is not a gap; re-asking it tells the user their recorded decision didn't stick. The rule applies at the moment the question arises — including when the user challenges the design mid-conversation — and demands a fresh read of the file, not a recollection of one from earlier in a long (and, on some engines, compacted) session.

/gspec-implement now has a change-request protocol. The flow used to end at "verify & report," leaving the conversation that follows — where users actually ask for changes — unguided. A change request now starts with re-reading the feature's arch.md and prd.md: if the spec already decides the question, follow it and cite the anchor; if the request conflicts with a documented decision, surface the conflict, and when the user changes the decision, update the anchor in the same change so spec and code move together; only what neither the request nor the specs decide is a genuine question.

On Codex, commands now inline the skills their flow names. Codex commands are emitted as skills, so installing the persona/convention catalog alongside them would collide in the same namespace — and the whole catalog was skipped. The sub-agents were fine (their persona is inlined into each .codex/agents/*.toml), but the command bodies — the part that talks to the user through planning, phase gates and change requests — ran with every persona reference dangling, including "follow the specs exactly" and "never override an explicit spec decision." The build now composes each referenced skill into the command body it is named in, and a dist test holds the invariant for every command.

A floor on the Modules table: it only grows. The build captures the table before the architecture writer runs and checks it after. A row that was renamed or dropped comes straight back to the writer as a mechanical violation naming the module and the gspec/architecture/<name>.md path it would orphan — no validator run spent discovering it. A module that really is retired keeps its row and says so, so the tier file and every reference to it stay resolvable.

The deterministic-lint loop is now shared by every stage that has one. It was written once for the per-feature fan-out; the single-deliverable gate had no way to run a floor at all. One implementation now backs both, so the non-convergence signature, the per-round recording to qa-failures.md and printing violations rather than counting them cannot drift apart between them. --no-qa skips the floor alongside the validators, as it already did per-feature.

/gspec-architect confirms before it regenerates the system tier. It already refused to overwrite a feature's arch.md or design.html without asking; gspec/architecture.md had no such guard one step earlier in the same flow. It now names the amendment as an amendment, and checks the writer's summary still carries every module row it started with.

An existing gspec/architecture.md is amended, not rewritten. The architecture-writer now checks whether the file exists before writing a word, and on a project that already has one it reads the system tier and every gspec/architecture/<name>.md first, then makes the smallest change the new feature PRDs require. Recorded decisions, resolved gaps and stated assumptions are preserved rather than re-litigated, and anything it does change gets a Technical Gap Analysis entry so the diff is reviewable. This fixes /gspec-architect and gspec build together — the gap was in the agent, so both paths had it.

Feature folders. gspec/features/<slug>/ holds prd.md, arch.md, design.html and tasks.md. Four files, four writers, each with its own validator gate — replacing the flat gspec/features/<slug>.md plus a sibling plan. /gspec-feature writes the PRD, /gspec-architect the architecture and design, /gspec-plan the plan.

Designs are HTML you can actually open. Each feature's design.html is a self-contained mockup that renders from file:// with no build step — so a human sees the design instead of reconstructing it from prose. It carries the visual decisions only; the structural ones live in arch.md, and the split is testable: could a designer change this without changing any behavior?

Architecture in two tiers, and it stops growing. gspec/architecture.md is the system tier — module boundaries, the shared model at the name level, inter-module contracts, the Modules & Verification table. Each row gets a gspec/architecture/<name>.md carrying that module's spine. Field lists, endpoint signatures and resolved edge cases belong to the feature that introduces them, so the root stays finite as the product grows.

Anchors — one origin, many deltas. Every entity, endpoint, screen, component, rule and machine gets a rigid heading and a machine-readable status. One feature originates it; others amend it, or keep a two-line stub with uses: when they consume it unchanged. The - **module:** line on each anchor is authoritative rather than the file's frontmatter, so a feature may legitimately span modules.

One memory, for everything gspec learns. Agents record to .gspec/memory/pending/<agent>/, one file per memory — disjoint paths, because same-wave agents run concurrently and a shared document loses whichever memory landed first. /gspec-memorize commits the worthy ones to .gspec/memory/ (this project) or ~/.gspec/memory/ (you, everywhere), and the installer composes them into the skill. pending/ is never composed, so an unreviewed memory cannot reach a skill — committing stays a decision you make.

The learning loop works on every engine. It used to ride on Claude Code's memory: field, which no other target has — so Cursor, Codex, OpenCode, Antigravity and Pi shipped a convention telling agents to ignore it. Recording is now a plain file write, and the convention ships to all six, inlined where a target cannot preload skills.

/gspec-teach — correct an agent without waiting for it to fail. Name a target (practices-writer) or just describe the symptom, and get a reviewed skill edit back. One correction usually needs two edits — a rule taught only to the writer leaves the validator unable to catch a regression — so they are proposed separately. Durability is reported rather than assumed: an edit inside an installed project lasts until the next install overwrites it.

A memory can be about gspec itself. Those are never composed into a skill — they are reports. gspec memory report prints a prefilled GitHub issue link per unsent one, with project identity stripped; nothing is sent until you open it and click through, and gspec memory filed <name> <url> records that you did.

gspec memory — see and apply what you have taught. Lists every skill carrying memory with a per-scope count and both store paths, plus anything pending review, per agent. gspec memory apply recomposes into the installed skills without a full re-install.

Deterministic floors run before any agent does. Anchor grammar, origin uniqueness, amends: targets resolving, screen coverage in both directions, [P] honesty, checked-task immutability. A mechanical violation is caught by a hook for free instead of being spent on a judgment call, and the task-immutability floor is a hard block: a checked task cannot be edited, renumbered, deleted or unchecked.

Per-agent model assignment and real token accounting. .gspec/config.json maps agents to models by name, role tier, or default, so the cheapest checker is not billed at the price of the most expensive writer. --models recommended writes a tiering for your engine; the build records per-agent runs, turns, tokens and cost. Nothing is assumed — a headless install writes no models map at all.

A run records what stopped it. On a long build a usage limit is routine — it resets on a clock and the run continues hours later — but nothing kept the reason, so a paused run and a failed one looked alike. The run now records what interrupted it and what resuming will do, and a fan-out stage reports progress as it goes instead of printing a header and going quiet for 29 minutes.

The build warns when your agents are older than the gspec running them. Agent, command and skill files are copies, and upgrading gspec never rewrites them. A version stamp is recorded at install so a build can say plainly that what is on disk predates the runtime driving it.

A root README is a required practice. The practices persona now states what its Documentation section must mandate — every module's README naming its run command and the port it binds — rather than leaving the whole section to the writer. The requirement stays tool-agnostic in the spec: "each module's test command", never a named runner.

/gspec-distill is now /gspec-memorize, and gspec lessons is now gspec memory. Same flow and the same apply / report / filed subcommands. The stores moved with them: .gspec/lessons/ and ~/.gspec/lessons/ are now memory/, renamed for you on the next install. If both exist, neither is touched and the collision is reported — silently merging two stores could resurrect something you deleted.

The style guide is tokens only. Palette, type scale, spacing, radius, elevation, motion durations, themes, icons, and a computed contrast table. Component styling moves to the feature that owns the component, so the guide stops being a second place for a decision to drift from.

A QA revision is a repair, not a rewrite — now including code. Every spec stage already sent a surgical revision naming only the findings; the implementer did not, and re-generated whole files. It now receives the same treatment, so a passing gate is not undone by the fix for a failing one.

The implementer defaults to Sonnet on Claude, not Opus. It is the highest-volume agent in a build and the only one whose output is checked by something deterministic — the gate runs verify.sh, so a weak result fails rather than ships. architecture-writer and feature-architect stay on Opus, where a mistake propagates with no gate to catch it. Measured on a like-for-like dogfood build: $139.72 → $95.42, and 16.7h → 3.9h.

A resume skips work that is already done. A scope with every task checked no longer spends an implementer run discovering that — roughly 5% of a run's cost on a large build. Transient engine failures no longer end builds either: a dropped connection is not a defect, and a truncated validator response used to be graded as a failure and spend a revision answering it.

A run's diagnostics tell the truth. A family of these turned up in one build: VERDICT: **PASS** read as no verdict; the [P] parallelism check was inverted, flagging a correct task and passing a broken one; three checks matched nothing at all — one bullet-only pattern matched none of 88 real tasks; four diagnostics pointed at evidence that had been summarized away; and verify.sh could hang the build silently for an hour against a daemon that was down.

The committed memory store is not writable by an agent. .gspec/memory/<skill>.md is composed into that skill on every install, so an agent writing there committed a memory with nobody reviewing it — a producer≠checker bypass by a slower route. The write guard blocks the committed store while explicitly allowing pending/, where recording belongs. Read-only agents no longer pretend to record at all; their failing verdicts reach the memorizer through the feedback log instead.

A pass of gspec's own agents, driven by what dogfood builds reported. Acceptance-criteria caps stated a number with no technique, and the naive way to satisfy one is deleting requirements. "The fix for a tie is always deletion" had no branch for a gap that no anchor resolves. Motion durations were missing from every token enumeration, so a literal animation duration was uncatchable. The plan bars stated properties without saying when to verify them — "honest parallelism" reads as one check but is two. And no writer agent had a pre-return required-sections check, so writers silently omitted sections their own skill lists by name.

The "Where should agent memory live?" install prompt is gone, along with the memory: field on every installed agent. There is no silo to scope any more: the manifest's remembers: flag decides which agents record, and pending memories live with the project.

A distinct exit code for every ending, and gspec build --status. A run now exits 0 complete, 1 failed a gate, 2 paused for spec review, or 3 crashed — so a watcher branches on a number instead of reading prose. The matching state is written to .gspec/build/status.json at every transition (state, stage, reason, exit code, engine, and the driving pid), and gspec build --status prints it in one line and exits with that code. run.json is still the control state a resume works from; this is the answer to "how did it end?".

A crash writes its own epitaph. Handlers for uncaughtException, unhandledRejection, SIGINT, and SIGTERM record the ending synchronously (process.exit will not wait on a promise) and write last-failure.md before dying, so a killed run stops looking identical to one still working. They install only after intake, so a Ctrl+C aimed at the interview behaves as it always has, and never for SIGHUP — which would have defeated nohup. A SIGKILL outruns any handler, so --status treats a running record whose pid is gone as a crash, records that, and exits 3.

Section contract for feature PRDs. Each PRD section now states what it holds, what it must not, and where the excluded content belongs — capabilities carry observable acceptance criteria, not state machines, layout tables, or timing formulas (those are the architecture spec's job); Dependencies names siblings rather than restating them; Implementation Context is a fixed portability note and nothing else. Two rules do most of the work: a PRD writer does not read profile.md, style.*, stack.md, practices.md, or architecture.md (sibling PRDs are the only spec it reads, cross-linked by slug), and the required-section list is exhaustive — no invented "Implementation Details" or "Technical Architecture" sections. An optional Deferred Decisions section is now explicitly allowed, resolving a contradiction where the quality bar referred to a section the required list omitted.

Size budgets, advisory by design. A new "Size budgets" table in the shared conventions skill gives every deliverable a word ceiling — 2,000 for the profile/stack/practices/style guides, 1,800 per feature PRD, 3,000 for the architecture — read by writers and validators, so the checker no longer pushes for detail the ceiling forbids. Counting includes tables (where an over-long spec usually hides) and exempts frontmatter and the practices Enforcement block. A budget is a ceiling, not a target: brevity is never a finding, a missing required section is still a defect, and no proposed fix may grow a spec already at its budget — revisions resolve findings by replacing text, not appending to it.

--scope small | standard | large. The intake now asks how big the product is and records the tier in the brief; the flag overrides it, and it is pinned on the run manifest. The tier scales every budget by ×0.6 / ×1 / ×1.5, so a one-level game and a multi-deployable platform no longer get the same specification volume. Honored at resume time like --qa-retries, so a run whose specs came out too big can be retuned and continued rather than restarted.

The driver measures what was actually written. After each writer runs, the build counts the produced spec and prints it against its budget (gspec/features/x.md — 4,877 words, 2.7× its 1,800-word budget), and feeds the overage into the next revision prompt. Measurement is in the driver because a model asked to self-limit reports compliance while writing lines twice as long — in the run that prompted this release, one spec was 8% shorter in lines than a known-good equivalent while being 60% larger. Over budget never fails a stage: it is logged, and QA records it as a [minor] finding that the severity contract keeps non-blocking.

The /gspec-build command must report how the run ended. The command used to offer a harness-tracked background task and a detached nohup launch as equal options, and monitoring happened "after each user check-in" — so a detached run that failed an hour later reached nobody. It now prefers the tracked background task explicitly (that is the only launch where the harness wakes the agent when the process exits), says plainly when it cannot watch the run, and requires running gspec build --status and reporting the result the moment the run ends — including, especially, when it failed.

Proportionality rules for the foundation specs. Unlike the PRD case, the stack and practices boundary rules were intact and honored — those specs grew because several quality-bar items scale with item count and had no threshold. So: rationale is for major choices (a minor or forced choice gets a clause, not a table row of its own); "Not Applicable" means one line and a reason, not a section that declares itself N/A and then specifies itself anyway; don't enumerate what a lockfile or a formatter config already declares; and scale depth to the scope tier. The practices guide's CI/CD pipeline structure now has a declared home (under Version Control & Collaboration) instead of writers inventing a section for it, and the style guide gets a one-specimen-per-pattern rule.

QA checks tier bleed and size. The QA persona's "Boundary violations" failure mode now explicitly covers a section that has started specifying how the system works inside a spec whose job is what — cite the block, name the spec it belongs to, and propose relocation rather than deletion. A new "Over budget" failure mode reports size but is capped at [minor] however large the overage. And every proposed fix must fit the budget: "add a section explaining…" is almost always the wrong fix.

Your saved templates now reach an autonomous build. gspec-templates lets you keep reusable specs under ~/.gspec/{stacks,styles,practices,features}/, and the four matching writers preload the skill — but the convention resolves ~ in the orchestrating command, which has a shell. An autonomous gspec build has no such command, and the writers have no Bash, so they were pointed at a folder they had no way to name: every saved template was ignored, silently, and indistinguishably from having none. The driver now resolves the library itself and lists the matching folder's candidates — absolute path, name, and description — in that stage's brief, printing what it found (templates: practices 1 · stacks 2). Which template to adopt is still the writer's judgment, and adapting it to the brief is still required. A stage is only ever offered its own type, and only its writer is (a planner decides scope, not content); profile.md and architecture.md still have no library, being inherently project-specific.

A writer that exits 0 having written nothing now fails, naming itself. An engine that hits an auth failure, a rate limit, or a usage cap in headless mode reports it as its final message and exits clean. The driver took that as success: the stage marched on and the validator failed against a document nobody had written, pausing the run with the wrong culprit. Delivery — not the exit code — now decides whether a writer succeeded; it is retried once, then fails with the real reason. The existing "a crash after a good write is not a gate failure" recovery is unchanged. The same insistence covers the driver-written deliverables: the research synthesis must land on disk, and a plan-decomposer's output must actually contain task checkboxes before it is persisted as a plan. A validator that returns no VERDICT: line is now called out as unvalidated rather than counted as a quiet FAIL.

A QA revision now knows which rule wins. Two rules from this release could point in opposite directions with nothing ranking them: "a revision that grows the document is a defect" (and, when the draft was already over budget, the flat "it must not grow at all") against a blocker finding like eight required sections are missing — a fix that multiplies the document's length. Which rule gave way was left to the writer's judgment. The revision prompt and the shared budget contract now state the precedence, ahead of the rule it governs: resolving a blocker or major finding outranks every size rule. Content a finding names as missing gets added in full, however far past the ceiling it takes the spec, and is never watered down to stay near a word count — an unresolved blocker fails the gate, an overage cannot. Growth is still only for what the findings require: everything else is resolved by replacing text, an over-budget draft pays for required additions by cutting restatement elsewhere, and an overage that survives is reported in the summary (with a decomposition recommendation for a feature or architecture spec) instead of being traded for an unresolved finding.

The style stage could never pass its delivery check. A stage's declared outputs are alternatives — the style writer produces gspec/style.html or gspec/style.md, one format, and the validator target names the pair with "or". The new delivery check read them as a checklist and demanded both, so "did the writer deliver?" was permanently false for that stage: a perfectly good style guide was reported as "produced no deliverable", retried once, and then failed the run — and the companion recovery (accept an artifact that is present and well-formed even though the writer exited non-zero) could never fire either. Any one of a stage's outputs, present and non-empty, now counts as delivery.

Per-agent model config. A models map in .gspec/config.json assigns models by selector, resolved most-specific-first: exact agent name > role tier > default. Role tiers are writer (every *-writer), qa (every *-validator), planner (feature-planner, plan-decomposer, build-orchestrator, research-planner), implementer, researcher, and inspector. Example: { "models": { "default": "claude-sonnet-5", "qa": "claude-haiku-4-5", "architecture-writer": "claude-opus-4-8" } }. Model strings pass straight through to the engine's --model flag — no allowlist, so new models work immediately.

Global defaults, project overrides. ~/.gspec/config.json holds your cross-project defaults; a project's .gspec/config.json overrides them. Precedence is most-specific-wins with project breaking ties at the same level — so a global architecture-writer pin still beats a project-wide writer tier, while a project qa tier beats the global qa tier. The config is read fresh each run (not pinned like the engine), so you can retune models and --resume. The run header now prints the active assignments.

One failed feature-writer no longer restarts the whole writing phase. The features stage fans out one feature-writer per feature and only then validates, so a single writer failing (e.g. running out of tokens) used to pause the run before any memoization — and the resume re-ran the planner and every writer, regenerating already-written PRDs and re-spending their token cost. On a re-run, the driver now skips a feature whose gspec/features/<slug>.md already exists and is well-formed; the skipped PRD is still re-checked by the validation gate, so a truncated draft is caught there. A fresh run is unchanged (it always writes). This also stops a resume from overwriting a PRD you hand-edited while the run was paused.

Cumulative QA failure log. Every failing QA verdict — spec gates, the per-PRD feature loop, the plan QA note, the verify.sh build/test gate, and the implementation judgment gate — is appended in full to .gspec/build/qa-failures.md, tagged with the stage, checker, target, and whether it was a self-heal revision (rev N), a downgraded advisory (ADVISORY), or the TERMINAL failure that paused the run. Recovered failures are captured too, so a build that self-heals and completes still leaves a reviewable record. Previously a recovered failure left only a truncated manifest excerpt, and the one detailed report (last-failure.md) was overwritten by the next failure and deleted on completion. The new log is cumulative across runs and never auto-removed — delete it once you have mined it; the end-of-run learnings report and the paused-build banner both point at it.

Per-stage cost signal. Each stage now reports its elapsed time as it finishes, the manifest carries a running totalElapsedMs, and the completion line shows total stage time across all runs — so a stage that has quietly consumed an hour is visible while you can still act on it.

Resume re-enforces a failed gate instead of skipping it (correctness fix). A single-file stage recorded failed used to be skipped on --resume because its output file existed on disk — carrying the rejected spec forward into every downstream stage. Now a resumed failed (or crashed) stage re-validates the current on-disk deliverable first, honoring any edit you made to unblock it, and self-heals from there; skip-if-present is reserved for a genuinely pre-existing spec on a stage that never ran.

The gate passes on severity, so the loop has a reachable exit. Per the QA contract a spec FAILs only on a blocker/major finding, but validators applied it unevenly and the loop chased fresh precision nits until the retry budget drained. The driver now enforces the contract: a FAIL whose findings are all [minor]/[nit] is passed with advisory notes (kept in .gspec/build/qa-failures.md, tagged ADVISORY). Conservative — any blocker/major, or an untagged verdict, keeps the FAIL. The QA persona was reinforced to match, and revision prompts now forbid growing a document >~10% without resolving a blocker/major, with re-validation asked to confirm resolved findings before raising new ones.

Passing PRDs are memoized, not re-gated. The features stage restarts over the whole PRD list on every resume; an already-passing PRD used to burn a fresh budget each time (and its verdict was not stable across re-gates). Each PRD that passes is now recorded with a content hash in the run manifest, and an unchanged PRD is skipped on the next pass — removing a large slice of resume wall-clock.

A crash is no longer mistaken for a gate failure. A writer that exits non-zero is retried once; if it still exits non-zero but its expected artifact is present and well-formed (a transient post-write crash), it is accepted and handed to QA to judge — instead of restarting the whole stage. Applies to the foundation/architecture writers and the feature-writer fan-out.

Two-tier per-deployable architecture. The Deployables table now gates the file layout: one deployable keeps a single gspec/architecture.md; more than one splits C4-style into a system tier (shared data model, inter-deployable contracts, cross-cutting auth, the Deployables table, gap analysis) plus one gspec/architecture/<name>.md per deployable for that unit's internals. Each sub-file carries deployable: / covers: routing frontmatter and is linked from its Deployables row, and every concern is stated exactly once at the tier that owns it. On an update run, crossing the gate in either direction restructures the layout.

Token-literals hard floor. A new gspec-token-literals hook (PostToolUse on Write/Edit, Claude Code) flags any literal color — hex, rgb(), hsl(), oklch(), and friends — declared outside the design-token block in gspec/style.html, in <style> CSS or inline style= attributes. The token block (:root / theme-key selectors) is the only home for literal values; everything else must use var(--…). Swatch labels that merely display a hex code are untouched. The designer's quality bar now also requires the accessibility contrast table to be computed from the tokens by a small inline script, per theme key, rather than hand-typed.

Every architecture consumer routes on the new layout. The implementer always reads the root file but loads only the sub-files for deployables its scope touches; the plan decomposer loads only sub-files whose covers: lists its feature; the build orchestrator uses per-unit structure to judge file-disjoint parallel scopes; /gspec-analyze gains an architecture tier conflict category (tier disagreement, cross-tier duplication, orphaned or missing sub-files); and /gspec-audit and /gspec-migrate sweep architecture/*.md alongside the root. The architecture validator polices the layout gate and the tier boundary.

QA self-heal revisions are surgical. A failed gate used to re-send the full authoring prompt with the verdict stapled on, which biased fresh agents toward regenerating — drafts were observed growing while "fixing" contradictions. The revision prompt now names the deliverable, restricts the writer to the edits the findings name (everything else preserved byte-for-byte), and accumulates every verdict across attempts, so attempt N sees what attempt N−1 was told and a reappearing finding is fixed differently instead of repeated. Applies to every spec gate and the per-PRD feature loop.

Failed verdicts must produce a lesson. A revision run is now a capture run under the gspec-memory convention: the agent must either record an address-tagged generalizable lesson to its memory silo or state explicitly why the finding was purely project-specific. Failing the same gate twice and recording nothing is treated as an incomplete run.

Single source of truth is now a stated convention and a QA failure mode. gspec-conventions requires each class of fact to have one canonical home with references everywhere else, and one example per pattern; validators (gspec-qa) now flag redundancy and restatement as findings. The architect's bar adds "present-tense state, not history" — superseded decisions are folded in, never accumulated as a changelog. The agnosticism convention also names the sneaky identity-leak sites: document metadata, chrome copy in example components, and product-derived token/class/constant names.

Feature ceiling 12 → 24. The feature-planner still leans toward fewer features, so the cap is only a backstop against a runaway plan — but at 12 it was too low for genuinely large products. Beyond 24 the extras are dropped with a logged warning (never silently), same as before.

Writer fan-out is now concurrency-bounded. Feature PRDs are written by at most five feature-writer runs in flight (a worker pool, not fixed batches, so a slow writer doesn't stall the queue). This decouples "how many features are allowed" from "how many headless agents run at once", so raising the ceiling doesn't multiply peak API/subprocess load.

feature-planner agent. Right after the foundations, the planner reads the brief (and gspec/research.md when --research ran) and returns a right-sized feature breakdown — slug, scope, priority, and dependencies per feature. The features stage then fans out one feature-writer per feature and gates each PRD through feature-validator. It is the features-stage counterpart of the research stage's planner.

One decomposition heuristic, two callers. The "when to split a big request into multiple features" judgment now lives once in the gspec-product skill, shared by the interactive /gspec-feature (which proposes the breakdown and confirms it with you) and the headless feature-planner (which decides it unattended). The runtime reuses the same agents as before — only the orchestration it was missing was added.

The build never yields the wrong number of PRDs. A genuinely single-feature idea still writes exactly one PRD, and an empty or unusable plan falls back to a single writer rather than producing zero. A MAX_FEATURES ceiling caps a runaway breakdown, and planner-proposed slugs are sanitized so model output can't escape gspec/features/.

Competitive research stage (--research). Right after the profile, a research-planner turns the profile + brief into a competitor list, one competitor-researcher fans out per competitor (capped at six), and a research-writer synthesizes gspec/research.md. Findings are auto-accepted and become inputs to the feature PRDs; the run pauses at the spec-review gate, which is where you prune any you disagree with. The flag is pinned at run start, so it can't be added on a --resume.

Arrow-key CLI prompts. A new interactive prompt layer gives select / multiselect / confirm / text prompts you navigate with the arrow keys on a TTY. Off-TTY — piped or scripted usage — it degrades to numbered readline input, so non-interactive invocations keep working unchanged.

Per-engine web access for research. The research fan-out enables each engine's web tools only for that stage — Claude, Codex, and Pi each map to their own network-permission surface — so competitor research can reach the web without widening permissions for the rest of the build.

Regression guard. A test pins the frontmatter + builtin-tools contract on every emitted dist/pi agent, so a drift that makes agents invisible in Pi fails the build instead of shipping silently.

Pi agents now load. Every emitted Pi agent carries a name: field alongside description:, so npm:pi-subagents stops silently discarding them and gspec's agents actually appear in Pi.

Tool allowlist maps to Pi builtins. Glob now maps to Pi's find builtin — glob is not a Pi builtin, so under Pi's strict tools: allowlist the entry matched nothing.

Spec-review human gate. Between plan and implement the run pauses cleanly (exit 0): every spec exists, no code does. Review and edit gspec/ freely, then gspec build --resume to approve and continue into implementation. Skip it with --no-review — at launch, or at resume time. Runs started on an older gspec survive the upgrade: a manifest without the new stage simply pauses there on its next resume.

--qa-retries <n>. Every QA gate — spec validators, per-PRD feature checks, the driver-run verify.sh, and the implementation validator — may now attempt n self-heal revisions before pausing the run (default 1, the previous behavior; 0 fails on the first verdict). Also honored on --resume, so a run that paused at a stubborn gate can retry with a bigger budget.

Failures now say why. When a stage fails, the runtime prints the failing verdict/output in full and keeps it in .gspec/build/last-failure.md and in the failed stage's detail field in the run manifest — so a detached or CI run is diagnosable after the fact. The file is replaced by the next failure and removed when a build completes; a clean retry clears the stale reason from the manifest.

The build finds its engine on pre-2.0.1 installs. When neither --engine nor a recorded install target is present, the build now detects the one engine whose gspec agent files are installed in the project and uses it. More than one installed engine asks you to pick explicitly; none produces a clear "not installed for any engine" error with the exact install command, instead of a misleading Claude-specific message.

Interviews ask one question per message. The shared clarification protocol (gspec-authoring) now requires every gspec interview — the build intake, /gspec-profile, /gspec-feature, and the rest — to ask exactly one question, wait for the answer, then ask the next, instead of sending a questionnaire in one message.

/gspec-build is a better front door. It now preflights that gspec is installed in the project for an engine (offering to install for the harness you're in), and its monitoring step distinguishes the three ways a run ends — paused for spec review (expected; summarize the specs and resume on approval), paused on a failure (relay the kept verdict verbatim, optionally resume with --qa-retries), or complete.

The install records its target. npx gspec -t <target> now writes the chosen platform to .gspec/config.json, so later commands can tell which platform the project runs on.

gspec build defaults its engine to the installed target. The --engine flag no longer hardcodes claude; resolution order is explicit --engine, then the recorded install target, then claude. A project installed for a platform without a wired engine (Cursor, Antigravity, Open Code) gets a clear error asking for an explicit --engine instead of a silent Claude fallback.

/gspec-build works fully in-session on every harness. The command's launch step now degrades gracefully: harnesses with background tasks use one, others launch the runtime detached with a log file to poll (.gspec/build/build.log). The installed AGENTS.md preamble also clarifies that gspec-* names are slash commands, never shell binaries, and that generic "go" / "continue" prompts resume an in-flight autonomous build (gspec build --resume) instead of routing to gspec-implement.

A wrong engine can no longer get pinned into a run. Before the run manifest is written, the build verifies the engine's agent files are actually installed. Codex and Pi fail fast with the exact install command; an implicit fallback to Claude with no .claude/agents/ also fails fast, while an explicitly chosen Claude engine only warns (its agents may come from the gspec plugin).

The intake handoff no longer strands the run. When the CLI opens the interactive intake session, both you and the agent are now told the deal: once the brief is written, exit the session and the runtime takes over — the agent is explicitly barred from trying to run the build itself. Intake completion is judged by the brief file on disk instead of the session's exit code, so quitting with Ctrl+C after a good interview no longer aborts the run.

Autonomous build (/gspec-build). A deterministic runtime takes an idea and drives nine stages end to end — profile → stack → practices → style → features → architecture → plan → implement → reconcile. Each stage runs as an isolated agent behind a validator gate. Foundation stages are skip-if-present, so it works on greenfield and existing projects. Runs are resumable via an on-disk manifest, self-heal on validator failure, and end with a learnings report. Available where a headless engine is wired: Claude Code, Codex, and Pi.

Producer ≠ checker quality gates. The agent that writes a spec or a slice of code is never the one that approves it. Eight read-only validator agents return structured verdicts; a new /gspec-qa command runs the same gate on demand. The implementation gate is backed by a generated verify.sh that builds and tests every deployable.

Learning loop. Failing verdicts and user corrections are captured to per-agent memory, tagged by layer. The new /gspec-distill command reviews recurring lessons and promotes them into the skills themselves, with your approval — so corrections become durable expertise instead of evaporating.

Deterministic enforcement hooks. Shell guards on lifecycle events turn soft conventions into hard floors — task immutability (checked-off work can't be silently rewritten), spec integrity, profile agnosticism, and practices enforcement — on both the interactive and build paths. Codex gets floor parity via a turn-boundary Stop-hook gate.

Every command is now agent-backed. The twelve familiar commands (profile, style, stack, practices, research, feature, architect, plan, analyze, audit, implement, migrate) are re-implemented as thin conversational orchestrators that load a persona skill and delegate the real work to isolated agents behind a quality gate. Fifteen commands in total (adding build, qa, distill).

Claude-first, degrade gracefully. One source tree builds for all six targets. Claude Code gets the full skills / agents / commands / hooks split; other harnesses collapse each agent back into a skill or command and enforce what their platform allows. See the platform capabilities matrix for the honest, harness-by-harness picture.

Pi is a first-class install target. Select it in the interactive picker or pass --target pi. Each prompt emits to .pi/prompts/<name>.md as a slash command with $ARGUMENTS substitution, and to .pi/skills/<name>/SKILL.md as a skill Pi auto-loads when a task matches its description. Spec-sync guidance is appended to AGENTS.md, which Pi loads as project instructions.

The dual-emission logic Open Code introduced is now a shared helper parameterized by command directory, so Pi (prompts/) and Open Code (commands/) build from one code path.

The generated profile is now ten sections: Overview, Mission & Vision, Target Audience, Value Proposition, Product Description, Use Cases, Market & Competition, Brand & Positioning, Public-Facing Information, and Risks & Assumptions.

Product Roadmap Vision section removed from /gspec-profile. The Current Focus / Near-Term / Long-Term horizons duplicated state that feature PRDs track precisely through prioritized capabilities and checkboxes — and unlike PRDs, the relative time windows ("3–6 months") had no anchor and silently went stale. The profile describes what the product will be; features define how it gets there.

Business Model and Success Metrics sections removed from /gspec-profile. Revenue model, pricing, customer acquisition, growth strategy, and metrics targets are go-to-market concerns, not product identity. The profile no longer asks clarifying questions about monetization. If you want this content in your profile, ask for it explicitly when running the command — the spec now includes those sections only on request.

Dual emission for Open Code. The skill form still installs to .opencode/skills/<name>/SKILL.md so the agent can auto-load a gspec prompt when the task matches its description (e.g. "build the login feature" without a slash command). On a name collision Open Code's slash menu prefers the file command, so the two coexist safely.

Open Code slash commands work. Each gspec prompt is now emitted to .opencode/commands/<name>.md, which Open Code registers as a real /gspec-* slash command with $ARGUMENTS substitution — the invocation style the post-install instructions have always described.

All 12 skill descriptions trimmed to ≤250 characters. Claude Code truncates each description to 250 chars when injecting them into the system prompt for skill selection, so anything past char 250 was wasted token budget that never reached Claude's decision. The trimmed versions front-load the trigger verbs and the "when to use this" cue while keeping the same essential intent.

Validator tightened to hard-fail at 250 characters. Previously 1024 was the hard cap and 250 was just a warning. Since 250 is Claude Code's actual selection-window limit, treating it as the build-blocking cap is the only way to keep descriptions inside the window where Claude reads them. Trying to build a skill whose description exceeds 250 chars now stops the build with a clear error.

Build-time description length validator. npm run build now fails if any description exceeds 1024 characters (the documented hard cap for Claude Code and Open Code) and warns for any description over 250 characters (Claude Code's effective selection window — content past char 250 is silently dropped when Claude decides whether to invoke a skill). The warning surfaces drift before it ships; the hard fail prevents an unparseable skill from being published.

Trimmed /gspec-analyze, /gspec-audit, and /gspec-implement descriptions to bring them inside the 1024-char cap while keeping the most important trigger words front-loaded for the 250-char selection window.

Skill frontmatter no longer breaks YAML parsing. Descriptions like /gspec-implement's, which contain phrases like "Common triggers include:" and embedded "…" example phrases, were being emitted as unquoted YAML plain scalars — illegal under the YAML 1.2 spec because ": " inside a plain scalar is interpreted as a mapping indicator. The emitter now wraps every value in a double-quoted scalar with proper escaping, applied uniformly across all five emit targets (Claude Code, Cursor, Antigravity, Codex, Open Code).

/gspec-analyze now accepts an optional feature slug to scope a run. With no argument it scans all specs for cross-spec contradictions (existing behavior, unchanged). With a slug — e.g. /gspec-analyze user-authentication — it narrows to the named feature's PRD and plan plus the foundation specs, then adds an Ambiguity & Underspecification sweep against the PRD itself: capabilities missing acceptance criteria, vague verbs ("manage", "handle"), undefined nouns referenced as if they exist, implicit state assumptions, missing edge cases, priority gaps, dependency hand-waving, and unmeasurable success metrics. Findings are framed as questions, not errors — resolve inline, mark as a Deferred Decision, or skip. The ambiguity sweep is automatically suppressed when the PRD already has a Deferred Decisions subsection covering the same questions, so it doesn't re-litigate intentional gaps.

Renamed /gspec-tasks → /gspec-plan. The sibling artifact moves from gspec/features/<feature>.tasks.md to gspec/features/<feature>.plan.md. Task IDs (T1, T2, …), [P] parallel-execution markers, deps: lines, and covers: traceback to PRD capabilities are all unchanged — only the command and filename were renamed to better reflect that the file is an approved plan the implementer executes, not a passive task list.

/gspec-implement now skips its own plan-mode approval step when every in-scope feature has a non-empty *.plan.md file. The plan was already reviewed and approved during /gspec-plan — re-approving the same content adds friction without value. Implement still presents a brief summary of what it will execute and waits for confirmation before starting work, but the heavyweight plan-mode editor flow is bypassed. Features without plan files keep the original plan-mode approval.

Slug resolution in scoped /gspec-analyze is strict — passing a slug-like input that doesn't match a file in gspec/features/ stops the run and lists the available slugs rather than silently falling back to all-specs mode. Avoids running the wrong analysis on a typo.

Running npx gspec on a fresh install no longer fails with Cannot find module '.../scripts/emitters.js'. The 1.17.0 internal refactor extracted shared emitter logic into scripts/emitters.js, but scripts/ was not in the published files list, so the runtime import in bin/gspec.js resolved to a missing file. The module has been moved to bin/emitters.js, which ships with every install.

New /gspec-tasks command — decomposes a feature PRD into a sibling gspec/features/<feature>.tasks.md file with stable task IDs (T1, T2, …), [P] parallel-execution markers, deps: lines listing prerequisite tasks, and covers: lines that quote the PRD capability text each task contributes to. Run after /gspec-feature for non-trivial features. Optional — trivial features can skip straight to /gspec-implement.

New extension system — gspec extension save <path>, gspec extension list, and gspec extension remove <name> manage user-authored skills in ~/.gspec/extensions/. Extensions are auto-installed alongside built-in commands every time you run npx gspec, using the same per-platform formatting. Names that collide with built-in gspec-* skills are rejected; malformed or duplicate extensions are skipped with a warning.

/gspec-implement now reads gspec/features/*.tasks.md alongside PRDs. When a tasks file exists for an in-scope feature, the implementation plan is built from tasks — respecting deps: ordering and surfacing [P]-marked work for parallel execution. Capability checkboxes in the PRD flip only after every task whose covers: references the capability is checked. Projects without tasks files keep the original checkbox-driven flow unchanged.

/gspec-feature ends each generated PRD with a one-line nudge to run /gspec-tasks for non-trivial features. /gspec-analyze now validates Tasks ↔ PRD coverage (every capability covered by at least one task; no orphan tasks; consistent checkbox state across both files). /gspec-audit adds a Tasks Drift category for spec-to-code mismatches in tasks files.

Internal refactor — emitter logic shared by build and install moved into scripts/emitters.js so the same per-platform formatting handles both first-party skills and user extensions. No user-visible change.

New style.html output format — a single self-contained HTML design system with design tokens as CSS custom properties, live color swatches, typography specimens, and styled component previews. Renderable in any browser and directly readable by design-aware AI tools. The /gspec-style command asks which format you prefer when neither file exists, suggesting HTML as the default for new projects. Markdown (style.md) is still fully supported — both formats are valid.

New gspec/design/ folder for external mockups — drop HTML, SVG, PNG, or JPG files from Figma, v0, Framer AI, Penpot, or any other design tool. /gspec-implement reads these mockups as authoritative visual guidance and matches their layout and hierarchy within the style guide's token constraints. The folder is drop-in only; gspec does not generate or edit its contents.

New /gspec-audit command — inspects the actual codebase (package manifests, configs, source, tests) and surfaces drift between what the specs say and what the code does. Presents each finding one at a time with the spec quote and the code evidence side by side, then asks per-finding whether to update the spec to match the code, keep the spec and flag the code for a separate fix, or defer. Distinct from /gspec-analyze (which compares specs to other specs) and complements always-on spec-sync (which catches drift as code changes happen) by sweeping for accumulated drift.

/gspec-implement, /gspec-analyze, and /gspec-migrate now read either style.md or style.html, and the spec-sync rules in CLAUDE.md / AGENTS.md / cursor rules describe gspec/design/ as read-only authoritative guidance.

Version metadata for HTML specs lives in a first-line comment (<!-- spec-version: v1 -->) before <!DOCTYPE html>. The installer, migrate command, and gspec save / gspec restore now parse both YAML frontmatter (Markdown) and HTML comments (HTML specs).

gspec save, gspec restore, and gspec playbook preserve the style guide's file extension — HTML style guides are saved under ~/.gspec/styles/<name>.html and restored as gspec/style.html; Markdown style guides continue to use .md.

/gspec-profile now adapts to the product type — commercial SaaS, internal tools, open-source libraries, research software, and personal projects. Sections like Business Model, Market & Competition, Brand, and Public-Facing Information are now marked optional with guidance to skip or adapt when a product has no external market. Commercial framing is no longer forced onto products without customers or revenue.

New "Prefer gspec skills over ad-hoc work" section in spec-sync.md that maps user intents to the matching skill. Particular emphasis on routing build/code requests — including casual prompts like "build it", "go", or "keep going" — through gspec-implement instead of direct file edits.

All gspec skill descriptions now include explicit TRIGGER guidance — listing common user phrasings (e.g. "build the app", "write a PRD", "design the architecture", "research competitors") that should invoke each skill. This helps AI tools pick the right command rather than producing the equivalent output by hand.

gspec save now reuses the existing name from a spec's frontmatter when present, prompting Overwrite existing ~/.gspec/<type>/<name>.md? [Y/n] with overwrite as the default. Re-saving an updated spec is now a single keypress instead of re-entering the name.

New spec-sync rule: "Spec before you build" — when a user asks for a feature not covered by an existing PRD in gspec/features/, the agent must run gspec-feature to create the spec before implementing.

The feature command no longer allows open questions in saved PRDs. All questions must be resolved by asking the user in conversation. Only explicitly deferred decisions are recorded.

The architect command's "Open Decisions" section now requires all technical questions to be resolved before saving. Deferred decisions are only recorded when the user explicitly declines to answer.

The stack command's "Open Questions" section renamed to "Clarifications" and now requires resolution before saving, with the same deferred-only policy.

The research command's generated PRD structure updated to match the new no-open-questions policy.

The stack, practices, architect, and research commands now include explicit profile-agnostic rules — generated documents must not contain project names, company names, or business purpose in titles, headings, or body text.

The practices overview section simplified to focus on a summary of practices rather than team-specific context.

gspec save now resets all - [x] checkboxes to - [ ] before writing to ~/.gspec/, so restored specs correctly show all capabilities as not yet implemented.

gspec save command — save any spec from your project to ~/.gspec/ organized by type (profiles, stacks, styles, practices, features).

gspec restore command — restore saved specs into a new project, either individually or from a playbook.

gspec playbook command — bundle multiple saved specs into a single restorable package for one-command project setup.

Frontmatter field renamed from gspec-version to spec-version. The migrate command handles this rename automatically.

The installer now checks ~/.gspec/ for saved specs and playbooks instead of offering bundled starter templates.

Starter templates removed — the starters/ directory and all bundled templates (stacks, practices, styles, features) have been replaced by the save & restore system.

The gspec-migrate-starters skill has been removed.

New guardrail: the agent can never skip or descope a PRD capability without user approval, even when implementation details are ambiguous.

The implementation plan must now account for every unchecked PRD capability — each must be assigned to a phase or explicitly listed under "Proposed to Defer" with a reason for user approval.

Verification phase now checks for unapproved deferrals — any capability that was planned but not implemented must be flagged and approved by the user before it can remain unchecked.

When a user prompt narrows implementation scope, excluded unchecked capabilities must be explicitly listed under "Out of Scope for This Run" in the plan.

Spec-sync is now always installed during npx gspec — no longer opt-in. The agent will always reference gspec files to stay within specification boundaries.

Starter template selection now includes a None — I will define my own option for each category (practices, stack, style, and features), giving full control over which templates to seed.

Removed the profile check from the starter template flow. The CLI now displays a prominent "Next Step" banner after install instructing users to run /gspec-profile before continuing.

Open Code platform support — npx gspec --target opencode installs skills to .opencode/skills/.

The installer no longer flags gspec/README.md as needing migration.

Starter template seeding during npx gspec install — choose from pre-built practices, technology stacks, visual styles, and common feature PRDs to populate your gspec/ directory instantly.

Starter template library with templates for multiple stacks (Next.js + Supabase + Vercel, Next.js + Vercel + TypeScript, Astro + Tailwind + GitHub Pages), practices (TDD pipeline-first), styles (clean professional, dark minimal developer), and common features (home page, about page, contact form, navbar, footer, theme switcher, and more).

New gspec-migrate-starters command for migrating starter templates to the current gspec format (project maintenance).

The starters/ directory is now included in the published npm package.

Clarified document authority — stack is the single authority for testing tool choices and CI/CD technology, style is the single authority for icon libraries. Stack technology-specific practices take precedence over general practices for framework-specific concerns.

Component styling guidance refined — style focuses on visual appearance only (colors, spacing, typography), while stack owns component library selection (shadcn/ui, Radix, Headless UI).

Multi-feature output guidance — when generating multiple PRDs, the feature command cross-references dependencies, maintains consistent terminology, assigns priorities holistically, and suggests a build order.

Releases page added to the documentation site.

The feature command now intelligently assesses scope — if the request is small, it produces a single PRD; if it's large enough to warrant decomposition, it proposes a multi-feature breakdown for your approval before generating individual PRDs.

All commands that previously referenced epics (implement, architect, analyze, research, migrate) have been updated to remove epic references and work with the unified feature command.

The epic command has been removed. All of its functionality is now part of feature. The gspec/epics/ directory is no longer used.

Automatic spec-sync system — AI tools now read specs before making changes and update them when code diverges from documented intent, without needing explicit commands.

GitHub Pages documentation site with getting started guide, full command reference, and workflow overview.

The dor and record commands have been removed. Their functionality is replaced by the automated spec-sync rules.

Fixed the architect command description metadata in the build output.

New analyze command — cross-references all existing specs, identifies contradictions and inconsistencies, and walks you through resolving each one interactively.

Refined the overall spec workflow to position analyze between architect and implement for catching conflicts before building.

Codex platform support — npx gspec --target codex installs skills to .agents/skills/.

New standalone research command — analyzes competitors from the product profile, produces a competitive feature matrix, identifies gaps, and proposes additional features.

Simplified the implement command by removing its built-in competitor research phase. Research now happens separately before implementation.

All spec-generating commands now require clarifying questions in chat before finalizing output — no more unresolved questions embedded in generated documents.

Clarified that architect, epic, and feature are optional — you can skip straight to implement for simpler projects.

New architect command — generates a technical architecture document with project structure, data model (ER diagrams), API design, component architecture, auth flows, and technical gap analysis.

New migrate command — updates existing gspec documents to the current format when upgrading versions, preserving all content.

Mermaid diagrams in architect output — entity-relationship diagrams for data models, page hierarchy graphs, and sequence diagrams for auth flows.

Version tracking via gspec-version YAML frontmatter in all generated spec files.

Feature PRDs consolidated from 10 sections to 7, removing redundancy and improving clarity.

All command outputs refined for agent-oriented consumption — technology-agnostic, implementation-ready, with explicit acceptance criteria.

The implement command now has an explicit planning phase with user approval and pauses between implementation phases.

Added repository URL to package.json for npm listing.

Core specification commands: profile, style, stack, practices, feature, epic, implement, dor, record.

Build pipeline and npx gspec installer for Claude Code, Cursor, and Antigravity.

Incremental implementation tracking with capability checkboxes in feature PRDs.