arreio 1.1.0 → 1.2.1

package/ARCHITECTURE.md

@@ -0,0 +1,220 @@
+# Architecture Documentation
+
+A bird's-eye view of the Arreio system design, boundaries, and codebase layout.
+
+---
+
+## 1. System Overview
+
+- **Domain Problem**: AI-driven coding workflows are unpredictable and lack quality guardrails; Arreio transforms them into a deterministic, test-first software delivery pipeline.
+- **Target Audience**: Developers and teams using agentic coding tools who want structured, reviewable, and repeatable development cycles.
+- **Core Goal**: Provide an uncompromised, resilient harness for plan → work → review → learn execution.
+
+## 2. Core Constraints (The "Don'ts")
+
+- **No Ambiguous Plans**: Every plan must decompose into tasks with exactly one Acceptance Criterion each.
+- **No Implementation Without Tests**: Tasks follow strict Red → Green → Refactor TDD discipline.
+- **No Direct Cross-Skill Calls**: Skills are self-contained; orchestration happens through the agent harness, not skill-to-skill invocation.
+- **No Undocumented Decisions**: Learnings, reviews, and plan deviations must be captured in persistent docs.
+- **No Deep Inheritance in Skill Definitions**: Favor composition of micro-modules over monolithic skill files.
+
+## 3. Technology Stack
+
+| Layer             | Technology         | Primary Responsibility                                             |
+| :---------------- | :----------------- | :----------------------------------------------------------------- |
+| **Orchestration** | Agent Harness (pi) | Skill invocation, context management, user interaction             |
+| **Skills**        | Markdown + YAML    | Self-describing workflow definitions and constraints               |
+| **Modules**       | Markdown           | Reusable phase implementations within each skill                   |
+| **Storage**       | Git (docs/)        | Persistent, versioned artifacts (plans, tasks, learnings, reports) |
+| **Templates**     | Markdown           | Reference artifacts for consistent output formatting               |
+
+## 4. Architectural Pattern & Data Flow
+
+The system follows a **Pipeline Architecture**. Work flows unidirectionally through four core phases, each composed of deterministic micro-skills.
+
+```mermaid
+graph LR
+    A[User Input] --> B[Plan]
+    B --> C[Work]
+    C --> D["Work Review<br/>(Phase 4)"]
+    D -->|if regressions<br/>or scope-creep| E["for-review<br/>Status"]
+    E --> F[Standalone Review]
+    D -->|if clean| G["completed<br/>Status"]
+    F -->|approved| G
+    F -->|changes-requested| H["blocked<br/>Status"]
+    G --> I[Learn]
+    H --> I
+    I --> J[Archived Artifacts]
+```
+
+**Key Sequence:**
+
+1. User runs `/work <plan-id>` → executes tasks Red → Green → Refactor
+2. Work Review Phase 4 gates output:
+   - Binary gate: if `regression-check: regressions-found` **OR** `scope-creep` findings exist → tasks enter `for-review` status
+   - Else → tasks move to `completed` status
+3. If `for-review` tasks exist, user runs `/review <work-id>`:
+   - Standalone Review finds `status: for-review` tasks
+   - Runs comprehensive audit (quality/security/tests/docs/integration)
+   - Approval verdict updates task frontmatter:
+     - `approved` → `status: completed`
+     - `changes-requested` → `status: blocked` (with reason)
+4. Learnings captured via `/learn` (orthogonal to approval gates; optional post-Review)
+
+### Phase Pipelines
+
+> **Artifact persistence:** intermediate phase artifacts (`.scope/`, `.research/`, `.design/`, `.triage/`, `.prepare/`, `.execute/`, `.analyze/`, `.capture/`, `.refine/`, `.index/`, `.maintain/`) are written only in `detailed` interaction mode. `smart`/`autopilot` pass them in context. Final deliverables (plans, tasks, Work/Review Reports, learn entries) are always written.
+
+| Phase                 | Pipeline                                                   | Output Artifacts                                                                                     |
+| --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Plan**              | Scope → Research → Design → Generate → Tasks               | `docs/plans/<plan-id>.md`, `docs/tasks/<plan-id>/`                                                   |
+| **Work**              | Triage → Prepare → Execute → Review (with for-review gate) | Updated task files, code changes; tasks in `completed`, `for-review`, `blocked`, or `skipped` status |
+| **Standalone Review** | Scope → Prepare → Analyze → Report                         | `docs/review/.report/<review-id>.md`; task status updates (task-in-review input)             |
+| **Learn**             | Capture → Refine → Index (+ Maintain on-demand)¹           | `docs/learn/<category>/<learning>.md`                                                                |
+
+¹ **Learn phases:** Capture → Refine → Index for normal authoring. Maintain (Phase 4) runs on-demand for dedup, refresh, prune, and legacy migration.
+
+## 5. Codebase Map
+
+```text
+├── skills/                  # Core skill definitions
+│   ├── arreio-init/         # Project initialization skill
+│   │   ├── SKILL.md         # Skill contract and workflow
+│   │   └── references/      # Templates (architecture, indexes)
+│   ├── plan/                # Plan orchestration skill
+│   │   ├── SKILL.md
+│   │   ├── modules/         # Phase modules (scope, research, design, generate, tasks)
+│   │   └── references/      # Templates and artifacts
+│   ├── work/                # Work execution skill
+│   │   ├── SKILL.md
+│   │   ├── modules/         # Phase modules (triage, prepare, execute, review)
+│   │   └── references/
+│   ├── review/              # Code review skill
+│   │   ├── SKILL.md
+│   │   ├── modules/
+│   │   └── references/
+│   └── learn/               # Learning extraction skill
+│       ├── SKILL.md
+│       ├── modules/
+│       └── references/
+├── docs/                    # Persistent artifact storage
+│   ├── plans/               # Plan artifacts
+│   │   └── index.md         # Registry of all plans
+│   ├── tasks/               # Task artifacts (per-plan subdirectories)
+│   ├── learn/               # Extracted learnings
+│   │   └── index.md         # Central knowledge base
+│   ├── review/              # Review reports and phase artifacts
+│   └── archives/            # Historical artifacts
+├── ARCHITECTURE.md          # System design and architecture documentation
+└── README.md                # Project overview
+```
+
+### Entry Points
+
+- **Initialization**: `/arreio-init` — Bootstraps folder structure and indexes for a new project.
+- **Planning**: `/plan <task description>` — Runs the full planning pipeline.
+- **Execution**: `/work <plan-id>` — Executes task list for a plan.
+- **Review**: `/review <input>` — Analyzes code changes.
+- **Learning**: `/learn <input>` — Extracts and catalogs patterns.
+- **Session End**: `/end-session` — Preserves context with a documented commit.
+
+## 6. Component Design Philosophy
+
+- **Thin Orchestrators**: Skill files (`SKILL.md`) define contracts and pipelines; they delegate all work to discrete modules.
+- **Deterministic Phases**: Each module in a pipeline has a single, well-defined input/output contract with no fallback paths.
+- **Self-Describing Artifacts**: Every generated document (plan, task, report, learning) carries front-matter metadata for discoverability.
+- **Immutable References**: Templates and reference artifacts are versioned and never mutated in-place; downstream skills copy and fill them.
+
+## 7. Operational Guidelines & Verification
+
+- **Skill Validation**: Before modifying any `SKILL.md`, confirm its downstream modules and references still align with the contract.
+- **Artifact Consistency**: All docs under `docs/` must use the metadata schema defined in `references/` templates.
+- **Git Hygiene**: Run `/end-session` before closing a session to ensure state, decisions, and next steps are committed.
+- **Agent Attribution**: Every session-end commit carries an `[AGENT: ...]` trailer on its last line — a project-wide commit standard. The trailer names the agent that made the session's file changes (verified against the session's change history; fallback: the current agent). Session-end artifacts under `docs/plans/.end-session/` record the same attribution for traceability.
+- **Index Maintenance**: After creating any plan, task, or learning, update the corresponding `index.md` so the knowledge graph remains traversable.
+
+## 8. Design Decisions — Work Review & Standalone Review Integration (2026-08-12)
+
+### Problem
+
+Work executes tasks Red → Green → Refactor, then updates task status to `completed`. Standalone Review audits arbitrary code changes with a comprehensive quality/security/tests/docs/integration rubric. These are complementary but were architecturally adjacent (potential for duplication of scope-creep logic, inconsistent findings).
+
+### Solution: Sequential Approval Gates via `for-review` Status
+
+**Goals:**
+
+1. Eliminate redundancy: Work Review is a lightweight pre-check; Standalone Review is the definitive approval gate
+2. Make approval explicit: tasks cannot move to `completed` until Standalone Review approves
+3. Decouple learnings from approval: the Learn skill is the single authoritative source for durable knowledge capture (orthogonal to approval gates)
+
+**Implementation:**
+
+1. **Work Review Phase 4** (lightweight pre-check):
+   - Simplify, consolidate, run regression check (binary: any failure = gate blocks), detect scope-creep (any finding = gate blocks)
+   - If `regression-check: regressions-found` **OR** `scope-creep` findings exist → tasks enter `status: for-review` (not `completed`)
+   - Else → tasks move to `status: completed`
+   - Surface learnings-to-capture for later `/learn` invocation (orthogonal to approval)
+
+2. **Standalone Review** (definitive audit):
+   - New input shape: **task-in-review** — accepts `/review <work-id>`, discovers `status: for-review` tasks
+   - Runs full 4-phase audit (Scope → Prepare → Analyze → Report)
+   - Report phase (new behavior): updates task file frontmatter based on approval verdict:
+     - If `approved` → `status: completed`
+     - If `changes-requested` → `status: blocked` (with reason)
+   - Idempotent on `report-id`
+
+3. **Learn Skill** (durable knowledge):
+   - Receives learnings-to-capture from Work Report's Phase 5
+   - User runs `/learn <work-id>` (or `/learn <candidate-ref>`) to persist learnings
+   - Learn writes to `docs/learn/` (single source of truth for durable knowledge)
+   - Orthogonal to approval gates — can run before/after Review
+
+**Workflow:**
+
+```
+User runs /work <plan-id>
+  ↓
+Execute tasks (Red → Green → Refactor)
+  ↓
+Work Review Phase 4:
+  - Simplify & consolidate
+  - Regression check (any failure = gate)
+  - Scope-creep detection (any finding = gate)
+  - Learnings summary (for later /learn)
+  ↓
+If regression/scope-creep:
+  - Tasks → status: for-review
+  ↓
+User runs /review <work-id>  (if for-review tasks exist)
+  ↓
+Standalone Review (full audit):
+  - Scope → Prepare → Analyze → Report
+  - Report updates task status:
+    - approved → status: completed
+    - changes-requested → status: blocked
+  ↓
+User runs /learn <work-id>  (optional; orthogonal to approval)
+  ↓
+Learn persists learnings to docs/learn/
+```
+
+**Rationale:**
+
+- **Sequential, not parallel**: Decouples execution quality (Work Review) from approval authority (Standalone Review). No ambiguity about which skill approves.
+- **Binary gates**: Work Review's gate is simple and fast (helps catch regressions early). Detailed severity assignment is Standalone Review's job.
+- **Learnings orthogonal to approval**: Separates knowledge capture from gating, avoiding coupling. Learn skill remains the single source of truth.
+- **Task status as API**: Task frontmatter `status:` field becomes the shared contract between Work and Review — no folder moves needed, paths stay stable.
+
+**Trade-offs:**
+
+- **User must run two skills**: `/work` then `/review` (if regressions/scope-creep detected). Adds a step. Mitigated by clear workflow documentation and optional automation via agent harness.
+- **Two approval concepts**: Work's gate (regression/scope-creep) + Review's approval status (approved/changes-requested/rejected) could be confusing. Mitigated by renaming Work's gate outcome to avoid collision (using `task-status-target` internally; user sees `for-review` status).
+
+### Status
+
+- ✅ Phase 1 (define `for-review` status): Done (design)
+- ✅ Phase 2 (update Work Review module): Done
+- ✅ Phase 3 (update Review SKILL + task-in-review input): Done
+- ✅ Phase 4 (update task index model, artifacts): In progress (work-report schema updated)
+- ⏳ Phase 5 (error handling + quality gates): Pending implementation
+- ⏳ Phase 6 (documentation + swimlane diagram): In progress

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to Arreio are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> Versions prior to 1.0.5 predate this changelog. See `git log` for historical commits.
+
+## [Unreleased]
+
+## [1.2.1] - 2026-10-09
+
+### Changed
+
+- **npm discoverability.** Rewrote the package description, expanded keywords (agent skills, Claude Code, Codex, Copilot, Cursor, TDD, slash commands, etc.), made `author` an object with a profile URL, and now publish `CHANGELOG.md` and `ARCHITECTURE.md`.
+
+## [1.2.0] - 2026-10-01
+
+### Added
+
+- **`/plan --deep` flag.** Forces the Deep plan tier in any interaction mode (including Autopilot), skipping the tier question. `tier_recommended` still records the algorithm's result so the override is auditable. The Design phase also produces ≥ 2 alternatives and rollout/integration drafts when the flag is set.
+
+### Fixed
+
+- **Work/Review/Learn reliability pass.** Each skill gets an "Execution Rules" block (ordered steps, no invented values, compute-don't-copy, one question at a time, phase-transition announcements, write rules). Work's execution-mode selection now states first-match-wins evaluation, treats `serial` as a fallback only, and builds its Detailed-mode question (with an `Auto` option) from computed values. `--deep` stays Plan-only: the other skills have no plan tier.
+- **Plan tier no longer collapses to Standard.** The tier prompt hardcoded "Auto … (result: Standard)" and its example contradicted the algorithm (HIGH complexity → Deep). The prompt is now built from computed values, `Auto` resolves to `tier_recommended`, and Design computes `tier_recommended` with the same `recommend_tier(complexity, risk_level)` function Generate re-checks.
+- **Complexity scoring consistency.** Risk now maps to a fixed score (LOW 0, MEDIUM 1, HIGH 2, CRITICAL 3); the missing-risk default is MEDIUM = 1 (was documented as 2); each dimension requires cited evidence.
+
+### Changed
+
+- **`docs/` is no longer tracked in this repository.** It is generated by the skills at runtime and is now in `.gitignore`.
+- **Intermediate phase artifacts are now written only in `detailed` mode.** In `smart` and `autopilot` mode, the plan, work, review, and learn pipelines pass phase artifacts in context instead of writing hidden files (`.scope/`, `.research/`, `.design/`, `.triage/`, `.prepare/`, `.execute/`, `.analyze/`, `.capture/`, `.refine/`, `.index/`, `.maintain/`). Final deliverables (plans, tasks, Work Reports, Review Reports, learn entries) are still always written. `arreio-init` no longer pre-creates the intermediate directories.
+
+## [1.0.5] - 2026-09-02
+
+### Fixed
+
+- **Postinstall script targeted wrong directory.** When Arreio was installed as a dependency, the `postinstall` script used `process.cwd()`, which inside `node_modules/arreio/` points to the package directory itself — not the consuming project. Skills were being copied to `node_modules/arreio/.agents/skills/` instead of `<project>/.agents/skills/`. Switched the destination base to `process.env.INIT_CWD || process.cwd()`, which npm sets to the original invocation directory during lifecycle scripts.
+
+### Documentation
+
+- **README: clarified npm 10+ install-script behavior.** Replaced the misleading "informational advisory" note with actionable guidance. npm 10+ blocks lifecycle scripts by default; users must run `npm install-scripts approve arreio` to run the postinstall, or invoke `/arreio-init` in their AI coding agent to install skills manually.

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,9 +1,12 @@
 {
   "name": "arreio",
-  "version": "1.1.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.",
+  "version": "1.2.1",
+  "description": "Agent skills for AI coding agents (Claude Code, Codex, Copilot, Cursor): a guardrailed Plan → Work → Review → Learn workflow with /plan, /work, /review and /learn slash commands for predictable, test-first software delivery.",
   "license": "MIT",
-  "author": "Wicttor",
+  "author": {
+    "name": "Wicttor",
+    "url": "https://github.com/wicttor"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/wicttor/arreio.git"
@@ -14,21 +17,41 @@
   "homepage": "https://github.com/wicttor/arreio#readme",
   "keywords": [
     "arreio",
+    "agent-skills",
+    "ai-agents",
+    "ai-coding",
+    "ai-coding-agent",
+    "ai-assisted-development",
     "agentic-workflows",
-    "ai-driven-development",
-    "software-delivery",
+    "agentic-coding",
+    "claude-code",
+    "claude",
+    "codex",
+    "github-copilot",
+    "cursor",
+    "copilot",
+    "llm",
+    "skills",
+    "slash-commands",
+    "prompt-engineering",
     "plan-work-review-learn",
-    "guardrailed-execution",
-    "quality-assurance",
+    "guardrails",
+    "tdd",
+    "test-driven-development",
     "code-review",
-    "documentation",
-    "workflow-orchestration"
+    "task-planning",
+    "developer-workflow",
+    "workflow-orchestration",
+    "software-delivery",
+    "project-documentation"
   ],
   "main": "README.md",
   "files": [
     "skills/",
     "scripts/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md"
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js"

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.