arreio 1.1.0 → 1.2.0

package/README.md

@@ -34,13 +34,25 @@ Run this command in your AI coding agent to:
 2. Create the project structure (`docs/plans/`, `docs/learn/`, etc.)
 3. Set up architectural documentation and index files
 
-This makes all five core skills available in your AI development environment:
+This makes all six skills available in your AI development environment:
 
 - **arreio-init** - Initialize projects to follow the Arreio workflow
 - **plan** - Structure and decompose work into executable tasks
 - **work** - Execute tasks with guardrailed implementation
 - **review** - Conduct comprehensive code reviews
 - **learn** - Capture and refine knowledge from completed work
+- **end-session** - Commit the session with a traceable session artifact
+
+## Quick Start
+
+```text
+/plan [--deep] Add Redis-backed session storage      # produce a plan (+ optional task files)
+/work <plan-id>                                      # execute the plan's tasks, test-first
+/review <work-id | git range | description>          # review the changes, get a verdict
+/learn <candidate-ref | decision "text">             # keep what the team learned
+```
+
+Each skill is invoked by prompt (`/plan`, `/work`, `/review`, `/learn`) and first asks you to choose an interaction mode.
 
 ## Skill Based Workflow
 
@@ -48,8 +60,22 @@ This makes all five core skills available in your AI development environment:
 
 Use /arreio-init to initialize a new project, to enable the project to follow the four phases of the Arreio workflows.
 
+### Interaction Modes
+
+Every pipeline asks for an interaction mode before it starts:
+
+| Mode          | Behavior                                                                         |
+| ------------- | -------------------------------------------------------------------------------- |
+| **Detailed**  | Confirm at each phase transition; inspect every artifact. Maximum control.       |
+| **Smart**     | Phases run automatically; pause only on risky, destructive, or ambiguous events. |
+| **Autopilot** | Phases run automatically; only the final outcome is reported.                    |
+
+Intermediate phase artifacts (scope, research, triage, analyze, etc.) are written to hidden folders **only in Detailed mode**; in Smart/Autopilot they are passed in context. Final deliverables (plans, tasks, reports, learn entries) are always written.
+
 ### Plan
 
+Invoke with `/plan [--deep] <task description>`.
+
 | Phase | Module Name  | Purpose                                   |
 | ----- | ------------ | ----------------------------------------- |
 | 1     | **scope**    | Gather context, validate domain           |
@@ -58,8 +84,16 @@ Use /arreio-init to initialize a new project, to enable the project to follow th
 | 4     | **generate** | Select tier, render plan, save to docs    |
 | 5     | **tasks**    | Slice plan into executable tasks          |
 
+**Plan tiers.** The Generate phase right-sizes the plan: **Fast** (trivial/low complexity), **Standard** (medium), or **Deep** (high/very high complexity, with alternatives and rollout notes). The tier comes from a complexity score (five dimensions, 0–15) combined with the detected risk level; high risk raises the minimum tier. Choosing `Auto` uses the computed recommendation, which is recorded as `tier_recommended`.
+
+**`--deep`.** Put `--deep` at the start or end of the input to force a Deep plan in any interaction mode (including Autopilot), without the tier question. The algorithm's own recommendation is still recorded in `tier_recommended`, so the override is auditable.
+
+Plan outputs: `docs/plans/YYYY-MM-DD-NNN-<name>.md` (indexed in `docs/plans/index.md`) and, optionally, one task file per acceptance criterion in `docs/tasks/<plan-id>/`.
+
 ### Work
 
+Invoke with `/work <plan-id>`, `/work <task file or task-id>`, or `/work <task description>` (ad-hoc). Work runs on its own `work/<short-description>` git branch, executes each task Red → Green → Refactor, and chooses an **execution mode** (inline, serial, or parallel waves) from task priority, risk, and dependencies; HIGH-risk tasks always run inline.
+
 | Phase | Module Name | Purpose                                   |
 | ----- | ----------- | ----------------------------------------- |
 | 1     | **triage**  | Classify input and extract context        |
@@ -69,12 +103,14 @@ Use /arreio-init to initialize a new project, to enable the project to follow th
 
 ### Review
 
+Invoke with `/review <git range | HEAD | branch | paths>`, `/review <work-id>`, or `/review <target description>`. Findings are graded `blocker` / `major` / `minor` / `nit` across quality, security, tests, documentation, integration, and scope creep, and the approval status (`approved` / `changes-requested` / `rejected`) is derived from the findings. Review is local and read-only: reports are written to `docs/review/`, never posted to GitHub.
+
 | Phase | Module Name | Purpose                          |
 | ----- | ----------- | -------------------------------- |
 | 1     | **scope**   | Classify input and scope review  |
 | 2     | **prepare** | Set up review environment        |
 | 3     | **analyze** | Execute code review, find issues |
-| 4     | **report**  | Report verdict                   |
+| 4     | **report**  | Derive approval, write report    |
 
 ### Learn
 
