speclet

Spec-driven development CLI. Write your plan in markdown, speclet turns it into structured AI agent workflows — native slash commands in GitHub Copilot Chat, Claude Code, Cursor, and Mistral Vibe, with no copy-paste required.

Table of Contents

1. How it works
2. Install
3. Step-by-step guide
   • Step 1 — Write your plan
   • Step 2 — Initialize speclet
   • Step 3 — Fill in context.md
   • Step 4 — Set project ground rules
   • Step 5 — Generate a .gitignore
   • Step 6 — Clarify the plan (optional)
   • Step 7 — Generate tasks
   • Step 8 — Analyze tasks (optional)
   • Step 9 — Implement
4. Adding speclet to an existing project
5. Using speclet in your AI agent
   • GitHub Copilot Chat
   • Claude Code
   • Cursor
   • Mistral Vibe
6. CLI reference
7. .speclet directory structure
8. Updating speclet

How it works

speclet reads your plan files and .speclet/ context, then assembles structured prompts for your AI agent. The agent reads only what it needs, does the work, and writes results back to your task files.

new project:        speclet plan  →  plans/*.md  →  speclet init ./plans  →  .speclet/ + agent files
                                                                                  ↓
                                                                       /speclet.tasks
                                                                                  ↓
                                                                       agent generates tasks/phase-N-*.md
                                                                                  ↓
                                                                       /speclet.implement 1

existing project:   speclet map   →  context.md + architecture.md + constitution.md + plans/ + tasks/
                                                ↓
                                         review → plan new features → normal workflow above

speclet is the scaffolding and the prompt factory. The agent does the thinking and coding.

• context.md and constitution.md are injected into every prompt automatically
• Agents load one phase file at a time — never the whole project at once
• Every command is a native slash command inside your agent — no copy-paste needed

Install

npm install -g speclet

Verify:

speclet --version

Development install (if you're working on speclet itself):

git clone https://github.com/Shawn-Imran/speclet.git
cd speclet
npm install
npm run build
npm install -g .

Step-by-step guide

Step 1 — Write your plan

Create a plans/ folder in your project. Write your feature plan as one or more markdown files, using ## headings to define phases. Prefix filenames with numbers to control the order.

my-app/
└── plans/
    ├── 01-backend.md
    └── 02-frontend.md

Example plan file:

# plans/01-backend.md

## Phase 1: Setup
Initialize Node project, install Express, configure dotenv and TypeScript.

## Phase 2: API
Build authentication endpoints (register, login, refresh).
Build user CRUD endpoints with role-based access.

## Phase 3: Database
Set up PostgreSQL with Prisma. Write migrations for user and session tables.

Rules for plans:

• Use ## headings for phase boundaries — speclet parses these automatically
• Each phase should be one meaningful increment of work
• Keep descriptions high-level — your agent will break them into concrete tasks later

Don't want to write plans by hand? Use speclet plan — your AI agent interviews you and writes the files:

speclet plan                # writes to plans/
speclet plan --path .       # writes to current directory

Or use the slash command:

| Agent | Command | |---|---| | Copilot Chat | /speclet.plan | | Claude Code | /project:speclet-plan | | Mistral Vibe | /speclet-plan |

Step 2 — Initialize speclet

Run speclet init from your project root:

cd my-app
speclet init ./plans                    # with plan files — scaffold for all agents (recommended)
speclet init ./plans/01-backend.md      # single plan file
speclet init ./plans --agent copilot    # Copilot only
speclet init ./plans --agent claude     # Claude Code only
speclet init ./plans --agent cursor     # Cursor only
speclet init ./plans --agent vibe       # Mistral Vibe only

speclet init                            # no plans yet — scaffold templates only

With plans: Creates the .speclet/ directory, copies plans, writes the phase index, and scaffolds agent files.

Without plans (new project, no plans yet): Creates .speclet/ with template files (context.md, constitution.md) and agent scaffolding. Use speclet plan to create plan files, then re-run speclet init ./plans.

This creates the following in your project:

.speclet/
├── context.md          ← edit with your stack (Step 3)
├── constitution.md     ← fill in with your agent (Step 4)
├── plans/              ← copies of your plan files (if provided)
├── tasks/
│   └── index.md        ← phase map (task files generated later in Step 7)
└── prompts/            ← prompt templates used by each command

.github/                ← GitHub Copilot Chat integration
├── copilot-instructions.md
├── agents/             ← custom agents (appear in Copilot Chat dropdown)
│   ├── speclet.map.agent.md
│   ├── speclet.constitution.agent.md
│   ├── speclet.tasks.agent.md
│   ├── speclet.implement.agent.md
│   ├── speclet.clarify.agent.md
│   └── speclet.analyze.agent.md
└── prompts/            ← slash command shortcuts → reference agent files
    ├── speclet.map.prompt.md
    ├── speclet.constitution.prompt.md
    ├── speclet.tasks.prompt.md
    ├── speclet.implement.prompt.md
    ├── speclet.clarify.prompt.md
    └── speclet.analyze.prompt.md

.claude/
└── commands/           ← Claude Code slash commands (/project:speclet-*)
    ├── speclet-map.md
    ├── speclet-constitution.md
    ├── speclet-tasks.md
    ├── speclet-implement.md
    ├── speclet-clarify.md
    └── speclet-analyze.md

.cursor/
└── rules/
    └── speclet.mdc        ← Cursor workflow rules

.vibe/
├── AGENTS.md           ← Always-on context for Vibe sessions
└── skills/             ← Vibe custom slash commands (/speclet-*)
    ├── speclet-map/
    │   └── SKILL.md
    ├── speclet-constitution/
    │   └── SKILL.md
    ├── speclet-tasks/
    │   └── SKILL.md
    ├── speclet-implement/
    │   └── SKILL.md
    ├── speclet-clarify/
    │   └── SKILL.md
    └── speclet-analyze/
        └── SKILL.md

Task files (.speclet/tasks/phase-N-*.md) are not created here. Your agent creates them in Step 7.

Step 3 — Fill in context.md

Open .speclet/context.md and describe your project's stack, conventions, and constraints. Keep it short — it is injected into every speclet prompt, so every agent action is grounded in your actual stack.

For existing projects, run speclet map first — your agent scans the codebase and fills this in automatically.

# Project Context

## Stack
- Language: TypeScript
- Framework: NestJS 10
- Database: PostgreSQL 16 with Prisma 7
- Package manager: pnpm

## Conventions
- Feature-based module structure (one NestJS module per domain)
- Controllers are thin — business logic lives in services only
- DTOs with class-validator for all controller inputs

## Constraints
- No microservices — single NestJS process
- No raw SQL except where Prisma cannot handle it
- All secrets via ConfigService, never hardcoded

Step 4 — Set project ground rules

The constitution defines non-negotiable principles for the project — architecture rules, testing requirements, quality standards, and definition of done. It is injected into every future prompt once filled in.

In Copilot Chat:

/speclet.constitution

In Claude Code:

/project:speclet-constitution

In Mistral Vibe:

/speclet-constitution

CLI (copy-paste to any agent):

speclet constitution

Your agent will interview you section by section:

| Section | What to define | |---|---| | Code Quality | ESLint rules, Prettier, max file length, no any types | | Architecture Principles | Layered / hexagonal, module boundaries, forbidden patterns | | Testing Requirements | Unit + integration, testing library, coverage threshold | | What To Avoid | Banned libraries, security rules, anti-patterns | | Definition of Done | Tests pass, PR reviewed, no lint errors, feature complete |

The agent writes your answers into .speclet/constitution.md and removes the <!-- speclet:unfilled --> marker. From that point on, the constitution is automatically included in every speclet prompt.

Step 5 — Generate a .gitignore

speclet can auto-generate a .gitignore tailored to your stack by reading .speclet/context.md:

speclet gitignore          # creates or merges into an existing .gitignore
speclet gitignore --dry    # preview what would be written without touching the file
speclet gitignore --force  # overwrite instead of merging

Stack keywords in context.md are detected automatically (TypeScript, NestJS, Python, Django, Go, Rust, Docker, Terraform, etc.) and the appropriate patterns are added.

Step 6 — Clarify the plan (optional but recommended)

Before generating tasks, have your agent ask clarifying questions to surface ambiguities and missing decisions. This prevents costly rework later.

In Copilot Chat:

/speclet.clarify           ← full plan
/speclet.clarify 2         ← phase 2 only

In Claude Code:

/project:speclet-clarify 2

In Mistral Vibe:

/speclet-clarify           ← full plan
/speclet-clarify 2         ← phase 2 only

CLI:

speclet clarify              # full plan
speclet clarify --phase 2    # specific phase

The agent scans for scope ambiguities, technical unknowns, missing edge cases, and unspecified non-functional requirements. It asks up to 5 targeted questions (one at a time, with recommendations) and updates the plan with your answers.

Step 7 — Generate tasks

Have your agent break each phase into concrete, ordered tasks and write them to .speclet/tasks/phase-N-*.md.

In Copilot Chat:

/speclet.tasks             ← all phases
/speclet.tasks 1           ← phase 1 only (recommended — lower token cost)

In Claude Code:

/project:speclet-tasks 1

In Mistral Vibe:

/speclet-tasks             ← all phases
/speclet-tasks 1           ← phase 1 only

CLI:

speclet tasks --phase 1    # one phase at a time (recommended)
speclet tasks              # all phases at once

Tip: Process one phase at a time to minimize token usage and get more focused, accurate output.

The agent creates a task file like .speclet/tasks/phase-1-setup.md:

## Phase 1: Setup

- [ ] **Initialize project** — run `pnpm init`, configure TypeScript with strict mode in tsconfig.json
- [ ] **Install dependencies** — NestJS CLI, class-validator, class-transformer, @nestjs/config
- [ ] **Configure ESLint + Prettier** — add .eslintrc.js and .prettierrc, add lint-staged + husky
- [ ] **Set up environment** — create .env.example with all required keys, add ConfigModule to AppModule

Step 8 — Analyze tasks (optional)

Before implementing, have your agent check all generated tasks for gaps, conflicts, and risks — then fix them automatically.

In Copilot Chat:

/speclet.analyze                         ← all phases
/speclet.analyze 1                       ← phase 1 only
/speclet.analyze "fix the found issues"  ← analyze, then fix

In Claude Code:

/project:speclet-analyze
/project:speclet-analyze "fix the found issues"

In Mistral Vibe:

/speclet-analyze                         ← all phases
/speclet-analyze 1                       ← phase 1 only
/speclet-analyze "fix the found issues"  ← analyze, then fix

CLI:

speclet analyze --phase 1
speclet analyze
speclet analyze "fix the found issues"

The agent runs analysis first, producing a structured report covering:

| Category | What it finds | |---|---| | Conflicts | Tasks that contradict each other or touch the same file in incompatible ways | | Gaps | Features mentioned in the plan with no corresponding task | | Risks | Vague tasks, missing file paths, unclear success criteria | | Constitution violations | Anything conflicting with your ground rules — always marked CRITICAL |

After analysis, if a follow-up instruction was given (e.g., "fix the found issues"), the agent will:

1. Update task/phase files first — add, modify, or remove tasks to reflect needed changes, keeping .speclet/tasks/ in sync as the source of truth
2. Implement code changes — make the actual code edits described by the updated tasks

Step 9 — Implement

Have your agent work through a phase's tasks one by one, marking each [x] when complete.

In Copilot Chat:

/speclet.implement 1
/speclet.implement "Phase 2: API"

In Claude Code:

/project:speclet-implement 1

In Mistral Vibe:

/speclet-implement 1
/speclet-implement "Phase 2: API"

CLI:

speclet implement 1
speclet implement "Phase 2"

The agent will:

1. Read context.md and constitution.md to know your exact stack and rules
2. Load only the requested phase file — never other phases
3. Work through each - [ ] task in order
4. Mark each task - [x] immediately after completing it
5. When all tasks are done, add Status: Complete to the phase file and summarize what was built

Repeat for each phase:

/speclet.implement 1  →  /speclet.implement 2  →  /speclet.implement 3

Adding speclet to an existing project

If you already have a working codebase and want to use speclet for new features, run speclet map first. It scans your project and auto-generates all the context files speclet needs — no manual editing.

cd my-existing-app
speclet map

The command prints a prompt with a project snapshot. Feed it to your AI agent and it will produce:

| File | What it contains | |---|---| | .speclet/context.md | Real stack, module structure, conventions, constraints | | .speclet/architecture.md | Module map, key files, data flow, integrations, tech debt | | .speclet/constitution.md | Ground rules inferred from lint configs, patterns, test setup, CI | | .speclet/plans/01-existing.md | Plan file with ## phases describing what was already built | | .speclet/tasks/index.md | Phase map | | .speclet/tasks/phase-N-*.md | Task file per phase — all past tasks marked [x] done |

The constitution is filled in automatically by reading the evidence — no questions asked. The plans and tasks document the existing work as if speclet had been used from the start, giving you a clean baseline to continue from.

Existing project workflow

existing codebase  →  speclet map  →  .speclet/context.md        (real stack, auto-filled)
                                    .speclet/architecture.md   (module map)
                                    .speclet/constitution.md   (inferred from lint/patterns/CI)
                                    .speclet/plans/01-existing.md  (what was already built)
                                    .speclet/tasks/phase-N-*.md    (all [x] done)
                                              ↓
                                   review + edit any file the agent got wrong
                                              ↓
                                   speclet plan               → write plans for new features
                                              ↓
                                   speclet init ./plans/02-new-feature.md
                                              ↓
                                   normal speclet workflow (tasks → implement)

You can also use the slash command directly in your agent:

| Agent | Command | |---|---| | Copilot Chat | /speclet.map | | Claude Code | /project:speclet-map | | Mistral Vibe | /speclet-map | | Cursor | "Map the existing codebase following the speclet workflow" |

Using speclet in your AI agent

GitHub Copilot Chat (VS Code)

After speclet init, open Copilot Chat. The speclet agents appear in the agent dropdown at the top of the chat panel. You can also trigger them with slash commands:

| Command | Description | |---|---| | /speclet.map | Full retroactive speclet setup — scans codebase, generates context, architecture, constitution, plans, and completed tasks | | /speclet.constitution | Fill in or update the project constitution | | /speclet.tasks | Generate tasks for all phases | | /speclet.tasks 1 | Generate tasks for phase 1 only | | /speclet.clarify | Clarify the full plan | | /speclet.clarify 2 | Clarify phase 2 | | /speclet.analyze | Analyze all tasks for gaps and conflicts, then fix | | /speclet.analyze 1 | Analyze phase 1, then fix | | /speclet.analyze "fix issues" | Analyze, then update tasks and implement fixes | | /speclet.implement 1 | Implement phase 1 | | /speclet.implement "Phase 2" | Implement by phase name |

After each command, Copilot Chat shows handoff buttons to continue the workflow — e.g., after /speclet.tasks you'll see "Analyze for Consistency" and "Start Implementation" without having to retype anything.

How the files work:

| File | Purpose | |---|---| | .github/agents/speclet.*.agent.md | Full agent definitions — VS Code surfaces these in the dropdown | | .github/prompts/speclet.*.prompt.md | 3-line wrappers: agent: speclet.tasks — links /speclet.X slash commands to agent files | | .github/copilot-instructions.md | Always-on context block that Copilot reads in every session |

Claude Code

After speclet init, type / in Claude Code to see all project commands:

| Command | Description | |---|---| | /project:speclet-map | Full retroactive speclet setup — scans codebase, generates context, architecture, constitution, plans, and completed tasks | | /project:speclet-constitution | Fill in or update the project constitution | | /project:speclet-tasks | Generate tasks for all phases | | /project:speclet-tasks 1 | Generate tasks for phase 1 | | /project:speclet-clarify | Clarify the full plan | | /project:speclet-clarify 2 | Clarify a specific phase | | /project:speclet-analyze | Analyze tasks for gaps and conflicts, then fix | | /project:speclet-analyze "fix issues" | Analyze, then update tasks and implement fixes | | /project:speclet-implement 1 | Implement phase 1 |

Anything you type after the command name is passed to the agent as $ARGUMENTS — so /project:speclet-implement 2 tells the agent to implement phase 2.

Claude Code automatically registers .claude/commands/speclet-*.md as /project:speclet-* commands.

Cursor

Cursor reads .cursor/rules/speclet.mdc and applies the speclet workflow rules whenever you work in the project. Use natural language in Cursor chat:

"Generate tasks for Phase 1 following the speclet workflow" "Implement Phase 2 — follow context.md and the implement prompt" "Analyze phase-2-api.md for gaps and conflicts"

Mistral Vibe

After speclet init, Vibe picks up the speclet workflow from two places:

• .vibe/AGENTS.md — always-on context injected into every Vibe session, pointing Vibe at the .speclet/ files
• .vibe/skills/speclet-*/SKILL.md — custom slash commands registered in Vibe's autocompletion menu

