Generate and validate a .specs/ bundle for your repo, then hand it to your AI coding agent
dev.specpilot/specpilot MCP Server
The dev.specpilot/specpilot MCP server generates and validates a .specs/ bundle for a repository, then hands it to your AI coding agent. It targets specification-driven development workflows and project initialization tasks, and is positioned for use in TypeScript/Node.js-based development environments.
🛠️ Key Features
Generate a .specs/ bundle for a repo
Validate the generated .specs/ bundle
Provide the bundle to an AI coding agent
🚀 Use Cases
Specification-driven development (SDD) for repositories
Project initialization using spec-driven materials
AI-assisted coding flows that consume structured specs
⚡ Developer Benefits
Supports TypeScript and Node.js development workflows
Helps produce and check repo-specific specification bundles
Integrates with AI coding agents (e.g., Claude Code)
⚠️ Limitations
Description provided does not specify supported languages beyond references to TypeScript/Node.js
Tool count and concrete tool names are not included in the available data
Returns the still-unanswered SpecPilot onboarding questions of the next incomplete step, gated by the answers supplied so far - questions that do not apply to this kind of project are omitted, and options are filtered, badged or flagged the same way the SpecPilot web chat would. Stateless: send every answer collected so far on each call.
Procedure: (1) Decide whether the repository already has real source code and set `isNewBuild` accordingly - it changes which onboarding analysis is generated at the end. (2) Infer what the repo already answers rather than asking: `platforms` from the dependency manifests and layout, `languageOverride`, `ideAgent` (you are the IDE - claudecode, cursor, copilot, codex, windsurf), `handle` from git config or the origin remote, `projectName` from the package manifest or folder name, and `projectDescription` from the README only if it plainly says what the project is. (3) Call this tool with what you have; answer what the repo makes obvious and ask the developer the rest, a whole step per message. Send an empty value for an optional question the developer declines, or it will be asked again; send `todoSentinel` verbatim when they do not know yet. For `projectDescription`, sending one of the returned chip labels exactly is what infers `projectCategory` and gates every later question - free prose infers nothing. Confirm any pre-seeded value rather than accepting it silently. (4) Loop until `done` is true, then call specpilot_generate_specs and follow its `nextSteps` for where each file goes.
Parameters1
answers
object
optional
Raw schema
{
"type": "object",
"properties": {
"answers": {
"type": "object",
"properties": {
"projectCategory": {
"description": "Project archetype. Normally inferred from projectDescription when it exactly matches a returned chip label - send it only if you already know it.",
"anyOf": [
{
"type": "string",
"enum": [
"saas",
"api",
"mobile",
"cli",
"pipeline",
"ml",
"static",
"docs",
"extension",
"library",
"other"
]
},
{
"type": "null"
}
]
},
"projectName": {
"description": "Short name for the project. Required by specpilot_generate_specs. Infer from the package manifest or the folder name.",
"type": "string"
},
"projectDescription": {
"description": "One line saying what the project is. Required by specpilot_generate_specs. Sending one of the chip labels returned by specpilot_next_questions verbatim is what infers projectCategory and gates every later question; free prose infers nothing.",
"type": "string"
},
"isNewBuild": {
"description": "True for a greenfield project, false when adding onto an existing codebase. Decides which onboarding analysis is generated at the end.",
"type": "boolean"
},
"handle": {
"description": "The developer GitHub handle. Optional; it namespaces generated task IDs (e.g. CD-jsmith-001). Infer from git config or the origin remote.",
"type": "string"
},
"platforms": {
"description": "Platforms this should run on, e.g. web, ios, android, desktop. Infer from the dependency manifests and repo layout.",
"type": "array",
"items": {
"type": "string"
}
},
"ideAgent": {
"description": "The editor or AI IDE in use - claudecode, cursor, copilot, codex, windsurf. You are the IDE, so set this yourself; it decides which rules and config files are generated.",
"type": "string"
},
"languageOverride": {
"description": "Primary language, when it should override what SpecPilot infers from the repo.",
"type": "string"
},
"userTypes": {
"description": "Who is going to use this system, e.g. end users, admins, internal staff.",
"type": "array",
"items": {
"type": "string"
}
},
"customUserType": {
"description": "A user type in free text, when none of the userTypes options fit.",
"type": "string"
},
"accessControl": {
"description": "The access control model. Drives the security spec auth/authorization section and the permission model.",
"type": "string"
},
"specialConsiderations": {
"description": "Cross-cutting concerns that apply, such as accessibility, internationalisation or offline support.",
"type": "array",
"items": {
"type": "string"
}
},
"accessibilityNotes": {
"description": "Anything further on accessibility or constraints, in free text.",
"type": "string"
},
"scaleTier": {
"description": "Expected scale of the system. Drives infrastructure and architecture choices.",
"type": "string"
},
"activeUsers": {
"description": "Roughly how many active users are expected, as a range.",
"type": "string"
},
"deploymentTargets": {
"description": "Where this ships - cloud hosting, a package registry, a browser store. The option list depends on the project type.",
"type": "array",
"items": {
"type": "string"
}
},
"buildTimeline": {
"description": "How long the build is expected to take.",
"type": "string"
},
"teamSize": {
"description": "How many people are building this.",
"type": "string"
},
"systemPattern": {
"description": "Architecture pattern - monolith, modular monolith, or microservices.",
"type": "string"
},
"apiStyle": {
"description": "API style - REST, GraphQL, gRPC or tRPC. Shapes how the architecture spec documents client-server communication.",
"type": "string"
},
"databases": {
"description": "Database kinds in use - SQL, NoSQL, cache/key-value, vector. As many as apply.",
"type": "array",
"items": {
"type": "string"
}
},
"authStrategy": {
"description": "Auth approach - a protocol built in-house (JWT/OAuth/SAML) or a managed service (Clerk, Auth0, Firebase). Feeds the security spec.",
"type": "string"
},
"realtimeEnabled": {
"description": "Whether anything updates live without a refresh. Set automatically when realtimeTypes is non-empty.",
"type": "boolean"
},
"realtimeTypes": {
"description": "Realtime transports - WebSockets, SSE, polling. Leave empty when nothing needs to update live.",
"type": "array",
"items": {
"type": "string"
}
},
"offlineSupport": {
"description": "Whether this has to work offline. Set automatically when localDatabases is non-empty.",
"type": "boolean"
},
"localDatabases": {
"description": "On-device stores backing offline support. Leave empty when offline is not needed.",
"type": "array",
"items": {
"type": "string"
}
},
"dataSyncStrategy": {
"description": "How conflicting local and server state gets reconciled once the device is back online.",
"type": "string"
},
"integrations": {
"description": "Third-party integrations keyed by category, e.g. { payments: [\"stripe\"] }. Only categories relevant to the project type apply.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"otherApis": {
"description": "External APIs or services not covered by integrations.",
"type": "string"
},
"nonGoals": {
"description": "What this project explicitly will NOT do. Becomes the non-goals section of the specs.",
"type": "string"
},
"technicalConstraints": {
"description": "Hard constraints - budget, existing infrastructure, legacy systems, a fixed deadline.",
"type": "array",
"items": {
"type": "string"
}
},
"constraintDescription": {
"description": "More detail on whatever was named in technicalConstraints.",
"type": "string"
},
"compliance": {
"description": "Compliance regimes that apply - GDPR, HIPAA, SOC 2. Pick by the actual situation (EU users, health data, payments), since getting it wrong has legal consequences.",
"type": "array",
"items": {
"type": "string"
}
},
"apiResponseTime": {
"description": "Target API response time.",
"type": "string"
},
"availability": {
"description": "Availability SLA target as a fraction of uptime; higher percentages allow far less downtime per year.",
"type": "string"
},
"securityConcerns": {
"description": "Security measures to plan for - encryption, rate limiting, audit logging.",
"type": "array",
"items": {
"type": "string"
}
},
"testingStrategy": {
"description": "Testing approaches this project will use.",
"type": "array",
"items": {
"type": "string"
}
},
"cicd": {
"description": "CI/CD practices - automatically running tests and deploying on every change.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
specpilot_generate_specs
Generates the complete SpecPilot .specs/ file set plus the matching IDE rules and slash-command files from a full answer set - identical to what the SpecPilot web chat produces for the same answers. Requires projectName and projectDescription. Returns the files to write and the steps to follow after writing them.
Parameters1
answers
object
required
Raw schema
{
"type": "object",
"properties": {
"answers": {
"type": "object",
"properties": {
"projectCategory": {
"description": "Project archetype. Normally inferred from projectDescription when it exactly matches a returned chip label - send it only if you already know it.",
"anyOf": [
{
"type": "string",
"enum": [
"saas",
"api",
"mobile",
"cli",
"pipeline",
"ml",
"static",
"docs",
"extension",
"library",
"other"
]
},
{
"type": "null"
}
]
},
"projectName": {
"description": "Short name for the project. Required by specpilot_generate_specs. Infer from the package manifest or the folder name.",
"type": "string"
},
"projectDescription": {
"description": "One line saying what the project is. Required by specpilot_generate_specs. Sending one of the chip labels returned by specpilot_next_questions verbatim is what infers projectCategory and gates every later question; free prose infers nothing.",
"type": "string"
},
"isNewBuild": {
"description": "True for a greenfield project, false when adding onto an existing codebase. Decides which onboarding analysis is generated at the end.",
"type": "boolean"
},
"handle": {
"description": "The developer GitHub handle. Optional; it namespaces generated task IDs (e.g. CD-jsmith-001). Infer from git config or the origin remote.",
"type": "string"
},
"platforms": {
"description": "Platforms this should run on, e.g. web, ios, android, desktop. Infer from the dependency manifests and repo layout.",
"type": "array",
"items": {
"type": "string"
}
},
"ideAgent": {
"description": "The editor or AI IDE in use - claudecode, cursor, copilot, codex, windsurf. You are the IDE, so set this yourself; it decides which rules and config files are generated.",
"type": "string"
},
"languageOverride": {
"description": "Primary language, when it should override what SpecPilot infers from the repo.",
"type": "string"
},
"userTypes": {
"description": "Who is going to use this system, e.g. end users, admins, internal staff.",
"type": "array",
"items": {
"type": "string"
}
},
"customUserType": {
"description": "A user type in free text, when none of the userTypes options fit.",
"type": "string"
},
"accessControl": {
"description": "The access control model. Drives the security spec auth/authorization section and the permission model.",
"type": "string"
},
"specialConsiderations": {
"description": "Cross-cutting concerns that apply, such as accessibility, internationalisation or offline support.",
"type": "array",
"items": {
"type": "string"
}
},
"accessibilityNotes": {
"description": "Anything further on accessibility or constraints, in free text.",
"type": "string"
},
"scaleTier": {
"description": "Expected scale of the system. Drives infrastructure and architecture choices.",
"type": "string"
},
"activeUsers": {
"description": "Roughly how many active users are expected, as a range.",
"type": "string"
},
"deploymentTargets": {
"description": "Where this ships - cloud hosting, a package registry, a browser store. The option list depends on the project type.",
"type": "array",
"items": {
"type": "string"
}
},
"buildTimeline": {
"description": "How long the build is expected to take.",
"type": "string"
},
"teamSize": {
"description": "How many people are building this.",
"type": "string"
},
"systemPattern": {
"description": "Architecture pattern - monolith, modular monolith, or microservices.",
"type": "string"
},
"apiStyle": {
"description": "API style - REST, GraphQL, gRPC or tRPC. Shapes how the architecture spec documents client-server communication.",
"type": "string"
},
"databases": {
"description": "Database kinds in use - SQL, NoSQL, cache/key-value, vector. As many as apply.",
"type": "array",
"items": {
"type": "string"
}
},
"authStrategy": {
"description": "Auth approach - a protocol built in-house (JWT/OAuth/SAML) or a managed service (Clerk, Auth0, Firebase). Feeds the security spec.",
"type": "string"
},
"realtimeEnabled": {
"description": "Whether anything updates live without a refresh. Set automatically when realtimeTypes is non-empty.",
"type": "boolean"
},
"realtimeTypes": {
"description": "Realtime transports - WebSockets, SSE, polling. Leave empty when nothing needs to update live.",
"type": "array",
"items": {
"type": "string"
}
},
"offlineSupport": {
"description": "Whether this has to work offline. Set automatically when localDatabases is non-empty.",
"type": "boolean"
},
"localDatabases": {
"description": "On-device stores backing offline support. Leave empty when offline is not needed.",
"type": "array",
"items": {
"type": "string"
}
},
"dataSyncStrategy": {
"description": "How conflicting local and server state gets reconciled once the device is back online.",
"type": "string"
},
"integrations": {
"description": "Third-party integrations keyed by category, e.g. { payments: [\"stripe\"] }. Only categories relevant to the project type apply.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"otherApis": {
"description": "External APIs or services not covered by integrations.",
"type": "string"
},
"nonGoals": {
"description": "What this project explicitly will NOT do. Becomes the non-goals section of the specs.",
"type": "string"
},
"technicalConstraints": {
"description": "Hard constraints - budget, existing infrastructure, legacy systems, a fixed deadline.",
"type": "array",
"items": {
"type": "string"
}
},
"constraintDescription": {
"description": "More detail on whatever was named in technicalConstraints.",
"type": "string"
},
"compliance": {
"description": "Compliance regimes that apply - GDPR, HIPAA, SOC 2. Pick by the actual situation (EU users, health data, payments), since getting it wrong has legal consequences.",
"type": "array",
"items": {
"type": "string"
}
},
"apiResponseTime": {
"description": "Target API response time.",
"type": "string"
},
"availability": {
"description": "Availability SLA target as a fraction of uptime; higher percentages allow far less downtime per year.",
"type": "string"
},
"securityConcerns": {
"description": "Security measures to plan for - encryption, rate limiting, audit logging.",
"type": "array",
"items": {
"type": "string"
}
},
"testingStrategy": {
"description": "Testing approaches this project will use.",
"type": "array",
"items": {
"type": "string"
}
},
"cicd": {
"description": "CI/CD practices - automatically running tests and deploying on every change.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"required": [
"answers"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
SpecPilot is a spec-driven development (SDD) CLI for AI coding agents like Claude Code, Cursor, and ChatGPT. It initializes, validates, and syncs a .specs/ directory so AI-assisted coding stays grounded in living requirements, architecture, and task specs instead of drifting from the codebase. specpilot serve lays that folder out in a local web page: the tasks, the architecture, the test plan, the security model, and your AI IDE's instructions, commands and skills.
SpecPilot CLI demo
MCP server
Prefer to stay inside your editor? SpecPilot also runs as a remote MCP server, so
Claude Code, Cursor or Copilot can run the whole onboarding itself - answering what
it can infer from your repo and asking you only the rest.
bash
claude mcp add --transport http specpilot https://init.specpilot.dev/mcp
Then ask your agent: "Onboard this project with SpecPilot".
For Cursor, VS Code and other clients, add it as an HTTP (streamable) server:
specpilot serve also serves a local MCP endpoint, so your AI IDE can read this machine's specs, add or move tasks and set up a folder: see Local MCP endpoint below.
Requirements
Node.js 22.23.5 or later 22.x, 24.22.3 or later 24.x, or 26.13.1 or later (package.jsonengines: ^22.23.5 || ^24.22.3 || >=26.13.1): the Node.js release lines that still get security fixes, at or above their November 2026 security release. Older Node.js versions and 25.x are not supported. npm warns (EBADENGINE) when you install on a Node.js outside this range, but does not stop the install.
Serve a local web UI over the .specs/ of this project, or of each folder named, plus the projects remembered in ~/.specpilot/projects.json (every project you serve or open; reopened at startup when they have .specs/); in a folder without .specs/ and with nothing remembered, with no project open until you open one from the page (task moves, new tasks, Regenerate All for command files, the Setup view of a folder without .specs/, unless --read-only)
Tip — command aliases: All commands have a short alias you can use instead of the full name.
init → i · validate → v · migrate → m · list → ls · refine → ref · archive → ar · add-specs → add · backfill → bf
Example: specpilot i my-app is identical to specpilot init my-app.
Run specpilot <command> --help for full flag descriptions and default values.
Examples
bash
# Initialize with specific language/framework
specpilot init api --lang python --framework fastapi
# Preview files that would be created without writing anything
specpilot init api --dry-run
# Refine specifications
specpilot refine "REST API for user management" --update
# Validate with auto-fix
specpilot validate --fix
specpilot serve
Serve a local web UI over a project's .specs/, where you can also move tasks between Backlog, Current Sprint and Review, approve or send back what an agent finished, add new ones, bring SpecPilot's command files up to date, set up .specs/ in a folder that has none yet, and open more projects. With no folders it serves the project you run it from (the folder that contains .specs/); name one or more folders to serve those instead, all from one server, or open them later from the page. Press Ctrl+C to stop.
bash
specpilot serve # this project, at http://127.0.0.1:4321
specpilot serve --port 5000 --open
specpilot serve ../api ../web # two projects on one server; switch in the left rail
specpilot serve ../new-project # no .specs/ there yet: the page sets it up (or `specpilot serve .`)
specpilot serve --stop # stop the server on port 4321 from another terminal (--port for another)
Option
Default
Description
--port <n>
4321
Port to listen on (127.0.0.1 only)
--poll <ms>
1000
Change-detection interval in ms (minimum 250); polling runs only while a page is open
--read-only
No task moves, no new tasks, no Setup view steps, no opening folders and no registry: the UI only reads, with no drag handles, no Add or Archive buttons and no write routes
--open
Open the UI in the default browser
--no-mcp
Leave out the local MCP endpoint at /mcp (served by default for your AI IDE, with the Connect Your AI IDE card on Home and in the Setup view; below). --mcp is still accepted and changes nothing
--stop
Stop the SpecPilot server running on this machine on --port (default 4321), as Ctrl+C would; takes no other option. A --read-only server cannot be stopped this way: press Ctrl+C in its terminal
Several projects: name any folders; one without .specs/ is served too and shows the Setup view (below). They are numbered in command-line order from 0 (../api is project 0, ../web is project 1), and that number is the ?project=<n> on the server's /api/ routes and the #1/... at the start of a page link for any project after the first (no number means project 0). Each project keeps its own tasks, files and live reload; a move changes only that project's tasks.md. Folders opened from the page (below) get the next numbers; a number never changes while the server runs, and one server holds at most 20 projects.
Quit: the power button at the foot of the left rail stops the server after you confirm, as Ctrl+C or specpilot serve --stop would (a running clone is stopped and cleaned up first). The page then says SpecPilot has stopped; other open pages simply stop updating. Not shown with --read-only.
Task moves: drag a row, use Alt+Up/Down to reorder and Alt+Left/Right to move between Backlog, Current Sprint and Review (Backlog and Current Sprint either way; Current Sprint to Review and back), or open a card's menu (right-click, the ⋯ button on the card, or Shift+F10) and pick Move to <lane> (its end, or <lane>, top), Move up or Move down; the menu also has Open details and Copy ID. A move changes exactly one line of .specs/planning/tasks.md and nothing else, and offers Undo; Completed and Won't do rows do not move. If the file changed on disk since the page loaded, the move is refused and the page redraws. Start with --read-only to turn moves off.
Warning while work is in progress: a move from the page, and Archive, ask first when the project is on a branch other than main or master, or when a .specs/ file changed on disk in the last two minutes and not from the page (an agent or editor at work). The dialog says what could happen (the change rides on the branch's work and can conflict at the merge; an agent saving an older copy of tasks.md can undo it) and offers Cancel or Move anyway; Archive adds the check to its own list. The page knows only what it has seen since it loaded. Approve and Send back never ask.
Review lane: ## Review in .specs/planning/tasks.md holds finished work that you check before it counts as done; the lane's header reads Review HITL (human-in-the-loop). Your AI agent moves finished work from Current Sprint to Review, never straight to Completed (the generated instruction files and the MCP server say so). Open a Review card: Approve appends Approved <date> to the row and shows an Approved chip, and the panel says the next step (tell your agent to wrap it up; Copy prompt gives you the line); Send back opens a note box (What needs fixing? (optional), up to 200 characters, Cmd/Ctrl+Enter sends, Escape cancels), appends Sent back <date>: <note> and moves the row to the top of Current Sprint, so the agent picks it up next; both offer Undo, and the panel lists earlier notes under History. A drag or Alt+← out of Review is a Send back without a note, so an approved row that comes back is no longer approved. The agent writes the Completed entry (number, CD ID, commit) by hand once a row is marked Approved; SpecPilot never writes it. ## Won't do, when the file has it, is a read-only lane after Completed, folded to a strip until you open it. Off with --read-only.
Type and Priority: when Backlog, Current Sprint and Review are | ID | Type | Priority | Description | tables (what init writes), each card shows its Priority (P1 to P3) and Type (feat, bug, chore) on its bottom line, and the task details set them with two button groups that save at once; New Task offers them too. A table that is still | ID | Description | works as before; when all three are, a note above the lanes says how to add the columns (Copy prompt), and a warning says when the three lanes' shapes differ, because a row with a Type or Priority cannot move into a table without the columns. Off with --read-only.
Section headings: when .specs/planning/tasks.md lacks ## Backlog, ## Current Sprint, ## Review or ## Completed, a warning above the lanes names the empty lane, what the file has instead and the fix (edit the file; best ask your AI IDE, so anything that refers to the section follows), with Open tasks.md in VS Code and Copy prompt; a ## heading the board does not know gets a note that its rows are not shown here; a known section that holds its tasks as plain lines or a list instead of a table gets a warning saying the lane shows none of them and how to turn them into a table. Warnings hide for the session into a one-line strip, notes until the headings change. specpilot validate warns on the missing ones and --fix renames an unambiguous variant.
Commands and Skills: each view lists its files in two groups. Under From SpecPilot are the specpilot-* commands whose bytes match a version SpecPilot released (in .claude/commands/, .github/prompts/, .cursor/commands/, .windsurf/workflows/, .agent/workflows/ and .codex/prompts/) and the specpilot-project skill while it is still SpecPilot's own render of your project.yaml; everything else is under Yours, including a specpilot-* command you edited and every file in Devin Desktop's .devin/workflows/, which SpecPilot does not write, and every other skill in .claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/ and .agent/skills/ (the project skills folders Claude Code, Cursor, Codex, Copilot and Antigravity read). Regenerate All, in the From SpecPilot header of Commands, runs what specpilot backfill runs for command files, and nothing else: for each IDE project.yaml lists in ides (without that line, each IDE whose instruction file is in the project) it adds the missing specpilot-* commands and updates the unedited ones to the current version, in every IDE's command folder. It also refreshes .claude/skills/specpilot-project/SKILL.md from .specs/project/project.yaml (name, language, framework, platforms, package manager, test framework, repository URL, license) when the skill is still SpecPilot's own, and adds it when missing; a skill you edited, or one rendered from values project.yaml no longer holds, is kept with the reason does not match SpecPilot's render of project.yaml. Edited files, links, files under a linked folder, your own commands and skills, instruction files and .specs/ are never written. What it did is shown above the groups as it happened: updated, added, and kept with the reason.
New Task: the + Add button in the header of the Backlog or Current Sprint lane opens a small form for that lane: a description, with the ID the row will get shown above it. SpecPilot adds one row, | <ID> | <description> |, at the end of that section's table in .specs/planning/tasks.md and changes nothing else in the file. The ID is the next free one: BL-### for Backlog, CS-### for Current Sprint, one past the highest in use in tasks.md and tasks-archive.md (only IDs in ID columns and leading tags count, not IDs mentioned in a description; gaps are never filled). The description is written exactly as you typed it, markdown included, with no label or date added; one with a line break, a control character, a | or a trailing \, or over 4000 characters, is refused with the reason, and what you typed stays in the form. The new row is selected and opened in the details panel. If the file changed on disk since the page loaded, nothing is added and the page redraws. Protected like a task move; off with --read-only.
Archive oldest Completed rows: the Completed lane's header has an Archive button. It opens a dialog that says what the action does and lists the checks that apply, each with its state: the branch (as specpilot archive warns, archive on main or master after merging) and ## Completed's 25-line limit (the specpilot validate warning), with how many rows would move. A check that warns has a box to tick, and Archive is enabled once every box is ticked. It then does what specpilot archive does for that section: the oldest rows move, byte for byte, into a dated block at the end of .specs/planning/tasks-archive.md, the newest 10 stay, nothing else in either file changes, and the lane shows what is left. Within the limit you can still archive by ticking the limit check. prompts.md is left to specpilot archive. Protected like a task move; off with --read-only.
Setup view: a folder without .specs/ (one you name, open from the page or clone) shows the Setup view instead of the other views, and Start a New Project on Home shows it too, with a Project name and a Parent folder (with Browse…). Your AI IDE does the setup: it reads the code, answers what it can, and asks you the rest. The view says how, in three steps: 1 Connect your AI IDE, the config for this server with Copy and a status, Waiting for a connection until an IDE connects to /mcp, then Connected · <the IDE's name>; 2 Tell it what to do, one line to paste into the IDE (Set up SpecPilot for <folder>, or Start a SpecPilot project called <name> in <parent>); 3 Progress, four rows that follow the IDE's calls (Read the code, Answer the questions, Write the files, Validate). When .specs/ appears, the page opens the project; there is no Finish button. For a new project, the page checks the name and the parent as you type and remembers <parent>/<name> for this run of the server as the one place a new project may be made; nothing is created until your IDE does it, and the folder must be missing or empty. Without MCP the view says so and how to restart. specpilot add-specs (in an existing folder) or specpilot init (for a new one) asks the same questions in the terminal. The current-directory default is never offered setup (it needs .specs/ to start; specpilot serve . names it). If a setup is interrupted, the next specpilot serve removes the .specpilot-setup-<id>/ folder it left (and only that folder, recognised by its marker file).
Home: the logo at the top of the left rail, the + tile below the projects (or the h key, or #home) shows "The command center for your spec-driven projects.", an Open a Project Folder button and your Recent projects (path, last-opened time and, for projects already open, the git branch); click one to open it, or Remove from list to forget it (the folder is not touched). specpilot serve starts on the first project's Tasks view (the first folder you named, else the project you opened most recently); in a folder without .specs/ and with nothing remembered it starts with no project open and shows Home (the terminal says No .specs/ folder in <folder>; the folder itself is not served, specpilot serve . names it). --read-only has no Home, so there a folder without .specs/ still exits 1.
Open a project from the page: Open a Project Folder on Home opens a sheet (Clone a Repository opens it on its Clone tab); type a folder path (/Users/you/project or ~/project), or click Browse… to pick it in your system's folder dialog (macOS; Linux with zenity or kdialog; Windows), and Open, and the folder is served alongside the others, with the Setup view if it has no .specs/. Folders you open this way are listed under Recent projects next time, remembered in ~/.specpilot/projects.json (path, last-opened time and a pinned flag, at most 50; the file is created the first time a project is served, and every project you serve or open is added to it). At startup, after the folders you name, the remembered projects that have .specs/ are reopened, pinned and most recently opened first, up to 20 in all (the terminal says Reopened <k> remembered projects from ~/.specpilot/projects.json.); a folder without .specs/ stays on the list to click, a missing one is skipped, and reopening never changes the file. Remove from list forgets a folder without touching it. Browse… only fills in the path; nothing is opened until you click Open. The Clone tab's Parent folder and the Setup view's Parent folder (Start a New Project) have the same Browse… button, which likewise only fills in the field. Checked on macOS: picking a folder fills the field and Open opens it, and no privacy prompt appears at Browse… or at Open, also for a folder inside ~/Documents; the Linux and Windows dialogs are not yet checked by hand. The home folder, the root of a drive and folders already open are refused; a projects.json that cannot be read is left exactly as it is, and the page and the terminal say so. The request is protected like a task move.
Clone a repository from the page: Clone a Repository on Home (or the Clone tab of the same sheet) asks for a repository URL, a parent folder and a folder name (leave it empty for the repository's name), runs your installed git clone and opens the result: on Tasks when the repository has .specs/, in the Setup view when it has none. Accepted URLs: https://host/path, git@host:path and ssh://host/path; an https URL must not contain a user name or password (git uses your credential helper and ssh keys, as in a terminal), so for Azure DevOps drop the org@ part. Submodules are not cloned, Git LFS files are left as pointer files (run git lfs pull in the folder to fetch them), and there is no branch or depth option. The target folder must not exist or must be empty; the parent follows the rules of Start a New Project. As you type or paste the URL, Folder name is filled with the repository's name until you type one yourself. While the clone runs the sheet shows the elapsed time and, once git reports it, git's stage and percentage (Receiving objects 42% · 0:13, then Resolving deltas and Updating files); until then, or when git reports none, a moving bar. git is never asked a question it would wait on: a repository that needs a login it cannot get fails with git's own message, its last fatal: line with the line before it, for example Host key verification failed. fatal: Could not read from remote repository., and a clone is stopped after 10 minutes. The page cannot accept an ssh host key for you: for a host you have never connected to, run ssh -T git@host once in a terminal, then clone again. Your ssh setup is used as it is; SpecPilot sets no ssh option on macOS and Linux. One clone runs at a time. A clone that fails, is stopped, or is cancelled (Cancel, Escape, closing the tab, Ctrl+C) removes what it downloaded; on Ctrl+C the server waits at most 5 seconds for that. Needs git on your PATH. This is the only time SpecPilot starts another program for the page and the only time it uses the network. On Windows ssh is put in batch mode (unless you have set GIT_SSH_COMMAND, GIT_SSH or core.sshCommand), and a stopped clone can leave git's helper process running until it ends by itself, and the clean-up can then fail on a file that helper still holds; the message says so.
Open in VS Code: the icon at the top right of every project view (and beside each Recent project on Home whose folder still exists) is a vscode://file/ link to that project's folder. Your browser hands it to VS Code, which asks before opening it; SpecPilot starts nothing itself. Nothing happens if VS Code is not installed. A task's details panel has Open tasks.md in VS Code, which opens .specs/planning/tasks.md at that task's line; VS Code puts a file in the window it picks (by default the last one you used), which may not be this project's. It opens VS Code only, not Insiders or another editor. The file view of every .specs/ file and the details panel of every Instructions, Commands and Skills file also have Open in VS Code, which opens that file.
Open in AI IDE: the sparkle icon beside Open in VS Code shows a short menu when it has something to offer. Open in Cursor (cursor://file/) appears when the project has .cursor/rules/specpilot.mdc, the file SpecPilot writes for Cursor. While .specs/development/onboarding.md exists, Send onboarding prompt to Cursor puts the prompt into Cursor's chat through Cursor's own link (it stays on this machine; Cursor waits for you to confirm, and uses the window it has in front, so open the project in Cursor first), and Copy onboarding prompt copies it for Claude Code, which has no link to open, or any other IDE. A prompt too long for a Cursor link (10,000 characters) is copied instead. It is on project views only, not on Home's rows.
Nothing else is written: in a project with .specs/, its .specs/planning/tasks.md and, through Regenerate All, its specpilot-* command files and its specpilot-project skill are the only files the server can change; in a named folder without .specs/, setup creates new files and changes none; a new project is one new folder (or an empty one) with new files; a clone is one new folder (or an empty one) filled by git clone; ~/.specpilot/projects.json is the one file written outside your projects; everything else is read on every request.
Loopback only: binds 127.0.0.1 only; rejects any Host header other than 127.0.0.1:<port> or localhost:<port> (403).
Live reload: polls allowlisted files with stat() every --poll ms while a page is open, and pushes changed paths on /api/events; open pages update in place.
What it shows: .specs/, the instruction files CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .cursor/rules/specpilot.mdc, .windsurfrules, .antigravity/rules.md and CODEX_INSTRUCTIONS.md, and the folders .claude/commands/, .claude/skills/, .github/prompts/, .cursor/commands/, .windsurf/workflows/, .agent/workflows/, .codex/prompts/, .agents/skills/, .cursor/skills/, .github/skills/, .agent/skills/, .devin/skills/, .windsurf/skills/ and .devin/workflows/, as the files' own text. Nothing else in an IDE's folder is shown: not .cursor/mcp.json or other settings files, which can hold tokens.
Limits: paths through symlinked folders, hidden files and node_modules are not shown. The Connect Your AI IDE configs follow each IDE's docs as read on 2026-11-09; only Claude Code's was tested with the IDE itself. The Skills view lists Windsurf's .devin/skills/ and legacy .windsurf/skills/ from Windsurf's (Devin Desktop's) docs as read on 2026-11-14, unverified with Windsurf itself, and not .codex/skills/, which Codex's docs do not name; Antigravity's .agent/skills/ comes from Google's codelab; skills folders in subfolders such as apps/web/.cursor/skills/ are not listed; and no IDE was tested loading skills from these folders. The Commands view lists Devin Desktop's .devin/workflows/ from its docs as read on 2026-11-15. SpecPilot still writes .windsurf/workflows/ and .windsurfrules, which those docs call legacy and read when a workspace kept .windsurf/; whether a workspace migrated to .devin/ still reads them, and whether Devin Desktop still reads the Connect card's ~/.codeium/windsurf/mcp_config.json, is not verified with Devin Desktop itself. Task moves and new tasks are refused, not approximated, when they cannot change exactly one line: a section with no table yet (a fresh project's [TODO]), a move involving the file's last line when it has no trailing newline, and a tasks.md that is not valid UTF-8. If an editor saves tasks.md in the same instant the server writes it, that save can be overwritten; git keeps it recoverable. VS Code reads a path ending in :<number> as a line number, so a project folder whose name ends that way (notes:12) may not open as a folder from Open in VS Code. Windows paths (C:\…) in that link are untested. The Cursor links are untested on a machine with Cursor installed, and Windsurf has none yet. The Setup view's Connected status shows the name the IDE sends when it connects (clientInfo); it was checked with test requests in both MCP revisions, not with every IDE. The order the setup tools want is sent as the MCP instructions and in the tools' descriptions; whether an IDE shows instructions to its agent is up to the IDE, and only test requests were checked. A local program that can read the page can also register a new project's folder itself: the setup tools guard against an agent writing elsewhere by mistake, not against software already running on your machine. The server treats every user and program that can reach its port on this machine as you, so do not run it on a machine shared with other accounts. With SPECPILOT_MCP_TOKEN set, your IDE sends that token to whatever program holds the port while serve is down; if another program has used the port, set a new value. A service worker another program left on the port is removed when the page loads, and the page takes no token while one is in control; this is checked in Chromium, not yet in Firefox or Safari, and Safari before 16.4 lacks part of it. A page shown inside another tool's frame (for example an editor's built-in browser) does not display; open it in a browser tab. No other page can frame it or clear its saved theme and dismissed notes.
Local MCP endpoint (specpilot serve)
The server also answers MCP at http://127.0.0.1:<port>/mcp, so Claude Code, Cursor and other AI IDEs on this machine can read the specs and add or move tasks through the same checks as the page. It is on by default; start with --no-mcp to leave it out (the Setup view then says how to restart). --mcp is still accepted and changes nothing.
bash
specpilot serve
# MCP endpoint: http://127.0.0.1:4321/mcp# Claude Code (.mcp.json): {"mcpServers":{"specpilot-local":{"type":"http","url":"http://127.0.0.1:4321/mcp","headers":{"X-SpecPilot-Token":"<token>"}}}}# Other IDEs: Connect Your AI IDE on the page gives each one's file.
The terminal line is Claude Code's. Each IDE takes its own file and shape, so the Connect Your AI IDE card on Home and step 1 of the Setup view have one button per IDE, chosen from the project's instruction file until you pick one, and show that IDE's file, config and note, with Copy:
TOML [mcp_servers.specpilot-local], url, http_headers or env_http_headers
Antigravity
.agents/mcp_config.json in the project
mcpServers, serverUrl, headers
A project file that holds the page's token belongs in .gitignore; the card's note says so. With SPECPILOT_MCP_TOKEN set, the config names the variable where the IDE reads one, and Windsurf and Antigravity get a placeholder for its value.
Tools: specpilot_list_projects, specpilot_read_spec, specpilot_list_tasks, specpilot_new_task, specpilot_move_task, specpilot_validate_specs (no --fix, writes nothing) and specpilot_regenerate_commands. Each takes an optional project index. The two task writes need the sha256 that specpilot_list_tasks returned; if tasks.md changed since, the write is refused ("since you last read it") and nothing is written. Open pages show the change through live reload.
Setup tools: specpilot_setup_questions (a path) returns what was detected in the code and every question, with choices and suggestions; specpilot_setup_project (the path, the answers, and which ones the user gave) writes .specs/, the instruction files and the skill (creating a new project's folder), runs specpilot validate and returns the files written and the result. Nine tools in all. They work only on a folder the page is setting up: one you named, opened or cloned that has no .specs/, or the new project's folder you named on the Setup view. The server tells the IDE the order (questions, answer from the code, ask the user the rest, write, report). The Setup view's Progress rows follow these calls.
Same guards as the page: loopback only, the Host check, the token (a wrong or missing X-SpecPilot-Token gets 403), JSON only, 64 KB, the page's read allowlist, the page's write allowlist and one write lock for page and IDE. A request from a web page (any other Origin) is refused with 403; IDEs send none. Clones and the project list are not tools.
Protocol revisions: MCP 2026-07-28 (no handshake; the version, Mcp-Method and Mcp-Name headers must match the request body), and 2025-11-25 and 2025-06-18 (with initialize), on the same URL. A client that speaks both picks one; the config line is the same. Streamable HTTP, POST only, no sessions; answers are JSON, never a stream, and no change notifications are sent.
Token: a new one each time serve starts, so the line needs copying again after a restart. To keep one line, set SPECPILOT_MCP_TOKEN (at least 32 characters, no spaces) in the environment of serve and of your IDE; the config then names the variable where the IDE reads one (Claude Code, Cursor, VS Code, Codex), and Windsurf and Antigravity get a placeholder for its value. SpecPilot never writes the token anywhere.
--read-only: only the four read tools (no task writes, no Regenerate, no setup tools); the endpoint gets its own token and the page stays read-only.
Instruction files: files generated by init, add-specs and the setup through your AI IDE carry one more process mandate: use the SpecPilot MCP tools for tasks when they are connected, otherwise edit .specs/planning/tasks.md and keep its table format (| ID | Type | Priority | Description | under Backlog, Current Sprint and Review, or | ID | Description | in a file that has that shape; | # | ID | Description | under Completed; one row per task). specpilot backfill adds it to an existing file that has no Tasks line.
Supported Languages & Frameworks
TypeScript
React: SPA applications
Express: REST APIs
Next.js: Full-stack apps
Nest.js: Scalable server-side apps
Vue: Progressive UI framework
Angular: Enterprise SPA framework
JavaScript
React: SPA applications
Express: REST APIs
Note: no framework prompt is shown for JavaScript — pass --framework explicitly if needed.
Python
FastAPI: Modern REST APIs
Django: Full-stack applications
Flask: Lightweight REST APIs
Streamlit: Data Science / ML apps
Kotlin
Android: Native Android apps
Spring: Server-side REST APIs
Ktor: Async Kotlin web framework
Compose: Jetpack Compose UI
Swift
iOS: Native iOS apps
SwiftUI: Declarative Apple UI
Vapor: Swift server-side framework
Project Structure
SpecPilot generates a .specs/ folder with organized subdirectories:
code
.specs/
├── architecture/
│ ├── api.yaml # CLI / REST API / GraphQL interface spec
│ └── architecture.md # System design decisions and patterns
├── development/
│ ├── context.md # Development memory, decisions, learnings
│ ├── onboarding.md # One-time AI bootstrap prompt — delete after first use
│ └── prompts.md # AI interaction log — MANDATED, update every session
├── planning/
│ ├── roadmap.md # Release milestones and objectives
│ └── tasks.md # Sprint tracker (backlog / current / completed)
├── project/
│ ├── project.yaml # Project config and AI context (MANDATED)
│ └── requirements.md # Functional & non-functional requirements
├── quality/
│ └── tests.md # Test strategy, coverage targets, acceptance criteria
└── security/
├── security-decisions.md # ADR-style security design decisions
└── threat-model.md # Threat inventory with impact/likelihood/mitigation
Also generated at project root: an AI context file (.github/copilot-instructions.md, CLAUDE.md, .cursor/rules/specpilot.mdc , .windsurfrules, .antigravity/rules.md etc.) based on your selected IDE/Agent
Configuration
SpecPilot requires no global configuration. Each project is self-contained with settings in project.yaml.
IDE & Agent Support
SpecPilot generates AI agent configuration files during project initialization. When you run specpilot init, you'll be prompted to select your AI IDE/Agent:
Desktop IDEs (Workspace Settings):
GitHub Copilot - Industry standard with Copilot integration
Cursor - AI-first code editor with enhanced AI context
Windsurf (Devin Desktop) - Advanced AI coding assistant
Antigravity - AI-powered IDE with context awareness
Cloud-Based AI Agents (Instruction Files):
Claude Code - Anthropic Claude Code CLI agent (CLAUDE.md)
Codex - OpenAI Codex agent with instruction context
Generated Configuration Files:
Each IDE/Agent selection generates one AI context file at the project root:
IDE/Agent
Generated file
GitHub Copilot
.github/copilot-instructions.md
Codex
.github/copilot-instructions.md
Cursor
.cursor/rules/specpilot.mdc
Windsurf (Devin Desktop)
.windsurfrules
Antigravity
.antigravity/rules.md
Claude Code
CLAUDE.md
All context files contain: project name/stack, critical mandates, Code Philosophy, Code Rules, and a Re-Anchor Prompt.
Which IDEs SpecPilot writes for: setup records your choice in .specs/project/project.yaml as ides: [cursor] (the lowercased choice; vscode is GitHub Copilot). specpilot backfill, Regenerate All on specpilot serve and the specpilot_regenerate_commands tool write commands for the IDEs that list names, and the page offers Open in Cursor and preselects the Connect card's IDE from it. Add an IDE by hand (ides: [cursor, claude-code]) to have its commands written too. A project without the line, set up before it existed, works as before: SpecPilot looks for each IDE's instruction file. specpilot validate warns about a value it does not know.
For desktop IDEs: .vscode/settings.json (or .cursor/, .windsurf/, etc.)
IDE-specific workspace folder setup for code + .specs
Extensions recommendations for development
AI context configuration for better spec integration
Generated Slash Commands
Each IDE/Agent selection also generates 8 specpilot-* slash/workflow commands (status, reanchor, report, sync, refine, validate, archive, backfill) that mirror key CLI operations as in-editor commands — e.g. .claude/commands/specpilot-status.md for Claude Code, .cursor/commands/ for Cursor, .github/prompts/ for GitHub Copilot. Running backfill on an existing project fills in any commands missing for your already-configured IDE(s) and updates the ones you have not edited to the current version; edited files are kept and listed. Each command file is reported as added, updated (to the current version), or kept with its reason: kept: modified (you changed it; delete it and re-run specpilot backfill to get the latest version), kept: CRLF line endings (a known version saved with Windows line endings) kept: symbolic link (links are never written through), kept: folder is a symbolic link or not a folder (nothing is written through a linked .claude/ or similar) or kept: could not be written: <code> (the write failed; the rest still run). The specpilot serve page's Regenerate All runs the same step. See the Full Guide for the complete list and per-IDE paths.
SpecPilot's commands do not write through symbolic links in the project, even links that point inside it; replace the link with the file to have it updated.
The generated settings/instructions automatically configure your AI agent to:
Include .specs/ folder in AI context
Understand project structure and requirements
Follow specification-driven development principles
Access development guidelines and onboarding prompts
Example:
bash
# During init, you'll be prompted to select your IDE/Agent
specpilot init my-project --lang typescript --framework react
# Respond with your preferred IDE/Agent:# - vscode, cursor, windsurf, antigravity (desktop)# - claude-code, codex (cloud agents)
Troubleshooting
Common Issues
Permission Errors
bash
sudochown -R $USER ~/.npm-global
npm config set prefix '~/.npm-global'
Template Not Found
bash
specpilot list --verbose
Validation Failures
bash
specpilot validate --verbose --fix
Migration Issues
Error: "Source structure 'complex' not found"
bash
# For NEW projects, use:
specpilot init my-project
# For EXISTING projects without specs:
specpilot add-specs
# Only use migrate if you have an old .project-spec folder
specpilot migrate --from complex --to simple --backup
Debug Mode
bash
DEBUG=specpilot specpilot <command>
Why SpecPilot?
SpecPilot implements Specification-Driven Development (SDD) where specifications come first:
Clarity: Everyone understands what needs to be built
Consistency: Standardized structure across projects
Quality: Built-in validation and testing
AI-Ready: Clear context for AI assistants
Maintainable: Comprehensive documentation
Contributing
This project follows SDD principles. See .specs/ for contribution guidelines.
Development Setup
bash
git clone https://github.com/girishr/SpecPilot.git
cd SpecPilot
npm install
npm run build
npm link# For local testing
Browser tests for specpilot serve
The page's clicks, keys, focus and live reload are tested in headless Chromium, separately from npm test:
bash
npx playwright-core install chromium-headless-shell # once, if Playwright's Chromium is not on this machine yet
npm run test:browser # builds, then runs src/__browser__/ (about 10 s)
The suite starts the built server on scratch copies of a fixture project (src/__browser__/fixture/, never this repo's own .specs/) under a temporary HOME, so it writes nothing in the repo or in ~/.specpilot/. A failing test prints the paths of its error message and stack, a screenshot and the page's HTML, kept in a temp folder.