@@ -85,6 +121,23 @@ Use /arreio-init to initialize a new project, to enable the project to follow th
 | 3     | **index**    | Catalog and index the entry         |
 | 4     | **maintain** | Dedup, refresh, and prune entries   |
 
+Invoke with `/learn <decision|pattern|gotcha|workflow> <text>`, `/learn <candidate-ref>` (a Work or Review `learnings-to-capture` item), or `/learn maintain`. Entries live in `docs/learn/<type>/`, are indexed in `docs/learn/index.md`, and are searched by Plan, Work, and Review.
+
+### Project Structure
+
+After `/arreio-init`, generated artifacts live under `docs/`:
+
+```text
+docs/
+  plans/   final plans + index.md   (hidden .scope/.research/.design/ in Detailed mode)
+  tasks/   <plan-id>/ task files + index.md
+  learn/   decision/ pattern/ gotcha/ workflow/ + index.md
+  review/  index.md + .report/      (other hidden phase folders in Detailed mode)
+  archives/
+```
+
+Whether to commit `docs/` is your choice; this repository ignores it.
+
 ### Supporting Skills
 
 We have designed a set of supporting skills to help you to manage your repository and work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arreio",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Arreio transforms agentic coding workflows into a predictable, safe, and high-quality software delivery pipeline. Master the four core phases—Plan, Work, Review, Learn—to orchestrate a highly reliable development cycle.",
   "license": "MIT",
   "author": "Wicttor",

package/skills/arreio-init/SKILL.md

@@ -92,7 +92,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** If `docs/learn/index.md` doesn't exist, create it using the [Learn Index Template](references/learn-index-template.md).
 
-### Step 7: Create Plan Skill Hidden Artifact Directories
+### Step 7: Plan Skill Hidden Artifact Directories (not created at init)
 
 **Folders:**
 
@@ -100,11 +100,11 @@ Creates the organizational spine for Arreio artifacts:
 - `docs/plans/.research/` — Stores Research phase artifacts
 - `docs/plans/.design/` — Stores Design phase artifacts
 
-**Rationale:** The `plan/SKILL.md` orchestrator saves intermediate phase artifacts in these hidden directories to preserve the planning trail and enable recovery/resumption.
+**Rationale:** The `plan/SKILL.md` orchestrator writes intermediate phase artifacts to these hidden directories **only when the user picks `detailed` interaction mode**. In `smart`/`autopilot` they are passed in context.
 
-**Action:** Create all three directories if they don't exist.
+**Action:** Do **not** create them. The plan skill creates them lazily on first `detailed` run.
 
-### Step 8: Create Work Skill Hidden Artifact Directories
+### Step 8: Work Skill Artifact Directories
 
 **Folders:**
 
@@ -113,11 +113,11 @@ Creates the organizational spine for Arreio artifacts:
 - `docs/plans/.work/.execute/` — Stores Execute phase artifacts
 - `docs/plans/.work/.review/` — Stores Review phase artifacts
 
-**Rationale:** The `work/SKILL.md` orchestrator saves phase artifacts here during task execution to track work progress and decisions.
+**Rationale:** `.triage/`, `.prepare/`, `.execute/` hold intermediate artifacts written **only in `detailed` mode**. `.review/` holds the Work Report, which is always written (read by `/review` and `/learn`).
 
-**Action:** Create all four directories if they don't exist.
+**Action:** Create only `docs/plans/.work/.review/`. The work skill creates the other three lazily on first `detailed` run.
 
-### Step 9: Create Review Skill Hidden Artifact Directories and Registry
+### Step 9: Review Skill Artifact Directories and Registry
 
 **Folders:**
 
@@ -130,9 +130,9 @@ Creates the organizational spine for Arreio artifacts:
 
 - `docs/review/index.md` — Central registry of all review reports
 
-**Rationale:** The `review/SKILL.md` orchestrator saves phase artifacts in these hidden directories and maintains a central index of all review reports.
+**Rationale:** `.scope/`, `.prepare/`, `.analyze/` hold intermediate artifacts written **only in `detailed` mode**. `.report/` holds the Review Report (always written). The orchestrator also maintains a central index of all review reports.
 
-**Action:** Create all four directories if they don't exist. If `docs/review/index.md` doesn't exist, create it with a header:
+**Action:** Create only `docs/review/.report/`; the review skill creates the other three lazily on first `detailed` run. If `docs/review/index.md` doesn't exist, create it with a header:
 
 ```markdown
 ---
@@ -153,7 +153,7 @@ This is the index of all review reports for the project. Reports are organized b
 _No review reports yet._
 ```
 
-### Step 10: Create Learn Skill Hidden Artifact Directories
+### Step 10: Learn Skill Hidden Artifact Directories (not created at init)
 
 **Folders:**
 
