Extend GitHub Spec Kit: Add Explore and Alternatives-Review Modes

GitHub Spec Kit takes you from an idea to implementation with an opinionated command flow. But it starts at /speckit.specify — it assumes you already know what to build and which approach won. Tools like OpenSpec add a phase before that: a place to think out loud, and a place to record which alternatives you rejected and why.

You do not have to fork Spec Kit or switch tools to get those two phases. You can add them as two small extension commands:

• explore — a thinking mode before you commit to a specification
• alternatives-review — a mode that compares options and records the decision

This article shows how to build both, and nothing more. The goal is a smaller, sharper Spec Kit — not a bigger one.

TL;DR

• Spec Kit is missing two phases that OpenSpec-style workflows have: open-ended exploration and a recorded alternatives decision.
• Add them as two small commands, explore and alternatives-review (namespaced as /speckit.adaptive-workflow.* once packaged).
• For one repo, install nothing: drop the command files straight into your agent’s command directory (.claude/commands/, .cursor/commands/) and commit them.
• Use an extension (not a fork) only when the commands must travel across repos or a team; a fork is overkill and a preset only reshapes existing artifacts.
• Explore is a thinking stance: investigate, surface assumptions and risks, do not write code, and only persist a document when asked.
• Alternatives-review compares two or more options and writes one artifact that records the chosen path, the rejected options, and the accepted trade-offs.
• Files too long? That is a separate problem — shorten the template and the command (a preset or project-local override), because verbosity comes from the command instructions, not just the templates.
• Do not try to rebuild all of OpenSpec inside Spec Kit. Borrow these two behaviors and stop.
• Treat any community extension you install as a third-party dependency: read its command files before trusting it.

What You Will Learn Here

• Which two phases Spec Kit is missing, and why an extension (not a fork) is the right tool
• How to build an explore command that thinks instead of implements
• How to build an alternatives-review command that records a decision, not just more docs
• How to add both to a repo two ways — ad-hoc with no install, or as a packaged extension — and test them
• When too-verbose output is a separate problem, and where to fix it (a linked companion guide)
• How to connect approved tasks to GitHub Issues and Projects — and what the built-in bridge does not do
• A staged rollout for adopting any of this safely
• Where to stop, so the workflow stays simple

Audience: engineers and architects who use Spec Kit and want a lighter discovery step before the spec. This is a focused how-to, not an OpenSpec migration guide.

Source and Version Boundary

I rechecked this against GitHub Spec Kit v0.10.1 (published June 9, 2026) and its official extension documentation, on July 20, 2026.

The manifest fields and CLI commands below are source-backed for that version. The two commands, their contracts, and the “borrow, don’t rebuild” recommendation are my editorial judgment. Validate the examples against the exact Spec Kit version you install, because extension behavior can change between releases.

If you need the core workflow first, read GitHub Spec Kit: How to Get Started with Cursor or Claude Code. This article starts where the default flow feels too abrupt.

The Two Gaps

Spec Kit’s default path assumes clarity that early work rarely has:

Spec Kit today:      idea ──▶ /speckit.specify ──▶ /speckit.plan ──▶ tasks

What is missing:     idea ──▶ [ explore ] ──▶ [ alternatives-review ] ──▶ /speckit.specify ──▶ ...
                              └ think first ┘   └ decide on purpose ┘

Both are additions, not replacements. Everything else in Spec Kit stays exactly as it is.

Why an Extension, Not a Fork or a Preset

Spec Kit gives you three ways to customize it. The choice is simple:

Add a new command or phase?          Extension  (to reuse across repos/teams)
Add a command in one repo only?      Ad-hoc command file — no install
Change an existing template's shape? Preset, or a project-local override for one repo

explore and alternatives-review are brand-new commands, so they are not a preset (presets only reshape artifacts Spec Kit already generates) and never a fork (a fork makes you responsible for merging every upstream change forever — two commands do not justify that).

That leaves two routes, and the only difference is how far the commands travel. Package them as an extension when several repos or a team need them. Add them ad-hoc — plain command files committed to a single repo — when you just want to try them. Both use the exact same command content you will write below, and the ad-hoc route needs no packaging and no specify CLI. Get the Commands Into a Repo covers it.

One more rule worth stating plainly: do not try to rebuild OpenSpec inside Spec Kit. OpenSpec has persistent change containers, delta specs, task state, and archiving — a whole operating model. Copying all of that would recreate the complexity we are trying to avoid. Borrow the two behaviors above and stop. If you want the full OpenSpec model, compare the two tools directly instead of cloning one into the other.

