| name | spec-driven-ideation |
| description | Transform business ideas into structured requirements through guided discovery with structural anti-skip enforcement (Execute-Verify-Gate pattern). Applies per-phase reference loading, checkpoint persistence, and artifact verification to every step of the 7-phase ideation process. Prevents token optimization bias through lean orchestration. Use when users say "I have a business idea", "help me define requirements", "let's explore what to build", or runs /ideate. Do NOT use when user wants to brainstorm a vague problem (use spec-driven-brainstorming) or wants a business plan directly (use planning-business).
|
| allowed-tools | ["Read","Write","Edit","Glob","Grep","ask the user","Task","Skill"] |
| model | opus |
| effort | High |
| version | 1.0.0 |
| topics | requirements, ideation, discovery, spec-driven, anti-skip, elicitation |
Spec-Driven Ideation
Transform business ideas into structured, actionable requirements through guided interactive questioning with structural anti-skip enforcement.
Output: devforgeai/specs/requirements/{project-name}-requirements.md (YAML per F4 schema)
Feeds Into: /create-solution-architecture command for epic generation, /create-system-architecture for architecture
Execution Model
See .claude/rules/core/anti-skip-behavior.md for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase 00 Initialization immediately.
Anti-Skip Enforcement Contract
Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the devforgeai-validate phase gates, the settings.json-registered .codex/hooks/ scripts, and .codex/hooks/phase-steps-registry.json (ADR-076). Behavioral residue: .claude/rules/core/anti-skip-behavior.md.
Layer 4 (CLI phase-gate) is wired as of gh#283: ideation is registered in phase_state.py WORKFLOW_SCHEMAS, and Phase 00 + every phase file call phase-init / phase-check / phase-record / phase-complete. The active boundary enforcer is pre-phase-complete-boundary-check.sh (PreToolUse exit 2 when a BLOCK-policy phase file [phases 01–06] was never file inspection during the story — ADR-132; phase-07 is EXEMPT as the terminal handoff phase; phase-entry-validator.sh is now PostToolUse telemetry). There are no [MANDATORY] reference manifests — ideation's reference reads stay advisory/graceful (phase-01 degrades without halting) and the generated requirements are validated downstream by validate-pm-plan. Step- and subagent-count enforcement stays deferred (empty steps_required / subagents_required, per ADR-110 / ADR-073).
Parameter Extraction
Extract from conversation context:
| Parameter | Source | Default |
|---|
$BUSINESS_IDEA | Text from /ideate command or <business-idea> XML | null (will ask in Phase 02) |
$BRAINSTORM_FILE | <brainstorm-file> XML element from /ideate | null (no brainstorm input) |
$PROJECT_MODE | <project-mode> XML element from /ideate | "auto-detect" |
$RESUME_ID | --resume IDEATION-NNN argument | null (new session) |
$MODE | Derived from above | "new" or "resume" |
Phase 00: Initialization [INLINE - Bootstraps State]
This phase runs inline because it creates the state that all other phases depend on.
Step 0.1: Parse Arguments
IF conversation contains "--resume IDEATION-":
Extract IDEATION_ID from argument
MODE = "resume"
ELSE IF conversation contains "<ideation-context>":
Extract BUSINESS_IDEA from <business-idea> element
Extract BRAINSTORM_FILE from <brainstorm-file> element
Extract PROJECT_MODE from <project-mode> element
MODE = "new"
ELSE IF conversation contains business idea text after /ideate:
BUSINESS_IDEA = extracted text
MODE = "new"
ELSE:
MODE = "new"
BUSINESS_IDEA = null
Step 0.2: Handle Resume Mode
IF MODE == "resume":
checkpoint_results = search for `devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json`
IF found:
inspect `devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json`
Restore session state from checkpoint
CURRENT_PHASE = checkpoint.progress.current_phase
Display: "Resuming ${IDEATION_ID} from Phase ${CURRENT_PHASE}"
GOTO Phase Orchestration Loop at CURRENT_PHASE
ELSE:
Display: "No checkpoint found for ${IDEATION_ID}."
ask the user:
Question: "No checkpoint found. What would you like to do?"
Header: "Resume"
Options:
- label: "Start a new ideation session"
description: "Begin fresh session"
- label: "Check for completed requirements"
description: "Look for existing requirements files"
IF "Start new": MODE = "new", continue below
IF "Check completed": Glob for existing requirements files, display results
Step 0.3: Brainstorm Context Detection
The brainstorm file may be either format. Branch on file extension BEFORE any field
extraction so the wrong parser is never run against the wrong format:
.brainstorm.html -> v2.0 (ADR-065): extract the embedded JSON data island..brainstorm.md -> v1.0 (legacy): parse YAML frontmatter.
The extension-branching extractor lives in references/brainstorm-handoff-workflow.md
§2.1 (extract_brainstorm_data). Step 0.3 calls it -- it never field-extracts inline.
IF BRAINSTORM_FILE is not null and BRAINSTORM_FILE != "none":
# Validate brainstorm file exists
brainstorm_exists = file search (pattern=BRAINSTORM_FILE)
IF found:
# Load the handoff workflow reference, then extract via its extension-branching
# extractor. Do NOT field-extract inline -- the extractor handles both .html and .md.
inspect `.codex/skills/spec-driven-ideation/references/brainstorm-handoff-workflow.md`
brainstorm_context = extract_brainstorm_data(BRAINSTORM_FILE) # branches on .html / .md
brainstorm_context = validate_brainstorm_context(brainstorm_context)
Display: "Brainstorm loaded ({brainstorm_context.source_format})."
# Pre-populate session from the extracted context
session.brainstorm_input = {
brainstorm_id: brainstorm_context.brainstorm_id,
confidence_level: brainstorm_context.confidence_level,
source_format: brainstorm_context.source_format,
pre_populated_fields: [problem_statement, personas, constraints, must_haves]
}
session = apply_brainstorm_to_ideation(brainstorm_context) # handoff-workflow.md §3.1
ELSE:
Display: "Brainstorm file not found. Starting fresh."
BRAINSTORM_FILE = null
Step 0.4: Generate Session ID (New Session)
IF MODE == "new":
# Scan for highest existing ID
search for `devforgeai/specs/ideation/IDEATION-*.checkpoint.json`
search for `devforgeai/specs/requirements/*-requirements.md`
# Extract highest NNN, increment
IDEATION_ID = "IDEATION-{NNN+1}" (zero-padded to 3 digits minimum)
# Ensure output directories exist
search for `devforgeai/specs/ideation/.gitkeep`
IF not found: write `devforgeai/specs/ideation/.gitkeep` with the specified content
Step 0.5: Create Initial Checkpoint
checkpoint = {
"checkpoint_version": "2.0",
"session_id": IDEATION_ID,
"created_at": "current ISO 8601 timestamp",
"updated_at": "current ISO 8601 timestamp",
"status": "in_progress",
"business_idea": BUSINESS_IDEA,
"project_mode": PROJECT_MODE or "auto-detect",
"brainstorm_input": {
"brainstorm_id": session.brainstorm_input.brainstorm_id or null,
"confidence_level": session.brainstorm_input.confidence_level or null,
"pre_populated_fields": session.brainstorm_input.pre_populated_fields or []
},
"progress": {
"current_phase": 0,
"phases_completed": [],
"completion_percentage": 0,
"total_questions_asked": 0
},
"phases": {},
"completed_outputs": {
"project_type": null,
"problem_statement": BUSINESS_IDEA or null,
"user_types": [],
"personas": [],
"business_goals": [],
"scope_boundaries": {},
"complexity_assessment": null,
"functional_requirements": [],
"nfr_requirements": [],
"data_entities": [],
"integrations": [],
"adr_prerequisites": [],
"requirements_file_path": null,
"validation_status": null,
"next_action": null
}
}
write `devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json` with the specified content
VERIFY: search for devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json``
IF not found: HALT -- "Initial checkpoint was NOT created."
Step 0.5b: Initialize Phase-State CLI
Initialize the phase-state machine that backs the boundary gate (ADR-132). This
is the activation switch: it creates devforgeai/workflows/${IDEATION_ID}-ideation-phase-state.json,
which the reference-reads producer resolves so the boundary gate can verify each
phase file was loaded.
devforgeai-validate phase-init ${IDEATION_ID} --workflow=ideation --project-root=. 2>&1
| Exit Code | Action |
|---|
| 0 | New workflow initialized — proceed |
| 1 | Existing workflow — resume (the checkpoint.json drives resume; continue) |
| 127 | CLI not installed — proceed without enforcement (graceful degradation) |
| Other | HALT — phase-state initialization error |
The CLI state file (${IDEATION_ID}-ideation-phase-state.json) backs the boundary
gate; the skill's own ${IDEATION_ID}.checkpoint.json backs --resume. They
coexist — do NOT unify them. On a resumed session the existing-workflow exit (1)
is expected and non-fatal.
Step 0.6: Display Session Banner
Display:
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DevForgeAI Ideation Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: ${IDEATION_ID}
Mode: ${MODE == 'resume' ? 'Resumed' : 'New Ideation'}
Business Idea: ${BUSINESS_IDEA || 'To be discovered in Phase 2'}
Brainstorm Input: ${BRAINSTORM_FILE || 'None'}
Project Mode: ${PROJECT_MODE || 'Auto-detect'}
Phases: 7 (Pre-Flight > Discovery > Elicitation > Compliance > Artifacts > Validation > Handoff)
Estimated Duration: 30-90 minutes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
Set CURRENT_PHASE = 1.
Phase Orchestration Loop
FOR phase_num in range(CURRENT_PHASE, 8): # Phases 01-07
1. LOAD: inspect `.codex/skills/spec-driven-ideation/phases/{phase_files[phase_num]}`
Load the phase file FRESH. Do NOT rely on memory of previous reads.
2. REFERENCE: Read the phase's reference files as specified in the phase Contract section.
Each phase references files in .codex/skills/spec-driven-ideation/references/.
Load ALL listed references. Do not skip any.
3. EXECUTE: Follow EVERY step in the phase file using EXECUTE-VERIFY-RECORD triplets.
- Each step's EXECUTE tells you exactly what ask the user to call or action to take
- Each step's VERIFY tells you how to confirm the data was captured
- Each step's RECORD tells you how to update the checkpoint
4. EXIT CRITERIA: Verify ALL phase exit criteria are met before proceeding.
IF any required data key is null or empty: HALT.
IF questions_answered < minimum_questions: HALT.
5. CHECKPOINT: Update checkpoint JSON with phase completion.
Write updated checkpoint to disk.
Verify write via file search.
6. CONTEXT CHECK: If estimated context > 70%, offer save-and-resume via ask the user.
IF user chooses "Save and resume later":
Write final checkpoint, display resume command, EXIT skill.
Display: "Run /ideate --resume ${IDEATION_ID} to continue."
Phase Table
| Phase | Name | File | Min Qs | Required Data |
|---|
| 00 | Initialization | (inline above) | 0-1 | session_id, checkpoint on disk |
| 01 | Pre-Flight & Context Detection | phases/phase-01-preflight.md | 0-3 | project_type, user_input_patterns_loaded |
| 02 | Discovery & Problem Understanding | phases/phase-02-discovery.md | 5 | problem_statement, user_types[>=1], business_goals[>=1], scope_boundaries |
| 03 | Requirements Elicitation | phases/phase-03-elicitation.md | 10 | functional_requirements[>=5], nfr_requirements[>=1], data_entities[>=1] |
| 04 | Constitutional Compliance | phases/phase-04-compliance.md | 0 | compliance_checked=true, adr_prerequisites (list) |
| 05 | Artifact Generation | phases/phase-05-artifacts.md | 0-2 | requirements_file_path (non-null, file on disk, F4 fields present) |
| 06 | Self-Validation | phases/phase-06-validation.md | 0-1 | validation_status in [PASSED, PASSED_WITH_WARNINGS] |
| 07 | Completion & Handoff | phases/phase-07-handoff.md | 1-3 | completion_summary_displayed=true, next_action_determined=true |
Required Subagents
| Phase | Subagent | Enforcement |
|---|
| 01 | internet-sleuth | CONDITIONAL (if user opts for market research enrichment) |
| 04 | context-validator | CONDITIONAL (if context files exist for brownfield check) |
State Persistence
- Checkpoint:
devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json
- Output:
devforgeai/specs/requirements/{project-name}-requirements.md
- References:
.codex/skills/spec-driven-ideation/references/ (shared read, not duplicated)
- Templates:
.codex/skills/spec-driven-ideation/assets/templates/ (shared read)
- Scripts:
.codex/skills/spec-driven-ideation/scripts/ (shared read)
Workflow Completion Validation
IF phases_completed < 7: HALT "WORKFLOW INCOMPLETE - {completed_count}/7 phases"
IF requirements_file not on disk (Glob returns empty): HALT "Requirements document not generated"
IF validation_status not in [PASSED, PASSED_WITH_WARNINGS]: HALT "Validation did not pass"
IF checkpoint still exists: Mark checkpoint status = "complete"
Error Handling
Load error recovery patterns from: .codex/skills/spec-driven-ideation/references/error-handling-index.md
Error Type Files (load on-demand):
error-type-1-incomplete-answers.md - Vague/incomplete user responseserror-type-2-artifact-failures.md - File write/permission errorserror-type-3-complexity-errors.md - Complexity assessment errorserror-type-4-validation-failures.md - Quality validation issueserror-type-5-constraint-conflicts.md - Brownfield constraint conflictserror-type-6-directory-issues.md - Directory structure issues
Graceful Degradation Priority:
- User answers (highest - never lose)
- Problem statement
- Functional requirements
- Non-functional requirements
- Data entities
- Integrations (lowest - can be discovered later)
Success Criteria
- All 7 phases executed (no skipping)
- requirements.md exists on disk with all F4 schema sections
- Validation passed (PASSED or PASSED_WITH_WARNINGS)
- User validated requirements accuracy
- Checkpoint marked as complete
- Next steps displayed to user
