Spec Gen

spec-gen

Spec Refinement Orchestrator for Claude Code.

Enforces a guided, one-step-at-a-time specification refinement workflow that converts a vague idea into an implementation-grade spec with explicit constraints, tracked unknowns, and cited context — without requiring you to write a complete spec upfront.

What It Does

1. Hard refusal gate — Refuses all implementation actions until the spec is approved
2. Structured interview — One question per turn, tracks assumptions, converts them to explicit questions
3. Research phase — Spawns parallel research agents (Notion, Slack, Web) once the brief is ready
4. Distillation — Synthesizes research into decision-relevant context
5. Conflict surfacing — If sources disagree, asks the user (never silently chooses)
6. Spec generation — Progressive disclosure: single SPEC.md for small scope, linked sub-specs for larger
7. Open questions tracker — Continuously maintained authoritative list
8. Approval checklist — Derived from spec schema; implementation blocked until approved

Usage

/spec-gen:refine                          # Start fresh from interview
/spec-gen:refine path/to/seed-file.md     # Start with seed input
/spec-gen:refine "brief idea description" # Start with text

The workflow resumes automatically if a spec/ directory already exists.

Artifacts Produced

All files are written to spec/ in the current working directory:

File	Purpose
BRIEF.md	One-page seed context and index
SPEC.md	Full specification (links to sub-specs if needed)
OPEN_QUESTIONS.md	Authoritative list of unresolved questions
RESEARCH/NOTION.md	Findings from Notion search
RESEARCH/SLACK.md	Findings from Slack search
RESEARCH/WEB.md	Findings from web research
RESEARCH/DISTILLED_CONTEXT.md	Synthesized decision-relevant context

Prerequisites

For full research capability, these MCP servers should be configured:

• Notion MCP — for searching your Notion workspace
• Slack MCP — for searching Slack channels and threads
• Web search works via Claude Code's built-in WebSearch tool

The plugin works without MCP integrations — research agents will report "no results" and the workflow continues with manual context.

Components

• 1 skill: spec-refinement — core workflow knowledge
• 1 command: refine — entry point
• 5 agents: notion-researcher, slack-researcher, web-researcher, distiller, open-questions-tracker

Installation

claude --plugin-dir /path/to/spec-gen