arreio 1.0.0-dev.1

package/skills/plan/modules/scope.md

@@ -0,0 +1,121 @@
+---
+title: Scope
+description: Gather context, check existing plans and learnings, validate domain, and return a scoped context object for downstream modules (research, design, generate).
+type: module
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Phase 1 - Scope & Context Gathering
+
+**Purpose:** Entry point to the planning workflow. Gathers context, checks existing plans and learnings, validates domain, and returns a scoped context object that downstream modules (research, design, generate) consume.
+
+## Workflow
+
+This is the Phase 1 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 **User Input Artifact** (see [user-input.md](../references/templates/artifacts/user-input.md)) from the Orchestrator.
+
+### Step 1: Check for Existing Plan
+
+1. Search `docs/plans/index.md` for existing plans related (grep title and description) to the task.
+   - If the index file does not exist, assume no existing plans are present.
+   - Ask the user one multiple-choice question:
+     ```
+     The Plans Index was not found. Do you want to run the /arreio-init to create all the necessary folders, files, and index for planning? (Recommended)
+     What would you like to do?
+      - Yes: Run /arreio-init to create the planning structure
+      - No: Skip and continue without creating the structure
+     ```
+   - If the user selects "Yes," run `/arreio-init` to create the necessary structure, then run the Step 1 of the Scope phase again to check for existing plans.
+
+2. **If an existing plan is found:**
+   - Read the plan to understand its title and goal. Plan files are stored in `docs/plans/` with naming format: `YYYY-MM-DD-NNN-<kebab-case-name>.md` (e.g., `docs/plans/2026-07-02-001-migrate-session-storage.md`)
+   - Ask the user one multiple-choice question:
+     ```
+     An existing plan was found: "[Plan Title]"
+     What would you like to do?
+     - Resume: Continue working on this plan
+     - Review: Read the plan before deciding
+     - Archive: Keep for reference, mark as inactive
+     - Delete: Remove the plan entirely
+     - Create New: Start fresh
+     ```
+   - Handle each choice:
+     - **Resume:** Use plan as-is; set `existing_plan.action: resume`, `existing_plan.path: docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md` and carry the reference forward; the pipeline still runs and produces a new `plan-id` that supersedes the existing plan
+     - **Review:** Show plan summary, then re-prompt with same options
+     - **Archive:** Move to archive; set `existing_plan.action: archive`, update `docs/plans/index.md` to mark as archived
+     - **Delete:** Remove file; set `existing_plan.action: delete`, update `docs/plans/index.md` to remove entry
+     - **Create New:** Keep old plan in archive; set `existing_plan.action: create-new`, `existing_plan.path: null`
+
+3. **If no existing plan is found:**
+   - Set `existing_plan.path: null`, `existing_plan.action: none`
+   - Proceed to Step 2
+
+### Step 2: Domain Validation
+
+- Check if the context provided is a software/code planning task (the downstream phases are tailored for software planning).
+- Record `domain: software | non-software` in the scoped context.
+- **If the task is non-software:** ask one question with options *(1) Proceed anyway* (continue with generic, reduced software-style guidance) or *(2) Abort and plan manually*. On Abort, stop and inform the Orchestrator. On Proceed, continue with `domain: non-software`.
+
+### Step 3: Bootstrap Problem Context
+
+Evaluate if context is "rich enough" by confirming the **User Input Artifact** contains **all three** of:
+
+- **Problem frame** — a clear `Task Description` (the problem statement)
+- **Intended Behavior** — an observable desired outcome
+- **Success Criteria** — 1–3 measurable outcomes (derive from `Goals & Objectives` if already measurable; otherwise collect below)
+
+**If any of these three are missing or vague:** ask the user, one question at a time:
+
+1. **Problem Frame:** "What problem are you trying to solve? Describe it in 1–2 sentences." (maps to `Task Description`)
+2. **Intended Behavior:** "What should happen after this is implemented? Describe the desired outcome." (maps to `Intended Behavior`)
+3. **Success Criteria:** "How will we know this is complete? What specific outcomes define success?" Collect 1–3 criteria.
+
+**If all three are present and concrete:** extract them from the **User Input Artifact** and proceed to Step 4.
+
+### Step 4: Learnings Index Gate
+
+Always search for project learnings (in `docs/learn/index.md`) for entries matching the task description. For details on keyword matching, relevance rating, gap identification, and examples, see **[learnings-gate-logic.md](../references/learnings-gate-logic.md)**. Add HIGH and MEDIUM relevance learnings to `Related Learnings`; identify and document any learning gaps.
+
+### Step 5: Requirements Search
+
+1. Search `docs/` for files whose names or content match the task description.
+   - Keywords: exact match on filename, grep content for relevant terms
+   - If the directory does not exist, skip silently
+   - ignore files in `docs/archives/`,`docs/plans/`, and `docs/learn/` (already handled in previous steps)
+2. **For each match:**
+   - Extract the title and a 1-2 sentence relevant excerpt
+   - Add to `Requirements Found` list
+3. If no matches found, set `Requirements Found` to empty.
+
+### Step 6: Generate the Scoped Context Artifact
+
+1. **Assign a `scope-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-scope`, saved to `docs/plans/.scope/`). Reuse it if the user later picks **Edit & Retry**.
+
+2. Produce a **Scoped Context Artifact** block (as markdown) following the schema in [scoped-context.md](../references/templates/artifacts/scoped-context.md).
+   - Include the generated `scope-id` in the artifact
+
+### Step 7: Present, Confirm, and Save
+
+Apply the **[phase confirmation behavior](../references/interaction-mode-propagation.md)** for the current `interactionMode`, using these scope-specific **Smart pause triggers**:
+
+- 3+ learning gaps identified, or
+- Domain flagged non-software (Step 2), or
+- Conflicting requirements detected in the User Input.
+
+- **Detailed:** present the Scoped Context Artifact and ask one question with options *(1) Proceed to Research, (2) Edit & Retry, (3) Abort*. On **Edit & Retry**, loop back through Steps 2–6 reusing the `scope-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/.scope/<scope-id>.md` (ensure `interactionMode` is included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Research).
+
+## Output: Scoped Context Artifact
+
+- Verify that the Scoped Context 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/.scope/<scope-id>.md` for future reference or reuse.
+
+> Pass the scoped context to `research` (Phase 2) for the research phase.

package/skills/plan/modules/tasks.md

@@ -0,0 +1,190 @@
+---
+title: Tasks
+description: Slice the finalized plan into granular, executable, test-driven task files saved to docs/tasks/. One task per Acceptance Criterion; one test per task; ordered by dependency. Optional Phase 5 of the Plan pipeline.
+type: module
+version: 2.0
+timestamp: "2026-08-07"
+---
+
+# Phase 5 - Tasks
+
+**Purpose:** Fifth and final (optional) step in the planning workflow. Reads the Final Plan's Implementation Units and their **Acceptance Criteria**, slices them into granular, executable task files per the [task-slicing rules](../references/task-slicing-rules.md), orders them by dependency, and saves them to `docs/tasks/<plan-id>/`. Produces a set of [Task Artifacts](../references/templates/artifacts/task.md) that the Work skill (`work/SKILL.md`) consumes for execution.
+
+> **Optional phase.** The Orchestrator must ask the user before continuing to this phase, even in Autopilot mode — the user may prefer to defer task generation.
+
+## Core rule
+
+**One Acceptance Criterion per task. One test per task. Test-Driven.**
+
+- Each Implementation Unit carries one or more **Acceptance Criteria** (set in the Design phase).
+- Each Acceptance Criterion becomes **exactly one task** → with **exactly one test file** in `files.test` asserting that single criterion.
+- 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).
+- Never bundle multiple Acceptance Criteria into one task. Never merge units into a shared multi-criterion task.
+
+## Workflow
+
+This is the Phase 5 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 **Final Plan Artifact** from Generate. Specifically verify:
+
+1. The Final Plan exists at `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md` and is non-empty.
+2. The plan frontmatter contains `plan-id`, `tier`, `complexity`, `risk`, and `interactionMode`.
+3. The plan body contains an `## Implementation Units (Phased)` section with at least one unit (`U1`), and each unit lists its **Acceptance Criteria** (at least one).
+4. If the plan has no Implementation Units, abort and ask the user to re-run the Generate phase — the plan is incomplete.
+
+### Step 1: Read and Normalize Units
+
+1. **Read the Implementation Units** from the Final Plan. Parse each unit into a normalized record:
+
+   ```yaml
+   - id: U1
+     name: "[Unit Name]"
+     goal: "[What this unit accomplishes]"
+     phase: 1 | 2 | 3
+     dependencies: [U<id>, ...]        # Unit IDs this depends on
+     files:
+       create: [path, ...]
+       modify: [path, ...]
+       test: [path, ...]
+     acceptance_criteria:             # each becomes exactly one task + one test
+       - "[single, verifiable criterion]"
+     test_scenarios:                   # informational; the task's one test asserts the AC
+       - "[Scenario]: [Input -> Expected Outcome]"
+   ```
+
+2. **Extract the plan's `Related Learnings`** to carry into task files that touch the relevant domains.
+3. **Extract the plan's `tier`** to determine sizing guidance (see [task-slicing-rules.md](../references/task-slicing-rules.md)).
+
+### Step 2: Slice Into Candidate Tasks (one per Acceptance Criterion)
+
+Apply the [task-slicing rules](../references/task-slicing-rules.md):
+
+1. **One task per Acceptance Criterion.** For every criterion on every unit, create one candidate task inheriting the unit's goal, dependencies, and file paths. Each task gets its own dedicated test file in `files.test`.
+2. **Never split within an Acceptance Criterion.** If a criterion would need > 5 files or > 1 day of effort, **split the criterion into two finer sub-criteria** (each its own task) and update the originating unit accordingly — do not slice a task partway through a criterion. Honor the tier's sizing targets (Fast: 1–3 tasks; Standard: 4–8; Deep: 8–15) when choosing how fine to split.
+3. **Sub-IDs only.** If one unit yields multiple criteria/tasks, use sub-identifiers: `U1` → `U1a`, `U1b`. Never renumber original units.
+4. **No merging across criteria.** Do not merge tasks; a task always carries exactly one Acceptance Criterion. (Trivial adjacent units that genuinely share a single criterion are already a single criterion by definition.)
+5. Record slicing decisions for traceability (which criteria were split and why).
+
+### Step 3: Order by Dependencies
+
+Order the tasks so each task's dependencies are satisfied by earlier tasks, using the topological ordering algorithm in [task-slicing-rules.md](../references/task-slicing-rules.md):
+
+```
+1. Start with all tasks as "remaining".
+2. Find tasks whose dependencies are all already ordered → "ready".
+3. If no task is ready: a cycle exists → surface to the user, ask to break or abort.
+4. Sort ready tasks by original unit number (stable ordering).
+5. Append ready tasks to "ordered"; remove from "remaining".
+6. Repeat until all tasks are ordered.
+```
+
+On a cycle: log the error, list the involved tasks, and ask the user one question whether to break the cycle manually (remove a dependency) or abort the Tasks phase.
+
+### Step 4: Assign Priorities
+
+Assign a priority to each ordered task:
+
+| Priority | Criteria                                           |
+| -------- | -------------------------------------------------- |
+| P0       | Blocks all other tasks (foundation, infra, schema) |
+| P1       | On the critical path but not blocking             |
+| P2       | Can be deferred or parallelized                    |
+
+Default: Phase 1 (Foundation) tasks → `P0`; Phase 2 (Integration) → `P1`; Phase 3 (Rollout) → `P2`. Adjust based on the plan's risk analysis — a rollout task that mitigates a HIGH risk may be `P1`.
+
+### Step 5: Present and Confirm
+
+> **Always ask the user in this phase**, even in Autopilot mode (per [interaction-mode-propagation.md](../references/interaction-mode-propagation.md)).
+
+Present the ordered task manifest to the user with one question:
+
+```
+The plan has been sliced into <N> tasks (T01–T<NN>); one per Acceptance Criterion,
+each with its own failing-first test.
+Would you like me to create the task files in docs/tasks/<plan-id>/?
+  - Yes: Create all task files and update the index
+  - Review: Show the task list first, then ask again
+  - No: Skip task creation
+```
+
+- **Review:** display the full task list (IDs, titles, AC, dependencies, priorities, test file) and re-prompt.
+- **No:** skip task creation; the plan remains the unit of work (the user can slice manually later). Inform the Orchestrator that the plan is complete without tasks.
+- **Detailed mode only:** before saving, also show the full content of each task file and allow edit requests.
+- **Yes:** proceed to Step 6.
+
+### Step 6: Materialize Task Files
+
+For each ordered task, materialize a task file using the [Task Artifact template](../references/templates/artifacts/task.md):
+
+1. **Assign a task ID:** `<plan-id>-T<NN>` where `NN` is a zero-padded 2-digit number matching dependency order (01, 02, ..., 10). Sub-IDs → `T02a`, `T02b` (letters, not extra digits).
+2. **Derive the filename:** `T<NN>-<kebab-case-name>.md` (e.g., `T01-redis-client-setup.md`).
+3. **Fill the schema** (all fields required unless noted):
+   - `id` = `<plan-id>-T<NN>`; `title` action-oriented (from the criterion); `plan-id`; `unit` = originating unit (or sub-ID, e.g., `U1` / `U1a`); `tier` inherited; `status = not-started`; `priority` from Step 4; `dependencies` = mapped earlier task IDs; `files` = inherited (create/modify + a **dedicated `test` file for this criterion**); `estimated-effort` by tier (Fast: ≤ half day; Standard/Deep: ≤ 1 day).
+   - `## Goal` — inherited from the unit, scoped to this criterion (1–2 sentences).
+   - `## Acceptance Criterion` — **exactly one** verifiable criterion.
+   - `## Steps` — **Red → Green → Refactor**, in that order:
+     1. **(Red)** Write the failing test in the file from `files.test` asserting this one Acceptance Criterion. Run it and confirm it fails **for the right reason**.
+     2. **(Green)** Implement the minimum code (in `files.create` / `files.modify`) to make the test pass.
+     3. **(Refactor)** Clean up naming, duplication, and structure while keeping the test green.
+   - `## Test Scenarios` — the assertion(s) for this criterion: `[Scenario]: [Input -> Expected Outcome]` (required for Phase 1–2; optional for rollout-only). May be a single scenario (this task asserts one criterion).
+   - `## Dependencies` — `task-id: why` or `None`.
+   - `## Notes` — carry the relevant `Related Learnings` and any gotchas.
+4. **Validate** each task file against the [task.md template](../references/templates/artifacts/task.md) validation rules (singular AC, one test per AC, Red-first Steps, repository-relative paths).
+
+### Step 7: Save Task Files
+
+1. **Create the task directory** `docs/tasks/<plan-id>/` if it does not exist.
+2. **Save each task file** to `docs/tasks/<plan-id>/T<NN>-<kebab-case-name>.md`.
+3. **Verify** all files were written successfully.
+
+### Step 8: Update Tasks Index
+
+Append a section to `docs/tasks/<plan-id>/index.md`. Mark each task with `- [ ]` (unchecked); the Work skill updates these to `- [x]` as tasks complete.
+
+```markdown
+## <plan-id> — [Plan Title]
+
+- [ ] T01 — [Task title] (`U1`, AC: [criterion]) — `docs/tasks/<plan-id>/T01-<name>.md`
+- [ ] T02 — [Task title] (`U2a`, AC: [criterion]) — `docs/tasks/<plan-id>/T02-<name>.md`
+```
+
+If the index does not exist, create it with a header and the new section. If it exists but is malformed, log a warning and append the section without reformatting existing content.
+
+### Step 9: Return to Orchestrator
+
+1. **Return the task manifest**:
+
+   ```yaml
+   plan-id: YYYY-MM-DD-NNN
+   task-count: <N>
+   tasks:
+     - id: <plan-id>-T01
+       path: docs/tasks/<plan-id>/T01-<name>.md
+       unit: U1
+       acceptance_criterion: "[criterion]"
+       priority: P0
+       dependencies: []
+     - id: <plan-id>-T02
+       path: docs/tasks/<plan-id>/T02-<name>.md
+       unit: U2a
+       acceptance_criterion: "[criterion]"
+       priority: P1
+       dependencies: [<plan-id>-T01]
+   interactionMode: detailed | smart | autopilot
+   ```
+
+2. **Inform the Orchestrator** that the Plan workflow is complete. The task files are ready for the Work skill (`work/SKILL.md`) to execute in dependency order.
+
+## Output: Task Artifacts
+
+- Verify that **one task file exists per Acceptance Criterion** (never one task for multiple criteria), saved to `docs/tasks/<plan-id>/T<NN>-<name>.md`.
+- Verify that each task carries **exactly one Acceptance Criterion** and **exactly one `files.test` entry** (its own test asserting that criterion).
+- Verify that each task's `## Steps` are ordered **Red → Green → Refactor**, with the failing test written and confirmed before implementation.
+- Verify that task IDs are zero-padded 2 digits matching dependency order, with no gaps.
+- Verify that no task depends on a later task (dependency order is valid).
+- Verify that `docs/tasks/<plan-id>/index.md` has been updated with an unchecked checklist for all tasks.
+- Verify that the task manifest returned to the Orchestrator accurately reflects the saved files.
+
+> The Task Artifacts are the handoff to the Work skill. Each task is self-contained around a single Acceptance Criterion and its test — executable without re-reading the full plan.

