Documentation

Workflow Overview

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

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.

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.

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:

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

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.