ideation

name	ideation
description	Transform raw brain dumps (dictated freestyle) into structured implementation artifacts. Use when user has messy ideas, scattered thoughts, or dictated stream-of-consciousness about something they want to build. Produces contracts and implementation specs written to ./docs/ideation/{project-name}/.

Ideation

Transform unstructured brain dumps into structured, actionable implementation artifacts through a confidence-gated workflow.

Critical: Use AskUserQuestion Tool

ALWAYS use the AskUserQuestion tool when asking clarifying questions. Do not ask questions in plain text. The tool provides structured options and ensures the user can respond clearly.

Use AskUserQuestion for:

• Clarifying questions during confidence scoring (Phase 2)
• Project name confirmation before writing artifacts
• Contract approval
• Workflow choice (PRDs vs straight to specs)
• Phase review feedback before spec generation
• Any decision point requiring user input

Workflow Pipeline

INTAKE → CODEBASE EXPLORATION → CONTRACT FORMATION → PHASING → SPEC GENERATION → HANDOFF
              ↓                        ↓                  ↓            ↓               ↓
         Understand              confidence < 95%?    PRDs or     Repeatable?    Analyze deps
         existing code                ↓               straight      ↓               ↓
                                 ASK QUESTIONS        to specs?   Template +    Sequential?
                                      ↓                           per-phase     Parallel?
                                 (loop until ≥95%)                deltas        Agent Team?

Phase 1: Intake

Accept whatever the user provides:

• Scattered thoughts and half-formed ideas
• Voice dictation transcripts (messy, stream-of-consciousness)
• Bullet points mixed with rambling
• Topic jumping and tangents
• Contradictions and unclear statements
• Technical jargon mixed with vague descriptions

Don't require organization. The mess is the input.

Acknowledge receipt and begin analysis. Do not ask for clarification yet.

Phase 2: Codebase Exploration

Before scoring confidence or generating any artifacts, understand the existing codebase. This is critical — specs written without understanding existing patterns, architecture, and conventions will be generic and wrong.

2.1 Determine if Exploration is Needed

Exploration is needed when:

• The brain dump references existing code, features, or systems
• The project directory contains source code (not a greenfield project)
• The user mentions extending, modifying, or integrating with existing functionality

Skip exploration for greenfield projects with no existing code.

2.2 Explore the Codebase

Use the Task tool with subagent_type: "Explore" or direct Glob/Grep/Read to understand:

1. Project structure — What frameworks, languages, and patterns are in use?
2. Relevant existing code — What modules/files relate to the brain dump's scope?
3. Conventions and patterns — How are similar features implemented? What abstractions exist?
4. Testing patterns — How is the codebase tested? What infrastructure exists?
5. Configuration and build — What tools, package managers, and CI/CD are in use?

2.3 Record Findings

Retain exploration context for use in later phases. These inform:

• Confidence scoring — better understanding of the problem space
• Contract — realistic scope boundaries based on actual architecture
• Specs — "Pattern to follow" references, accurate file paths, correct abstractions

Do not write exploration findings to files. They're context for the ideation process, not an artifact.

Phase 3: Contract Formation

3.1 Analyze the Brain Dump

Extract from the raw input + codebase exploration:

1. Problem signals: What pain point or need is being described?
2. Goal signals: What does the user want to achieve?
3. Success signals: How will they know it worked?
4. Scope signals: What's included? What's explicitly excluded?
5. Contradictions: Note any conflicting statements
6. Codebase constraints: What does the existing architecture enable or limit?

3.2 Calculate Confidence Score

Read references/confidence-rubric.md for detailed scoring criteria.

Score conservatively. When uncertain between two levels, choose the lower one. One extra round of questions costs minutes; a bad contract costs hours. Do not inflate scores to move forward faster.

Score each dimension (0-20 points):

Dimension	Question
Problem Clarity	Do I understand what problem we're solving and why it matters?
Goal Definition	Are the goals specific and measurable?
Success Criteria	Can I write tests or validation steps for "done"?
Scope Boundaries	Do I know what's in and out of scope?
Consistency	Are there contradictions I need resolved?

Total: /100 points

3.3 Confidence Thresholds

Score	Action
< 70	Major gaps. Ask 5+ questions targeting lowest dimensions.
70-84	Moderate gaps. Ask 3-5 targeted questions.
85-94	Minor gaps. Ask 1-2 specific questions.
≥ 95	Ready to generate contract.