The Extension Package

Everything lives in one small extension with two commands:

spec-kit-adaptive-workflow/
├── extension.yml
├── commands/
│   ├── explore.md
│   └── alternatives-review.md
└── templates/
    └── alternatives-review-template.md

The manifest targets the v0.10.1 extension schema:

schema_version: "1.0"

extension:
  id: "adaptive-workflow"
  name: "Adaptive Workflow"
  version: "0.1.0"
  description: "Add explore and alternatives-review phases before specification."
  author: "Your Organization"
  license: "MIT"

requires:
  speckit_version: ">=0.10.1"
  commands:
    - "speckit.specify"

provides:
  commands:
    - name: "speckit.adaptive-workflow.explore"
      file: "commands/explore.md"
      description: "Explore a problem before specification."
    - name: "speckit.adaptive-workflow.alternatives-review"
      file: "commands/alternatives-review.md"
      description: "Compare options and record the decision."

The namespaced names (speckit.adaptive-workflow.explore) make the boundary obvious: these are your additions, not core Spec Kit commands. Set speckit_version to the version you actually test against.

Command 1: Explore Mode

Explore should be a thinking stance, not an early implementation command. Its whole job is to help a human think before the spec locks anything in.

Its contract:

• inspect the repository and any current feature artifacts when relevant
• surface assumptions, constraints, alternatives, risks, and unknowns
• do not write code
• do not silently rewrite specifications
• write an exploration document only after the user confirms
• end by recommending the next move: keep exploring, specify, or stop

A compact commands/explore.md:

---
description: "Explore a problem before committing to a feature specification."
---

# Adaptive Workflow: Explore

## Input

$ARGUMENTS

## Rules

1. Investigate relevant repository context before recommending a direction.
2. Separate observed facts, assumptions, and editorial recommendations.
3. Compare meaningful alternatives and expose their trade-offs.
4. Do not implement code.
5. Do not modify feature artifacts without explicit user confirmation.
6. Use an ASCII diagram when relationships are hard to scan in prose.

## Response

- Problem as currently understood
- Constraints and affected boundaries
- Alternatives worth weighing
- Risks and unknowns
- One recommended next move: continue exploring, run /speckit.specify, or stop

Should Explore write a file?

Default to conversation only, and persist a document only when the user asks. Automatically saving every brainstorm creates a new problem: throwaway ideas start to look like approved decisions. When exploration does reach a stable conclusion, write a short specs/<feature>/exploration.md that captures only the problem framing, key constraints, alternatives considered, and the open question or decision — nothing more.

Command 2: Alternatives-Review Mode

Explore is open-ended. Alternatives-review is the moment you decide on purpose — and record it. This is the piece Spec Kit has no home for today: a spec captures what you build, but not what you rejected and why.

Its contract:

• read the active spec (and exploration notes if present)
• compare at least two real options across the same criteria
• recommend one, but require a human to accept, change scope, or override with a written reason
• write exactly one artifact: specs/<feature>/reviews/alternatives-review.md
• never write code, and never mark the decision approved on its own

A compact commands/alternatives-review.md:

---
description: "Compare options and record the decision before implementation."
---

# Adaptive Workflow: Alternatives Review

## Input

$ARGUMENTS

## Steps

1. Read the active feature spec and any exploration notes.
2. Identify at least two serious alternatives (not one plan plus strawmen).
3. Score each against the same criteria; mark low-confidence scores.
4. Recommend one path and state the trade-offs it accepts.
5. Write only specs/<feature>/reviews/alternatives-review.md.
6. Leave the Decision field for a human. Do not implement code.

## Output

- Comparison table across shared criteria
- Recommended path and the trade-offs it accepts
- Rejected options with a one-line reason each
- Human decision: accept, reduce scope, or override with rationale

The referenced templates/alternatives-review-template.md:

# Alternatives Review: [feature]

## Decision Requested

[The concrete choice reviewers must make.]

## Options Compared

| Criterion            | Option A | Option B | Option C |
|----------------------|:--------:|:--------:|:--------:|
| Fit for the problem  |          |          |          |
| Implementation cost  |          |          |          |
| Migration / rollback |          |          |          |
| Operational risk     |          |          |          |
| Reversibility        |          |          |          |

## Recommendation

[Which option and why. Name the trade-off you are accepting.]

## Rejected Alternatives

- Option X — rejected because ... (reconsider if ...)

## Decision