@@ -162,9 +162,9 @@ _No review reports yet._
 - `docs/learn/.index/` — Stores Index phase artifacts
 - `docs/learn/.maintain/` — Stores Maintain phase artifacts
 
-**Rationale:** The `learn/SKILL.md` orchestrator saves phase artifacts in these hidden directories to preserve the knowledge entry authoring trail.
+**Rationale:** The `learn/SKILL.md` orchestrator writes phase artifacts here **only in `detailed` mode**. Durable entries and the index are always written elsewhere.
 
-**Action:** Create all four directories if they don't exist.
+**Action:** Do **not** create them. The learn skill creates them lazily on first `detailed` run.
 
 ### Step 11: Create End-Session Skill Hidden Artifact Directory
 
@@ -205,15 +205,10 @@ After initialization, verify:
 - ✓ Root-level index files exist:
   - `docs/plans/index.md` (registry of all plans)
   - `docs/learn/index.md` (central knowledge base)
-- ✓ Plan skill hidden artifact directories exist:
-  - `docs/plans/.scope/`, `docs/plans/.research/`, `docs/plans/.design/`
-- ✓ Work skill hidden artifact directories exist:
-  - `docs/plans/.work/.triage/`, `docs/plans/.work/.prepare/`, `docs/plans/.work/.execute/`, `docs/plans/.work/.review/`
-- ✓ Review skill hidden artifact directories exist:
-  - `docs/review/.scope/`, `docs/review/.prepare/`, `docs/review/.analyze/`, `docs/review/.report/`
+- ✓ Always-written report directories exist:
+  - `docs/plans/.work/.review/` (Work Reports), `docs/review/.report/` (Review Reports)
   - `docs/review/index.md` (review reports registry)
-- ✓ Learn skill hidden artifact directories exist:
-  - `docs/learn/.capture/`, `docs/learn/.refine/`, `docs/learn/.index/`, `docs/learn/.maintain/`
+- ✓ Intermediate phase-artifact directories (`.scope/`, `.research/`, `.design/`, `.triage/`, `.prepare/`, `.execute/`, `.analyze/`, `.capture/`, `.refine/`, `.index/`, `.maintain/`) are **not** created — skills create them lazily, only in `detailed` interaction mode
 - ✓ End-session skill hidden artifact directory exists:
   - `docs/plans/.end-session/`
 - ✓ Learn category folders exist:
@@ -225,10 +220,10 @@ After initialization, verify:
 
 Downstream skills (plan, learn, work, review) automatically create missing folders and indexes if arreio-init wasn't explicitly run:
 
-- **plan** skill creates missing `docs/plans/` core folders, and allocates `docs/plans/.scope/`, `.research/`, `.design/` directories on first use.
-- **work** skill creates missing `docs/plans/.work/` directories (`.triage/`, `.prepare/`, `.execute/`, `.review/`) on first execution.
-- **review** skill creates missing `docs/review/` directories and `index.md` registry on first review.
-- **learn** skill creates missing phase-artifact directories under `docs/learn/` and the `docs/learn/` category folders on first learning capture.
+- **plan** skill creates missing `docs/plans/` core folders; creates `docs/plans/.scope/`, `.research/`, `.design/` only in `detailed` mode.
+- **work** skill creates `docs/plans/.work/.review/` on first execution; creates `.triage/`, `.prepare/`, `.execute/` only in `detailed` mode.
+- **review** skill creates `docs/review/.report/` and the `index.md` registry on first review; creates `.scope/`, `.prepare/`, `.analyze/` only in `detailed` mode.
+- **learn** skill creates the `docs/learn/` category folders on first learning capture; creates `.capture/`, `.refine/`, `.index/`, `.maintain/` only in `detailed` mode.
 - **end-session** skill creates missing `docs/plans/.end-session/` directory (and the `## Session Ends` section in `docs/plans/index.md`) on first session end.
 
 **However**, running `arreio-init` upfront provides several benefits:

package/skills/learn/SKILL.md

@@ -38,6 +38,8 @@ Store in the context object:
 interactionMode: detailed | smart | autopilot
 ```
 
+**Artifact persistence:** intermediate phase artifacts are written to disk **only in `detailed` mode**. In `smart`/`autopilot` they are passed between phases in context and never written (see `references/interaction-mode-propagation.md#artifact-persistence`). Final deliverables are always written.
+
 **Propagation:** `interactionMode` flows into the `capture`, `refine`, `index`, and `maintain` artifacts; each downstream phase reads it to adjust confirmation behaviour (detailed = pause every transition + before destructive writes; autopilot = run all; smart = pause only on duplicates, prunes, and migrations).
 
 ## Orchestration Implementation
@@ -60,7 +62,7 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 Before starting the learn pipeline, the orchestrator verifies that required folders exist:
 
 - `docs/learn/` — must exist for writing entries and the index; the seed `docs/learn/index.md` must exist (empty `entries:` block is valid — the legacy migration populates 28 entries)
