devlyn-cli 1.15.0 → 2.0.0

package/config/skills/devlyn:ideate/SKILL.md

@@ -1,467 +1,137 @@
 ---
 name: devlyn:ideate
-description: Transforms unstructured ideas into implementation-ready planning documents through structured brainstorming, research, and a built-in self-skeptical rubric pass. Produces a three-layer document architecture (Vision, Roadmap index, auto-resolve-ready specs) to eliminate context pollution in the implementation pipeline. Default `--engine auto` routes the CHALLENGE rubric pass to OpenAI Codex (GPT-5.4) as a cross-model critic for a GAN dynamic. Use when the user wants to brainstorm, plan a new project or feature set, create a vision and roadmap, or structure scattered ideas into an actionable plan. Triggers on "let's brainstorm", "let's plan", "ideate", "I have an idea for", "help me think through", "let's explore", new project planning, feature discovery, roadmap creation, or when the user is throwing ideas that need structuring.
+description: Extract a verifiable spec from a user's idea by driving the conversation with focused questions. Output is a single-feature `spec.md` + `spec.expected.json` that `/devlyn:resolve --spec` consumes directly. Use when the user has an idea but not a spec, or wants AI to elicit the missing engineering context. Modes: default (single spec, AI drives Q&A), `--quick` (assume-and-confirm from one-line goal), `--from-spec <path>` (normalize external spec), `--project` (plan.md index + N specs). Optional in the pipeline — `/devlyn:resolve` works standalone via free-form mode for users who skip ideate.
 ---
 
-# Ideation to Implementation Bridge
+Spec-elicitation surface for users who have ideas but not engineering specifications. AI drives the conversation with focused questions until a structurally-valid, verifiable spec exists. Output consumed directly by `/devlyn:resolve --spec`.
 
-Turn unstructured thinking into auto-resolve-ready documents. The output is a precision-engineered context pipeline — each document layer serves a specific role so that implementation agents receive exactly the context they need, nothing more.
+<elicit_config>
+$ARGUMENTS
+</elicit_config>
 
-<hard_boundary>
-This skill is a PLANNING tool, not an IMPLEMENTATION tool. Your output is documents (VISION.md, ROADMAP.md, item specs) — never code changes.
+<orchestrator_context>
+This skill is OPTIONAL. `/devlyn:resolve` is standalone-capable: free-form mode handles trivial/medium tasks without a spec, `--spec` mode accepts handwritten specs from any source. Use ideate when the user wants AI to do the elicitation work.
+</orchestrator_context>
 
-When the user describes a bug, improvement, or feature request through ideate, they want it CAPTURED in the roadmap, not FIXED in the codebase. Even if the fix seems trivial and obvious, resist the urge to implement it. The user chose `/devlyn:ideate` over `/devlyn:resolve` for a reason — they want planning, not coding.
+<elicitation_contract>
+The user does not know context engineering. They will under-specify and over-assume. AI's job is to ask focused, specific questions that surface the missing engineering decisions.
 
-Concretely:
-- Do NOT read source code to find and fix issues
-- Do NOT edit application files (.tsx, .ts, .py, .js, etc.)
-- DO create or update roadmap documents (VISION.md, ROADMAP.md, item specs)
-- DO explore and research the problem space to write better specs
-- If you catch yourself about to open a source file to make a code change, stop — that's a signal you've left ideation mode
-</hard_boundary>
+1. Ask one or two questions per turn, not more. Multi-question lists overwhelm and produce shallow answers.
+2. Questions are concrete and decision-grade — what is the input, what is the expected output, what command verifies success, what files are out of scope.
+3. Do not ask design preferences the user clearly does not have. Infer the simplest reasonable default and confirm in one line.
+4. Stop when the spec passes structural lint AND the user explicitly confirms or 8 turns have elapsed (whichever comes first). Eight turns is a hard ceiling — beyond that, the spec is either ready or the task is too large for ideate.
+5. The output is the spec, not a transcript. Do not include the conversation in the saved files.
+</elicitation_contract>
 
-## Arguments
+<harness_principles>
+Read `_shared/runtime-principles.md` (Subtractive-first / Goal-locked / No-workaround / Evidence). The principles bind the spec content as well as your conversation. A spec that says "for future flexibility" is a Subtractive-first violation. A spec that asks for `try { ... } catch { return null }` is a No-workaround violation. AI flags these in elicitation, not after `/devlyn:resolve` has built them.
+</harness_principles>
 
-Parse these from the user's invocation message:
+<engine_routing>
+Default engine: Claude. The per-engine adapter from `_shared/adapters/<model>.md` is prepended to the elicitation prompt so the model honors its own official prompt-engineering guidance during the Q&A.
+</engine_routing>
 
