gspec

Documentation

Complete reference for the gspec workflow and all 16 commands.

Workflow Overview

gspec organizes product specification into a structured workflow. Each stage builds on the previous, giving your AI coding tools progressively deeper context.

Define req
profile, style, stack, practices
Research
research
Specify
feature
Architect
architect
Plan
plan
Analyze
analyze, audit
Build req
implement

Only Define and Build are required. The four Define commands (profile, style, stack, practices) establish your product foundation. The implement command reads all specs and builds software. Everything in between adds optional depth — use what your project needs.

Don't want to run each stage yourself? The build command runs this entire workflow autonomously — from an idea to working, verified code — with a quality gate at every stage. See the autonomous build →

Most specs are Markdown files stored in a gspec/ directory in your repository. The style guide can alternatively be a self-contained HTML design system (style.html) that renders tokens and component previews directly in a browser — useful for design-aware AI tools. An optional gspec/design/ folder holds mockups (HTML, SVG, PNG, JPG) exported from external design tools; the implement command reads them as authoritative visual guidance. All files are version-controlled, human-readable, and automatically kept in sync through gspec's spec-sync system.

Save & Restore

Once you've built specs you're happy with, save them to ~/.gspec/ for reuse across projects. Bundle multiple specs into playbooks for one-command project setup.

Save a spec

Run gspec save to save any spec from your current project. You give it a name and optional description, and it's stored in ~/.gspec/ organized by type (profiles, stacks, styles, practices, features).

Restore a spec

Run gspec restore to interactively pick a saved spec, or pass the path directly: gspec restore stacks/my-stack. The spec is copied into your project's gspec/ directory.

Templates

Restoring copies a spec in verbatim. Your saved specs also act as templates: when gspec writes a stack, style, practices guide, or feature PRD, it first looks in the matching ~/.gspec/ folder for one to start from — offering the match for you to choose in a command, or adopting the single best fit in an autonomous gspec build. A template is adapted to the new project, never copied blindly, and the writer reports which one seeded the spec. profile.md and architecture.md are never seeded — both are inherently project-specific.

Playbooks

Run gspec playbook to bundle multiple saved specs — profile, stack, practices, style, and features — into a single restorable package. Restore an entire playbook with gspec restore playbook/my-starter.

Install flow

When you run npx gspec in a new project, the installer checks ~/.gspec/ for saved specs. If playbooks exist, you're offered them first. Otherwise, you can pick individual specs from each category. If ~/.gspec/ is empty, the installer skips straight to post-install guidance.

See the full save & restore documentation for detailed examples.

Extensions

Extensions are user-authored skills that install alongside the built-in gspec commands. They live in ~/.gspec/extensions/ as Markdown files with frontmatter, and are auto-installed into every project the next time you run npx gspec.

An extension is a complete skill — same shape as anything in gspec's own commands/ folder. Use them for organization-specific or project-class-specific commands you want available everywhere without forking gspec or copy-pasting into each project.

Authoring

Write an extension as a Markdown file with two required frontmatter fields:

markdown 
---
name: my-deploy
description: Trigger and manage deploy workflows. Run after tests pass.
---

You are a Deployment Engineer.
... rest of the skill body ...

The name must be lowercase letters, digits, and hyphens, and must not collide with a built-in gspec-* skill. Names like my-deploy, release-notes, or jira-sync are fine; gspec-implement is rejected.

Manage extensions

shell 
gspec extension save ./my-deploy.md   # Install into ~/.gspec/extensions/
gspec extension list                  # See what's installed
gspec extension remove my-deploy      # Delete from ~/.gspec/extensions/

Removing an extension only deletes it from ~/.gspec/extensions/ — already-emitted copies in projects (under .claude/skills/, .cursor/commands/, etc.) stay in place. Delete them per-project if desired.

Install behavior

When you run npx gspec in a project, the installer first copies the built-in skills, then scans ~/.gspec/extensions/ and emits each valid extension into the same install directory using the same per-platform formatting as core skills. Invalid extensions (missing frontmatter, name collisions, malformed names) are skipped with a warning. Two extensions claiming the same name resolve last-write-wins, also with a warning.

