Save & Restore

Overview

Once you've built specs you're happy with — a technology stack, a visual style, development practices, feature PRDs — you can save them to ~/.gspec/ for reuse in future projects. No more redefining the same stack or style from scratch every time.

Saved specs are organized by type:

~/.gspec/
├── profiles/        # Product profiles
├── stacks/          # Technology stacks
├── styles/          # Visual styles
├── practices/       # Development practices
├── features/        # Feature PRDs
└── playbooks/       # Bundled spec sets

These are plain Markdown files on your machine. Share them with teammates by copying them, checking them into a dotfiles repo, or distributing them however you like.

Save

Save any spec from your current project to ~/.gspec/ for reuse:

gspec save

The CLI lists your project's gspec files and prompts you to select one. You give it a name (e.g. my-saas-stack) and an optional description. The spec is saved to the corresponding type folder — for example, ~/.gspec/stacks/my-saas-stack.md.

$ gspec save

  Which spec would you like to save?

  1) gspec/stack.md — Next.js App Router with Supabase
  2) gspec/style.md — Dark minimal design system
  3) gspec/practices.md — TDD pipeline-first

  Select [1-3]: 1

  Save name (no spaces, e.g. my-saas-stack): nextjs-supabase

  ✓ Saved to ~/.gspec/stacks/nextjs-supabase.md

Restore

Restore a saved spec into a new project:

gspec restore

Interactive mode walks you through selecting a type and then a specific spec. Or pass the path directly:

gspec restore stacks/nextjs-supabase

The spec is copied into your project's gspec/ directory. If the saved spec was created with an older gspec version, you'll be prompted to run /gspec-migrate to update it.

Templates

Restoring copies a saved spec in verbatim. Your library does a second job that needs no command at all: when gspec writes a spec, it first looks for a saved one to start from. A saved spec used this way is a template — a proven starting point rather than a blank page.

Four spec types have a template library, one folder each:

~/.gspec/stacks/      →  seeds  gspec/stack.md
~/.gspec/styles/      →  seeds  gspec/style.md · style.html
~/.gspec/practices/   →  seeds  gspec/practices.md
~/.gspec/features/    →  seeds  gspec/features/<slug>/prd.md

profile.md and architecture.md are deliberately excluded — both are inherently specific to one project, so neither is ever seeded from a template. (You can still save and restore a profile; it just won't be used as a starting point for a written one.)

How a template gets chosen

Matching is on each file's frontmatter name and description, so a useful description is worth writing — it is what gspec reads to decide whether a template fits.

• In a command (/gspec-stack, /gspec-style, /gspec-practices, /gspec-feature) any match is surfaced by name and description, and you choose: start from it, adapt it, or write fresh.
• In an autonomous gspec build there is nobody to ask, so the run reports what it found (templates: practices 1 · stacks 2) and the writer adopts the single best fit — or writes fresh if none clearly fits.

Either way a template is a starting point, never a verbatim answer. The writer reconciles every choice against the current project, keeps the spec free of the original project's identity, brings the frontmatter up to the current spec version, and reports which template seeded the result — so the choice stays auditable.

An empty or absent folder simply means no templates: gspec writes from scratch, and says nothing about it.

Playbooks

A playbook bundles multiple saved specs into a single restorable package — a profile, stack, practices, style, and any number of features. Use playbooks to capture a complete project setup that you can replay in new projects with one command.

Create a playbook

gspec playbook

The CLI walks you through selecting saved specs from each category. You give the playbook a name and description, and it's saved to ~/.gspec/playbooks/.

$ gspec playbook

  Create a playbook

  A playbook bundles saved specs so you can restore them all at once.

  Select a profile (or skip): my-saas-profile
  Select a stack (or skip): nextjs-supabase
  Select practices (or skip): tdd-pipeline-first
  Select a style (or skip): dark-minimal
  Select features (optional): home-page, contact-form

  Playbook name: saas-starter
  Description: Full-stack SaaS with auth and contact form

  ✓ Playbook saved to ~/.gspec/playbooks/saas-starter.md

Restore a playbook

gspec restore playbook/saas-starter

All specs in the playbook are restored into gspec/ at once — profile, stack, practices, style, and features. From there, customize for the new project and start building.

Install Flow

When you run npx gspec in a new project, the installer checks for saved specs in ~/.gspec/. If you have saved specs or playbooks, it offers to seed your project from them — so you can go from zero to a fully-specced project in seconds.

If playbooks are available, you're asked to pick one first. If you prefer to pick individual specs, choose "Pick individual specs instead" and select from each category. If ~/.gspec/ is empty, the installer skips straight to post-install guidance.

The installer also scans ~/.gspec/extensions/ for any user-authored skills you've installed via gspec extension save. Each valid extension is emitted into the same per-platform install directory as the built-in skills. See the Extensions section in the docs for details.