npm - arreio - Versions diffs - 1.0.5 → 1.2.0 - Mend

arreio 1.0.5 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "arreio",
-  "version": "1.0.5",
+  "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 CHANGED Viewed

@@ -54,7 +54,7 @@ Creates the organizational spine for Arreio artifacts:
 - `docs/plans/` — Stores generated plans and design artifacts
 - `docs/learn/` — Stores extracted learnings and insights
-- `docs/reports/` — Stores review reports and analysis
+- `docs/review/` — Stores review reports and analysis
 - `docs/tasks/` — Stores task lists and execution records
 - `docs/archives/` — Stores historical artifacts
@@ -92,15 +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 Reports Folder
-**Folder:** `docs/reports/`
-**Rationale:** Stores review reports and analysis artifacts. The `review/SKILL.md` module generates reports here.
-**Action:** Create the `docs/reports/` folder if it doesn't exist.
-### Step 8: Create Plan Skill Hidden Artifact Directories
+### Step 7: Plan Skill Hidden Artifact Directories (not created at init)
 **Folders:**
@@ -108,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 9: Create Work Skill Hidden Artifact Directories
+### Step 8: Work Skill Artifact Directories
 **Folders:**
@@ -121,26 +113,26 @@ 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 10: Create Review Skill Hidden Artifact Directories and Registry
+### Step 9: Review Skill Artifact Directories and Registry
 **Folders:**
-- `docs/plans/.review/.scope/` — Stores Review Scope phase artifacts
-- `docs/plans/.review/.prepare/` — Stores Review Prepare phase artifacts
-- `docs/plans/.review/.analyze/` — Stores Review Analyze phase artifacts
-- `docs/plans/.review/.report/` — Stores Review Report phase artifacts
+- `docs/review/.scope/` — Stores Review Scope phase artifacts
+- `docs/review/.prepare/` — Stores Review Prepare phase artifacts
+- `docs/review/.analyze/` — Stores Review Analyze phase artifacts
+- `docs/review/.report/` — Stores Review Report phase artifacts
 **File:**
-- `docs/plans/.review/index.md` — Central registry of all review reports
+- `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/plans/.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
 ---
@@ -161,20 +153,20 @@ This is the index of all review reports for the project. Reports are organized b
 _No review reports yet._
 ```
-### Step 11: Create Learn Skill Hidden Artifact Directories
+### Step 10: Learn Skill Hidden Artifact Directories (not created at init)
 **Folders:**
-- `docs/plans/.learn/.capture/` — Stores Capture phase artifacts
-- `docs/plans/.learn/.refine/` — Stores Refine phase artifacts
-- `docs/plans/.learn/.index/` — Stores Index phase artifacts
-- `docs/plans/.learn/.maintain/` — Stores Maintain phase artifacts
+- `docs/learn/.capture/` — Stores Capture phase artifacts
+- `docs/learn/.refine/` — Stores Refine phase artifacts
+- `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 12: Create End-Session Skill Hidden Artifact Directory
+### Step 11: Create End-Session Skill Hidden Artifact Directory
 **Folder:**
@@ -184,7 +176,7 @@ _No review reports yet._
 **Action:** Create the directory if it doesn't exist.
-### Step 13: Create Learn Category Folders
+### Step 12: Create Learn Category Folders
 **Folders:**
@@ -208,20 +200,15 @@ After initialization, verify:
   - `.agents/skills/learn/`
   - `.agents/skills/end-session/`
   - `.agents/skills/arreio-init/`
-- ✓ All five core folders exist: `docs/plans/`, `docs/learn/`, `docs/reports/`, `docs/tasks/`, `docs/archives/`
+- ✓ All five core folders exist: `docs/plans/`, `docs/learn/`, `docs/review/`, `docs/tasks/`, `docs/archives/`
 - ✓ `ARCHITECTURE.md` exists at project root
 - ✓ 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/plans/.review/.scope/`, `docs/plans/.review/.prepare/`, `docs/plans/.review/.analyze/`, `docs/plans/.review/.report/`
-  - `docs/plans/.review/index.md` (review reports registry)
-- ✓ Learn skill hidden artifact directories exist:
-  - `docs/plans/.learn/.capture/`, `docs/plans/.learn/.refine/`, `docs/plans/.learn/.index/`, `docs/plans/.learn/.maintain/`
+- ✓ Always-written report directories exist:
+  - `docs/plans/.work/.review/` (Work Reports), `docs/review/.report/` (Review Reports)
+  - `docs/review/index.md` (review reports registry)
+- ✓ 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:
@@ -233,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/plans/.review/` directories and `index.md` registry on first review.
-- **learn** skill creates missing `docs/plans/.learn/` directories and `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 CHANGED Viewed

@@ -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
@@ -49,7 +51,7 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 - Receives a context object from the user, a saved prompt, a document, or a combination.
 - **Three input shapes:**
   1. **Explicit** — `/learn <type> <text>`. Capture drafts an entry of the named type from the text. The canonical path for authoring a decision/pattern/gotcha/workflow.