profile Product Strategist

What it does

Defines what your product is, who it serves, and why it exists. This is the foundational spec that all other commands reference — it establishes product identity, target audience, value proposition, and market positioning.

What it produces

A comprehensive product profile saved to gspec/profile.md. Includes product overview, target audience with pain points, value proposition, use cases, competitive landscape, and key messaging.

Example invocation

command 
/gspec-profile

Key questions

The command guides you through a conversation covering:

  • Product name, tagline, and category
  • Target audience and their pain points
  • Core value proposition and differentiation
  • Key use cases and scenarios
  • Market context and competitive landscape

Best practices

  • Run this first — it's the foundation everything else builds on
  • Be specific about your target audience; vague audiences produce vague specs
  • Include real pain points you've observed, not hypothetical ones
  • Keep the tagline under 10 words and the elevator pitch under 2 sentences

Common pitfalls

  • Skipping the profile and jumping to style or stack — downstream specs lack context
  • Being too broad with the target audience ("all developers" tells the AI nothing)
  • Filling in aspirational features as if they exist today

Related commands

  • style — Reads profile to align design with brand personality
  • stack — Reads profile to recommend technology appropriate for the audience
  • research — Uses profile to identify competitors and market gaps

style UI Designer

What it does

Generates a visual design system with colors, typography, spacing, component patterns, and design tokens. Adopts the perspective of a UI Designer to create a cohesive visual language for your product. Supports two output formats: a renderable HTML design system (style.html) — a single self-contained file with live swatches, type specimens, and styled component previews, readable by design-aware AI tools — or a Markdown style guide (style.md). Either format is valid; gspec consumers read whichever is present. A complementary gspec/design/ folder can hold mockups (HTML, SVG, PNG, JPG) from external design tools like Figma, v0, or Framer AI, which the implement command reads as authoritative visual guidance.

What it produces

A single style guide saved as gspec/style.html (recommended — a renderable HTML design system with design tokens as CSS variables, color swatches, typography specimens, and live styled component examples for light and dark mode) or gspec/style.md (a Markdown style guide with the same structured content as prose). In both formats: color palette with hex/RGB/HSL values, typography scale, spacing system, component specifications (buttons, cards, forms), theme tokens for dark/light mode, and accessibility guidelines. In style.html the token block is the single source of truth: it is the only place a literal color value appears (everything else uses var(--…) — enforced by a hard-floor hook on Claude Code), and the accessibility contrast table is computed from the tokens by an inline script per theme, so it can never drift from the values it describes.

Example invocation

command 
/gspec-style

Key questions

The command guides you through a conversation covering:

  • Preferred output format (HTML renderable design system or Markdown style guide)
  • Design vision and visual personality (minimal, bold, playful, etc.)
  • Target platforms (web, mobile, desktop)
  • Brand colors or color preferences
  • Typography preferences
  • Dark mode, light mode, or both

Best practices

  • Run profile first so the style command can align design with brand personality
  • Provide a clear visual personality direction — "clean and minimal" produces better results than "nice"
  • Review the generated color palette for accessibility compliance (WCAG AA contrast ratios)
  • Prefer style.html when your workflow includes design-aware AI tools — they can render and reason about it directly
  • Drop mockups from external design tools into gspec/design/ so /gspec-implement can match their layouts
  • The style guide is consumed by implement — keep it structured and specific

Common pitfalls

  • Generating a style guide without a profile — the design won't reflect your product's personality
  • Maintaining both style.html and style.md for the same project — pick one as the source of truth
  • Over-specifying in the conversation and constraining the Designer role too much
  • Ignoring accessibility requirements in the output — check contrast ratios

Related commands

  • profile — Style reads profile for brand personality and audience context
  • implement — Implement reads style and gspec/design/ mockups for all UI decisions (colors, spacing, components, layout)

stack Solutions Architect

What it does

Defines your technology choices — frameworks, languages, runtime, database, hosting, and key libraries. Documents every decision with rationale so your AI tools make consistent technology choices.

