Releases

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.

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, OpenCode).

Build-time description length validator. npm run build now fails if any description exceeds 1024 characters (the documented hard cap for Claude Code and OpenCode) 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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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.

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.

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.

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

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

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.