@juicesharp/rpiv-pi 0.12.6 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.12.6",
+  "version": "0.13.0",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": [
     "pi-package",

package/skills/design2/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: design2
+description: Design features through architectural grill-me + per-slice grill-me with Slice Contract specification. Walks a decision-DAG to exhaustion at architectural scope, then per slice. Produces design artifacts in thoughts/shared/designs/ — contracts, not code. For complex multi-component features touching 6+ files across multiple layers. Always requires a research artifact.
+argument-hint: "[research artifact path] [discover artifact path] [task description]"
+---
+
+# Design
+
+You are tasked with designing how code will be shaped for a feature or change. This grill-me variant walks a decision-DAG architecturally to fix architectural decisions, decomposes the feature into vertical slices, then walks each slice's decision-DAG to fix Slice Contracts. The design produces contracts — no code generation. The plan skill synthesizes contract-fulfilling code at plan-time.
+
+**How it works**:
+- Read input and key source files into context (Step 1)
+- Spawn targeted research agents for depth analysis (Step 2)
+- Architectural grill-me — walk the decision-DAG to exhaustion, fixing architectural decisions (Step 3)
+- Decompose into vertical slices holistically (Step 4)
+- Per-slice grill-me — interview the developer per slice and draft Slice Contracts (Step 5)
+- Verify cross-slice integration consistency (Step 6)
+- Finalize the design artifact (Step 7)
+- Review and iterate with the developer (Step 8)
+
+The final artifact is plan-compatible. Plan extracts Slice Contracts and Q/A pairs to dispatch per-slice pattern-finder agents and synthesize contract-fulfilling code.
+
+## Step 1: Input Handling
+
+When this command is invoked:
+
+1. **Read research artifact**:
+
+   **Research artifact provided** (argument contains a path to a `.md` file in `thoughts/`):
+   - Read the research artifact FULLY using the Read tool WITHOUT limit/offset
+   - Extract: Summary, Code References, Integration Points, Architecture Insights, Developer Context, Open Questions
+   - **Read the key source files from Code References** into the main context — especially hooks, shared utilities, and integration points the design will depend on. Read them FULLY. This ensures you have complete understanding before proceeding.
+   - These become starting context — no need to re-discover what exists
+   - Research Developer Context Q/As = inherited decisions (record in Decisions, never re-ask); Open Questions = starting ambiguity queue, filtered by dimension in Step 3
+   - If a discover artifact is also provided, read it for additional discovery context
+
+   **No arguments provided**:
+   ```
+   I'll design a feature iteratively from a research artifact. Please provide:
+
+   `/skill:design2 [research artifact] [discover] [task description]`
+
+   Research artifact is required. Discover and task description are optional, in any order.
+   ```
+   Then wait for input.
+
+2. **Read any additional files mentioned** — tickets, related designs, existing implementations. Read them FULLY before proceeding.
+
+## Step 2: Targeted Research
+
+This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).
+
+1. **Dispatch all agents below as parallel `subagent` tool calls in the same assistant message** — multiple tool_use blocks in one response, not one call per turn. Each call matches this shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Wait for all to return before proceeding.
+
+   - Use **codebase-pattern-finder** to find existing implementations to model after — the primary template for code shape
+   - Use **codebase-analyzer** to understand HOW integration points work in detail
+   - Use **integration-scanner** to map the wiring surface — inbound refs, outbound deps, config/DI/event registration
+   - Use **precedent-locator** to find similar past changes in git history — what commits introduced comparable features, what broke, and what lessons apply to this design. Only when `git_commit` is available (not `no-commit`); otherwise skip and note "git history unavailable" in Verification Notes.
+
+   **Novel work** (new libraries, first-time patterns, no existing codebase precedent):
+   - Add **web-search-researcher** for external documentation, API references, and community patterns
+   - Instruct it to return LINKS with findings — include those links in the final design artifact
+
+   Agent prompts should focus on (labeled by target agent):
+   - **codebase-pattern-finder**: "Find the implementation pattern I should model after for [feature type]"
+   - **codebase-analyzer**: "How does [integration point] work in detail"
+   - **integration-scanner**: "What connects to [component] — inbound refs, outbound deps, config"
+
+   NOT: "Find all files related to X" — that's discovery's job, upstream of this skill.
+
+2. **Read all key files identified by agents** into the main context — especially the pattern templates you'll model after.
+
+3. **Wait for ALL agents to complete** before proceeding.
+
+4. **Analyze and verify understanding**:
+   - Cross-reference research findings with actual code read in Step 1
+   - Identify any discrepancies or misunderstandings
+   - Note assumptions that need verification
+   - Determine true scope based on codebase reality
+
+## Step 3: Architectural Grill-Me
+
+The architectural grill-me is a relentless interview that walks the design's decision-DAG to exhaustion. It absorbs the dimension sweep, holistic self-critique, and grounded-questions checkpoint into one phase. The dimensions seed the DAG; the walk produces fixed architectural decisions recorded with full Q/A trace.
+
+### Decision-DAG seeded by dimensions
+
+Six architectural dimensions seed the initial DAG roots (each contributes 0-N root questions):
+
+- **Data model** — types, schemas, entities
+- **API surface** — signatures, exports, routes
+- **Integration wiring** — mount points, DI, events, config
+- **Scope** — in / explicitly deferred
+- **Verification** — tests, assertions, risk-bearing behaviors
+- **Performance** — load paths, caching, N+1 risks
+
+Add **migration** as a seventh dimension if the feature changes persisted schema.
+
+For each dimension, walk Step 2 findings, inherited research Q/As, and carried Open Questions. Classify findings as **simple decisions** (one valid option, obvious from codebase — record in Decisions with `file:line` evidence, do not ask) or **DAG nodes** (multiple valid options, conflicting patterns, scope questions, novel choices — feed into the grill-me walk). Inherited research Q/As land as simple; Open Questions filter by dimension — architectural survives, implementation-detail defers.
+
+Pre-validate every option against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence.
+
+### Grill-me walk
+
+Walk the DAG dependency-topologically. The lead question is the topologically earliest one — the node with the most downstream dependents. Each answer becomes a fixed architectural decision recorded in the artifact's Decisions section with full Q/A trace.
+
+**Question rules** (preserved from grounded-questions pattern):
+- Reference real findings with `file:line` evidence
+- Present concrete options (not abstract choices)
+- Pull a DECISION from the developer, not confirm what you already found
+- Ask ONE question at a time. Wait for the answer before asking the next.
+
+**Question patterns by ambiguity type** (preserved):
+
+- **Pattern conflict**: "Found 2 patterns for [X]: [pattern A] at `file:line` and [pattern B] at `file:line`. They differ in [specific way]. Which should the new [feature] follow?"
+- **Missing pattern**: "No existing [pattern type] in the codebase. Options: (A) [approach] modeled after [external reference], (B) [approach] extending [existing code at file:line]. Which fits the project's direction?"
+- **Scope boundary**: "The [research/description] mentions both [feature A] and [feature B]. Should this design cover both, or just [feature A] with [feature B] deferred?"
+- **Integration choice**: "[Feature] can wire into [point A] at `file:line` or [point B] at `file:line`. [Point A] matches the [existing pattern] pattern. Agree, or prefer [point B]?"
+- **Novel approach**: "No existing [X] in the project. Options: (A) [library/pattern] — [evidence/rationale], (B) [library/pattern] — [evidence/rationale]. Which fits?"
+
+**Question format choice** (preserved):
+- **`ask_user_question` tool** — when your question has 2-4 concrete options from code analysis. The user can always pick "Other" for free-text.
+- **Free-text with ❓ Question: prefix** — when the question is open-ended and options can't be predicted (discovery, "what am I missing?", corrections).
+
+**Per-question check** (absorbs holistic self-critique):
+After each answer, before the next question, ask yourself:
+- Does this answer reveal new DAG branches that weren't seeded by the dimensions?
+- Does this answer conflict with a prior answer? If so, surface the conflict explicitly (see Evidence-driven reopen below).
+- Does this answer cover a multi-faceted concern that should split into sub-questions?
+
+Add new branches to the DAG when discovered. Resolve conflicts proactively. Split multi-faceted nodes.
+
+### FIXED-decision rule with evidence-driven reopen
+
+Decisions stay FIXED within a single branch traversal — no oscillation. When a downstream branch surfaces evidence that an upstream answer was wrong-framed, the grill-me PROACTIVELY surfaces the conflict as one explicit reopen question:
+
+> "❓ Question: Decision D1 (use pattern A at `file:line`) was framed assuming [X], but D5 just established [Y] which means D1 needs to be reopened. Do you want to: (A) revise D1 in light of D5, (B) revise D5's premise, or (C) accept the inconsistency for now and document the tension in Verification Notes?"
+
+This activates the existing "no revisiting unless the developer explicitly asks" clause proactively. Mirrors the cascade-revision pattern from later phases moved earlier in the lifecycle.
+
+### Two-gate exit
+
+The grill-me phase exits when BOTH gates hold:
+
+- **Gate 1 (depth)**: Every DAG node has a recorded answer or simple-decision classification. No unresolved children.
+- **Gate 2 (breadth)**: Coverage check — every dimension is addressed. Silent-resolved is valid (a dimension whose findings all classified as simple decisions counts as addressed). Skipped-unchecked does NOT count as addressed.
+
+If Migration was added as the seventh dimension, it gates Gate 2 conditionally on persisted-schema changes.
+
+### Classify each response
+
+**Decision** (e.g., "use pattern A", "yes, follow that approach"):
+- Record in Decisions section under heading `### D<N>: <title>` (sequential D1, D2, … — IDs are mandatory; plan2 references them by ID) with full Q/A trace inline (Ambiguity → Explored → Decision format).
+- Update `architectural_qa_count` frontmatter counter.
+
+**Correction** (e.g., "no, there's a third option you missed", "check the events module"):
+- Spawn targeted rescan: **codebase-analyzer** on the new area (max 1-2 agents).
+- Merge results. Update DAG and re-walk affected branches.
+
+**Scope adjustment** (e.g., "skip the UI, backend only", "include tests"):
+- Record in Developer Context (non-Q/A interaction). Adjust Scope section.
+
+### Exit gate
+
+After both Gate 1 and Gate 2 hold, present a brief design summary (under 15 lines):
+
+```
+Design: [feature name]
+Approach: [1-2 sentence summary of chosen architecture]
+
+Decisions:
+- [Decision 1]: [choice] — modeled after `file:line`
+- [Decision 2]: [choice]
+- [Decision 3]: [choice]
+
+Scope: [what's in] | Not building: [what's out]
+Slices: [N] preliminary slices identified | Files: [N] new, [M] modified
+```
+
+Use the `ask_user_question` tool to confirm. Question: "[Summary from design brief above]. Ready to proceed to decomposition?". Header: "Design". Options: "Proceed" (Decompose into vertical slices, then per-slice grill-me); "Adjust decisions" (Revisit one or more architectural decisions above); "Change scope" (Add or remove items from the building/not-building lists).
+
+## Step 4: Feature Decomposition
+
+After the architectural grill-me exit gate confirms, decompose the feature into vertical slices. Each slice is a self-contained unit: types + impl + wiring for one concern. Decomposition is one shot — define ALL slices, dependencies, and ordering before per-slice grill-me begins.
+
+1. **Decompose holistically** — define ALL slices, dependencies, and ordering before any per-slice grill-me runs:
+
+   ```
+   Feature Breakdown: [feature name]
+
+   Slice 1: [name] — [what this slice delivers]
+     Files: path/to/file.ext (NEW), path/to/file.ext (MODIFY)
+     Depends on: nothing (foundation)
+
+   Slice 2: [name] — [what this slice delivers]
+     Files: path/to/file.ext (NEW), path/to/file.ext (MODIFY)
+     Depends on: Slice 1
+
+   Slice 3: [name] — [what this slice delivers]
+     Files: path/to/file.ext (NEW)
+     Depends on: Slice 2
+   ```
+
+2. **Slice properties**:
+   - End-to-end vertical: each slice is a complete cross-section of one concern (types + impl + wiring)
+   - ~512-1024 tokens per slice contract block
+   - Sequential. 5a/5b drafting may be done internally for sibling slices in any order, but Step 5c micro-checkpoints are strictly one slice at a time — never batched, never parallel from the developer's view.
+   - Foundation first when applicable: if the feature has shared types/interfaces, they're typically Slice 1
+   - Encode `depends_on` per slice — drives both per-slice grill-me parallelization eligibility and plan's parallel-phase eligibility
+
+3. **Confirm decomposition** using the `ask_user_question` tool. Question: "[N] slices for [feature]. Slice 1: [name] (foundation). Slices 2-N: [brief]. Approve decomposition?". Header: "Slices". Options: "Approve" (Proceed to per-slice grill-me); "Adjust slices" (Reorder, merge, or split slices before grill-me); "Change scope" (Add or remove files from the decomposition).
+
+4. **Create skeleton artifact** — immediately after decomposition is approved:
+   - Determine metadata: filename `thoughts/shared/designs/YYYY-MM-DD_HH-MM-SS_topic.md`, repository name from git root, branch and commit from the git context injected at the start of the session (fallbacks: "no-branch" / "no-commit"), designer from the injected User (fallback: "unknown")
+   - Write skeleton using the Write tool with `status: in-progress` in frontmatter
+   - **Include all prose sections filled** from Steps 1-3: Summary, Requirements, Current State Analysis, Scope, Decisions (architectural Q/A trace inline), Desired End State, File Map, Ordering Constraints, Verification Notes, Performance Considerations, Migration Notes, Pattern References, Developer Context, References
+   - **Slice Contracts section**: one `### Slice N: [name] — Contract` heading per slice from the decomposition, each with empty placeholders for the seven required contract fields plus a `#### Q/A` placeholder
+   - **Design History section**: list all slices with `— pending` status
+   - This is the living artifact — all subsequent writes use the Edit tool
+
+   **Artifact template sections** (all required in skeleton):
+
+   - **Frontmatter**: standard metadata (date, designer, git_commit, branch, repository, topic, tags, `status: in-progress`, research_source, last_updated, last_updated_by) plus contract-validation counters initialized at skeleton write: `architectural_qa_count: <Step 3 final total>`, `per_slice_qa_count: 0` (5d increments), `slice_count: <N>`, `unresolved_qa_count: 0` (sentinel; two-gate exit guarantees), `unresolved_contract_count: <slice_count>` (5d decrements; 0 to complete), `slices: [{name, contract_status: pending, qa_count: 0, files, depends_on}]` (status → approved/revised in 5d), `contract_fields_required: [inputs, outputs, types, integration_anchors, invariants, verification_hooks]`.
+   - **# Design: [Feature Name]**
+   - **## Summary**: 2-3 sentences — what we're building and the chosen architectural approach. Settled decision, not a discussion.
+   - **## Requirements**: Bullet list from ticket, research, or developer input.
+   - **## Current State Analysis**: What exists now, what's missing, key constraints. Include `### Key Discoveries` with `file:line` references, patterns to follow, constraints to work within.
+   - **## Scope**: `### Building` — concrete deliverables. `### Not Building` — developer-stated exclusions AND likely scope-creep vectors (alternative architectures not chosen, nearby code that looks related but shouldn't be touched).
+   - **## Decisions**: `### D<N>: <title>` per architectural decision (sequential D1, D2, … — IDs are mandatory; plan2 references them by ID). Complex: Ambiguity → Explored (Option A/B with `file:line` + pro/con) → Decision. Simple: just state decision with evidence. Each `### D<N>:` includes inline Q/A trace per decision.
+   - **## Slice Contracts**: `###` per slice with `Slice N: [name] — Contract` heading. Required field bullets in order: Inputs, Outputs, Types/Data Model, Integration anchors, Invariants, Verification hooks, Files touched. `#### Q/A` subsection embeds the per-slice grill-me transcript. No implementation code. (Filled progressively in Step 5d.)
+   - **## Desired End State**: Usage examples showing the feature in use from a consumer's perspective — concrete code, not prose.
+   - **## File Map**: `path/to/file.ext  # NEW/MODIFY — purpose` per line. Stays at artifact level as the canonical flat list. NEW/MODIFY labels also appear inside each slice contract's Files touched field (slice-scoped duplicate is intentional).
+   - **## Ordering Constraints**: What must come before what. What can run in parallel. Drives plan's phase eligibility.
+   - **## Verification Notes**: Carry forward from research — known risks, build/test warnings, precedent lessons. Format as verifiable checks (commands, grep patterns, visual inspection). plan converts these to success criteria.
+   - **## Performance Considerations**: Any performance implications or optimizations.
+   - **## Migration Notes**: If applicable — existing data, schema changes, rollback strategy, backwards compatibility. Empty if not applicable.
+   - **## Pattern References**: one entry per reference, formatted as `path/to/similar.ext:line-range — Slice <N> (<slice name>): <one-line reason>`. Each entry MUST tag at least one slice it serves; references that serve multiple slices repeat across multiple lines, one tag per line. Plan dispatches `codebase-pattern-finder` per slice using the references tagged for that slice.
+   - **## Developer Context**: Non-Q/A interactions — corrections (rescans triggered by codebase-analyzer correction path), scope adjustments, mid-walk redirects. Q/A pairs live inside `## Decisions` (architectural) and `## Slice Contracts` `#### Q/A` (per-slice).
+   - **## Design History**: Slice contract approval/revision log. `- Slice N: [name] — pending/approved as drafted/revised: [what changed]`. plan ignores this section AND the `#### Q/A` subsections inside Slice Contracts.
+   - **## References**: Research artifacts, tickets, similar implementations.
+
+   **Slice contract block format in skeleton**:
+   - `### Slice N: [name] — Contract` heading
+   - Required field bullets with TBD placeholders:
+     - `**Inputs**: TBD`
+     - `**Outputs**: TBD`
+     - `**Types/Data Model**: TBD`
+     - `**Integration anchors**: TBD`
+     - `**Invariants**: TBD`
+     - `**Verification hooks**: TBD`
+     - `**Files touched**: TBD`
+   - `#### Q/A` heading with empty body
+   - Filled in Step 5d via Edit when the slice's contract is approved.
+
+## Step 5: Per-Slice Grill-Me
+
+Walk each slice's decision-DAG to draft its Slice Contract. Each per-slice grill-me runs after holistic decomposition is locked. The developer is a serial resource — Step 5c micro-checkpoints are strictly one slice at a time. Slices are NEVER batched at the checkpoint, regardless of `depends_on` independence.
+
+**For each slice in the decomposition (strictly sequential at the developer checkpoint):**
+
+### 5a. Draft contract internally
+
+**Commitments before drafting.** Before populating contract fields, scan the slice for any choice where two reasonable implementers reading the same spec would diverge in their code — those divergence points are architectural commitments, not local logic. Pull each as a Q/A in the slice's `#### Q/A` before drafting. If you catch yourself choosing between alternatives during drafting, stop and pull the Q/A first.
+
+Walk the slice's decision-DAG. Reuse the grounded-questions pattern from Step 3, scoped to this slice. The slice's contract walk seeds DAG roots from the seven required fields:
+
+- **Inputs** — what does this slice receive? Function/route parameters with types, request shapes, event payloads.
+- **Outputs** — what does this slice produce? Return types, response shapes, side effects.
+- **Types/Data Model** — what new entities/schemas does this slice introduce?
+- **Integration anchors** — where does this slice mount? `file:line` for DI calls, route registration, event subscription, hook installation.
+- **Invariants** — what cross-cutting properties must this slice preserve? Transaction boundaries, ordering guarantees.
+- **Verification hooks** — how do we prove the contract holds? Test names with intent, grep patterns, observable behaviors.
+- **Files touched** — which files does this slice create or modify? `path (NEW)` or `path:line-range (MODIFY)`.
+
+Walk the DAG dependency-topologically. Resolve each node before drafting the dependent contract field. If additional context is needed, spawn a targeted **codebase-analyzer** agent (max 1).
+
+**Context grounding** (after slice 2): Before drafting, re-read the artifact's Slice Contracts section for prior slices. The artifact is the source of truth — generate contract anchors that align with what's already declared, not what you remember from conversation.
+
+### 5b. Self-verify slice contract
+
+Before presenting to the developer, cross-check the drafted contract and produce a structured summary:
+
+```
+Self-verify Slice N contract:
+- Architectural decisions: [OK / VIOLATION: contract violates decision X — fix applied]
+- Cross-slice: [OK / CONFLICT: integration anchors at file:line clash with prior slice — fix applied]
+- Research: [OK / WARNING: research constraint Y not satisfied by verification hooks — fix applied]
+- Required fields: [all populated / missing: <field list>]
+```
+
+If violations found: fix in-place before presenting. Include the self-verify summary in the 5c micro-checkpoint presentation.
+
+### 5c. Developer micro-checkpoint
+
+Present a **condensed contract review** — the developer reviews the contract shape, not every field's prose. For each contract field, show:
+
+1. **Summary** (1-2 sentences): what this slice does, what pattern it follows, what it connects to
+2. **Inputs/Outputs**: the surface — types, parameters, return shapes
+3. **Integration anchors**: `file:line` mount points — the wiring decisions
+4. **Verification hooks**: test names + grep patterns — how we'll know it works
+
+**Omit**: full prose for Types/Data Model (named only), Invariants summary line only, Files touched as a path list.
+
+**If the developer asks to see the full contract**, show it inline — exception, not default.
+
+Use the `ask_user_question` tool to confirm. Question: "Slice [N/M]: [slice name] — [files affected]. [1-line contract summary]. Approve?". Header: "Slice [N]". Options: "Approve" (Lock this slice's contract, write to artifact, proceed to slice [N+1]); "Revise this slice" (Adjust contract before proceeding — describe what to change); "Rethink remaining slices" (This slice reveals a design issue — revisit decomposition).
+
+**Checkpoint cadence**:
+- Every slice is presented individually. No batching, no grouping — one slice per `ask_user_question` call. The developer reviews and approves each slice's contract on its own before the next slice's 5a draft begins.
+
+### 5d. Incorporate feedback
+
+**Approve**: Lock this slice's contract and **Edit the artifact immediately**:
+1. Edit the slice's `### Slice N: [name] — Contract` block to replace TBD placeholders with the drafted contract fields
+2. Append the per-slice grill-me transcript to the slice's `#### Q/A` subsection (one bullet per Q/A pair with `file:line` evidence)
+3. Update the Design History section: `- Slice N: [name] — approved as drafted`
+4. Increment frontmatter `per_slice_qa_count` by the number of new Q/As; decrement `unresolved_contract_count` by 1; update the `slices: [{contract_status}]` entry for this slice from `pending` to `approved`
+- Proceed to next slice
+
+**Revise**: Update contract per developer feedback. Re-run self-verify (5b). Re-present the same slice (5c). The artifact is NOT touched — only "Approve" writes to the artifact.
+
+**Rethink**: Developer spotted a design issue. If a previously approved slice's contract is affected, flag the conflict and offer cascade revision — developer decides whether to reopen (if yes, Edit artifact entry). Update decomposition (add/remove/reorder remaining slices) and confirm before continuing. If the conflict invalidates an architectural decision from Step 3, surface as evidence-driven reopen at architectural scope.
+
+## Step 6: Integration Verification
+
+After all slices' contracts are drafted, review cross-slice consistency:
+
+1. **Present integration summary** (under 15 lines):
+   ```
+   Integration: [feature name] — [N] slice contracts complete
+
+   Slices: [brief list of slice names and file counts]
+   Cross-slice: [integration anchors consistent / outputs feed inputs / no orphan invariants]
+   Research constraints: [all satisfied by verification hooks / N gaps noted]
+   ```
+
+2. **Verify research constraints**: Check each Precedent & Lesson and Verification Note from the research artifact against each slice's verification hooks. List satisfaction status per constraint.
+
+3. **Verify cross-slice contract consistency**:
+   - Outputs of upstream slices match Inputs of downstream slices that depend on them
+   - Integration anchors don't conflict (two slices claiming the same `file:line` for incompatible mount points)
+   - No invariant declared in one slice is contradicted by another slice's contract
+
+4. **Self-verify and proceed**. If steps 2–3 above pass, proceed directly to Step 7 finalize. If a research constraint is unsatisfied, an integration anchor conflicts, or a slice's outputs don't match a downstream slice's inputs, return to that slice's grill-me (Step 5) — do NOT ask the developer to choose; reopening the affected slice is the only correct action.
+
+## Step 7: Finalize Design Artifact
+
+The artifact was created as a skeleton in Step 4 and filled progressively in Step 5d. This step verifies completeness and finalizes.
+
+1. **Verify every slice contract is fully specified**: Every `### Slice N:` heading has populated Inputs, Outputs, Types/Data Model, Integration anchors, Invariants, Verification hooks, and Files touched fields. Empty TBD placeholders fail. If any are still empty, return to per-slice grill-me for that slice.
+
+2. **Verify frontmatter counters**:
+   - `unresolved_qa_count == 0`
+   - `unresolved_contract_count == 0`
+   - `slice_count ==` actual slice count in `## Slice Contracts`
+   - `architectural_qa_count` matches Q/A pairs in `## Decisions`
+   - `per_slice_qa_count` matches Q/A pairs across all `#### Q/A` subsections
+
+   If any check fails, return to the relevant grill-me phase. Do NOT flip status to complete.
+
+3. **Update frontmatter** via Edit:
+   - Set `status: complete`
+   - Update `last_updated` to current date
+   - Update `last_updated_by` to the User from the injected git context (fallback: "unknown")
+   - Update `slices: [{contract_status}]` array — every entry should be `approved` or `revised`
+
+4. **Verify template completeness**: Ensure all 16 sections from the template reference in Step 4 are present and filled. Edit to fix any gaps.
+
+5. **Slice Contract block format reminder**:
+   - Heading: `### Slice N: [name] — Contract`
+   - Required field bullets in order: Inputs, Outputs, Types/Data Model, Integration anchors, Invariants, Verification hooks, Files touched
+   - File entries inside Files touched carry `(NEW)` or `:line-range (MODIFY)` labels
+   - `#### Q/A` subsection logs the per-slice grill-me transcript (one bullet per Q/A pair with `file:line` evidence)
+   - No code blocks — contract fields are prose specs
+
+## Step 8: Review & Iterate
+
+1. **Present the design artifact location**:
+   ```
+   Design artifact written to:
+   `thoughts/shared/designs/[filename].md`
+
+   [N] architectural decisions fixed, [M] slices with full contracts.
+   [A] architectural Q/As, [P] per-slice Q/As across the decomposition.
+
+   Please review and let me know:
+   - Are the architectural decisions correct?
+   - Do the slice contracts capture the design you envision?
+   - Any missing integration points or edge cases?
+
+   When ready, run `/skill:plan2 thoughts/shared/designs/[filename].md` to synthesize per-slice code into phases.
+   ```
+
+2. **Handle follow-up changes**:
+   - Use the Edit tool to update the design artifact in-place
+   - Update frontmatter: `last_updated` and `last_updated_by`
+   - Add `last_updated_note: "Updated [brief description]"` to frontmatter
+   - If the change affects an architectural decision, return to Step 3 (architectural grill-me reopen)
+   - If the change affects a slice contract, return to Step 5 (per-slice grill-me for that slice)
+   - Update affected frontmatter counters
+
+## Guidelines
+
+1. **Be Architectural**: Design fixes architectural decisions and shapes contracts; plans synthesize code from contracts. Every architectural decision and every contract field must be grounded in `file:line` evidence from the actual codebase.
+
+2. **Be Interactive**: Don't produce the full design in one shot. Walk the architectural decision-DAG to exhaustion first, get buy-in on the approach, decompose into slices, THEN walk each slice's contract DAG.
+
+3. **Be Complete**: Slice contracts must be unambiguous enough that plan can synthesize copy-pasteable code from them. No TBD placeholders, no "implementer decides" cop-outs. If you can't fully specify a contract field, an architectural ambiguity wasn't resolved — return to Step 3.
+
+4. **Be Skeptical**: Question vague requirements. If an existing pattern doesn't fit the new feature, say so and propose alternatives. Don't force a pattern where it doesn't belong.
+
+5. **Resolve Everything**: No unresolved questions in the final artifact. If something is ambiguous, ask during the architectural grill-me or per-slice grill-me. The design must be complete enough that plan can synthesize phase code by reading contracts + Q/A pairs.
+
+6. **Present Condensed, Persist Complete**: Micro-checkpoints show the developer condensed contract reviews. The artifact always contains full contract fields. If the developer asks to see the full contract, show it — but never default to walls of contract prose in checkpoints.
+
+7. **No code in design**: Source code does NOT appear in the design artifact. The Slice Contracts section specifies inputs/outputs/anchors/invariants/verification, never implementation. Plan synthesizes implementation from the contract.
+
+## Subagent Usage
+
+| Context | Agents Spawned |
+|---|---|
+| Default (research artifact provided) | codebase-pattern-finder, codebase-analyzer, integration-scanner, precedent-locator |
+| Novel work (new library/pattern) | + web-search-researcher |
+| During architectural grill-me (correction path) | targeted codebase-analyzer for the new area (max 1-2) |
+| During per-slice grill-me (5a clarification) | targeted codebase-analyzer when contract has `file:line` ambiguity (max 1) |
+
+When agents are searching for different things, dispatch them as parallel `subagent(...)` tool calls in the same assistant message — multiple tool_use blocks in one response, not one call per turn. Call shape: `subagent({ agent: "<agent-name>", task: "<task>", context: "fresh", artifacts: false })`. Each agent runs in isolation — provide complete context in the prompt, including specific directory paths when the feature targets a known module. Don't write detailed prompts about HOW to search — just tell it what you're looking for and where.
+
+## Important Notes
+
+- **Always chained**: This skill requires a research artifact produced by the research skill. There is no standalone design mode.
+- **File reading**: Always read research artifacts and referenced files FULLY (no limit/offset) before spawning agents
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read input files first (Step 1) before spawning agents (Step 2)
+  - ALWAYS wait for all agents to complete before architectural grill-me (Step 3)
+  - ALWAYS exit architectural grill-me via the two-gate check (depth + breadth) before decomposition (Step 4)
+  - ALWAYS complete holistic decomposition before per-slice grill-me (Step 5)
+  - ALWAYS create the skeleton artifact immediately after decomposition approval (Step 4)
+  - NEVER make architectural commitments during 5a drafting — the orchestrator drafts, the developer decides; pull divergent-implementer choices as Q/As first
+  - NEVER leave a slice contract with TBD placeholders after the slice is approved — fill via Edit in Step 5d
+- NEVER skip the architectural grill-me or per-slice grill-me — developer input on architectural decisions and contract shape is the highest-value signal in the design process
+- NEVER edit source files — all output goes into the design document, not the codebase. This skill produces a contract document, not implementation. Source file editing is implement's job; code synthesis is plan's job.
+- **Contract is source of truth** — if the Slice Contracts section conflicts with Decisions prose, the contract fields win. Update the prose to match.
+- **Checkpoint recordings**: Architectural Q/As live inline in `## Decisions` (per-decision Q/A trace). Per-slice Q/As live inside each slice's `#### Q/A` subsection in `## Slice Contracts`. `## Developer Context` records non-Q/A interactions (corrections, scope adjustments, rescans). Plan reads contract fields; plan IGNORES `#### Q/A` subsections (extends the Design History "plan ignores" annotation).
+- **Frontmatter consistency**: Always include frontmatter, use snake_case for multi-word fields, keep tags relevant. Frontmatter counters (`architectural_qa_count`, `per_slice_qa_count`, `slice_count`, `unresolved_qa_count`, `unresolved_contract_count`, `slices: [...]`, `contract_fields_required`) are machine-validatable preflight signals plan uses to STOP on incomplete designs.
+- CC auto-loads CLAUDE.md files when agents read files in a directory — no need to scan for them explicitly
+
+## Common Design Patterns
+
+- **New Features**: types first → backend logic → API surface → UI last. Research existing patterns first. Each slice's verification hooks include test surface alongside implementation surface.
+- **Modifications**: Read current file FULLY in Step 1. Per-slice contracts capture only the modified portions in Files touched (`path:line-range (MODIFY)`) and Integration anchors. Check integration points for side effects.
+- **Database Changes**: schema/migration → store/repository → business logic → API → client. Migration becomes a seventh dimension in Step 3's seed list. Include rollback strategy in the migration slice's Verification hooks.
+- **Refactoring**: Document current behavior first via research. Plan incremental backwards-compatible changes — each slice contract preserves an invariant ("existing behavior preserved").
+- **Novel Work**: Include approach comparison in Decisions Q/A trace. Ground in codebase evidence OR web research. Get explicit developer sign-off via the architectural grill-me exit gate BEFORE decomposing into slices.

package/skills/discover/SKILL.md

@@ -23,6 +23,8 @@ Before Step 1, create a todo list tracking every step below (Step 1 through Step
 
 ## Steps
 
+**Subagent mode (non-interactive)**: When this skill is invoked from another skill via a subagent (e.g., `research` auto-running discover from a free-text prompt), there is no developer to ask. Skip Step 5 (Developer Checkpoint) entirely, write the artifact (Step 6), and as your final output return ONLY the absolute path to the questions artifact. All other steps run unchanged.
+
 ### Step 1: Read Mentioned Files
 
 - If the user mentions specific files (tickets, docs, JSON), read them FULLY first

package/skills/plan2/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: plan2
+description: Synthesize implementation plans from design artifacts. One design slice maps 1:1 to one plan phase, synthesized in topological order, with per-phase Success Criteria. Produces plans in thoughts/shared/plans/. Use after design.
+argument-hint: [design artifact path]
+---
+
+# Write Plan
+
+You are tasked with synthesizing implementation plans from design artifacts. The design artifact contains all architectural decisions, per-slice Slice Contracts, and Q/A pairs — but NO source code. Your job is to synthesize contract-fulfilling code one phase at a time in topological order. Each design slice maps 1:1 to a plan phase; the plan artifact is phase-shaped from skeleton-write onward and consumed by `/skill:implement` phase by phase.
+
+## Step 1: Read Design Artifact
+
+When this command is invoked:
+
+1. **Determine input mode**:
+
+   **Design artifact provided** (path to a `.md` file in `thoughts/shared/designs/`):
+   - Read the design artifact FULLY using the Read tool WITHOUT limit/offset
+   - Extract: Slice Contracts, Decisions (architectural Q/A trace), File Map, Ordering Constraints, Verification Notes, Performance Considerations, Migration Notes, Scope, Pattern References
+   - Architectural decisions and slice contracts are settled — do not re-evaluate them
+   - **Two-pass STOP gate**:
+     - **Pass A**: Frontmatter `unresolved_qa_count == 0`. If > 0 or missing, STOP — tell the developer to return to design (architectural grill-me or per-slice grill-me has unresolved Q/As).
+     - **Pass B**: Frontmatter `unresolved_contract_count == 0` AND every slice in `## Slice Contracts` has populated Inputs, Outputs, Types/Data Model, Integration anchors, Invariants, Verification hooks, Files touched (no TBD placeholders). If any contract is incomplete, STOP — tell the developer to return to design Step 5 for the affected slice.
+   - **Pre-restructure designs** (no `slices:` frontmatter array): treat as legacy. STOP with: "This design predates the contract restructure. Re-run /skill:design2 to produce a contract-format artifact." Do NOT attempt to plan a legacy design.
+
+   **No arguments provided**:
+   ```
+   I'll synthesize an implementation plan from a design artifact. Please provide the path:
+
+   `/skill:plan2 thoughts/shared/designs/2026-01-20_09-30-00_feature.md`
+
+   Run `/skill:design2` first to produce the design artifact. There is no standalone path.
+   ```
+   Then wait for input.
+
+2. **Read any additional files mentioned** in the design's References — research documents, tickets. Read them FULLY for context.
+
+3. **Read each Pattern Reference**: For every `path/to/similar.ext:line-range` in the design's `## Pattern References`, read the cited range FULLY. These are the templates plan synthesizes against.
+
+4. **Anchor reverification gate** — runs every plan2 invocation, unconditionally. Source code drifts between runs; a prior `last_updated_note` is an audit entry, not a skip signal. Re-read every anchor every time. For every `file:line` (or `file:line-range`) cited in each slice's `Integration anchors` and `Files touched` fields under `## Slice Contracts`, read the cited range using the Read tool with the line offset.
+   - **If the cited range still contains the symbol/text the contract describes** (e.g., the schema, interface, function, or call site referenced in prose): proceed.
+   - **If the line range has drifted** (the cited symbol now lives at a different line range in the same file): use the Edit tool to update every occurrence of the stale `file:line` in the design artifact to the correct line range, and bump frontmatter `last_updated` + `last_updated_by` + append a dated audit entry to `last_updated_note` of the form `"<YYYY-MM-DD HH:MM>: anchor reverification adjusted <slice-id>:<old-range> → <new-range> in <file>"`.
+   - **If the cited symbol is gone** (renamed, deleted, or moved): STOP — return the developer to /skill:design2 Step 5. Do NOT guess at a corrected anchor.
+
+## Step 2: Per-Phase Synthesis Loop
+
+Synthesis runs one phase at a time in topological order (`depends_on` of the corresponding design slice). One design slice = one plan phase. Each iteration produces complete, copy-pasteable code for one slice's contract written under `## Phase N` in the plan artifact.
+
+1. **Write the phase-shaped skeleton** to `thoughts/shared/plans/YYYY-MM-DD_HH-MM-SS_description.md`:
+   - Filename format: `YYYY-MM-DD_HH-MM-SS_description.md` (kebab-case description, ticket prefix optional). Examples: `2026-01-08_14-30-00_ENG-1478-parent-child-tracking.md`, `2026-01-08_14-30-00_improve-error-handling.md`.
+   - One phase per design slice, in topological order (`depends_on`). Skeleton includes everything EXCEPT code blocks: frontmatter, Overview, Desired End State, What We're NOT Doing, one `## Phase N: [slice name]` section per slice with `### Overview` (one sentence + parallelism note from `depends_on`), `### Changes Required:` placeholders sourced from the design's `Files touched` and Verification hooks (no code), and `### Success Criteria:` (Automated + Manual placeholders per the Success Criteria Conversion section), Performance Considerations, Migration Notes, References, and a `## Plan History` section listing each phase as `— pending`.
+   - Skeleton frontmatter MUST include: `slice_count` (informational, from design), `phase_count` (= `slice_count`), `unresolved_phase_count` (initialized to `phase_count`, decrements as each phase's synthesis is approved).
+
+2. **Topological order**: Sort slices by `depends_on` so every slice's prerequisites are already synthesized and written to the artifact before its own synthesis begins.
+
+3. **Parallel pre-fetch of pattern-finder for every slice (Step 2.0)**.
+
+   **Hard rule — fan-out, not loop.** Emit ONE assistant message that contains N `subagent(...)` tool calls, where N = `slice_count`. Every slice's pattern-finder dispatches in the SAME message as a separate `tool_use` block. The model that emits this message MUST list all N tool calls before sending. If you find yourself sending one tool call per assistant turn, STOP — you are violating Step 2.0; restart the message with all N blocks together.
+
+   Forbidden anti-patterns:
+   - One `subagent(...)` call per assistant message, looping through slices serially.
+   - Mixing pattern-finder dispatches with synthesis or other tool calls.
+   - Dispatching pattern-finder for "the next slice" inside the topological loop (Step 2a) — pattern-finder is pre-fetched ONCE for ALL slices before the loop starts.
+
+   Required shape — one assistant message with N parallel blocks (illustration for N=3; scale to actual `slice_count`):
+
+   ```
+   subagent({ agent: "codebase-pattern-finder", task: "<contract excerpt for Slice 1>", context: "fresh", artifacts: false })
+   subagent({ agent: "codebase-pattern-finder", task: "<contract excerpt for Slice 2>", context: "fresh", artifacts: false })
+   subagent({ agent: "codebase-pattern-finder", task: "<contract excerpt for Slice 3>", context: "fresh", artifacts: false })
+   ```
+
+   Each `task` prompt includes that slice's contract excerpt verbatim:
+
+   ```
+   "Find code templates I can model the [slice name] implementation after.
+
+   Contract excerpt from the design artifact:
+     Inputs: <slice Inputs field verbatim>
+     Outputs: <slice Outputs field verbatim>
+     Types/Data Model: <slice Types field verbatim>
+     Files touched: <slice Files touched field verbatim>
+   Change classification: <NEW module | narrow-edit | replacement | config>
+   Pattern References from design: <paths from ## Pattern References that name this slice>
+   Integration anchors: <slice Integration anchors verbatim>
+
+   Return paste-ready snippets that match BOTH the shape and the contract."
+   ```
+
+   Wait for ALL pattern-finder calls to return before entering the topological loop. Cache results keyed by slice name. The synthesis loop consumes from this cache — do NOT re-dispatch pattern-finder per slice.
+
+**For each slice in topological order:**
+
+### 2a. Per-phase spot-checks, conditional dispatches, synthesize
+
+- **Spot-check anchors**: Re-read every `file:line` in this slice's `Integration anchors` and `Files touched` (the artifact-level reverification ran once in Step 1.4; this catches drift introduced by an earlier slice's MODIFY in this same plan run). If a cited symbol moved, Edit the design artifact to correct the line range. If gone, STOP — return to /skill:design2 Step 5 for this slice.
+- **Read prior phases' synthesized code from the artifact**: For each slice in this slice's `depends_on`, read its `## Phase N` section in the in-progress plan. Imports and types come from the actually-emitted code, not the contract abstraction.
+- **Conditional dispatches** (run in parallel as `subagent(...)` blocks in one assistant message; only those that apply):
+  - Any `Files touched` entry is MODIFY → dispatch **integration-scanner** for that file/symbol. Task: "Map current callsites and wiring for [symbol] at [file]. List inbound references that must be preserved or updated, outbound dependencies the new code will inherit, and any config / event registration the symbol participates in."
+  - Change classification is replacement (closure / function rewrite > 20 lines) → dispatch **precedent-locator**. Task: "Find prior commits in this repository that performed similar [closure / function] rewrites at comparable size. Return commit SHAs, file paths, and any follow-up fix commits."
+  - An Integration anchor's surrounding code shape isn't obvious from the contract → dispatch **codebase-analyzer** (max 1) for that anchor.
+  - Pattern-finder cache returned no patterns AND Pattern References are empty → dispatch **web-search-researcher** for external documentation.
+- Wait for all dispatched agents to return before synthesizing.
+
+**MODIFY test-cascade.** When integration-scanner reports inbound references inside test files (`*.test.ts`, `*.spec.ts`) for any symbol this slice modifies, those test files become additional MODIFY entries in this slice's `### Changes Required:`. Synthesize updated test code that matches the slice's new signatures so existing test imports do not break. These cascaded test entries are independent of the slice's Verification hooks (which produce NEW test files) — these are pre-existing tests whose imports / type expectations would otherwise break under the modification.
+
+After agents return, **synthesize contract-fulfilling code in the orchestrator** for this single slice:
+- Use pattern-finder cache snippets as templates
+- Apply this slice's contract Inputs/Outputs/Types/Integration anchors as the spec
+- Honor architectural Q/A guardrails from `## Decisions` and per-slice Q/A constraints from the slice's `#### Q/A`
+- Resolve imports against prior slices' actually-emitted exports (read from the artifact), not contract prose
+- For MODIFY slices, preserve every callsite and wiring relationship reported by integration-scanner
+- For replacement-class slices, reference precedent-locator findings as the structural template
+- The code MUST fulfill the contract; the orchestrator must NOT invent new design decisions
+
+**Tests as first-class entries.** Every test name in this slice's `Verification hooks` becomes a `#### N. <test-name>` entry under `### Changes Required:` with a real Vitest code block that satisfies the copy-pasteable contract (Step 2b). Co-locate `*.test.ts` next to the production source. Grep-pattern hooks → `expect(...)` matchers; observable-behavior hooks → assertions on `render(width)` / return shapes / factory-driver outcomes. If the test cannot be synthesized from the contract alone, STOP and return to /skill:design2 Step 5 — never emit a placeholder.
+
+### 2b. Self-verify slice
+
+Cross-check this slice's synthesized code and produce a structured summary:
+
+```
+Self-verify Slice N: [name]
+- Contract fulfillment: [OK / VIOLATION: contract field X not satisfied]
+- Q/A guardrails: [OK / VIOLATION: architectural decision Y violated]
+- Cross-slice: [OK / CONFLICT: imports from Slice M reference symbols not emitted]
+- Research: [OK / WARNING: Verification Note Z not satisfied]
+- Copy-pasteable: [OK / VIOLATION: code block <file> not paste-ready]
+- Decision traceability: [OK / VIOLATION: Decision <D-id> "<title>" has no matching code at <plan-file>:<line-range>]
+```
+
+**Decision traceability** (mechanical map, not prose). For each entry under the design's `## Decisions` section that this slice is responsible for implementing (a Decision is owned by a slice when its specifics are encoded in any of that slice's contract fields), identify the synthesized lines that implement the Decision's specifics. Record the mapping inline in the self-verify summary as `<D-id>: <plan-file>:<line-range>`. If any owned Decision has no matching code in this slice, the synthesis violated the design — re-synthesize. The point is to grep design Decisions against synthesized output, not to restate them in prose.
+
+**Enumerated-set fidelity**. When a slice's contract enumerates a closed set (discriminated-union kinds, mode names, action types, key-binding names, error codes), the synthesized code emits exactly that set. Count the design's enumeration; count the plan's emission; mismatch in either direction is a violation. If synthesis discovers the set is insufficient, STOP and return to /skill:design2 Step 5 — do not silently expand it.
+
+**Copy-pasteable contract** (happy-path enforcement). You are writing real implementation, not a sketch. Every code block MUST:
+
+- Be paste-into-editor ready — `npm run check` (Biome + `tsc --noEmit`) passes against it. Every value concrete, every signature fully typed, every import resolves to a real export, every literal fully populated (no `{ ... }`, no `[ ... ]`).
+- Stand alone per file — a reader needs nothing beyond the code block and its imports.
+- Include the entire body of any function / method / closure the contract says is replaced — emit the whole thing, never a description.
+- Have function bodies that compute the value their name and contract describe. Hardcoded returns (`return false`, `return constant`, `return param.length`) are stubs unless the contract says the function is a constant.
+- Resolve every identifier to a declaration that precedes it in execution order. No TDZ, no forward-reference of `let` / `const` from inside an arrow that runs at construction time.
+- Contain no deferred-work comment: `// TODO`, `// FIXME`, `// would need`, `// handled at <X>`, `// see <Y>`, `// for now`, `// later`, `// reset method needed`. If you catch yourself writing such a comment, the synthesis is incomplete — STOP and surface the gap.
+- For any block whose contract says a function, closure, switch, or method is replaced, the AFTER state is the executable body itself, not a comment outline of it. Diff narration (`// BEFORE: ... // AFTER: ...`) may precede the block but never substitutes for it. Cases, branches, and statements the contract enumerates appear as real `case` / `if` / statements, not commented placeholders.
+- A symbol marked `// REMOVED: <name>` must not appear in any AFTER body in the same phase. Grep the phase for `<name>`; any surviving reference falsifies the REMOVED claim.
+
+If a contract's scope can't fit a single complete code block, the slice was under-decomposed — STOP and return to /skill:design2 Step 5.
+
+**Self-heal on violation**: If any line above reports VIOLATION / CONFLICT / WARNING, re-synthesize the affected file once and re-run self-verify. If the second self-verify still reports a violation, STOP and surface the specific violation to the developer with the slice name, file, and the failing check — request guidance before proceeding.
+
+### 2c. Write to artifact
+
+**One phase, one cycle.** Steps 2a → 2b → 2c are a single transaction for ONE phase. Complete this phase's 2c artifact write before starting phase N+1's 2a. Never:
+- Use the `Write` tool on the artifact (only `Edit`)
+- Batch edits across multiple phase sections in one tool call
+- Synthesize multiple phases' code in memory and then write them together
+- Rewrite the entire artifact "for consistency" — the skeleton is already consistent
+
+Each `Edit` call targets exactly one `## Phase N` section. If a single phase needs multiple Edits (one per file in `### Changes Required:`), issue them sequentially to disjoint regions of that phase's section.
+
+On clean self-verify (all OK), Edit the artifact in place:
+1. For each file in this phase, replace the phase's `### Changes Required:` placeholders with the synthesized code blocks.
+2. Append to `## Plan History`: `- Phase N: [name] — synthesized`.
+3. Decrement frontmatter `unresolved_phase_count` by 1.
+4. Proceed to the next phase in topological order.
+
+**Use this template structure** (the artifact's final shape; phases are written into the skeleton at Step 2.1 and progressively filled by 2c):
+
+```markdown
+---
+date: [Current date and time with timezone in ISO format]
+planner: [User from injected git context]
+git_commit: [Current commit hash]
+branch: [Current branch name]
+repository: [Repository name]
+topic: "[Feature/Task Name]"
+tags: [plan, relevant-component-names]
+status: ready
+design_source: "[path to design artifact]"
+slice_count: [S, copied from design frontmatter — informational]
+phase_count: [P, equal to slice_count]
+unresolved_phase_count: [decrements as each phase synthesizes in Step 2; 0 means synthesis complete]
+last_updated: [Current date in YYYY-MM-DD format]
+last_updated_by: [User from injected git context]
+---
+
+# [Feature/Task Name] Implementation Plan
+
+## Overview
+
+[Brief description of what we're implementing and why. Reference design artifact.]
+
+## Desired End State
+
+[From design artifact's Desired End State / Summary — what "done" looks like and how to verify it]
+
+## What We're NOT Doing
+
+[From design artifact's Scope → Not Building]
+
+## Phase 1: [Descriptive Name]
+
+### Overview
+[What this phase accomplishes — fulfills slice [S]; parallelism note from `depends_on`]
+
+### Changes Required:
+
+#### 1. [Component/File Group]
+**File**: `path/to/file.ext`
+**Changes**: [Summary of changes]
+**Fulfills**: Slice [S] contract Inputs/Outputs/Anchors
+
+```[language]
+// Synthesized from Slice [S] contract; pattern source: <pattern-finder file:line>
+```
+
+#### 2. [Test name from slice's Verification hooks]
+**File**: `path/to/file.test.ext`
+**Fulfills**: Slice [S] Verification hook: `<hook test name>`
+
+```[language]
+// Synthesized from Slice [S] Verification hook; pattern source: <existing *.test.ext file:line>
+```
+
+(One Changes Required entry per Verification hook test name.)
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] `npm run check` passes
+- [ ] `npm test` passes
+
+#### Manual Verification:
+- [ ] [From design's Verification Notes — observable behaviors not expressible as tests]
+
+---
+
+## Phase 2: [Descriptive Name]
+
+[Similar structure...]
+
+---
+
+## Plan History
+
+- Phase 1: [name] — synthesized
+- Phase 2: [name] — synthesized
+
+## Performance Considerations
+
+[Copied from design artifact.]
+
+## Migration Notes
+
+[Copied from design artifact, or empty if N/A.]
+
+## References
+
+- Design: `thoughts/shared/designs/[file].md`
+- Research: `thoughts/shared/research/[file].md`
+- Original ticket (if any): `thoughts/me/tickets/[file].md`
+```
+
+## Step 3: Cross-Phase Integration Verify
+
+After all phases are synthesized (`unresolved_phase_count == 0`), verify consistency across the synthesized phases via `claim-verifier`. The orchestrator builds an explicit claim list mechanically from design + skeleton; the agent grounds each claim against the in-progress plan and emits Verified / Weakened / Falsified per row.
+
+1. **Build the claim list.** Walk the design + the in-progress plan artifact. For each phase N (which corresponds 1:1 with design slice N), emit one claim row per expected invariant. Use a stable ID scheme: `<phase-id>-<check-id>-<seq>` (e.g., `P3-EXPORT-1`, `P5-IMPORT-2`). Claim categories:
+
+   - **EXPORT**: each symbol named in the slice's `Outputs` / `Types/Data Model` is exported from the phase's synthesized code at `<plan-file>:<line>`.
+   - **IMPORT**: each `depends_on` reference resolves to a real export of the prior phase (cite the import line in this phase and the export line in the prior phase).
+   - **FILE-MAP**: each entry in the design's `## File Map` has a synthesized code block in exactly one phase.
+   - **TEST-ENTRY**: each test name in the slice's `Verification hooks` has a `#### N. <test-name>` Changes Required entry under that phase.
+   - **DECISION-SPEC**: for each Decision owned by this slice, claim its specifics — what symbol does what at which line. Example: "D<N> (<title>) → case `<action>` sets `<flag-A> = true` (NOT a similarly named `<flag-B>`) at `<line>`."
+   - **SET-CARDINALITY**: for each closed set the design enumerates, claim the plan emits the same members at the same count. Format: "Slice <N> enumerates {a, b, c} (count=3); plan emits {a, b, c} at `<line>` (count=3)." Extra, missing, or renamed members → Falsified.
+   - **MODIFY-BODY**: for each MODIFY entry, claim the AFTER block contains executable statements at `<line>` (real declarations / cases / branches), not commented narration. A block whose AFTER body is `//` lines only → Falsified.
+   - **REMOVED-SURVIVOR**: for each `// REMOVED: <name>` annotation, claim `<name>` does not appear in any AFTER body across all phases. Any surviving reference → Falsified.
+   - **VERIFICATION-NOTE**: each item in the design's `## Verification Notes` is satisfied by some synthesized code or test (cite the satisfying location).
+   - **METHOD-USAGE**: each public method / setter / factory-output member declared on a class or object in any phase has at least one call site in a downstream phase OR is documented as intentionally unused.
+   - **COMMENT-REF**: each comment referencing work performed elsewhere ("handled at integration layer", "managed by Slice X", "see Y", "reset in caller") cites a location that actually performs that work.
+   - **SEMANTIC-CLAIM**: for each behavior-prescribing `#### Q/A` clause (verb-led: cancels / sets / rebuilds / activates — not noun-led: is / has), claim what the code does at a specific line. Examples:
+     - "Slice <N> Q/A '<verb-led behavior clause>' → handler `<name>` performs `<observable mutation>` at `<line>`."
+     - "Slice <N> Outputs '<derivation rule citing a domain field>' → mapper uses the domain field (NOT iteration-index `i`) at `<line>`."
+   - **ANCHOR**: each `file:line` cited in any slice's `Integration anchors` still matches the symbol it's claimed to anchor in the source repository.
+
+2. **Dispatch `claim-verifier`** with the claim list:
+
+   ```
+   subagent({
+     agent: "claim-verifier",
+     task: "Verify each claim below against <plan artifact path> and <design artifact path>. Ground non-ANCHOR claims in the plan artifact's '## Phase N' code blocks; ANCHOR claims in the cited source file. Emit one row per claim:
+
+     FINDING <id> | <Verified|Weakened|Falsified> | <one-line justification with file:line>
+
+     Claims:
+     <id-1> | <category> | <claim text with cited <file:line> evidence the orchestrator expects to see>
+     <id-2> | <category> | ...
+     ...",
+     context: "fresh",
+     artifacts: false
+   })
+   ```
+
+3. **Present integration summary** (under 15 lines):
+   ```
+   Integration: [feature name] — [P] phases synthesized
+   Phases: [brief list of phase names and file counts]
+   Claims verified: [N] | Weakened: [W] | Falsified: [F]
+   ```
+
+4. **On any Falsified or Weakened row**: parse the phase from the claim ID, return to Step 2 for that phase, re-synthesize once, then rebuild the claim list and re-dispatch `claim-verifier`. If any row is still Falsified/Weakened after one auto-resynthesis cycle, STOP and surface those rows to the developer for guidance.
+
+5. **On all Verified**: proceed directly to finalize.
+
+6. **Finalize**: Set frontmatter `status: ready`, `unresolved_phase_count: 0`. Present:
+
+   ```
+   Implementation plan written to: thoughts/shared/plans/[filename].md
+   [P] phases synthesized, [F] total file changes.
+   Run `/skill:implement thoughts/shared/plans/[filename].md Phase 1` when ready.
+   ```
+
+7. **Iterate on feedback**: adjust Success Criteria, return to Step 2 for a wrong phase, or return to /skill:design2 Step 5 for an under-specified contract.
+
+## Guidelines
+
+- **No routine developer touchpoint**: synthesis runs end-to-end. Stop and surface only on real failure signals — self-verify still violating after one auto-retry, Step 3 finding still present after one auto-resynthesis, an anchor whose cited symbol is gone, or a contract proven under-specified during synthesis.
+- **Trust the design**: Slice Contracts and Decisions are fixed. If a contract is wrong or under-specified, return to /skill:design2 Step 5 — do not silently change the approach.
+- **No open questions in the final plan**: Step 1's two-pass STOP gate already filtered them. If new questions surface during synthesis, the contract is under-specified — STOP and return to design2.
+
+## Success Criteria Conversion
+
+Each phase's `### Success Criteria:` always splits into Automated and Manual.
+
+**Format example:**
+```markdown
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] All unit tests pass: `npm test`
+- [ ] No linting errors: `npm run check`
+- [ ] Grep pattern from Slice 1 Verification hook: `grep -r "newApiCall" packages/ | wc -l` returns >= 3
+- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`
+
+#### Manual Verification:
+- [ ] New feature appears correctly in the UI
+- [ ] Performance is acceptable with 1000+ items
+- [ ] Error messages are user-friendly
+- [ ] Feature works correctly on mobile devices
+```
+
+**Convert design's Verification Notes AND each slice's Verification hooks to success criteria:**
+- Slice Verification hook test names → automated `npm test` matchers
+- Slice Verification hook grep patterns → `grep -r "..." | wc -l` automated checks
+- Slice Verification hook observable behaviors → manual verification steps
+- Artifact-level Verification Notes (precedents/warnings) → cross-phase manual verification
+- Prose warnings → specific automated commands or manual steps
+
+## Important Notes
+
+- NEVER edit source files — this skill produces a plan document, not implementation.
+- **Never write the artifact whole**: after Step 1's skeleton, only `Edit` operations touch the artifact, and each `Edit` is scoped to a single `## Phase N` section. Batched cross-phase Edits and full-file rewrites are forbidden — they cause overlap errors and break the per-phase transaction.
+- **One slice per phase**: each design slice maps to exactly one plan phase, in topological order from `depends_on`. No grouping at synthesis time, no packaging step.
+- **Read prior phases' emitted code, not their contracts**: when synthesizing a phase whose slice has `depends_on`, import against the actually-emitted exports in prior `## Phase N` sections, not the abstract contract.
+- **Agents fulfill contracts, never invent decisions** — pattern-finder (Step 2.0 templates), integration-scanner (Step 2a MODIFY), precedent-locator (Step 2a replacement), codebase-analyzer (Step 2a anchor ambiguity), web-search-researcher (Step 2a novel work), and claim-verifier (Step 3 cross-phase verification) return templates, analysis, or row-tagged findings; the orchestrator synthesizes.
+- **Frontmatter consistency**: snake_case for multi-word field names.
+- **Pre-restructure design refusal**: if the design lacks the `slices:` frontmatter array, STOP and instruct the developer to re-run /skill:design2.

package/skills/research/SKILL.md

@@ -1,33 +1,46 @@
 ---
 name: research
-description: Answer structured research questions via targeted parallel analysis agents. Consumes question artifacts from discover. Produces research documents in thoughts/shared/research/. Second stage of the research pipeline — always requires a questions artifact.
-argument-hint: [path to discover artifact]
+description: Answer structured research questions via targeted parallel analysis agents. Accepts either a questions artifact from discover OR a free-text prompt/task (in which case it auto-runs discover via a subagent). Produces research documents in thoughts/shared/research/.
+argument-hint: [path to discover artifact | free-text research prompt]
 ---
 
 ## Questions Source
 
-If the user has not already provided a specific discover artifact path, ask them for it before proceeding. Their input will appear as a follow-up paragraph after this skill body.
+The user's argument is inlined below as `$ARGUMENTS` (resolved by rpiv-args). If `$ARGUMENTS` is empty, ask for input. If `$ARGUMENTS` is a path to a `.md` file under `thoughts/`, treat it as a discover artifact. Otherwise treat it as a free-text research prompt and auto-run discover via a subagent (Step 1, free-text branch).
 
 # Research
 
-You are tasked with answering structured research questions by spawning targeted analysis agents and synthesizing their findings into a comprehensive research document. This skill consumes questions artifacts produced by the `discover` skill.
+You are tasked with answering structured research questions by spawning targeted analysis agents and synthesizing their findings into a comprehensive research document. This skill consumes questions artifacts produced by the `discover` skill — either provided directly by the user, or produced on-demand via a subagent when the user passes free text.
+
+Argument (resolved by rpiv-args): `$ARGUMENTS`
 
 ## Step 1: Read Questions Artifact
 
-1. **Determine input:**
+1. **Determine input** by inspecting `$ARGUMENTS`:
 
-   **Questions artifact provided** (path to a `.md` file in `thoughts/`):
+   **Path to a `.md` file under `thoughts/`** (questions artifact):
    - Read the questions artifact FULLY using the Read tool WITHOUT limit/offset
    - Extract: Discovery Summary, Questions (dense paragraphs), frontmatter metadata (topic, tags)
    - The Discovery Summary provides the file landscape overview — no need to re-discover
 
-   **No arguments provided:**
+   **Free-text prompt / task description** (`$ARGUMENTS` is non-empty and is NOT a path to a `thoughts/**/*.md` file):
+   - Dispatch ONE subagent to run discover end-to-end in non-interactive mode:
+     ```
+     subagent({
+       agent: "general-purpose",
+       task: "Read packages/rpiv-pi/skills/discover/SKILL.md and execute it in subagent (non-interactive) mode.
+              Topic: $ARGUMENTS
+              Return ONLY the absolute path to the questions artifact you wrote.",
+       context: "fresh",
+       artifacts: false
+     })
+     ```
+   - Capture the returned absolute path, then fall through into the "Path to a `.md` file …" branch above.
+   - Report: `[Auto-discovered]: ran discover via subagent for "$ARGUMENTS". Questions artifact: [path].`
+
+   **`$ARGUMENTS` is empty:**
    ```
-   I'll answer research questions from a questions artifact. Please provide the path:
-   `/skill:research thoughts/shared/questions/YYYY-MM-DD_HH-MM-SS_topic.md`
-
-   This skill requires a questions artifact from discover.
-   There is no standalone path — run /skill:discover first to produce a questions artifact.
+   Please provide a discover questions artifact path or a free-text research prompt. Free text will auto-run discover via a subagent first.
    ```
    Then wait for input.
 
@@ -289,7 +302,7 @@ When ready:
 ## Important Notes
 
 - **Analysis only**: This skill answers questions. It does NOT discover what to ask — that's discover's job.
-- **Always chained**: This skill requires a questions artifact from discover. There is no standalone path.
+- **Two entry points**: A discover questions artifact path (chained) OR free text (auto-runs discover via a subagent in non-interactive mode, then proceeds with the produced artifact). Argument substitution is handled by `rpiv-args` (`$ARGUMENTS`).
 - **Grouped dispatch**: Related questions are batched per agent based on file overlap. Default agent: codebase-analyzer. This reduces token waste from redundant file reads and lets agents build cross-question context.
 - **Downstream compatible**: Research documents feed directly into design and plan — the same Code References / Integration Points / Architecture Insights sections they expect.
 - **File reading**: Always read the questions artifact FULLY (no limit/offset) before dispatching agents