ideation

name

ideation

description

You MUST use this before building any new feature, planning a migration, designing a system, or turning a decided-on idea into a plan. Triggers on: feature requests, project ideas, brain dumps, 'help me plan,' 'spec this out,' 'interview me,' 'I want to build,' 'let's design,' or any unstructured idea you're ready to turn into code. Covers small single-spec projects through multi-phase initiatives. Runs a conversational interview, writes an interactive HTML contract, then generates implementation-ready Markdown specs. This is the planning-HOW stage: if the user is still deciding WHETHER to build — weighing options, pressure-testing a rough idea, 'should I…' — that's the lighter-weight brainstorming skill, and ideation takes over once they've committed to build. Skip ONLY for well-defined implementation tasks (writing code to a known spec, fixing bugs, refactoring, explaining code).

Ideation

Transform unstructured brain dumps into implementation artifacts through a conversational interview that builds shared understanding before writing anything. HTML is for interactive decision-making (visualizations, comparisons, the Mission Brief contract); Markdown is for reference documents (specs, PRDs).

Workflow

INTAKE → INTERVIEW LOOP → CONTRACT.HTML → PHASING → SPEC.MD GENERATION → HANDOFF
              ↓                  ↓             ↓             ↓                ↓
         Accept the mess    One question    Mission       Repeatable?      Phase track
                            at a time,      Brief with      ↓              + copy buttons
                            explore code    gates +      Template +        in contract
                            + show HTML     scope        per-phase
                            examples        tiers        deltas

Phases 1-2: Interview