What it produces

A technology stack definition saved to gspec/stack.md. Includes core languages, runtime environment, frontend and backend frameworks, database, hosting, CI/CD, package management, and technology-specific practices.

Example invocation

command 
/gspec-stack

Key questions

The command guides you through a conversation covering:

  • Programming languages and runtime environment
  • Frontend framework and styling approach
  • Backend framework and API style
  • Database and data storage
  • Hosting, deployment, and CI/CD
  • Key libraries and third-party integrations

Best practices

  • Run profile first — the stack should match your audience and scale requirements
  • Document the "why" behind each technology choice, not just the "what"
  • Include version constraints (e.g., "Node 20 LTS") to prevent AI tools from using incompatible versions
  • Note anti-patterns specific to your stack (e.g., "Don't use CSS-in-JS alongside Tailwind")

Common pitfalls

  • Listing technologies without rationale — the AI can't make good tradeoff decisions without context
  • Forgetting to specify development tools (linters, formatters) that affect code style
  • Not mentioning infrastructure constraints that impact architecture decisions

Related commands

  • profile — Stack reads profile for scale and audience context
  • architect — Architect reads stack for technology constraints
  • implement — Implement reads stack for framework and library choices

practices Engineering Lead

What it does

Establishes development standards — testing conventions, code quality rules, git workflow, error handling, documentation requirements, and your definition of done. Ensures your AI produces code that meets your team's standards.

What it produces

A development practices guide saved to gspec/practices.md. Includes testing standards (unit, E2E, when to write tests), code quality rules, naming conventions, git practices, error handling patterns, security practices, and definition of done.

Example invocation

command 
/gspec-practices

Key questions

The command guides you through a conversation covering:

  • Team size and collaboration model
  • Testing philosophy and frameworks
  • Code review process and standards
  • Git branching strategy and commit conventions
  • Error handling and logging patterns
  • Security practices and vulnerability prevention

Best practices

  • Be specific about testing expectations — "test important logic" is less useful than "unit test all non-trivial functions, E2E for critical user flows"
  • Include naming conventions for files, variables, and functions
  • Document your definition of done as a checklist the AI can reference
  • Mention what NOT to test — this prevents the AI from over-testing trivial code

Common pitfalls

  • Writing aspirational practices that your team doesn't actually follow
  • Being too vague — "write good tests" gives the AI no guidance
  • Forgetting to mention your error handling philosophy (fail fast vs. graceful degradation)

Related commands

  • stack — Practices references stack for testing framework and tooling choices
  • implement — Implement reads practices for code quality, testing, and git standards

research Market Analyst

What it does

Analyzes competitors based on your product profile and produces a competitive analysis with feature matrix, strengths/weaknesses, and gap identification. Helps you understand the landscape before committing to features.

What it produces

A competitive analysis saved to gspec/research.md. Includes competitor profiles, feature comparison matrix, strengths/weaknesses analysis, market gaps, and strategic recommendations.

Example invocation

command 
/gspec-research

Key questions

The command guides you through a conversation covering:

  • Known competitors or similar products
  • Specific areas to investigate (features, pricing, market positioning)
  • Your product's intended differentiation

Best practices

  • Run profile first — research uses your product identity to identify relevant competitors
  • Name specific competitors if you know them; the AI will also discover others
  • Focus the research on your product's differentiating areas, not every possible feature
  • Use research findings to inform feature prioritization

Common pitfalls

  • Running research without a profile — the AI doesn't know what market you're in
  • Taking the competitive analysis as exhaustive truth — verify key claims
  • Feature-stuffing your roadmap based on what competitors have rather than what your audience needs

Related commands

  • profile — Research reads profile for product identity and market context
  • feature — Research findings can inform feature PRD priorities

feature Product Manager

What it does

Writes one or more product requirements documents (PRDs) for features. Handles both single features and larger bodies of work — if the scope is large enough, it proposes a multi-feature breakdown for your approval before generating individual PRDs.

What it produces