-- `docs/learn/.capture/`, `docs/learn/.refine/`, `docs/learn/.index/`, `docs/learn/.maintain/` — must exist for saving the phase artifacts
+- `docs/learn/.capture/`, `docs/learn/.refine/`, `docs/learn/.index/`, `docs/learn/.maintain/` — **`detailed` mode only**, for saving the phase artifacts; do not create them in `smart`/`autopilot`
 
 **Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`), and seeds `docs/learn/index.md` from the [index-format.md](references/index-format.md) template. This allows the Learn skill to run even if `arreio-init` wasn't explicitly run.
 
@@ -70,10 +72,10 @@ For **explicit** input, verify `<type>` is one of the four; if not, ask to pick
 
 | Phase | Phase Module                          | Output Artifact                                                              | Saved to                               |
 | ----- | ------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------- |
-| 1     | [Capture](modules/capture.md)        | [Captured entry](references/templates/artifacts/captured-entry.md)           | `docs/learn/.capture/<id>.md`   |
-| 2     | [Refine](modules/refine.md)          | [Refined entry](references/templates/artifacts/refined-entry.md)             | `docs/learn/.refine/<id>.md`    |
-| 3     | [Index](modules/index.md)            | [Index update](references/templates/artifacts/index-update.md)               | `docs/learn/.index/<id>.md`     |
-| 4     | [Maintain](modules/maintain.md) _(on demand)_ | [Maintain log](references/templates/artifacts/maintain-log.md)   | `docs/learn/.maintain/<id>.md`  |
+| 1     | [Capture](modules/capture.md)        | [Captured entry](references/templates/artifacts/captured-entry.md)           | `docs/learn/.capture/<id>.md` _(detailed only)_ |
+| 2     | [Refine](modules/refine.md)          | [Refined entry](references/templates/artifacts/refined-entry.md)             | `docs/learn/.refine/<id>.md` _(detailed only)_ |
+| 3     | [Index](modules/index.md)            | [Index update](references/templates/artifacts/index-update.md)               | `docs/learn/.index/<id>.md` _(detailed only)_ |
+| 4     | [Maintain](modules/maintain.md) _(on demand)_ | [Maintain log](references/templates/artifacts/maintain-log.md)   | `docs/learn/.maintain/<id>.md` _(detailed only)_ |
 
 **Phase 4 is on-demand.** A normal `/learn <type> <text>` run executes Phases 1–3 and writes one entry; Maintain runs only via `/learn maintain`. The migration procedure (legacy → canonical) is a Maintain operation, run once.
 
@@ -104,7 +106,7 @@ The **Index phase** is the skill's only index writer for authored entries; the *
 
 - **Entry file:** Saved to `docs/learn/<type>/<slug>.md` with the [entry-schema.md](references/entry-schema.md) frontmatter (`type`, `domain`, `tags`, `applicability`, `summary`, plus `created_at`/`updated_at`, `source`, `confidence`, and `related`).
 - **Index:** `docs/learn/index.md` updated — a YAML `entries:` block (the `filename` / `domain` / `tags` / `applicability` / `summary` record per entry — the **read contract** that Plan/Work/Review's [learnings-gate-logic.md](../plan/references/learnings-gate-logic.md) parses) plus the human-readable By Category / By Domain tables.
-- **Maintain Log (if `/learn maintain`):** Saved to `docs/learn/.maintain/<maintain-id>.md`, recording the dedup/refresh/prune operations performed and any migration applied.
+- **Maintain Log (if `/learn maintain`, `detailed` mode only):** Saved to `docs/learn/.maintain/<maintain-id>.md`, recording the dedup/refresh/prune operations performed and any migration applied.
 - **Not produced:** This skill produces **no session log, no event transcript, no "what we did."** Only durable entries and the index.
 
 ## References
@@ -135,6 +137,17 @@ Artifact templates live in [references/templates/artifacts/](references/template
 
 > The Learn skill **owns the write side** — the per-entry frontmatter schema ([entry-schema.md](references/entry-schema.md)) and the `docs/learn/index.md` format ([index-format.md](references/index-format.md)). The Plan skill **owns the read side** — the keyword/relevance search in [learnings-gate-logic.md](../plan/references/learnings-gate-logic.md), reused cross-skill by Work and Review. The two contracts share the **index-record shape** (`filename`, `domain`, `tags`, `applicability`, `summary` + the `applicability` enum). Learn **guarantees** its index satisfies that shape; it does **not** re-encode the search algorithm (honoring the secondary-spec-contradicts-authoritative-matrix gotcha — one algorithm lives in Plan's gate-logic, one schema lives here; see `docs/learn/gotcha/2026-08-07-secondary-spec-contradicts-authoritative-matrix.md` post-migration).
 
+## Execution Rules
+
+Follow these literally; they exist to keep runs consistent across agents.
+
+1. **Run each module's steps in order**, starting with its Step 0 verification. Do not skip, merge, or reorder steps.
+2. **Never invent values.** If a required input is missing, apply the recovery in [error-handling.md](references/error-handling.md) or ask the user; do not fill it with a plausible guess.
+3. **Compute, don't copy.** Values defined by a rule (`slug`, `applicability` enum, duplicate/analog matches, prune candidates) must be derived with the canonical reference and the real entry — never copied from an example or guessed. Example values in references and templates are illustrations, never defaults.
+4. **One question at a time**, with 2–4 concrete options; build the question text from the current values.
+5. **Announce phase transitions in one line** (e.g., "Phase 2/3 Refine complete: <key result>") so the user can follow progress, even in Autopilot.
+6. **Honor write rules:** intermediate phase artifacts only in `detailed` mode; final deliverables always.
+
 ## Core Principles
 
 - **Source of Truth, Not Memory:** `docs/learn/` is the project's durable, authoritative knowledge base. Plan/Work/Review search it; this skill authors and maintains it. Not a session memory, not an event log.
@@ -143,6 +156,7 @@ Artifact templates live in [references/templates/artifacts/](references/template
 - **Idempotent Writes:** Authoring a known `slug` upserts the entry file and its index record — never duplicates. Maintain rebuilds the index from the file tree and is idempotent. Re-running a normal `/learn` over the same content merges, it does not pile up.
 - **Dedup Welcomed, Lineage Preserved:** Decisions don't duplicate, but analogs exist; dedup merges an analog into the canonical entry and records the merge (the path-convention-split entry is the model — a migrated entry carries both the old and new path knowledge, not just the new; see `docs/learn/gotcha/2026-08-07-path-convention-split-silently-noops.md` post-migration).
 - **Write Side / Read Side Split:** Learn owns the entry schema and the index format; Plan owns the search algorithm. Both agree on the index-record shape. Never re-encode the other side's logic inline.
+- **Lean Persistence:** Phase artifacts hit disk only in `detailed` mode; `smart`/`autopilot` pass them in context to save tokens and time.
 - **Transparent Artifacts:** Each phase produces an explicit output artifact for the next phase.
 - **Behavior-Described, Tool-Agnostic:** Steps describe required capabilities ("write the entry file", "rebuild the index", "ask the user to confirm"), not specific tool names.
 - **Stay Portable:** Use repository-relative paths only — `docs/learn/<type>/<slug>.md`, never absolute.

package/skills/learn/modules/capture.md

@@ -70,7 +70,7 @@ Draft the entry's frontmatter and body per the authoritative write contract **[e
 ### Step 4: Propose slug and Allocate the learn-id Umbrella
 
 1. **Propose a `slug`** — a kebab-case, globally-unique stable key for the entry. Derive from the title (concise, descriptive); for time-bound decisions a date suffix is allowed (`critical-risk-tier-security-payments-2026-07-04`). The slug is the upsert key for the entry file and its index record. Refine checks uniqueness; Capture only **proposes**.
-2. **Allocate a `learn-id`** umbrella of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/learn/.capture/YYYY-MM-DD-NNN-capture.md` files for today. The `learn-id` is the pipeline umbrella carried through Capture → Refine → Index (Maintain-only runs allocate their own `maintain-id` and have no `learn-id`).
+2. **Allocate a `learn-id`** umbrella of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/learn/.capture/YYYY-MM-DD-NNN-capture.md` files for today (`detailed` mode only; in `smart`/`autopilot` use the in-memory label per id-generation.md). The `learn-id` is the pipeline umbrella carried through Capture → Refine → Index (Maintain-only runs allocate their own `maintain-id` and have no `learn-id`).
 3. **Assign a `capture-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-capture`, saved to `docs/learn/.capture/`). Reuse it if the user later picks **Edit & Retry**.
 
 ### Step 5: Generate the Captured Entry Artifact
@@ -95,7 +95,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/learn/.capture/<capture-id>.md` (ensure `interactionMode` and `target-type` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Refine).
+Then, **in `detailed` mode only**, save the artifact to `docs/learn/.capture/<capture-id>.md` (ensure `interactionMode` and `target-type` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Refine). In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Captured Entry Artifact
 
