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.

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.