One or more feature PRDs saved to gspec/features/<slug>/prd.md. Each includes overview, user stories, scope (in/out/deferred), prioritized capabilities with acceptance criteria, dependencies, assumptions and risks, and success metrics.

Example invocation

command 
/gspec-feature "Task board with drag-and-drop columns"

Key questions

The command guides you through a conversation covering:

  • Feature description and user need it addresses
  • Target users and their workflows
  • Scope boundaries — what's in and what's explicitly out
  • For large requests: how to decompose into independent features
  • Edge cases and error scenarios
  • Dependencies on other features or systems

Best practices

  • Describe the user need, not the solution — let the Product Manager role shape the requirements
  • Be explicit about scope boundaries to prevent feature creep
  • P0 capabilities should be the minimum for the feature to be useful
  • For large initiatives, review the proposed feature breakdown before the PRDs are generated

Common pitfalls

  • Describing implementation details instead of user needs in the feature description
  • Making everything P0 — if everything is critical, nothing is prioritized
  • Over-decomposing small work into multiple features — only split when sub-features deliver independent user value

Related commands

  • architect — Architect reads feature PRDs to design the technical blueprint
  • implement — Implement builds against feature PRD capabilities and checks them off

architect Technical Architect

What it does

Designs the technical architecture — project structure, data model, API design, component architecture, and environment configuration. Reads your stack, practices, and feature PRDs to produce a comprehensive blueprint. The file layout follows the Modules table and is always two-tier: a system-level architecture.md (shared data model, inter-module contracts, cross-cutting auth, the Modules table) plus one gspec/architecture/<name>.md per row — including a single-module project — carrying that unit's internals and its spine, the architecture anchors more than one feature references. Each sub-file carries routing frontmatter so downstream commands load only the units their work touches.

What it produces

A technical architecture document saved to gspec/architecture.md, plus one gspec/architecture/<name>.md per Modules-table row, linked from its row. Includes project structure with directory layout, data model, API design, component architecture, environment configuration, CI/CD setup, and a technical gap analysis. Every concern is stated exactly once, at the tier that owns it.

Example invocation

command 
/gspec-architect

Key questions

The command guides you through a conversation covering:

  • Architectural patterns and preferences
  • Data model requirements
  • API style and endpoint structure
  • Component organization and relationships
  • Deployment and environment concerns

Best practices

  • Run after defining features — the architect needs requirements to design against
  • Run after stack — the architect needs technology constraints
  • Review the gap analysis section carefully — it identifies contradictions between specs
  • The architecture document is the most influential spec for implement — invest time reviewing it

Common pitfalls

  • Running architect before feature PRDs exist — produces a generic architecture
  • Skipping the gap analysis review — contradictions between specs cause confused implementation
  • Over-constraining the architecture for a simple project — not every project needs a detailed data model

Related commands

  • stack — Architect reads stack for technology constraints and patterns
  • feature — Architect reads feature PRDs to design the technical structure
  • analyze — Run analyze after architect to catch cross-spec contradictions
  • implement — Implement reads architecture for project structure, data model, and APIs

plan Engineering Lead

What it does

Decomposes a feature PRD into an ordered, dependency-aware plan with explicit parallel-execution markers. Sits between feature (the 'what') and implement (the 'how'). Reads the PRD plus the architecture and stack for ordering signals, then proposes 1–N concrete tasks per capability with stable IDs, deps lines, and [P] markers for tasks that are safe to run in parallel. When a plan file exists, implement skips its own plan-mode step and executes the plan directly.

What it produces

A sibling file at gspec/features/<slug>/tasks.md with YAML frontmatter linking it back to the PRD, plus a single ## Plan section containing ordered, checkboxed tasks. Each task carries a priority (P0/P1/P2), an optional [P] marker, a deps: line listing prerequisite task IDs, and a covers: line quoting the PRD capability text the task contributes to.

Example invocation

command 
/gspec-plan "home-page"

Key questions

The command guides you through a conversation covering:

  • Which feature PRD to decompose (if multiple PRDs exist)
  • Whether to regenerate from scratch or extend an existing plan file

