arreio 1.0.0-dev.1

package/skills/plan/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: plan
+description: "Create durable implementation plans that can be handed off for execution. Orchestrates a deterministic pipeline of micro-skills: Scope -> Research -> Design -> Generate -> Tasks. No agent dependency, no fallback paths."
+disable-model-invocation: true
+---
+
+# Plan
+
+Orchestrates a deterministic pipeline of micro-skills: `Scope -> Research -> Design -> Generate -> Tasks`. No agent dependency, no fallback paths.
+
+## Skill Invocation
+
+This skill is invoked by prompting `/plan <task description>`. This skill will run the planning pipeline, producing a final plan artifact and optionally a set of task artifacts, acting as the Orchestrator.
+
+## Interaction Method
+
+- Ask the user one structured question at a time (2–4 concrete options) using the agent's interactive question capability; never hardcode a specific tool name.
+- If input is empty, ask: "What would you like to plan? Describe the task or project."
+
+Before starting the workflow, ask the user to choose an interaction mode:
+
+- **Detailed** — Confirm at each phase transition; inspect artifacts; maximum control. Best for complex/unfamiliar work.
+- **Autopilot** — All phases run automatically; only final outcome reported. Fastest. Best for straightforward work.
+- **Smart** — Phases run automatically; pause only on HIGH-risk operations.
+
+Store in the context object:
+
+```yaml
+interactionMode: detailed | smart | autopilot
+```
+
+**Propagation:** `interactionMode` flows into `research`, `design`, and `generate` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition; autopilot = run all; smart = pause only on HIGH-risk).
+
+## Orchestration Implementation
+
+Each phase runs sequentially: the orchestrator calls the module, receives the output artifact, validates it with a quality gate, and passes it to the next phase.
+
+### INPUT
+
+- Receives a context object (task description, goals, constraints, references, previous plans) from the user, a saved prompt, a document, or a combination.
+- **If no context is provided**, ask: "What would you like to plan? Describe the task or project."
+- Output: [User Input Artifact](references/templates/artifacts/user-input.md)
+
+### Pre-Flight Check
+
+Before starting the planning pipeline, the orchestrator verifies that required folders exist:
+
+- `docs/plans/` — must exist for saving final plan
+- `docs/tasks/` — must exist if task generation is enabled
+
+**Self-Healing:** If missing, the orchestrator automatically creates these folders. This allows the plan skill to run even if `arreio-init` wasn't explicitly run.
+
+### Phases
+
+| Phase | Module                                 | Output Artifact                                                                    |
+| ----- | -------------------------------------- | ---------------------------------------------------------------------------------- |
+| 1     | [Scope](modules/scope.md)              | [Scoped context](references/templates/artifacts/scoped-context.md)                 |
+| 2     | [Research](modules/research.md)        | [Research findings](references/templates/artifacts/research-findings.md)           |
+| 3     | [Design](modules/design.md)            | [Design with unit decomposition](references/templates/artifacts/design.md)         |
+| 4     | [Generate](modules/generate.md)        | [Final plan](references/templates/artifacts/final-plan.md) saved to `docs/plans/`  |
+| 5     | [Tasks](modules/tasks.md) _(optional)_ | [Task list](references/templates/artifacts/task.md) saved to `docs/tasks/plan-id/` |
+
+**Phase 5** is optional; ask the user 'Generate individual task files?' before running, even in Autopilot. If user declines, planning is complete.
+
+### Quality Gates
+
+Between phases, the orchestrator validates the output artifact before passing it to the next phase:
+
+1. **Schema validation** — required fields present and well-formed (see [error-handling.md](references/error-handling.md) for the per-type field list).
+2. **Cross-phase consistency** — IDs (`scope-id`, `research-id`, `design-id`, `plan-id`) match the upstream artifacts; `interactionMode` is identical across artifacts.
+3. **Status check** — the artifact's `status` is `complete` (not `pending` or `failed`).
+4. **Tier/complexity coherence** (after Design) — the `tier_recommended` is consistent with `complexity` and `risk_level` per [plan-tier-selection.md](references/plan-tier-selection.md).
+
+If a gate fails, the orchestrator returns to the producing phase with the error context (per the recovery workflow in [error-handling.md](references/error-handling.md)).
+
+### Index Registration
+
+Each skill module is responsible for registering its own outputs:
+
+| Module   | Registers To                    | Artifact Format                                  |
+| -------- | ------------------------------- | ------------------------------------------------ |
+| Generate | `docs/plans/index.md`           | Link + brief summary to final plan file          |
+| Tasks    | `docs/tasks/<plan-id>/index.md` | Folder creation + task links (created on-demand) |
+
+**Who updates what:**
+
+- **Generate phase:** Creates `docs/plans/index.md` if missing; appends new plan entry with timestamp and link
+- **Tasks phase:** Creates `docs/tasks/<plan-id>/` folder and `docs/tasks/<plan-id>/index.md` if missing; populates with task file links and metadata
+
+### FINAL OUTPUT
+
+- **Plan file:** Saved to `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md`
+  - **Registration:** Generate phase appends an entry to `docs/plans/index.md` linking the new plan
+- **Task files (optional):** Saved to `docs/tasks/<plan-id>/TASK-NNN-<kebab-case-name>.md`
+  - **Registration:** Tasks phase creates `docs/tasks/<plan-id>/index.md` and registers task file links there
+  - Ready for the Work skill to consume via `docs/tasks/<plan-id>/index.md`
+
+## References
+
+The orchestrator and modules share these reference files:
+
+| Reference                                                                     | Used By                          |
+| ----------------------------------------------------------------------------- | -------------------------------- |
+| [error-handling.md](references/error-handling.md)                             | All phases (Step 0 verification) |
+| [id-generation.md](references/id-generation.md)                             | Scope, Research, Design, Generate (ID assignment) |
+| [interaction-mode-propagation.md](references/interaction-mode-propagation.md) | All phases (Step N confirmation) |
+| [learnings-gate-logic.md](references/learnings-gate-logic.md)                 | Scope (Step 4)                   |
+| [high-risk-detection.md](references/high-risk-detection.md)                   | Research (Step 2)                |
+| [external-research-guidance.md](references/external-research-guidance.md)     | Research (Step 4)                |
+| [design-complexity-assessment.md](references/design-complexity-assessment.md) | Design (Step 4)                  |
+| [plan-tier-selection.md](references/plan-tier-selection.md)                   | Generate (Step 1)                |
+| [task-slicing-rules.md](references/task-slicing-rules.md)                     | Tasks (Steps 2–3)                |
+
+Artifact templates live in [references/templates/artifacts/](references/templates/artifacts/).
+
+## Core Principles
+
+- **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
+- **Error Handling:** Fail explicitly, not silently; each phase has clear error handling with recovery suggestions.
+- **Focus on Decisions:** Capture approach, structure, risks, and sequencing (not code simulation).
+- **Right-Size:** Small tasks → short plans; complex work → more structure.
+- **Separate Planning from Execution:** NEVER simulate implementation during planning.
+- **Be Concrete:** Use specific files, components, and dependencies.
+- **Stay Portable:** Use repository-relative paths only.
+- **Transparent Artifacts:** Each phase produces an explicit output artifact for the next phase.
+- **Interaction Mode Propagation:** `interactionMode` is read at the start of each subsequent phase and determines whether confirmation steps execute.
+- **Single Source of Truth:** This skill defines all its own rules; it does not depend on any external agent rule file.
+- **Behavior-Described, Tool-Agnostic:** Steps describe required capabilities ("search the codebase", "ask the user one question"), not specific tool names; each agent maps to its native tools.
+- **Test-Driven Tasks:** One Acceptance Criterion per task; one test per AC; each task's Steps follow Red → Green → Refactor (write the failing test first and confirm it fails, implement the minimum code to pass, then refactor with the test green).

