Installation

This page gets you from zero to your first Systematic workflow in under five minutes, on OpenCode, Pi, or Claude Code. Most setups are one line of config and a restart away.

Prerequisites

You need the harness you are installing into — OpenCode, Pi, or Claude Code — installed and running. Systematic supports OpenCode v1 from 1.18.29 and OpenCode v2 from 2.2.5. Older versions of either are not supported, and there is no compatibility shim. The OpenCode and Pi package also needs Node.js 18+ or the Bun runtime, and Pi itself needs Node.js 22.19+. No API keys, no accounts, no extra tooling.

The pr-attachments skill, which git-commit-push-pr uses to attach screenshots to a pull request, also needs Node.js 18+ on your PATH. An OpenCode install that runs on Bun alone does not have it. Without Node.js, the skill stops and publishes nothing; every other skill works as before.

Install the OpenCode plugin

The OpenCode plugin is the recommended installation path. It provides the full experience: slash commands, the systematic_skill tool, agent registration, and automatic bootstrap.

It is one npm package for both OpenCode lines. The only difference is the config key: OpenCode v1 reads plugin, and OpenCode v2 reads plugins.

1. Add the plugin to your OpenCode config

   Open your global OpenCode config (typically ~/.config/opencode/opencode.json, or opencode.jsonc). On OpenCode v1 (1.18.29 or later), add Systematic to the plugin array:

   {
     "plugin": ["@fro.bot/systematic@latest"]
   }

   On OpenCode v2 (2.2.5 or later), add it to the plugins array:

   {
     "plugins": ["@fro.bot/systematic@latest"]
   }

   If you already have other plugins, add it to the existing array.

   systematic setup --harness opencode and OCX installs write the v1 plugin key. For OpenCode v2, add the plugins entry by hand.

2. Restart OpenCode

   Close and reopen your OpenCode session. Systematic registers all bundled skills, agents and commands automatically on startup: through OpenCode’s config hook on v1, and through the plugin’s setup function on v2. No manual wiring, no scaffolding commands. On v2, Systematic reads systematic.json once at startup, so restart OpenCode after you change it.

3. Verify it’s working

   In any conversation, check that systematic_skill appears in the available tool list. You can also run the bootstrap skill:

   /systematic:using-systematic

   If the skill loads and displays usage instructions, the installation succeeded.

Harness compatibility at a glance

Harness	Install	Skill loading
OpenCode v1 (1.18.29+)	opencode.json plugin array	systematic_skill tool + skills-as-commands
OpenCode v2 (2.2.5+)	opencode.json plugins array	systematic_skill tool + native skill tool + skills-as-commands
Pi	setup --harness pi	systematic_skill tool
Claude Code	plugin marketplace	native Skill tool

See HARNESSES.md for the full capability matrix and per-harness boundaries.

Or install skill content with npx skills

Use npx skills to install the skill Markdown files directly. This path works in any AI harness (OpenCode, Claude Code, Cursor, Copilot) but installs the content only. It does not include slash-command registration, the systematic_skill tool, or automatic bootstrap.

Whole collection

Current project

Install all Systematic skills into the current working directory.

npx skills add marcusrbrown/systematic

Global install

All projects

Make skills available across all projects.

npx skills add marcusrbrown/systematic -g

Specific AI Harness

OpenCode / Claude Code

Target a specific AI coding assistant.

npx skills add marcusrbrown/systematic -a opencode

npx skills add marcusrbrown/systematic -a claude-code

Specific skill

Single workflow

Install just one skill instead of the entire collection.

npx skills add marcusrbrown/systematic --skill [name]

List skills

Discovery

See what skills are available in the collection before installing.

npx skills add marcusrbrown/systematic --list

Install into a Pi coding-agent project

Systematic also ships a Pi coding-agent extension from the same package — same systematic_skill tool, same bootstrap injection, plus a systematic_delegate persona-delegation tool.

npx @fro.bot/systematic setup --harness pi

This atomically writes the plugin entry into .pi/settings.json. It is idempotent — running it again is safe and will not duplicate the entry. Pi trust-gates the extension at first use, so expect a trust prompt the first time it loads.

Optional: use the personas with pi-subagents

pi-subagents is a separate Pi extension for parallel or multi-model delegation. Install it yourself (version 0.22 or newer); it is not part of Systematic. Once both are installed, pi-subagents offers Systematic’s 29 curated personas as systematic-<name> agent types straight from the installed Systematic package, with no export step. A project-scope install such as the one above is read only after Pi trusts the project, and pi -e runs and git installs expose none of them. This is an opt-in complement — systematic_delegate (sequential, bounded, depth-1) stays the default.