Best practices

  • Run after feature (and after architect when it exists) so technical context informs the decomposition
  • Skip for trivial features — implement's checkbox-driven planning is enough when there's nothing to parallelize and nothing depends on anything
  • Keep tasks small enough that a single implementation pass can finish and verify each one
  • Prefer to leave [P] off when in doubt — false parallelism causes more pain than missed parallelism

Common pitfalls

  • Marking [P] on tasks that write to the same file as a sibling — one will overwrite the other
  • Renumbering existing task IDs on regenerate — IDs are stable, append new ones at the next free number
  • Inventing acceptance criteria for an underspecified PRD — fix the PRD with /gspec-feature first instead
  • Treating the plan file as a rewrite of the PRD — capabilities stay in the PRD, execution stays in the plan

Related commands

  • feature — Plan decomposes the PRD that feature produced — every task line traces back to a capability via covers:
  • architect — Plan reads architecture for ordering signals (e.g., schema before API, API before UI)
  • implement — When a plan file exists for every in-scope feature, implement skips plan mode and executes the plan directly — respecting deps and [P] markers — updating task checkboxes as work completes
  • analyze — Analyze validates that every PRD capability is covered by at least one task and that no task references a missing capability

analyze Quality Analyst

What it does

Cross-references gspec documents and identifies discrepancies. Has two modes. (1) All-specs (no argument): scans every spec for contradictions across the full set — stack vs architecture, PRD vs architecture, plan vs PRD, and (on a two-tier architecture) the system-level architecture.md vs its per-module architecture/<name>.md sub-files: tier disagreements, concerns duplicated across tiers, and sub-files orphaned from or missing for a Modules-table row. (2) Scoped (pass a feature slug): narrows to one feature's PRD and plan plus the foundation specs, then adds an Ambiguity & Underspecification sweep against the PRD itself, catching missing acceptance criteria, vague verbs, undefined nouns, implicit assumptions, missing edge cases, and unmeasurable success metrics. Findings are presented one at a time with resolution options; the user decides each individually.

What it produces

A list of findings — contradictions, or in scoped mode also ambiguity questions — each presented with the conflicting evidence (or, for ambiguity, the unclear text and a specific question). With your per-finding approval, affected spec files are updated in place. At the end, a summary of resolved, deferred, and skipped findings.

Example invocation

command 
/gspec-analyze
# or, scoped to one feature:
/gspec-analyze user-authentication

Key questions

The command guides you through a conversation covering:

  • Optional feature slug — when present, scope to that feature and run the ambiguity sweep; when absent, scan all specs for cross-spec conflicts
  • For each finding, whether to update the spec, mark it as a Deferred Decision, or skip

Best practices

  • Run all-specs analyze after architect and before implement for the most comprehensive sweep
  • Run scoped analyze on each feature PRD before /gspec-plan (or before /gspec-implement when skipping plan) to catch ambiguity early
  • Use scoped mode on aged or imported PRDs that may have accumulated implicit assumptions
  • Review findings and accept or reject each recommendation — do not blindly apply all
  • Re-run after significant edits to the targeted feature or to any foundation spec

Common pitfalls

  • Running all-specs analyze with only one or two specs — it needs multiple specs to find cross-references
  • Passing a feature slug that does not match a file in gspec/features/ — analyze will stop and ask you to pick from the available slugs rather than silently fall back
  • Skipping the ambiguity sweep on aged PRDs and trusting old documents that no longer reflect implicit team knowledge
  • Treating ambiguity questions as errors — they are deliberate prompts; the answer can be "mark this as a Deferred Decision" rather than resolving inline

Related commands

  • feature — Generation-time clarification in /gspec-feature catches ambiguity before the PRD is saved; scoped /gspec-analyze catches what slipped through or accumulated later
  • plan — Run scoped /gspec-analyze on a PRD before /gspec-plan so the plan is built from a clean spec
  • architect — All-specs /gspec-analyze catches contradictions between architecture and other specs
  • implement — Run /gspec-analyze before /gspec-implement to ensure specs are consistent and unambiguous
  • audit — Analyze compares specs to other specs; audit compares specs to the codebase

