plugin-maintenance

# Chorus Plugin & Skill Maintenance

How to modify the Chorus plugin, update skill documentation, and release new versions. **Three plugin packages** are maintained in parallel — Claude Code, Codex, and OpenClaw — plus the standalone skill surface. That is **four skill surfaces total**; when you change skill content, sweep all four (see [Skill Content Changes — Four Surfaces](#skill-content-changes--four-surfaces)).

## File Structure

```
.claude-plugin/
  marketplace.json              ← Claude Code marketplace registry (version here)

public/chorus-plugin/           ← Claude Code plugin package
  .claude-plugin/
    plugin.json                 ← Plugin metadata (version here)
  hooks.json                    ← Hook definitions (SubagentStart, etc.)
  bin/                          ← Hook scripts (bash) — stateful via API state-get/set
  skills/
    chorus/SKILL.md             ← Core skill
    develop/ idea/ proposal/ quick-dev/ review/ yolo/SKILL.md
  agents/                       ← Reviewer agents as .md (Claude Code style)
    proposal-reviewer.md
    task-reviewer.md

plugins/chorus/                 ← Codex plugin package (separate from Claude Code)
  .codex-plugin/
    plugin.json                 ← Plugin metadata (version here)
  hooks.json
  hooks/                        ← Hook scripts (bash) — intentionally stateless
    on-session-start.sh
    on-post-submit-proposal.sh
    on-post-submit-for-verify.sh
    chorus-mcp-call.sh          ← MCP helper (has hardcoded clientInfo version)
    hook-output.sh
  skills/
    chorus/SKILL.md             ← Codex port — mentions $skill syntax, ~/.codex/config.toml
    develop/ idea/ proposal/ quick-dev/ review/ yolo/SKILL.md
    chorus-proposal-reviewer/SKILL.md  ← Reviewers as skills in Codex (no agents/)
    chorus-task-reviewer/SKILL.md

packages/openclaw-plugin/       ← OpenClaw plugin package (TS runtime + skills)
  openclaw.plugin.json          ← Plugin manifest (id, skills dir, activation, configSchema) — NO version field
  package.json                  ← npm package (version here; `openclaw` block: extensions, runtimeExtensions, install/compat)
  src/                          ← TypeScript runtime (index.ts, mcp-client.ts, sse-listener.ts, event-router.ts, wake.ts)
                                  — real-time SSE event bridge + MCP registration; NOT bash hooks
  dist/                         ← Compiled JS (npm install loads this; linked install loads src/ via jiti)
  skills/
    chorus/SKILL.md             ← OpenClaw port — tools namespaced `chorus__<tool>`, inline OpenSpec detection
    develop/ idea/ proposal/ quick-dev/ review/ yolo/ brainstorm/ openspec-aware/SKILL.md
    proposal-reviewer/SKILL.md  ← Reviewers as skills (like Codex, no agents/)
    task-reviewer/SKILL.md

public/skill/                   ← Standalone skill (any MCP-compatible agent)
  chorus/SKILL.md               ← Same structure, softer language, IDE-agnostic
  proposal-chorus/SKILL.md
  quick-dev-chorus/SKILL.md
```

### Claude Code vs Codex vs OpenClaw plugin: key differences

| Aspect | `public/chorus-plugin/` (Claude Code) | `plugins/chorus/` (Codex) | `packages/openclaw-plugin/` (OpenClaw) |
|--------|---------------------------------------|---------------------------|----------------------------------------|
| Skill invocation | `/chorus:develop` etc. | `$develop`, `$yolo` (no namespace) | `/develop` etc. |
| Tool names | `chorus_<tool>` | `chorus_<tool>` | **`chorus__<tool>`** (double-underscore prefix from the MCP server registration) |
| MCP config | `.mcp.json` | `~/.codex/config.toml` with `[mcp_servers.chorus.http_headers]` | Plugin config (`chorusUrl` + `apiKey` via `configSchema`); the TS runtime registers MCP itself |
| Session lifecycle | Auto-managed via SubagentStart/Stop hooks | **Stateless** — main agent manages sessions manually | **Manual** — no SubagentStart hook; main agent manages sessions |
| Reviewers | `agents/*.md` + spawned via Task tool | Skills mounted into `agent_type="default"` via `spawn_agent` + `items` | `proposal-reviewer/` & `task-reviewer/` skills, spawned via `sessions_spawn` (read-only self-review fallback) |
| User interaction | `AskUserQuestion` (MUST use) | plain-text prompt | **plain-text prompt** — no `AskUserQuestion` primitive |
| OpenSpec detection | `CHORUS_OPENSPEC_ACTIVE` precomputed by SessionStart hook | precomputed by SessionStart hook | **inline** — run the §1 three-check detection yourself every time (no SessionStart hook) |
| "Hooks" | `bin/*.sh` (bash, stateful) | `hooks/*.sh` (bash, stateless) | **No bash hooks** — real-time behavior is a **TypeScript SSE runtime** in `src/` (`sse-listener.ts`, `event-router.ts`, `wake.ts`) |
| Task execution (yolo) | Wave-based Agent Teams (`TeamCreate`) | Sequential / `spawn_agent` | Sequential main-agent waves (no Agent Teams primitive) |

When porting a change between plugins, preserve these intentional differences. Don't add state files to the Codex/OpenClaw plugins, don't use `$`-prefix in Claude Code/OpenClaw docs, and in OpenClaw docs keep the `chorus__` tool-name note and the "sessions are manual / detection is inline / prompts are plain-text" phrasing.

## When to Update What

"All three plugin `chorus/SKILL.md`" = Claude Code + Codex + OpenClaw. "All four surfaces" additionally includes standalone `public/skill/`.

| Change | Files to update |
|--------|----------------|
| New MCP tool added | `src/mcp/tools/*.ts` (implementation) + `docs/MCP_TOOLS.md` + all three plugin `chorus/SKILL.md` files + standalone `public/skill/chorus/SKILL.md` |
| MCP tool description changed | `src/mcp/tools/*.ts` only (skill docs reference tool names, not descriptions) |
| Skill content / wording (e.g. AC now required) | The matching stage skill in **all four surfaces** (see [Skill Content Changes — Four Surfaces](#skill-content-changes--four-surfaces)) |
| New workflow step | All three plugin stage-specific `SKILL.md` (e.g. `develop/`, `proposal/`) + standalone equivalent |
| Ne