Getting Started
Two ways to use gspec: let it build autonomously, or drive the workflow one spec at a time.
Introduction
gspec meets you where your project is. There are two paths through it, and they share the same specs — so you can start with one and switch to the other at any time:
- Autonomous build — describe your idea once and let
/gspec-builddrive the whole workflow to working code. Best for greenfield projects and fast prototypes. - Spec by spec — run each command yourself, reviewing as you go. Best when you want hands-on control, or when you're layering gspec onto an existing codebase.
Both paths produce the same living specs in your gspec/ directory. Pick a path below — everything the autonomous build does, you can also do by hand.
Install
You'll need two things first: Node.js (the npx command ships with it) and at
least one supported AI coding tool already set up. Then, either way, start by installing gspec into your
AI coding tool:
npx gspecThe CLI will prompt you to select your platform — Claude Code, Cursor, Antigravity, Codex, Open Code, or Pi. It installs the gspec commands, skills, and agents into your tool of choice.
Pi runs gspec through sub-agents, so it needs the pi-subagents extension: pi install npm:pi-subagents. The installer reminds you after a Pi install.
If you have saved specs in ~/.gspec/ from a previous project, the installer will offer to seed your new project from them — either from a playbook or by picking individual specs. This is optional. Learn more about saving and reusing specs across projects.
Choose your path
Pick how you want to work. You can switch tabs at any time — the specs are shared between both paths.
When to use it
Best for greenfield. If you're starting a brand-new project from zero — or spinning up a prototype fast — the autonomous build is the shortest path from idea to running code. There's nothing to set up first; the build creates your foundation specs as it goes.
It works on existing projects too — foundation specs you already have are reused, not regenerated, and an architecture you already have is amended rather than rewritten: the writer preserves your recorded decisions and cannot rename or drop a module, because the Modules table is what every feature spec points at. But this path shines on zero-to-one work where there's little or nothing yet.
The autonomous build needs a harness — the AI coding tool gspec is installed into — with a wired headless engine: Claude Code, Codex, or Pi. On other harnesses, use the spec-by-spec path instead.
Run the build
After installing, run it one of two ways. From inside your coding harness, use the slash command — pass your idea in quotes, or run it bare to be interviewed:
/gspec-build "a habit tracker with streaks and reminders"
Or run it headless as a script from your terminal or CI. The engine defaults to the platform you installed gspec for; override it with --engine, and resume a paused run with --resume:
gspec build "a habit tracker with streaks and reminders"
gspec build --engine codex --resumeIf you pass an idea directly, the build uses it as the brief; if you leave it off, it opens with a short intake interview — a few questions about your idea and the essentials (audience, platform, key constraints). Either way you answer up front; the run won't stop to re-ask. Then a deterministic runtime drives all nine stages in order:
- profile — product identity and positioning
- stack — technology and infrastructure
- practices — standards and quality gates
- style — design system
- features — prioritized feature PRDs
- architecture — data models, APIs, structure
- plan — ordered, dependency-aware tasks
- implement — write the code
- reconcile — sync the specs back to reality
Want a richer feature set out of the gate? Pass --research and the build adds an optional
competitive-research stage right after profile: it researches your competitors on the
web, writes gspec/research.md, and feeds the auto-accepted findings into the feature PRDs.
The spec-review pause below is where you prune any findings you disagree with.
Every stage runs as an isolated agent checked by an independent validator (the writer never grades its own
work), and the implementation stage is backed by a generated verify.sh that builds and tests the
project. If a gate fails, the run gets a revision attempt — one by default, more with
--qa-retries — then pauses for you rather than shipping something broken, keeping the full
failing verdict in .gspec/build/last-failure.md.
Between plan and implement the run pauses once on purpose: every spec is
written and no code exists yet, so you can review and edit gspec/ before anything is built.
Continue with gspec build --resume — or pass --no-review for a fully unattended run.
What you get
When the run finishes you have a working baseline: living specs in gspec/, an ordered plan, and
implemented code that passed its own build-and-test gate. The run is tracked in a resumable manifest — if it
stops, restart it and it picks up where it left off — and it ends by recording the learnings it captured
along the way.
From here, switch to the spec-by-spec path whenever you want to refine a specific spec by hand. For the full mechanics of the pipeline, see the autonomous build page.
Profile
We'll walk this path using a fictional task management app called TaskFlow. The profile command defines what your product is, who it serves, and why it exists. It adopts the perspective of a Product Strategist and asks you about your product's identity, target audience, and value proposition.
/gspec-profileThe command guides you through a conversation about your product. For TaskFlow, we'd describe it as a task management app for small dev teams. Here's a condensed excerpt of what it produces:
# TaskFlow — Product Profile
## Product Overview
- **Product Name:** TaskFlow
- **Tagline:** Simple task management for teams that ship.
- **Category:** Project management / productivity
## Target Audience
- Small development teams (2–10 people)
- Pain points: existing tools are bloated, context-switching
between project management and development tools
## Value Proposition
Lightweight task management that lives close to the code.
No enterprise overhead, no learning curve.The profile becomes the foundation that all other specs reference. Your AI tools now know who you're building for and why.
Style
The style command generates a visual design system — colors, typography, spacing, component patterns, and design tokens. It adopts the perspective of a UI Designer.
/gspec-style
It reads your profile first, then asks about your design vision, target platforms, and visual personality. Pick an output format — a renderable HTML design system (style.html) that design-aware AI tools can inspect directly, or a Markdown style guide (style.md). Either way, the output includes hex colors, font stacks, spacing scales, and component specifications.
Your AI coding tools can now make UI decisions that match your intended design language — consistent colors, proper spacing, correct typography. Drop mockups from external design tools (Figma, v0, Framer AI) into gspec/design/ and /gspec-implement will use them as authoritative layout guidance.
Stack
The stack command defines your technology choices — frameworks, languages, infrastructure, and architectural patterns. It adopts the perspective of a Solutions Architect.
/gspec-stackIt asks about your runtime, frontend/backend frameworks, database, hosting, and key libraries. The output documents every technology decision with rationale.
For TaskFlow, we might choose Next.js, PostgreSQL, and Vercel. Now when your AI writes code, it uses the right frameworks, follows the right patterns, and imports the right libraries — without you repeating this in every prompt.
Practices
The practices command establishes development standards — testing conventions, code quality rules, git workflow, and error handling patterns. It adopts the perspective of an Engineering Lead.
/gspec-practicesIt asks about your team size, testing philosophy, code review process, and deployment workflow. The output covers everything from naming conventions to your definition of done.
This means your AI produces code that follows your standards — right test framework, right patterns, right commit message format. No more AI-generated code that uses Jest when you're a Vitest team.
Feature
The feature command writes a product requirements document (PRD) for an individual feature. It adopts the perspective of a Product Manager and produces prioritized capabilities with acceptance criteria.
/gspec-feature "Task board with drag-and-drop columns"The command engages you in a conversation — asking about user stories, scope boundaries, and edge cases. It then generates a structured PRD with P0/P1/P2 prioritized capabilities, each with testable acceptance criteria.
This gives your AI implementation clear, scoped requirements to build against — not a vague description, but a structured spec with explicit success criteria.
Implement
The implement command reads all existing specs — profile, style, stack, practices, features, and architecture — and builds your software with the full picture.
/gspec-implementIt doesn't just read one spec — it synthesizes them all. It knows your audience (profile), your design language (style), your technology choices (stack), your code standards (practices), and your feature requirements. Here's a condensed view of what it does:
Reading specs...
✓ profile.md — TaskFlow, task management for small teams
✓ style.html — Renderable design system, 3 component variants
✓ design/task-board.html — Mockup from external design tool
✓ stack.md — Next.js, PostgreSQL, Vercel
✓ practices.md — Vitest, trunk-based, conventional commits
✓ features/task-board.md — 8 capabilities, 3 P0
Building task-board feature...
✓ Created src/components/TaskBoard.tsx
✓ Created src/components/TaskColumn.tsx
✓ Created src/components/TaskCard.tsx
✓ Updated capabilities: [x] P0: Board displays columns
✓ Updated capabilities: [x] P0: Drag task between columnsAs it builds, it checks off capabilities in your feature PRD — giving you a clear picture of progress. Want gspec to run this whole sequence for you? That's the autonomous build.
Next Steps
Whichever path you took, gspec offers more depth for projects that need it:
research— Analyze competitors and identify feature gaps before committing to a roadmaparchitect— Design a technical blueprint with data models, APIs, and project structureanalyze— Cross-reference all specs and resolve contradictions before implementingqa— Run the producer ≠ checker quality gate on your specs and code on demand- How it works — The five-layer agent-team architecture behind every command
Explore the full documentation for detailed coverage of every command. Or start with your own project — run npx gspec.