arreio 1.0.0-dev.1 → 1.0.0

package/README.md

@@ -17,7 +17,19 @@ Install Arreio as a dependency to enable all skills in your workspace:
 npm install arreio
 ```
 
-The post-install script will automatically copy all Arreio skills to your `.agents/skills` directory. This makes all four core skills available in your AI development environment:
+Then initialize your project to set up Arreio workflows:
+
+```
+/arreio-init
+```
+
+Run this command in VS Code Copilot Chat to:
+
+1. Copy all Arreio skills to your `~/.agents/skills/` directory
+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:
 
 - **arreio-init** - Initialize projects to follow the Arreio workflow
 - **plan** - Structure and decompose work into executable tasks
@@ -78,4 +90,4 @@ Initialize a new project, enabling the project to follow the four phases of the
 
 #### /end-session
 
-Preserve session context with a well-documented commit capturing state, decisions, and next steps.
+Preserve session context with a well-documented commit capturing state, decisions, and next steps — saved as a traceable session artifact (with agent attribution) in `docs/plans/.end-session/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arreio",
-  "version": "1.0.0-dev.1",
+  "version": "1.0.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",
@@ -27,12 +27,8 @@
   "main": "README.md",
   "files": [
     "skills/",
-    "scripts/",
     "README.md"
   ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js"
-  },
   "engines": {
     "node": ">=14.0.0"
   },

package/skills/arreio-init/SKILL.md

@@ -33,7 +33,20 @@ After initialization, the following modules can operate:
 
 ## Workflow
 
-### Step 1: Create Core Folder Structure
+The initialization workflow runs in two phases:
+
+1. **Phase 0: Install Skills** — Copy Arreio skills to `~/.agents/skills/` for VS Code Copilot Chat discovery
+2. **Phase 1: Initialize Project Structure** — Create folders, indexes, and architectural documentation
+
+### Step 1: Install Skills
+
+Install Arreio skills to the user's `.agents/skills` directory. See [modules/install.md](modules/install.md) for detailed instructions.
+
+**Why:** Skills must be copied from the installed npm package to the user's home directory so they are discoverable by VS Code Copilot Chat. This step must run first, before project structure is created.
+
+**Action:** Execute the [install.md](modules/install.md) phase to copy all skills from `node_modules/arreio/skills/` to `~/.agents/skills/`.
+
+### Step 2: Create Core Folder Structure
 
 Creates the organizational spine for Arreio artifacts:
 
@@ -45,7 +58,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Why:** Downstream skills assume these folders exist and will create files within them.
 
-### Step 2: Initialize Root Architecture Document
+### Step 3: Initialize Root Architecture Document
 
 **File:** `ARCHITECTURE.md` (project root)
 
@@ -53,7 +66,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** If `ARCHITECTURE.md` doesn't exist, create it using the [Architecture Template](references/architecture-template.md).
 
-### Step 3: Initialize Plans Index
+### Step 4: Initialize Plans Index
 
 **File:** `docs/plans/index.md`
 
@@ -61,7 +74,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** If `docs/plans/index.md` doesn't exist, create it using the [Plan Index Template](references/plan-index-template.md).
 
-### Step 4: Create Tasks Folder
+### Step 5: Create Tasks Folder
 
 **Folder:** `docs/tasks/`
 
@@ -69,7 +82,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** Create the `docs/tasks/` folder if it doesn't exist.
 
-### Step 5: Initialize Learning Index
+### Step 6: Initialize Learning Index
 
 **File:** `docs/learn/index.md`
 
@@ -77,7 +90,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 6: Create Reports Folder
+### Step 7: Create Reports Folder
 
 **Folder:** `docs/reports/`
 
@@ -85,7 +98,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** Create the `docs/reports/` folder if it doesn't exist.
 
-### Step 7: Create Plan Skill Hidden Artifact Directories
+### Step 8: Create Plan Skill Hidden Artifact Directories
 
 **Folders:**
 
