arreio 1.0.1-dev.0 → 1.0.1

package/README.md

@@ -17,7 +17,21 @@ 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:
+The post-install script will automatically copy all Arreio skills to your `~/.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
+```
+
+Run this command in VS Code Copilot Chat to:
+
+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
+
+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.1",
   "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

@@ -33,7 +33,22 @@ 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 (Optional)** — Verify or manually copy Arreio skills to `~/.agents/skills/` (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 (Optional Fallback)
+
+Verify that Arreio skills are installed to the user's `.agents/skills` directory. See [modules/install.md](modules/install.md) for detailed instructions.
+
+**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.
+
+**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
 
 Creates the organizational spine for Arreio artifacts:
 
@@ -45,7 +60,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 +68,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 +76,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 +84,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 +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 6: Create Reports Folder
+### Step 7: Create Reports Folder
 
 **Folder:** `docs/reports/`
 
@@ -85,7 +100,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 +112,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 +125,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 +161,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 +174,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 +184,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 +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 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,151 @@
+---
+title: Install Skills
+description: Verify or manually install Arreio skills to the user'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 (Fallback)
+
+**Purpose:** Verify that Arreio skills are installed to the user'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 performs verification and optional installation before creating project structure.
+
+### Step 1: Check if Skills Already Installed
+
+First, verify that Arreio skills are already available:
+
+1. Check if `~/.agents/skills/` directory exists 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/`).
+
+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 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/`
+
+### Step 4: 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 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
+- 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 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 the next phase 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.