-  2. **Candidate** — `/learn <candidate-ref>`. The ref resolves to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/plans/.review/.report/<id>.md`); Capture reads its `learnings-to-capture` list and, for each candidate, drafts the corresponding entry. The user confirms which candidates become durable entries.
+  2. **Candidate** — `/learn <candidate-ref>`. The ref resolves to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/review/.report/<id>.md`); Capture reads its `learnings-to-capture` list and, for each candidate, drafts the corresponding entry. The user confirms which candidates become durable entries.
   3. **Maintain** — `/learn maintain`. Runs only the Maintain phase (dedup / refresh / prune); bypasses Capture → Refine → Index (no new entry is authored).
 - **If no context is provided**, ask: "What would you like to capture? Provide a type and text, a candidate ref, or `maintain`."
 - **Unified key:** downstream phases key off a `learn-id` umbrella (`YYYY-MM-DD-NNN`), allocated by Capture. For Maintain-only runs, Maintain allocates its own `maintain-id` (no `learn-id` umbrella — there is no newly authored entry).
@@ -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/plans/.learn/.capture/`, `docs/plans/.learn/.refine/`, `docs/plans/.learn/.index/`, `docs/plans/.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/plans/.learn/.capture/<id>.md`   |
-| 2     | [Refine](modules/refine.md)          | [Refined entry](references/templates/artifacts/refined-entry.md)             | `docs/plans/.learn/.refine/<id>.md`    |
-| 3     | [Index](modules/index.md)            | [Index update](references/templates/artifacts/index-update.md)               | `docs/plans/.learn/.index/<id>.md`     |
-| 4     | [Maintain](modules/maintain.md) _(on demand)_ | [Maintain log](references/templates/artifacts/maintain-log.md)   | `docs/plans/.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/plans/.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 CHANGED Viewed

@@ -30,7 +30,7 @@ If the input is empty or ambiguous, ask the user one question: "What would you l
 Determine which of the two authoring shapes applies (maintain is rejected in Step 0):
 1. **Explicit** — the input carries a `<type>` (one of `decision` / `pattern` / `gotcha` / `workflow`) and `<text>` (prose, a file/commit ref, or a short description to expand).
-2. **Candidate** — the input carries a ref to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/plans/.review/.report/<id>.md`).
+2. **Candidate** — the input carries a ref to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/review/.report/<id>.md`).
 Record `input-shape: explicit | candidate`. If `<type>` is provided but is not one of the four, ask the user to pick from the four (Step 2 confirms intent either way).
@@ -48,7 +48,7 @@ Capture produces **one** Captured Entry per run (single-shape artifact). The sha
 1. Resolve the ref to the artifact file:
    - Work `review-id` → `docs/plans/.work/.review/<review-id>.md` → read its `learnings-to-capture` list.