Type / in Vibe to see all speclet commands:

| Command | Description | |---|---| | /speclet-map | Full retroactive speclet setup — scans codebase, generates context, architecture, constitution, plans, and completed tasks | | /speclet-constitution | Fill in or update the project constitution | | /speclet-tasks | Generate tasks for all phases | | /speclet-tasks 1 | Generate tasks for phase 1 | | /speclet-clarify | Clarify the full plan | | /speclet-clarify 2 | Clarify a specific phase | | /speclet-analyze | Analyze tasks for gaps and conflicts, then fix | | /speclet-analyze 1 | Analyze phase 1, then fix | | /speclet-analyze "fix issues" | Analyze, then update tasks and implement fixes | | /speclet-implement 1 | Implement phase 1 | | /speclet-implement "Phase 2" | Implement by phase name |

Anything you type after the command name is passed to the agent as context — so /speclet-implement 2 tells the agent to implement phase 2.

Vibe discovers skills from the .vibe/skills/ directory automatically. Each skill directory contains a SKILL.md file that defines the command's behavior using the Agent Skills specification.

CLI reference

The CLI is the fallback workflow — each command prints an assembled prompt to stdout so you can copy-paste it into any agent.

| Command | Description | |---|---| | speclet init [plan] | Initialize speclet from an optional .md file or folder of .md files. Without a plan, scaffolds templates only | | speclet plan | Have your AI agent help you create feature plan files interactively | | speclet map | Full retroactive speclet setup — scan existing codebase and generate context.md, architecture.md, constitution.md, plan files, and completed task history | | speclet constitution | Print the constitution setup prompt | | speclet tasks [--phase n] | Print the task generation prompt | | speclet clarify [--phase n] | Print the clarify prompt | | speclet analyze [request] [--phase n] | Analyze tasks for gaps and conflicts, then update task files and implement fixes | | speclet implement <phase> | Print the implement prompt for a phase (by number or name) | | speclet gitignore | Generate or update .gitignore based on your stack | | speclet update | Update speclet CLI to the latest version |