@@ -97,7 +110,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** Create all three directories if they don't exist.
 
-### Step 8: Create Work Skill Hidden Artifact Directories
+### Step 9: Create Work Skill Hidden Artifact Directories
 
 **Folders:**
 
@@ -110,7 +123,7 @@ Creates the organizational spine for Arreio artifacts:
 
 **Action:** Create all four directories if they don't exist.
 
-### Step 9: Create Review Skill Hidden Artifact Directories and Registry
+### Step 10: Create Review Skill Hidden Artifact Directories and Registry
 
 **Folders:**
 
@@ -146,7 +159,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 11: Create Learn Skill Hidden Artifact Directories
 
 **Folders:**
 
@@ -159,7 +172,17 @@ _No review reports yet._
 
 **Action:** Create all four directories if they don't exist.
 
-### Step 11: Create Learn Category Folders
+### Step 12: Create End-Session Skill Hidden Artifact Directory
+
+**Folder:**
+
+- `docs/plans/.end-session/` — Stores session-end artifacts
+
+**Rationale:** The `end-session/SKILL.md` skill saves a session artifact here for every session-end commit, providing a traceable record of what was done, why, and by which agent.
+
+**Action:** Create the directory if it doesn't exist.
+
+### Step 13: Create Learn Category Folders
 
 **Folders:**
 
@@ -176,6 +199,13 @@ _No review reports yet._
 
 After initialization, verify:
 
+- ✓ All Arreio skills are installed to `~/.agents/skills/`:
+  - `~/.agents/skills/plan/`
+  - `~/.agents/skills/work/`
+  - `~/.agents/skills/review/`
+  - `~/.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/`
 - ✓ `ARCHITECTURE.md` exists at project root
 - ✓ Root-level index files exist:
@@ -190,6 +220,8 @@ After initialization, verify:
   - `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/`
+- ✓ End-session skill hidden artifact directory exists:
+  - `docs/plans/.end-session/`
 - ✓ Learn category folders exist:
   - `docs/learn/decision/`, `docs/learn/pattern/`, `docs/learn/gotcha/`, `docs/learn/workflow/`
 - ✓ Per-plan task indexes created on-demand by plan skill: `docs/tasks/<plan-id>/index.md` (created when Tasks phase runs)
@@ -203,6 +235,7 @@ Downstream skills (plan, learn, work, review) automatically create missing folde
 - **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.
+- **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/arreio-init/modules/install.md

