One interview. One spec. Every AI tool.

Install · How It Works · Exports · Commands · .spec Format

---

SpecIt runs an adaptive AI conversation in your terminal, captures everything it learns into a structured .spec file, and exports that file to any AI coding tool's native format. You describe your project once. Every tool gets the same context.

 ┌─────────────────────────────────┐      ┌──────────────┐
 │  specit init                    │      │  .spec       │
 │                                 │ ──▶  │  (one file)  │
 │  AI interview in your terminal  │      └──────┬───────┘
 └─────────────────────────────────┘             │
                                    ┌────────────┼────────────┐
                                    ▼            ▼            ▼
                              .specit/      .planning/       .gsd/

The Problem

AI planning tools each invented their own config format for the same information — what you're building and how you want it built. You end up writing the same project context, constraints, and architectural decisions into different formats for each tool.

SpecIt makes it N + M: one interview per project, one exporter per tool. Add a new planning framework to your workflow and run specit export.

Install

npm (recommended):

npm install -g specit-cli

Go install:

go install github.com/Solvely-Colin/specit@latest

Build from source:

git clone https://github.com/Solvely-Colin/SpecIt.git
cd SpecIt
make build

How It Works

1. Run the interview

specit init

SpecIt opens a split-pane TUI. On the left, an AI interviewer asks about your project — starting with vision, then tech stack, then constraints. On the right, a live preview shows the .spec file building in real time.

The interview is adaptive:

• Codebase detection — scans your repo for languages, frameworks, and structure before asking anything
• Thread-following — picks up terms you use and probes deeper, not a fixed script
• Depth modes — gives short answers and it switches to quick mode automatically; say /deep to go harder
• Recommendations — say "you pick" or "what do you recommend" and the AI makes an opinionated call based on your stack
• Skip-friendly — say "skip" or "no opinion" and it moves on without pushing

2. Export to your tools

# Export everything at once
specit export

# Or pick a format
specit export --format specit
specit export --format gsd
specit export --format gsd-2

3. Keep it in sync

# Check your code against the spec
specit validate

# See what drifted
specit diff

Supported Exports

Format	Output	Tool
specit	.specit/ (PROJECT, ROADMAP, STATE, DECISIONS)	SpecIt planning engine
gsd	.planning/ (PROJECT, ROADMAP, STATE, REQUIREMENTS, config.json)	Get Shit Done
gsd-2	.gsd/ (PROJECT, STATE, DECISIONS, REQUIREMENTS)	GSD 2

Each exporter generates files matching the real format that the target tool expects. Run specit export with no flags to generate all detected formats at once.

Commands

Command	Description
specit init	Run the AI interview and generate a .spec file
specit export	Export .spec to one or all supported formats
specit validate	Check codebase against spec rules (--ci for pipelines)
specit diff	Detect drift between spec and current codebase
specit import	Reverse-engineer a .spec from existing config files
specit planning	List, save, and switch planning profiles
specit plugin	Manage plugins: add, list, remove

.spec Format

The .spec file is YAML with a strict JSON Schema. Machine-readable for tools, human-editable when you need to tweak something by hand.

version: "1.0"

project:
  name: my-app
  description: Real-time collaboration tool for small teams
  goals:
    - Sub-100ms latency for live cursors
    - Works offline with sync on reconnect
  non_goals:
    - Mobile apps (web only for v1)

domain:
  context: B2B SaaS for teams of 2-20 people
  terminology:
    workspace: isolated environment per organization
    presence: real-time awareness of who is online

architecture:
  patterns: [event-driven, CQRS]
  structure: feature-based under src/
  data_flow: client -> WebSocket -> event bus -> projections

stack:
  languages: [TypeScript]
  frameworks: [Next.js 14, tRPC]
  databases: [PostgreSQL, Redis]
  deployment: Vercel + Railway

constraints:
  always:
    - validate all API inputs with Zod
    - use server components by default
  never:
    - class components
    - direct DB access from UI components
  security:
    - row-level security on all tables
  performance:
    - < 200ms p95 API response time

style:
  formatting:
    general: Prettier defaults
  naming:
    functions: camelCase
    components: PascalCase
  patterns:
    - compound components for complex UI

planning:
  active_profile: specit
  profiles:
    - id: specit
      framework: specit
      label: SpecIt Planning
      summary: Strong project brief, implementation roadmap, clean AI handoff
      deliverables: [project brief, roadmap, handoff state, decision log]

AI Providers

SpecIt auto-detects available providers from your environment:

Provider	Detection
Anthropic	ANTHROPIC_API_KEY env var or OAuth (specit auth anthropic)
OpenAI	OPENAI_API_KEY env var
Google Gemini	OAuth only (specit auth gemini)
GitHub Copilot	OAuth (specit auth copilot)
OpenAI Codex	OAuth (specit auth codex)
Ollama	Running local instance

On first run, SpecIt shows what it found and lets you pick. No config file needed. For OAuth providers, run specit auth <provider> once to store credentials.

Planning Profiles

A single .spec can hold multiple planning profiles for different frameworks. Switch between them without redoing the interview:

# Save the current spec as a planning profile
specit planning save --framework specit --activate
specit planning save --framework gsd-2

# Switch active profile
specit planning use gsd-2

# List profiles
specit planning list

# Inside the TUI: ctrl+l opens the planning picker

Exports automatically use the active profile to generate framework-specific planning artifacts.

TUI Shortcuts

Key	Action
enter	Submit answer
shift+enter	Newline in answer
tab / shift+tab	Cycle focus (input / history / preview)
ctrl+k	Command palette
ctrl+l	Planning profile picker
ctrl+s	Save snapshot
ctrl+p	Toggle raw/styled preview
ctrl+o	Open full preview screen
ctrl+/	Show all shortcuts
esc esc	Quit (double-tap)
/next	Skip to next section
/done	Finish and save
/brief	Switch to quick mode
/deep	Switch to deep mode

Contributing

Issues and PRs welcome. If you're building an exporter for a tool that isn't supported yet, the plugin system is the right entry point.

Open an issue to report bugs, request features, or discuss ideas.

License

MIT. See LICENSE.