-- `--engine MODE` (auto) — controls which model handles each ideation phase. Modes:
-  - `auto` (default): Claude handles FRAME/EXPLORE/CONVERGE/DOCUMENT (ambiguous intent, writing quality), Codex runs the CHALLENGE rubric pass as critic (GAN dynamic). Requires Codex MCP server.
-  - `codex`: Codex handles FRAME/EXPLORE/CONVERGE/DOCUMENT, Claude runs CHALLENGE (role reversal — builder and critic are always different models).
-  - `claude`: all phases use Claude. No Codex calls.
+<modes>
+Four modes, selected by flag:
 
-**Engine pre-flight** (runs unless `--engine claude` was explicitly passed):
-- The default engine is `auto`. If the user did not pass `--engine`, the engine is `auto` — not `claude`.
-- Call `mcp__codex-cli__ping` to verify Codex MCP availability. On failure, **silently fall back to `--engine claude`** and note `engine downgraded: codex-ping failed` in your eventual output summary. Do not present a menu; do not abort. This matches auto-resolve's hands-off contract.
-- Read `references/challenge-rubric.md` up front.
+1. **Default** (no flag) — single-spec elicitation. AI asks questions in-conversation until lint passes. Output: `<spec-dir>/<id>-<slug>/spec.md` + `<spec-dir>/<id>-<slug>/spec.expected.json`. Default spec dir: `docs/specs/` (configurable via `--spec-dir <path>`).
+2. **`--quick`** — one-line goal, AI synthesizes a spec with explicit assumptions block, asks the user to confirm or correct in a single turn. Use when the user wants speed over thoroughness.
+3. **`--from-spec <path>`** — external spec exists. AI lints it for the canonical structure, normalizes section names, generates a missing `spec.expected.json` if absent, fixes minor schema issues, and stops. Does NOT reshape Requirements / Out-of-Scope content; structural changes only.
+4. **`--project`** — multi-feature project. AI elicits a project description, decomposes it into 3-7 feature specs, writes `<spec-dir>/plan.md` (the index) and one `<spec-dir>/<id>/spec.md` + `<spec-dir>/<id>/spec.expected.json` per feature. See `references/project-mode.md`.
 
-**Consolidated flag**: `--with-codex` was rolled into the smarter `--engine auto` default. If the user passes it, inform them once and proceed with `--engine auto`: "Note: `--with-codex` was consolidated into `--engine auto` (default), which routes the CHALLENGE rubric pass to Codex automatically. No flag needed. Continuing with `--engine auto`."
+`--spec-dir <path>` overrides the default output directory. `--engine <model>` selects the adapter.
+</modes>
 
-## Output Architecture
+<spec_kind_escape_hatch>
+The spec carries `spec.kind ∈ {feature, spike, prototype}` in its frontmatter. The kind changes downstream behavior:
 
-The skill produces a three-layer progressive disclosure structure:
+- **feature** — production-quality implementation expected. `/devlyn:resolve --spec` runs the full pipeline (PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY).
+- **spike** — exploratory work; deliverable is learning, evidence, or a disposable demo. `/devlyn:resolve --spec` proceeds but VERIFY's quality bar is relaxed for code that the spike says is throwaway.
+- **prototype** — between feature and spike. Production-shape but not production-grade. CLEANUP runs; VERIFY's quality bar is stricter than spike, looser than feature.
 
-```
-docs/
-├── VISION.md              # Layer 1: Strategic WHY (~50-100 lines)
-│                          # Orientation only. auto-resolve never reads this.
-│
-├── ROADMAP.md             # Layer 2: Tactical index (what, in what order)
-│                          # Thin table linking to detail specs. auto-resolve never reads this.
-│
-└── roadmap/               # Layer 3: Auto-resolve-ready specs
-    ├── phase-1/
-    │   ├── _overview.md   # Phase-level context and goals
-    │   ├── 1.1-xxx.md     # Self-contained spec → direct auto-resolve input
-    │   └── 1.2-yyy.md
-    ├── phase-2/
-    │   └── ...
-    ├── decisions/         # Architecture decision records (why we chose X over Y)
-    │   └── 001-xxx.md
-    └── backlog/           # Ideas acknowledged but not yet phased
-        └── ...
-```
+The user picks the kind during elicitation. Default = feature when not specified. `--quick` infers from the goal text (verbs like "explore", "investigate", "spike" → spike; "implement", "ship", "add" → feature).
+</spec_kind_escape_hatch>
 
-**Core principle**: auto-resolve reads ONE spec file. That file is self-contained. Vision and Roadmap exist for humans and for this ideation skill — not for the implementation pipeline.
+## PHASE 0: PARSE + ROUTE
 