3.4 Ask Clarifying Questions

When confidence < 95%, MUST use AskUserQuestion tool to ask clarifying questions. Structure questions with clear options when possible.

Using AskUserQuestion effectively:

• Provide 2-4 options per question when choices are clear
• Use multiSelect: true when multiple answers apply
• Keep question headers short (max 12 chars)
• Include descriptions that explain implications of each choice

Question strategy:

• Target the lowest-scoring dimension first
• Be specific, not open-ended
• Offer options when possible ("Is it A, B, or C?")
• Reference what was stated ("You mentioned X, did you mean...?")
• Limit to 3-5 questions per round
• After each round, recalculate confidence

Question templates by dimension:

Problem Clarity:

• "What specific problem are you trying to solve?"
• "Who experiences this problem and how often?"
• "What's the cost of NOT solving this?"

Goal Definition:

• "What does success look like for this project?"
• "How will you measure whether this worked?"
• "What specific metrics should improve?"

Success Criteria:

• "How will you know when you're done?"
• "What tests would prove this feature works?"
• "What would a QA person check?"

Scope Boundaries:

• "What is explicitly NOT part of this project?"
• "Are there related features we should defer?"
• "What's the MVP vs. nice-to-have?"

Consistency:

• "You mentioned [X] but also [Y]. Which takes priority?"
• "These requirements seem to conflict. Can you clarify?"
• "How should we handle [edge case]?"

3.5 Generate Contract

When confidence ≥ 95%, generate the contract document.

1. Use AskUserQuestion to confirm project name if not obvious from context
2. Convert to kebab-case for directory name
3. Create output directory: ./docs/ideation/{project-name}/
4. Write contract.md using references/contract-template.md
5. Use AskUserQuestion to get approval:

Question: "Does this contract accurately capture your intent?"
Options:
- "Approved" - Contract is accurate, proceed
- "Needs changes" - Some parts need revision
- "Missing scope" - Important items are not captured
- "Start over" - Fundamentally off track, re-analyze

If not approved: Revise the contract based on feedback. Do not re-score confidence unless the feedback reveals a fundamental misunderstanding — in that case, return to Phase 3.2 and re-score. Otherwise, edit contract.md directly and re-present for approval. Iterate until approved.

Do not proceed until contract is explicitly approved.

Phase 4: Phasing & Specification

After contract is approved, determine phases and generate specs. PRDs are optional.

4.1 Choose Workflow

Use AskUserQuestion to ask:

Question: "How should we proceed from the contract?"
Options:
- "Straight to specs" — Recommended for technical projects.
  Contract defines what, specs define how. Faster.
- "PRDs then specs" — Recommended for large scope or cross-functional
  teams. Adds a requirements layer for stakeholder alignment.

4.2 Determine Phases

Regardless of PRD choice, analyze the contract and break scope into logical implementation phases.

Small-project shortcut: If the scope is small enough to implement in a single phase (1-3 components, touches fewer than ~10 files), skip phasing entirely. Generate a single spec.md (no phase number needed) and proceed directly to handoff. Not every project needs multiple phases — don't force structure where simplicity suffices.

Phasing criteria (for multi-phase projects):

• Dependencies (what must be built first?)
• Risk (tackle high-risk items early)
• Value delivery (can users benefit after each phase?)
• Complexity (balance phases for consistent effort)

Typical phasing:

• Phase 1: Core functionality / infrastructure
• Phase 2+: Features, enhancements, additional integrations
• Phase N: Future considerations

Detect repeatable patterns: If 3+ phases follow the same structure with different inputs (e.g., "add SDK support for {language}"), note this — it affects how specs are generated (see 4.4).

4.3 Generate PRDs (only if user chose "PRDs then specs")

For each phase, generate prd-phase-{n}.md using references/prd-template.md.

Include:

• Phase overview and rationale
• User stories for this phase
• Functional requirements (grouped)
• Non-functional requirements
• Dependencies (prerequisites and outputs)
• Acceptance criteria

Present all PRDs for review. Use AskUserQuestion:

Question: "Do these PRD phases look correct?"
Options:
- "Approved" - Phases and requirements look good, proceed to specs
- "Adjust phases" - Need to move features between phases
- "Missing requirements" - Some requirements are missing or unclear
- "Start over" - Need to revisit the contract

Iterate until user explicitly approves.