package/skills/plan/modules/design.md

@@ -0,0 +1,140 @@
+---
+title: Design
+description: Design the solution based on the scoped context and research findings. Decomposes the approach into phased implementation units, assesses complexity, and produces a Design Artifact for the Generate phase.
+type: module
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Phase 3 - Design
+
+**Purpose:** Third step in the planning workflow. Reads the Scoped Context and Research Findings, selects an approach, decomposes it into phased implementation units, assesses complexity, and returns a [Design Artifact](../references/templates/artifacts/design.md) that the Generate phase renders into a final plan.
+
+## Workflow
+
+This is the Phase 3 pipeline for the Plan Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required inputs:
+
+1. **Scoped Context Artifact** with `scope-id`, `domain`, `Problem`, `Intended Behavior`, `Success Criteria`.
+2. **Research Findings Artifact** with `research-id`, `Patterns Found`, `High-Risk Detection` (with `risk_level`), `Tech Stack`.
+3. `interactionMode` present (default to `smart` if missing; log warning).
+4. Cross-phase consistency: the research artifact's `scope-id` matches the scope output.
+
+### Step 1: Approach Selection
+
+1. **Read the Scoped Context** to understand the problem, intended behavior, and success criteria.
+2. **Read the Research Findings** to identify available patterns, confidence levels, high-risk areas, and technical constraints.
+3. **Draft 2–3 candidate approaches** that satisfy the success criteria. Base each on:
+   - Patterns found in the codebase (prefer HIGH-confidence patterns when available)
+   - Tech stack constraints from research
+   - Risk level and whether external research was conducted
+4. **Evaluate each approach** against:
+   - Fit with success criteria
+   - Pattern reuse (higher confidence = lower risk)
+   - Complexity (fewer integration points = simpler)
+   - Reversibility (can it be rolled back?)
+5. **Select the recommended approach.** If no clear winner emerges, present the top 2 to the user in one question and let them choose.
+6. **Record the selected approach** as a 1–3 sentence summary in the Design Artifact's `Approach` field, including why it fits the context and research.
+
+### Step 2: High-Level Technical Design
+
+Produce a **directional** design representation (NOT an implementation specification). Choose ONE of:
+
+- **Mermaid diagram** — Use `sequenceDiagram`, `flowchart`, or `graph` to show component interaction. Best for multi-actor flows.
+- **Pseudo-code sketch** — High-level steps in plain language. Best for algorithmic/logic-heavy work.
+- **Data-flow map** — ASCII arrows showing how data moves through the system. Best for pipeline/ETL work.
+
+The design must:
+
+- Reference real components, files, or services from the research findings (be concrete)
+- Show the "happy path" only; edge cases go in the Implementation Units
+- Avoid implementation details (naming, abstractions, code structure) — those are decided during execution
+
+> **Note:** This is directional guidance for review, not an implementation specification to copy. The implementation phase will determine specific naming, abstractions, and code structure.
+
+### Step 3: Implementation Unit Decomposition
+
+Break the approach into **phased implementation units**. Each unit is a coherent, testable chunk of work.
+
+1. **Define phases** based on dependency layers:
+   - **Phase 1: Foundation** — Units with no dependencies (infra, interfaces, schema)
+   - **Phase 2: Integration** — Units depending on Phase 1 (wiring, middleware, adapters)
+   - **Phase 3: Rollout** (if applicable) — Units for migration, feature flags, cutover
+
+2. **For each unit, record:**
+   - **Unit ID:** `U1`, `U2`, ... (never renumber; preserve across iterations)
+   - **Name:** Short, descriptive
+   - **Goal:** What this unit accomplishes (1 sentence)
+   - **Dependencies:** Which unit IDs must complete first (or "None")
+   - **Files:** `Create`, `Modify`, and `Test` paths — repository-relative, in backtick code formatting
+   - **Acceptance Criteria:** A list of one or more checkable criteria. **Each criterion later becomes exactly one task and one test** (see Tasks phase). Phrase each as a single, verifiable outcome — not a bundle.
+   - **Test Scenarios:** `[Scenario]: [Input -> Expected Outcome]` (required for Phase 1–2 units; optional for rollout-only)
+
+3. **Decomposition check:** Units are sized so the Tasks phase can honor **one Acceptance Criterion per task**. If a unit's criteria would need > 5 files or > 1 day, split that unit (or its criteria) finer; never let a single criterion exceed one task (see [task-slicing-rules.md](../references/task-slicing-rules.md)).
+
+4. **Dependency check:** Verify no cycles exist. A unit may only depend on units in earlier phases. If a cycle is detected, restructure the units.
+
+### Step 4: Complexity Assessment
+
+Score the design across five dimensions (0–3 each) and compute the complexity level. For the scoring table, dimension definitions, and threshold mapping, see **[design-complexity-assessment.md](../references/design-complexity-assessment.md)**.
+
+1. Score each dimension:
+   - `scope_breadth` — from the Implementation Units' file lists
+   - `integration_surface` — from Research Findings' patterns and tech stack
+   - `risk_level` — **inherited** from Research Findings (do not re-score)
+   - `novelty` — compare chosen approach against `Patterns Found` confidence
+   - `data_migration` — from the design's operational/rollout notes draft
+2. Sum the scores (0–15).
+3. Map to complexity level: `TRIVIAL | LOW | MEDIUM | HIGH | VERY_HIGH`.
+4. Record all five scores, the total, and the complexity level in the Design Artifact.
+
+### Step 5: Alternative Approaches
+
+Document the approaches considered but not selected, with rejection rationale.
+
+- **TRIVIAL / LOW complexity:** At least 1 alternative (may be brief).
+- **MEDIUM complexity:** At least 1 alternative with rationale.
+- **HIGH / VERY_HIGH complexity:** At least 2 alternatives with side-by-side rationale.
+
+Format: `**[Approach Name]**: [Description] → **Rejected because:** [Rationale]`
+
+### Step 6: Learnings and Gaps Update
+
+1. **Carry forward** the `Related Learnings` and `Learning Gaps` from the Scoped Context.
+2. **Add new learnings** discovered during design (e.g., a pattern confirmed or refuted).
+3. **Add new gaps** the design revealed (e.g., "No learning on Redis failover in production").
+4. Update both lists in the Design Artifact.
+
+### Generate the Design Artifact
+
+1. **Assign a `design-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-design`, saved to `docs/plans/.design/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce a **Design Artifact** block (as markdown) following the schema in [design.md](../references/templates/artifacts/design.md).
+   - Include the generated `design-id`, inherited `scope-id` and `research-id`, `interactionMode`, `complexity`, and `tier_recommended` (derived from complexity per [plan-tier-selection.md](../references/plan-tier-selection.md)).
+
+### Step 7: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these design-specific **Smart pause triggers**:
+
+- `complexity = VERY_HIGH`, or
+- Research reported HIGH risk with `patterns_found_count < 3`, or
+- 3+ learning gaps carried from Scope, or
+- The selected approach has no local pattern precedent (Novelty = 3).
+
+- **Detailed:** present the Design Artifact and ask one question with options *(1) Proceed to Generate, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–6 reusing the `design-id`. On **Abort**, stop and inform the Orchestrator.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
+- **Autopilot:** auto-proceed (no confirmation).
+
+Then save the artifact to `docs/plans/.design/<design-id>.md` (ensure `interactionMode`, `complexity`, and `tier_recommended` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Generate).
+
+## Output: Design Artifact
+
+- Verify that the Design Artifact is complete and valid, containing all required fields: `design-id`, `scope-id`, `research-id`, `interactionMode`, `complexity`, `tier_recommended`, Approach, High-Level Technical Design, Implementation Units (each with Acceptance Criteria), Complexity Assessment, Alternative Approaches, Related Learnings, and Learning Gaps.
+- Verify that the `complexity` value matches the threshold mapping from the five dimension scores.
+- Verify that `tier_recommended` is consistent with the complexity and risk level per [plan-tier-selection.md](../references/plan-tier-selection.md).
+- Verify that the artifact is saved to `docs/plans/.design/<design-id>.md` for future reference or reuse.
+
+> Pass the design artifact to `generate` (Phase 4) for final plan generation.

package/skills/plan/modules/generate.md

@@ -0,0 +1,156 @@
+---
+title: Generate
+description: Render the final plan from the Design Artifact by selecting a tier, filling the plan template, and saving it to docs/plans/. Produces a Final Plan Artifact for the optional Tasks phase.
+type: module
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Phase 4 - Generate
+
+**Purpose:** Fourth step in the planning workflow. Reads the Design Artifact, selects a plan tier (Fast/Standard/Deep) based on complexity and risk, renders the final plan from the [Final Plan template](../references/templates/artifacts/final-plan.md), and saves it to `docs/plans/`. Returns a [Final Plan Artifact](../references/templates/artifacts/final-plan.md) that the optional Tasks phase consumes.
+
+## Workflow
+
+This is the Phase 4 pipeline for the Plan Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Design Artifact**. Specifically verify:
+
+1. The Design Artifact exists and contains `design-id`, `scope-id`, `research-id`, `interactionMode`, `complexity`, `tier_recommended`, `Approach`, `High-Level Technical Design`, and `Implementation Units`.
+2. The `complexity` field is one of: `TRIVIAL`, `LOW`, `MEDIUM`, `HIGH`, `VERY_HIGH`.
+3. The `interactionMode` is present and valid (default to `smart` if missing; log warning).
+4. Cross-phase consistency: the `scope-id` and `research-id` match the upstream artifacts.
+
+### Step 1: Tier Selection
+
+Select the plan tier based on complexity, risk, and user preference. For the full algorithm, risk floor rules, and tier section requirements, see **[plan-tier-selection.md](../references/plan-tier-selection.md)**.
+
+1. **Read inputs:**
+   - `complexity` from the Design Artifact
+   - `risk_level` from the Research Findings (carried via the Design Artifact's complexity assessment)
+   - `tier_recommended` from the Design Artifact (the algorithm's suggestion)
+
+2. **Determine user preference:**
+   - In **Detailed** mode: Ask the user which tier they want, presenting the recommendation. Options: `Fast`, `Standard`, `Deep`, `Auto`.
+   - In **Smart** mode: Auto-select, unless a pause trigger fires (Deep tier, preference conflicts with risk floor, or CRITICAL risk). If paused, ask the user.
+   - In **Autopilot** mode: Set `user_preference = auto`; never ask.
+
+3. **Apply the selection algorithm** (see [plan-tier-selection.md](../references/plan-tier-selection.md)):
+   - Start from the complexity-driven default tier.
+   - Upgrade if risk warrants it (respect the risk floor).
+   - Honor user preference unless it violates the risk floor.
+
+4. **Record the selected tier** as `tier` and the algorithm's recommendation as `tier_recommended` (for audit when the user overrides).
+
+### Step 2: Plan Rendering
+
+Render the final plan from the [Final Plan template](../references/templates/artifacts/final-plan.md), including only the sections required by the selected tier.
+
+1. **Assemble frontmatter:**
+
+   ```yaml
+   plan-id: YYYY-MM-DD-NNN
+   type: plan
+   title: "[Plan title]"
+   status: complete
+   tier: fast | standard | deep
+   tier_recommended: fast | standard | deep
+   complexity: TRIVIAL | LOW | MEDIUM | HIGH | VERY_HIGH
+   risk: Low | Medium | High | Critical
+   scope-id: YYYY-MM-DD-NNN-scope
+   research-id: YYYY-MM-DD-NNN-research
+   design-id: YYYY-MM-DD-NNN-design
+   interactionMode: detailed | smart | autopilot
+   created: YYYY-MM-DD
+   updated: YYYY-MM-DD
+   version: 1.0
+   ```
+
+2. **Render sections per tier** (see [plan-tier-selection.md](../references/plan-tier-selection.md) for the full section list):
+
+   | Section                       | Fast | Standard | Deep |
+   | ----------------------------- | :--: | :------: | :--: |
+   | Overview                      |  ✅  |    ✅    |  ✅  |
+   | High-Level Technical Design   |  ✅  |    ✅    |  ✅  |
+   | Implementation Units (Phased) |  ✅  |    ✅    |  ✅  |
+   | Alternative Approaches        |  ➖  |    ✅    |  ✅  |
+   | Risk Analysis & Mitigation    |  ✅  |    ✅    |  ✅  |
+   | Operational / Rollout Notes   |  ➖  |    ✅    |  ✅  |
+   | Related Learnings             |  ✅  |    ✅    |  ✅  |
+   | Learning Gaps                 |  ➖  |    ✅    |  ✅  |
+
+   Legend: ✅ required, ➖ optional (skip if not applicable).
+
+3. **Carry forward content from the Design Artifact:**
+   - `Approach` → Overview
+   - `High-Level Technical Design` → High-Level Technical Design
+   - `Implementation Units` → Implementation Units (Phased)
+   - `Alternative Approaches` → Alternative Approaches Considered
+   - `Related Learnings` → Related Learnings
+   - `Learning Gaps` → Learning Gaps
+
+4. **Build the Risk Analysis table** from the Research Findings' high-risk detection and the Design's complexity:
+   - Each risk row: `| [Specific risk] | High/Medium | [Concrete mitigation] |`
+   - Fast tier: 1–2 rows (brief)
+   - Standard tier: full table covering all detected high-risk areas
+   - Deep tier: full table with impact ratings + rollback plan
+
+5. **Build Operational / Rollout Notes** (Standard/Deep only) from the Design's rollout units:
+   - Feature flags, monitoring, data migration, rollback plan, performance baseline
+   - Skip the section entirely if not applicable (Fast tier, or no rollout units)
+
+6. **Right-size:** Per Plan Skill core principles — small tasks → short plans; complex work → more structure. Do not pad a Fast plan with empty sections; do not omit required sections from a Deep plan.
+
+### Step 3: Plan ID Generation
+
+1. **Assign a `plan-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN`). Reuse it if the user later picks **Edit & Retry**.
+2. **Derive the plan filename** from the plan title (lowercase, hyphens, no stopwords): `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md`.
+
+### Step 4: Present and Confirm
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these generate-specific **Smart pause triggers**:
+
+- The selected tier is `Deep`, or
+- The user's tier preference conflicts with the risk floor, or
+- Research reported CRITICAL risk (Security or Payments).
+
+- **Detailed:** present the assembled Final Plan (in memory) and ask one question with options *(1) Proceed to Tasks, (2) Edit & Retry, (3) Skip Tasks, (4) Abort*.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
+- **Autopilot:** auto-proceed (no confirmation); the Tasks phase still always asks the user before writing files.
+
+Map each answer to its action so save+index **never run before the decision**:
+
+| Answer | Action |
+| --- | --- |
+| **Proceed to Tasks** | Run Step 5, then return with `continue-to-tasks: true`. |
+| **Skip Tasks** | Run Step 5, then return with `continue-to-tasks: false`. |
+| **Edit & Retry** | Loop back through Steps 1–3 reusing the `plan-id` (save+index have not run yet). |
+| **Abort** | Stop; inform the Orchestrator; do not save. |
+
+### Step 5: Assemble, Save, and Register
+
+Run this step only after confirmation (or any auto-proceed path); never on **Abort** or a pending **Edit & Retry**.
+
+1. **Assemble** the complete plan — frontmatter (Step 2.1) + rendered sections (Step 2.2–2.6) — with `plan-id` set to the assigned id.
+2. **Save** (write or overwrite) the plan to `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md`.
+3. **Register** in `docs/plans/index.md`. **Insert or replace** the row by `plan-id` (idempotent on Edit & Retry) — never blind-append. If the index does not exist, create it with a header row. Row format:
+
+```markdown
+| [YYYY-MM-DD-NNN](YYYY-MM-DD-NNN-<kebab-case-name>.md) | [Plan Title] | [tier] | [tier_recommended] | [complexity] | [risk] | ready |
+```
+
+### Step 6: Return to Orchestrator
+
+Return the Final Plan Artifact to the Orchestrator — `path`, `plan-id`, `tier`, `tier_recommended`, `interactionMode`, and `continue-to-tasks` (`true` if the user chose Proceed to Tasks, `false` on Skip). The Orchestrator continues to Phase 5 (Tasks) when `continue-to-tasks: true`, or marks the plan complete otherwise.
+
+## Output: Final Plan Artifact
+
+- Verify that the Final Plan is complete and valid, containing all required frontmatter fields (`plan-id`, `type`, `title`, `status`, `tier`, `tier_recommended`, `complexity`, `risk`, `scope-id`, `research-id`, `design-id`, `interactionMode`, `created`, `updated`, `version`) and all tier-required sections.
+- Verify that all file paths in the plan are repository-relative (never absolute) and wrapped in backtick code formatting.
+- Verify that `## Related Learnings` is present and references `docs/learn/index.md` entries (or states "No relevant learnings found").
+- Verify that `## Learning Gaps` is present (may be empty).
+- Verify that the plan is saved to `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md` and registered in `docs/plans/index.md`.
+
+> The Final Plan is the primary deliverable of the Plan Skill. Pass it to `tasks` (Phase 5, optional) for task slicing, or mark the plan as complete if the user declines tasks.