audit Specification Auditor

What it does

Reads the specs and inspects the actual codebase, then surfaces drift between what the specs say and what the code does — mismatched dependencies, undocumented routes, stale data models, design tokens that don't match the stylesheet, capability checkboxes that don't reflect reality. Walks you through each discrepancy and — with your approval — updates the specs to match reality. Distinct from analyze, which compares specs against each other rather than against the codebase. Complements always-on spec-sync (which catches drift as code changes happen) by sweeping for accumulated drift that slipped through.

What it produces

A list of findings where each drift is cited with the exact spec statement and the matching evidence in code. With your per-finding approval, affected spec files are updated in place. At the end, a summary of updates made, items deferred, and a code-follow-up list for any drift the user chose to fix in the code rather than the spec.

Example invocation

command 
/gspec-audit

Key questions

The command guides you through a conversation covering:

  • Optional scope hint (e.g., "just audit the stack", "audit the features/ folder") — without a hint, audit sweeps all specs
  • Whether to update specs to match code, leave specs alone (and flag code for fix), or defer on a per-finding basis

Best practices

  • Run audit before shipping a major release or before handing the project to a new contributor
  • Run audit after a long sprint where spec-sync may have missed changes (e.g., rapid iterative sessions)
  • Pass a scope hint for large codebases — audit one domain at a time (stack, then architecture, then features)
  • Use the code-follow-up list from audit as input for the next /gspec-implement run
  • Treat profile drift conservatively — the profile is often aspirational, not descriptive

Common pitfalls

  • Running audit on a brand-new project with no code — there's nothing to compare specs against
  • Blindly choosing "update spec to match code" for every finding — some drift means the code is wrong, not the spec
  • Using audit as a substitute for /gspec-implement — audit never modifies code
  • Auditing a massive codebase in one pass — prefer scoped sweeps for comprehension

Related commands

  • analyze — Analyze finds spec-to-spec contradictions; audit finds spec-to-code drift
  • implement — Audit's code-follow-up list feeds the next implement run when code needs to change
  • migrate — Run migrate first if specs use an outdated format before auditing against code

build Build Orchestrator

What it does

Runs the entire gspec workflow autonomously — from a plain-language idea to working, verified code. Holds a single up-front intake interview, then launches a deterministic runtime that drives nine stages in order (profile → stack → practices → style → features → architecture → plan → implement → reconcile). Each stage runs as an isolated agent gated by an independent validator (producer ≠ checker). Between plan and implement the run pauses once — every spec written, no code yet — for a human spec review; resume approves it, or skip it with --no-review. Foundation specs that already exist are reused, not regenerated, and an existing architecture is amended rather than rewritten — a deterministic floor stops a module row being renamed out from under the feature specs that point at it — so build works on greenfield and existing projects alike. Runs on harnesses with a wired headless engine — today Claude Code, Codex, and Pi.

What it produces

A working product: specs in gspec/, an ordered plan, and implemented code that passes a generated verify.sh build-and-test gate. The run is tracked in a resumable on-disk manifest, self-heals on validator failure (one revision attempt by default; set the budget with --qa-retries) — each revision is a surgical repair that carries every verdict so far, so later attempts see what earlier ones were told instead of regenerating the draft — and pauses with the full failing verdict in .gspec/build/last-failure.md when a gate still fails. It ends by recording the learnings captured during the run.

Example invocation

command 
/gspec-build

Key questions

The command guides you through a conversation covering:

  • A plain-language description of what you want to build
  • Essentials the intake needs up front (audience, platform, key constraints) — asked once, so the run doesn't stop to re-ask

Best practices

  • Use build to go from zero to a working baseline, then switch to individual commands for hands-on refinement
  • Run it in a supported harness (Claude Code, Codex, or Pi) — other harnesses get the full interactive workflow but not the autonomous build
  • Let existing specs stand — build skips foundation stages whose spec already exists
  • Use the spec-review pause to read and edit gspec/ before any code is written; resume when it looks right (or pass --no-review to run straight through)
  • If a QA gate keeps failing on a hard stage, resume with --qa-retries <n> to give it a bigger self-heal budget instead of fixing everything by hand
  • Cut token cost by assigning models per agent in .gspec/config.json (or ~/.gspec/config.json) — put QA and foundations on a cheaper model, keep the strong one for architecture and implementation
  • Review the report at the end; it feeds the memorize step