@@ -103,6 +103,6 @@ Then save the artifact to `docs/learn/.capture/<capture-id>.md` (ensure `interac
 - Verify that `target-type` is one of `decision` / `pattern` / `gotcha` / `workflow`.
 - Verify that the frontmatter and body conform to [entry-schema.md](../references/entry-schema.md) (the per-type section template), without re-encoding the schema inline.
 - Verify that the `learn-id` umbrella was allocated (Capture is the allocating phase) and the `slug` is kebab-case and descriptive.
-- Verify that the artifact is saved to `docs/learn/.capture/<capture-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/learn/.capture/<capture-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > Pass the Captured Entry to `refine` (Phase 2) for type/frontmatter validation and the duplicate + analog check against existing entries.

package/skills/learn/modules/index.md

@@ -79,7 +79,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/learn/.index/<index-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the authoring run complete — the durable entry now lives at `docs/learn/<type>/<slug>.md` and `docs/learn/index.md` reflects it.
+Then, **in `detailed` mode only**, save the artifact to `docs/learn/.index/<index-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the authoring run complete — the durable entry now lives at `docs/learn/<type>/<slug>.md` and `docs/learn/index.md` reflects it. In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Index Update Artifact
 
@@ -89,6 +89,6 @@ Then save the artifact to `docs/learn/.index/<index-id>.md` (ensure `interaction
 - Verify **index coherence** (orchestrator gate #5): the YAML block length matches the on-disk entry-file count; the per-type count headings match; no duplicate index rows.
 - Verify that a merge **de-indexed** (not deleted) the analog and recorded the `superseded-by` lineage in the analog's file — lineage preserved per [dedup-rules.md](../references/dedup-rules.md).
 - Verify that the derived `index-applicability` enum was **read from** [index-format.md](../references/index-format.md) (the derivation rule) rather than re-encoded inline.
-- Verify that the artifact is saved to `docs/learn/.index/<index-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/learn/.index/<index-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > The Index Update is the authoring run's final artifact. The Orchestrator marks the workflow complete; the durable knowledge entry lives at `docs/learn/<type>/<slug>.md` and is discoverable via `docs/learn/index.md` (the source-of-truth index Plan/Work/Review search).

package/skills/learn/modules/maintain.md

@@ -101,7 +101,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed (but destructive operations — migration, prune, merge — always surface for confirmation even in Smart, per the principle that destructive writes are never silent).
 - **Autopilot:** auto-proceed for non-destructive steps (refresh, rebuild); **still pause** for destructive operations (migration, prune) — Autopilot never silently deletes or rewrites paths.
 
-Then save the artifact to `docs/learn/.maintain/<maintain-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the Maintain run complete — the canonical knowledge base is reconciled.
+Then, **in `detailed` mode only**, save the artifact to `docs/learn/.maintain/<maintain-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the Maintain run complete — the canonical knowledge base is reconciled. In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Maintain Log Artifact
 
@@ -111,6 +111,6 @@ Then save the artifact to `docs/learn/.maintain/<maintain-id>.md` (ensure `inter
 - Verify that every prune was explicitly confirmed (no silent deletion); a delete leaves no file; a de-index keeps the file with `status: obsolete`.
 - Verify **index coherence** (orchestrator gate #5): the rebuilt `docs/learn/index.md` YAML length matches the on-disk entry-file count; per-type totals consistent; no duplicate rows.
 - Verify that the rebuild was **applied from** [index-format.md](../references/index-format.md) (and the applicability-enum derivation) rather than re-encoded inline.
-- Verify that the artifact is saved to `docs/learn/.maintain/<maintain-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/learn/.maintain/<maintain-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > The Maintain Log is the Maintain run's deliverable. The Orchestrator marks the workflow complete; the canonical knowledge base at `docs/learn/` is reconciled and `docs/learn/index.md` reflects the on-disk truth.

package/skills/learn/modules/refine.md

@@ -91,7 +91,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
 
-Then save the artifact to `docs/learn/.refine/<refine-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Index).
+Then, **in `detailed` mode only**, save the artifact to `docs/learn/.refine/<refine-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Index). In `smart` and `autopilot` mode, do **not** write the file; pass the artifact to the next phase in context (see [Artifact Persistence](../references/interaction-mode-propagation.md#artifact-persistence)).
 
 ## Output: Refined Entry Artifact
 
@@ -99,6 +99,6 @@ Then save the artifact to `docs/learn/.refine/<refine-id>.md` (ensure `interacti
 - Verify that the frontmatter conforms to [entry-schema.md](../references/entry-schema.md) (every required field valid; the per-type body template present) without re-encoding the schema inline.
 - Verify that the duplicate/analog check ran per [dedup-rules.md](../references/dedup-rules.md) and that any conflict was resolved with a recorded `resolution` (never silently two entries).
 - Verify that a merge recorded `lineage` (the analog `slug` + `superseded-by` note) — lineage preserved, never deleted.
-- Verify that the artifact is saved to `docs/learn/.refine/<refine-id>.md`.
+- Verify that, in `detailed` mode, the artifact is saved to `docs/learn/.refine/<refine-id>.md`; in `smart`/`autopilot` mode, verify that **no** file was written and the artifact was passed to the next phase in context.
 
 > Pass the Refined Entry to `index` (Phase 3) to write the entry file and upsert the canonical index.

package/skills/learn/references/id-generation.md

@@ -12,7 +12,7 @@ Shared ID algorithm for the `capture`, `refine`, `index`, and `maintain` phases,
 
 ## ID Format by Phase
 
-| Phase    | ID format                            | Saved to                            |
+| Phase    | ID format                            | Saved to (detailed only)                            |
 | -------- | ----------------------------------- | ----------------------------------- |
 | Capture  | `YYYY-MM-DD-NNN-capture`            | `docs/learn/.capture/<id>.md`   |
 | Refine   | `YYYY-MM-DD-NNN-refine`             | `docs/learn/.refine/<id>.md`    |
@@ -69,6 +69,8 @@ The `slug` is the stable, globally-unique key for a knowledge entry — it keys
 
 > **Slug is the upsert key, not a timestamp id.** A re-author with the same `slug` overwrites in place (idempotent); a new `slug` creates a new entry. The slug namespace is shared across all four types — there is one global `docs/learn/` slug space, not four.
 
+> **Persistence by mode.** The "Saved to" column and the directory-listing algorithm below apply **only in `detailed` mode**. In `smart`/`autopilot` mode phase artifacts are not written, so no directory is listed: Phase ids are in-memory labels `<date>-001-<phase>`; no directory is listed to allocate them. The `slug` is unaffected. See [Artifact Persistence](interaction-mode-propagation.md#artifact-persistence).
+
 ## Algorithm (new phase artifact)
 
 ```

package/skills/learn/references/interaction-mode-propagation.md

@@ -86,4 +86,24 @@ Learn deliberately has **no** `executionMode`:
 | Invalid mode value          | Reject; re-prompt Orchestrator        |
 | Artifact missing mode field | Assume "smart"; log warning; continue |
 | User selects "Abort"        | Stop immediately; inform Orchestrator |
-| Timeout/connection lost     | Pause; ask user to retry or abort     |
+| Timeout/connection lost     | Pause; ask user to retry or abort     |
+
+## Artifact Persistence
+
+Phase artifacts (Capture, Refine, Index, Maintain) are **handoff data between phases**, not deliverables. Whether they are written to disk depends on `interactionMode`:
+
+| Mode          | Phase artifacts (`docs/learn/.capture/`, `.refine/`, `.index/`, `.maintain/`)          | Phase handoff                                  |
+| ------------- | ---------------------------------------- | ---------------------------------------------- |
+| **Detailed**  | Written to the hidden directories (audit trail; creating the directory on first use) | Artifact is written, shown, then passed on     |
+| **Smart**     | **Not written**                          | Artifact is held in context and passed in-memory to the next phase |
+| **Autopilot** | **Not written**                          | Artifact is held in context and passed in-memory to the next phase |
+
+**Always written, in every mode:** the durable entry in `docs/learn/<type>/<slug>.md` and its `docs/learn/index.md` record (written in every mode).
+
+**Rules:**
+
+- The artifact schema, quality gates, cross-phase ID checks, and pause triggers are **unchanged** — only the disk write is skipped. Validate and pass the in-memory artifact exactly as you would the file.
+- Never create the hidden directories in `smart`/`autopilot`; no placeholder or empty files.
+- **ID allocation without files:** Phase ids are in-memory labels `<date>-001-<phase>`; no directory is listed to allocate them. The `slug` is unaffected.
+- If the user switches to `detailed` mid-run, write the artifacts produced so far, then continue writing.
+- Because nothing is on disk, **Edit & Retry** reuses the in-memory artifact and its id (no file to overwrite).

package/skills/learn/references/templates/artifacts/captured-entry.md

@@ -53,7 +53,7 @@ inferred: true | false                     # true when drafted from a short desc
                                            # false when grounded in a concrete ref/file the user provided
 ```
 
-Also save the Captured Entry Artifact to `docs/learn/.capture/<capture-id>.md`.
+In `detailed` mode only, also save the Captured Entry Artifact to `docs/learn/.capture/<capture-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/learn/references/templates/artifacts/index-update.md

@@ -50,7 +50,7 @@ entry-written: true                           # the entry file was written (fals
 index-updated: true                           # docs/learn/index.md was upserted
 ```
 
-Also save the Index Update Artifact to `docs/learn/.index/<index-id>.md`.
+In `detailed` mode only, also save the Index Update Artifact to `docs/learn/.index/<index-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/learn/references/templates/artifacts/maintain-log.md

@@ -56,7 +56,7 @@ summary:                                    # a one-line human-readable summary
   "<N> entries migrated; <M> merged; <R> normalized, <F> flagged; <P> pruned; <I> indexed"
 ```
 
-Also save the Maintain Log Artifact to `docs/learn/.maintain/<maintain-id>.md`.
+In `detailed` mode only, also save the Maintain Log Artifact to `docs/learn/.maintain/<maintain-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/learn/references/templates/artifacts/refined-entry.md

@@ -58,7 +58,7 @@ lineage:                                        # set ONLY when resolution == me
 source-candidate: <carried from Capture> | null
 ```
 
-Also save the Refined Entry Artifact to `docs/learn/.refine/<refine-id>.md`.
+In `detailed` mode only, also save the Refined Entry Artifact to `docs/learn/.refine/<refine-id>.md`. In `smart`/`autopilot` mode, do not write it; pass it to the next phase in context.
 
 ## Validation Rules
 

package/skills/plan/SKILL.md

@@ -10,7 +10,14 @@ Orchestrates a deterministic pipeline of micro-skills: `Scope -> Research -> Des
 
 ## 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.
+This skill is invoked by prompting `/plan [--deep] <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.
+
+**`--deep` flag (optional):** forces the **Deep** plan tier in any interaction mode, including Autopilot, bypassing the tier question and the complexity-based choice.
+
+- **Parsing:** `--deep` counts only as a standalone token at the **start or end** of the input. Remove it from the task description, then set `force_deep: true` in the context object. Anywhere else (e.g., inside a sentence or quoted text) it is plain text and `force_deep` stays `false`.
+- If nothing remains after removing the flag, ask: "What would you like to plan? Describe the task or project."
+- The flag does not change the interaction-mode question, `complexity`, or `tier_recommended`; it only sets `tier: deep`. The override stays auditable (`tier_recommended` keeps the algorithm's result).
+- Other `--word` tokens are not flags of this skill; leave them in the description.
 
 ## Interaction Method
 
@@ -27,8 +34,13 @@ Store in the context object:
 
 ```yaml
 interactionMode: detailed | smart | autopilot
+force_deep: true | false   # true only when `--deep` was passed; default false
 ```
 
+`force_deep` lives in the Orchestrator context (not in artifact files). Pass it to **Design** (to produce the material a Deep plan needs) and **Generate** (to select the tier).
+
+**Artifact persistence:** intermediate phase artifacts are written to disk **only in `detailed` mode**. In `smart`/`autopilot` they are passed between phases in context and never written (see `references/interaction-mode-propagation.md#artifact-persistence`). Final deliverables are always written.
+
 **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
@@ -47,6 +59,7 @@ Before starting the planning pipeline, the orchestrator verifies that required f
 
 - `docs/plans/` — must exist for saving final plan
 - `docs/tasks/` — must exist if task generation is enabled
+- `docs/plans/.scope/`, `.research/`, `.design/` — **`detailed` mode only**, for saving the intermediate phase artifacts; do not create them in `smart`/`autopilot`
 
 **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.
 
@@ -69,7 +82,7 @@ Between phases, the orchestrator validates the output artifact before passing it
 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).
+4. **Tier/complexity coherence** (after Design) — `tier_recommended` equals `recommend_tier(complexity, risk_level)` per [plan-tier-selection.md](references/plan-tier-selection.md). Recompute it; do not trust the value blindly. A `HIGH`/`VERY_HIGH` complexity must yield `deep`.
 
 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)).
 
@@ -84,13 +97,13 @@ Each skill module is responsible for registering its own outputs:
 
 **Who updates what:**
 
-- **Generate phase:** Creates `docs/plans/index.md` if missing; appends new plan entry with timestamp and link
+- **Generate phase:** Creates `docs/plans/index.md` if missing; inserts the new plan row (or replaces the row with the same `plan-id`)
 - **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
+  - **Registration:** Generate phase inserts or replaces the row in `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`
@@ -113,6 +126,17 @@ The orchestrator and modules share these reference files:
 
 Artifact templates live in [references/templates/artifacts/](references/templates/artifacts/).
 
+## Execution Rules
+
+Follow these literally; they exist to keep runs consistent across agents.
+
+1. **Run each module's steps in order**, starting with its Step 0 verification. Do not skip, merge, or reorder steps.
+2. **Never invent values.** If a required input is missing, apply the recovery in [error-handling.md](references/error-handling.md) or ask the user; do not fill it with a plausible guess.
+3. **Compute, don't copy.** Values defined by an algorithm (`complexity`, `tier_recommended`, `tier`) must be evaluated with the real inputs. Example values in references are illustrations, never defaults.
+4. **One question at a time**, with 2–4 concrete options; build the question text from the current values.
+5. **Announce phase transitions in one line** (e.g., "Phase 3/5 Design complete: complexity HIGH, tier_recommended deep") so the user can follow progress, even in Autopilot.
+6. **Honor write rules:** hidden phase artifacts only in `detailed` mode; the final plan, index row, and (if accepted) task files always.
+
 ## Core Principles
 
 - **Deterministic Pipeline:** Phases always execute in sequence (no agent switching, no fallback paths).
@@ -122,6 +146,7 @@ Artifact templates live in [references/templates/artifacts/](references/template
 - **Separate Planning from Execution:** NEVER simulate implementation during planning.
 - **Be Concrete:** Use specific files, components, and dependencies.
 - **Stay Portable:** Use repository-relative paths only.
+- **Lean Persistence:** Phase artifacts hit disk only in `detailed` mode; `smart`/`autopilot` pass them in context to save tokens and time.
 - **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.