Structured product specifications for AI-assisted development.
AI coding tools are powerful, but they build better software when they understand what you're building and why. gspec gives your AI tools that context — a set of living specification documents that define your product, guide implementation, and stay in sync as your project evolves.
Without structured context, AI tools guess. They make assumptions about your audience, your tech stack, your design language, and your quality standards. gspec eliminates that guesswork by creating a shared specification layer that any AI coding tool can read and follow.
Two things go wrong when building with AI:
- AI tools lack product context. They don't know your target audience, your design system, your architectural decisions, or your engineering standards. Every prompt starts from zero.
- Specs drift from reality. Even when you write great specs upfront, they fall out of sync as the project evolves — leading to inconsistency, rework, and compounding confusion.
gspec solves both problems. It provides a structured specification workflow that gives AI tools rich context, and keeps that context accurate as your codebase changes.
gspec installs as a set of slash commands (skills) in your AI coding tool. Each command plays a specific role — business strategist, product manager, architect, designer, engineer — and produces a structured Markdown document in your project's gspec/ directory.
These documents become the shared context for all subsequent AI interactions. When you implement features, your AI reads the specs. When the code changes, the specs update to match.
The only commands you need are the four fundamentals and implement. Everything else exists to help when your project calls for it.
The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, implement can take a plain-language description and start building. The remaining commands — research, feature, epic, architect, analyze, dor, and record — add structure and rigor when the scope or complexity warrants it.
flowchart LR
Define["1. Define
profile · style
stack · practices"]
Research["2. Research
competitive analysis"]
Specify["3. Specify
feature · epic"]
Architect["4. Architect
technical blueprint"]
Analyze["5. Analyze
reconcile specs"]
Build["6. Build
implement"]
Iterate["7. Iterate
dor · record"]
Define --> Research
Define --> Specify
Define --> Build
Research --> Specify
Research --> Build
Specify --> Architect
Specify --> Build
Architect --> Analyze
Architect --> Build
Analyze --> Build
Build --> Iterate
Iterate --> Build
style Define fill:#4a9eff,color:#fff,stroke:none
style Research fill:#a855f7,color:#fff,stroke:none
style Specify fill:#f59e0b,color:#fff,stroke:none
style Architect fill:#f59e0b,color:#fff,stroke:none
style Analyze fill:#f59e0b,color:#fff,stroke:none
style Build fill:#22c55e,color:#fff,stroke:none
style Iterate fill:#64748b,color:#fff,stroke:none
Blue = required foundation. Purple/Yellow = optional depth. Green = implementation. Gray = maintenance. Every path starts with Define and passes through Build. The steps in between depend on your project's complexity.
1. Define the Fundamentals — Establish the foundation that drives every decision.
| Command | Role | What it produces |
|---|---|---|
gspec.profile |
Business Strategist | Product identity, audience, value proposition, positioning |
gspec.style |
UI/UX Designer | Visual design language, design tokens, component patterns |
gspec.stack |
Software Architect | Technology stack, frameworks, infrastructure, architecture |
gspec.practices |
Engineering Lead | Development standards, code quality, testing, workflows |
2. Research the Market (optional) — Understand the competitive landscape before building.
| Command | Role | What it produces |
|---|---|---|
gspec.research |
Product Strategist | Competitive analysis, feature matrix, gap identification, and additional feature proposals |
Use research when you want to understand what competitors offer, identify table-stakes features you might be missing, find differentiation opportunities, and propose additional features that serve your product's mission. It reads competitors from your product profile, produces a persistent gspec/research.md file, and can optionally generate feature PRDs from its findings and proposals. This is where new feature ideas are surfaced and vetted — not during implementation.
3. Specify What to Build (optional) — Define features and requirements.
| Command | Role | What it produces |
|---|---|---|
gspec.feature |
Product Manager | PRD for a single feature with prioritized capabilities |
gspec.epic |
Product Manager | Breaks a large epic into multiple feature PRDs with dependency mapping |
Use feature when you want a detailed PRD with prioritized capabilities and acceptance criteria before building. Use epic when a body of work is large enough to need decomposition into multiple features with dependency mapping. For smaller tasks or rapid prototyping, you can skip straight to implement with a plain-language description.
4. Architect (optional) — Translate specs into a concrete technical blueprint.
| Command | Role | What it produces |
|---|---|---|
gspec.architect |
Senior Architect | Technical architecture document with data models, API design, project structure, auth flows, technical gap analysis, and Mermaid diagrams |
Use architect when your feature involves significant technical complexity — new data models, service boundaries, auth flows, or integration points that benefit from upfront design. It also identifies technical gaps and ambiguities in your specs and proposes solutions, so that implement can focus on building rather than making architectural decisions. For straightforward features, implement can make sound architectural decisions on its own using your stack and practices specs.
5. Analyze (optional) — Reconcile discrepancies across specs before building.
| Command | Role | What it does |
|---|---|---|
gspec.analyze |
Specification Analyst | Cross-references all specs, identifies contradictions, and walks you through reconciling each one |
Use analyze after architect (or any time multiple specs exist) to catch conflicts before implement sees them. For example, if the stack says PostgreSQL but the architecture references MongoDB, or a feature PRD defines a data model that contradicts the architecture, analyze will surface the discrepancy and let you choose the resolution. Each conflict is presented one at a time with options — no new files are created, only existing specs are updated.
6. Build — Implement with full context.
| Command | Role | What it does |
|---|---|---|
gspec.implement |
Senior Engineer | Reads all specs, plans the build order, and implements |
7. Iterate (optional) — Keep specs and code in sync as the project evolves.
| Command | Role | What it does |
|---|---|---|
gspec.dor |
Engineer + Doc Lead | Makes code changes and updates specs to match |
gspec.record |
Doc Lead | Updates specs to reflect decisions or changes — no code modifications |
Use dor and record when you want your specification documents to stay accurate as the project evolves. If you're moving fast and specs are secondary, you can skip them — but as a project matures, keeping specs in sync prevents the context drift that degrades AI output over time.
Maintenance — Keep specs up to date with the latest gspec format.
| Command | Role | What it does |
|---|---|---|
gspec.migrate |
Migration Specialist | Updates existing gspec documents to the current format when you upgrade gspec, preserving all content |
Each command is self-contained and will ask clarifying questions when essential information is missing.
Run from your project root:
npx gspecThe CLI will ask which platform you're installing for:
| Platform | Install path |
|---|---|
| Claude Code | .claude/skills/ |
| Cursor | .cursor/commands/ |
| Antigravity | .agent/skills/ |
| Codex | .agents/skills/ |
You can skip the prompt by passing a target directly:
npx gspec --target claude
npx gspec --target cursor
npx gspec --target antigravity
npx gspec --target codexThat's it. The commands are immediately available in your AI tool.
All specifications live in a gspec/ directory at your project root:
project-root/
└── gspec/
├── profile.md # Product identity and positioning
├── style.md # Visual design language
├── stack.md # Technology stack and architecture
├── practices.md # Development standards
├── architecture.md # Technical architecture blueprint
├── research.md # Competitive analysis and feature gaps
├── epics/
│ └── onboarding-flow.md
└── features/
├── user-authentication.md
├── dashboard-analytics.md
└── ...
These are standard Markdown files. They live in your repo, are version-controlled with your code, and are readable by both humans and AI tools.
Spec-first development. Every implementation decision traces back to a specification. AI tools don't guess — they follow documented decisions about your product, stack, design, and standards.
Living documents. Specifications aren't write-once artifacts. The dor and record commands keep them in sync as your project evolves, so they remain a reliable source of truth.
Role-based commands. Each command adopts a specific professional perspective — product manager, architect, designer, engineer. This ensures specifications are comprehensive and consider multiple viewpoints.
Incremental implementation. Feature PRDs use checkboxes to track which capabilities have been built. The implement command reads these to know what's done and what's remaining, so it can be run multiple times as your project grows.
Research and architecture own discovery. Feature proposals and technical gap analysis happen before implementation — in research and architect respectively. The research command surfaces new feature ideas through competitive analysis and product-driven reasoning. The architect command identifies technical gaps and resolves ambiguities. This separation keeps implement focused on building what the specs define, rather than proposing scope changes mid-build.
Platform-agnostic. A single set of source commands builds for Claude Code, Cursor, Antigravity, and Codex. The build system handles platform-specific formatting so the commands stay consistent across tools.
| Platform | Version | Status |
|---|---|---|
| Claude Code | Skills format | Supported |
| Cursor | Commands format | Supported |
| Antigravity | Skills format | Supported |
| Codex | Skills format | Supported |
gspec is early-stage and actively evolving. The core workflow is stable, but commands and output formats may change as AI tool capabilities expand and user feedback comes in.
If you run into issues or have ideas, please open an issue.