package/skills/plan/references/design-complexity-assessment.md

@@ -0,0 +1,118 @@
+---
+title: Design Complexity Assessment
+description: Reference for the Design phase. Defines the complexity scoring algorithm across five dimensions, the heuristics for assigning complexity levels, and how complexity maps to interaction-mode pause behavior.
+type: reference
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Design Complexity Assessment
+
+This file documents the complexity scoring system used by the **Design** phase (Phase 3) to size a solution and decide whether to pause for user confirmation in Smart mode. It defines five scoring dimensions, the complexity-level thresholds, and the mapping to interaction-mode behavior.
+
+## When to Apply
+
+Complexity assessment runs at the end of the Design phase, after the approach and implementation units have been drafted but before the artifact is presented or saved. The resulting `complexity` field is written to the Design Artifact and read by the Generate phase to select a plan tier (see [plan-tier-selection.md](plan-tier-selection.md)).
+
+## Scoring Dimensions
+
+Score each dimension from 0 to 3, then sum for a total complexity score (0–15).
+
+| Dimension               | 0 — None                | 1 — Low                 | 2 — Medium                        | 3 — High                          |
+| ----------------------- | ----------------------- | ----------------------- | --------------------------------- | --------------------------------- |
+| **Scope Breadth**       | Single file             | 2–3 files, one module   | Multiple modules                  | Cross-system / cross-repo         |
+| **Integration Surface** | No new integrations     | One new internal API    | Multiple internal or one external | Multiple external / third-party   |
+| **Risk Level**          | LOW (from research)     | MEDIUM (single area)    | HIGH (single area)                | HIGH (multiple areas) or CRITICAL |
+| **Novelty**             | Existing pattern reused | Minor variation         | New pattern in familiar domain    | New pattern in unfamiliar domain  |
+| **Data / Migration**    | No data changes         | Additive, backward-safe | Schema change with migration path | Destructive or no rollback path   |
+
+### Dimension Definitions
+
+- **Scope Breadth** — How many files, modules, or systems the change touches. Read from the Implementation Units' `Files` lists.
+- **Integration Surface** — Number and kind of APIs/services the solution must connect to. Pull from the Research Findings `Patterns Found` and `Tech Stack`.
+- **Risk Level** — Inherited from the Research phase `High-Risk Detection`. Do not re-score; copy the value.
+- **Novelty** — Whether the approach reuses an existing local pattern or introduces a new one. Compare the chosen approach against `Patterns Found` confidence levels.
+- **Data / Migration** — Whether data schemas change and whether the change is reversible. Read from the Design's `Operational / Rollout Notes` draft.
+
+## Complexity Level Thresholds
+
+Map the total score to a complexity level:
+
+```
+total = sum(scope_breadth, integration_surface, risk_level, novelty, data_migration)
+
+if total >= 11:
+  complexity = VERY_HIGH
+elif total >= 7:
+  complexity = HIGH
+elif total >= 4:
+  complexity = MEDIUM
+elif total >= 1:
+  complexity = LOW
+else:
+  complexity = TRIVIAL
+```
+
+| Level     | Score Range | Typical Profile                                     |
+| --------- | ----------- | --------------------------------------------------- |
+| TRIVIAL   | 0           | Single-file tweak, no integrations, LOW risk        |
+| LOW       | 1–3         | Small feature, one module, no migration             |
+| MEDIUM    | 4–6         | Multi-module feature, one integration, additive     |
+| HIGH      | 7–10        | Cross-module or external integration, schema change |
+| VERY_HIGH | 11–15       | Cross-system, multiple risks, destructive migration |
+
+## Mapping to Interaction Mode
+
+| Mode      | Pause Behavior                                          |
+| --------- | ------------------------------------------------------- |
+| Detailed  | Always pause; show units and complexity; ask to proceed |
+| Smart     | Pause **only** if `complexity = VERY_HIGH`              |
+| Autopilot | Never pause; auto-proceed                               |
+
+**Smart mode also pauses if any of these flags are true** (regardless of complexity):
+
+- Research phase reported HIGH risk and `patterns_found_count < 3`
+- 3+ learning gaps were identified in the Scope phase
+- The selected approach has no local pattern precedent (Novelty = 3)
+
+## Mapping to Plan Tier
+
+Complexity feeds into tier selection in the Generate phase:
+
+| Complexity       | Default Tier | Rationale                                  |
+| ---------------- | ------------ | ------------------------------------------ |
+| TRIVIAL / LOW    | Fast         | Short plan; minimal structure needed       |
+| MEDIUM           | Standard     | Full template; phased units; risk table    |
+| HIGH / VERY_HIGH | Deep         | Full template + alternatives + rollout ops |
+
+See [plan-tier-selection.md](plan-tier-selection.md) for the complete tier-selection algorithm, including how complexity combines with risk and user preference.
+
+## Worked Example
+
+**Task:** Migrate session storage from in-memory to Redis.
+
+| Dimension           | Score | Reasoning                                         |
+| ------------------- | ----- | ------------------------------------------------- |
+| Scope Breadth       | 2     | Multiple modules: middleware, store, client       |
+| Integration Surface | 2     | One external system (Redis)                       |
+| Risk Level          | 2     | HIGH (single area: sessions/auth)                 |
+| Novelty             | 1     | Redis is new to the codebase but pattern is known |
+| Data / Migration    | 1     | Additive; sessions expire naturally               |
+| **Total**           | **8** | **Complexity: HIGH**                              |
+
+Result: In Smart mode, this would **not** pause (HIGH, not VERY_HIGH) unless the secondary flags trigger (e.g., 3+ learning gaps).
+
+## Error Handling
+
+| Scenario                                                         | Recovery                                 |
+| ---------------------------------------------------------------- | ---------------------------------------- |
+| Risk level missing from Research artifact                        | Default to MEDIUM (score 2); log warning |
+| Implementation Units not yet drafted                             | Defer scoring until units exist          |
+| Two dimensions conflict (e.g., LOW risk + destructive migration) | Use the higher score; log warning        |
+| Score lands exactly on a threshold (e.g., 7)                     | Round up to the higher level (HIGH)      |
+
+## Notes
+
+- Complexity is a planning aid, not a precise metric — favor conservative (higher) scoring when uncertain
+- The complexity value must be written to the Design Artifact for the Generate phase to consume
+- If the user overrides the tier in the Generate phase, complexity is preserved for reference but no longer drives tier selection