- Status: Pending | Accepted | Accepted with changes | Rejected
- Decided by:
- Date:

This is deliberately different from “generate more documentation.” The artifact exists to support one named decision, with a comparison and an owner. On a rerun, keep the human-authored Decision block and only refresh the generated analysis above it. If you want the deeper prompt patterns for generating and challenging alternatives, see Using GitHub Spec Kit to Investigate Alternatives Before You Build.

Get the Commands Into a Repo

You already have the only thing that matters — the two command files above. There are two ways to make them live in a repository, and the right one depends only on how far the commands need to travel:

One repo, just trying it?   Ad-hoc — commit the files, install nothing
Many repos or a team?       Package as an extension

Ad-hoc: commit the command files directly (no install)

A Spec Kit slash command is just a Markdown file in your agent’s command directory. Spec Kit writes its own commands there when you run specify init, and a file you add by hand behaves the same way. So to run explore and alternatives-review in a single repo, drop the same Markdown straight into that directory — no manifest, no specify CLI:

.claude/commands/explore.md               # Claude Code
.cursor/commands/explore.md               # Cursor
.claude/commands/alternatives-review.md
.cursor/commands/alternatives-review.md

The file name becomes the command, so you get a plain /explore and /alternatives-review. You lose the speckit.adaptive-workflow. namespace, which is fine for one repo. Commit the files and everyone on that repo gets the commands on their next git pull. Spec Kit materializes commands in whichever agent directories it detects, using that agent’s format — Markdown, or TOML for some CLIs. Match the format your agent already uses.

If instead you want to reshape an existing Spec Kit artifact in one repo — say, shorten this project’s plan-template.md — use a project-local override rather than a new command:

.specify/templates/overrides/templates/plan-template.md

Overrides sit at the top of Spec Kit’s resolution stack and are read at runtime, so the change applies immediately with no install and no fork. That is the right tool for changing existing outputs; the agent command directory is the right tool for brand-new commands like these two.

Packaged: install as an extension (reuse across repos)

When the commands need to travel — several repos, a team, version pinning, and clean removal — wrap them in the extension.yml manifest shown earlier and install in development mode:

specify extension add --dev /path/to/spec-kit-adaptive-workflow
specify extension list

Packaging is what buys you the namespaced names, the specify extension list / remove lifecycle, versioning, and catalog distribution. It is worth it for standardization — and overkill for a single experiment.

Test the Behavior

Whichever route you took, run one happy path and confirm the behavior — not just that the commands appeared:

1. /explore "replace session storage"     (packaged: /speckit.adaptive-workflow.explore)
   -> conversation only, unless you approve a file
2. /alternatives-review
   -> writes specs/<feature>/reviews/alternatives-review.md with a Pending decision
3. /speckit.specify
   -> normal Spec Kit flow, now grounded by a recorded decision

The tests that actually matter:

The acceptance question is simple: does this addition improve the next human decision without adding more process than the change warrants?

Make the Output Files Leaner

A common complaint about Spec Kit is the opposite of a missing phase: for one small change it produces a pile of long files — spec.md, plan.md, research.md, data-model.md, contracts/, quickstart.md, tasks.md, and a checklist. That verbosity comes from the command instructions, not just the templates, so a shorter template alone will not fix it.

Trimming that output is a customization concern in its own right, with four levers — inline prompts, a lean template override, a trimmed command, and Lean/Standard/Governed routing by impact — so it now has a dedicated companion piece:

→ How to Make GitHub Spec Kit Produce Leaner Output

The short version: fix verbosity with a preset or project-local override (never an extension), budget each file, omit empty sections, link instead of copy, and only generate an artifact that changes a decision.

Connect Spec Kit to GitHub Issues and Projects

A third gap teams hit: Spec Kit’s tasks live in Git, but delivery is tracked in GitHub Issues and Projects, and the two drift apart. Spec Kit ships one bridge — /speckit.taskstoissues — but it is deliberately small. In v0.10.1 that command:

• requires an existing tasks.md
• reads the origin remote and refuses to proceed unless it is a GitHub URL
• uses the GitHub MCP server’s issue_write tool to create one issue per task

That is a useful start. It does not create a feature-level parent issue, sub-issue or blocking relationships, Project fields, stable requirement-to-issue IDs, or any rerun policy. Do not assume rerunning it is safe.

Real traceability is its own extension to build — call it github-traceability. It needs two commands and one canonical chain, stored in specs/<feature>/traceability.json:

