Getting Started

Introduction

TaskFlow is a lightweight task management app for small teams. We'll use it as our example project to walk through every core gspec command — from defining your product profile to implementing features with full AI context.

By the end of this guide, you'll have a complete mental model of how gspec works and how each spec builds on the last. You can follow along with your own project or just read through to understand the flow.

Install

Run a single command to install gspec into your AI coding tool:

npx gspec

The CLI will prompt you to select your platform — Claude Code, Cursor, Antigravity, or Codex. It installs structured specification skills as slash commands in your tool of choice.

That's it. No accounts, no config files, no dependencies. The skills are plain Markdown files installed into your project.

Profile

The profile command defines what your product is, who it serves, and why it exists. It adopts the perspective of a Business Strategist and asks you about your product's identity, target audience, and value proposition.

/profile

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

/style

It reads your profile first, then asks about your design vision, target platforms, and visual personality. The output is a comprehensive style guide with 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.

Stack

The stack command defines your technology choices — frameworks, languages, infrastructure, and architectural patterns. It adopts the perspective of a Solutions Architect.

/stack

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

/practices

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

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

/implement

It 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.md — Design tokens, component patterns
  ✓ 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 columns

As it builds, it checks off capabilities in your feature PRD — giving you a clear picture of progress.

Next Steps

You've seen the core workflow: Define → Feature → Implement. But gspec offers more depth for projects that need it.

• research — Analyze competitors and identify feature gaps before committing to a roadmap
• epic — Break down large initiatives into multiple focused feature PRDs
• architect — Design a technical blueprint with data models, APIs, and project structure
• analyze — Cross-reference all specs and resolve contradictions before implementing

Explore the full documentation for detailed coverage of every command. Or start with your own project — run npx gspec and build your first spec.