package/skills/plan/references/error-handling.md

@@ -0,0 +1,155 @@
+---
+title: Error Handling & Recovery
+description: Reference for error handling and recovery strategies in the Plan Skill phases. Provides guidance on how to handle missing or malformed artifacts, invalid user input, and other common errors.
+type: reference
+version: 1.2
+timestamp: "2026-08-07"
+---
+
+# Error Handling & Recovery
+
+This file documents the error handling and recovery strategies shared across all Plan Skill phases (Scope, Research, Design, Generate, Tasks). Each phase begins with a **Step 0: Verification** that validates the incoming artifact; this reference defines the validation rules, recovery actions, and termination conditions.
+
+## Core Principle
+
+**Fail explicitly, never silently.** When an artifact is missing, malformed, or inconsistent, the phase must surface a clear error with a recovery suggestion rather than guessing or proceeding with bad data. Silent failures cascade downstream and produce invalid plans.
+
+## Step 0: Artifact Verification
+
+Every phase receives an artifact from the previous phase (or the Orchestrator, for Scope). Step 0 validates the artifact before any work begins.
+
+### Verification Procedure
+
+```
+1. Confirm the artifact exists and is non-empty
+2. Confirm the required frontmatter fields are present and well-formed
+3. Confirm the artifact type matches the expected phase input
+4. Confirm interactionMode is present and valid (default to "smart" if missing)
+5. Confirm status field indicates the previous phase completed successfully
+```
+
+### Required Fields by Artifact Type
+
+| Artifact Type | Required Fields                                                                                                                                                                                                                            | Produced By  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
+| `user-input`  | `type`, `timestamp`, `source`, `status`, Task Description, Intended Behavior                                                                                                                                                               | Orchestrator |
+| `scope`       | `type`, `scope-id`, `domain`, `status`, `interactionMode`, Problem, Intended Behavior, Success Criteria                                                                                                                                    | Scope        |
+| `research`    | `research-id`, `scope-id`, `status`, `interactionMode`, Patterns Found, High-Risk Detection, Tech Stack                                                                                                                                    | Research     |
+| `design`      | `design-id`, `scope-id`, `research-id`, `status`, `interactionMode`, `complexity`, `tier_recommended`, Approach, High-Level Technical Design, Implementation Units (each with Acceptance Criteria), Alternative Approaches, Complexity | Design       |
+| `plan`        | `plan-id`, `type`, `title`, `status`, `tier`, `tier_recommended`, `complexity`, `risk`, `scope-id`, `research-id`, `design-id`, `interactionMode`, `created`, `updated`, `version`, High-Level Design, Implementation Units, Risk Analysis | Generate     |
+
+## Error Categories
+
+### Category 1: Missing Artifact
+
+The expected input artifact was not provided by the Orchestrator or previous phase.
+
+| Trigger                           | Recovery Action                                               | Terminate?         |
+| --------------------------------- | ------------------------------------------------------------- | ------------------ |
+| Artifact object is null/undefined | Ask Orchestrator to re-run previous phase                     | Yes, after 1 retry |
+| Artifact file path does not exist | Log warning; ask user to locate file or re-run previous phase | No                 |
+| Artifact file is empty (0 bytes)  | Re-run previous phase from its saved context                  | Yes, after 1 retry |
+
+### Category 2: Malformed Artifact
+
+The artifact exists but is missing required fields or has invalid structure.
+
+| Trigger                                       | Recovery Action                                             | Terminate? |
+| --------------------------------------------- | ----------------------------------------------------------- | ---------- |
+| Missing required frontmatter field            | Re-run previous phase to regenerate artifact                | No         |
+| `interactionMode` missing or invalid          | Default to `smart`; log warning; continue                   | No         |
+| `status` field is `failed` or `pending`       | Reject; ask Orchestrator to re-run previous phase           | Yes        |
+| Artifact `type` does not match expected input | Reject; ask Orchestrator to check phase ordering            | Yes        |
+| YAML frontmatter has syntax errors            | Log error with line number; ask user to fix or re-run phase | No         |
+
+### Category 3: Invalid User Input
+
+Only applies to the Scope phase (Step 0) when validating the User Input Artifact.
+
+| Trigger                                             | Recovery Action                                      | Terminate? |
+| --------------------------------------------------- | ---------------------------------------------------- | ---------- |
+| Task Description empty or > 500 chars               | Ask: "What problem are you trying to solve?"         | No         |
+| Intended Behavior empty or unobservable             | Ask: "What should happen after this is implemented?" | No         |
+| Context Source is not a valid enum value            | Infer from input origin; ask if ambiguous            | No         |
+| Task Description AND Intended Behavior both missing | Abort; ask user to return with more context          | Yes        |
+
+### Category 4: File System Errors
+
+Errors encountered while saving or reading artifact files.
+
+| Trigger                                          | Recovery Action                                                   | Terminate?         |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ------------------ |
+| Target directory does not exist                  | Create directory (`mkdir -p`); treat counter as 0; start from 001 | No                 |
+| Counter directory exists but no files match date | Start counter at 001                                              | No                 |
+| File write permission denied                     | Log error; ask user to check permissions; retry once              | Yes, after 1 retry |
+| Index file (`docs/plans/index.md`) missing       | Create empty index; append entry                                  | No                 |
+| Index file locked or corrupted                   | Log warning; skip index update; continue with save                | No                 |
+
+### Category 5: Interaction Mode Errors
+
+Errors related to `interactionMode` propagation.
+
+| Trigger                                  | Recovery Action                                            | Terminate? |
+| ---------------------------------------- | ---------------------------------------------------------- | ---------- |
+| Mode missing from incoming artifact      | Default to `smart`; log warning; continue                  | No         |
+| Mode value is not in enum                | Reject; re-prompt Orchestrator to set valid mode           | Yes        |
+| User selects "Abort" during confirmation | Stop immediately; inform Orchestrator of abort with reason | Yes        |
+| User does not respond (timeout)          | Pause; ask user to retry or abort                          | No         |
+
+## Recovery Workflow
+
+When a verification failure is detected in Step 0, apply this workflow:
+
+```
+1. Identify the error category (1-5) from the tables above
+2. Look up the specific trigger to find the recovery action
+3. Execute the recovery action:
+   - If recovery is "ask user": ask one question with clear options (2–4 concrete choices)
+   - If recovery is "re-run previous phase": return to Orchestrator with error context
+   - If recovery is "default and continue": apply default, log warning, proceed
+4. If terminate = Yes: stop and inform Orchestrator with:
+   - Error category and trigger
+   - Recovery action attempted
+   - Reason for termination
+5. If terminate = No: after recovery, continue to Step 1 of the phase
+```
+
+## Retry Limits
+
+- **Maximum retries per error:** 1
+- **Maximum total retries per phase:** 2
+- After exhausting retries, terminate with a clear error message explaining what failed and suggesting the user re-run the planning workflow from the start or from the last successful phase.
+
+## Error Reporting Format
+
+When reporting an error to the Orchestrator or user, use this format:
+
+```yaml
+error:
+  phase: scope | research | design | generate | tasks
+  step: 0 | 1 | 2 | ...
+  category: 1 | 2 | 3 | 4 | 5
+  trigger: "[specific trigger description]"
+  recovery_attempted: "[action taken]"
+  outcome: recovered | terminated
+  suggestion: "[next step for the user or Orchestrator]"
+```
+
+## Cross-Phase Consistency Checks
+
+In addition to per-phase verification, the Orchestrator should verify consistency between phases:
+
+| Check                                                | Action on Failure                           |
+| ---------------------------------------------------- | ------------------------------------------- |
+| `scope-id` in research artifact matches scope output | Reject research; re-run from scope          |
+| `scope-id` in design artifact matches scope output   | Reject design; re-run from research         |
+| `plan-id` references the correct design artifact     | Reject generate; re-run from design         |
+| `interactionMode` is identical across all artifacts  | Log warning; use earliest non-default value |
+
+## Notes
+
+- All errors and warnings should be logged with a timestamp for debugging
+- When a phase terminates, its saved artifact (if any) should be marked `status: failed`
+- The Orchestrator is responsible for deciding whether to retry the entire workflow or resume from the last successful phase
+- ID assignment and re-use (including recycle-on-edit) is defined in [id-generation.md](id-generation.md); this reference covers only verification and recovery
+- This reference is shared by all five phases; phase-specific error handling (e.g., research's "no patterns found") is documented inline in the respective module

package/skills/plan/references/external-research-guidance.md

@@ -0,0 +1,61 @@
+---
+title: External Research Guidance
+description: Guidance for generating targeted external research queries when high-risk areas are detected and external research is recommended.
+type: reference
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# External Research Guidance
+
+This file documents how to generate targeted external research queries when high-risk areas are detected and external research is recommended.
+
+## When to Run External Research
+
+External research is recommended when:
+
+- One or more high-risk areas identified (see high-risk-detection.md)
+- Fewer than 3 similar local implementations found
+
+## Generating Targeted Queries
+
+Generate specific, actionable queries that include:
+
+- **Topic:** The specific area (e.g., "payment gateway", "OAuth2 implementation")
+- **Tech stack:** Relevant technologies (e.g., "Node.js", "Express", "PostgreSQL")
+- **Scope:** Information type (e.g., "best practices", "patterns", "troubleshooting")
+- **Year:** Current year for recent guidance
+
+## Query Templates
+
+| Area           | Template                                  | Example                                        |
+| -------------- | ----------------------------------------- | ---------------------------------------------- |
+| Security       | `[area] patterns [tech-stack] [year]`     | `JWT authentication patterns Node.js 2026`     |
+| Payments       | `[provider] integration [tech-stack]`     | `Stripe integration Node.js best practices`    |
+| API Design     | `[type] design patterns [year]`           | `REST API versioning strategies 2026`          |
+| Migrations     | `[type] migration guide [tech-stack]`     | `Database migration PostgreSQL best practices` |
+| Complex Logic  | `[algorithm] implementation [tech-stack]` | `Search optimization patterns Node.js`         |
+| Infrastructure | `[tech] [deployment] patterns [year]`     | `Kubernetes deployment best practices 2026`    |
+
+## Executing External Research
+
+Use generated queries with:
+
+- **Web search:** Use the agent's web search or fetch capabilities with your generated query
+- **Manual research:** GitHub, official docs, blogs, Stack Overflow
+- **Integration:** Some agents may offer specialized research tools — check agent documentation
+
+## Refining Queries
+
+| Finding            | Strategy                               |
+| ------------------ | -------------------------------------- |
+| Too many results   | Add "best practices" or "production"   |
+| Too few results    | Broaden or use alternative terminology |
+| Outdated info      | Add current year to query              |
+| Conflicting advice | Compare approaches side-by-side        |
+
+## Notes
+
+- Queries should be actionable and specific to the tech stack
+- Use whatever web search or research capabilities are available in your agent environment
+- Capture findings as learnings after research to build organizational knowledge