-Read `references/templates/` for the exact format of each document type when generating output.
+1. Parse flags from `<elicit_config>`:
+   - `--quick`
+   - `--from-spec <path>`
+   - `--project`
+   - `--spec-dir <path>` (default `docs/specs/`)
+   - `--engine MODE` (default `claude`)
+   - `--spec-id <id>` — optional explicit id; auto-generated when absent.
 
-## Conversation Protocol
+2. Engine pre-flight: `_shared/engine-preflight.md`.
 
-Ideation is a dialogue, not a monologue. The user will come in with scattered ideas, incomplete thoughts, and implicit assumptions. Your job is to draw out accurate, complete information through back-and-forth conversation — not to fill gaps with guesses.
+3. Mode dispatch:
+   - default → PHASE 1.
+   - `--quick` → PHASE 1Q (single turn assume-and-confirm).
+   - `--from-spec` → PHASE 1F (lint + normalize external).
+   - `--project` → PHASE 1P (project decomposition).
 
-<conversation_rhythm>
-**Ask, don't assume.** When information is missing or ambiguous, ask targeted questions. Generating a spec with wrong assumptions is worse than asking one more question. The user wants accuracy (documents they can trust and hand to auto-resolve), not speed.
+## PHASE 1: ELICITATION (default mode)
 
-**2-3 questions at a time, max.** Don't dump a 10-item questionnaire. Ask the most important unknowns, get answers, then ask the next batch based on what you learned. Each exchange should build on the last.
+Prompt body: `references/elicitation.md`. Adapter prepended.
 
-**Summarize after each exchange.** After the user shares information, reflect it back concisely: "So what I'm hearing is [X]. Is that right, or am I missing something?" This catches misunderstandings early — much cheaper than rewriting specs later.
+The elicitation agent:
+1. Reads the user's initial goal from `<elicit_config>`.
+2. Identifies the missing engineering decisions (input shape, output shape, success command, scope boundary, constraints).
+3. Asks 1-2 focused questions per turn until each blank is filled or the user accepts an inferred default.
+4. Maintains a running draft spec in `.devlyn/ideate-draft.md` (run-scoped, gitignored).
+5. Stops when the structural lint passes AND user confirms, or 8 turns elapsed.
 
-**Confirm before phase transitions.** Before moving from FRAME → EXPLORE, or EXPLORE → CONVERGE, summarize the current state and ask if the user is ready to move on. Never silently transition.
+Structural lint (inline check, no script needed):
+- Frontmatter has `id`, `title`, `kind`, `status: planned`.
+- `## Context` non-empty (≥ 1 sentence).
+- `## Requirements` has ≥ 1 `- [ ]` bullet.
+- `## Out of Scope` present (may list "none" if truly nothing).
+- `## Verification` has either ≥ 1 named command OR an explicit "all Requirements are pure-design" note.
 
-**Capture energy, then clarify.** When the user is excited and throwing out rapid-fire ideas, don't interrupt the flow with structural questions. Let them finish, capture everything, then come back with targeted clarifications: "Love these ideas. A few things I want to make sure I get right: [questions]."
+After lint passes:
+1. Write `<spec-dir>/<id>-<slug>/spec.md` (the spec).
+2. Generate `<spec-dir>/<id>-<slug>/spec.expected.json` from the spec's `## Verification` block + any `forbidden_patterns` / `required_files` / `forbidden_files` / `max_deps_added` the conversation surfaced.
+3. Run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate the verification carrier shape. If exit 2, fix the carrier and re-run.
+4. Print: `spec ready — /devlyn:resolve --spec <spec-path>`.
 
-**Track what's confirmed vs. assumed.** Mentally separate facts the user stated from inferences you made. When generating documents, only write confirmed facts. Flag assumptions explicitly: "I'm assuming [X] based on [Y] — correct?"
-</conversation_rhythm>
+## PHASE 1Q: QUICK MODE
 
-## Detecting the Mode
+Single-turn assume-and-confirm. Prompt body: see `references/elicitation.md` § "Quick mode".
 
-Before starting, identify what the user needs:
+1. AI synthesizes a spec from the one-line goal.
+2. AI surfaces an explicit "Assumptions made" section listing every inferred decision.
+3. User responds with "go" / "fix X" / "no, different".
+4. On "go": write spec + spec.expected.json + lint + announce.
+5. On "fix X": apply correction, re-show, ask again. Maximum 3 correction rounds before escalating to default mode.
 
