arreio 1.0.1-dev.0 → 1.0.2-dev.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arreio",
-  "version": "1.0.1-dev.0",
+  "version": "1.0.2-dev.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,7 @@ _No review reports yet._
 
 **Action:** Create all four directories if they don't exist.
 
-### Step 11: Create End-Session Skill Hidden Artifact Directory
+### Step 12: Create End-Session Skill Hidden Artifact Directory
 
 **Folder:**
 
@@ -169,7 +182,7 @@ _No review reports yet._
 
 **Action:** Create the directory if it doesn't exist.
 
-### Step 12: Create Learn Category Folders
+### Step 13: Create Learn Category Folders
 
 **Folders:**
 
@@ -186,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:

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/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);
-}