[Feature]: Guided SDD entry point — single intent to full workflow (speckit.go)

[LucianoDPerez]

Problem Statement

Problem Statement

Goal: reduce onboarding friction so a new user can drive a first feature through SDD with one known entry point instead of memorizing 7+ slash commands and when to use each optional step.

Spec Kit's SDD workflow is powerful but has a steep learning curve:

1. The README quick start teaches seven manual slash-command steps (/speckit.constitution → specify → plan → tasks → implement, plus optional clarify / analyze).
2. The workflow engine (specify workflow run speckit) already orchestrates part of the cycle, but it is easy to miss, does not include constitution / clarify / analyze in the bundled workflow, and is CLI-centric rather than a single agent-facing entry point.
3. Handoffs in command frontmatter help in some IDEs but still require the user to click through each transition manually.
4. Community extensions (Fleet, Conduct, Onboard, agent-orchestrator) and Community Friends (Spec Kit Assistant, SpecKit Companion) address pieces of this, but there is no official, lightweight, opt-in "start here" path in core that maps one user intent ("build X") to the right command sequence.

This gap shows up in roadmap themes ("experience simplification", end-to-end automation — see newsletters and related discussion in #1966, #1192) and in external reviews citing ceremony/overhead.

Per CONTRIBUTING.md, I'd like to align on direction here before opening a PR, since this touches templates and possibly CLI UX.

---

Proposal

Add an optional guided entry facade (composition layer) on top of existing Spec Kit commands/skills and the WorkflowEngine.

This is not a new SDD engine. The entry layer does not implement specify/plan/tasks/implement logic itself. It only:

• Accepts user intent in natural language
• Inspects project state (artifacts, active feature, missing constitution, etc.)
• Dispatches to already-installed Spec Kit commands or skills for the active integration (e.g. /speckit.specify, /speckit.plan, or the equivalent skill names in Codex/Cursor skills mode)
• Decides order, when to pause, and when to resume mid-flow
• Defers all phase behavior, scripts, hooks, and artifact formats to the existing commands

Power users keep full control via individual /speckit.* commands, presets (lean), extensions, and custom workflows.

Architecture (facade over existing commands)

flowchart TB
  User["User intent"] --> Entry["/speckit.go or specify run"]
  Entry --> Facade["Guided entry facade"]
  Facade --> Router["State detection + path selection"]
  Router --> C1["/speckit.constitution"]
  Router --> C2["/speckit.specify"]
  Router --> C3["/speckit.clarify optional"]
  Router --> C4["/speckit.plan"]
  Router --> C5["/speckit.tasks"]
  Router --> C6["/speckit.analyze optional"]
  Router --> C7["/speckit.implement"]
  C1 --> Artifacts["Existing specs/ scripts / hooks"]
  C2 --> Artifacts
  C4 --> Artifacts
  C5 --> Artifacts
  C7 --> Artifacts
  Facade -.->|"CLI path"| WFE["WorkflowEngine speckit-full"]
  WFE -.->|"dispatches same commands"| C2

Loading

Layer	Responsibility
Guided entry facade (/speckit.go, optional specify run)	Routing, sequencing, pause/resume, onboarding-oriented defaults
Existing /speckit.* commands / skills	All SDD phase logic and artifacts (unchanged)
WorkflowEngine (optional CLI complement)	Same sequence with persisted runs and review gates via specify workflow run

User-facing entry (agent):

• New optional command: /speckit.go (name open to discussion — alternatives: speckit.pipeline, speckit.run)
• Input: natural-language feature intent, e.g. Build a photo album organizer with drag-and-drop
• Behavior:
  • Inspect project state (e.g. missing memory/constitution.md, active feature under specs/, existing artifacts)
  • Select the appropriate path (full SDD vs lean vs resume mid-flow)
  • Invoke existing commands/skills in order (via the agent's native slash-command or skill mechanism), pausing only when a step genuinely needs user input (clarification questions, critical analyze findings, review gates)
  • Preserve all artifacts under specs/ and existing scripts/hooks — no parallel artifact model

User-facing entry (CLI, optional complement):

• specify run "<intent>" as a documented alias for running an extended catalog workflow with the same inputs (reusing specify workflow run, not a parallel execution engine)

Workflow complement:

• Extend or add a catalog workflow (e.g. speckit-full) that builds on workflows/speckit/workflow.yml:
  • Optional constitution when missing
  • specify → optional clarify → plan → tasks → optional analyze → implement
  • Reuse existing human review gates where appropriate

---

Non-Goals

• Not a heavy multi-agent orchestrator (Fleet / Conduct style coordination files)
• Not reimplementing SDD phases inside the entry command (no mega-prompt that replaces specify.md / plan.md / etc.)
• Not replacing /speckit.* or the modular extension/preset model
• Not silent auto-trigger on every chat message in core (opt-in explicit invocation preferred for predictability and token cost)
• Not duplicating VS Code Friends (Assistant / Companion) — core should stay agent-agnostic; documentation cross-links are fine

---

Prior Art (in-repo and community)

Area	Reference
Prior pipeline proposal	#1966 (closed; proposed /speckit.pipeline meta-command)
User-built phase runner	#1192 (closed; orchestrator/run_phase.py pattern)
Built-in partial workflow	workflows/speckit/workflow.yml (specify → plan → tasks → implement)
Ceremony reduction	presets/lean/
Workflow engine	src/specify_cli/workflows/engine.py
Community onboarding / routing	Onboard, Intelligent Agent Orchestrator, Fleet Orchestrator extensions
Visual orchestration	Spec Kit Assistant, SpecKit Companion (Friends)

---

Proposed MVP (after maintainer agreement)

1. templates/commands/go.md — facade command: state detection + ordered dispatch to existing commands/skills (no new phase templates)
2. workflows/speckit-full/workflow.yml (or extend speckit) — CLI complement: full cycle with conditional optional steps, same dispatch targets as today
3. Docs: README / docs site — "Quick path" (one entry) vs "Advanced path" (individual /speckit.*, lean preset, custom workflows)
4. Tests: workflow loading/validation in tests/test_workflows.py

I am happy to submit a focused MVP PR once the preferred shape (facade command vs workflow-only, core vs extension catalog, constitution handling) is agreed.

---

Open Questions for Maintainers

1. Surface area: Agent meta-command only, CLI workflow only, or both?
2. Command name: speckit.go, speckit.pipeline, or something else?
3. Constitution: Required in the default guided path, optional when missing, or always manual?
4. Shipping vehicle: Bundled in core vs community extension first?
5. Friends overlap: Document alongside Assistant/Companion, or integrate/reference explicitly?
6. Auto-trigger: Should core support any implicit routing, or stay strictly opt-in?

---

Component

• CLI (specify)
• Templates / commands
• Workflows
• Documentation
• Other

---

AI Disclosure

• I did not use AI assistance for this issue
• I did use AI assistance (describe below)

This issue was drafted with AI assistance for structure and wording; the problem framing, proposal scope, and willingness to implement an MVP are my own.

Proposed Solution

Add an optional guided entry facade (composition layer) on top of existing Spec Kit commands/skills and the WorkflowEngine — not a new SDD engine.

What it does (facade only):

• Accepts one natural-language intent (e.g. “Build a photo album organizer with drag-and-drop”)
• Inspects project state (constitution present?, active feature under specs/, existing artifacts)
• Dispatches to already-installed /speckit.* commands or skills for the active integration, in the right order
• Pauses only when a step needs human input (clarify, critical analyze, review gates)
• Does not reimplement specify/plan/tasks/implement logic

User-facing entry points:

1. Agent: /speckit.go (name open to discussion) — single slash command for onboarding
2. CLI (optional): specify run "<intent>" as an alias over specify workflow run (no parallel engine)

Workflow complement: catalog workflow speckit-full extending workflows/speckit/workflow.yml with optional constitution, clarify, and analyze.

flowchart TB
  User["User intent"] --> Entry["/speckit.go or specify run"]
  Entry --> Facade["Guided entry facade"]
  Facade --> Router["State detection + path selection"]
  Router --> Commands["Existing /speckit.* commands & skills"]
  Commands --> Artifacts["specs/ scripts hooks"]

### Alternatives Considered

_No response_

### Component

Specify CLI (initialization, commands)

### AI Agent (if applicable)

None

### Use Cases

_No response_

### Acceptance Criteria

_No response_

### Additional Context

_No response_

Loading

[lucianoperez-cmyk]

Relationship to prior work (overlap check)

I did a pass over open/closed issues, the community catalog, built-in workflows, and external repos to make sure this proposal is scoped distinctly. Sharing here so maintainers don't have to re-triage.

Not a duplicate of any open issue

I did not find another open issue asking for the same thing. The closest match is closed work and community tooling (below).

Strongest overlap: #1966 / PR #1977

#1966 describes essentially the same friction (manual step-by-step /speckit.* invocations) and proposed /speckit.pipeline to auto-progress through specify → clarify → plan → tasks → analyze → implement, pausing only when user input is required.

Maintainer direction there was to ship as an extension. PR #1977 moved the implementation to extensions/pipeline/, but it was closed without merge and I don't see a pipeline entry in extensions/catalog.community.json today.

How this issue differs / what it reopens:

Area	#1966 / PR #1977	This proposal (#2625)
Shipping vehicle	Extension (per review)	Asks maintainers to align on core facade vs extension after the extension path stalled
Entry surfaces	Agent command (speckit.pipeline)	Agent (/speckit.go) plus optional CLI complement (specify run → workflow)
State handling	Linear run from feature description	State detection + resume mid-flow (existing artifacts / active feature)
Constitution	Not emphasized	Optional inclusion when missing
CLI workflow	Not in scope	speckit-full extending built-in workflows/speckit (adds constitution / clarify / analyze to the partial cycle already shipped)

I'm not asking to reimplement SDD phases—same non-goals as in the issue body: thin facade that dispatches existing commands/skills.

Community implementations (outside the tracker)

The March newsletter already notes community pipeline work. Relevant prior art not filed as spec-kit issues:

• TechZi/speckit-pipeline — gated coordinator across specify → clarify → plan → tasks → analyze → checklist → implement; resume via specs/<feature>/.speckit-pipeline-state.json; multi-tool (Codex, Claude Code, Cursor, Qoder). Closest external match to the "one feature, disciplined order, can resume later" shape.
• Hacklone/lazy-spec-kit — heavier "one command" E2E automation (auto-clarify, multi-agent review/fix). Different weight class; useful as contrast for "lightweight opt-in facade" vs "batteries-included framework."
• iandeherdt/speckit-pipeline — design/build loops with browser verification; adjacent but not the same "first SDD cycle onboarding" problem.

Happy to coordinate with or reference an existing community pipeline rather than invent a parallel command name—see open question below.

Partial overlap already in core (complementary)

• specify workflow run speckit — already automates specify → plan → tasks → implement. This proposal's speckit-full extends that path (optional constitution, clarify, analyze), not a second engine.
• presets/lean — ceremony reduction, not orchestration.
• Catalog extensions (Onboard, agent-orchestrator, Fleet, Conduct, orchestrator) — called out in the issue; they solve onboarding slices, routing, or multi-agent / cross-feature orchestration, not a single official "start here" entry for the default SDD cycle.

Issues that are adjacent but not duplicates

• #1174 — smaller-task workflow (tinySpec); complementary.
• #2238 — cross-feature orchestration (closed); different problem.
• #1192 — external phase runner pattern (closed); different approach.
• #2342 / #2216 — workflow/step catalog infrastructure, not user-facing guided entry.

Additional open question for maintainers

Community coordination: Should core adopt, document, or officially coordinate with an existing community pipeline (e.g. TechZi) instead of adding a new bundled command—or is a thin official opt-in facade still warranted for discoverability and docs ("Quick path" vs "Advanced path")?

---

Still happy to implement a focused MVP once direction is agreed—whether that lands in core templates, an extended speckit-full workflow, a catalog extension, or a thin wrapper that points at existing community tooling.