-| Signal | Mode | Approach |
-|--------|------|----------|
-| No existing docs, new project or idea | **Greenfield** | Full flow: Frame → Explore → Converge → Document |
-| Existing docs, user adds new ideas | **Expand** | Lighter Frame, focused Explore on new area, merge into existing phases |
-| Existing docs, user describes a single bug/improvement/idea | **Quick Add** | Read existing roadmap, create one item spec, add row to ROADMAP.md |
-| One specific feature needs deep thought | **Deep-dive** | Intensive Explore on one topic, output 1-3 specs |
-| User shares links/resources to process | **Research-first** | Lead with Explore (research synthesis), then standard flow |
-| Existing roadmap, user wants to reprioritize | **Replan** | Read existing docs, focus on Converge, update documents |
+## PHASE 1F: FROM-SPEC MODE
 
-**Tie-breaks when a request matches two modes:** choose the narrowest mode that satisfies the request. Quick Add wins over Expand when the user has one concrete item in mind. Research-first wins over Deep-dive when links or resources are the primary input. Deep-dive wins over Expand when one topic specifically needs depth. Replan is chosen only when priority or order changes are explicit. If two modes still look equally plausible after applying these rules, present the top two to the user and let them pick — silently choosing one wastes the session if the other was right.
+Prompt body: `references/from-spec-mode.md`.
 
-Announce the detected mode and confirm before proceeding.
+1. Read the external spec at `<path>`.
+2. Lint structure (same checks as default mode).
+3. Identify missing pieces (no frontmatter, missing sections, malformed Verification block).
+4. Apply structural fixes only — do NOT reshape Requirements / Out-of-Scope content. The user's substantive intent is preserved.
+5. Generate `spec.expected.json` if absent (best-effort from `## Verification` block).
+6. Write the normalized spec back to `<spec-dir>/<id>-<slug>/` (preserves original at `<path>` untouched unless user passes `--in-place`).
+7. Lint pass → announce. Lint fail → surface the unfixable issue and exit non-zero.
 
-### Expand Mode Detail
+## PHASE 1P: PROJECT MODE
 
-Expand is the most common mode after initial setup — the user already has Vision + Roadmap and wants to add new capabilities. This mode requires careful integration with existing documents.
+Prompt body: `references/project-mode.md`.
 
-**On entry:**
-1. Read `docs/VISION.md`, `docs/ROADMAP.md`, and existing phase `_overview.md` files to understand the established context
-2. Scan existing item specs to understand what's built and what's planned
-3. **Run the Archive Pass** (see Context Archiving below) before summarizing. Summarizing a stale roadmap to the user wastes the exchange — they'll see "Phase 1 has 4 items" when really all 4 are already Done and the phase should be collapsed.
-4. Summarize your understanding: "Here's what exists: [phases, item count, current status]. You want to add [new area]. Does this expand an existing phase or warrant a new one?"
+1. AI elicits a project description (longer Q&A — multi-feature scope warrants more turns).
+2. AI decomposes the project into 3-7 feature specs. Each feature is independently shippable; cross-feature dependencies surface explicitly in the spec frontmatter `depends_on:` field.
+3. AI writes `<spec-dir>/plan.md` — index file with: project name, decomposition rationale, list of feature specs with id + title + dependency, suggested implementation order.
+4. AI writes one `<spec-dir>/<id>/spec.md` + `<spec-dir>/<id>/spec.expected.json` per feature, each lint-validated.
+5. Announce: `project ready — N specs at <spec-dir>/. Start with /devlyn:resolve --spec <first-spec-path>`.
 
-**During ideation:**
-- FRAME is lighter — the vision already exists, focus on framing the NEW area only
-- EXPLORE focuses specifically on the new capability and how it integrates with existing features
-- CONVERGE must consider dependencies on existing items, not just new ones
+`/devlyn:resolve` consumes one spec at a time; the user works through `plan.md`'s suggested order. Multi-feature parallel runs are Mission 2 work.
 
-**During document generation:**
-- Don't overwrite existing VISION.md unless the user explicitly wants to update it
-- Continue numbering from existing IDs (if Phase 2 exists with 2.1-2.4, new items start at 2.5 or create Phase 3)
-- Add new rows to ROADMAP.md, don't regenerate the whole table
-- New item specs can reference existing items in their Dependencies section
-- If new items change the meaning of existing items, flag this: "Adding [X] may affect the scope of existing item [Y]. Should we update [Y]'s spec?"
+## State management
 
-In Replan mode: read existing docs first, **run the Archive Pass** (see Context Archiving below) before any reprioritization — you can't sensibly reorder work that's already finished — then focus on the Converge phase to reprioritize what remains. The Archive Pass also surfaces Backlog items whose Revisit date has passed, which are natural candidates when replanning.
+ideate is conversational, not pipeline-staged. State lives in:
+- `.devlyn/ideate-draft.md` — current draft spec during elicitation (run-scoped, gitignored).
+- `<spec-dir>/<id>-<slug>/` — final output (committed to repo by user choice).
 