The packaged personas are plain defaults. To apply your systematic.json overlays (model, thinking, max_turns, tools, skills), or to keep your settings in one file, export them instead.

Optional: export personas to customize them

Export writes the same curated personas as flat agent files that carry your config overlays. A file in <cwd>/.pi/agents/ outranks the packaged one of the same name.

npx @fro.bot/systematic pi-subagents preview   # see what would be exported
npx @fro.bot/systematic pi-subagents export    # write to <cwd>/.pi/agents/

Exact CLI form: systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global. Default scope is project (writes to <cwd>/.pi/agents/). Pass --scope global to target $PI_CODING_AGENT_DIR/agents/ instead, falling back to ~/.pi/agent/agents/ if that variable is unset. Existing files not owned by Systematic (i.e. not tracked in its manifest) are never overwritten; manifest-owned generated files are replaced when you explicitly run refresh, as documented in the pi-subagents pairing guide below. Run cleanup to remove the exported files and fall back to the packaged defaults.

Your Systematic config is the durable source of truth for exported personas — the generated files and manifest are a disposable projection that refresh intentionally overwrites when it drifts from current config; run preview first to see what would change. See the pi-subagents pairing guide for the packaged defaults, the packageAgents off switch and its cost, the full ownership model, config precedence, refresh/cleanup commands, and delegation boundary notes.

See HARNESSES.md for an honest list of where Pi parity with OpenCode currently ends (config support, permission gating).

Install into a Claude Code project

Systematic is also built and published as a Claude Code plugin (from a dedicated claude-code-plugin branch) and installed through Claude Code’s plugin marketplace.

claude plugin marketplace add marcusrbrown/systematic
claude plugin install systematic@systematic

In Claude Desktop’s GUI, the equivalent path is + → Plugins → Add plugin. Once installed, skills are available through Claude Code’s native Skill tool rather than the systematic_skill tool.

See HARNESSES.md for the full capability matrix and per-harness boundaries.

Automatic asset discovery

Systematic requires zero manual file copying. When the OpenCode plugin loads, it automatically:

• Discovers all bundled skills and makes them available via the systematic_skill tool.
• Registers bundled agents so you can @mention them immediately.
• Exposes bundled skills as slash-invokable workflows (for example, /ce:plan).

Pi and Claude Code surface the same skills and agents through their own discovery — Pi via the systematic_skill tool, Claude Code via its native Skill tool. See HARNESSES.md for how discovery differs per harness.

Recommended: enable background subagents

Set OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true before starting OpenCode. This allows Systematic workflows to dispatch subagents in the background. The orchestrator continues working while subagents run, and results are pushed into the parent session automatically upon completion.

export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true

Add this to your shell profile (.zshrc, .bashrc, or equivalent) to persist the setting.

This flag is experimental but stable in recent OpenCode versions. It is optional but recommended for parallel and long-running workflow steps. Without it, Systematic falls back to foreground dispatch, which is serial but correct.

Your first workflow

Systematic is built around a four-step loop. Here is what it looks like in practice, using a concrete task: adding a dark mode toggle. The commands below use OpenCode’s slash-command form; Pi and Claude Code run the same workflows through their native skill invocation (see HARNESSES.md for the per-harness equivalents).

1. Brainstorm — explore the problem before writing code

   /ce:brainstorm "add dark mode toggle"

   The brainstorm skill asks clarifying questions, surfaces edge cases, and produces a requirements document. You end up with a clear scope before a single line of code is written.

2. Plan — break the work into a structured implementation plan

   /ce:plan

   Takes the requirements document from the brainstorm and produces a sequenced implementation plan. For high-stakes work, run /systematic:deepen-plan afterward to stress-test the plan’s assumptions.

3. Work — execute the plan

   /ce:work

   The agent follows the plan, tracks progress, and surfaces blockers instead of silently guessing. You stay in the loop without micromanaging every step.

4. Review — check the work before opening a PR

   /ce:review

   Tiered persona agents check for correctness, security, performance, and style, in parallel. You get a structured report, not a wall of unranked comments.

After shipping, use /ce:compound to capture what you learned. That knowledge becomes part of the system and speeds up the next similar task.

Next steps

• The Systematic Philosophy — understand why the loop is structured this way and what “compounding” actually means in practice.
• Configuration — disable bundled content you don’t want, add project-specific skills, or configure agent overlays.
• Skills Reference — browse all bundled skills and when to reach for each one.
• Agents Reference — explore the specialized subagents available for review, research, and architecture work.