4.4 Generate Implementation Specs

Generate specs using references/spec-template.md. How specs are generated depends on whether phases are repeatable:

Standard phases (each is unique)

For each phase, generate a full spec-phase-{n}.md with:

• Technical approach
• File changes (new and modified)
• Implementation details with code patterns
• Testing requirements
• Error handling
• Validation commands

Reference existing code: When the codebase exploration (Phase 2) identified relevant patterns, include "Pattern to follow: path/to/similar/file.ts" in the spec's implementation details. This gives the executing agent concrete examples to follow.

Repeatable phases (3+ phases follow the same pattern)

When multiple phases share the same structure (e.g., "add support for {SDK}"), avoid generating N nearly-identical full specs. Instead:

1. Generate one full template spec — spec-template-{pattern-name}.md — with detailed implementation steps, using placeholders for the variable parts.

2. Generate lightweight per-phase delta files — spec-phase-{n}.md — containing only:

   • Phase-specific inputs (e.g., language name, package manager, framework)
   • Deviations from the template (what's different about this phase)
   • Any phase-specific concerns or edge cases
   • Reference to the template: "Follow spec-template-{pattern-name}.md with the inputs below"

Example for SDK integrations:

spec-template-sdk-integration.md:

# SDK Integration Template

## Pattern
For each SDK, create:
1. `src/{language}/{language}-installer-agent.ts` — FrameworkConfig following existing pattern
2. `skills/workos-{sdk-name}/SKILL.md` — Agent skill fetching SDK README
3. `tests/fixtures/{language}/{framework}-example/` — Minimal project fixture
4. `tests/evals/graders/{language}.grader.ts` — Extending BaseGrader

## Implementation Details
{Detailed steps with {placeholders} for variable parts}

## Validation
{Common validation steps}

spec-phase-5.md:

# Spec: Ruby SDK (workos-ruby)

**Template**: ./spec-template-sdk-integration.md

## Inputs
- Language: Ruby
- Framework: Rails
- Package manager: Bundler (`bundle add`)
- Manifest file: Gemfile
- SDK package: workos
- Detection: `rails` gem in Gemfile or `config/routes.rb` exists

## Deviations from template
- Rails has strong conventions — files go in specific locations
- Initializer pattern: `config/initializers/workos.rb`
- Env vars: `.env` with dotenv-rails, or Rails credentials

## Phase-specific concerns
- CI needs Ruby 3.x installed for eval fixtures

This approach:

• Saves significant context window space
• Makes the per-phase differences obvious
• Avoids copy-paste errors across specs
• Makes it easy to update the shared pattern in one place

4.5 Present Phases for Review

Whether using PRDs or straight-to-specs, present the phase breakdown and specs for user approval before proceeding to handoff.

Use AskUserQuestion:

Question: "Do these specs look correct?"
Options:
- "Approved" - Specs look good, proceed to execution handoff
- "Adjust approach" - Implementation strategy needs changes
- "Missing components" - Some files or steps are missing
- "Revisit phases" - Phase breakdown needs restructuring

If not approved, revise the relevant specs based on feedback and re-present. Iterate until approved.

Phase 5: Execution Handoff

After specs are generated, create task list, analyze orchestration options, and hand off for implementation.

5.1 Analyze Orchestration Strategy

Do not create tasks during ideation handoff — they are ephemeral and will be lost when the user starts a fresh session. Each /execute-spec session creates its own granular implementation tasks.

Analyze the phase dependency graph to determine the best execution strategy.

Detect parallelizable phases:

• Examine which phases are blocked by what
• If 2+ phases share the same single blocker (e.g., all blocked only by Phase 1), they are parallelizable
• If phases form a linear chain (Phase 2 → Phase 3 → Phase 4), they are sequential
• Mixed graphs have both parallel and sequential segments

Determine recommended strategy:

Pattern	Recommendation
All phases sequential (chain)	Sequential execution — one session at a time
2+ independent phases	Agent team — lead orchestrates teammates in parallel
Mixed dependencies	Hybrid — sequential for dependent chain, agent team for independent group

5.2 Present Handoff Summary

Present the execution strategy directly to the user. No manifest file — the contract and specs are the artifacts. The handoff summary is conversational output.

Always include:

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.

For sequential execution or when a blocking phase must complete first:

## To start implementation

```bash
claude
/execute-spec docs/ideation/{project-name}/spec-phase-1.md

Each /execute-spec session creates its own implementation tasks.

**When ALL phases are independent (no blocking phase), skip the sequential start and go straight to the agent team prompt below.**

**When 2+ phases are parallelizable (after a blocking phase or from the start), present an agent team prompt.**

Agent teams let a single lead session automatically spawn and coordinate multiple teammates — the user starts **one** `claude` session, and the lead handles spawning, task assignment, plan approval, and synthesis. No manual terminal juggling.

Parallel Execution with Agent Teams

After {blocking phase} is complete, {N} phases can run in parallel.

Ensure agent teams are enabled in .claude/settings.json or ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Start one new Claude Code session and enter delegate mode (Shift+Tab), then paste:

{Blocking phase} is complete. Create an agent team to implement
{N} remaining phases in parallel. Each phase is independent.

Spawn {N} teammates with plan approval required. Each teammate should:
1. Read their assigned spec file (and the template spec if referenced)
2. Explore the codebase for relevant patterns before planning
3. Plan their implementation approach and wait for approval
4. Implement following spec and codebase patterns
5. Run validation commands from their spec after implementation

Only approve plans that include test coverage and match existing
codebase conventions.

Teammates:

1. "{Phase title}" — docs/ideation/{project-name}/spec-phase-{n}.md
   {One-line context about what this phase does}

2. "{Phase title}" — docs/ideation/{project-name}/spec-phase-{n}.md
   {One-line context about what this phase does}

...

**Why delegate mode?** Pressing Shift+Tab restricts the lead to coordination-only tools: spawning teammates, messaging, managing tasks, and approving plans. This prevents the lead from implementing tasks itself and ensures work is distributed to teammates.

**Why one session?** The lead automatically spawns each teammate as a separate Claude Code instance. Each teammate gets its own context window, loads project context (CLAUDE.md, MCP servers, skills), and works independently. You interact with the lead and it coordinates everything — use Shift+Up/Down to message individual teammates if needed.

**Shared file detection:** Scan the spec files' "Modified Files" sections. If multiple specs modify the same files, add a coordination note to the team prompt:

Coordinate on shared files ({list}) to avoid merge conflicts — only one teammate should modify a shared file at a time.

**Batching:** If more than 5 parallelizable phases, recommend starting with the highest-priority batch first, then spawning the rest after plans are approved.

### 5.3 Why Fresh Sessions?

- Ideation consumes significant context (contract, specs, exploration)
- Execution benefits from clean context focused on the spec
- Human review between phases catches issues early
- Each phase is independently committable
- Each session creates granular implementation tasks scoped to that phase

## Output Artifacts

All artifacts written to `./docs/ideation/{project-name}/`:

contract.md # Lean contract (problem, goals, success, scope) prd-phase-1.md # Phase 1 requirements (only if PRDs chosen) ... spec-phase-1.md # Phase 1 implementation spec (always full) spec-template-{pattern}.md # Shared template for repeatable phases (if applicable) spec-phase-{n}.md # Per-phase delta referencing template (if repeatable) ...

## Bundled Resources

### References

- `references/contract-template.md` - Template for lean contract document
- `references/prd-template.md` - Template for phased PRD documents
- `references/spec-template.md` - Template for implementation specs
- `references/confidence-rubric.md` - Detailed scoring criteria for confidence assessment
- `references/workflow-example.md` - End-to-end workflow walkthrough

### Examples

Completed artifact examples for reference when generating output:

- `examples/contract-example.md` - A filled-in contract for a bookmark feature
- `examples/spec-example.md` - A filled-in spec for the same feature

When generating artifacts, reference these examples for tone, structure, and level of detail.

## Important Notes

- **ALWAYS use `AskUserQuestion` tool for clarifications and approvals.** Never ask questions in plain text.
- **Explore the codebase** before scoring confidence (unless greenfield).
- **Score confidence conservatively.** When uncertain, score lower.
- Never skip the confidence check. Don't assume understanding.
- Always write artifacts to files. Don't just display them.
- Each phase should be independently valuable.
- Specs should be detailed enough to implement without re-reading PRDs or the contract.
- Keep contracts lean. Heavy docs slow iteration.
- **Reference existing code patterns** in specs — "Pattern to follow" with real file paths.
- **Use template + delta** for repeatable phases — don't generate N identical specs.
- **Small projects don't need phases.** If scope is 1-3 components, generate a single spec.