@@ -0,0 +1,136 @@
+---
+title: Install Skills
+description: Install Arreio skills to the user's .agents/skills directory, making them available in VS Code Copilot Chat.
+type: module
+version: 1.0
+timestamp: "2026-09-01"
+---
+
+# Phase 0 - Install Skills
+
+**Purpose:** Copy Arreio skills from the installed npm package to the user's `~/.agents/skills/` directory, making them available for discovery and invocation in VS Code Copilot Chat. This ensures all Arreio workflows (plan, work, review, learn, end-session) are accessible after initialization.
+
+## Workflow
+
+This is the Phase 0 pipeline for the Arreio Init Skill. It orchestrates the following steps before creating project structure.
+
+### Step 1: Verify Installation Context
+
+Verify that the prerequisites are met:
+
+1. Arreio is installed as an npm package in the current project (`node_modules/arreio/` exists).
+2. The skills directory exists in the package: `node_modules/arreio/skills/` contains subdirectories for each skill.
+3. The user's home directory is accessible (required to create `~/.agents/skills/`).
+
+If any verification fails:
+
+- **Missing package:** Suggest running `npm install arreio` first.
+- **Missing skills:** Report a package integrity error (the skills/ directory is missing from the installed package).
+- **No home access:** Report an environment error (unable to determine home directory).
+
+### Step 2: Create Target Directory
+
+Create the destination directory hierarchy:
+
+1. If `~/.agents/` does not exist, create it.
+2. If `~/.agents/skills/` does not exist, create it.
+3. Log: `✓ Created ~/.agents/skills/`
+
+### Step 3: Copy Skills from Package
+
+Copy each skill directory from `node_modules/arreio/skills/` to `~/.agents/skills/`:
+
+**Skills to copy:**
+
+- `plan` — Planning and decomposition
+- `work` — Task execution with guardrails
+- `review` — Code review and analysis
+- `learn` — Knowledge capture and indexing
+- `end-session` — Session documentation
+- `arreio-init` — Workspace initialization (this skill itself, for re-runs)
+
+**Copy algorithm:**
+
+For each skill:
+
+1. Read the source directory: `node_modules/arreio/skills/<skill-name>/`
+2. Copy recursively to destination: `~/.agents/skills/<skill-name>/`
+3. Verify the destination directory was created and contains the expected files (`SKILL.md`, `modules/`, `references/`).
+4. Log: `✓ Copied <skill-name>`
+
+If any copy operation fails:
+
+- Log the error and the source/destination paths.
+- Ask the user to manually verify the source exists and the destination is writable.
+- Do not proceed to the next phase.
+
+### Step 4: Verify Installation Success
+
+After all skills are copied, verify that the expected skill files are present:
+
+For each skill, check:
+
+- `~/.agents/skills/<skill-name>/SKILL.md` exists
+- Directory structure is intact (modules/, references/ subdirs if present)
+
+If verification passes, log:
+
+```
+✓ Arreio skills installed successfully
+  - plan
+  - work
+  - review
+  - learn
+  - end-session
+  - arreio-init
+
+Skills are now available in VS Code Copilot Chat.
+```
+
+If verification fails for any skill, report which skills failed and suggest manual verification.
+
+### Step 5: Log Installation Summary
+
+Provide the user with confirmation and next steps:
+
+```
+Installation complete. Arreio skills are now available:
+
+Next step: Project structure will be initialized in Step 1 of arreio-init.
+
+You can now use:
+  /plan    — Create implementation plans
+  /work    — Execute tasks with guardrails
+  /review  — Conduct code reviews
+  /learn   — Capture and organize knowledge
+```
+
+## Success Criteria
+
+After this phase completes:
+
+- ✓ `~/.agents/skills/` directory exists
+- ✓ All six skills are copied to `~/.agents/skills/`:
+  - `~/.agents/skills/plan/`
+  - `~/.agents/skills/work/`
+  - `~/.agents/skills/review/`
+  - `~/.agents/skills/learn/`
+  - `~/.agents/skills/end-session/`
+  - `~/.agents/skills/arreio-init/`
+- ✓ Each skill directory contains `SKILL.md` and expected subdirectories
+- ✓ Skills are ready for discovery by VS Code Copilot Chat
+
+## Error Handling
+
+Refer to [error-handling.md](../references/error-handling.md) for category classification and resolution strategies. Common errors:
+
+- **Category 1 (Missing context):** Arreio package not installed; suggest `npm install arreio`.
+- **Category 2 (Routing error):** Skills directory missing from package; report package integrity issue.
+- **Category 3 (Environment issue):** Cannot write to `~/.agents/`; insufficient permissions or home dir unavailable.
+
+## Notes
+
+- This phase runs **before** project structure initialization (Phase 1 → Create Core Folders).
+- Skills are copied to the user's home directory (`~/.agents/`), not the project directory. This allows skills to be reused across all projects once installed.
+- The copy is non-destructive; if skills already exist in `~/.agents/skills/`, they are overwritten with the latest version from the installed package. This supports package updates.
+- This phase is idempotent; running it multiple times produces the same result.

