# OAC Package Refactor — Master Planning Document

**Document**: 12-MASTER-SYNTHESIS.md  
**GitHub Issue**: #206  
**Status**: Authoritative Implementation Plan  
**Date**: 2026-02-19  
**Synthesized from**: 6 specialist research agents (Context, Agent Behaviour, Task Breakdown, Plugin System, ExternalScout, CLI & Multi-IDE)

---

## Table of Contents

1. [Executive Summary](#1-executive-summary)
2. [Architecture Overview](#2-architecture-overview)
3. [The 5 Core Subsystems](#3-the-5-core-subsystems)
4. [Implementation Phases (9 Weeks)](#4-implementation-phases-9-weeks)
5. [Key Technical Decisions](#5-key-technical-decisions)
6. [Critical Gaps to Address](#6-critical-gaps-to-address)
7. [Configuration Schema](#7-configuration-schema)
8. [Auto-Update Strategy](#8-auto-update-strategy)
9. [CLI Command Reference](#9-cli-command-reference)
10. [Success Metrics](#10-success-metrics)

---

## 1. Executive Summary

### What We Are Building

OAC (`@nextsystems/oac`) is transitioning from a 52KB bash-script installer (`install.sh`) into a proper npm CLI package with a rich plugin system, registry-backed component management, and first-class multi-IDE support.

The refactored OAC manages four types of AI configuration artifacts across four IDEs:

| Artifact | Description | Primary Location |
|----------|-------------|------------------|
| **Agents** | `.md` files with YAML frontmatter defining AI personas and permissions | `.opencode/agent/` |
| **Context files** | Markdown guides that shape AI behaviour in a session | `.opencode/context/` |
| **Skills** | Loadable modules (`SKILL.md` + `router.sh` + `scripts/`) | `.opencode/skills/` |
| **Plugins** | IDE integration hooks (TypeScript events, file-based, shell scripts) | IDE-specific |

| IDE | Priority | Integration Method |
|-----|----------|--------------------|
| OpenCode | PRIMARY | TypeScript npm plugin (`"plugin": ["@nextsystems/oac"]`) |
| Claude Code | Secondary | File-based plugin (`.claude-plugin/`) |
| Cursor | Tertiary | Router pattern in `.cursorrules` |
| Windsurf | Partial | Partial compatibility adapter |

### Key Architectural Decisions (Summary)

1. **OpenCode is the primary target** — richest plugin API (25+ events, custom tools, TypeScript SDK). All other IDEs are adaptation layers.
2. **Bundle context into npm, do not fetch at runtime** — eliminates network dependency during AI sessions, enables offline use, provides version-locked reproducibility.
3. **`agent.json` + `prompt.md` as source of truth** — clean separation of metadata/configuration from prose content; generate IDE-specific formats from this canonical form.
4. **shadcn-inspired registry** — adapt the shadcn component registry pattern for agents, skills, and context files. Already have `registry.json` in the repo.
5. **`oac.lock` lockfile** — reproducible installs across machines and CI, analogous to `package-lock.json`.
6. **Two-layer update system** — `update-notifier` for the CLI binary itself; hash-based registry polling for content files.
7. **Monorepo with tsup** — `packages/cli` (new) + `packages/compatibility-layer` (existing) + `packages/plugin-abilities` (existing).

### Success Criteria

- `npx @nextsystems/oac init` completes full project setup in under 2 minutes
- All bundled content survives `npm update` without overwriting user customizations
- OpenCode auto-updates agent/context files on every session start via `session.created` event
- `oac doctor` catches 100% of common misconfiguration issues
- Registry supports community-published agents/skills with SHA256 verification
- Zero bash script dependency for any core functionality (install.sh becomes legacy/deprecated)

---

## 2. Architecture Overview

### Package Structure (Monorepo)

```
@nextsystems/oac/                    # Root package (npm: @nextsystems/oac)
├── bin/
│   └── oac.js                       # CLI entry point (compiled)
├── packages/
│   ├── cli/                         # NEW: Full commander.js CLI
│   │   ├── src/
│   │   │   ├── commands/            # One file per command group
│   │   │   ├── registry/            # Registry client
│   │   │   ├── resolvers/           # 6-layer context resolver
│   │   │   ├── adapters/            # IDE format adapters
│   │   │   └── index.ts             # Entry point
│   │   ├── tsconfig.json
│   │   └── package.json
│   ├── compatibility-layer/         # EXISTING: Multi-IDE adapters
│   │   ├── src/
│   │   │   ├── adapters/
│   │   │   │   ├── claude.ts        # COMPLETE
│   │   │   │   ├── cursor.ts        # COMPLETE
│   │   │   │   └── windsurf.ts      # COMPLETE
│   │   │   └── index.ts
│   │   └── package.json
│   └── plugin-abilities/            # EXISTING: OpenCode plugin
│       ├── src/
│       │   ├── events/              # 25+ OpenCode event handlers
│       │   └── index.ts
│       └── package.json
├── .opencode/                       # Bundled OAC configuration
│   ├── agent/                       # Agent .md files (YAML frontmatter)
│   ├── context/                     # Bundled context files
│   ├── skills/                      # Skill packages
│   ├── plugin/                      # OpenCode plugin hooks
│   └── opencode.json                # OpenCode config
├── registry.json                    # Component registry (shadcn-style)
├── manifest.json                    # Bundle manifest with checksums
├── oac.lock                         # Lockfile template (copied to project)
└── package.json
```

### The 5 Core Subsystems and Their Relationships

```
┌─────────────────────────────────────────────────────────────────┐
│                     OAC CLI (Subsystem 1)                        │
│  oac init / add / update / remove / context / skill / plugin    │
│  oac doctor / rollback / publish / browse / search              │
└──────────┬────────────┬───────────────┬────────────┬────────────┘
           │            │               │            │
           ▼            ▼               ▼            ▼
┌──────────────┐ ┌────────────┐ ┌──────────────┐ ┌─────────────┐
│   Context    │ │  Agent &   │ │   Plugin     │ │  Registry & │
│   System     │ │   Skill    │ │   System     │ │  Community  │
│ (Subsystem 2)│ │ Management │ │ (Subsystem 4)│ │(Subsystem 5)│
│              │ │(Subsystem 3│ │              │ │             │
│ 6-layer      │ │            │ │ OpenCode     │ │ shadcn      │
│ resolution   │ │ agent.json │ │ Claude Code  │ │ registry    │
│ Bundle/      │ │ + prompt.md│ │ Cursor       │ │ oac.lock    │
│ manifest     │ │ Presets    │ │ Windsurf     │ │ SHA256 hash │
│ Auto-update  │ │ Skills pkg │ │ session.     │ │ verify      │
└──────────────┘ └────────────┘ │ created hook │ └─────────────┘
                                └──────────────┘
```

### Data Flow: From Registry to IDE

```
npm registry / community registry
         │
         │  oac add agent/openagent
         ▼
   Registry Client
         │ fetches files + verifies SHA256
         ▼
   oac.lock updated
         │
         ├──► .opencode/agent/openagent/
         │      ├── agent.json       (metadata, permissions, config)
         │      └── prompt.md        (prose content)
         │
         │  oac compat apply --ide=cursor
         ▼
   Compatibility Adapter
         │
         ├──► .cursorrules           (Cursor router pattern)
         ├──► CLAUDE.md             (Claude Code format)
         └──► .windsurfrules        (Windsurf format)
```

### Data Flow: Auto-Update via OpenCode Plugin

```
OpenCode session starts
         │
         │  fires session.created event
         ▼
   plugin-abilities/src/events/session.ts
         │
         │  reads oac.lock
         │  checks registry for newer versions
         │  compares SHA256 of installed files
         ▼
   No user modifications detected → auto-update silently
   User modifications detected    → prompt user (or skip in --yolo mode)
         │
         ▼
   Files updated in .opencode/
   IDE picks up changes on next tool invocation
```

---

## 3. The 5 Core Subsystems

---

### Subsystem 1: CLI & Package Distribution

#### Current State

The current `bin/oac.js` is 91 lines of Node.js that spawns `install.sh` (52KB bash script). It has no command parsing, no help text, no interactive prompts, and no multi-IDE awareness. The npm package `files` array in `package.json` already bundles `.opencode/` content correctly.

#### Target State

A full `commander.js`-based CLI with 20+ commands, interactive prompts via `@inquirer/prompts`, progress indication via `ora`, and coloured output via `chalk`. Built with `tsup` into `dist/cli.js`, entry point remains `bin/oac.js` which simply requires the compiled output.

#### Package Structure

```json
// packages/cli/package.json
{
  "name": "@nextsystems/oac-cli",
  "private": true,
  "main": "dist/index.js",
  "scripts": {
    "build": "tsup src/index.ts --format cjs --dts",
    "test": "vitest run",
    "dev": "tsup src/index.ts --watch"
  },
  "dependencies": {
    "commander": "^12.0.0",
    "@inquirer/prompts": "^5.0.0",
    "ora": "^8.0.0",
    "chalk": "^5.0.0",
    "conf": "^13.0.0",
    "fs-extra": "^11.0.0",
    "semver": "^7.6.0",
    "zod": "^3.23.0",
    "update-notifier": "^7.0.0"
  }
}
```

#### Commander.js Structure

```typescript
// packages/cli/src/index.ts
import { Command } from "commander";
import { initCommand } from "./commands/init";
import { addCommand } from "./commands/add";
import { contextCommand } from "./commands/context";
import { skillCommand } from "./commands/skill";
import { pluginCommand } from "./commands/plugin";
import { doctorCommand } from "./commands/doctor";

const program = new Command()
  .name("oac")
  .description("AI agent configuration manager")
  .version(packageJson.version)
  .option("--yolo", "skip all confirmations")
  .option("--no-color", "disable color output");

program.addCommand(initCommand);
program.addCommand(addCommand);
program.addCommand(contextCommand);
program.addCommand(skillCommand);
program.addCommand(pluginCommand);
program.addCommand(doctorCommand);
// ... additional commands

program.parse();
```

#### Key Design Decisions

- **tsup over tsc**: tsup bundles dependencies into a single file, eliminating runtime `node_modules` resolution issues when installed globally via `npm install -g`
- **`--yolo` flag**: Skips all `inquirer` prompts and confirmation gates. Required for CI/automation use cases
- **`conf` for global config**: Uses OS-appropriate config directory (`~/.config/oac/` on Linux/Mac, `%APPDATA%/oac/` on Windows). Survives npm updates
- **`update-notifier`**: Background process checks npm registry for CLI updates; shows non-blocking notification at session end

#### Critical Gaps

- The entire `packages/cli/` package does not exist yet — needs to be created from scratch
- `bin/oac.js` needs to be rewritten to simply `require('../packages/cli/dist/index.js')`
- `install.sh` remains as legacy fallback during transition but should be deprecated in v1.0

---

### Subsystem 2: Context System

#### Current State

Context files exist in `.opencode/context/` with a rich function-based and concern-based organizational pattern. `CONTEXT_SYSTEM_GUIDE.md` (16KB) documents the system thoroughly. However there is no programmatic management — files are installed/copied by `install.sh` and never updated automatically.

#### Target State

A 6-layer resolution system where the CLI and plugin can deterministically locate, version, and update context files. All OAC-maintained context files are bundled into the npm package with SHA256 checksums tracked in `manifest.json`.

#### The 6-Layer Priority Resolution

```
Priority (highest to lowest):
┌─────────────────────────────────────────────────────┐
│ 1. .oac/context/          project override          │ ← USER OWNED
│ 2. .opencode/context/     IDE config dir            │ ← OAC MANAGED (with user edits)
│ 3. IDE-specific dir       e.g. .cursor/context/     │ ← IDE MANAGED
│ 4. docs/                  project documentation     │ ← PROJECT OWNED
│ 5. ~/.config/oac/context/ user global overrides     │ ← USER OWNED
│ 6. npm package bundled    @nextsystems/oac/context/  │ ← OAC DEFAULT
└─────────────────────────────────────────────────────┘
```

Resolution algorithm:
1. Walk layers 1-6 in order
2. First file found at a given logical name wins
3. User-owned layers (1, 4, 5) are never overwritten by `oac update`
4. OAC-managed layer (2) is updated only when no user modifications detected (SHA256 match)

#### Bundle/Manifest Approach

```json
// manifest.json (in npm package root, copied to .oac/manifest.json on init)
{
  "version": "0.7.1",
  "generatedAt": "2026-02-19T00:00:00Z",
  "context": {
    "typescript-patterns.md": {
      "sha256": "a1b2c3d4...",
      "size": 4821,
      "category": "language",
      "description": "TypeScript coding patterns and conventions"
    },
    "git-workflow.md": {
      "sha256": "e5f6a7b8...",
      "size": 2341,
      "category": "workflow"
    }
  },
  "agents": {
    "openagent": {
      "sha256": "c9d0e1f2...",
      "files": ["agent.json", "prompt.md"]
    }
  },
  "skills": {
    "task-management": {
      "sha256": "f3a4b5c6...",
      "files": ["SKILL.md", "router.sh", "scripts/task-cli.js"]
    }
  }
}
```

#### Auto-Update Mechanism

```
oac update context (or: triggered by session.created event)
         │
         ├── Read .oac/manifest.json (installed versions + hashes)
         ├── Fetch registry for latest manifest
         ├── For each context file:
         │    ├── SHA256(installed file) == manifest.sha256?
         │    │    YES → file is stock OAC → safe to update
         │    │    NO  → file has user modifications
         │    │         ├── update mode == "auto-all"  → overwrite + backup
         │    │         ├── update mode == "auto-safe" → skip + notify
         │    │         └── update mode == "manual"    → skip silently
         │    └── New version available? → download + install + update manifest
         └── Print summary of updated / skipped / conflict files
```

#### CLI Commands

```bash
oac context install [name]     # Install a specific context file
oac context update [name]      # Update installed context files
oac context validate           # Validate all context files are syntactically correct
oac context resolve <name>     # Show which layer a context file resolves from
oac context list               # List all context files with source layer
oac context diff <name>        # Show diff between installed and stock version
```

#### Key Design Decisions

- **Bundle into npm, not fetch at runtime**: Context files are needed the moment an AI session starts. Network dependency at that point is unacceptable. Bundling ensures offline functionality and version-locked reproducibility.
- **ContextScout navigation**: The existing ContextScout agent that discovers relevant context via navigation is preserved. The CLI manages the underlying files; ContextScout operates on them.
- **`manifest.json` is the authoritative truth**: Neither `package.json` version nor git history determines what's installed — only `manifest.json` + SHA256 comparison.

---

### Subsystem 3: Agent & Skill Management

#### Current State

Agents are `.md` files with YAML frontmatter in `.opencode/agent/`. No programmatic management exists. Skills live in `.opencode/skills/` as `SKILL.md` + `router.sh` + `scripts/` bundles. `task-cli.ts` is a TypeScript file requiring `ts-node` to run — this is a critical gap.

#### Target State

A canonical `agent.json` + `prompt.md` two-file representation per agent, with IDE-specific formats generated on demand. Skills are proper packages with compiled JS. A preset system allows user customizations to survive updates.

#### Agent Architecture: `agent.json` + `prompt.md`

```
.opencode/agent/openagent/
├── agent.json        # Metadata, permissions, config, OAC-specific data
└── prompt.md         # The actual agent prompt content (prose)
```

```json
// agent.json — canonical agent definition
{
  "name": "openagent",
  "displayName": "Open Agent",
  "version": "2.1.0",
  "description": "Primary orchestration agent for plan-first development",
  "model": "claude-sonnet-4-5",
  "maxTokens": 8192,
  "permission": [
    { "deny": "bash(**)" },
    { "allow": "bash(git status, git diff, git log)" },
    { "allow": "bash(npm run*)" }
  ],
  "tools": ["read", "write", "edit", "bash", "glob", "grep"],
  "tags": ["orchestration", "planning", "primary"],
  "oac": {
    "bundledSha256": "a1b2c3d4e5f6...",
    "installedAt": "2026-02-19T00:00:00Z",
    "source": "registry",
    "presetApplied": "team-lead-preset"
  }
}
```

```markdown
---
name: openagent
model: claude-sonnet-4-5
maxTokens: 8192
---

# Open Agent

You are OpenAgent, the primary orchestration agent...
[prose content continues]
```

**Design principle**: `prompt.md` YAML frontmatter contains only fields that the IDE (OpenCode) reads natively. All OAC-specific metadata goes in `agent.json`. This avoids frontmatter bloat and keeps IDE compatibility clean.

#### Permission System

The `permission:` field uses **last-match-wins** evaluation (same as OpenCode's native system):

```json
"permission": [
  { "deny": "bash(**)" },          // default deny all bash
  { "allow": "bash(git status)" }, // allow specific git commands
  { "allow": "bash(npm run*)" }    // allow npm run commands
]
```

Rules are evaluated in order; the LAST matching rule wins. This matches OpenCode's permission semantics exactly, ensuring IDE-native compatibility.

#### Preset System

User customizations are stored separately from stock agent files:

```
~/.config/oac/presets/
├── team-lead-preset.json       # User's customizations
└── solo-dev-preset.json

// team-lead-preset.json
{
  "name": "team-lead-preset",
  "appliesTo": ["openagent", "task-manager"],
  "overrides": {
    "model": "claude-opus-4-5",
    "maxTokens": 16384,
    "permission": [
      { "allow": "bash(docker*)" }
    ]
  },
  "promptAppend": "\n\n## Team Context\nAlways consider team conventions..."
}
```

When `oac update` runs:
1. Stock `agent.json` + `prompt.md` are updated from registry
2. Preset is re-applied on top of updated stock
3. Final merged files written to `.opencode/agent/`
4. User never loses customizations

#### Essential Agents

| Agent | Purpose | Critical |
|-------|---------|---------|
| `openagent` | Primary orchestration, plan-first development | Yes |
| `opencoder` | Code implementation | Yes |
| `contextscout` | Context discovery and navigation | Yes |
| `externalscout` | External documentation fetching | Yes |
| `task-manager` | Task breakdown and tracking | Yes |
| `coder-agent` | Focused coding tasks | Yes |

#### Skill Packaging

```
.opencode/skills/task-management/
├── SKILL.md          # Skill definition (YAML frontmatter + prose)
├── router.sh         # Dispatch script (must be fully implemented, not stub)
└── scripts/
    ├── task-cli.js   # COMPILED from task-cli.ts (NOT ts-node)
    └── helpers.js
```

```yaml
# SKILL.md frontmatter
---
name: task-management
version: 1.2.0
description: Task breakdown, tracking, and validation
entrypoint: router.sh
scripts:
  - scripts/task-cli.js
permissions:
  - read: ".tmp/sessions/**"
  - write: ".tmp/sessions/**"
---
```

#### Four Core Skills

| Skill | Status | Critical Gap |
|-------|--------|-------------|
| `task-management` | Mostly complete | `task-cli.ts` must be compiled to JS |
| `context-manager` | router.sh is STUB | Needs full implementation (highest priority) |
| `context7` | Complete | None |
| `smart-router-skill` | Complete | None |

#### CLI Commands

```bash
oac add agent <name>           # Install agent from registry
oac remove agent <name>        # Remove agent
oac list agents                # List installed agents
oac customize agent <name>     # Open editor for agent customization
oac presets list               # List available presets
oac presets apply <preset>     # Apply preset to agents
oac validate agents            # Validate all agent files
oac create agent               # Interactive agent creation wizard

oac skill install <name>       # Install skill from registry
oac skill list                 # List installed skills
oac skill update [name]        # Update skill(s)
oac skill remove <name>        # Remove skill
oac skill validate             # Validate all skills

oac task status                # Show current task session status
oac task next                  # Get next task
oac task complete <id>         # Mark task as complete
```

---

### Subsystem 4: Plugin System

#### Current State

**Two existing plugin systems**:
1. **Claude Code** (`.claude-plugin/`): File-based plugin using `session-start.sh` bash script. Functional but bash-only.
2. **OpenCode** (`packages/plugin-abilities/`): TypeScript event system. Compatibility layer (Phases 1-3) is ~59% complete. CLI integration is missing.

Adapters for Claude, Cursor, and Windsurf exist in `packages/compatibility-layer/` and are functionally complete but have no CLI wiring.

#### Target State

OAC becomes a first-class OpenCode npm plugin registered in `opencode.json`:

```json
// .opencode/opencode.json
{
  "plugin": ["@nextsystems/oac"],
  "model": "claude-sonnet-4-5",
  "theme": "opencode"
}
```

This single line activates the full OAC plugin system including auto-updates on session start.

#### OpenCode Plugin (PRIMARY)

OpenCode offers the richest integration API:
- 25+ lifecycle events (session.created, file.changed, tool.before, tool.after, etc.)
- Custom tool registration
- TypeScript SDK with full type safety
- npm-based distribution (no file copying required)

```typescript
// packages/plugin-abilities/src/index.ts
import type { Plugin } from "@opencode/sdk";
import { handleSessionCreated } from "./events/session";
import { handleToolBefore } from "./events/tools";

export default {
  name: "@nextsystems/oac",
  version: "0.7.1",

  events: {
    "session.created": handleSessionCreated,
    "tool.before": handleToolBefore,
  },

  tools: [
    // Custom OAC tools exposed to the AI
  ],
} satisfies Plugin;
```

```typescript
// packages/plugin-abilities/src/events/session.ts
export async function handleSessionCreated(ctx: SessionContext) {
  // 1. Check for OAC updates
  const updates = await checkForUpdates();

  // 2. Apply safe updates (no user modifications)
  await applySafeUpdates(updates);

  // 3. Notify about skipped updates (user-modified files)
  if (updates.conflicts.length > 0) {
    ctx.notify(`OAC: ${updates.conflicts.length} files have local modifications — run 'oac update' to manage`);
  }

  // 4. Validate active context
  await validateActiveContext(ctx);
}
```

#### Claude Code Plugin (Secondary)

The `.claude-plugin/session-start.sh` needs to be rewritten in TypeScript and compiled:

```
.claude-plugin/
├── plugin.json          # Plugin manifest
├── session-start.js     # Compiled from session-start.ts
└── src/
    └── session-start.ts # TypeScript source
```

```json
// .claude-plugin/plugin.json
{
  "name": "@nextsystems/oac",
  "version": "0.7.1",
  "hooks": {
    "session-start": "node session-start.js"
  }
}
```

#### Cursor Integration

Cursor uses a single `.cursorrules` file (100KB limit). OAC generates this file from installed agents/context:

```bash
oac compat apply --ide=cursor
# Generates .cursorrules with router pattern:
# - Lists available agent personas
# - Includes abbreviated context
# - Stays under 100KB limit
```

#### Windsurf Integration

Windsurf uses `.windsurfrules`. Adapter is functionally complete; needs CLI wiring only.

#### Compatibility Layer CLI (Missing — High Priority)

The compatibility adapters exist but have NO CLI. This must be added:

```bash
oac compat apply --ide=cursor        # Generate cursor-specific files
oac compat apply --ide=claude        # Generate CLAUDE.md etc.
oac compat apply --ide=windsurf      # Generate .windsurfrules
oac compat apply --all               # Apply all compatible IDEs
oac compat status                    # Show compatibility status per IDE
oac compat validate --ide=cursor     # Validate generated files
```

#### Plugin CLI Commands

```bash
oac plugin install <name>            # Install plugin from registry
oac plugin update [name]             # Update plugin(s)
oac plugin remove <name>             # Remove plugin
oac plugin list                      # List installed plugins
oac plugin configure <name>          # Configure plugin settings
oac plugin create                    # Scaffold new plugin
```

---

### Subsystem 5: Registry & Community

#### Current State

`registry.json` exists at the repo root (106KB). It appears to be a flat JSON file. The exact format and whether it follows a published schema is unclear. No community contribution workflow exists. No lockfile system exists.

#### Target State

A shadcn-inspired registry with:
- Typed component entries with SHA256 verification
- `oac.lock` lockfile for reproducible installs
- Community contribution via PR workflow
- Security scanning on all community contributions

#### Registry Item Format

```json
// registry.json
{
  "version": "1",
  "registryUrl": "https://registry.nextsystems.dev/oac",
  "items": [
    {
      "name": "openagent",
      "type": "oac:agent",
      "version": "2.1.0",
      "description": "Primary orchestration agent for plan-first development",
      "tags": ["orchestration", "planning", "primary"],
      "author": "nextsystems",
      "license": "MIT",
      "files": [
        {
          "path": "agent.json",
          "target": ".opencode/agent/openagent/agent.json",
          "url": "https://registry.nextsystems.dev/oac/agents/openagent/2.1.0/agent.json",
          "sha256": "a1b2c3d4..."
        },
        {
          "path": "prompt.md",
          "target": ".opencode/agent/openagent/prompt.md",
          "url": "https://registry.nextsystems.dev/oac/agents/openagent/2.1.0/prompt.md",
          "sha256": "e5f6a7b8..."
        }
      ],
      "dependencies": [],
      "peerDependencies": ["context7"]
    },
    {
      "name": "task-management",
      "type": "oac:skill",
      "version": "1.2.0",
      "files": [
        {
          "path": "SKILL.md",
          "target": ".opencode/skills/task-management/SKILL.md",
          "url": "...",
          "sha256": "..."
        },
        {
          "path": "router.sh",
          "target": ".opencode/skills/task-management/router.sh",
          "url": "...",
          "sha256": "..."
        },
        {
          "path": "scripts/task-cli.js",
          "target": ".opencode/skills/task-management/scripts/task-cli.js",
          "url": "...",
          "sha256": "..."
        }
      ]
    }
  ]
}
```

#### `oac.lock` Format

```json
// oac.lock (committed to git — enables reproducible installs)
{
  "version": "1",
  "generatedAt": "2026-02-19T00:00:00Z",
  "oacVersion": "0.7.1",
  "installed": {
    "agents": {
      "openagent": {
        "version": "2.1.0",
        "source": "registry",
        "sha256": {
          "agent.json": "a1b2c3d4...",
          "prompt.md": "e5f6a7b8..."
        },
        "installedAt": "2026-02-19T00:00:00Z",
        "userModified": {
          "agent.json": false,
          "prompt.md": true
        }
      }
    },
    "skills": {
      "task-management": {
        "version": "1.2.0",
        "source": "registry",
        "sha256": { ... },
        "installedAt": "..."
      }
    },
    "context": {
      "typescript-patterns.md": {
        "version": "1.0.3",
        "source": "bundled",
        "sha256": "...",
        "installedAt": "..."
      }
    }
  }
}
```

#### Directory Ownership (oh-my-zsh Pattern)

```
.opencode/agent/
├── openagent/          # OAC-managed (tracked in oac.lock)
├── task-manager/       # OAC-managed
└── custom/             # USER-OWNED (never touched by oac update)
    └── my-custom-agent/
```

OAC **never** modifies files in `.opencode/agent/custom/` or `.opencode/context/custom/`. This is the clean separation between OAC-managed and user-owned content.

#### CLI Commands

```bash
oac browse                           # TUI browser of registry
oac search <query>                   # Search registry
oac publish <path>                   # Publish to community registry
oac registry add <url>               # Add custom registry source
oac registry list                    # List configured registries
```

---

## 4. Implementation Phases (9 Weeks)

### Phase Overview

```
Week 1-2: Foundation & Package Structure
Week 3:   Context System
Week 4:   Agent & Skill Management
Week 5:   Plugin System (OpenCode primary)
Week 6:   Compatibility Layer CLI
Week 7:   Registry & Lockfile
Week 8:   Auto-Update & Community
Week 9:   Polish, Doctor, Testing
```

---

### Phase 1: Foundation (Week 1-2)

**Goal**: Working CLI binary with package structure. `oac --help` works and shows all commands.

**What Gets Built**:

1. Create `packages/cli/` package
   - `tsconfig.json`, `package.json` with all dependencies
   - `tsup.config.ts` for build
   - `src/index.ts` with commander.js skeleton
   - All command files as stubs (return "not yet implemented")

2. Rewrite `bin/oac.js`
   ```javascript
   #!/usr/bin/env node
   require('../packages/cli/dist/index.js');
   ```

3. Add `packages/cli` to root `workspaces` in `package.json`

4. Configure `tsup` to compile `task-cli.ts` → `task-cli.js`
   - Remove `ts-node` dependency from skills
   - Update `router.sh` references to use compiled `task-cli.js`

5. Set up `vitest` for testing across all packages

6. Create `~/.config/oac/config.json` initialization in `oac init`

**Dependencies**: None (this is the foundation everything else builds on)

**Validation Criteria**:
- `oac --help` lists all planned commands with descriptions
- `oac --version` outputs correct version
- `npx @nextsystems/oac init` runs without error
- All packages build with zero TypeScript errors
- `task-cli.js` executes correctly without `ts-node`

---

### Phase 2: Init & Doctor (Week 2)

**Goal**: `oac init` sets up a project correctly. `oac doctor` diagnoses problems.

**What Gets Built**:

1. `oac init` command (interactive wizard)
   ```
   ? Which IDE are you using? (OpenCode / Claude Code / Cursor / Windsurf / Multiple)
   ? Install standard agent pack? (Yes / No / Select)
   ? Enable auto-updates? (Auto-safe / Auto-all / Manual)
   ? Create .oac/config.json? (Yes)
   ```
   - Creates `.oac/config.json` (project config)
   - Creates `oac.lock` (empty initially)
   - Copies bundled content to `.opencode/`
   - Creates `manifest.json` copy in project
   - Adds entries to `.gitignore` (sessions, tmp)

2. `oac doctor` command
   - Checks: OAC version vs latest
   - Checks: oac.lock exists and is valid
   - Checks: all agents in oac.lock are present on disk
   - Checks: all SHA256s match (detects corruption)
   - Checks: IDE-specific config is correct
   - Checks: `task-cli.js` is compiled (not `.ts`)
   - Checks: context-manager `router.sh` is not a stub
   - Reports: pass/warn/fail per check

**Validation Criteria**:
- `oac init` completes in < 30 seconds on first run
- `oac doctor` correctly identifies a deliberately broken install
- `oac doctor --fix` auto-repairs fixable issues

---

### Phase 3: Context System (Week 3)

**Goal**: Full context system with 6-layer resolution and CLI management.

**What Gets Built**:

1. `ContextResolver` class implementing 6-layer resolution
2. `oac context list` — shows all context with source layer
3. `oac context resolve <name>` — shows which layer wins
4. `oac context install <name>` — installs specific context file
5. `oac context update` — updates all OAC-managed context
6. `oac context validate` — validates syntax
7. `oac context diff <name>` — diff vs stock version

**Context Resolver Implementation**:

```typescript
// packages/cli/src/resolvers/context.ts
const RESOLUTION_LAYERS = [
  { name: "project-override",  path: ".oac/context",                    userOwned: true },
  { name: "opencode-config",   path: ".opencode/context",               userOwned: false },
  { name: "ide-specific",      path: ".cursor/context",                  userOwned: false },
  { name: "project-docs",      path: "docs",                            userOwned: true },
  { name: "user-global",       path: "~/.config/oac/context",           userOwned: true },
  { name: "npm-bundled",       path: "__dirname/../../.opencode/context", userOwned: false },
];

export async function resolveContext(name: string): Promise<ResolvedContext> {
  for (const layer of RESOLUTION_LAYERS) {
    const filePath = join(layer.path, name);
    if (await exists(filePath)) {
      return { filePath, layer, userOwned: layer.userOwned };
    }
  }
  throw new Error(`Context file not found: ${name}`);
}
```

**Validation Criteria**:
- `oac context list` shows correct source layer for each file
- Updating a user-modified file is blocked/warned
- `oac context resolve` output matches manual file system inspection

---

### Phase 4: Agent & Skill Management (Week 4)

**Goal**: Full agent and skill lifecycle management. Preset system working.

**What Gets Built**:

1. `agent.json` schema with Zod validation
2. `oac add agent <name>` — install from registry
3. `oac remove agent <name>` — remove with confirmation
4. `oac list agents` — tabular view with versions
5. `oac customize agent <name>` — opens editor, saves to preset
6. `oac presets list/apply` — preset management
7. `oac validate agents` — schema validation
8. **Fix context-manager router.sh stub** — implement full dispatch logic
9. `oac skill install/list/update/remove/validate`

**Agent Schema (Zod)**:

```typescript
// packages/cli/src/schemas/agent.ts
const AgentSchema = z.object({
  name: z.string().regex(/^[a-z][a-z0-9-]*$/),
  displayName: z.string(),
  version: z.string(),
  description: z.string(),
  model: z.string().optional(),
  maxTokens: z.number().optional(),
  permission: z.array(z.union([
    z.object({ allow: z.string() }),
    z.object({ deny: z.string() }),
  ])).optional(),
  tools: z.array(z.string()).optional(),
  tags: z.array(z.string()).default([]),
  oac: z.object({
    bundledSha256: z.string(),
    installedAt: z.string(),
    source: z.enum(["registry", "bundled", "local"]),
    presetApplied: z.string().optional(),
  }).optional(),
});
```

**context-manager router.sh** (critical gap fix):

```bash
#!/usr/bin/env bash
# router.sh — context-manager skill dispatcher
set -euo pipefail

COMMAND="${1:-help}"
SCRIPTS_DIR="$(dirname "$0")/scripts"

case "$COMMAND" in
  discover)    node "$SCRIPTS_DIR/discover.js" "${@:2}" ;;
  fetch)       node "$SCRIPTS_DIR/fetch.js" "${@:2}" ;;
  harvest)     node "$SCRIPTS_DIR/harvest.js" "${@:2}" ;;
  extract)     node "$SCRIPTS_DIR/extract.js" "${@:2}" ;;
  compress)    node "$SCRIPTS_DIR/compress.js" "${@:2}" ;;
  organize)    node "$SCRIPTS_DIR/organize.js" "${@:2}" ;;
  cleanup)     node "$SCRIPTS_DIR/cleanup.js" "${@:2}" ;;
  workflow)    node "$SCRIPTS_DIR/workflow.js" "${@:2}" ;;
  *)           echo "Usage: router.sh <discover|fetch|harvest|extract|compress|organize|cleanup|workflow>"; exit 1 ;;
esac
```

**Validation Criteria**:
- `oac add agent openagent` installs correctly and updates `oac.lock`
- `oac customize agent openagent` opens editor and saves preset
- After `oac update`, customizations survive
- `oac validate agents` catches malformed `agent.json`
- context-manager `router.sh` dispatches all 8 commands correctly

---

### Phase 5: OpenCode Plugin (Week 5)

**Goal**: OAC registers as an OpenCode npm plugin. Auto-update works on session start.

**What Gets Built**:

1. Complete `packages/plugin-abilities/src/index.ts` as a proper OpenCode plugin
2. `session.created` event handler with update check logic
3. Register in `.opencode/opencode.json` as `"plugin": ["@nextsystems/oac"]`
4. Session management CLI: `oac session list/clean`

**OpenCode Plugin Registration**:

```json
// .opencode/opencode.json (updated)
{
  "plugin": ["@nextsystems/oac"],
  "model": "claude-sonnet-4-5",
  "theme": "opencode"
}
```

**Session Created Handler**:

```typescript
// packages/plugin-abilities/src/events/session.ts
import { checkForUpdates, applySafeUpdates } from "../updater";
import { readLockfile } from "../lockfile";

export async function handleSessionCreated(ctx: SessionContext) {
  try {
    const lockfile = await readLockfile();
    const updates = await checkForUpdates(lockfile);

    if (updates.safe.length > 0) {
      await applySafeUpdates(updates.safe);
      // Silent — don't interrupt the user's session
    }

    if (updates.conflicts.length > 0 && !lockfile.config.suppressConflictWarnings) {
      ctx.log.warn(
        `OAC: ${updates.conflicts.length} components have updates but local modifications. ` +
        `Run 'oac update --interactive' to manage.`
      );
    }
  } catch (err) {
    // Never crash the user's session due to OAC errors
    ctx.log.debug(`OAC update check failed: ${err.message}`);
  }
}
```

**Validation Criteria**:
- OpenCode loads `@nextsystems/oac` plugin without error
- `session.created` fires and completes without affecting session start time > 500ms
- Auto-update correctly identifies modified files and skips them
- Plugin unloads cleanly when removed from `opencode.json`

---

### Phase 6: Compatibility Layer CLI (Week 6)

**Goal**: All existing compatibility adapters (Claude, Cursor, Windsurf) wired to CLI commands.

**What Gets Built**:

1. `oac compat apply --ide=<ide>` command wiring to existing adapters
2. `oac compat status` — show what's generated for each IDE
3. `oac compat validate --ide=<ide>` — validate generated files
4. Claude Code plugin: rewrite `session-start.sh` → `session-start.ts` → compile to `session-start.js`
5. Cursor: enforce 100KB limit in generator, warn if exceeded

**Compat Apply Implementation**:

```typescript
// packages/cli/src/commands/compat.ts
import { ClaudeAdapter } from "@nextsystems/oac-compatibility-layer";
import { CursorAdapter } from "@nextsystems/oac-compatibility-layer";
import { WindsurfAdapter } from "@nextsystems/oac-compatibility-layer";

export const compatApplyCommand = new Command("apply")
  .option("--ide <ide>", "target IDE (claude|cursor|windsurf|all)")
  .option("--dry-run", "show what would be generated without writing")
  .action(async (options) => {
    const agents = await loadInstalledAgents();
    const context = await loadInstalledContext();

    const adapters = resolveAdapters(options.ide);
    for (const adapter of adapters) {
      const output = await adapter.generate({ agents, context });
      if (!options.dryRun) {
        await adapter.write(output);
      }
      console.log(`Generated ${adapter.name} files`);
    }
  });
```

**Validation Criteria**:
- `oac compat apply --all` runs without error with a fresh install
- Cursor output stays under 100KB
- Claude Code `session-start.js` runs without `ts-node`
- `oac compat status` correctly shows missing/present/outdated state

---

### Phase 7: Registry & Lockfile (Week 7)

**Goal**: Full registry client with lockfile. `oac add` fetches from registry and records in lock.

**What Gets Built**:

1. Registry client with SHA256 verification
2. `oac.lock` read/write with atomic updates
3. `oac add` fetches from registry, verifies hash, writes to disk, updates lock
4. `oac remove` removes files and updates lock
5. `oac browse` TUI browser of registry items
6. `oac search <query>` search registry

**Registry Client**:

```typescript
// packages/cli/src/registry/client.ts
export class RegistryClient {
  async fetch(name: string, type: OACItemType): Promise<RegistryItem> {
    const url = `${this.baseUrl}/${type}s/${name}`;
    const item = await fetch(url).then(r => r.json());
    return RegistryItemSchema.parse(item);
  }

  async download(item: RegistryItem): Promise<DownloadedFiles> {
    const files = await Promise.all(
      item.files.map(async (f) => {
        const content = await fetch(f.url).then(r => r.text());
        const sha256 = await computeSHA256(content);
        if (sha256 !== f.sha256) {
          throw new Error(`SHA256 mismatch for ${f.path}: expected ${f.sha256}, got ${sha256}`);
        }
        return { ...f, content };
      })
    );
    return files;
  }
}
```

**Atomic Lockfile Updates**:

```typescript
// packages/cli/src/registry/lockfile.ts
export async function updateLockfile(
  lockfilePath: string,
  updates: LockfileUpdate[]
): Promise<void> {
  const tmpPath = lockfilePath + ".tmp";
  const lock = await readLockfile(lockfilePath);
  for (const update of updates) {
    applyUpdate(lock, update);
  }
  await writeFile(tmpPath, JSON.stringify(lock, null, 2));
  await rename(tmpPath, lockfilePath); // Atomic rename
}
```

**Validation Criteria**:
- `oac add agent openagent` downloads, verifies SHA256, installs, updates `oac.lock`
- Corrupted download (wrong SHA256) is rejected with clear error
- `oac.lock` is valid JSON after every operation
- `oac remove agent openagent` removes files and updates `oac.lock`

---

### Phase 8: Auto-Update & Community (Week 8)

**Goal**: Background update checking, conflict resolution, community publish workflow.

**What Gets Built**:

1. `update-notifier` integration for CLI binary updates
2. Registry polling with configurable interval
3. `oac update` with `--interactive` conflict resolution
4. `oac rollback <component>` to previous version
5. `oac publish` workflow for community contributions
6. Update modes: `manual` / `auto-safe` / `auto-all` / `locked`

**Update Modes**:

```typescript
type UpdateMode = 
  | "manual"      // Never auto-update, always prompt
  | "auto-safe"   // Auto-update files with no local modifications
  | "auto-all"    // Auto-update everything, backup modifications
  | "locked"      // Never update, lock.json is authoritative
```

**Rollback**:

```typescript
// oac rollback openagent
// Reads previous version from lock history
// Fetches from registry at pinned version
// Restores files + updates lock
```

**Validation Criteria**:
- `update-notifier` shows update message when newer CLI version available
- `oac update --interactive` correctly shows diffs and prompts for each conflict
- `oac rollback openagent` restores previous version
- Update mode `auto-safe` correctly skips user-modified files
- Update mode `auto-all` creates backup before overwriting

---

### Phase 9: Polish & Testing (Week 9)

**Goal**: Production-ready package with comprehensive test coverage and documentation.

**What Gets Built**:

1. Unit tests for all core functionality (vitest)
2. Integration tests for CLI commands
3. End-to-end test: fresh install → configure → update cycle
4. `oac doctor` covers all known failure modes
5. Performance: measure and optimize `session.created` handler
6. README and getting-started guide updates
7. Deprecation of `install.sh` with migration notice

**Test Coverage Targets**:
- Unit tests: ≥ 80% coverage on `packages/cli/src/`
- Integration tests: all 20+ commands
- E2E test: full install/update/rollback cycle

**Validation Criteria**:
- All tests pass on macOS, Linux, Windows (via GitHub Actions)
- `oac init` completes in < 2 minutes on fresh machine
- `session.created` handler adds < 500ms to session start
- `oac doctor` passes on a correct install

---

## 5. Key Technical Decisions

### Decision 1: OpenCode as Primary Target

**Rationale**: OpenCode offers a TypeScript plugin SDK with 25+ lifecycle events, custom tool registration, and npm-based distribution. This is the richest integration model available among the four IDEs. By targeting OpenCode first, we get:
- Auto-update on every session start (via `session.created`)
- Type-safe plugin development
- Zero file-copying for plugin distribution (npm handles it)
- Future access to new OpenCode capabilities as they're released

Claude Code, Cursor, and Windsurf are adaptation layers — we write once for OpenCode and adapt for others.

### Decision 2: Bundle Context into npm (Not Fetch at Runtime)

**Rationale**: Context files are needed the moment an AI session starts. A network fetch at that moment creates:
- Latency (adds delay to every session)
- Network dependency (fails offline, in CI, on slow connections)
- Version drift (server updates mid-session)

By bundling context into the npm package, we get zero-latency access, offline functionality, and version-locked reproducibility. The `manifest.json` + SHA256 system handles update detection separately from file delivery.

### Decision 3: `agent.json` + `prompt.md` Separation

**Rationale**: Separating metadata from prose has three benefits:
1. **Diffability**: `agent.json` changes (model, permissions) are clearly separated from prompt content changes — easier to review in PRs
2. **IDE compatibility**: `prompt.md` frontmatter contains only fields OpenCode reads natively. OAC metadata in `agent.json` doesn't pollute the frontmatter
3. **Preset application**: Presets can override specific `agent.json` fields without touching `prompt.md`, and vice versa

### Decision 4: shadcn Registry Pattern

**Rationale**: shadcn demonstrated that a file-copy registry model is superior to package-per-component for configuration files. Benefits:
- Users own their copies — they can modify them freely
- No npm install needed to add an agent/skill/context file
- SHA256 verification provides security without requiring a signing infrastructure
- Community can contribute by PR to `registry.json`

The `oac.lock` lockfile extends this pattern with version pinning and reproducibility.

### Decision 5: Backward Compatibility Strategy

During the 9-week transition:
- `install.sh` continues to work but shows a deprecation notice
- `bin/oac.js` is backward compatible — no arguments → runs equivalent of old behavior
- All files installed by old `install.sh` remain valid; `oac doctor` can adopt them into `oac.lock`
- `oac init --import` scans existing `.opencode/` and creates `oac.lock` from discovered files

---

## 6. Critical Gaps to Address

These are gaps that will break functionality if not addressed before launch. Ordered by priority.

### Gap 1: context-manager router.sh is a STUB (P0)

**Current state**: `router.sh` in `.opencode/skills/context-manager/` exists but dispatches nothing.  
**Impact**: The context-manager skill is completely non-functional.  
**Fix**: Implement full dispatch logic to 8 subcommands (see Phase 4 above).  
**Owner**: Phase 4, Week 4.

### Gap 2: task-cli.ts requires ts-node (P0)

**Current state**: `task-cli.ts` is invoked directly via `ts-node` in `router.sh`.  
**Impact**: Breaks in any environment without `ts-node` (most production setups).  
**Fix**: Compile `task-cli.ts` → `task-cli.js` via `tsup` in the build pipeline. Update `router.sh` to call `node task-cli.js`.  
**Owner**: Phase 1, Week 1.

### Gap 3: Compatibility Layer has no CLI (P1)

**Current state**: `packages/compatibility-layer/` adapters are functionally complete but have zero CLI exposure.  
**Impact**: Multi-IDE users cannot generate Claude/Cursor/Windsurf files via `oac` commands.  
**Fix**: Wire adapters to `oac compat apply` command (Phase 6, Week 6).  
**Owner**: Phase 6, Week 6.

### Gap 4: OpenCode plugin does not exist as a proper plugin (P1)

**Current state**: `packages/plugin-abilities/` has event handler stubs but is not registered in `opencode.json` as a proper plugin.  
**Impact**: Auto-update via `session.created` does not fire.  
**Fix**: Complete plugin-abilities implementation and add to `opencode.json` plugin array.  
**Owner**: Phase 5, Week 5.

### Gap 5: No lockfile system (P1)

**Current state**: Installed components are not tracked. No reproducibility.  
**Impact**: Teams cannot share exact installs. Updates cannot detect user modifications.  
**Fix**: Implement `oac.lock` with atomic read/write (Phase 7, Week 7).  
**Owner**: Phase 7, Week 7.

### Gap 6: Full CLI does not exist (P0 — foundation)

**Current state**: `bin/oac.js` is 91 lines that spawns `install.sh`.  
**Impact**: Everything depends on this being fixed.  
**Fix**: Create `packages/cli/` and rewrite `bin/oac.js` (Phase 1, Week 1-2).  
**Owner**: Phase 1, Week 1.

### Gap 7: No test infrastructure (P2)

**Current state**: No tests exist anywhere in the codebase.  
**Impact**: Regressions will go undetected. Cannot validate fixes.  
**Fix**: Set up vitest in Phase 1, write tests progressively through Phases 2-9.  
**Owner**: Phase 1 (setup) + ongoing.

---

## 7. Configuration Schema

### Global Config: `~/.config/oac/config.json`

```json
{
  "$schema": "https://registry.nextsystems.dev/oac/schemas/global-config.json",
  "version": "1",
  "defaults": {
    "ide": "opencode",
    "updateMode": "auto-safe",
    "registry": "https://registry.nextsystems.dev/oac",
    "telemetry": false
  },
  "presets": {
    "default": "~/.config/oac/presets/default.json"
  },
  "auth": {
    "registryToken": null
  }
}
```

**`updateMode` values**:
- `"manual"` — Never auto-update. Run `oac update` explicitly.
- `"auto-safe"` — Auto-update only files matching stock SHA256 (default).
- `"auto-all"` — Auto-update everything. Creates `.oac/backups/` before overwriting.
- `"locked"` — Never update. `oac.lock` is authoritative.

### Project Config: `.oac/config.json`

```json
{
  "$schema": "https://registry.nextsystems.dev/oac/schemas/project-config.json",
  "version": "1",
  "project": {
    "name": "my-project",
    "ide": "opencode",
    "updateMode": "auto-safe"
  },
  "agents": {
    "enabled": ["openagent", "task-manager", "contextscout"],
    "disabled": []
  },
  "context": {
    "enabled": ["typescript-patterns", "git-workflow"],
    "disabled": []
  },
  "skills": {
    "enabled": ["task-management", "context-manager", "context7"],
    "disabled": []
  },
  "compatibility": {
    "cursor": { "enabled": true, "autoRegenerate": true },
    "claude": { "enabled": true, "autoRegenerate": false },
    "windsurf": { "enabled": false }
  }
}
```

### `oac.lock` Format

```json
{
  "$schema": "https://registry.nextsystems.dev/oac/schemas/lockfile.json",
  "version": "1",
  "generatedAt": "2026-02-19T00:00:00Z",
  "oacVersion": "0.7.1",
  "installed": {
    "agents": {
      "<name>": {
        "version": "<semver>",
        "source": "registry | bundled | local",
        "registryUrl": "<url>",
        "sha256": {
          "<filename>": "<sha256>"
        },
        "installedAt": "<iso8601>",
        "updatedAt": "<iso8601>",
        "userModified": {
          "<filename>": true | false
        },
        "presetApplied": "<preset-name> | null"
      }
    },
    "skills": { "<same shape>" },
    "context": { "<same shape>" },
    "plugins": { "<same shape>" }
  },
  "history": [
    {
      "action": "add | update | remove | rollback",
      "component": "<type>/<name>",
      "fromVersion": "<semver> | null",
      "toVersion": "<semver>",
      "timestamp": "<iso8601>"
    }
  ]
}
```

### OAC Component Manifest: `manifest.json`

```json
{
  "$schema": "https://registry.nextsystems.dev/oac/schemas/manifest.json",
  "version": "1",
  "packageVersion": "0.7.1",
  "generatedAt": "2026-02-19T00:00:00Z",
  "agents": {
    "<name>": {
      "version": "<semver>",
      "description": "<string>",
      "files": {
        "<filename>": {
          "sha256": "<sha256>",
          "size": 4821
        }
      }
    }
  },
  "skills": { "<same shape>" },
  "context": {
    "<filename>": {
      "version": "<semver>",
      "sha256": "<sha256>",
      "size": 2341,
      "category": "language | workflow | tooling | project"
    }
  }
}
```

---

## 8. Auto-Update Strategy

### Two-Layer Update System

**Layer 1: CLI Binary Updates** (via `update-notifier`)

```typescript
// packages/cli/src/index.ts
import updateNotifier from "update-notifier";
import packageJson from "../../package.json";

const notifier = updateNotifier({
  pkg: packageJson,
  updateCheckInterval: 1000 * 60 * 60 * 24, // Check daily
});

// Non-blocking: shows notification at end of command
notifier.notify();
```

**Layer 2: Content File Updates** (hash-based registry polling)

```
Content update check flow:

1. Read oac.lock (installed versions + sha256)
2. Fetch registry manifest (latest versions + sha256)
3. For each installed component:
   a. Compare installed version vs registry version (semver)
   b. If newer version available:
      i.  Compute SHA256 of file on disk
      ii. Compare to oac.lock sha256 for that file
          MATCH  → file is stock OAC → SAFE TO UPDATE
          DIFFER → file has user modifications → RESPECT updateMode
4. Apply updates according to updateMode
5. Update oac.lock
```

### Hash-Based Conflict Detection

The SHA256 stored in `oac.lock` is the hash of the file **as installed from the registry**, not the current file on disk. This allows detection of user modifications:

```typescript
async function detectModification(
  installedPath: string,
  lockEntry: LockfileEntry
): Promise<boolean> {
  const currentContent = await readFile(installedPath);
  const currentSha256 = await sha256(currentContent);
  const installedSha256 = lockEntry.sha256[basename(installedPath)];
  return currentSha256 !== installedSha256;
}
```

### User-Owned vs OAC-Managed Files

```
OAC-MANAGED (tracked in oac.lock, updated by oac update):
  .opencode/agent/<name>/          (standard agents)
  .opencode/context/<name>.md     (standard context)
  .opencode/skills/<name>/         (standard skills)

USER-OWNED (never touched by oac update):
  .opencode/agent/custom/          (user's custom agents)
  .opencode/context/custom/        (user's custom context)
  .oac/context/                    (project overrides, highest priority)
  docs/                            (project documentation)
  ~/.config/oac/presets/           (user presets)
```

### Update Modes in Detail

| Mode | Behavior | Best For |
|------|----------|---------|
| `manual` | Never updates automatically. Must run `oac update` | Teams with strict change control |
| `auto-safe` | Updates only files with SHA256 matching oac.lock (default) | Solo developers, most teams |
| `auto-all` | Updates everything; backs up modified files to `.oac/backups/` | Users who want always-latest |
| `locked` | Ignores registry. oac.lock is authoritative. | CI/CD, reproducible builds |

### Update in OpenCode Plugin

```typescript
// Runs on every session.created — must be fast
export async function handleSessionCreated(ctx: SessionContext) {
  const updateMode = await getUpdateMode();
  if (updateMode === "locked") return; // Fast exit for locked mode

  const check = await checkUpdatesWithTimeout(5000); // 5s timeout
  if (!check) return; // Network unavailable — skip silently

  if (check.safeUpdates.length > 0 && updateMode !== "manual") {
    await applySafeUpdates(check.safeUpdates); // Unmodified files
  }

  if (check.conflicts.length > 0) {
    ctx.log.info(`OAC: ${check.conflicts.length} updates available (run 'oac update')`);
  }
}
```

---

## 9. CLI Command Reference

### Core Commands

```bash
oac init [--ide <ide>] [--no-agents] [--no-context] [--yolo]
  Initialize OAC in the current project. Interactive wizard by default.
  Creates: .oac/config.json, oac.lock, copies bundled content

oac add <type> <name> [--version <semver>] [--yolo]
  Install a component from the registry.
  Types: agent, skill, context, plugin
  Example: oac add agent openagent

oac remove <type> <name> [--yolo]
  Remove an installed component.
  Example: oac remove agent openagent

oac update [type] [name] [--interactive] [--dry-run] [--yolo]
  Update installed components. Without args, updates all safe components.
  --interactive: prompts for each conflict
  --dry-run: shows what would be updated without making changes

oac list [type] [--format table|json]
  List installed components with versions and modification status.
  Example: oac list agents

oac doctor [--fix]
  Diagnose installation issues. --fix auto-repairs fixable issues.

oac rollback <type> <name> [--version <semver>]
  Rollback a component to a previous version.
  Example: oac rollback agent openagent --version 2.0.0
```

### Context Commands

```bash
oac context install <name>
  Install a specific context file from the registry.

oac context update [name]
  Update context file(s). Without name, updates all safe context.

oac context list [--format table|json]
  List installed context files with source layer.

oac context resolve <name>
  Show which resolution layer provides a context file.

oac context validate [name]
  Validate context file syntax and frontmatter.

oac context diff <name>
  Show diff between installed file and stock (registry) version.
```

### Agent Commands

```bash
oac add agent <name>              # Install from registry
oac remove agent <name>           # Remove agent
oac list agents                   # List with versions and status
oac customize agent <name>        # Open editor, save as preset
oac validate agents [name]        # Validate agent.json schema
oac create agent                  # Interactive creation wizard
oac show agent <name>             # Show agent configuration

oac presets list                  # List available presets
oac presets apply <preset> [agents...]   # Apply preset to agents
oac presets create <name>         # Create preset from current customizations
oac presets remove <name>         # Delete preset
```

### Skill Commands

```bash
oac skill install <name>          # Install skill from registry
oac skill update [name]           # Update skill(s)
oac skill remove <name>           # Remove skill
oac skill list                    # List installed skills
oac skill validate [name]         # Validate SKILL.md and router.sh
oac skill run <name> <command>    # Run skill command directly

oac task status                   # Show current task session
oac task next                     # Get next task from session
oac task complete <id>            # Mark task as complete
oac task session list             # List task sessions
oac task session clean [--older-than <days>]  # Clean old sessions
```

### Plugin Commands

```bash
oac plugin install <name>         # Install plugin from registry
oac plugin update [name]          # Update plugin(s)
oac plugin remove <name>          # Remove plugin
oac plugin list                   # List installed plugins
oac plugin configure <name>       # Configure plugin settings
oac plugin create                 # Scaffold new plugin
```

### Compatibility Commands

```bash
oac compat apply [--ide <ide>] [--all] [--dry-run]
  Generate IDE-specific files from installed agents/context.
  IDEs: cursor, claude, windsurf
  Example: oac compat apply --ide cursor

oac compat status
  Show compatibility file status for each supported IDE.

oac compat validate [--ide <ide>]
  Validate generated compatibility files.

oac compat clean [--ide <ide>]
  Remove generated compatibility files.
```

### Registry Commands

```bash
oac browse [type]                 # TUI browser of registry
oac search <query> [--type <type>]  # Search registry
oac publish <path>                # Publish component to community registry
oac registry add <url>            # Add custom registry source
oac registry remove <url>         # Remove custom registry
oac registry list                 # List configured registries
oac registry status               # Check registry connectivity
```

### Configuration Commands

```bash
oac configure                     # Interactive config editor
oac configure get <key>           # Get config value
oac configure set <key> <value>   # Set config value
oac configure reset               # Reset to defaults

oac show [type] [name]            # Show details of installed component
oac edit [type] [name]            # Open component in $EDITOR
```

### Global Flags

```bash
--yolo                  # Skip all confirmations
--no-color              # Disable color output
--quiet                 # Minimal output
--verbose               # Verbose output
--debug                 # Debug output with stack traces
--json                  # Output as JSON (machine-readable)
--config <path>         # Use alternate config file
--registry <url>        # Use alternate registry URL
```

---

## 10. Success Metrics

### Technical Metrics

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| Test coverage | ≥ 80% on `packages/cli/src/` | vitest coverage |
| Build time | < 30 seconds for full build | `time npm run build` |
| CLI startup time | < 200ms for `oac --version` | `time oac --version` |
| `oac init` time | < 2 minutes on fresh machine | Manual timing |
| `session.created` overhead | < 500ms | OpenCode plugin timing |
| Bundle size | < 5MB total npm package | `npm pack --dry-run` |
| TypeScript errors | 0 errors on `tsc --noEmit` | CI check |
| Zero bash dependencies | `oac` commands work without bash | Test on fresh Windows VM |

### User Experience Metrics

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| Setup time (solo dev) | < 2 minutes from `npx @nextsystems/oac init` to working | User testing |
| Update friction | Zero prompts in `auto-safe` mode | Automated test |
| Customization survival rate | 100% presets survive `oac update` | Integration test |
| `oac doctor` detection rate | 100% of documented failure modes | Test against each failure mode |
| Rollback reliability | `oac rollback` succeeds 100% if oac.lock is present | Integration test |

### Community Adoption Metrics (6-month targets)

| Metric | Target |
|--------|--------|
| npm weekly downloads | > 1,000 |
| Community registry contributions | > 10 agents/skills submitted |
| GitHub issues: "broken install" | < 5% of total issues |
| `oac doctor --fix` auto-repair success rate | > 90% |
| Multi-IDE users | > 20% of users run `oac compat apply` |

### Migration Metrics

| Metric | Target |
|--------|--------|
| `install.sh` usage | < 20% of installs by Week 9 |
| Users successfully migrated via `oac init --import` | > 80% |
| Regressions reported after migration | 0 P0/P1 bugs |

---

## Appendix A: File Naming Conventions

```
Agents:   .opencode/agent/<name>/agent.json + prompt.md
Skills:   .opencode/skills/<name>/SKILL.md + router.sh + scripts/*.js
Context:  .opencode/context/<name>.md
Plugins:  packages/plugin-abilities/ (OpenCode) | .claude-plugin/ (Claude Code)
Config:   .oac/config.json (project) | ~/.config/oac/config.json (global)
Lock:     oac.lock (project root, commit to git)
Manifest: manifest.json (project root, commit to git)
Backups:  .oac/backups/<timestamp>/<component>/ (git-ignored)
Sessions: .tmp/sessions/ (git-ignored)
Presets:  ~/.config/oac/presets/<name>.json (survives npm updates)
```

## Appendix B: Dependency Rationale

| Package | Purpose | Why Not Alternative |
|---------|---------|---------------------|
| `commander` | CLI framework | Battle-tested, good TypeScript support. Yargs has more complex API. |
| `@inquirer/prompts` | Interactive prompts | Official Inquirer v9 rewrite, modular. Better than `enquirer` |
| `ora` | Spinners | Standard, well-maintained |
| `chalk` | Colors | Standard, ESM-compatible v5 |
| `conf` | Global config persistence | OS-correct paths, handles JSON schema |
| `fs-extra` | File operations | Adds `copy`, `ensureDir`, `readJSON` etc. Better than raw `fs` |
| `semver` | Version comparison | npm's own semver library, authoritative |
| `zod` | Schema validation | Best TypeScript DX, composable schemas |
| `update-notifier` | CLI update notifications | Non-blocking background check |
| `tsup` | Build tool | Bundles deps, fast, simple config |
| `vitest` | Testing | Fast, native ESM, compatible with tsup |

## Appendix C: Migration Path from install.sh

```bash
# Old workflow:
curl -fsSL https://install.nextsystems.dev/oac | bash

# New workflow (v1.0):
npx @nextsystems/oac init

# For existing users:
oac init --import          # Scans .opencode/ and creates oac.lock
oac doctor                 # Validates the import
oac compat apply --all     # Regenerates IDE-specific files

# install.sh shows deprecation notice but continues to work:
echo "DEPRECATED: install.sh will be removed in v2.0. Run: npx @nextsystems/oac init"
```

---

*Document status: Authoritative master plan. All implementation decisions should reference this document. Update this document when architectural decisions change.*

*Next action: Begin Phase 1 — create `packages/cli/` package structure and rewrite `bin/oac.js`.*