Read and follow ${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md for the full intake and interview loop; complete every phase there before Phase 3. Read ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md for the evidence-gate criteria.

Phase 3: Contract (HTML)

When all 5 evidence gates are ready — not before — generate the Mission Brief contract:

1. AskUserQuestion to confirm the project name if not obvious; kebab-case it into the slug.

2. Create ./docs/ideation/{slug}/.

3. Write contract-data.json there, conforming to the ContractData schema (the CLI renders HTML from it). It captures all interview findings:

   {
     "projectName": "Human-Readable Name",
     "slug": "kebab-case-name",
     "date": "YYYY-MM-DD",
     "status": "Draft",
     "supersedes": null,
     "gates": {
       "dimensions": [
         {
           "key": "problem",
           "label": "Problem Clarity",
           "status": "ready",
           "evidence": "One sentence citing the artifact that makes this gate ready"
         },
         {
           "key": "goals",
           "label": "Goal Definition",
           "status": "ready",
           "evidence": "One sentence"
         },
         {
           "key": "criteria",
           "label": "Success Criteria",
           "status": "ready",
           "evidence": "One sentence"
         },
         {
           "key": "scope",
           "label": "Scope Boundaries",
           "status": "ready",
           "evidence": "One sentence"
         },
         {
           "key": "consistency",
           "label": "Consistency",
           "status": "not-ready",
           "evidence": "One sentence naming the gap that keeps this gate not-ready"
         }
       ]
     },
     "problem": ["paragraph 1", "paragraph 2"],
     "goals": ["Measurable goal 1", "Measurable goal 2"],
     "successCriteria": [
       {
         "criterion": "Pass/fail criterion",
         "check": "command that verifies it — expected outcome"
       },
       { "criterion": "Judgment-only criterion (no mechanical check exists)" }
     ],
     "scope": {
       "mvp": [{ "item": "Core feature", "reason": "Why it's MVP" }],
       "full": [{ "item": "Full feature", "reason": "Optional rationale" }],
       "stretch": [{ "item": "Stretch feature" }],
       "outOfScope": [{ "item": "Excluded item", "reason": "Why excluded" }],
       "future": ["Deferred idea 1"]
     },
     "execution": {
       "strategy": "Sequential",
       "phases": [
         {
           "title": "Phase name",
           "risk": "low",
           "blocking": true,
           "specPath": "docs/ideation/slug/spec-phase-1.md",
           "notes": "Brief description of what this phase covers"
         }
       ],
       "agentTeamPrompt": "only if 2+ phases parallelizable"
     }
   }
   

   Field semantics live in the contract-gen.ts types. Key contracts: the five gate dimensions are exactly the rubric's gates — Problem Clarity, Goal Definition, Success Criteria, Scope Boundaries, Consistency (see ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md; the example above uses their canonical keys/labels). Each dimension has a status (ready/not-ready) and one-sentence evidence (the artifact making it ready, or the gap keeping it not-ready) — readiness is derived from the dimensions, no counts. Proceed only when all 5 are ready — record not-ready gates only when the user ends the interview early. Success criteria carry their own verification: give every criterion a check — a runnable command plus its expected outcome ("npx vitest run src/auth — exits 0", "curl -s localhost:3000/health — returns 200") — whenever it can be verified mechanically. Omit check only when verification is genuinely human judgment; the contract renders those with a visible "judgment call" tag, and the success-criteria critic challenges any omission where a command is plausible. Phase fields: risk (high/medium/low), blocking, specPath, notes; optional kind ("gate" for human checkpoints) and prereqs (array of phase titles). Two top-level fields are express-only and never written by this flow: approvalMode ("express" = single-confirmation approval) and branch (isolation branch autopilot re-asserts) — absent means interactive review on the current branch. status stays "Draft" here — a Draft contract renders the phase track as a plan preview with no run commands; commands appear when Phase 5 flips it to "Approved".

4. Fan out the plan critics (before rendering — fixing a blocker is a one-line JSON edit at this stage, not a regenerate loop). Issue all four Agent calls in one message so they run concurrently: subagent_type: ideation:plan-critic, prompt = per-invocation inputs only (contract-data.json path, project directory, and the lens — one of scope-creep, over-engineering, hidden-dependency, success-criteria); workflow/format/read-only tools come from the registered definition and are platform-enforced.

   Act on findings: each blocker → revise contract-data.json to resolve it (re-tier a scope item, add a phase prereq, rewrite a criterion); if a blocker exposes a genuine unknown rather than a fixable defect, return to the interview loop for that gate. Each notable → fold in if clearly right, else carry to the digest with a one-line dismissal. nit → digest mention only.

   Failure tolerance: a failed critic or an unregistered ideation:plan-critic (older Claude Code) → warn, proceed without that lens, note the gap in the digest. Critics amplify quality; never block the contract on a critic failure. Run-once rule: critics run exactly once per contract — re-run only if a revision changes goals or scope fundamentally, not for wording. The "Needs changes" approval loop does not re-trigger them.

5. Run the generator (it handles lineage — an existing Approved contract.html is renamed to contract-{date}.html with the supersedes link set; a Draft is replaced in place, so interview revisions and the Draft→Approved flip don't accumulate snapshots):

   npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/contract-gen.ts \
     --input ./docs/ideation/{slug}/contract-data.json \
     --output ./docs/ideation/{slug}/contract.html
   

   The generator is the only renderer for contract.html. There is no fallback template — never hand-write the contract HTML or "render it from a template" if the generator can't run. If the command is denied by permissions (common when the plugin root is outside the current repo — the classifier flags npx tsx on an out-of-repo script as untrusted code), do not work around the denial and do not hand-render — the denial message may say you "may attempt other tools to accomplish this goal"; for this step that does not apply, since any other tool means hand-authoring the contract. Instead show the user the exact command and ask them to run it themselves by typing ! npx tsx … in the prompt, then continue once contract.html exists. Run the generator and open as separate Bash calls — never chained with && — so a denial of one is visible and doesn't silently skip the other.

6. Open it: open ./docs/ideation/{slug}/contract.html (macOS) or xdg-open (Linux).

7. Present the Critic digest, then ask for approval. Only ask once contract.html was actually generated and opened — never ask the user to approve a contract they haven't seen. The digest is one line per lens: found N (B blockers folded in, M notables, dismissed X — reasons); note any skipped lens; if all four returned SOUND, say so. Then AskUserQuestion:

   Question: "Does this contract capture your intent? Which scope tier should we target?"
   Options:
   - "Approved — Full scope (Recommended)" - Build MVP + Full tiers
   - "Approved — MVP scope" - Ship the minimum viable version first
   - "Approved — Stretch scope" - Include MVP + Full + Stretch tiers
   - "Needs changes" - Some parts need revision before approving
   - "Start over" - Fundamentally off track, re-interview
   

   The approved tier determines what goes into specs; items outside it move to "Future Considerations". If not approved: revise (fundamental misunderstanding → back to the interview loop; otherwise re-write the HTML and re-open), iterating until approved. Do not proceed until explicitly approved.

Phase 4: Phasing & Specification

After approval, determine phases and generate Markdown specs. PRDs are optional.

4.1 Choose Workflow

AskUserQuestion:

Question: "How should we proceed from the contract?"
Options:
- "Straight to specs (Recommended)" — Contract defines what, specs define how. Faster.
- "PRDs then specs" — Adds a requirements layer for stakeholder alignment.

4.2 Determine Phases

Break scope into logical implementation phases.

Small-project shortcut: if the scope fits one phase (1-3 components, fewer than ~10 files), skip phasing — generate a single spec.md (no phase number) and go straight to handoff.

Phasing criteria (multi-phase): dependencies (build-order), risk (high-risk early), value delivery (benefit after each phase), complexity (balanced effort). Typical: Phase 1 core/infrastructure, Phase 2+ features/integrations, Phase N future considerations.

Detect repeatable patterns: 3+ phases with the same structure but different inputs (e.g., "add SDK support for {language}") change how specs are generated (see 4.4).

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

Read ${CLAUDE_PLUGIN_ROOT}/skills/ideation/references/prd-template.md, then generate prd-phase-{n}.md per phase: overview/rationale, user stories, functional requirements (grouped), non-functional requirements, dependencies (prerequisites and outputs), acceptance criteria. Review via AskUserQuestion, iterating until approved:

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

4.4 Generate Implementation Specs

Read ${CLAUDE_PLUGIN_ROOT}/skills/ideation/references/spec-template.md, then generate specs lazily — only when a phase's details are resolved.

Standard phases (each unique): a full spec-phase-{n}.md with technical approach, feedback strategy (inner-loop command, playground, rationale), file changes (table with new/modified/deleted), implementation details (per-component, each with a playground → experiment → check-command loop), testing requirements (table), failure modes (table: component, failure, trigger, impact, mitigation), validation commands.

• Prefer the minimum approach: the technical approach should be the simplest implementation that meets the phase's success criteria — no speculative abstractions, no configurability or error handling for cases the contract doesn't raise. If a design would make a senior engineer say "overcomplicated," cut it back; when added structure genuinely earns its keep, name the criterion that justifies it. (Scope minimalism is the over-engineering critic's job at the contract stage; this is its implementation-stage companion.)
• Reference existing code: where the interview found relevant patterns, add "Pattern to follow: path/to/file.ts" to implementation details.
• Feedback loops: match the mechanism to the component — data layers use tests, UI uses a dev server, APIs use curl scripts, config/types skip loops. See ${CLAUDE_PLUGIN_ROOT}/references/feedback-loop-guide.md for the full mapping.
• Failure modes: for each non-trivial component, name how it fails — data shadows (nil/empty/stale), edge cases (concurrency, oversized input, missing permissions). Trivial components (config, types, constants) skip this.

Repeatable phases (3+ share a structure): don't generate N near-identical specs. Generate one full template — spec-template-{pattern-name}.md with placeholders for the variable parts — plus lightweight spec-phase-{n}.md deltas containing only the phase-specific inputs, deviations from the template, phase-specific concerns, and a reference: "Follow spec-template-{pattern-name}.md with the inputs below".

4.5 Present Specs for Review

First, self-review feedback-loop quality against the Spec Feedback Quality checklist in ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md: Strong (all iterative components have loops, inner-loop command defined, trivial ones skipped) → present as-is; Adequate (minor gaps) → present with a note; Weak (no Feedback Strategy, or complex components missing loops) → fix the gaps before presenting. Then AskUserQuestion, iterating until approved:

Question: "Do these specs look correct? (Review them in your browser)"
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

Phase 5: Execution Handoff

After specs are approved, update the contract with the execution plan and emit Markdown for /ideation:execute-spec.

5.1 Analyze Orchestration Strategy

Do not create tasks here — they are ephemeral and lost on a fresh session; each /ideation:execute-spec creates its own. Analyze the phase dependency graph: 2+ phases sharing a single blocker (e.g., all blocked only by Phase 1) are parallelizable; a linear chain is sequential; mixed graphs have both.

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 Update Contract Data with Execution Plan

Update contract-data.json with the final plan and re-run contract-gen.ts so the contract is self-contained:

• Status — set "status": "Approved". This is what unlocks the run UI: Draft contracts render the phase track as a plan preview with an "awaiting approval" note; Approved contracts render First Move, the autopilot bar, and per-phase copy commands.
• Phase Track — populate execution.phases (titles, risk, blockers, spec paths, notes, human gates); the CLI renders the risk-colored track.
• Execution Commands — the CLI renders copy buttons for /ideation:autopilot and each /ideation:execute-spec.
• Agent Team Prompt — set execution.agentTeamPrompt only if 2+ phases are parallelizable (CLI renders it in a collapsible section); omit entirely for sequential projects.

Shared file detection: before writing the agent team prompt, scan specs' "Modified Files". If multiple specs touch the same files, add a coordination note: "Coordinate on shared files ({list}) — only one teammate should modify a shared file at a time." Batching: more than 5 parallelizable phases → note starting with the highest-priority batch first. Re-open the regenerated contract.

5.3 Generate Contract Markdown

Generate contract.md from ${CLAUDE_PLUGIN_ROOT}/skills/ideation/references/contract-template.md mirroring contract.html (including the Execution Plan) — autopilot's fallback parser (when contract-data.json is absent) and get-goal-prompt consume it. Specs and PRDs are already Markdown.

5.4 Present Handoff Summary

Present a brief summary, then recommend one entry point — don't hand over an undifferentiated menu. Always include:

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.
Open contract.html to review the full plan — phase track, scope, and the Mission Brief.

Then apply the decision rule:

• Single phase: recommend the one spec directly, no question:

  Your next step: /ideation:execute-spec docs/ideation/{project-name}/spec.md (One phase — orchestration adds nothing.)

• Multi-phase: ask exactly one question — whether they'll watch or walk away:

  Question: "How do you want to run this?"
  Options:
  - "Watch it run now (Recommended)" — /ideation:autopilot runs the phases on its Workflow engine while you watch.
  - "Start it and walk away" — get a /goal that drives autopilot to completion unattended, recovering from failures.
  - "I'll run phases myself" — run each /ideation:execute-spec manually.
  

  Recommend by verifiability: the unattended path can only trust what it can check. If most successCriteria carry a check command, keep "Watch it run now" or "Start it and walk away" as viable recommendations. If most criteria are judgment calls, do not recommend the walk-away option — say why in one line: a /goal run would complete phases nothing mechanical verified.

  Then echo the exact command for their choice:

  • Watch now → /ideation:autopilot docs/ideation/{project-name}/contract.md
  • Walk away → run /ideation:get-goal-prompt docs/ideation/{project-name}/contract.md, then paste the /goal it copies
  • Manually → the per-phase /ideation:execute-spec commands in dependency order

The layered model (state once if helpful): /ideation:autopilot is the deterministic Workflow engine; the /goal is a durability wrapper that drives it unattended; /ideation:execute-spec is the per-phase unit all of them call. Graph shape doesn't change which entry point to recommend — the engine handles parallelism internally — so route on phase count, attended-vs-unattended, and whether the contract's checks make unattended verification trustworthy.

Output Artifacts

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

_comparison.html                   # Ephemeral decision aid (deleted after choice is made)
contract-data.json                 # Machine-readable contract (source of truth; consumed by autopilot)
contract.html                      # Mission Brief contract (for review)
contract.md                        # Plain contract (autopilot fallback + get-goal-prompt)
prd-phase-1.md                     # Phase 1 requirements (only if PRDs chosen)
...
spec-phase-1.md                    # Implementation spec (for execute-spec)
spec-template-{pattern}.md         # Shared template for repeatable phases (if applicable)
spec-phase-{n}.md                  # Per-phase delta or full spec
...

Bundled Resources

Shared references (plugin root):

• interview-engine.md — interview engine (Phases 1-2)
• confidence-rubric.md — evidence-gate criteria for readiness and spec feedback quality
• feedback-loop-guide.md — component-type mapping and design criteria for spec feedback loops
• workflow-example.md — end-to-end walkthrough

Skill references — these live at ${CLAUDE_PLUGIN_ROOT}/skills/ideation/references/, a different base from the shared refs above; bare references/... mentions in this file resolve there. HTML (interactive): references/html-guide.md (component library, design tokens, constraints — for ephemeral comparison artifacts only; contract.html comes exclusively from scripts/contract-gen.ts). Markdown: references/contract-template.md, references/prd-template.md, references/spec-template.md.

Examples (filled-in artifacts for a bookmark feature — reference for tone, structure, detail): examples/contract-example.md, examples/prd-example.md, examples/spec-example.md.

Decision Aids: Previews First, HTML When Visual

During the interview and phasing, comparisons help the user decide. Default to AskUserQuestion previews; escalate to ephemeral HTML only when the decision hinges on something a monospace preview can't show.

AskUserQuestion's per-option preview field renders side-by-side in a monospace box (markdown) — the default routing, since it keeps the decision inline with no file to write or clean up. Use it for ASCII layout mockups, code snippets (signature/config/schema per option), dependency-flow or phasing sketches, and compact pros/cons blocks. By stage: interview examples → ASCII mockups; architecture comparisons → structure + trade-offs per approach; phasing strategies → core-first vs. risk-first vs. value-first as dependency-flow sketches; orchestration strategy → sequential vs. parallel vs. hybrid as ASCII timelines.

Constraints: previews are single-select only — never combine with multiSelect (drop previews and rely on labels + descriptions, or escalate to HTML). Keep them comparative — a preview earns its place only when seeing options side-by-side changes the choice; otherwise skip it.

Escalate to ephemeral HTML only when a monospace box can't render the deciding factor: real visual design (color, typography, spacing), interactive behavior (sliders, toggles, hover), or side-by-side rendered (not sketched) artifacts. Workflow: write _comparison.html (prefix _ marks it ephemeral) using references/html-guide.md components, show each option as a card/column (name, description, trade-offs, visual where apt), open it, ask via AskUserQuestion referencing the browser view, then delete it after the choice. Genuine visual mockups still use this path — the contract HTML does not; it comes only from the generator.

When NOT to use a decision aid: simple yes/no, choices where the recommended option is clearly best, or anything faster to explain in text.

Important Notes

• HTML is for interactive artifacts only (contract, ephemeral visualizations); specs and PRDs are Markdown.
• Read templates before writing: references/html-guide.md before any ephemeral HTML, references/spec-template.md before specs. contract.html is generator output — never hand-written.
• Use AskUserQuestion for all questions and approvals — one at a time, with your recommended answer.
• Judge gates conservatively — when unsure the evidence is sufficient, the gate is not-ready. No fixed question limit.
• Open HTML artifacts after writing (open / xdg-open).
• Create files lazily — only when decisions are locked.
• Small projects don't need phases — 1-3 components → single spec. Template + delta for repeatable phases.
• Specs must stand alone — implementable without re-reading PRDs or the contract.
• Express variant — /ideation:express (skills/express/SKILL.md) reuses Phases 1–2 verbatim and overrides the Phase 3–5 approval gates by section reference (one consolidated confirmation, approvalMode: "express", isolation branch, immediate autopilot). When restructuring or renumbering Phases 3–5 here, keep that file's references in sync.