# @haylan/opencode-pocock

[OpenCode](https://opencode.ai) v2 integration for [Matt Pocock's skills](https://github.com/mattpocock/skills):
the upstream skills injected verbatim as OpenCode skills, plus generated agents that run his
skill-driven engineering flow — grill an idea, turn it into a spec and tickets, build test-first
with parallel workers in isolated git worktrees, review, retro.

All engineering discipline is Matt Pocock's; this package only supplies the OpenCode v2 wiring.
Upstream is synced nightly and the package republished on change (see `CHANGELOG.md` for the
upstream revision each release carries).

## Install

1. Add the plugin (from the Gitea registry, or npm once published there):

   ```jsonc
   // opencode.json
   {
     "$schema": "https://opencode.ai/config.json",
     "plugins": ["@haylan/opencode-pocock"],
   }
   ```

   The plugin injects all skills at startup — no files copied into your repo.

2. Install the agents (OpenCode discovers agents only as markdown files, and plugins cannot
   register them, so this one copy step is required):

   ```bash
   npx @haylan/opencode-pocock init      # project: .opencode/agents/
   npx @haylan/opencode-pocock init -g   # or global: ~/.config/opencode/agents/
   ```

3. Once per repo, run `/setup-matt-pocock-skills` in OpenCode. It configures the issue tracker,
   triage labels and domain docs that `to-spec`, `to-tickets`, `triage`, `implement`,
   `implement-spec`, `code-review` and `wayfinder` depend on.

## Usage

Start OpenCode with the `pocock` agent selected and describe what you want to build:

```bash
opencode mini --agent pocock                  # interactive (v2.0.29: --agent is not a top-level flag)
opencode run --agent pocock "build …" --auto  # one-shot, autonomous
```

In the default TUI (plain `opencode`), switch to `pocock` with the agent picker instead.

| Agent             | Role                                                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pocock`          | Primary orchestrator. Routes with `ask-matt`, walks grill → spec → tickets → build → review → retro, proposes before each user-invoked step, runs `implement-spec` with one git worktree per ticket and parallel `pocock-worker` subagents. |
| `pocock-worker`   | Subagent. Builds one ticket test-first (`tdd` at the spec's seams) inside its worktree, merges the integration tip, reports. Never pushes.                                                                                                  |
| `pocock-reviewer` | Subagent. Read-only executor of one `code-review` axis (Standards or Spec).                                                                                                                                                                 |

23 of the 31 vendored skills are user-invoked upstream (`disable-model-invocation: true`);
OpenCode v2 honors that natively — they stay out of the model's auto-selection. Note that
plugin-injected skills are not exposed as slash commands in v2 (only file-based skills are):
the `pocock` agent proposes each user-invoked step and loads it after your yes. If you want
`/to-spec` & co. directly, either keep a file-based install of Matt's skills (e.g.
`npx skills@latest add mattpocock/skills -a opencode`; id collisions then resolve to your
file-based copies) or, for a project-level npm install, add a skills source:
`"skills": ["./node_modules/@haylan/opencode-pocock/skills"]`.

Worktrees live under `/tmp/pocock-workers`. Current OpenCode v2 builds allow `external_directory`
for `/tmp/*` by default; if yours asks before a subagent writes there, add a global rule:

```json
{ "permission": { "external_directory": { "/tmp/pocock-workers/*": "allow" } } }
```

## Plugin options

```jsonc
{
  "plugins": [
    {
      "package": "@haylan/opencode-pocock",
      // Ports skills/misc/git-guardrails-claude-code to OpenCode: blocks dangerous git
      // commands (push --force, reset --hard, clean -f, branch -D, ...) before execution.
      "options": { "guardrails": true },
    },
  ],
}
```

## Development

- `npm run sync` — update `upstream/` snapshot from mattpocock/skills (script-only; never
  hand-edit `upstream/` or `skills/`).
- `npm run generate` — regenerate `skills/` + `manifest.json` from `upstream/` and
  `.opencode/state/classification.json`.
- `npm test` / `npm run check` / `npm run build` — unit + integration tests (`node --test` on TS),
  prettier + tsc gate, build.
- `npm run smoke` — boots `opencode serve` against a fixture and verifies plugin/skills/agents
  over the HTTP API (needs a local `opencode` binary; no model calls).

Design and rationale: [`docs/architecture.md`](docs/architecture.md).
Per-skill classification: [`docs/skill-mapping.md`](docs/skill-mapping.md).

## License

MIT — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) for upstream attributions.