-### Quick Add Mode Detail
-
-Quick Add is for when the user has a single concrete idea, bug report, or improvement — they don't need a full ideation session, just a new entry in the roadmap. This is the most common trigger for misuse: the request looks like a simple fix, so the temptation is to implement it. Don't. Capture it.
-
-**On entry:**
-1. Read `docs/ROADMAP.md` and relevant phase `_overview.md` files
-2. **Run the Archive Pass first** (see Context Archiving below). Do this *before* you figure out where the new item goes — a stale roadmap will mislead phase selection and ID numbering. If the pass moves a phase out of the active section, the new item's natural home may change.
-3. Identify the best-fit phase for the new item (or suggest a new phase if it doesn't fit)
-4. Determine the next available item ID (e.g., if phase 2 has 2.1-2.4, the new item is 2.5)
-
-**Workflow (minimal — no full Frame/Explore/Converge):**
-1. Confirm the idea with the user: "I'll add this as [item title] in Phase [N]. That sound right?"
-2. Ask 1-2 clarifying questions if the requirement is unclear (skip if the user gave enough detail)
-3. Generate the item spec following `references/templates/item-spec.md`
-4. Add a row to `docs/ROADMAP.md`
-5. Output confirmation: the file path and a suggested auto-resolve command
-
-**Example output:**
-```
-Added: docs/roadmap/phase-2/2.5-back-to-review-button.md
-
-To implement:
-/devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-2/2.5-back-to-review-button.md"
-```
-
-### Context Archiving
-
-ROADMAP.md is the tactical index. Done work should move to a collapsed `## Completed` block at the bottom, not clutter the active view. Item spec files stay on disk at `docs/roadmap/phase-N/{id}.md` — only the index row moves.
-
-#### The Archive Pass (conditional)
-
-Run this at the start of Quick Add / Expand / Replan **only when** `docs/ROADMAP.md` contains at least one phase where every row is `Done`. A quick scan tells you within seconds. Skip the pass otherwise — running it on a roadmap with no fully-done phases is no-op bookkeeping that burns the user's turn.
-
-When it runs:
-
-1. Read `docs/ROADMAP.md`.
-2. For each phase where every row is `Done`: cut the `## Phase N: …` heading and table, move it into a new or existing `## Completed` block at the bottom as a `<details>` entry (see format below). Use the latest completion date found in item spec frontmatter (`completed:`), or today's if absent. Item count is the row count.
-3. Individual `Done` rows inside an otherwise-active phase stay put — mixed phases show recent wins alongside open work.
-4. Scan the Backlog table; surface any row whose `Revisit` date has passed as a replan candidate (don't auto-promote — that's a conversation).
-5. Scan `docs/roadmap/decisions/` for `accepted` decisions whose reasoning is visibly contradicted by newly-Done work; raise them as open questions rather than silently editing.
-6. One-sentence report of what was archived, then proceed with the mode's main work. Skip the report if nothing changed.
-
-**Completed block format** (place at the bottom of ROADMAP.md, below Decisions):
-
-```markdown
-## Completed
-<details>
-<summary>Phase 1: Foundation (completed 2026-04-15, 4 items)</summary>
-
-| # | Feature | Completed |
-|---|---------|-----------|
-| 1.1 | Auth & Onboarding | 2026-02-10 |
-| 1.2 | Order Management | 2026-03-05 |
-| 1.3 | Inventory Tracking | 2026-03-28 |
-| 1.4 | Customer Directory | 2026-04-15 |
-</details>
-```
-
-If the `## Completed` section already exists and you're archiving an additional phase, append a new `<details>` block — don't rewrite existing ones.
-
-#### Outdated decisions
-
-When a decision becomes wrong because the world changed under it:
-- Don't delete it — set its `status:` to `superseded` in the decision file's frontmatter and add a one-line pointer to the replacement decision record.
-- This preserves the reasoning history for future reference, which matters more than a tidy decisions table.
-
-## Phase 1: FRAME
-
-<phase_goal>Establish problem space boundaries before exploring solutions.</phase_goal>
-
-The biggest risk in ideation is premature convergence — jumping to solutions before understanding the problem. This phase prevents that.
-
-Establish through conversation:
-1. **Job-to-be-Done**: In one sentence — "When [situation], [user] wants to [motivation], so they can [outcome]." Capture this before anything else. If the user cannot produce it, that is itself the finding — pause and explore the situation until the sentence exists. A bare problem statement without this frame is a state description, not a job, and downstream specs built from it will describe system behavior instead of customer progress.
-2. **Constraints**: What can't change? (tech stack, timeline, existing commitments)
-3. **Success criteria**: How will we know this worked? (outcomes, not outputs)
-4. **Anti-goals**: What are we explicitly NOT trying to do?
-
-Adapt to what the user has already shared — if they came in with a clear vision, this might be a quick confirmation. If the idea is fuzzy, spend more time here. Ask conversationally, not as a rigid questionnaire.
-
-Don't write documents yet. The output of this phase is a shared mental model between you and the user.
-
-## Phase 2: EXPLORE
-
-<phase_goal>Systematically expand the possibility space before narrowing it.</phase_goal>
-
-This is the creative core — the phase that should take the most conversational turns. The user chose to ideate with AI because they want perspectives, research, and creative expansion they wouldn't get alone.
-
-<use_parallel_tool_calls>
-EXPLORE often needs several independent lookups: web search for prior art, doc fetches, repo greps for existing patterns. When tool calls have no dependencies on each other, issue them in parallel in the same response. Spawn subagents in parallel when fanning out across distinct research topics. Only chain calls that depend on a previous call's output. Pace research across turns rather than front-loading every lookup before the user has framed direction — EXPLORE is dialogue-driven, parallel is just for the lookups inside any single turn.
-</use_parallel_tool_calls>
-
-<research_protocol>
-When relevant, actively research before and during brainstorming:
-- **Existing solutions**: What's already out there? (web search, documentation)
-- **Technical feasibility**: Can this be built within the constraints? Where are the hard parts?
-- **Patterns and prior art**: How have similar problems been solved?
-- **Market/user context**: Who else needs this? What do they currently use?
-- **Evidence discipline**: Treat prior art as source-backed only when verified by a fetched link or documentation the user can open. If a pattern is inferred from memory or analogy, label it `[UNVERIFIED]` inline and do not present it as market fact. The CHALLENGE rubric's NO GUESSWORK axis fires hard on unlabeled claims that look authoritative but are actually recall.
-
-Not every ideation needs all of these — a personal side project doesn't need market research. Judge what's relevant and use subagents for parallel research when multiple topics need investigation.
-</research_protocol>
-
-<multi_perspective>
-For each major idea, consider it from at least three angles:
-- **User**: Is this actually useful? Does it solve a real pain?
-- **Technical**: Is this buildable? Where are the complexity hotspots?
-- **Strategic**: Does this align with the vision? Does it create leverage for future work?
-
-Add perspectives as relevant:
-- **Risk**: What could go wrong? What are the dependencies?
-- **Business**: Does this create value? Is the effort justified?
-- **Accessibility**: Is this inclusive? Who gets left out?
-</multi_perspective>
-
-<creative_expansion>
-When the conversation needs energy or the user feels stuck:
-- **"What if..."** — Remove a constraint and see what emerges
-- **Analogy transfer** — "How does [adjacent domain] solve this?"
-- **Inversion** — "What's the worst version? Now invert it."
-- **10x thinking** — "If this needed 10x users, what changes?"
-- **Minimum viable magic** — "What's the smallest thing that would feel magical?"
-
-Use these naturally in conversation, not as a mechanical checklist.
-</creative_expansion>
-
-As ideas accumulate, periodically synthesize:
-```
-Here's where we are:
-- Core ideas: [list]
-- Open questions: [list]
-- Tensions to resolve: [list]
-- Research still needed: [list]
-```
-
-This prevents circular conversations and gives the user a clear sense of progress.
-
-## Phase 3: CONVERGE
-
-<phase_goal>Transform exploration into decisions.</phase_goal>
-
-When the user signals readiness or exploration winds down naturally, shift to convergence.
-
-### Theme Clustering
-Group related ideas into coherent themes:
-```
-Theme A: [name]
-- Ideas: 1, 3, 7
-- Value: [why this matters]
-- Risk: [what could go wrong]
-```
-
-### Prioritization
-Use value x feasibility as the primary framework:
-- **High value + High feasibility** → Phase 1 (build first)
-- **High value + Low feasibility** → Phase 2+ (build after foundation exists)
-- **Low value + High feasibility** → Backlog (if time permits)
-- **Low value + Low feasibility** → Cut
-
-Present as a recommendation — the user makes the final call on ordering.
-
-### Sequencing
-Within each phase:
-- **Dependencies**: What must exist before what?
-- **Risk ordering**: Build uncertain things first (fail fast)
-- **Value delivery**: Each phase should deliver usable value, not just infrastructure
-
-### Architecture Decisions
-Surface decisions that affect multiple items — technology choices, data model, integration approaches, UX patterns. For each: **What** was decided, **Why** (tradeoffs), and **What alternatives** were considered. These become decision records.
-
-### Internal draft — do not show the user yet
-
-At this point you have an internal convergence draft: themes, phases, items, decisions. **Do not present it to the user yet.** Phase 3.5 CHALLENGE runs next, and the user will see exactly one summary — the post-challenge plan, with visibility into what CHALLENGE changed. Showing the pre-challenge draft first and then changing it after challenge creates a two-round confirmation loop that burns the user's trust.
-
-## Phase 3.5: CHALLENGE
-
-<phase_goal>Apply a strict 5-axis rubric to the internal convergence draft, then present one post-challenge summary to the user for confirmation. Always runs.</phase_goal>
-
-<thinking_effort>
-Engage maximum thinking effort here — both the solo rubric pass and, if enabled, the Codex pass. Use extended thinking ("ultrathink") when reading each item, applying each axis, and producing revisions. The default Claude failure mode in self-review is nodding along to the draft you just produced; shallow thinking here is the exact pattern this phase exists to prevent.
-
-Before finalizing the rubric pass, verify your findings against the rubric one more time: every flagged item should have a specific Quote, a failing axis, and a concrete revision — not a vague concern.
-</thinking_effort>
-
-### The rubric — single source of truth
-
-Read `references/challenge-rubric.md` before starting. That file is the only definition of the 5 axes, the finding format, the hard rule about respecting explicit user intent, and the good-vs-bad examples. Both the solo pass and the Codex pass use the same rubric; do not re-derive it inline.
-
-### Solo pass (always runs)
-
-Apply the rubric to the internal convergence draft. Produce findings in the format specified in `challenge-rubric.md` (Severity / Quote / Axis / Why / Fix).
-
-For Quick Add with one new item, one solo pass is enough. For a full greenfield or expand plan, run the rubric once, revise, and run it again on the revision. If a third pass would be needed, the plan has structural problems that belong in the user-facing summary as open questions — surface them rather than iterating further.
-
-### Codex critic pass (engine-routed)
-
-**If `--engine auto`** (default): Codex runs the CHALLENGE rubric pass automatically as critic.
-
-Call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "read-only"`, `workingDirectory: <project root>`. The `prompt` parameter is built from the packaged plan + the inlined rubric + the appended Codex instructions. Codex has no filesystem access to this project, so everything it needs travels in the prompt.
-
-**Step 1 — Package the post-solo plan.** Build the prompt per `references/codex-critic-template.md` (section order, rubric inlining, Codex-specific instructions all live there verbatim — follow the template structure, fill in the plan/findings sections).
-
-**Step 2 — Reconcile.** Merge the two finding lists:
-- Same finding from both → keep the more specific wording, mark "confirmed by both"
-- Codex-only → prefix `[codex]` in internal notes so the user-facing summary can attribute correctly
-- Solo-only → keep as-is
-- Conflicts (solo says X, Codex says not-X) → record both, do not silently pick one; if material, surface as an open question in the user-facing summary
-
-If Codex raised CRITICAL or HIGH findings the solo pass missed, apply the fixes to the plan before presenting the user-facing summary — unless fixing would change something the user explicitly confirmed, in which case follow the rubric's "Respect explicit user intent" rule.
-
-**Do not loop.** One Codex pass is enough. If the result is still FAIL after reconciliation, the plan has structural problems that belong in the user-facing summary as open questions rather than further iteration.
-
-**If `--engine codex`**: Role reversal — Codex built the plan, so Claude runs the solo CHALLENGE pass and that is the only pass. Do not also run Codex on CHALLENGE — builder and critic should always be different models. Skip this section.
-
-**If `--engine claude`**: No Codex calls. The solo pass is the only pass.
-
-### Respect explicit user intent
-
-The rubric is a quality lens, not an override. If a finding conflicts with something the user explicitly and clearly asked for, follow the "Hard rule" section in `challenge-rubric.md`: record the finding, **do not silently rewrite the plan**, and surface it as an open question in the summary below. The user makes the call.
-
-### User-facing summary (the first and only time the user sees the plan)
-
-After the rubric pass(es), present the post-challenge plan to the user for confirmation. This is the first time the user sees the converged plan — by design, so they see a rubric-checked result rather than a draft that immediately gets revised.
-
-Format:
-```
-Vision: [one sentence]
-Phases: [N] phases, [M] total items
-Phase 1 ([theme]): [items with brief descriptions]
-Phase 2 ([theme]): [items]
-Key decisions: [list]
-Deferred: [items with reasons]
-
-## CHALLENGE results
-
-Solo pass: [N findings, M applied]
-Codex pass: [N findings, M applied]   ← only on --engine auto
-
-Changes applied during CHALLENGE:
-- [item]: [what changed and which axis triggered it]
-
-Open questions for you (rubric flagged something you explicitly asked for):
-- [item]: rubric says [finding]; you asked for [original]; here is the tradeoff — proceed as-is, or adopt the alternative?
-```
-
-Get explicit confirmation before proceeding to DOCUMENT.
-
-### Quick Add mode
-
-For single-item additions, run one solo rubric pass on just the new item. Even then do not skip — single-item additions are exactly where overengineering and workarounds slip in unnoticed, because the lack of surrounding context makes a bad item look self-contained and harmless.
-
-## Engine Routing for FRAME / EXPLORE / CONVERGE / DOCUMENT
-
-**If `--engine codex`**: Phases 1-3 and Phase 4 are delegated to Codex. For each phase, call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "workspace-write"`, and the phase instructions + user context as the prompt. Use `sessionId` to maintain conversational context across phases (note: sandbox/fullAuto only apply on the first call). Claude remains the orchestrator — it reads Codex's output, manages the conversation with the user (confirmation prompts, clarifying questions), and routes findings between phases.
-
-**If `--engine auto` or `--engine claude`**: All planning phases use Claude directly (current behavior). Claude's ambiguous intent handling and writing quality benchmarks favor it for planning tasks.
-
-## Phase 4: DOCUMENT
-
-<phase_goal>Generate the three-layer document set.</phase_goal>
-
-Read the templates before generating:
-- `references/templates/vision.md` — VISION.md format
-- `references/templates/roadmap.md` — ROADMAP.md index format
-- `references/templates/item-spec.md` — Auto-resolve-ready spec format
-- `references/templates/decision.md` — Architecture decision record format
-
-### Generation Order
-1. `docs/VISION.md` — from Phase 1 framing + Phase 3 decisions
-2. `docs/roadmap/decisions/` — one file per architecture decision
-3. `docs/roadmap/phase-N/_overview.md` — phase-level context
-4. `docs/roadmap/phase-N/{id}-{name}.md` — one per roadmap item
-5. `docs/ROADMAP.md` — index linking to everything above
-
-### Item Spec Quality
-
-Each Layer 3 spec is the direct input to auto-resolve. Its quality determines implementation quality.
-
-<spec_quality_criteria>
-**Requirements section** — becomes auto-resolve's done-criteria:
-- Testable: a test can assert it OR a human can verify in under 30 seconds
-- Specific: not "handles errors well" but "returns 400 with `{error: 'missing_field', field: 'email'}`"
-- Scoped: tied to this item only, not aspirational
-
-**Context section** — 2-3 sentences maximum. Just enough for auto-resolve to understand WHY without loading the full vision.
-
-**Out of Scope** — explicitly states what this item does NOT do. This is what prevents auto-resolve from over-building, which is one of its most common failure modes.
-
-**Constraints** — technical constraints with reasoning. Auto-resolve respects constraints significantly better when it understands the motivation behind them.
-</spec_quality_criteria>
-
-If an item is too vague to write specific requirements, it needs more exploration (revisit Phase 2 for that item) or should be split into smaller items.
-
-### Handling Existing Documents
-In **Expand** and **Replan** modes:
-- Read existing documents first
-- Merge new items into the existing phase structure
-- Preserve existing items (don't overwrite or reorder without confirmation)
-- Update ROADMAP.md index to include new entries
-
-### Output Summary
-After generating all documents:
-```
-Documents created:
-- docs/VISION.md
-- docs/ROADMAP.md
-- docs/roadmap/phase-1/_overview.md
-- docs/roadmap/phase-1/1.1-xxx.md
-- docs/roadmap/phase-1/1.2-yyy.md
-- docs/roadmap/decisions/001-xxx.md
-[total: N files]
-```
-
-## Phase 5: BRIDGE
-
-<phase_goal>Connect documents to the implementation pipeline.</phase_goal>
-
-After document generation, output the implementation guide:
-
-```
-## Implementation
-
-To implement each item:
-/devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-1/1.1-xxx.md — read the spec file for requirements, constraints, and scope boundaries"
-
-Recommended order (respecting dependencies):
-1. 1.1 [name] — no dependencies
-2. 1.2 [name] — depends on 1.1
-3. 1.3 [name] — depends on 1.1
-...
-
-After completing each item:
-1. Update status in the item spec frontmatter (status: done)
-2. Update ROADMAP.md status column
-```
-
-The auto-resolve prompt explicitly tells the build agent to read the spec file — this ensures done-criteria are adopted from the spec rather than generated from scratch, preserving the ideation context through to implementation.
-
-## Language
-
-Generate all documents in the language the user communicates in. If the user mixes languages, match their primary language for prose and keep technical terms in English.
+No `pipeline.state.json` here — that's resolve's surface.