What is GitHub Spec Kit?
Spec Kit is GitHub's open source toolkit for spec-driven development: a command-line program called specify, plus templates, scripts and agent skills that it installs into your project. Its README describes it as a toolkit "that gives AI coding agents structured processes, reusable templates, and documented outcomes." GitHub introduced it on The GitHub Blog on September 2, 2025. If writing specs for agents is new to you, start with our spec-driven development guide. This post is the hands-on part.
The core process is spec-driven development (SDD): define what to build and why, then turn the spec into a plan, a task list and code. Bug fixing and idea assessment ship as bundled extensions you install when you need them. Spec Kit changes fast: versions 1.4.0 to 1.4.3 came out between November 10 and November 19, 2026 (releases). Pin a version and check the docs before you rely on a detail.
We installed specify-cli 1.4.3 from PyPI on November 21, 2026 and ran init, the feature script and the overlay commands below in a test project on a Linux machine. Agent steps need a model, so for those we describe what each skill tells the agent to do, quoted from the skill files that 1.4.3 installed. We tested the workflow steps we added on their own. The outputs shown are from our run.
How do you install Spec Kit and set up a project?
Install the specify CLI once, then run specify init in each project and name your coding agent. The installation guide lists uv, pipx and pip, and asks for Python 3.11 or later:
# Needs Python 3.11 or later. uv is the recommended tool for the PyPI install. uv tool install specify-cli==1.4.3 # or: pipx install specify-cli==1.4.3 # or: pip install specify-cli==1.4.3 (inside a virtual environment) specify init my-project --integration claude --script sh cd my-project
Three things to know. First, always pass --integration: in a session with no terminal, init picks GitHub Copilot by default. Second, init needs no network access, because its help text says the templates ship inside the package and so match the CLI version. Third, init ended with a warning that some agents store credentials or tokens in their folder, and suggested adding .claude/ (or parts of it) to .gitignore. With --integration claude --script sh, it created these files:
.claude/skills/speckit-{constitution,specify,clarify,plan,checklist,
tasks,analyze,implement,converge}/SKILL.md
.specify/memory/constitution.md project principles (from a template)
.specify/templates/ spec, plan, tasks, checklist, constitution
.specify/scripts/bash/ create-new-feature.sh, setup-plan.sh, ...
.specify/workflows/speckit/workflow.yml the "Full SDD Cycle" workflow
.specify/init-options.json integration, script type, numbering
Claude Code gets skills, not slash command files. Run specify integration list to see the rest: version 1.4.3 lists 43 integration keys, including codex, gemini, cursor-agent and copilot, plus generic for any other agent.
Which Spec Kit commands do you run, and in what order?
Run constitution once per project, then specify, plan, tasks, implement and converge for each feature, one at a time, and review each result before the next. The README is clear that these run "in your agent's chat, not your terminal." Here is what each skill in 1.4.3 tells the agent to write:
| Command | What it writes | Note |
|---|---|---|
/speckit-constitution | .specify/memory/constitution.md | Once per project. Later commands read it. |
/speckit-specify | specs/NNN-name/spec.md, checklists/requirements.md | The what and why. At most 3 [NEEDS CLARIFICATION] markers. |
/speckit-clarify | Answers back into spec.md | Optional. Up to 5 targeted questions, before plan. |
/speckit-plan | plan.md, research.md, data-model.md, contracts/, quickstart.md | Tech stack and design. Stops after design. |
/speckit-checklist | A checklist in checklists/ | Optional. Tests the requirements, not the code. |
/speckit-tasks | tasks.md | Dependency-ordered tasks, grouped by user story. |
/speckit-analyze | Nothing | Optional. "STRICTLY READ-ONLY" consistency report. |
/speckit-implement | Code, plus [X] marks in tasks.md | Works through the task list. |
/speckit-converge | New tasks at the end of tasks.md | Append-only. Repeat with implement until it reports Converged. |
Command names depend on your agent. The command invocation docs use /speckit.specify in references, /speckit-specify for skills in GitHub Copilot (and in our Claude Code run), $speckit-specify in Codex and /skill:speckit-specify in Kimi.
What does a Spec Kit feature folder contain?
Each feature gets a numbered folder under specs/, and .specify/feature.json records which folder is current. The specify skill names the folder from a sequence number and a short name of two to four words, such as 003-user-auth, or from a timestamp if you chose that numbering. It then writes the path to .specify/feature.json so the later commands "locate the feature directory without relying on git branch name conventions." Branches are optional. The core command always creates the folder, and the bundled git extension creates a branch first through a before_specify hook if you install it.
When we ran the feature script by hand with "Let users export their board as CSV", it created specs/001-let-users-export/spec.md and that feature.json entry. The tasks file is where the work is tracked. Spec Kit's tasks template uses the format [ID] [P?] [Story] Description, where [P] means a task "can run in parallel (different files, no dependencies)". Here is a short example in that format, with one task done and one task added by converge:
## Phase 3: User Story 1 - Export one board (Priority: P1)
- [X] T002 [P] [US1] Contract test for GET /boards/{id}/export in tests/contract/test_export.py
- [ ] T003 [US1] Implement CSV writer in src/export/csv_writer.py
- [ ] T004 [US1] Add export endpoint in src/api/export.py (depends on T003)
## Phase 4: Convergence
- [ ] T005 Return 404 for an unknown board ID in src/api/export.py per FR-004 (missing)
Implement marks each finished task [X]. Converge never edits a line. It adds a new phase with new IDs for whatever is missing, so a task list only grows.
How do Spec Kit workflows and review gates work?
A workflow runs the commands for you, from your terminal, and stops at review gates. The bundled speckit workflow runs specify, plan, tasks and implement, with a gate after the spec and another after the plan. The workflows overview says a gate asks for a verdict on an interactive terminal and pauses otherwise:
specify workflow run speckit --input spec="Let users export a board as CSV" # No terminal attached? The run pauses at each gate. Review, then: specify workflow status <run_id> specify workflow resume <run_id> --input speckit_review_spec_verdict=approve
The docs say agent steps "require an integration capable of CLI execution." Each run keeps its own state, and completed steps are not run again on resume. One line in the docs matters if a step writes to another system: "a side effect interrupted before its completion checkpoint may still repeat." Remember this in the next section.
How do you send Spec Kit tasks to a shared board?
Add a workflow overlay that runs a card import right after the tasks step, then a gate before implement. Progress in tasks.md lives on one agent's branch. A teammate or a second agent sees nothing until someone pushes, and the file can't show who is working on a task or what is waiting for review. A board can show both. Spec Kit's own github extension takes the same view for GitHub: its README says it "turns a feature's tasks.md into dependency-ordered GitHub issues." For a Flux board for AI agents, an overlay does the job without forking the workflow.
Overlays edit the step list of an installed workflow, and they survive workflow updates. This one inserts a shell step after tasks that runs the tasks_to_flux.py import script from our spec-driven development guide (save it as scripts/tasks_to_flux.py), and a gate before implement:
# flux-overlay.yml
id: "flux-cards"
extends: "speckit"
priority: 10
edits:
- insert_after: tasks
step:
id: flux-cards
type: shell
strict: true
run: |
TASKS="$(python3 -c 'import json; print(json.load(open(".specify/feature.json"))["feature_directory"])')/tasks.md"
python3 scripts/tasks_to_flux.py "$TASKS" "$FLUX_BOARD_ID" "$FLUX_COLUMN_ID" --send
- insert_before: implement
step:
id: review-cards
type: gate
message: "Tasks are on the Flux board. Approve to let this run implement them, or reject to hand the cards to your agents."
options: [approve, reject]
on_reject: abort Install it and check where the new steps land:
$ specify workflow overlay add flux-overlay.yml ✓ Overlay 'flux-cards' added for workflow 'speckit' $ specify workflow resolve speckit Step attribution: • specify: base • review-spec: base • plan: base • review-plan: base • tasks: base • flux-cards: project:flux-cards • review-cards: project:flux-cards • implement: base
Then set the four values the script reads, from the project root, and run the workflow as usual:
# Typed keys land in shell history; read -rs FLUX_API_KEY && export FLUX_API_KEY avoids that export FLUX_API_KEY=flux_... # a key with the Write scope export FLUX_IMPORT_SECRET=... # any long random string, same every run export FLUX_BOARD_ID=<board UUID> export FLUX_COLUMN_ID=<Backlog column UUID> specify workflow run speckit --input spec="Let users export a board as CSV"
We ran the two new steps as a local workflow against a mock of the Flux POST /api/cards endpoint, not a live board. Here is what happened:
- Open tasks became cards. Three unchecked tasks became three requests with titles like
001-let-users-export T003: .... The task already marked[X]was skipped. The gate then paused, because no terminal was attached. - A re-run after converge added only the new task. We appended a T005 the way converge does and ran it again. The three earlier requests carried the same
X-Idempotency-Keyand came back deduplicated, and only T005 was new. On a real board, Flux returns the earlier card with"deduplicated": truefor a key it has already seen. That is also your protection when a step repeats after an interruption. Our guide to idempotency keys for AI agents covers what the key does not protect against. - A bad key stopped the run. With a wrong API key the script exited with code 1, the step failed, and the workflow stopped before the gate and before implement.
- Reject ended the run. On a terminal, the gate offered approve or reject, and reject marked the run aborted.
Four details matter. First, strict: true makes Spec Kit reject {{ expressions in run, so nothing from the spec is pasted into shell code. Second, keep the API key in your environment, not in the overlay file, which lives in .specify/ and usually gets committed. Third, read every shell step before you add it: Spec Kit warns that a shell step "runs a local command with your privileges" and has no sandbox. Fourth, use the board UUID for FLUX_BOARD_ID every time. The board ID is part of each key, so switching to the short ID from the board's URL would make new keys and duplicate cards.
How should agents work the cards?
Approve the gate when one agent should build the whole feature in this run. Reject it when the tasks will be shared out, and let each agent take one card at a time. Overlays cannot add workflow inputs, so this gate has no verdict input. Without a terminal it stays paused, and approving it means a resume on a terminal.
Tasks marked [P] touch different files, so they are the safe ones to give to different agents, each in its own git worktree, as described in how to coordinate multiple AI coding agents. The implement skill tells the agent it "MUST consider" whatever you type after the command, so you can narrow it to one card. With the Flux MCP server connected:
/speckit-implement Only task T003 in specs/001-let-users-export/tasks.md. Do not start any other task. When T003 is done, mark it [X], post a comment on its Flux card that starts with [claude] and says what changed and how to check it, then move the card to Needs review. Never move a card to Done.
This is an instruction, not a lock. Flux does not enforce column order, so move_card can move a card to any column on its board, and keeping Done for people is a rule your team follows. Comments posted with an API key show under the key owner's name, which is why the agent signs them. Cards the import script creates over REST are recorded in the Flux activity log under the key owner. Changes the agent makes over MCP are not, so its signed comments, the [X] marks and the pull request are what a reviewer reads. An agent that connects through the API or MCP with an existing member's API key never takes a seat on any Flux plan.