package/skills/plan/modules/research.md

@@ -0,0 +1,122 @@
+---
+title: Research
+description: Research the task and gather relevant information, requirements, and constraints. Produces a Research Findings Artifact for downstream phases.
+type: module
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Phase 2 - Research
+
+**Purpose:** Second step in the planning workflow. Performs local codebase research, detects high-risk areas, and determines if external research is needed. Returns [research findings](../references/templates/artifacts/research-findings.md) that inform the design phase.
+
+## Workflow
+
+This is the Phase 2 pipeline for the Plan Skill. It orchestrates the following steps:
+
+### Step 0: Verification
+
+Run the **[Step 0 verification](../references/error-handling.md)**. Required input: a valid **Scoped Context Artifact** from Scope carrying `scope-id`, `domain`, `Problem`, `Intended Behavior`, `Success Criteria`, and `interactionMode`.
+
+### Step 1: Local Pattern Discovery
+
+1. **Read the scoped context** to understand the task and extract key terms (domain, feature, technology area).
+
+2. **Detect tech stack** from config files in repository root:
+   - Check for: `package.json` (Node.js), `pyproject.toml` (Python), `go.mod` (Go), `Cargo.toml` (Rust), `Gemfile` (Ruby), `composer.json` (PHP), `pom.xml` (Java), `build.gradle` (Java/Kotlin)
+   - Record detected tech stack and versions for Step 5
+   - If multiple tech stacks detected, prioritize primary language
+   - **If NO config files match:** Record "Unknown/Multi-language" and proceed to Step 3 using generic search queries (e.g., "architecture", "pattern", "implementation") instead of tech-specific table. Note: This may result in broader matches and lower confidence.
+
+3. **Define tech-stack-specific search queries** based on detected stack and task domain:
+
+   | Tech Stack | Example Query (Auth Pattern)                       | Example Query (API Pattern)                   |
+   | ---------- | -------------------------------------------------- | --------------------------------------------- |
+   | Node.js    | "middleware", "passport", "jwt", "express auth"    | "router", "express", "endpoint", "middleware" |
+   | Python     | "decorator", "authenticate", "middleware", "flask" | "route", "flask", "endpoint", "blueprint"     |
+   | Go         | "middleware", "handler", "auth", "gin"             | "handler", "route", "gin", "endpoint"         |
+   | Rust       | "middleware", "guard", "auth", "actix"             | "handler", "route", "actix", "endpoint"       |
+   | Java       | "filter", "interceptor", "security", "spring"      | "controller", "endpoint", "spring", "mapping" |
+
+4. **Search in two phases** (hybrid approach):
+
+   **Phase A — Pattern search (literal):**
+   - Search common directories: `src/`, `app/`, `lib/`, `services/`, `api/`, `controllers/`, `handlers/`
+   - Use tech-stack-specific queries from table above
+   - Also search for: `architecture.md`, `design.md`, `ARCHITECTURE.md`, `DESIGN.md` at repo root and in `docs/`, `design/`, `architecture/` subdirectories
+   - **Collect all unique file paths found** (count across all Phase A searches; deduplicate)
+   - Record total count and note which queries yielded matches
+
+   **Phase B — Pattern gap detection (meaning-based, conditional):**
+   - **Decision rule:** If Phase A found fewer than 3 unique file paths, proceed to Phase B
+   - Run a meaning-based search using the task description as the query
+   - Example: "How is authentication implemented in this codebase?" or "Where are API endpoints defined?"
+   - Captures conceptual patterns missed by literal pattern search
+   - **If Phase A found 3+ files:** Skip Phase B; proceed to Step 5 with existing matches
+
+5. **Count confidence levels** based on total unique file matches:
+   - **HIGH:** 3 or more files with pattern examples
+   - **MEDIUM:** 1–2 file examples found
+   - **LOW (or 0):** No pattern examples in codebase
+
+6. **For each pattern found, record:**
+   - File path(s)
+   - Pattern name and brief description
+   - Confidence level (HIGH/MEDIUM/LOW)
+   - Relevant code snippet or line range (if available)
+
+7. **Output:** Compile patterns found into `Patterns Found` section of Research Findings Artifact with confidence levels.
+
+### Step 2: High-Risk Area Detection
+
+- Scan the task description and scoped context for high-risk keywords across six areas: Security, Payments, APIs, Migrations, Complex Logic, and Infrastructure.
+- For details on the risk keyword table, area definitions, and heuristics for assigning risk levels, see **[high-risk-detection.md](../references/high-risk-detection.md)**.
+
+### Step 3: External Research Decision
+
+1. Look up the external-research decision in the **risk × patterns matrix** in [high-risk-detection.md](../references/high-risk-detection.md) ("Mapping to Research Decision") using the detected **risk level** (Step 2) and the **patterns found count** (Step 1).
+2. If the matrix returns "Recommend external": provide specific web search guidance (Step 4). If it returns "Skip external", record `External Research: skipped` and proceed to Step 5.
+3. If it returns "Optional external": provide guidance only when interaction is detailed/smart or risk is HIGH/CRITICAL.
+
+### Step 4: External Research Guidance (if needed)
+
+Generate targeted web search queries when external research is recommended.
+For query templates, formatting guidance, and examples for each high-risk area, see **[external-research-guidance.md](../references/external-research-guidance.md)**.
+
+### Step 5: Technical Constraints Gathering
+
+1. Document all technical constraints found:
+   - Framework and language versions from config files
+   - Performance requirements or implications
+   - Compatibility notes (e.g., "must support IE11", "must work with existing auth")
+   - Deployment constraints (e.g., "must run on AWS Lambda")
+   - Integration constraints (e.g., "must use existing logging framework")
+
+### Step 6: Generate the Research Findings Artifact
+
+1. **Assign a `research-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-research`, saved to `docs/plans/.research/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce a **Research Findings Artifact** block (as markdown) following the schema in [research-findings.md](../references/templates/artifacts/research-findings.md):
+   - Include the generated `research-id` and the inherited `scope-id`.
+   - Write a 2–3 sentence **Findings Summary** overview of the Patterns Found, risk level, and constraints.
+
+### Step 7: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these research-specific **Smart pause triggers**:
+
+- Risk level is HIGH or CRITICAL **and** fewer than 3 patterns found (external research recommended), or
+- Zero patterns found in the codebase.
+
+- **Detailed:** present the Research Findings Artifact and ask one question with options *(1) Proceed to Design, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 1–6 reusing the `research-id`. On **Abort**, stop and inform the Orchestrator.
+- **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
+- **Autopilot:** auto-proceed (no confirmation).
+
+On any proceed/skip path: save the artifact to `docs/plans/.research/<research-id>.md` (ensure `interactionMode` is included), then return the artifact and `interactionMode` to the Orchestrator for the transition to Phase 3 (Design).
+
+## Output: Research Findings Artifact
+
+- Verify that the Research Findings Artifact is complete and valid, containing all required fields, and it accurately reflects the user's input and any existing plans, learnings, or requirements found.
+- Verify that the `interactionMode` value is set correctly based on the user's selection in the Orchestrator skill.
+- Verify that the artifact is saved to `docs/plans/.research/<research-id>.md` for future reference or reuse.
+
+> Pass the research findings to `design` (Phase 3) for the design phase.