/speckit.github-traceability.publish   -> dry-run, create/reconcile issues, set Project fields, persist a mapping
/speckit.github-traceability.status    -> read relationships, report gaps, write nothing remotely

Requirement R001 -> Task T001 -> Issue #381 -> PR #402 -> test/review evidence

What the GitHub MCP server gives you

As of July 2026, the GitHub MCP server’s issues toolset provides issue_write and sub_issue_write (the parent/sub-issue hierarchy). Both need the repo scope. GitHub Projects lives in a separate projects toolset (projects_list, projects_get, projects_write) that is not enabled by default. Turn it on with --toolsets default,projects (or the X-MCP-Toolsets header), and grant read:project for reads and project for writes.

One limit shapes the design: there is no issue-dependency (blocking) write tool. sub_issue_write covers hierarchy, not dependencies, so “blocked by” links need the GitHub CLI or REST API.

A publish command can therefore create issues, nest sub-issues, and set Project fields through MCP, but falls back to gh for blocking links. Keep Git-tracked artifacts as the source of truth for intent. Use issues as execution records and Projects as the operational view — never copy the whole spec into an issue.

Before You Install Someone Else’s Extension

If you pull an extension from a community catalog instead of writing your own, treat it as a third-party dependency. Catalog inclusion is discovery metadata, not a code audit — Spec Kit maintainers verify catalog metadata but do not review, endorse, or support extension code. Before trusting one, read its command files and manifest for what the agent is instructed to do, which tools it requests, and where it writes. If it fails any of those checks, do not install it.

A Practical Rollout

Whichever of these you adopt — the two commands, leaner output, or GitHub traceability — roll out one behavior at a time rather than shipping the whole layer at once:

1. Baseline — name the real pain: missing exploration, no recorded decision, verbose output, or drift from GitHub. Fix that one first.
2. Local pilot — try it ad-hoc in one sandbox repo (a command file or a project-local override) before packaging anything.
3. Output review — compare artifacts from a few representative changes; keep what improves a decision, cut the rest.
4. Failure testing — check the ugly paths: ambiguous input, missing files, reruns, conflicting presets, removal, and rollback.
5. Team approval — for every added command or artifact, name its owner, trigger, output, and the decision it supports.
6. Curated distribution — only then package it and publish a reviewed version through an install-enabled catalog.
7. Measure and prune — remove commands and documents that do not change decisions.

A few signals worth watching:

• share of generated sections reviewers delete as irrelevant
• clarification questions raised before planning
• review conditions caught before implementation
• time spent reconciling contradictory artifacts

These do not prove causation, but they show whether the workflow is getting clearer or just larger.

Where to Stop

The temptation with an extensible tool is to keep adding. Resist it. Two phases fix the real gap:

missing thinking phase   -> explore command
missing decision record  -> alternatives-review command

Trimming verbose output and routing a change to the right tier (the companion guide above) are worth doing because they remove or right-size process. Building a specialist-review pipeline or GitHub Issues/Projects traceability is different: each is a legitimate but separate problem that deserves its own decision, not a reason to bloat this extension. Add one command, test its failure modes, and keep it only if the resulting artifact helps a human make the next decision.

That is the useful promise of Spec Kit extensions: not more commands and not more documents, but the two missing phases that make the spec that follows a better one.

Sources

• GitHub Spec Kit v0.10.1 README: released workflow, supported integrations, and version context.
• Spec Kit v0.10.1 Extensions Reference: extension search, installation, configuration, and command management.
• Spec Kit v0.10.1 Extension Development Guide: manifest schema, namespaced commands, local testing, and security guidance.
• Spec Kit v0.10.1 Extensions README: curated catalog model and the community catalog trust boundary.
• Spec Kit Presets Reference: the customization resolution stack, project-local overrides (.specify/templates/overrides/), and how commands are materialized into agent directories at install time versus templates resolved at runtime.
• Spec Kit v0.10.1 core command templates: the plan command’s instruction to generate research.md, data-model.md, contracts/, and quickstart.md, and the specify command’s requirements checklist — the source of output verbosity that a lean preset or override must trim.
• Spec Kit v0.10.1 tasks-to-issues command: the tasks.md prerequisite, GitHub remote validation, and one-issue-per-task creation via the MCP issue_write tool.
• Official GitHub MCP server: current issue_write / sub_issue_write / projects_* tool capabilities, the default toolsets (the projects toolset is not among them), and OAuth scope requirements (repo, read:project, project).
• OpenSpec repository: the change-based workflow whose explore and decision-recording phases inspired these two commands.