package/skills/end-session/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: end-session
+description: "Create a single clear commit at session end capturing state. Saves a session artifact to docs/plans/.end-session/ with agent attribution from file changes."
+argument-hint: "[Optional: reason for ending session]"
+disable-model-invocation: true
+version: 2.0.0
+timestamp: "2026-09-01"
+---
+
+# End Session
+
+Create a well-documented commit when a work session ends, with a persistent session artifact for continuity.
+
+## Usage
+
+```text
+/end-session                           # End current session
+/end-session "switching to bugfix"     # End with context note
+```
+
+## Workflow
+
+### 1. Pre-flight: Verify Changes
+
+1. Check working tree for modifications
+2. If no changes, inform the user and exit
+3. Show list of changed files; ask if all should be included
+4. Create `docs/plans/.end-session/` if missing (self-healing)
+
+**Critical failure:** Working tree is unreadable or inaccessible → exit with error.
+
+### 2. Confirm & Prepare
+
+1. Ask user: "Ready to end this session?" (yes/no)
+2. If no, list incomplete work and exit
+3. Draft commit message:
+   - Subject: imperative mood, ≤50 chars, no period (e.g., "Add feature" not "Added")
+   - Body: explain **why**, not what; include skills used (e.g., "Used: -plan, -work")
+   - Add `[AGENT: {AGENT_NAME}]` as last line (mandatory)
+4. Show message for user approval; allow edits
+
+**Critical failure:** User declines or message is empty after body prompt → exit without committing.
+
+### 3. Create & Record
+
+1. Stage approved files and create commit
+2. Capture commit SHA
+3. Allocate session ID: `YYYY-MM-DD-NNN` (date + sequential counter)
+4. Write session artifact to `docs/plans/.end-session/<session-id>.md`
+5. Register in `docs/plans/index.md` under `## Session Ends` (create section if missing)
+6. Report: commit SHA + artifact path + suggest `/learn maintain` if learnings were touched
+
+**Critical failure:** Commit creation fails or artifact write fails → surface error with SHA (if captured) so user can recover manually.
+
+## Session Artifact Format
+
+```markdown
+---
+type: session
+session-id: 2026-09-01-001
+timestamp: "2026-09-01T14:30:00"
+commit-sha: "<short sha>"
+agent: "<agent name>"
+files-changed: <count>
+status: complete
+---
+
+# Session End: <commit subject>
+
+## Reason
+
+<context note or "session complete">
+
+## Changed Files
+
+- <path> (added | modified | deleted)
+
+## Commit Message
+
+<verbatim subject + body>
+
+## Next Steps
+
+<open todos or "none">
+```
+
+## Requirements
+
+- **Changes required**: session ends only if there are staged changes
+- **User approval**: commit message always shown before committing
+- **No push**: changes remain local; user pushes manually
+- **Attribution**: `[AGENT: ...]` trailer derived from session file changes (current agent if mixed)
+- **Artifact**: saved to `docs/plans/.end-session/` and indexed in `docs/plans/index.md`
+
+## References
+
+| Reference                                         | Purpose                                   |
+| ------------------------------------------------- | ----------------------------------------- |
+| [error-handling.md](references/error-handling.md) | Critical failure modes and recovery steps |

package/skills/end-session/references/error-handling.md

