Build a complete spec through interactive conversation so gather produces plans that execute cleanly.
From gignpx claudepluginhub gregrossdev/gigThis skill uses the workspace's default tool permissions.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Read .gig/STATE.md and display:
Version: {version} | Iteration: {iteration} | Status: {status}
Check if .gig/ exists in the current project root.
If NOT present:
Say: "No gig context found. Run /gig:init first." STOP.
If present:
Read .gig/STATE.md for current position.
If status is GATHERING, IMPLEMENTING, or IMPLEMENTED: Say: "An iteration is in progress. Complete it before starting a new spec." STOP.
If status is SPECCED:
.gig/SPEC.md and check the Status column in the Requirements table.COVERED:
.gig/SPEC.md to .gig/iterations/SPEC-completed-{today's date}.md.gig/iterations/SPEC-completed-{date}.md. Starting fresh elicitation."NOT COVERED:
.gig/SPEC.md to .gig/iterations/SPEC-partial-{today's date}.md, then proceed to Step 2.If status is IDLE, GOVERNED, or SPECING (resuming): Proceed.
Read these files for background:
.gig/ARCHITECTURE.md — project structure, stack, patterns.gig/ROADMAP.md — current milestone, completed iterations.gig/BACKLOG.md — backlog ideas that might inform the spec.gig/ISSUES.md — open/deferred issues.gig/SPEC.md — if resuming a draft spec.gig/MVP.md — if present, the MVP product discovery documentIf .gig/SPEC.md exists and has content beyond the template, present it:
"Found existing spec draft. Resuming from where you left off."
If .gig/MVP.md exists and has content beyond the template, note it for use in Step 3:
"Found MVP discovery document. Will use it to pre-populate stories and requirements."
This is an interactive conversation. Claude guides the user to articulate what they want clearly enough that gather can make decisions without assumptions.
Update .gig/STATE.md:
SPECINGIf user says "baseline" or "reverse-engineer" (or provided args containing these words):
Jump to the Baseline from Iterations flow below.
If user says "mvp" (or provided args containing "mvp"):
Jump to the MVP Product Discovery flow below.
If user provided other args: Use the args as the starting topic. Begin with: "Let's build a spec for {topic}. I'll help you define what you want so gather can execute it cleanly."
If no args and the project has completed iterations (existing project):
Launch 3 Explore agents in parallel (Agent tool, subagent_type "Explore"), one per profile:
.gig/ARCHITECTURE.md, package/config files..gig/ISSUES.md..gig/ROADMAP.md, .gig/BACKLOG.md, .gig/ISSUES.md.Synthesize findings from all 3 agents into a unified project assessment before presenting directions.
Present a project assessment and propose directions:
### Your Project Now
{2-3 sentence assessment of current state and capabilities}
### Suggested Directions
1. **{Direction}** ({type: refactor / feature / enhancement / testing / docs}) — {why this matters now}
2. **{Direction}** ({type}) — {why}
3. **{Direction}** ({type}) — {why}
Pick a direction to spec out, combine them, or tell me what you have in mind.
The user picks a direction (or states their own), then elicitation continues normally.
If no args and new project (no completed iterations): Ask ONE question: "What are you trying to build or accomplish?"
If .gig/MVP.md was loaded in Step 2 and has content beyond the template (and this is NOT an MVP or baseline flow):
Before starting normal elicitation, pre-populate from the MVP document:
Extract story candidates from MVP Core Flows — each flow maps to a candidate user story. Present them as draft US-XXX entries for the user to confirm or adjust.
Extract requirement candidates from MVP Screens and Data Model — each screen maps to requirements about what it must display/do, each entity maps to data requirements. Present them as draft REQ-XXX entries.
Surface Open Questions from MVP.md: "These items were flagged as open questions during MVP discovery — let's resolve them now before building the spec:"
Present the pre-populated draft: "Found MVP discovery document. Pre-populated {N} story candidates and {M} requirement candidates from your flows and screens. Let's refine them."
Then continue with normal elicitation — the user adjusts, adds, removes, and the standard elicitation behaviors apply.
For existing projects that want to capture what's already been built as a spec. This reverse-engineers user stories and requirements from iteration history.
Read all archived iterations: Scan .gig/iterations/ for completed iteration archives. For each, read PLAN.md (batch details, acceptance criteria) and DECISIONS.md (what was decided and why).
Read current state: Read .gig/ARCHITECTURE.md, .gig/ROADMAP.md (completed milestones and iterations).
Launch 3 Explore agents in parallel (Agent tool, subagent_type "Explore"), one per profile:
Present the baseline draft spec:
### Baseline Spec (reverse-engineered from {N} iterations)
## Stories
| ID | Story | Priority | Status |
|----|-------|----------|--------|
| US-001 | As a ..., I want ..., so that ... | core | DELIVERED |
| US-002 | ... | core | DELIVERED |
| ... | ... | ... | ... |
## Requirements
| ID | Story | Description | Acceptance Criteria | Status | Iteration |
|----|-------|-------------|---------------------|--------|-----------|
| REQ-001 | US-001 | ... | ... | COVERED | v0.X.Y |
| REQ-002 | US-001 | ... | ... | COVERED | v0.X.Y |
| ... | ... | ... | ... | ... | ... |
All {count} requirements are marked COVERED — these represent what's already built.
"This is what your project has built so far. Review the stories and requirements — adjust anything that's wrong."
"To add NEW work, describe what you want next. I'll add new stories and requirements with status NOT COVERED. Govern will track them going forward."
NOT COVERED. Then continue to the Lock Gate (Step 4).A structured interview that produces .gig/MVP.md — a product discovery document with flows, screens, data model, and boundaries. Use this for new projects or existing projects that need to think through the product before coding.
If the project has existing context (.gig/ARCHITECTURE.md has content beyond the template, or .gig/ROADMAP.md has completed iterations): Read both files before starting. Reference existing architecture and capabilities when asking questions — the interview should build on what exists, not ignore it.
If .gig/MVP.md already exists and has content beyond the template: Present it and ask: "Found existing MVP discovery document. Resume editing or start fresh?" If resume, pre-populate the running draft from the existing file. If fresh, proceed with a blank slate.
The interview uses clustered questions — each section presents 2-4 related questions at once. After the user answers, show a running draft of that section for course-correction before moving to the next.
Handling unknowns: When the user says "I don't know" or is uncertain, ask ONE follow-up to help them think through it (e.g., "If you had to pick, would it be more like X or Y?"). If still uncertain after the follow-up, add it to the Open Questions section and move on.
Handling multiple user types: When the user identifies multiple user types in Section 1, interview all types together. Annotate flows and screens with which role performs/sees them. Shared elements are noted as shared; role-specific elements are tagged with the user type.
Ask as a cluster:
After answers, present running draft:
### MVP Draft (Section 1/7 complete)
## Vision
**Product:** {elevator pitch}
**Target Users:** {user types}
**Problem:** {problem statement}
**What exists today:** {current state}
Ask as a cluster:
Use the inspiration answers to ground follow-up questions in later sections. For example, if the user says "like Trello but for X," ask about differences from Trello when discussing flows and screens.
After answers, update running draft adding:
## Inspiration
| Product | Borrow | Avoid |
|---------|--------|-------|
| {product} | {what to borrow} | {what to avoid} |
Ask as a cluster:
If multiple user types were identified in Section 1, ask: "Which user type performs each flow?"
For each flow described, generate a Mermaid flowchart:
flowchart TD
A[{first step}] --> B[{second step}]
B --> C{Decision point}
C -->|Option 1| D[{outcome}]
C -->|Option 2| E[{outcome}]
If a flow is role-specific, add a comment: %% Role: {user type}
After answers, update running draft with all flows and their Mermaid diagrams.
Ask as a cluster:
Generate a screen inventory table:
| Screen | Purpose | User Types |
|--------|---------|------------|
| {name} | {what it does} | {all / specific role} |
For each key screen, generate an ASCII mockup showing rough layout:
### {Screen Name}
{Brief description of purpose and what the user does here.}
┌─────────────────────────────────┐
│ {Header / Nav} │
├─────────────────────────────────┤
│ ┌───────────┐ ┌─────────────┐ │
│ │ {Section} │ │ {Section} │ │
│ │ {content} │ │ {content} │ │
│ └───────────┘ └─────────────┘ │
├─────────────────────────────────┤
│ {Actions / Footer} │
└─────────────────────────────────┘
After answers, update running draft with screen inventory and mockups.
Ask as a cluster:
Generate an entity table:
| Entity | Key Attributes | Relationships |
|--------|---------------|---------------|
| {name} | {attr1, attr2, ...} | {belongs to X, has many Y} |
For stateful entities, generate Mermaid state diagrams:
stateDiagram-v2
[*] --> {initial state}
{state1} --> {state2}: {trigger}
{state2} --> {state3}: {trigger}
After answers, update running draft with entity table and state diagrams.
Ask as a cluster:
If the user is uncertain, push once: "Think about it from the user's perspective — what would make them come back a second time?" If still uncertain, flag as open question.
After answers, update running draft with metrics.
Ask as a cluster:
Surface all items flagged as open questions during earlier sections: "During our conversation, these items were flagged as open questions: {list}. Want to resolve any of them now, or keep them flagged for spec?"
After answers, update running draft with boundaries, constraints, and final open questions list.
After EACH section, present the full accumulated MVP.md draft so far:
### MVP Draft (Section {N}/7 complete)
{Full accumulated content from all completed sections}
Do NOT write to .gig/MVP.md during the interview — keep the draft in the conversation. Only write on lock.
After all 7 sections are complete, present the full MVP.md document. Do not abbreviate, inline, or collapse into prose.
Then ask:
Does this capture your MVP vision?
- "lock" / "approve" — write MVP.md and continue to spec.
- "change X" — adjust specific sections before locking.
- "not yet" — continue refining (go back to any section).
STOP. Do not write MVP.md. Wait for approval.
Once the user approves:
Write .gig/MVP.md with the locked content. Overwrite any existing draft.
Update .gig/STATE.md:
SPECCEDDerive documentation needs from MVP.md:
Read the just-written MVP.md and .gig/ARCHITECTURE.md (if populated). For each section, determine if additional documentation beyond the minimum set (README, CHANGELOG, LICENSE) would help users of this project:
Do NOT use a fixed mapping. Read the actual content and reason about what docs would help. The above are examples, not rules.
Write .gig/DOCS.md with the derived documentation plan:
scaffoldednot-started, noting which MVP section or ARCHITECTURE.md field informed the needtemplates/docs/ (look in ${CLAUDE_PLUGIN_ROOT}/templates/docs/ then ~/.claude/templates/docs/) to the project rootPresent the documentation plan:
"Based on your MVP, this project needs these docs beyond the basics:"
- {doc} — {reason} (template scaffolded)
- {doc} — {reason} (template scaffolded)
"Documentation plan written to
.gig/DOCS.md. Govern will track freshness."
Say:
"MVP discovery locked. Run
/gig:specto build the detailed spec from this MVP — spec will pre-populate stories and requirements from your flows and screens.""Or run
/gig:gatherto plan implementation directly if the MVP is straightforward enough."
After writing MVP.md and DOCS.md, STOP. Do not auto-transition to spec elicitation. The user decides the next step.
During the elicitation conversation, use run_in_background to launch research agents when the user mentions topics that benefit from investigation. This keeps the conversation flowing while research completes.
When to launch:
When to collect:
Do NOT block the conversation waiting for background agents. Ask the next question while research runs.
Claude's job is to draw out what the user knows but hasn't articulated:
User Stories:
Requirements (derived from stories):
Constraints:
Clarifications:
After each substantive exchange, present the updated spec draft so the user can see it taking shape. Use the SPEC.md format:
### Current Draft
**Stories:** {count}
**Requirements:** {count}
**Constraints:** {count}
{Show the most recently added/changed items}
Do NOT write to .gig/SPEC.md during elicitation — keep the draft in the conversation. Only write on lock.
Keep asking questions until:
If the user seems done but gaps remain, surface them: "Before locking, I notice {gap}. Want to address it or mark it out of scope?"
Present the complete spec in full. Do not abbreviate, inline, or collapse into prose.
Present the entire draft spec in SPEC.md format:
# Spec
## Stories
| ID | Story | Priority | Scope Notes | Status |
|----|-------|----------|------------|--------|
| US-001 | As a ..., I want ..., so that ... | core | ... | NOT COVERED |
| ... | ... | ... | ... | ... |
## Requirements
| ID | Story | Description | Acceptance Criteria | Priority | Dependencies | Status | Iteration |
|----|-------|-------------|---------------------|----------|-------------|--------|-----------|
| REQ-001 | US-001 | ... | ... | must | — | NOT COVERED | — |
| ... | ... | ... | ... | ... | ... | ... | ... |
## Constraints
- ...
## Out of Scope
- ...
## Clarifications
- Q: ... → A: ...
Then ask:
If gather executes this spec perfectly, does the result match what you have in your head?
- "lock" / "approve" — write the spec and mark it ready for gather.
- "change X" — adjust specific items before locking.
- "not yet" — continue elicitation (go back to Step 3).
STOP. Do not write SPEC.md. Do not proceed to gather. Wait for approval.
Once the user approves:
Write .gig/SPEC.md with the locked spec content. Overwrite any existing draft.
Update .gig/STATE.md:
SPECCEDSay:
"Spec locked. Run
/gig:gatherto start making decisions — gather will trace every decision back to these requirements.""To change the spec later, edit
.gig/SPEC.mdand re-run/gig:gather."