-   - Review `report-id` → `docs/plans/.review/.report/<report-id>.md` → read its `learnings-to-capture` list.
+   - Review `report-id` → `docs/review/.report/<report-id>.md` → read its `learnings-to-capture` list.
 2. If the list is empty, inform the user (no candidates to curate) and stop — do not fabricate an entry.
 3. Present the candidate list to the user (each has a `title`, `domain`, `source` {finding-id or task-id+gate}, `summary`, `type`) and ask which to author **first** (one entry per Captured Entry). If the candidate's recorded `type` is one of the four, use it; otherwise map: `confirmed-pattern` → `pattern`, `refuted-assumption` → `gotcha`, `gotcha` → `gotcha`, `forced-decision` → `decision`. The user may override the inferred type.
 4. Record the selected candidate as `capture.source-candidate` (carried for traceability into the entry's `source` frontmatter).
@@ -70,8 +70,8 @@ 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/plans/.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`).
-3. **Assign a `capture-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-capture`, saved to `docs/plans/.learn/.capture/`). Reuse it if the user later picks **Edit & Retry**.
+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/plans/.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/plans/.learn/.capture/<capture-id>.md` (ensure `
 - 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/plans/.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 CHANGED Viewed

@@ -55,7 +55,7 @@ Update `docs/learn/index.md` per the authoritative **[index-format.md](../refere
 ### Step 4: Allocate the index-id
-Assign an `index-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-index`, saved to `docs/plans/.learn/.index/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
+Assign an `index-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-index`, saved to `docs/learn/.index/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
 ### Step 5: Generate the Index Update Artifact
@@ -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/plans/.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/plans/.learn/.index/<index-id>.md` (ensure `inte
 - 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/plans/.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 CHANGED Viewed

@@ -74,7 +74,7 @@ Rebuild `docs/learn/index.md` from the on-disk file tree — the file tree is th
 ### Step 6: Allocate the maintain-id
-Assign a `maintain-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-maintain`, saved to `docs/plans/.learn/.maintain/`). Maintain has **no `learn-id` umbrella** (it authors no new entry). Reuse the `maintain-id` if the user picks **Edit & Retry**.
+Assign a `maintain-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-maintain`, saved to `docs/learn/.maintain/`). Maintain has **no `learn-id` umbrella** (it authors no new entry). Reuse the `maintain-id` if the user picks **Edit & Retry**.
 ### Step 7: Generate the Maintain Log Artifact
@@ -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/plans/.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/plans/.learn/.maintain/<maintain-id>.md` (ensure
 - 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/plans/.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 CHANGED Viewed

@@ -65,7 +65,7 @@ Record the matches (`dup-status: exact | analog | none`, the matched `slug`/file
 ### Step 4: Allocate the refine-id
-Assign a `refine-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-refine`, saved to `docs/plans/.learn/.refine/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
+Assign a `refine-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-refine`, saved to `docs/learn/.refine/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
 ### Step 5: Generate the Refined Entry Artifact
@@ -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/plans/.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/plans/.learn/.refine/<refine-id>.md` (ensure `in
 - 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/plans/.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 CHANGED Viewed

@@ -12,12 +12,12 @@ 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/plans/.learn/.capture/<id>.md`   |
-| Refine   | `YYYY-MM-DD-NNN-refine`             | `docs/plans/.learn/.refine/<id>.md`    |
-| Index    | `YYYY-MM-DD-NNN-index`              | `docs/plans/.learn/.index/<id>.md`     |
-| Maintain | `YYYY-MM-DD-NNN-maintain`           | `docs/plans/.learn/.maintain/<id>.md`  |
+| Capture  | `YYYY-MM-DD-NNN-capture`            | `docs/learn/.capture/<id>.md`   |
+| Refine   | `YYYY-MM-DD-NNN-refine`             | `docs/learn/.refine/<id>.md`    |
+| Index    | `YYYY-MM-DD-NNN-index`              | `docs/learn/.index/<id>.md`     |
+| Maintain | `YYYY-MM-DD-NNN-maintain`           | `docs/learn/.maintain/<id>.md`  |
 `learn-id` (see below) is the umbrella shared across Capture → Refine → Index. **Maintain has no `learn-id`** — it authors no new entry; it allocates only a standalone `maintain-id`.
@@ -27,7 +27,7 @@ Allocated **only in Capture** Step 4:
 ```
 1. Get the current date in UTC
-2. List existing files under docs/plans/.learn/.capture/ matching YYYY-MM-DD-NNN-capture.md for that date
+2. List existing files under docs/learn/.capture/ matching YYYY-MM-DD-NNN-capture.md for that date
 3. NNN = (highest existing NNN for that date), zero-padded to 3 digits
    - if none exist for that date, start at 001
 4. learn-id = "<date>-<NNN>"  (the same NNN as the capture-id being allocated)
@@ -42,7 +42,7 @@ Allocated **only in Maintain** Step 6:
 ```
 1. Get the current date in UTC
-2. List existing files under docs/plans/.learn/.maintain/ matching YYYY-MM-DD-NNN-maintain.md for that date
+2. List existing files under docs/learn/.maintain/ matching YYYY-MM-DD-NNN-maintain.md for that date
 3. NNN = (count + 1), zero-padded to 3 digits
 4. maintain-id = "<date>-<NNN>-maintain"
 ```
@@ -69,15 +69,17 @@ 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)
 ```
 1. Get the current date in UTC (e.g., 2026-08-08)
 2. List existing files for today in the phase's save directory:
-   - capture  -> docs/plans/.learn/.capture/  matching YYYY-MM-DD-*-capture.md
-   - refine   -> docs/plans/.learn/.refine/   matching YYYY-MM-DD-*-refine.md
-   - index    -> docs/plans/.learn/.index/    matching YYYY-MM-DD-*-index.md
-   - maintain -> docs/plans/.learn/.maintain/ matching YYYY-MM-DD-*-maintain.md
+   - capture  -> docs/learn/.capture/  matching YYYY-MM-DD-*-capture.md
+   - refine   -> docs/learn/.refine/   matching YYYY-MM-DD-*-refine.md
+   - index    -> docs/learn/.index/    matching YYYY-MM-DD-*-index.md
+   - maintain -> docs/learn/.maintain/ matching YYYY-MM-DD-*-maintain.md
 3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
 4. id = "<date>-<NNN>-<phase>"
 ```
@@ -108,7 +110,7 @@ The legacy `docs/learnings/` store uses filenames, not slugs, as the key. The mi
 ## Notes
-- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan`, `/work`, and `/review`; the Learn skill's counters are independent from those skills (separate save directories under `docs/plans/.learn/`).
+- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan`, `/work`, and `/review`; the Learn skill's counters are independent from those skills (separate save directories under `docs/learn/`).
 - `learn-id` carries through Capture → Refine → Index; Maintain uses the standalone `maintain-id` only. Cross-phase chaining is `capture-id → refine-id → index-id`, all sharing one `learn-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
 - The `slug` is a **separate** key from the phase ids — it identifies the durable knowledge entry across re-authors, not the pipeline run. A single `slug` may be authored by many `learn-id` runs over time (each upsert overwrites); the `slug` is stable, the `learn-id` is per-run.
 - Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.

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

@@ -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 CHANGED Viewed

@@ -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/plans/.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 CHANGED Viewed

@@ -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/plans/.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