@@ -0,0 +1,80 @@
+---
+title: Error Handling & Recovery
+description: Critical failure modes and recovery steps for end-session
+type: reference
+version: 2.0
+timestamp: "2026-09-01"
+---
+
+# Error Handling & Recovery
+
+Minimal reference for critical failures only. Surface errors explicitly; never silently skip or fabricate data.
+
+## Critical Failures (Exit Immediately)
+
+| Scenario                                                        | Recovery Action                                            |
+| --------------------------------------------------------------- | ---------------------------------------------------------- |
+| Working tree is unreadable (repo access issue)                  | Log error; ask user to verify repository is accessible     |
+| Working tree is clean (no changes)                              | Inform user, exit gracefully (nothing to commit)           |
+| User declines session completion (Phase 2)                      | List incomplete work, exit without committing              |
+| Commit message is empty or invalid                              | Re-prompt user; never commit with placeholder              |
+| Commit creation fails (identity not configured, hook rejection) | Log failure reason; do not fabricate SHA; suggest fix      |
+| File write fails (artifact or index permission denied)          | Log error; provide commit SHA so user can recover manually |
+
+## Self-Healing (Non-Blocking)
+
+- **Missing `docs/plans/.end-session/`** → create it automatically
+- **Missing `## Session Ends` in `docs/plans/index.md`** → create section before appending
+- **Missing `docs/plans/index.md` entirely** → create minimal index with section
+
+## User Decisions Always Required
+
+- Confirm session completion (Phase 2)
+- Approve commit message before committing
+- Approve staging files before commit creation
+
+4. If terminate = Yes: stop and inform the user with:
+   - Error category and trigger
+   - Recovery action attempted
+   - Reason for termination
+5. If terminate = No: after recovery, continue to the next step of the phase
+
+````
+
+## Retry Limits
+
+- **Maximum retries per error:** 1
+- **Maximum total retries per phase:** 2
+- After exhausting retries, terminate with a clear error explaining what failed and suggesting the user resolve the underlying issue and re-run `/end-session`.
+
+## Error Reporting Format
+
+When reporting an error to the user, use this format:
+
+```yaml
+error:
+  phase: pre-flight | confirm-completion | prepare-commit | create-commit | save-artifact | post-commit
+  step: 0 | 1 | 2 | ...
+  category: 1 | 2 | 3 | 4 | 5 | 6
+  trigger: "[specific trigger description]"
+  recovery_attempted: "[action taken]"
+  outcome: recovered | terminated
+  suggestion: "[next step for the user]"
+````
+
+## Cross-Phase Consistency Checks
+
+| Check                                                                      | Action on Failure                                        |
+| -------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `interactionMode` is identical across all phases                           | Log warning; use the earliest non-default value          |
+| Change list in Phase 3/4 matches the Pre-flight list (no silent additions) | Reject; return to Pre-flight                             |
+| Session artifact `commit-sha` matches the commit reported in Phase 4       | Reject the artifact; re-run Phase 5 with the correct SHA |
+| Session artifact `agent` matches the attribution confirmed in Phase 3      | Reject the artifact; re-run Phase 5                      |
+| `session-id` date matches today's date                                     | Reject; re-allocate the session-id                       |
+
+## Notes
+
+- All errors and warnings should be logged with a timestamp for debugging.
+- Graceful exits (clean tree, user-declined completion) are **not** failures — they are valid outcomes of Phases 1–2 and must be reported as such.
+- The skill is not resume-safe by design: a failed session end is re-run from Phase 1 with a fresh look at the working tree. The only idempotent write is the session artifact (overwrite on the same `session-id`, never duplicate).
+- This reference is shared by all six phases; phase-specific handling is documented inline in the SKILL.md workflow.

package/scripts/postinstall.js

@@ -1,50 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Post-install script for arreio
- * Copies skills from the package to the user's .agents/skills directory
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-// Determine the source and destination paths
-const packageDir = path.dirname(__dirname);
-const skillsSource = path.join(packageDir, 'skills');
-const agentsDir = path.join(os.homedir(), '.agents');
-const skillsDestination = path.join(agentsDir, 'skills');
-
-// Function to recursively copy directories
-function copyDirectory(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-
-  const files = fs.readdirSync(src);
-  files.forEach(file => {
-    const srcFile = path.join(src, file);
-    const destFile = path.join(dest, file);
-    const stat = fs.statSync(srcFile);
-
-    if (stat.isDirectory()) {
-      copyDirectory(srcFile, destFile);
-    } else {
-      fs.copyFileSync(srcFile, destFile);
-    }
-  });
-}
-
-try {
-  // Create .agents directory if it doesn't exist
-  if (!fs.existsSync(agentsDir)) {
-    fs.mkdirSync(agentsDir, { recursive: true });
-  }
-
-  // Copy skills to .agents/skills
-  copyDirectory(skillsSource, skillsDestination);
-  console.log(`✓ Arreio skills installed to ${skillsDestination}`);
-} catch (error) {
-  console.error(`✗ Failed to install Arreio skills: ${error.message}`);
-  process.exit(1);
-}