@rryando/arcs 3.0.0 → 3.1.1

package/README.md

@@ -1,217 +1,249 @@
-# ARCS
+<div align="center">
 
-> Give AI agents durable memory — so they start from context, not a blank slate.
+# ARCS
 
-ARCS tracks projects, tasks, plans, and knowledge as a directed acyclic graph (DAG) stored in `~/.arcs/`. AI agents call `arcs <command>` to read structured project context instead of scanning codebases from scratch each session.
+**Agent Routing & Context System**
 
-The name is a direct nod to graph theory — where nodes are connected by "arcs" (directed edges). It perfectly describes this DAG-based task orchestration tool.
+[![npm](https://img.shields.io/npm/v/@rryando/arcs?color=cb3837&label=npm&logo=npm)](https://www.npmjs.com/package/@rryando/arcs)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
----
+*Persistent workflow continuity for AI agents — start from context, not a blank slate.*
 
-## What Is ARCS
+</div>
 
-Every AI coding session starts fresh. ARCS fixes that by maintaining three persistent surfaces per project:
+---
 
-```mermaid
-graph LR
-    CTX["arcs context\n──────────\noperating brief\ncurrent focus\nnext action"]
-
-    subgraph Q["Queue  (tasks.md + tasks/index.json)"]
-        QD["backlog → in_progress → done\nimmediate work items"]
-    end
-    subgraph P["Plan  (plans/*.md + .diagram.mmd)"]
-        PD["proposed → in_progress → done\nmulti-step feature work"]
-    end
-    subgraph M["Memory  (knowledge/*.md)"]
-        MD["lessons · patterns · gotchas · architecture\ndurable, searchable, BM25-indexed"]
-    end
-
-    CTX --> Q
-    CTX --> P
-    CTX --> M
-```
+ARCS gives AI coding agents a queryable project DAG so they never start cold. Instead of scanning a codebase from scratch, an agent calls `arcs brief` and gets back: what to work on, what was decided, and what went wrong last time — in a single ~1 KB JSON envelope.
 
-An agent calls `arcs brief` at session start and receives an **operating brief** (~890-byte routing envelope with `currentFocus`, `recommendedSurface`, and `nextAction`) — without reading a single source file.
+> **arcs** `/ɑːrks/` — Directed edges in graph theory. Also: **A**gent **R**outing & **C**ontext **S**ystem.
 
 ---
 
-## How It Works
+## The Problem
 
-### Orchestrator → Workflow → DAG
+Every AI coding session starts fresh. The agent doesn't know:
+- What task to pick up next (and which tasks are blocked by incomplete work)
+- What was already tried and failed
+- What architectural decisions were made
+- What the current plan looks like
 
-```mermaid
-flowchart TD
-    User(["User / Agent Request"])
-    Orch{"ARCS Orchestrator\nClassify intent"}
+ARCS solves this with three persistent surfaces:
 
-    Init["INIT\nCreate project\nScan codebase\nPopulate docs & knowledge"]
-    Brain["BRAINSTORM\nExplore state\nCreate plans + tasks\nGenerate diagram"]
-    Exec["EXECUTE\nSelect unblocked task\nDispatch implementer\nUpdate DAG"]
-    Sync["SYNC\nRe-scan codebase\nAudit docs\nReconcile drift"]
-    Explore["EXPLORE\nList projects\nInspect status\n(read-only)"]
-    Multi["MULTI\nChain workflows\nin parallel or sequence"]
+| Surface | Storage | Purpose |
+|---------|---------|---------|
+| **Queue** | `tasks/index.json` | Work items with dependency ordering via `dependsOn` |
+| **Plan** | `plans/*.md` + `.diagram.mmd` | Multi-step feature work with Mermaid execution maps |
+| **Memory** | `knowledge/*.md` | Durable discoveries: lessons, patterns, gotchas, architecture |
 
-    DAG[("~/.arcs/\nProjects · Tasks · Plans\nKnowledge · Diagrams")]
+---
 
-    User --> Orch
-    Orch -- "new project" --> Init
-    Orch -- "plan features" --> Brain
-    Orch -- "do work" --> Exec
-    Orch -- "update docs" --> Sync
-    Orch -- "inspect" --> Explore
-    Orch -- "compound" --> Multi
+## How It Works
 
-    Multi -.-> Init & Brain & Exec & Sync & Explore
+### The Core Loop
 
-    Init & Brain & Exec & Sync & Explore --> DAG
 ```
-
-### T0 Orientation
-
-```bash
-arcs brief --lean --json
-# → currentFocus, recommendedSurface, nextAction (~890-byte routing envelope)
+arcs next  →  [agent works]  →  arcs done <id>  →  arcs remember "..."
+     │                                │                      │
+     │ returns first task             │ completes task,      │ captures durable
+     │ whose dependencies             │ unblocks dependents  │ knowledge for
+     │ are ALL satisfied              │                      │ future sessions
+     ▼                                ▼                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    ~/.arcs/projects/{slug}/                      │
+│                                                                  │
+│  tasks/index.json ──dependsOn──→ topological sort → next task   │
+│  knowledge/       ──BM25+graph──→ related context               │
+│  plans/           ──diagram.mmd──→ execution map                │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-The orchestrator calls `arcs brief` at the start of every session to orient without loading any source files. `--lean` strips timestamps for token efficiency.
+Three commands: `arcs next` → work → `arcs done`. The DAG handles ordering.
 
-### Confidence Gate
+### Task Dependencies — The Actual DAG
 
-Before any irreversible action (DAG write, code edit, plan creation), the orchestrator self-scores 0–100% confidence with cited evidence. Threshold: 80% (85% for cross-cutting changes). Reads and exploration are never gated. Self-report without citations is invalid.
+Tasks declare dependencies. ARCS enforces acyclicity and uses topological sort to determine execution order:
 
-### Mutations
+```bash
+arcs task create myapp "Design database schema" --priority=high
+arcs task create myapp "Build REST API" --dependsOn=design-database-schema
+arcs task create myapp "Write integration tests" --dependsOn=build-rest-api
+arcs task create myapp "Deploy to staging" --dependsOn=build-rest-api,write-integration-tests
+```
 
-Mutating commands run directly — no token, no proposal. Reads and writes share the same `arcs <command> [args] --json` shape.
+```mermaid
+flowchart TD
+    T001["Design database schema"]:::done
+    T002["Build REST API"]:::inProgress
+    T003["Write integration tests"]:::backlog
+    T004["Deploy to staging"]:::blocked
+
+    T001 --> T002
+    T002 --> T003
+    T002 --> T004
+    T003 --> T004
+
+    classDef done fill:#22c55e,color:#fff
+    classDef inProgress fill:#f59e0b,color:#fff
+    classDef backlog fill:#94a3b8,color:#fff
+    classDef blocked fill:#ef4444,color:#fff
+```
 
----
+`arcs next` returns "Write integration tests" (T003) — it's the first task whose dependencies are all done. T004 is blocked because T003 isn't done yet. Priority is a tiebreaker within the same topological level, not the primary sort.
 
-## Prerequisites
+### The Orchestrator
 
-| Requirement | Version | Notes |
-|---|---|---|
-| [Node.js](https://nodejs.org/) | v18+ | Required |
-| [OpenCode](https://opencode.ai/) | latest | Required for agent integration |
-| [gh (GitHub CLI)](https://cli.github.com/) | any | Required — used by skills like `deep-pr-review` |
-| [graphify](https://github.com/safishamsi/graphify) | any | Optional — AST code-graph analysis |
-| [rtk](https://github.com/rtk-ai/rtk) | any | Optional — improves AI command usage tracking |
+When used with [OpenCode](https://opencode.ai/), ARCS ships a full orchestrator that automates the loop:
 
-**Install RTK:**
-```bash
-rtk init -g                 # Install hook + RTK.md (recommended)
-rtk init -g --opencode      # OpenCode plugin (instead of Claude Code)
+```mermaid
+flowchart TD
+    User(["User Request"])
+    T0["arcs brief → T0 envelope"]
+    Classify{"Classify Intent"}
+
+    Init["INIT\nScan repo → populate DAG"]
+    Brain["BRAINSTORM\nCreate plan → wire dependsOn\n→ generate diagram"]
+    Exec["EXECUTE\narcs next → dispatch sub-agent\n→ arcs done → unblock dependents"]
+    Sync["SYNC\nAudit DAG → reconcile drift"]
+
+    DAG[("Project DAG\ntasks + plans + knowledge\n+ dependency graph")]
+
+    User --> T0 --> Classify
+    Classify -- "new project" --> Init
+    Classify -- "plan features" --> Brain
+    Classify -- "do work" --> Exec
+    Classify -- "update docs" --> Sync
+    Init & Brain & Exec & Sync --> DAG
 ```
 
----
-
-## Quick Start
+The orchestrator:
+1. **Orients** — calls `arcs brief` for the T0 routing envelope (~1 KB)
+2. **Classifies** — detects intent (INIT / BRAINSTORM / EXECUTE / SYNC)
+3. **Routes** — delegates to specialist sub-agents with scoped prompts
+4. **Executes** — `arcs next` picks dependency-safe tasks; sub-agents implement them
+5. **Advances** — `arcs done` completes tasks, automatically unblocking dependents
 
-**1. Install from npm**
+### T0 Routing Envelope (the operating brief)
 
 ```bash
-npm install -g @rryando/arcs
+$ arcs brief --lean --json
 ```
 
-**2. Run the setup wizard**
-
-```bash
-npm run init
+```json
+{
+  "slug": "my-project",
+  "name": "My Project",
+  "operatingBrief": {
+    "currentFocus": "Build REST API",
+    "recommendedSurface": "QUEUE",
+    "why": "Task in progress: Build REST API",
+    "nextAction": "Continue task build-rest-api"
+  },
+  "openTasksCount": 3,
+  "topOpenTasks": [
+    { "id": "build-rest-api", "title": "Build REST API", "status": "in_progress" },
+    { "id": "write-integration-tests", "title": "Write integration tests", "status": "backlog" }
+  ]
+}
 ```
 
-The wizard:
-1. Builds the TypeScript source
-2. Registers the `arcs` CLI at `~/.local/bin/arcs`
-3. Creates `~/.arcs/` (project data store)
-4. Deploys bundled agents + skills into `~/.config/opencode/`
+~1 KB. No source files read. The orchestrator uses `recommendedSurface` to pick the workflow branch.
 
-**3. Track a project**
+---
 
-Open OpenCode in your desired project folder, then call `arcs init` to register it with ARCS:
+## CLI Reference
 
-```bash
-arcs init
-```
+All commands: `arcs <command> [args] --json`. Output: `{ok, data}` on success, `{ok, code, message}` on error.
 
-This creates the DAG structure for the project and registers the current directory as a workspace path.
+### Core Agent Loop
 
-**4. Start using ARCS**
+| Command | Purpose |
+|---------|---------|
+| `arcs brief` | T0 routing envelope — what to focus on |
+| `arcs next` | Next dependency-safe task + related knowledge |
+| `arcs done <taskId>` | Mark complete, unblock dependents |
+| `arcs remember "<text>"` | Capture knowledge (auto-classifies kind) |
+| `arcs status` | Progress overview across all surfaces |
 
-You'll see the **ARCS Orchestrator** listed as a selectable agent in OpenCode. Every session starts with an operating brief instead of a blank slate:
+### Tasks & Dependencies
 
-```bash
-arcs context
-# → project overview, current focus, active plans, relevant knowledge
-```
+| Command | Purpose |
+|---------|---------|
+| `arcs task create <slug> <title> --dependsOn=id1,id2` | Create task with dependency edges |
+| `arcs task update <slug> <id> --dependsOn=id1` | Add/update dependencies |
+| `arcs task transition <slug> <id> <status>` | Move through lifecycle |
+| `arcs diagram ready <slug> <planId>` | Get unblocked diagram nodes |
 
----
+### Project Management
 
-## Agents
+| Command | Purpose |
+|---------|---------|
+| `arcs project init` | Register current directory as a project |
+| `arcs project list` | List all tracked projects |
+| `arcs context [slug]` | Full context assembly (audience-targeted) |
+| `arcs search <slug> "<query>"` | BM25 + graph-scored search across DAG |
+| `arcs validate <slug>` | Health check — status drift, orphans, staleness |
 
-### Primary Agents
+### Plans & Knowledge
 
-These are registered as selectable agents in OpenCode. You interact with them directly.
+| Command | Purpose |
+|---------|---------|
+| `arcs plan create <slug> <title>` | Create a plan |
+| `arcs knowledge create <slug> <title>` | Create knowledge entry |
 
-| Agent | Token Mode | Description |
-|---|---|---|
-| **ARCS Orchestrator** | Full prose | Classifies intent, routes to workflows, delegates to sub-agents, writes DAG |
-| **ARCS Caveman** | ~65% fewer tokens | Identical capabilities; caveman-speak for chat narration only |
+### Flags
 
-The orchestrator follows three phases on every request:
-1. **Classify** — detect intent (INIT / BRAINSTORM / EXECUTE / SYNC / EXPLORE / MULTI)
-2. **Route** — delegate to the right workflow and specialist sub-agents
-3. **Complete** — summarize what was done, current state, and next steps
+| Flag | Effect |
+|------|--------|
+| `--json` | Structured JSON output (always use for agents) |
+| `--lean` | Strip timestamps (saves tokens) |
+| `--dry-run` | Validate without mutation |
+| `--help` | Per-command usage |
 
-ARCS Caveman supports three intensity levels: `lite`, `full` (default), `ultra`. Code, tool arguments, DAG content, and commit messages are always full prose regardless of mode.
+Full command discovery: `arcs --commands --json`.
 
-### Sub-Agents
+---
 
-Dispatched automatically by the orchestrator. You do not interact with them directly.
+## Graph & Retrieval
 
-| Sub-Agent | Role | Model |
-|---|---|---|
-| **software-engineer** | Implementation specialist. Writes code, runs tests, ships features. Loads quick-dev, code-agent, TDD, executing-plans skills as needed. | Opus |
-| **tech-architect** | Architecture and analysis specialist. Deep structural reasoning, refactor guidance, trade-off evaluation, and root cause analysis without making hasty edits. | Haiku |
-| **qa-analyst** | Quality enforcement specialist. Proactive code audits, convention compliance, and verification gate enforcement. | Haiku |
-| **oncall-ops** | Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling. | Opus |
-| **arcs-docs** | ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. | Opus |
-| **system-architect** | Architecture and design specialist. Module boundaries, dependency graphs, migration strategies, and cross-project design decisions. | Opus |
-| **code-reviewer** | Reviews code changes for production readiness. Catches correctness, maintainability, and testing issues. | Haiku |
-| **docs-researcher** | Handles documentation writing, research synthesis, and document-heavy analysis tasks. | Opus |
+ARCS builds a relationship graph across all project entities:
 
----
+| Edge Type | Weight | Connects |
+|-----------|--------|----------|
+| `task_belongs_to_plan` | 1.0 | Task → Plan |
+| `task_blocks_task` | 0.95 | Task → Task (from `dependsOn`) |
+| `shares_source_file` | 0.9 | Any → Any (co-reference) |
+| `knowledge_touches_file` | 0.85 | Knowledge → File |
+| `plan_contains_task` | 0.8 | Plan → Task |
+| `shares_keywords` | 0.5 | Knowledge → Knowledge |
 
-## Skills
+Queries: `arcs search` uses BM25 for text + graph traversal (weighted BFS) for relationship scoring. `arcs next` enriches results with related knowledge from the graph.
 
-Skills are instruction sets loaded on demand. The orchestrator auto-layers them based on context; sub-agents load them at dispatch time.
-
-### Work Mode (select exactly one per code-change dispatch)
+---
 
-| Skill | Load When |
-|---|---|
-| `quick-dev` | Fully bounded — rename, refactor, config nudge, trivial bugfix |
-| `code-agent` | 50–90% clear, 1–2 open decisions resolvable from the repo |
-| `test-driven-development` | New feature or bugfix — test-first discipline adds value |
-| `brainstorming` | Design open, product direction genuinely unclear |
+## Sub-Agents
 
-### Lifecycle & Planning (layer on top of work mode)
+The orchestrator dispatches specialist sub-agents with scoped prompts:
 
-| Skill | Load When |
-|---|---|
-| `writing-plans` | Have requirements, about to create a structured plan |
-| `executing-plans` | Have a plan, executing it in a separate session with checkpoints |
-| `subagent-driven-development` | Multi-task plan with independent leaf nodes |
-| `verification-before-completion` | Before claiming "done" on any non-trivial change |
-| `requesting-code-review` | Self-review gate at phase/feature completion |
-| `deep-pr-review` | Deep PR review triggered from a GitHub PR link |
+| Sub-Agent | Role | When |
+|-----------|------|------|
+| **software-engineer** | Writes code, runs tests | EXECUTE — bounded tasks |
+| **system-architect** | Module boundaries, plan creation | BRAINSTORM — design-open |
+| **tech-architect** | Deep analysis, trade-offs | Analysis without edits |
+| **oncall-ops** | Debugging, log triage, bisect | Bugs, test failures |
+| **code-reviewer** | Pre-merge review | PR review, phase gates |
+| **devil-advocate** | Adversarial KISS/YAGNI/DRY gate | Phase boundaries |
+| **arcs-docs** | DAG health, knowledge curation | SYNC workflow |
 
-### Diagnosis & Tooling
+### Skills (loaded per-dispatch)
 
-| Skill | Load When |
-|---|---|
-| `systematic-debugging` | Any bug, test failure, or unexpected behavior |
-| `confidence-gate` | Before irreversible actions — self-score with citations |
-| `to-diagram` | Creating or updating a Mermaid plan diagram |
-| `init-project` | Initializing a new ARCS project into the DAG |
-| `caveman-commit` | Writing git commit messages in ARCS Caveman mode |
+| Category | Skills |
+|----------|--------|
+| **Work mode** (pick one) | `quick-dev`, `code-agent`, `test-driven-development`, `brainstorming` |
+| **Lifecycle** | `writing-plans`, `executing-plans`, `subagent-driven-development` |
+| **Quality** | `requesting-code-review`, `deep-pr-review`, `systematic-debugging` |
+| **Tooling** | `to-diagram`, `init-project`, `caveman-commit` |
 
 ---
 
@@ -219,230 +251,104 @@ Skills are instruction sets loaded on demand. The orchestrator auto-layers them
 
 ```
 ~/.arcs/
-├── meta.json                    # Global registry — all project slugs
-└── projects/
-    └── {slug}/
-        ├── meta.json            # name · description · status · workspacePaths · lastSyncedAt
-        ├── overview.md          # 2-3 sentence summary + goals     ← summary docs
-        ├── tasks.md             # Execution queue (auto-rendered from structured tasks)
-        ├── dependencies.md      # Upstream / downstream project edges
-        ├── knowledge.md         # Pointer page → knowledge/ entries
-        ├── AGENTS.md            # Auto-generated guardrail doc (symlinked into workspace)
-        ├── tasks/
-        │   └── index.json       # Structured task records (status, priority, planId)
-        ├── plans/
-        │   ├── {planId}.meta.json
-        │   ├── {planId}.md      # Plan body (prose)       ← structured stores
-        │   └── {planId}.diagram.mmd  # Mermaid execution map (agents read this first)
-        └── knowledge/
-            ├── index.json
-            ├── {entryId}.meta.json
-            └── {entryId}.md     # Knowledge entry body
-```
-
-### Summary Docs vs Structured Stores
-
-| Layer | Files | Purpose |
-|---|---|---|
-| **Summary docs** | `overview.md`, `tasks.md`, `dependencies.md`, `knowledge.md` | Quick-orientation landing pages — short, scannable, always current |
-| **Structured stores** | `plans/*.md`, `knowledge/*.md`, `tasks/index.json` | Full documents with indexed metadata — durable, searchable, detailed |
-
-### Project Lifecycle
-
-```
-draft → active → completed → archived
+├── meta.json                         # Global registry
+└── projects/{slug}/
+    ├── meta.json                     # Project metadata + workspace paths
+    ├── overview.md                   # Summary + goals
+    ├── tasks.md                      # Rendered task queue (human-readable)
+    ├── tasks/index.json              # Structured tasks + dependsOn edges
+    ├── plans/
+    │   ├── {id}.meta.json            # Plan status + keywords
+    │   ├── {id}.md                   # Plan body
+    │   └── {id}.diagram.mmd          # Mermaid execution map (auto-generated arrows)
+    └── knowledge/
+        ├── index.json                # Knowledge index
+        ├── {id}.meta.json            # Metadata (kind, audience, sourceFiles)
+        └── {id}.md                   # Entry body
 ```
 
-### Plan Diagrams
-
-Each plan has an associated `.diagram.mmd` file — a Mermaid flowchart that serves as the **agent execution map**. Agents read the diagram first for task selection before loading plan prose.
-
-Node status is encoded via `classDef`:
+### Knowledge Kinds
 
-| Class | Meaning |
-|---|---|
-| `:::backlog` | Not started |
-| `:::in_progress` | Active |
-| `:::done` | Complete |
-| `:::blocked` | Waiting on dependency |
+8 structured categories: `lesson`, `gotcha`, `pattern`, `architecture`, `module`, `feature`, `reference`, `decision`.
 
 ---
 
-## Workspace Integration
-
-Registering a workspace path enables two features:
-
-**1. Context resolution** — `arcs context --path=/path/to/repo` matches the directory to its ARCS project and returns the operating brief, current focus, active plans, and relevant knowledge.
-
-**2. AGENTS.md generation** — `arcs sync-agents-md <slug>` assembles a coding guardrail document from three sources and symlinks it into each workspace:
-
-| Source | Content |
-|---|---|
-| Coding discipline | Non-negotiable rules (DRY, single responsibility, etc.) |
-| Codebase analysis | LLM-provided scan of tech stack, patterns, file structure |
-| Project context | ARCS overview, current focus, dependencies, active plans |
-
----
-
-## Development
+## Quick Start
 
-### Setup
+**1. Install**
 
 ```bash
-npm install
-npm run build
+npm install -g @rryando/arcs
 ```
 
-### Commands
+Registers `arcs` CLI, creates `~/.arcs/`, deploys agents + skills to `~/.config/opencode/`.
 
-| Command | Description |
-|---|---|
-| `npm run build` | Compile TypeScript → `dist/` |
-| `npm run dev` | Watch mode (rebuild on change) |
-| `npm test` | Run Vitest test suite (62 test files, 685 tests) |
-| `npm run typecheck` | Type check without emit |
-| `npm run lint` | Biome lint + format check |
-| `npm run lint:fix` | Auto-fix lint and format issues |
-| `npm run format` | Format only |
+**2. Track a project**
 
-Full quality gate before committing:
 ```bash
-npm test && npm run typecheck && npm run lint
+cd your-project
+arcs init
 ```
 
-### Testing Patterns
-
-| Pattern | Detail |
-|---|---|
-| Framework | Vitest |
-| DAG isolation | `withTempDataDir()` — each test gets a fresh `~/.arcs/` |
-| No mocks | Core DAG I/O tests operate on real (temp) filesystem |
-| Test location | All tests in `test/` (not co-located with source) |
-
-### Environment
+**3. Use it**
 
 ```bash
-# Override data directory (default: ~/.arcs/)
-ARCS_DATA_DIR=/path/to/custom/dir arcs context
+arcs brief              # What should I work on?
+arcs next               # Get next unblocked task
+arcs done <taskId>      # Mark complete, unblock dependents
+arcs remember "..."     # Capture what I learned
 ```
 
----
+Or select **ARCS Orchestrator** in OpenCode for full automation.
 
-## Bundle Release Playbook
+---
 
-> **Rule:** repo → config only. Never overwrite repo files from config.
+## Prerequisites
 
-| Step | Command | Notes |
-|---|---|---|
-| 1. Edit | Modify `opencode/arcs/skills/` or `opencode/arcs/prompts/` | Source of truth is the repo |
-| 2. Build | `npm run build:opencode-bundle` | Produces hashes, runtime JSON |
-| 3. Lint | `arcs lint-bundle` | Must pass with zero errors |
-| 4. Dry-run | `arcs deploy-superpowers --dry-run` | Review `filesAdded / filesChanged / filesRemoved` |
-| 5. Deploy | `arcs deploy-superpowers` | Writes to `~/.config/opencode/` |
-| 6. Restart | Restart OpenCode / IDE | Skills load at startup |
+| Tool | Required | Notes |
+|------|----------|-------|
+| [Node.js](https://nodejs.org/) v18+ | Yes | Runtime |
+| [OpenCode](https://opencode.ai/) | Recommended | Agent host (orchestrator + sub-agents) |
+| [graphify](https://github.com/safishamsi/graphify) | No | Optional AST-based codebase knowledge extraction |
 
 ---
 
-## Graphify Integration (Optional)
+## Graphify (Optional)
 
-Graphify performs AST-based static analysis of your codebase and ingests the results as ARCS knowledge entries — without any LLM API calls.
+When [graphify](https://github.com/safishamsi/graphify) is on PATH, ARCS auto-extracts structural knowledge during INIT and SYNC:
 
-See installation instructions at **https://github.com/safishamsi/graphify**.
+| Category | Cap | What |
+|----------|-----|------|
+| God nodes | 8 | Highest-connectivity modules |
+| Clusters | 8 | Directory-based module boundaries |
+| Couplings | 5 | Cross-module dependency links |
 
-### What gets extracted
+---
 
-| Category | Cap | Description |
-|---|---|---|
-| God nodes | 8 | Highest-connectivity modules — likely architectural hubs |
-| Architecture clusters | 8 | Directory-based groupings revealing module boundaries |
-| Cross-module couplings | 5 | Links between high-degree nodes across top-level directories |
+## Development
 
-### When it runs
+```bash
+git clone https://github.com/rryando/arcs.git
+cd arcs && npm install && npm run build
+```
 
-| Trigger | Action |
-|---|---|
-| `arcs init` | Full extraction → up to 20 knowledge proposals → creates DAG entries |
-| SYNC workflow | Re-extracts, compares against existing entries, surfaces stale / new / drifted |
-| Ad-hoc | `arcs graphify-sync <slug>` — re-extracts codebase graph on demand |
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm test` | Vitest suite (67 files, 744 tests) |
+| `npm run typecheck` | Type check without emit |
+| `npm run lint` | Biome lint + format |
 
-Output: `graphify-out/graph.json` in workspace (auto-added to `.gitignore`).
+### Bundle Workflow
 
-If graphify is not installed, ARCS operates normally — all graphify features are gated behind availability checks.
+```bash
+npm run build:opencode-bundle    # Build agent/skill bundle
+arcs lint-bundle                 # Validate bundle integrity
+arcs deploy-superpowers          # Deploy to ~/.config/opencode/
+```
 
 ---
 
-## Project Structure
+## License
 
-```
-arcs/
-├── src/
-│   ├── index.ts                          # Main entry point — dispatches to CLI
-│   ├── cli/
-│   │   ├── index.ts                      # Registry-first CLI router + fallback
-│   │   ├── command-registry.ts           # Declarative command registration system
-│   │   ├── arg-parser.ts                 # Schema-driven argument parser
-│   │   ├── output-envelope.ts            # Structured JSON output ({ok, data} / {ok, code, message})
-│   │   ├── help-generator.ts             # Auto-generated help text from registry
-│   │   ├── dag-commands.ts               # LEGACY: thin delegation shell (backward-compat)
-│   │   ├── brief-renderer.ts             # Renders brief output for arcs brief command
-│   │   ├── md-renderer.ts                # Markdown rendering utilities
-│   │   ├── bundle-installer.ts           # OpenCode bundle installer
-│   │   ├── setup.ts                      # Interactive setup wizard
-│   │   ├── lean-output.ts                # --lean flag support (strip timestamps)
-│   │   ├── arcs-orchestrate.ts           # Orchestrator prompt content
-│   │   ├── status-dashboard.ts           # TTY status overview
-│   │   └── commands/                     # 17 focused command modules (≤400 lines each)
-│   │       ├── index.ts                  # Trigger all command registrations (side-effects)
-│   │       ├── brief.ts                  # T0 operating brief
-│   │       ├── next.ts                   # arcs next — get next task + related knowledge
-│   │       ├── done.ts                   # arcs done — mark task complete (--learn flag)
-│   │       ├── remember.ts              # arcs remember — capture knowledge (auto-classify)
-│   │       ├── status.ts                # arcs status — progress overview
-│   │       ├── project.ts                # project list, get, init, validate
-│   │       ├── project-updates.ts        # project update-doc, update-status, update-paths
-│   │       ├── task.ts                   # task list, get, create, transition, update, delete
-│   │       ├── plan.ts                   # plan list, get, create, update-meta, update-body, delete
-│   │       ├── knowledge.ts              # knowledge CRUD
-│   │       ├── knowledge-search.ts       # Dedicated knowledge search
-│   │       ├── utility.ts                # context, search, agents-md, validate
-│   │       ├── batch.ts                  # batch operations
-│   │       ├── graph.ts                  # related, graph inspect
-│   │       ├── diagnostics.ts            # audit, diff
-│   │       ├── diagram.ts                # diagram ready/inspect/validate/status/show
-│   │       ├── dependency.ts             # dependency add/remove
-│   │       ├── maintenance.ts            # git-log, sync-agents-md
-│   │       ├── bundle.ts                 # lint-bundle, deploy-superpowers
-│   │       └── loop.ts                   # loop start, cancel, status
-│   ├── retrieval/
-│   │   ├── bm25.ts                       # BM25 full-text scoring
-│   │   ├── graph-retrieval.ts            # Graph-based related-entity retrieval
-│   │   ├── knowledge-selection.ts        # Graph+BM25 knowledge selection for context
-│   │   └── graph-cache.ts                # Graph index caching + invalidation
-│   └── utils/
-│       ├── dag.ts                        # Core DAG I/O
-│       ├── project-memory.ts             # Barrel re-exporting split modules below
-│       ├── storage-utils.ts              # Shared enums, types, filesystem helpers
-│       ├── plan-store.ts                 # Plan CRUD operations
-│       ├── knowledge-store.ts            # Knowledge CRUD operations
-│       ├── task-store.ts                 # Task CRUD operations
-│       ├── paths.ts                      # Data dir and project path helpers
-│       ├── workflow-policy.ts            # deriveOperatingBrief(), WorkflowSurface
-│       ├── schemas.ts                    # Shared Zod schemas
-│       ├── graphify.ts                   # Graphify integration (detect, extract, ingest)
-│       ├── graphify-knowledge.ts         # Graphify→knowledge entry ingestion helpers
-│       ├── diagram-generator.ts          # Generate Mermaid diagrams from task metadata
-│       ├── errors.ts                     # Error factory functions
-│       └── file-lock.ts                  # Advisory file locking for concurrent writes
-├── opencode/arcs/
-│   ├── skills/                           # Agent skill instruction sets (15 skills)
-│   ├── prompts/                          # Sub-agent prompt definitions (8 agents)
-│   ├── manifest.json                     # Bundle install manifest
-│   └── bundle-runtime.json               # Curated runtime payload
-├── scripts/
-│   ├── arcs-cli.mjs                      # CLI entry wrapper (bin)
-│   └── build-opencode-bundle.mjs         # Build bundle
-└── test/                                 # Vitest test suite (62 files, 685 tests)
-    └── helpers/
-        ├── cli-runner.ts                 # runCommand() for registry-path invocation
-        └── temp-data-dir.ts              # withTempDataDir() — isolated DAG state
-```
+MIT