speclet init options:

--agent <agent>   all (default) | copilot | claude | cursor | vibe

speclet gitignore options:

--dry     Preview without writing to disk
--force   Overwrite existing .gitignore instead of merging

.speclet directory structure

.speclet/
├── context.md             Stack, conventions, constraints
│                          → Edit manually (new projects) or fill via speclet map (existing projects).
│                          → Injected into every speclet prompt.
│
├── constitution.md        Project ground rules
│                          → Filled in by your agent via /speclet.constitution
│                          → Injected into every prompt once the unfilled marker is removed
│
├── architecture.md        Existing module map, key files, data flow, integration points
│                          → Generated by speclet map on existing projects
│                          → Read by agents during implementation to respect module boundaries
│                          → Not present on new (greenfield) projects
│
├── plans/                 Read-only copies of your original plan files
│
├── tasks/
│   ├── index.md           Phase map — auto-generated by speclet init, do not edit
│   └── phase-N-name.md    Task files — generated by your agent via /speclet.tasks
│
└── prompts/               Prompt instruction files used internally by each command
    ├── map.md
    ├── constitution.md
    ├── clarify.md
    ├── analyze.md
    ├── tasks.md
    └── implement.md

Commit everything in .speclet/ and all agent files — they are project configuration, not build artifacts.

Updating speclet

npm update -g speclet

Or use the built-in update command:

speclet update

Development update (if you installed from git clone):

cd /path/to/speclet
git pull
npm install
npm run build
npm install -g .