Common pitfalls

  • Expecting an autonomous build on a harness without a wired engine — use the interactive commands there instead
  • Treating it as fully unattended — a failing quality gate pauses the run for your input by design
  • Skipping the intake — a vague idea produces a vague foundation

Related commands

  • implement — Build runs implement as its implementation stage, gated by verify.sh and the implementation validator
  • qa — Build applies the same producer ≠ checker quality gate that qa runs on demand
  • memorize — Build records memories each run; memorize commits recurring ones to skills

implement Senior Developer

What it does

Reads all existing gspec documents and implements your software with full project context. Synthesizes profile, style (style.md or style.html), stack, practices, architecture, and feature PRDs, plus any mockups in gspec/design/, to produce code that matches your specifications. When design mockups are present, implement matches their layout and visual hierarchy within the style guide's token constraints.

What it produces

Working code committed to your repository. Updates feature PRD capability checkboxes from [ ] to [x] as each capability is implemented. Produces code that follows your stack, practices, and style specifications.

Example invocation

command 
/gspec-implement

Key questions

The command guides you through a conversation covering:

  • Which feature(s) to implement (if multiple exist)
  • Any additional context or constraints for this implementation session

Best practices

  • At minimum, have the four Define specs (profile, style, stack, practices) before running implement
  • Feature PRDs give the best results — implement works from prioritized capabilities, not vague descriptions
  • Run implement incrementally — one feature at a time, reviewing output between runs
  • Check the capability checkboxes in your feature PRD to track progress
  • If output quality is low, the issue is usually in the specs — improve your specs, not your prompts

Common pitfalls

  • Running implement with no specs — produces generic code with no project context
  • Implementing everything at once instead of one feature at a time
  • Not reviewing the generated code — implement is a tool, not an autopilot
  • Blaming implement for poor output when the real issue is vague or contradictory specs

Related commands

  • profile — Implement reads profile for product context and audience
  • style — Implement reads the style guide (style.md or style.html) plus any gspec/design/ mockups for all visual and UI decisions
  • stack — Implement reads stack for technology choices and patterns
  • practices — Implement reads practices for code quality and testing standards
  • feature — Implement builds against feature PRD capabilities
  • architect — Implement reads architecture for project structure and data model — on a two-tier architecture it loads only the per-module sub-files its scope touches, routed by their frontmatter

qa QA Lead

What it does

Runs gspec's quality gate on demand. Delegates to read-only validator agents that check your specs and code against their acceptance criteria and quality bars, then presents each verdict. It embodies the producer ≠ checker principle: the agent that grades the work is never the one that wrote it. qa never edits — it only judges and reports, leaving the fixes to you or to the relevant command.

What it produces

A set of validator verdicts — pass or fail with specific reasoning per finding — across the specs and/or code you point it at. No files are modified.

Example invocation

command 
/gspec-qa

Key questions

The command guides you through a conversation covering:

  • What to check — a spec type, a feature, or the implementation
  • Any acceptance criteria or definition-of-done to weigh the verdict against

Best practices

  • Run qa before a release or before handing work off, as an independent second opinion
  • Use it to sanity-check specs an agent produced before you build against them
  • Treat a failing verdict as a prompt to fix the source, then re-run

Common pitfalls

  • Expecting qa to fix what it finds — it is read-only by design
  • Ignoring verdicts because they are advisory in interactive use — during an autonomous build the same gate is enforced

Related commands

  • build — Build runs this gate automatically after every producer stage
  • audit — Audit checks specs against code drift; qa checks work against its acceptance criteria and quality bars

memorize Steward

What it does

