arreio 1.0.2-dev.0 → 1.0.3

package/README.md

@@ -1,8 +1,3 @@
----
-Title: Arreio
-Type: Documentation
----
-
 **Arreio** (Brazilian word for _harness_) transforms agentic coding workflows into a predictable, safe, and high-quality software delivery pipeline.
 
 By enforcing a **pragmatic**, guardrailed execution, Arreio brings structure to AI-driven development. Master just four core phases to orchestrate a highly reliable development cycle:
@@ -17,7 +12,9 @@ Install Arreio as a dependency to enable all skills in your workspace:
 npm install arreio
 ```
 
-Then initialize your project to set up Arreio workflows:
+The post-install script will automatically copy all Arreio skills to your project's `.agents/skills/` directory, making them available in VS Code Copilot Chat. (Note: npm may show an advisory about unallowed install scripts—this is informational and won't block the installation.)
+
+Then initialize your project to set up the Arreio folder structure and documentation:
 
 ```
 /arreio-init
@@ -25,7 +22,7 @@ Then initialize your project to set up Arreio workflows:
 
 Run this command in VS Code Copilot Chat to:
 
-1. Copy all Arreio skills to your `~/.agents/skills/` directory
+1. Verify or manually install Arreio skills to `.agents/skills/` (if postinstall was skipped)
 2. Create the project structure (`docs/plans/`, `docs/learn/`, etc.)
 3. Set up architectural documentation and index files
 

package/package.json

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

package/scripts/postinstall.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for arreio
+ * Copies skills from the package to the project's .agents/skills directory
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Determine the source and destination paths
+const packageDir = path.dirname(__dirname);
+const skillsSource = path.join(packageDir, 'skills');
+const agentsDir = path.join(process.cwd(), '.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);
+}

package/skills/arreio-init/SKILL.md

@@ -35,16 +35,18 @@ After initialization, the following modules can operate:
 
 The initialization workflow runs in two phases:
 
-1. **Phase 0: Install Skills** — Copy Arreio skills to `~/.agents/skills/` for VS Code Copilot Chat discovery
+1. **Phase 0: Install Skills (Optional)** — Verify or manually copy Arreio skills to `.agents/skills/` in the project (skills are normally installed via npm postinstall, but this phase can install them as a fallback)
 2. **Phase 1: Initialize Project Structure** — Create folders, indexes, and architectural documentation
 
-### Step 1: Install Skills
+### Step 1: Install Skills (Optional Fallback)
 
-Install Arreio skills to the user's `.agents/skills` directory. See [modules/install.md](modules/install.md) for detailed instructions.
+Verify that Arreio skills are installed to the project'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.
+**Why:** Skills must be available in `.agents/skills/` for VS Code Copilot Chat discovery. Normally, the npm postinstall script handles this automatically when you run `npm install arreio`. This step provides a manual fallback if postinstall was skipped.
 
-**Action:** Execute the [install.md](modules/install.md) phase to copy all skills from `node_modules/arreio/skills/` to `~/.agents/skills/`.
+**When to run:** Skip this step if npm postinstall has already run. If skills are not yet installed, this phase will copy them from `node_modules/arreio/skills/` to `.agents/skills/`.
+
+**Action:** See [install.md](modules/install.md) for verification and manual installation steps.
 
 ### Step 2: Create Core Folder Structure
 
@@ -199,13 +201,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 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

@@ -1,44 +1,63 @@
 ---
 title: Install Skills
-description: Install Arreio skills to the user's .agents/skills directory, making them available in VS Code Copilot Chat.
+description: Verify or manually install Arreio skills to the project's .agents/skills directory, providing a fallback if npm postinstall was skipped.
 type: module
 version: 1.0
 timestamp: "2026-09-01"
 ---
 
-# Phase 0 - Install Skills
+# Phase 0 - Install Skills (Fallback)
 
-**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.
+**Purpose:** Verify that Arreio skills are installed to the project's `.agents/skills/` directory, making them available for discovery and invocation in VS Code Copilot Chat. This is normally handled by the npm postinstall script, but this phase provides a manual fallback if postinstall was skipped or if users need to reinstall skills.
 
 ## Workflow
 
-This is the Phase 0 pipeline for the Arreio Init Skill. It orchestrates the following steps before creating project structure.
+This is the Phase 0 pipeline for the Arreio Init Skill. It performs verification and optional installation before creating project structure.
 
-### Step 1: Verify Installation Context
+### Step 1: Check if Skills Already Installed
 
-Verify that the prerequisites are met:
+First, verify that Arreio skills are already available:
+
+1. Check if `.agents/skills/` directory exists in the project and contains the expected skill folders (plan, work, review, learn, end-session, arreio-init).
+2. If all skills are present and current, log success and skip to project structure initialization (Step 2).
+3. If skills are missing or incomplete, proceed to Step 2.
+
+**Result:**
+
+- ✓ Skills already installed → Skip to project structure
+- ✗ Skills missing → Proceed to manual installation
+
+### Step 2: Verify Installation Context (if needed)
+
+### Step 2: Verify Installation Context (if needed)
+
+Verify that the prerequisites are met if skills need to be installed:
 
 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/`).
+3. The project directory is writable (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).
+- **No write access:** Report an environment error (unable to write to project directory).
+
+### Step 3: Create Target Directory
+
+Create the destination directory hierarchy:
 
-### Step 2: Create Target Directory
+### Step 3: 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/`
+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
+### Step 4: Copy Skills from Package
 
-Copy each skill directory from `node_modules/arreio/skills/` to `~/.agents/skills/`:
+Copy each skill directory from `node_modules/arreio/skills/` to `.agents/skills/`:
 
 **Skills to copy:**
 
@@ -54,7 +73,7 @@ Copy each skill directory from `node_modules/arreio/skills/` to `~/.agents/skill
 For each skill:
 
 1. Read the source directory: `node_modules/arreio/skills/<skill-name>/`
-2. Copy recursively to destination: `~/.agents/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>`
 
@@ -64,13 +83,13 @@ If any copy operation fails:
 - 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
+### Step 5: 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
+- `.agents/skills/<skill-name>/SKILL.md` exists
 - Directory structure is intact (modules/, references/ subdirs if present)
 
 If verification passes, log:
@@ -89,14 +108,14 @@ 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
+### Step 6: 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.
+Next step: Project structure will be initialized in the next phase of arreio-init.
 
 You can now use:
   /plan    — Create implementation plans
@@ -109,14 +128,14 @@ You can now use:
 
 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/`
+- ✓ `.agents/skills/` directory exists in the project
+- ✓ 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
 
@@ -126,11 +145,11 @@ Refer to [error-handling.md](../references/error-handling.md) for category class
 
 - **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.
+- **Category 3 (Environment issue):** Cannot write to project `.agents/` directory; insufficient permissions.
 
 ## 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.
+- Skills are copied to the project's `.agents/` directory, keeping them scoped to the project. Each project gets its own copy of skills.
+- 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.