Problem Statement
Spec Kit's SDD pipeline starts at specify — a user's idea is fed directly as $ARGUMENTS and immediately structured into spec.md. There is no phase for thinking through the problem before committing to a specification. This forces premature structuring: vague ideas get squeezed into spec templates, and the exploration that should happen before specification (questioning assumptions, comparing approaches, reading the codebase) either gets lost or leaks into the specify command's already-long template.
The result is lower-quality specs that miss hidden complexity, skip alternative approaches, and require more downstream rework.
Proposed Solution
Add a new core command speckit.explore — a pre-specify thinking phase that acts as a "thinking partner" stance rather than a procedure-driven workflow.
Key characteristics:
- No file artifacts — explore produces no directories, no spec files, runs no scripts. Its output is a structured exploration summary handed off to
specify via the existing handoff mechanism.
- Stance + repertoire, not numbered steps — the template uses a two-layer structure: a stance (curious, open, visual, grounded, patient, assumption-challenging) and a repertoire of exploratory actions (problem-space exploration, codebase investigation, option comparison, visualization, risk surfacing) that the AI calls upon as context demands — not a 1→2→3→4→5 procedure.
- Convergence detection — the AI detects when thinking has crystallized and proactively offers handoff to
specify. The user can accept (→ specify) or reject (→ continue exploring).
- Structured summary — on handoff, explore generates a four-part summary: framed problem, key findings, chosen direction, and rejected paths (prevents the spec from re-entertaining eliminated options).
- Pipeline extension — the SDD pipeline becomes:
explore → specify → clarify → plan → tasks → implement. Explore is an optional entry point; users can still invoke specify directly.
The change is purely additive: one new template file (templates/commands/explore.md), no changes to existing templates, no Python code changes, no new scripts.
Alternatives Considered
- Extension-based (
extensions/explore/) — rejected because explore is a core SDD phase concept, not an opt-in extension. Making it an extension means users who don't install it miss a fundamental part of the pipeline.
- Preset-only — rejected because it would make explore unavailable to projects that don't use that preset, fragmenting the SDD pipeline.
- Expand specify's template — rejected because specify's template is already long; adding exploratory thinking to it would conflate two distinct phases (thinking vs. structuring).
Component
Specify CLI (initialization, commands)
AI Agent
All agents
Use Cases
- Vague idea to structured spec — A user has a rough feature idea ("we need better search") but hasn't thought through the problem framing. Explore helps them clarify what they are actually solving before committing to a spec.
- Codebase investigation before spec — A user wants to add a feature but needs to understand existing patterns, integration points, and hidden complexity before writing the spec. Explore grounds the discussion in the actual codebase.
- Comparing approaches — Multiple viable architectures surface during thinking. Explore helps build comparison tables and tradeoff matrices, then captures rejected paths so the spec does not re-entertain them.
- Challenging assumptions — A user assumes they need X, but the codebase already has Y. Explore surfaces this: "You said you need X, but the codebase already has Y — would that work?"
Acceptance Criteria
Additional Context
I have a working implementation ready as a PR. The explore template adapts spec-kit's existing command skeleton (frontmatter, Pre-Execution Checks, Done When) while replacing the procedural Outline with a stance + repertoire structure.
The design was informed by a structured exploration process, which surfaced the key design tension: explore is a stance, not a workflow. Compressing it into numbered steps would destroy its value. The template resolves this by keeping the skeleton (for structural consistency with other commands) but replacing the procedural Outline with a non-sequential repertoire.
This is a large change (new template, 230 lines), so per the Contributing guidelines I am opening this issue for discussion before submitting a PR. Happy to adjust the design based on maintainer feedback.
Problem Statement
Spec Kit's SDD pipeline starts at
specify— a user's idea is fed directly as$ARGUMENTSand immediately structured intospec.md. There is no phase for thinking through the problem before committing to a specification. This forces premature structuring: vague ideas get squeezed into spec templates, and the exploration that should happen before specification (questioning assumptions, comparing approaches, reading the codebase) either gets lost or leaks into the specify command's already-long template.The result is lower-quality specs that miss hidden complexity, skip alternative approaches, and require more downstream rework.
Proposed Solution
Add a new core command
speckit.explore— a pre-specify thinking phase that acts as a "thinking partner" stance rather than a procedure-driven workflow.Key characteristics:
specifyvia the existing handoff mechanism.specify. The user can accept (→ specify) or reject (→ continue exploring).explore → specify → clarify → plan → tasks → implement. Explore is an optional entry point; users can still invokespecifydirectly.The change is purely additive: one new template file (
templates/commands/explore.md), no changes to existing templates, no Python code changes, no new scripts.Alternatives Considered
extensions/explore/) — rejected because explore is a core SDD phase concept, not an opt-in extension. Making it an extension means users who don't install it miss a fundamental part of the pipeline.Component
Specify CLI (initialization, commands)
AI Agent
All agents
Use Cases
Acceptance Criteria
templates/commands/explore.mdexists with the stance + repertoire structurespecify integration install <agent>installs explore alongside other core commandsspecify(linear pipeline)spec-driven.mdmentions explore as an optional pre-specify phaseAdditional Context
I have a working implementation ready as a PR. The explore template adapts spec-kit's existing command skeleton (frontmatter, Pre-Execution Checks, Done When) while replacing the procedural Outline with a stance + repertoire structure.
The design was informed by a structured exploration process, which surfaced the key design tension: explore is a stance, not a workflow. Compressing it into numbered steps would destroy its value. The template resolves this by keeping the skeleton (for structural consistency with other commands) but replacing the procedural Outline with a non-sequential repertoire.
This is a large change (new template, 230 lines), so per the Contributing guidelines I am opening this issue for discussion before submitting a PR. Happy to adjust the design based on maintainer feedback.