The reviewer half of gspec's learning loop. When validators reject work or you correct an agent, that memory is recorded to .gspec/memory/pending/ — one file per memory, tagged with the layer it belongs to. memorize reviews those pending memories and proposes surgical edits that commit recurring ones to the skills themselves — presented one at a time for your approval — then deletes the ones that have graduated. Corrections become durable, reusable expertise instead of evaporating after a session.

What it produces

Approved edits to skill files that fold in recurring memories, plus deletion of the pending entries that have graduated. Every change is reviewed and approved by you before it is applied.

Example invocation

command 
/gspec-memorize

Key questions

The command guides you through a conversation covering:

  • Which pending memories to review (all, or scoped to a layer or agent)
  • For each proposed skill edit, whether to apply, modify, or skip

Best practices

  • Run memorize periodically after several build or interactive sessions, once memories have accumulated
  • Review each proposed edit — memorize suggests, you decide
  • Let it delete graduated memories so pending stays focused on what is still unresolved

Common pitfalls

  • Running it with no recorded feedback yet — there is nothing to review on a fresh install
  • Blindly approving every proposed edit — skills are load-bearing, so review the wording

Related commands

  • build — Build records the memories that memorize later reviews
  • qa — A failing qa verdict is one of the signals recorded as a memory
  • teach — teach is the same reviewed edit, started from your correction instead of memory

teach Steward

What it does

The other half of the learning loop — the half that starts with you. memorize can only commit what an agent already recorded after something went wrong, so it is powerless when nothing went wrong from any agent's point of view: a spec that satisfies its own quality bar while missing something the bar never thought to ask for. The writer follows its guide exactly, the validator checks it against that same guide and passes it, and the output is self-consistently incomplete — no failure, so nothing recorded, so nothing to review. teach lets you state the correction directly. The memorizer works out where it belongs and drafts the minimal edit; you approve before anything changes.

What it produces

Approved, surgical edits to the skill, agent or command files that govern how an agent works — plus an explicit verdict on whether the edit survives your next gspec upgrade.

Example invocation

command 
/gspec-teach <what the agent should do differently>

Key questions

The command guides you through a conversation covering:

  • What should change about how the agent works (name a target, or just describe the symptom)
  • For each proposed edit, whether to apply, modify, or skip

Best practices

  • Describe the symptom you saw — you do not have to know which file governs it, that is the job
  • Expect two proposals for one correction: the rule itself, and the quality bar a validator checks against
  • Reach for it when reviewing built output, which is where the gaps no gate can catch actually show up

Common pitfalls

  • Using it for a product decision — anything true of this product belongs in gspec/ via its own command, not in a skill
  • Applying only the rule and skipping the quality-bar edit, which teaches the writer but leaves the checker unable to catch a regression
  • Assuming the edit is permanent in an installed project — skills under .claude/skills/ are overwritten on the next upgrade, and teach tells you when that applies

Related commands

  • memorize — The same reviewed edit path, sourced from recorded memories rather than from you
  • build — Reviewing a build's output is where corrections worth teaching usually surface

migrate Migration Specialist

What it does

Upgrades existing gspec documents to the current format when you move to a newer version of gspec. Reads your existing specs, maps them onto the latest structure, and rewrites them in place — preserving all of your content while updating headings, frontmatter, and section organization to match what the current commands expect.

What it produces

Your existing gspec/ files, rewritten to the current format with content preserved. Version metadata (spec-version frontmatter, or the style.html version comment) is updated to reflect the new format.

Example invocation

command 
/gspec-migrate

Key questions

The command guides you through a conversation covering:

  • Which specs to migrate (all, or a specific file) when formats differ
  • How to resolve any content that does not map cleanly onto the new structure

Best practices

  • Run migrate right after upgrading gspec, before running other commands against old specs
  • Commit your specs first so the rewrite is easy to review as a diff
  • Run audit afterward to confirm the migrated specs still match your code

Common pitfalls

  • Running migrate when specs are already current — it is only needed on a version bump that changes formats
  • Not reviewing the diff — migrate preserves content but reorganizes structure

Related commands

  • audit — Run migrate to fix outdated formats, then audit to check the migrated specs against code