@fro.bot/systematic 2.20.5 → 2.21.0

package/README.md

@@ -15,520 +15,60 @@
 
 <br>
 
-**[Overview](#overview)** · **[Quick Start](#quick-start)** · **[Skills](#skills)** · **[Agents](#agents)** · **[CLI](#cli)** · **[Configuration](#configuration)** · **[Development](#development)**
+**[Docs](https://fro.bot/systematic/)** · **[npm](https://www.npmjs.com/package/@fro.bot/systematic)** · **[GitHub](https://github.com/marcusrbrown/systematic)**
 
 </div>
 
 ---
 
-## Overview
+AI coding tools are fast at generating code, but they don't preserve engineering discipline by default. They skip planning, forget standards, miss review steps, and fail to capture what was learned. Systematic exists to turn those one-off interactions into a repeatable workflow.
 
-Systematic is an [OpenCode](https://opencode.ai/) plugin that transforms your AI assistant into a **disciplined engineering collaborator**. It provides battle-tested workflows adapted from the [Compound Engineering Plugin (CEP)](https://github.com/EveryInc/compound-engineering-plugin) for Claude Code.
+## Why Systematic?
 
-### Why Systematic?
+You want AI that follows your process, not just your prompts. You want repeatable engineering habits encoded into the environment. You want the system to get better after each task.
 
-Most AI coding assistants respond to requests without structure or methodology. This leads to inconsistent outputs, missed requirements, and wasted iterations.
+## What You Get
 
-**Systematic solves this with structured workflows.** Installation is the first step to equipping your AI with high-leverage engineering habits. Once installed, the plugin injects proven processes directly into the system prompt, enabling it to:
+Systematic is an [OpenCode](https://opencode.ai/) plugin that ships 40+ bundled skills covering brainstorming, planning, implementation, review, and knowledge capture. It includes 50+ specialized agents for architecture, security, performance, design, and code review. Installation is zero-configuration — the plugin registers everything via OpenCode's config hooks and works immediately on restart. OCX registry support is available for component-level installs when you only want specific pieces.
 
-- **Brainstorm systematically** before jumping to implementation
-- **Plan with rigor** using multi-phase workflows
-- **Review code architecturally** with specialized agents
-- **Follow consistent patterns** across your entire team
+## Quick Install
 
-### Key Features
-
-- **Structured Skills** — Pre-built workflows for brainstorming, planning, code review, and more
-- **Specialized Agents** — Purpose-built subagents for architecture, security, performance, and research
-- **Zero Configuration** — Works immediately after installation via config hooks
-- **Extensible** — Add project-specific skills and agents alongside bundled ones
-- **Batteries Included** — a curated catalog of skills and agents ships with the npm package
-- **CLI Tooling** — Inspect, list, and convert assets from the command line
-
-## Quick Start
-
-### Prerequisites
-
-- [OpenCode](https://opencode.ai/) installed and configured
-- Node.js 18+ or Bun runtime
-
-### Installation
-
-Install the plugin by adding it to your OpenCode configuration (`~/.config/opencode/opencode.json`):
+Add to your `opencode.json` and restart OpenCode:
 
 ```json
-{
-  "plugins": ["@fro.bot/systematic@latest"]
-}
-```
-
-Restart OpenCode to activate the plugin. All bundled skills and agents will be available immediately.
-
-> [!NOTE]
-> Systematic uses OpenCode's `config` hook to automatically register all bundled content. No manual file copying required.
-
-### Alternative: Install via OCX
-
-[OCX](https://github.com/kdcokenny/ocx) provides component-level installation:
-
-```bash
-# Add the Systematic registry
-ocx registry add https://fro.bot/systematic --name systematic
-
-# Install individual components
-ocx add systematic/using-systematic
-ocx add systematic/agent-architecture-strategist
-
-# Or install bundles
-ocx add systematic/skills     # All bundled skills
-ocx add systematic/agents     # All bundled agents
-
-# Or use a profile (requires --global registry)
-ocx registry add https://fro.bot/systematic --name systematic --global
-ocx profile add sys --from systematic/standalone
-```
-
-See the [OCX Registry Guide](https://fro.bot/systematic/guides/ocx-registry/) for details.
-
-### Verify Installation
-
-In any OpenCode conversation, type:
-
-```
-/systematic:using-systematic
-```
-
-If the skill loads and displays usage instructions, the plugin is working correctly.
-
-#### Next Steps
-
-Once verified, explore these guides to master the Systematic workflow:
-- **[Philosophy](https://fro.bot/systematic/guides/philosophy/)** — Understand the Compound Engineering mindset and why it works
-- **[Main Loop](https://fro.bot/systematic/guides/main-loop/)** — Learn the Plan → Work → Review → Compound cycle
-- **[Agent Install Guide](https://fro.bot/systematic/guides/agent-install/)** — Step-by-step install guide for AI agents
-
-## Skills
-
-Skills are structured workflows that guide the AI through systematic engineering processes. They're loaded via the `systematic_skill` tool and invocable as slash commands (e.g., `/ce:brainstorm`).
-
-### Core Workflows
-
-The Compound Engineering loop — the heart of Systematic:
-
-| Skill | Description |
-|-------|-------------|
-| `ce:brainstorm` | Explore requirements through collaborative dialogue before planning |
-| `ce:plan` | Transform feature descriptions into structured implementation plans |
-| `ce:review` | Perform exhaustive code reviews using multi-agent analysis |
-| `ce:work` | Execute work plans efficiently while maintaining quality |
-| `ce:compound` | Document recently solved problems to compound team knowledge |
-| `ce:ideate` | Generate and critically evaluate grounded improvement ideas |
-| `ce:compound-refresh` | Refresh stale learnings and pattern docs against current codebase |
-
-### Development Tools
-
-| Skill | Description |
-|-------|-------------|
-| `using-systematic` | Bootstrap skill — teaches the AI how to discover and use other skills |
-| `agent-browser` | Browser automation using Vercel's agent-browser CLI |
-| `agent-native-architecture` | Design systems where AI agents are first-class citizens |
-| `compound-docs` | Capture solved problems as categorized documentation |
-| `document-review` | Refine requirements or plan documents before proceeding |
-| `deepen-plan` | Enhance a plan with parallel research for each section |
-| `todo-create` · `todo-resolve` · `todo-triage` | Durable file-based todo tracking, triage, and batch resolution |
-| `frontend-design` | Create distinctive, production-grade frontend interfaces |
-| `git-worktree` | Manage git worktrees for isolated parallel development |
-| `generate_command` | Create a new custom slash command following conventions |
-| `orchestrating-swarms` | Coordinate multi-agent swarms and pipeline workflows |
-| `lfg` · `slfg` | Full autonomous engineering workflow (single-agent / swarm) |
-
-### Specialized Skills
-
-| Skill | Description |
-|-------|-------------|
-| `dhh-rails-style` | Write Ruby and Rails code in DHH's distinctive 37signals style |
-| `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's proven patterns |
-| `dspy-ruby` | Build type-safe LLM applications with DSPy.rb |
-| `every-style-editor` | Review and edit copy for style guide compliance |
-| `gemini-imagegen` | Generate and edit images using the Gemini API |
-| `proof` | Create, edit, and share markdown documents via Proof |
-| `rclone` | Upload, sync, and manage files across cloud storage providers |
-
-> **[View all skills →](https://fro.bot/systematic/reference/skills/)**
-
-### How Skills Work
-
-Skills are Markdown files with YAML frontmatter. When loaded, their content is injected into the conversation, guiding the AI's behavior:
-
-```markdown
----
-name: brainstorming
-description: This skill should be used before implementing features...
----
-
-# Brainstorming
-
-This skill provides detailed process knowledge for effective brainstorming...
-```
-
-The AI is instructed to invoke skills **before** taking action — even with a 1% chance a skill might apply.
-
-## Agents
-
-Agents are specialized subagents with pre-configured prompts and expertise. They're registered automatically via the config hook.
-
-### Design Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `design-implementation-reviewer` | Visually compare live UI against Figma designs and report discrepancies |
-| `design-iterator` | Iteratively refine UI design through screenshot-analyze-improve cycles |
-| `figma-design-sync` | Detect and fix visual differences between web implementation and Figma |
-
-### Docs Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `ankane-readme-writer` | Create or update README files following Ankane-style template for Ruby gems |
-
-### Research Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `best-practices-researcher` | Research external best practices, documentation, and examples for any technology |
-| `framework-docs-researcher` | Gather framework documentation and best practices |
-| `git-history-analyzer` | Archaeological analysis of git history to trace code evolution and patterns |
-| `issue-intelligence-analyst` | Analyze GitHub issues to surface recurring themes, pain patterns, and severity trends |
-| `learnings-researcher` | Search past solutions in docs/solutions/ to surface institutional knowledge |
-| `repo-research-analyst` | Research repository structure, documentation, conventions, and implementation patterns |
-
-### Review Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `agent-native-reviewer` | Ensure agent-native parity — any user action should also be available to agents |
-| `architecture-strategist` | Analyze code changes from an architectural perspective |
-| `code-simplicity-reviewer` | Final review pass for simplicity and YAGNI principles |
-| `data-integrity-guardian` | Review database migrations, data models, and persistent data code for safety |
-| `data-migration-expert` | Validate data migrations, backfills, and production data transformations |
-| `deployment-verification-agent` | Produce Go/No-Go deployment checklists with verification queries and rollback procedures |
-| `dhh-rails-reviewer` | Brutally honest Rails code review from DHH's perspective |
-| `julik-frontend-races-reviewer` | Review JavaScript and Stimulus code for race conditions and timing issues |
-| `kieran-python-reviewer` | High quality bar Python review for Pythonic patterns, type safety, and maintainability |
-| `kieran-rails-reviewer` | High quality bar Rails review for conventions, clarity, and maintainability |
-| `kieran-typescript-reviewer` | High quality bar TypeScript review for type safety, modern patterns, and maintainability |
-| `pattern-recognition-specialist` | Detect design patterns, anti-patterns, and code smells |
-| `performance-oracle` | Performance analysis, bottleneck identification, scalability |
-| `schema-drift-detector` | Detect unrelated schema.rb changes by cross-referencing against included migrations |
-| `security-sentinel` | Security audits, vulnerability assessment, OWASP compliance |
-
-### Workflow Agents
-
-| Agent | Purpose |
-|-------|---------|
-| `bug-reproduction-validator` | Systematically verify and reproduce reported bugs |
-| `lint` | Run linting and code quality checks on Ruby and ERB files |
-| `pr-comment-resolver` | Address PR review comments by implementing requested changes |
-| `spec-flow-analyzer` | Analyze specifications for user flow gaps and missing requirements |
-
-### Using Agents
-
-Agents are invoked via OpenCode's `@mention` syntax or `task`:
-
-```
-@architecture-strategist Review the authentication refactoring in this PR
+{ "plugins": ["@fro.bot/systematic@latest"] }
 ```
 
-Or programmatically in skills:
+Your global config lives at `~/.config/opencode/opencode.json`.
 
-```
-task(subagent_type="architecture-strategist", prompt="Review...")
-```
+## First Workflow
 
-## CLI
-
-Systematic includes a CLI for inspecting and converting assets outside of OpenCode.
+Once installed, run a full engineering cycle on any feature:
 
 ```
-systematic <command> [options]
+/ce:brainstorm "add dark mode toggle"
+/ce:plan
+/ce:work
+/ce:review
 ```
 
-### Commands
-
-| Command | Description |
-|---------|-------------|
-| `list [type]` | List available skills, agents, or commands |
-| `convert <type> <file>` | Convert a CEP file and output the result to stdout |
-| `config show` | Show current configuration and file contents |
-| `config path` | Print config file locations |
-
-### Examples
-
-```bash
-# List all bundled skills
-systematic list skills
-
-# List all bundled agents
-systematic list agents
-
-# Convert a Claude Code agent to OpenCode format
-systematic convert agent ./agents/my-agent.md
-
-# Convert with a specific agent mode
-systematic convert agent ./agents/my-agent.md --mode=primary
-
-# Show configuration
-systematic config show
-```
-
-## Configuration
-
-Systematic works out of the box, but you can customize it via configuration files.
-
-### Plugin Configuration
-
-Configuration is loaded from multiple locations and merged (later sources override earlier ones):
-
-1. **User config:** `~/.config/opencode/systematic.json`
-2. **Project config:** `.opencode/systematic.json`
-3. **Custom config:** `$OPENCODE_CONFIG_DIR/systematic.json` (if `OPENCODE_CONFIG_DIR` is set)
-
-```json
-{
-  "disabled_skills": ["git-worktree"],
-  "disabled_agents": [],
-  "categories": {
-    "review": {
-      "temperature": 0.1,
-      "steps": 12
-    }
-  },
-  "agents": {
-    "security-sentinel": {
-      "variant": "thinking"
-    },
-    "workflow/systematic-implementer": {
-      "steps": 20
-    }
-  },
-  "bootstrap": {
-    "enabled": true
-  }
-}
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `disabled_skills` | `string[]` | `[]` | Skills to exclude from registration |
-| `disabled_agents` | `string[]` | `[]` | Agents to exclude from registration |
-| `categories` | `object` | `{}` | Overlay bundled agents by category (`design`, `docs`, `document-review`, `research`, `review`, `workflow`) |
-| `agents` | `object` | `{}` | Overlay exact bundled agents by unique stem or `<category>/<stem>` key |
-| `bootstrap.enabled` | `boolean` | `true` | Inject the `using-systematic` guide into system prompts |
-| `bootstrap.file` | `string` | — | Custom bootstrap file path (overrides default) |
-
-Agent overlays support `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and managed `skills`. `color` accepts `#RRGGBB` hex colors or OpenCode theme tokens: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, and `info`. `skills` uses bundled skill frontmatter names like `ce:review`; it is a shortcut that writes OpenCode `permission.skill` rules, not a native OpenCode agent field. Because `model` and `variant` control provider routing/cost/privacy and `permission`/`skills` control tool access, those fields are only accepted from user config or `$OPENCODE_CONFIG_DIR/systematic.json`. Project config may tune non-sensitive presentation and runtime fields such as `temperature`, `top_p`, `mode`, `color`, `steps`, `hidden`, or exact-agent `disable`, but it cannot choose model/provider routing, tune `variant`, or loosen permission/capability policy.
-
-Systematic separates config-source precedence from overlay precedence. Config files merge in this order: user config, project config, then `$OPENCODE_CONFIG_DIR/systematic.json` if set. Higher-priority `agents.<key>` and `categories.<id>` entries replace lower-priority entries wholesale, while unrelated keys survive. Project overlays are the exception for trust-sensitive fields: same-key project overlays preserve user-level `model`, `variant`, `permission`, and `skills` fields instead of erasing them. After the effective config is built, Systematic applies agent overlay precedence for bundled agents:
-
-1. Exact `agents.<key>` overlay (high-trust `model` wins)
-2. `categories.<category-id>` overlay (high-trust `model` wins)
-3. Source category model default (built-in, code-owned)
-4. Bundled markdown/frontmatter defaults
-5. OpenCode inherited defaults
-
-Source category model defaults are primary model choices only — they are not fallback chains. Systematic does not support `fallback_models`, inherited retry semantics, runtime fallback behavior, or fallback to the parent model when a source model is unavailable. Explicit and source model IDs are structurally validated and may still fail at OpenCode runtime if the provider or model is unavailable.
-
-Source category model defaults are ordered provider/model preference chains per category. At plugin load, Systematic asks OpenCode for connected providers through `client.config.providers()` and selects the first provider/model entry OpenCode reports as available. If the live provider query fails, Systematic falls back to OpenCode's `models.json` cache; if both sources fail, it skips source-default emission so bundled agents inherit the parent OpenCode model instead of pinning an unavailable model. The chains are ordered preference lists, not runtime fallback chains — `fallback_models` is still not supported.
-
-If you want to restore OpenCode parent-model inheritance for a bundled agent or category (opting out of the source default), set `"model": null` in high-trust user or `$OPENCODE_CONFIG_DIR/systematic.json` config. Project config cannot use `model: null` — project config cannot set, erase, or shadow `model` at any value.
-
-The source defaults are:
-
-| Category | Chain | Rationale | When to Override |
-| --- | --- | --- | --- |
-| `design` | `github-copilot/gemini-3.1-pro-preview`, `openai/gpt-5.5` (`high`), `anthropic/claude-opus-4-7` (`max`), … | High-judgment UX, product, and design work benefits from a strong general reasoning model with broad creative capability. | Override to a faster/cheaper model when design tasks are primarily templating or low-stakes layout work. |
-| `docs` | `github-copilot/gemini-3.1-pro-preview`, `openai/gpt-5.4-mini`, `anthropic/claude-haiku-4-5`, … | Documentation and summarization tasks should start cheaper and faster; quality is sufficient at mid-tier models. | — |
-| `document-review` | `anthropic/claude-opus-4-7` (`max`), `openai/gpt-5.5` (`high`), `github-copilot/gemini-3.1-pro-preview`, … | Requirements and plan critique benefit from the strongest nuanced reasoning to surface non-obvious gaps and contradictions. | — |
-| `research` | `openai/gpt-5.4-mini`, `anthropic/claude-sonnet-4-6`, `github-copilot/gemini-3.1-pro-preview`, … | Tool-heavy synthesis and source evaluation benefit from a strong general reasoning model with broad knowledge. | — |
-| `review` | `anthropic/claude-sonnet-4-6`, `openai/gpt-5.3-codex`, `github-copilot/gemini-3.1-pro-preview`, … | Code, security, and adversarial review benefits from the strongest reasoning to catch subtle bugs and security issues. | Override to a faster model when review tasks are primarily style or formatting checks rather than correctness or security analysis. |
-| `workflow` | `openai/gpt-5.4-mini`, `anthropic/claude-sonnet-4-6`, `opencode/claude-haiku-4-5`, … | Orchestration and bounded implementation tasks should default cheaper and faster; strong reasoning is rarely needed for routing decisions. | — |
-
-These defaults are owned by Systematic code and emitted for bundled agents in each category when no stronger high-trust exact or category `model` override exists. Uncategorized bundled agents receive no source default and continue inheriting the parent OpenCode model. Native OpenCode agents with the same emitted key are full replacements and receive no Systematic source model default.
-
-Bundled agent markdown still intentionally omits `model` — the field belongs in source code defaults, not portable markdown files. Authors must not add `model:` frontmatter to bundled agent files.
-
-Systematic emits a source model as the default; you can override it per-agent or per-category in user or `$OPENCODE_CONFIG_DIR/systematic.json` config. Project config cannot set, erase, or shadow `model` policy.
-
-> **Migration: Restoring parent-model inheritance.** If you previously relied on bundled agents inheriting the parent OpenCode model (no source defaults), set `"model": null` in your high-trust config to opt out of the source default per agent or per category. For example:
->
-> ```jsonc
-> // ~/.config/opencode/systematic.json or $OPENCODE_CONFIG_DIR/systematic.json
-> {
->   "categories": {
->     "review": { "model": null }     // All review agents inherit parent model
->   },
->   "agents": {
->     "security-sentinel": { "model": null }  // Single agent inherits parent model
->   }
-> }
-> ```
->
-> This only works from high-trust config (user or `$OPENCODE_CONFIG_DIR/systematic.json`). Project `.opencode/systematic.json` cannot set `model: null` or any `model` value.
-
-Native OpenCode agents with the same emitted key are full replacements. An exact Systematic overlay for that key conflicts, while category overlays skip native replacements and continue applying to other bundled agents. Use one canonical agent key form across config sources (`security-sentinel` or `review/security-sentinel`) because alias collisions fail duplicate-target validation.
-
-Category IDs are V1 public API because broad policy overlays are a core use case; future agent reorganizations must preserve aliases or provide migration warnings. Category overlays also apply to future bundled agents added to that category. V1 does not include an MCP allowlist shortcut.
-
-### Project-Specific Content
-
-Add your own skills and agents alongside bundled ones:
-
-```
-.opencode/
-├── skills/
-│   └── my-skill/
-│       └── SKILL.md
-└── agents/
-    └── my-agent.md
-```
-
-Project-level content takes precedence over bundled content with the same name.
-
-## Tools
-
-The plugin exposes one tool to OpenCode:
-
-| Tool | Description |
-|------|-------------|
-| `systematic_skill` | Load Systematic bundled skills by name. Lists available skills in its description and returns formatted skill content when invoked. |
-
-For non-Systematic skills (project or user-level), use OpenCode's `skill` tool.
-
-## How It Works
-
-Systematic uses three OpenCode plugin hooks:
-
-```mermaid
-%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4FD1C5', 'lineColor': '#4FD1C5', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f0f23'}}}%%
-flowchart TB
-    A[Plugin Loaded] --> B[config hook]
-    A --> C[tool hook]
-    A --> D[system.transform hook]
-
-    B --> E[Merge bundled agents and skills into OpenCode config]
-    C --> F[Register systematic_skill tool]
-    D --> G[Inject bootstrap prompt into every conversation]
-
-    style A fill:#1a1a2e,stroke:#4FD1C5,color:#fff
-    style B fill:#16213e,stroke:#4FD1C5,color:#4FD1C5
-    style C fill:#16213e,stroke:#E91E8C,color:#E91E8C
-    style D fill:#16213e,stroke:#F5A623,color:#F5A623
-    style E fill:#0f0f23,stroke:#4FD1C5,color:#B2F5EA
-    style F fill:#0f0f23,stroke:#E91E8C,color:#B2F5EA
-    style G fill:#0f0f23,stroke:#F5A623,color:#B2F5EA
-```
-
-1. **`config` hook** — Discovers and merges bundled skills and agents into your OpenCode configuration. Existing config takes precedence over bundled content. Skills are registered as slash commands with the `systematic:` prefix.
-2. **`tool` hook** — Registers the `systematic_skill` tool, which lists available skills in its XML description and loads skill content on demand.
-3. **`system.transform` hook** — Injects the "Using Systematic" bootstrap guide into system prompts, teaching the AI how to discover and invoke skills.
-
-This architecture ensures skills and agents are available immediately without manual setup.
-
-## Development
-
-### Prerequisites
-
-- [Bun](https://bun.sh/) runtime
-- Node.js 18+ (for compatibility)
-
-### Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/marcusrbrown/systematic.git
-cd systematic
-
-# Install dependencies
-bun install
-
-# Build the plugin
-bun run build
-
-# Run type checking
-bun run typecheck
-
-# Run linter
-bun run lint
-
-# Run unit tests
-bun test
-```
-
-### Project Structure
-
-```
-systematic/
-├── src/
-│   ├── index.ts              # Plugin entry point (SystematicPlugin)
-│   ├── cli.ts                # CLI entry point
-│   └── lib/
-│       ├── bootstrap.ts      # System prompt injection
-│       ├── config.ts         # JSONC config loading + merging
-│       ├── config-handler.ts # OpenCode config hook implementation
-│       ├── converter.ts      # CEP-to-OpenCode content conversion
-│       ├── skill-tool.ts     # systematic_skill tool factory
-│       ├── skill-loader.ts   # Skill content loading + formatting
-│       ├── skills.ts         # Skill discovery
-│       ├── agents.ts         # Agent discovery
-│       ├── commands.ts       # Command discovery (backward compat)
-│       ├── frontmatter.ts    # YAML frontmatter parsing
-│       ├── validation.ts     # Agent config validation + type guards
-│       └── walk-dir.ts       # Recursive directory walker
-├── skills/                   # Bundled skills (SKILL.md files)
-├── agents/                   # Bundled agents (6 categories)
-├── docs/                     # Starlight documentation site
-├── registry/                 # OCX registry config + profiles
-├── scripts/                  # Build and utility scripts
-├── tests/
-│   ├── unit/                 # Unit test files
-│   └── integration/          # Integration test files
-└── dist/                     # Build output
-```
-
-### Testing
-
-```bash
-# Run all unit tests
-bun test tests/unit
-
-# Run a specific test file
-bun test tests/unit/skills.test.ts
-
-# Run integration tests
-bun test tests/integration
-
-# Run all tests
-bun test
-```
-
-### Contributing
-
-See [`AGENTS.md`](./AGENTS.md) for detailed development guidelines, code style conventions, and architecture overview.
+Each step invokes a structured skill that guides the AI through the appropriate phase — requirements exploration, implementation planning, execution, and code review.
 
-## Converting from Claude Code
+## First-Run Checklist
 
-Migrating skills or agents from Claude Code format to Systematic? The CLI includes a converter — run `bun src/cli.ts convert <file>` for field mappings and tool name translations.
+- [ ] [OpenCode](https://opencode.ai/) installed
+- [ ] Add `@fro.bot/systematic@latest` to your `opencode.json` plugins list
+- [ ] Restart OpenCode
+- [ ] Run `/ce:brainstorm` on something you're building
+- [ ] Verify: the `systematic_skill` tool appears in your tool list
 
-## References
+## Learn More
 
-- [Systematic Documentation](https://fro.bot/systematic) — Full documentation site
-- [Philosophy Guide](https://fro.bot/systematic/guides/philosophy/) — Core engineering principles
-- [Main Loop Guide](https://fro.bot/systematic/guides/main-loop/) — The standard development cycle
-- [Agent Install Guide](https://fro.bot/systematic/guides/agent-install/) — Advanced subagent configuration
-- [OpenCode Documentation](https://opencode.ai/docs/) — Official OpenCode platform docs
-- [OpenCode Plugin API](https://opencode.ai/docs/plugins) — Plugin development reference
-- [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) — Original Claude Code workflows
-- [Source Code](https://github.com/marcusrbrown/systematic) — View the implementation
+- [Documentation](https://fro.bot/systematic/)
+- [Skills Catalog](https://fro.bot/systematic/reference/skills/)
+- [Agents Catalog](https://fro.bot/systematic/reference/agents/)
+- [Configuration Reference](https://fro.bot/systematic/reference/configuration/)
+- [Architecture](./ARCHITECTURE.md)
 
 ## License
 

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-6evyges6.js";
+} from "./index-175fc4yn.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-6evyges6.js → index-175fc4yn.js}

@@ -16087,7 +16087,7 @@ function loadJsoncFile(filePath) {
   }
   return parsed;
 }
-var TYPED_VALIDATION_DOCS_URL = "https://systematic.fro.bot/getting-started/configuration#typed-validation";
+var TYPED_VALIDATION_DOCS_URL = "https://fro.bot/systematic/reference/configuration#typed-validation";
 var TYPED_KEY_FIELDS = new Set([
   "agents",
   "disabled_agents",

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   loadConfig,
   loadConfigWithSources,
   parseFrontmatter
-} from "./index-6evyges6.js";
+} from "./index-175fc4yn.js";
 
 // src/index.ts
 import fs5 from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.20.5",
+  "version": "2.21.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-work/references/shipping-workflow.md

@@ -68,7 +68,7 @@ This file contains the shipping workflow (Phase 3-4). Load it only when all Phas
 
 1. **Prepare Evidence Context**
 
-   Do not invoke `ce-demo-reel` directly in this step. Evidence capture belongs to the PR creation or PR description update flow, where the final PR diff and description context are available.
+   Do not invoke `feature-video` directly in this step. Evidence capture belongs to the PR creation or PR description update flow, where the final PR diff and description context are available.
 
    Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output). The `ce-commit-push-pr` skill will ask whether to capture evidence only when evidence is possible.
 

package/skills/compound-docs/SKILL.md

@@ -38,7 +38,7 @@ This skill captures problem solutions immediately after confirmation, creating s
 - "problem solved"
 - "that did it"
 
-**OR manual:** `/doc-fix` command
+**OR manual:** Invoke the `ce:compound` skill directly
 
 **Non-trivial problems only:**
 
@@ -348,7 +348,7 @@ Action:
 ## Integration Points
 
 **Invoked by:**
-- /compound command (primary interface)
+- `/ce:compound` skill (primary interface)
 - Manual invocation in conversation after solution confirmed
 - Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc.
 

package/skills/frontend-design/SKILL.md

@@ -297,7 +297,7 @@ Use the first available option:
 
 1. **Existing project browser tooling** -- if Playwright, Puppeteer, Cypress, or similar is already in the project's dependencies, use it. Do not introduce new dependencies just for verification.
 2. **Browser MCP tools** -- if browser automation tools (e.g., claude-in-chrome) are available in the agent's environment, use them.
-3. **agent-browser CLI** -- if nothing else is available and `agent-browser` is installed, use it. If not installed, inform the user: "`agent-browser` is not installed. Run `/ce-setup` to install required dependencies." Then skip to the next option.
+3. **agent-browser CLI** -- if nothing else is available and `agent-browser` is installed, use it. If not installed, inform the user: "`agent-browser` is not installed. Install it with `npm install -g agent-browser`." Then skip to the next option.
 4. **Mental review** -- if no browser access is possible (headless CI, no permissions to install), apply the litmus checks as a self-review and note that visual verification was skipped.
 
 ### What to Assess

package/skills/git-commit-push-pr/SKILL.md

@@ -69,11 +69,18 @@ Read the current PR description to drive the compare-and-confirm step later:
 gh pr view --json body --jq '.body'
 ```
 
-**Generate the updated title and body** — load the `ce-pr-description` skill with the PR URL from DU-2 (e.g., `https://github.com/owner/repo/pull/123`). The URL preserves repo/PR identity even when invoked from a worktree or subdirectory where the current repo is ambiguous. If the user provided a focus (e.g., "include the benchmarking results"), append it as free-text steering after the URL. The skill returns a `{title, body_file}` block (body in an OS temp file) without applying or prompting.
+**Generate the updated title and body** — using the PR URL from DU-2 and the commit range it covers, write an updated PR title and body. The URL preserves repo/PR identity even when invoked from a worktree or subdirectory. If the user provided a focus (e.g., "include the benchmarking results"), incorporate it into the generated content. Write the body to an OS temp file:
 
-If `ce-pr-description` returns a "not open" or other graceful-exit message instead of a `{title, body_file}` pair, report that message and stop.
+```bash
+BODY_FILE=$(mktemp /tmp/pr-body-XXXXXX.md)
+cat > "$BODY_FILE" << 'EOF'
+<generated body>
+EOF
+```
+
+If the PR is not open or the commit range cannot be resolved, report the issue and stop.
 
-**Evidence decision:** `ce-pr-description` preserves any existing `## Demo` or `## Screenshots` block from the current body by default. If the user's focus asks to refresh or remove evidence, pass that intent as steering text — the skill will honor it. If no evidence block exists and one would benefit the reader, invoke `ce-demo-reel` separately to capture, then re-invoke `ce-pr-description` with updated steering that references the captured evidence.
+**Evidence decision:** Preserve any existing `## Demo` or `## Screenshots` block from the current body by default. If the user's focus asks to refresh or remove evidence, honor that intent. If no evidence block exists and one would benefit the reader, load the `feature-video` skill to capture evidence, then splice the result as a `## Demo` section into the body file.
 
 **Compare and confirm** — briefly explain what the new description covers differently from the old one. This helps the user decide whether to apply; the description itself does not narrate these differences. Summarize from the body already in context (from the bash call that wrote `body_file`); do not `cat` the temp file, which would re-emit the body.
 
@@ -134,7 +141,7 @@ Priority order for commit messages and PR titles:
 
 Use the current branch and existing PR check from context. If the branch is empty, report detached HEAD and stop.
 
-If the PR check returned `state: OPEN`, note the URL -- this is the existing-PR flow. Continue to Step 4 and 5 (commit any pending work and push), then go to Step 7 to ask whether to rewrite the description. Only run Step 6 (which generates a new description via `ce-pr-description`) if the user confirms the rewrite; Step 7's existing-PR sub-path consumes the `{title, body_file}` that Step 6 produces. Otherwise (no open PR), continue through Steps 6, 7, and 8 in order.
+If the PR check returned `state: OPEN`, note the URL -- this is the existing-PR flow. Continue to Step 4 and 5 (commit any pending work and push), then go to Step 7 to ask whether to rewrite the description. Only run Step 6 (which generates a new description) if the user confirms the rewrite; Step 7's existing-PR sub-path uses the title and body file that Step 6 produces. Otherwise (no open PR), continue through Steps 6, 7, and 8 in order.
 
 ### Step 4: Branch, stage, and commit
 
@@ -191,44 +198,49 @@ Use this branch diff (not the working-tree diff) for the evidence decision. If t
 
 **Evidence decision (before delegation).** If the branch diff changes observable behavior (UI, CLI output, API behavior with runnable code, generated artifacts, workflow output) and evidence is not otherwise blocked (unavailable credentials, paid services, deploy-only infrastructure, hardware), ask: "This PR has observable behavior. Capture evidence for the PR description?"
 
-- **Capture now** -- load the `ce-demo-reel` skill with a target description inferred from the branch diff. ce-demo-reel returns `Tier`, `Description`, and `URL`. Note the captured evidence so it can be passed as free-text steering to `ce-pr-description` (e.g., "include the captured demo: <URL> as a `## Demo` section") or spliced into the returned body before apply. If capture returns `Tier: skipped` or `URL: "none"`, proceed with no evidence.
-- **Use existing evidence** -- ask for the URL or markdown embed, then pass it as free-text steering to `ce-pr-description` or splice in before apply.
+- **Capture now** -- load the `feature-video` skill with a target description inferred from the branch diff. feature-video returns `Tier`, `Description`, and `URL`. Note the captured evidence so it can be spliced into the PR body as a `## Demo` section. If capture returns `Tier: skipped` or `URL: "none"`, proceed with no evidence.
+- **Use existing evidence** -- ask for the URL or markdown embed, then splice it into the PR body as a `## Demo` section before applying.
 - **Skip** -- proceed with no evidence section.
 
 When evidence is not possible (docs-only, markdown-only, changelog-only, release metadata, CI/config-only, test-only, or pure internal refactors), skip without asking.
 
-**Delegate title and body generation to `ce-pr-description`.** Load the `ce-pr-description` skill:
+**Generate title and body.** Using the branch diff and commit log, write a PR title and body directly:
 
-- **For a new PR** (no existing PR found in Step 3): invoke with `base:<base-remote>/<base-branch>` using the already-resolved base from earlier in this step, so `ce-pr-description` describes the correct commit range even when the branch targets a non-default base (e.g., `develop`, `release/*`). Append any captured-evidence context or user focus as free-text steering (e.g., "include the captured demo: <URL> as a `## Demo` section").
-- **For an existing PR** (found in Step 3): invoke with the full PR URL from the Step 3 context (e.g., `https://github.com/owner/repo/pull/123`). The URL preserves repo/PR identity even when invoked from a worktree or subdirectory; the skill reads the PR's own `baseRefName` so no `base:` override is needed. Append any focus steering as free text after the URL.
-
-`ce-pr-description` returns a `{title, body_file}` block (body in an OS temp file). It applies the value-first writing principles, commit classification, sizing, narrative framing, writing voice, visual communication, numbering rules, and the Systematic badge footer internally. Use the returned values verbatim in Step 7; do not layer manual edits onto them unless a focused adjustment is required (e.g., splicing an evidence block captured in this step that was not passed as steering text — in that case, edit the body file directly before applying).
+- **Title**: conventional-commit format, under 72 characters, describing the value delivered (not the implementation).
+- **Body**: value-first narrative scaled to the change size. Apply the writing principles, commit classification, sizing, and narrative framing described in this skill. Write the body to an OS temp file:
+  ```bash
+  BODY_FILE=$(mktemp /tmp/pr-body-XXXXXX.md)
+  cat > "$BODY_FILE" << 'EOF'
+  <generated body>
+  EOF
+  ```
+- Splice any captured evidence as a `## Demo` section into the body file before applying.
 
-If `ce-pr-description` returns a graceful-exit message instead of `{title, body_file}` (e.g., closed PR, no commits to describe, base ref unresolved), report the message and stop — do not create or edit the PR.
+If the branch diff is empty or the base ref is unresolved, report the issue and stop — do not create or edit the PR.
 
 ### Step 7: Create or update the PR
 
 #### New PR (no existing PR from Step 3)
 
-Using the `{title, body_file}` returned by `ce-pr-description`:
+Using the title and body file generated in Step 6:
 
 ```bash
-gh pr create --title "<returned title>" --body "$(cat "<returned body_file>")"
+gh pr create --title "<title>" --body "$(cat "<body_file>")"
 ```
 
-Keep the title under 72 characters; `ce-pr-description` already emits a conventional-commit title in that range.
+Keep the title under 72 characters.
 
 #### Existing PR (found in Step 3)
 
 The new commits are already on the PR from Step 5. Report the PR URL, then ask whether to rewrite the description.
 
-- If **yes**, run Step 6 now to generate `{title, body_file}` via `ce-pr-description` (passing the existing PR URL as `pr:`), then apply the returned title and body file:
+- If **yes**, run Step 6 now to generate the title and body file (passing the existing PR URL for context), then apply:
 
   ```bash
-  gh pr edit --title "<returned title>" --body "$(cat "<returned body_file>")"
+  gh pr edit --title "<title>" --body "$(cat "<body_file>")"
   ```
 
-- If **no** -- skip Step 6 entirely and finish. Do not run delegation or evidence capture when the user declined the rewrite.
+- If **no** -- skip Step 6 entirely and finish. Do not run evidence capture when the user declined the rewrite.
 
 ### Step 8: Report
 

package/skills/test-browser/SKILL.md

@@ -32,7 +32,7 @@ Check whether `agent-browser` is installed:
 command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
 ```
 
-If not installed, inform the user: "`agent-browser` is not installed. Run `/ce-setup` to install required dependencies." Then stop — this skill cannot function without agent-browser.
+If not installed, inform the user: "`agent-browser` is not installed. Install it with `npm install -g agent-browser`." Then stop — this skill cannot function without agent-browser.
 
 ## Workflow
 
@@ -44,7 +44,7 @@ Before starting, verify `agent-browser` is available:
 command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"
 ```
 
-If not installed, inform the user: "`agent-browser` is not installed. Run `/ce-setup` to install required dependencies." Then stop.
+If not installed, inform the user: "`agent-browser` is not installed. Install it with `npm install -g agent-browser`." Then stop.
 
 ### 2. Ask Browser Mode
 

package/skills/todo-create/SKILL.md

@@ -93,9 +93,9 @@ To check blockers: search for `{dep_id}-complete-*.md` in both paths. Missing ma
 
 | Trigger | Flow |
 |---------|------|
-| Code review | `/ce:review` -> Findings -> `/todo-triage` -> Todos |
-| Autonomous review | `/ce:review mode:autofix` -> Residual todos -> `/todo-resolve` |
-| Code TODOs | `/todo-resolve` -> Fixes + Complex todos |
+| Code review | `/ce:review` -> Findings -> `/systematic:todo-triage` -> Todos |
+| Autonomous review | `/ce:review mode:autofix` -> Residual todos -> `/systematic:todo-resolve` |
+| Code TODOs | `/systematic:todo-resolve` -> Fixes + Complex todos |
 | Planning | Brainstorm -> Create todo -> Work -> Complete |
 
 ## Key Distinction

package/skills/todo-resolve/SKILL.md

@@ -62,7 +62,7 @@ Todos cleaned up: [count deleted]
 If pending todos were skipped, list them:
 
 ```
-Skipped pending todos (run /todo-triage to approve):
+Skipped pending todos (run `/systematic:todo-triage` to approve):
   - 003-pending-p2-missing-index.md
   - 005-pending-p3-rename-variable.md
 ```

package/skills/todo-triage/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: true
 
 Interactive workflow for reviewing pending todos one by one and deciding whether to approve, skip, or modify each.
 
-**Do not write code during triage.** This is purely for review and prioritization -- implementation happens in `/todo-resolve`.
+**Do not write code during triage.** This is purely for review and prioritization -- implementation happens in `/systematic:todo-resolve`.
 
 - First set the /model to Haiku
 - Read all pending todos from `.context/systematic/todos/` and legacy `todos/` directories
@@ -64,7 +64,7 @@ After all items processed:
 ```markdown
 What would you like to do next?
 
-1. run /todo-resolve to resolve the todos
+1. run `/systematic:todo-resolve` to resolve the todos
 2. commit the todos
 3. nothing, go chill
 ```