arreio 1.0.0-dev.1

package/README.md

@@ -0,0 +1,81 @@
+---
+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:
+
+**Plan → Work → Review → Learn**
+
+## Installation
+
+Install Arreio as a dependency to enable all skills in your workspace:
+
+```bash
+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:
+
+- **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
+
+## Skill Based Workflow
+
+**Arreio** orchestrates work through predictable skills that run in sequence:
+
+Use /arreio-init to initialize a new project, to enable the project to follow the four phases of the Arreio workflows.
+
+### Plan
+
+| Phase | Module Name  | Purpose                                   |
+| ----- | ------------ | ----------------------------------------- |
+| 1     | **scope**    | Gather context, validate domain           |
+| 2     | **research** | Discover patterns, detect high-risk areas |
+| 3     | **design**   | Decompose into implementation units       |
+| 4     | **generate** | Select tier, render plan, save to docs    |
+| 5     | **tasks**    | Slice plan into executable tasks          |
+
+### Work
+
+| Phase | Module Name | Purpose                                   |
+| ----- | ----------- | ----------------------------------------- |
+| 1     | **triage**  | Classify input and extract context        |
+| 2     | **prepare** | Set up environment, move task to progress |
+| 3     | **execute** | Implement with test-first discipline      |
+| 4     | **review**  | Code review, quality gates, move to done  |
+
+### Review
+
+| 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                   |
+
+### Learn
+
+| Phase | Module Name  | Purpose                             |
+| ----- | ------------ | ----------------------------------- |
+| 1     | **capture**  | Extract and capture knowledge entry |
+| 2     | **refine**   | Curate and refine the entry         |
+| 3     | **index**    | Catalog and index the entry         |
+| 4     | **maintain** | Dedup, refresh, and prune entries   |
+
+### Supporting Skills
+
+We have designed a set of supporting skills to help you to manage your repository and work.
+
+#### /arreio-init
+
+Initialize a new project, enabling the project to follow the four phases of the Arreio workflows
+
+#### /end-session
+
+Preserve session context with a well-documented commit capturing state, decisions, and next steps.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "arreio",
+  "version": "1.0.0-dev.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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wicttor/arreio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wicttor/arreio/issues"
+  },
+  "homepage": "https://github.com/wicttor/arreio#readme",
+  "keywords": [
+    "arreio",
+    "agentic-workflows",
+    "ai-driven-development",
+    "software-delivery",
+    "plan-work-review-learn",
+    "guardrailed-execution",
+    "quality-assurance",
+    "code-review",
+    "documentation",
+    "workflow-orchestration"
+  ],
+  "main": "README.md",
+  "files": [
+    "skills/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,50 @@
+#!/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);
+}

package/skills/arreio-init/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: arreio-init
+description: "Initialize Arreio workflow system. Use when: setting up a new project for Arreio planning, learning, and task execution; preparing workspace before running plan/learn/work skills; bootstrapping project documentation structure."
+argument-hint: "run to initialize workspace"
+user-invocable: true
+version: 1.1.0
+timestamp: "2026-08-13"
+---
+
+# Arreio Init
+
+## Purpose
+
+**Arreio Init** bootstraps the complete Arreio workflow system for a project. It creates the required folder structure, index files, and architectural documentation that enable the downstream Arreio skills (plan, learn, work, review) to function correctly.
+
+## When to Use
+
+Run this skill when:
+
+- Setting up a **new project** for Arreio workflows
+- **First time** using Arreio in an existing project
+- After cloning a repo—to ensure all required files and folders are present
+- Before invoking other Arreio skills (plan, learn, work, review)
+
+## Dependencies Enabled
+
+After initialization, the following modules can operate:
+
+- **Plan** (`plan/SKILL.md`) - Creates structured implementation plans
+- **Learn** (`learn/SKILL.md`) - Extracts and organizes learnings
+- **Work** (`work/SKILL.md`) - Executes implementation tasks
+- **Review** (`review/SKILL.md`) - Analyzes code changes
+
+## Workflow
+
+### Step 1: Create Core Folder Structure
+
+Creates the organizational spine for Arreio artifacts:
+
+- `docs/plans/` — Stores generated plans and design artifacts
+- `docs/learn/` — Stores extracted learnings and insights
+- `docs/reports/` — Stores review reports and analysis
+- `docs/tasks/` — Stores task lists and execution records
+- `docs/archives/` — Stores historical artifacts
+
+**Why:** Downstream skills assume these folders exist and will create files within them.
+
+### Step 2: Initialize Root Architecture Document
+
+**File:** `ARCHITECTURE.md` (project root)
+
+**Rationale:** Provides a single source of truth for project structure, principles, and design decisions. Other skills reference this for context.
+
+**Action:** If `ARCHITECTURE.md` doesn't exist, create it using the [Architecture Template](references/architecture-template.md).
+
+### Step 3: Initialize Plans Index
+
+**File:** `docs/plans/index.md`
+
+**Rationale:** Central registry of all plans. The `plan/SKILL.md` module creates plan files and links them here.
+
+**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
+
+**Folder:** `docs/tasks/`
+
+**Rationale:** Root folder for task artifacts. The `plan/SKILL.md` Tasks phase will create per-plan subdirectories (`docs/tasks/<plan-id>/`) with their own indexes when tasks are generated.
+
+**Action:** Create the `docs/tasks/` folder if it doesn't exist.
+
+### Step 5: Initialize Learning Index
+
+**File:** `docs/learn/index.md`
+
+**Rationale:** Central knowledge base index. The `learn/SKILL.md` module organizes learnings and cross-links them here.
+
+**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
+
+**Folder:** `docs/reports/`
+
+**Rationale:** Stores review reports and analysis artifacts. The `review/SKILL.md` module generates reports here.
+
+**Action:** Create the `docs/reports/` folder if it doesn't exist.
+
+### Step 7: Create Plan Skill Hidden Artifact Directories
+
+**Folders:**
+
+- `docs/plans/.scope/` — Stores Scope phase 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.
+
+**Action:** Create all three directories if they don't exist.
+
+### Step 8: Create Work Skill Hidden Artifact Directories
+
+**Folders:**
+
+- `docs/plans/.work/.triage/` — Stores Triage phase artifacts
+- `docs/plans/.work/.prepare/` — Stores Prepare phase 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.
+
+**Action:** Create all four directories if they don't exist.
+
+### Step 9: Create Review Skill Hidden Artifact Directories and Registry
+
+**Folders:**
+
+- `docs/plans/.review/.scope/` — Stores Review Scope phase artifacts
+- `docs/plans/.review/.prepare/` — Stores Review Prepare phase artifacts
+- `docs/plans/.review/.analyze/` — Stores Review Analyze phase artifacts
+- `docs/plans/.review/.report/` — Stores Review Report phase artifacts
+
+**File:**
+
+- `docs/plans/.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.
+
+**Action:** Create all four directories if they don't exist. If `docs/plans/.review/index.md` doesn't exist, create it with a header:
+
+```markdown
+---
+type: "index"
+title: "Review Reports Index"
+description: "Central registry of all code review reports."
+timestamp: "2026-07-03"
+---
+
+## Overview
+
+This is the index of all review reports for the project. Reports are organized by review-id and linked from this registry.
+
+## Review Reports
+
+<!-- Add new review reports below. Reports are generated by the `/review` skill. -->
+
+_No review reports yet._
+```
+
+### Step 10: Create Learn Skill Hidden Artifact Directories
+
+**Folders:**
+
+- `docs/plans/.learn/.capture/` — Stores Capture phase artifacts
+- `docs/plans/.learn/.refine/` — Stores Refine phase artifacts
+- `docs/plans/.learn/.index/` — Stores Index phase artifacts
+- `docs/plans/.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.
+
+**Action:** Create all four directories if they don't exist.
+
+### Step 11: Create Learn Category Folders
+
+**Folders:**
+
+- `docs/learn/decision/` — Stores decision-type learnings
+- `docs/learn/pattern/` — Stores pattern-type learnings
+- `docs/learn/gotcha/` — Stores gotcha-type learnings
+- `docs/learn/workflow/` — Stores workflow-type learnings
+
+**Rationale:** The `learn/SKILL.md` skill organizes knowledge entries by type. These folders provide category structure for the learnings index.
+
+**Action:** Create all four folders if they don't exist.
+
+## Success Criteria
+
+After initialization, verify:
+
+- ✓ 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:
+  - `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/plans/.review/.scope/`, `docs/plans/.review/.prepare/`, `docs/plans/.review/.analyze/`, `docs/plans/.review/.report/`
+  - `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/`
+- ✓ 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)
+- ✓ You can now run all four Arreio skills (plan, work, review, learn) without setup errors
+
+## Self-Healing Behavior
+
+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/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.
+
+**However**, running `arreio-init` upfront provides several benefits:
+
+- All directories are created consistently in one pass
+- Ensures the project structure is fully initialized before any skill runs
+- Provides a clear baseline for verification (no hidden "auto-created" surprises)
+- Reduces latency of first skill invocation
+
+Running arreio-init upfront is **recommended** for new projects, but not strictly required.

package/skills/arreio-init/references/architecture-template.md

@@ -0,0 +1,85 @@
+---
+title: "Architecture Template"
+description: "A template for documenting the architecture of a software system, including system overview, core constraints, technology stack, architectural pattern, data flow, codebase map, component design philosophy, and operational guidelines."
+type: Documentation
+version: 1.0
+timestamp: "2026-07-03"
+---
+
+````markdown
+# Architecture Documentation
+
+A bird's-eye view of the system design, boundaries, and codebase layout.
+
+---
+
+## 1. System Overview
+
+- **Domain Problem**: [One-sentence explanation of what business problem this software solves]
+- **Target Audience**: [Who uses this application and what they achieve with it]
+- **Core Goal**: Provide an uncompromised, resilient system for [Primary Core Feature]
+
+## 2. Core Constraints (The "Don'ts")
+
+- **No Shared State**: Context modules must remain fully isolated from each other.
+- **No Direct DB Calls**: Frontend components must never query database instances.
+- **No Third-Party Bleed**: Wrap external APIs inside internal adapters.
+- **No Deep Inheritance**: Favor composition and simple utility interfaces over deep class trees.
+
+## 3. Technology Stack
+
+| Layer           | Technology        | Primary Responsibility                       |
+| :-------------- | :---------------- | :------------------------------------------- |
+| **Frontend**    | React / Next.js   | Client UI and local state orchestration      |
+| **Backend API** | Node.js / Fastify | Request validation, business logic execution |
+| **Database**    | PostgreSQL        | Relational storage and ACID transactions     |
+| **Caching**     | Redis             | Session state and global rate limiting       |
+
+## 4. Architectural Pattern & Data Flow
+
+The system follows a strict **Layered Architecture**. Data flows unidirectionally from the User Interface down to the Storage Layer.
+
+```mermaid
+graph TD
+    UI[User Interface] --> API[API Gateway / Router]
+    API --> Service[Service Logic Layer]
+    Service --> Data[Data Access Layer]
+    Data --> DB[(PostgreSQL Database)]
+
+    subgraph Boundaries
+        Service --> |Adapter| ExternalAPI[Third-Party Service]
+    end
+```
+
+## 5. Codebase Map
+
+```text
+├── src/
+│   ├── config/          # Global application configurations and environment schemas
+│   ├── entrypoints/     # System entry points (server.js, workers, cron triggers)
+│   ├── domains/         # Vertical slices containing isolated business domains
+│   │   └── billing/     # Example domain: Handles invoices, webhooks, subscriptions
+│   │       ├── components/  # Domain-specific UI primitives
+│   │       ├── services/    # Business rules and internal calculations
+│   │       └── db/          # Queries, transactions, and tables
+│   ├── shared/          # Globally accessible utility libraries and design systems
+│   └── tests/           # Integration test suites and regression hooks
+```
+
+### Entry Points
+
+- **HTTP Server**: `src/entrypoints/server.js` — Bootstraps the global API instance.
+- **Worker Queue**: `src/entrypoints/worker.js` — Processes background tasks and retry loops.
+
+## 6. Component Design Philosophy
+
+- **Thin Controllers**: Route handlers only validate inputs and delegate work immediately.
+- **Fat Services**: Domain logic lives exclusively in pure, testable service functions.
+- **Predictable UI**: Presentational components consume immutable properties; state changes bubble up via events.
+
+## 7. Operational Guidelines & Verification
+
+- **Local Verification**: Execute `npm run check` to validate formatting, linting, and types before creating any pull request.
+- **Test Isolation**: Database unit tests must spin up an ephemeral container instance to prevent state pollution.
+- **State Updates**: Always modify domain states via explicit commands, never through structural cross-mutation.
+````

package/skills/arreio-init/references/learn-index-template.md

@@ -0,0 +1,15 @@
+---
+title: Learn Index Template
+description: Template for the Learn Index file, which serves as a central reference point for learning resources and documentation within the project.
+type: Template
+version: 1.0
+timestamp: "2026-07-03"
+---
+
+# Index of Learning Resources
+
+This document serves as a central reference point for learning resources and documentation within the project. It is intended to help team members quickly find relevant information and guidance.
+
+```markdown
+# Learning Resources Index
+```

package/skills/arreio-init/references/plan-index-template.md

@@ -0,0 +1,29 @@
+---
+title: "Plan Index Template"
+description: "A template for the index of planning documents, providing an overview of the knowledge base and linking to specific concept documents."
+type: Documentation
+version: 1.0
+timestamp: "2026-07-03"
+---
+
+# Plan Index Template
+
+Use the following template to create an index of planning documents in the `docs/plans/` directory. This index provides an overview of the knowledge base and links to specific concept documents.
+
+```markdown
+---
+type: "index"
+title: "Plan Index"
+description: "An index of planning documents, providing an overview of the knowledge base and linking to specific concept documents."
+timestamp: "2026-07-03"
+---
+
+## Overview
+
+This is the index of planning documents for the project. It serves as a central reference point for all planning-related artifacts, concepts, and templates.
+
+## Plans
+
+- [Plan Name 1](plan-one.md): Brief description of what this plan document contains. Task File: `docs/tasks/<task-id>/index.md`. STATUS: Active/Archived/Completed
+- [Plan Name 2](plan-two.md): Brief description of what this plan document contains. Task File: `docs/tasks/<task-id>/index.md`. STATUS: Active/Archived/Completed
+```

package/skills/arreio-init/references/tasks-index-template.md

@@ -0,0 +1,15 @@
+---
+title: Tasks Index Template
+description: Template for the Tasks Index file, which serves as a central reference point for task-related documentation and resources within the project.
+type: Template
+version: 1.0
+timestamp: "2026-07-03"
+---
+
+# Index of Tasks
+
+This document serves as a central reference point for task-related documentation and resources within the project. It is intended to help team members quickly find relevant information and guidance.
+
+```markdown
+# Tasks Index
+```