🌐 chore: multi-platform placeholder structure (Codex, Cursor, OpenCode, Gemini)

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tmb",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TMB multi-agent Claude Code plugin with SQLite trajectory MCP.",
   "author": {
     "name": "trustmybot",

.codex-plugin/README.md

@@ -0,0 +1,17 @@
+# `.codex-plugin/` — placeholder for OpenAI Codex adapter
+
+> **Status: not implemented.** This directory is a placeholder so the repo's structure mirrors the multi-platform pattern (Claude / Codex / Cursor / OpenCode / Gemini). TMB ships Claude Code only as of v0.1.1.
+
+## What this would be
+
+Once implemented, this directory would hold the OpenAI Codex adapter:
+
+- `plugin.json` — the Codex-format manifest pointing at the shared `./skills/`, `./templates/agents/`, and `./templates/skills/` directories at the repo root
+- Any Codex-specific persona/loading file (likely `../CODEX.md` at the repo root)
+- Any Codex-specific hook scripts under `../hooks/codex/`
+
+The shared content (skills, agent templates, MCP server, planning protocol) is already platform-agnostic and would be referenced via relative paths — no duplication. See [`../docs/multi-platform.md`](../docs/multi-platform.md) for the strategy and [Superpowers](https://github.com/obra/superpowers) for the canonical example of this pattern.
+
+## When this gets built
+
+When (a) there's user demand for TMB on Codex, AND (b) the Claude Code experience is stable enough that maintaining a parallel adapter is sustainable. Track via the multi-platform tracking issue.

.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "tmb",
+  "version": "0.1.1",
+  "description": "PLACEHOLDER — TMB multi-agent workflow plugin for OpenAI Codex (not yet implemented).",
+  "_status": "placeholder",
+  "_see": "https://github.com/trustmybot/plugin/blob/main/docs/multi-platform.md"
+}

.cursor-plugin/README.md

@@ -0,0 +1,17 @@
+# `.cursor-plugin/` — placeholder for Cursor adapter
+
+> **Status: not implemented.** This directory is a placeholder so the repo's structure mirrors the multi-platform pattern (Claude / Codex / Cursor / OpenCode / Gemini). TMB ships Claude Code only as of v0.1.1.
+
+## What this would be
+
+Once implemented, this directory would hold the Cursor adapter:
+
+- `plugin.json` — the Cursor-format manifest pointing at shared content
+- Cursor-specific hook config (Cursor's hook event names + JSON-decision protocol differ from Claude Code's; expect a separate `../hooks/cursor/hooks.json`)
+- Persona loading via `../CURSOR.md` at the repo root
+
+The shared content (skills, agent templates, MCP server, planning protocol) is already platform-agnostic. See [`../docs/multi-platform.md`](../docs/multi-platform.md).
+
+## When this gets built
+
+When the Cursor user community surfaces enough demand AND the per-platform hook abstraction has solidified. Cursor's plugin system is younger and may shift; tracking issue keeps tabs.

.cursor-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "tmb",
+  "version": "0.1.1",
+  "description": "PLACEHOLDER — TMB multi-agent workflow plugin for Cursor (not yet implemented).",
+  "_status": "placeholder",
+  "_see": "https://github.com/trustmybot/plugin/blob/main/docs/multi-platform.md"
+}

.opencode/README.md

@@ -0,0 +1,16 @@
+# `.opencode/` — placeholder for OpenCode adapter
+
+> **Status: not implemented.** This directory is a placeholder so the repo's structure mirrors the multi-platform pattern (Claude / Codex / Cursor / OpenCode / Gemini). TMB ships Claude Code only as of v0.1.1.
+
+## What this would be
+
+Once implemented, this directory would hold the OpenCode adapter:
+
+- `plugins/tmb.js` — OpenCode plugin entry point (auto-discovers `./skills/` from repo root)
+- An `INSTALL.md` documenting the install path: `/plugin install superpowers@git+https://github.com/trustmybot/plugin.git` (or equivalent)
+
+OpenCode uses native skill auto-discovery, so the manifest is thinner than other platforms.
+
+## When this gets built
+
+When OpenCode adoption justifies a maintained adapter. Tracking issue applies.

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable user-visible changes to the TMB plugin. Versions follow [SemVer](https://semver.org/) (pre-1.0: breaking changes may happen on minor bumps).
 
+## v0.1.2 — 2026-04-25
+
+**Docs + structural release.** No agent, hook, or MCP-server behavior change. Adds multi-platform structural placeholders following the [Superpowers](https://github.com/obra/superpowers) pattern, and refreshes contributor docs to match the bro-as-planner doctrine that landed in v0.1.0.
+
+### Added
+
+- **Multi-platform placeholder structure** ([#73](https://github.com/trustmybot/plugin/pull/73)). Per-platform adapter dirs (`.codex-plugin/`, `.cursor-plugin/`, `.opencode/`) and root-level personas (`CODEX.md`, `CURSOR.md`, `GEMINI.md`, `gemini-extension.json`) ship as **placeholders only** — clearly marked "not implemented." The strategy doc at [`docs/multi-platform.md`](docs/multi-platform.md) explains how the per-platform adapter pattern works, what an adapter would do, and why placeholders ship now (discoverability + path-precedent). No platform other than Claude Code is functional in this release.
+- **`scripts/release.sh`** — generic, idempotent release ritual. Reads version from `plugin.json`, validates `mcp pkg.json` agrees, requires a matching CHANGELOG section, asks for `y/N` per step, then tags + pushes + creates the GitHub release. Replaces the v0.1.0-specific stranded script. Documented under "Release ritual" in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+### Changed
+
+- **`docs/architecture/FLOWS.md`** — refreshed Flow 3 (difficult task), 5 (skill creation), 8 (SWE retry), 9 (roundtable) to the bro-as-planner chain. Added Flow D (Direct Mode). Dropped stale references to `validate-swe-output` and `require-review-sign` (replaced by bro's verification protocol + `git-push-guard.sh` respectively).
+- **`docs/architecture/FILES.md`** — full file-map refresh: empty `agents/` (by design), 17 `tmb_*` protocol skills, 6 agent + 7 default-skill templates under `templates/`, multi-platform placeholders, current hook list (`git-push-guard.sh` instead of `require-review-sign.sh`), MCP test layout.
+- **`docs/architecture/ERD.md`** — updated "How agents use this" to bro-as-planner role matrix; bumped `plugin_meta.plugin_version` reference to 0.1.2.
+- **`CONTRIBUTING.md`** — design principles rewritten for the bro-as-planner doctrine (zero-shipped-subagents, Lego layering, server-enforced decision chain). Added multi-platform section. Pre-PR checklist expanded to cover template/skill layering and schema-touching changes.
+- **Performance doctrine relocated.** `docs/PERFORMANCE.md` was deleted; its load-bearing content (target latency band + Tier 1/2/3 trim doctrine + re-eval triggers) lives in [`CONTRIBUTING.md` § Performance](CONTRIBUTING.md#performance). Historical baseline + change-tracking now lives in git history + this changelog instead of a doc that grows stale every perf cycle.
+- **`tests/manual/scenarios.md`** — header updated to point at the bro-as-planner targets that ARE current; full template-rewrite still tracked in [#51](https://github.com/trustmybot/plugin/issues/51).
+
+### Versioning
+
+`.claude-plugin/plugin.json` and `mcp/trajectory-server/package.json` bumped 0.1.1 → 0.1.2. No schema migrations needed (still `schema_version=1`).
+
+---
+
 ## v0.1.1 — 2026-04-25
 
 **Patch release.** Single fix to `scripts/hooks/git-guards.sh` that affects projects using a dual-tier `dev`/`main` branching model.
@@ -77,7 +101,7 @@ Every Q&A, decision, task, validation, and ledger event lands in SQLite at `<pro
 
 ### Performance
 
-Layer 3 dogfood verification on a CLI-todo task: ~12 minutes wall-clock end-to-end (including one-time onboarding + bootstrap, planning, SWE work, push gate). The latency story is documented in [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md) with phase-by-phase timings, doctrine on what's safe to trim, and the candidates for future tuning.
+Layer 3 dogfood verification on a CLI-todo task: ~12 minutes wall-clock end-to-end (including one-time onboarding + bootstrap, planning, SWE work, push gate). The latency story shipped in `docs/PERFORMANCE.md` with phase-by-phase timings + trim doctrine; the doctrine moved into [`CONTRIBUTING.md` § Performance](CONTRIBUTING.md#performance) in v0.1.2.
 
 Trivial single-file edits via Direct Mode land in ~10–20s, approaching pure Claude.
 
@@ -96,7 +120,7 @@ Three layers:
 - `docs/architecture/FLOWS.md` — workflow flowcharts
 - `docs/architecture/FILES.md` — file-by-file map
 - `docs/architecture/ERD.md` — SQLite schema
-- `docs/PERFORMANCE.md` — latency budget + doctrine
+- `CONTRIBUTING.md` § Performance — latency budget + trim doctrine (relocated from `docs/PERFORMANCE.md` in v0.1.2)
 - `tests/manual/scenarios.md` — Layer 3 dogfood test plan
 
 ### Plugin manifest

CLAUDE.md

@@ -199,7 +199,7 @@ User-created project consultants (via `tmb_agent-creator` from-scratch flow) are
 - **Auto-regenerated architecture docs** — `docs/trustmybot/architecture/auto/`, refreshed via `architecture_regen`.
 - **Snapshots** — `docs/trustmybot/snapshots/<issue_id>.md`, generated via `issue_snapshot_md`.
 
-For `plugin_config` keys see `mcp/trajectory-server/docs/CONFIG_KEYS.md`. For full architecture see `docs/architecture/FLOWS.md`. For latency design + budgets see `docs/PERFORMANCE.md`.
+For `plugin_config` keys see `mcp/trajectory-server/docs/CONFIG_KEYS.md`. For full architecture see `docs/architecture/FLOWS.md`. For latency design + budgets see the Performance section in `CONTRIBUTING.md`.
 
 ---
 

CODEX.md

@@ -0,0 +1,21 @@
+# TMB on OpenAI Codex — placeholder
+
+> **Status: not implemented.** TMB ships Claude Code only as of v0.1.1. This file is a placeholder for the day a Codex adapter ships under `.codex-plugin/`.
+
+## What goes here when ready
+
+The bro persona doctrine, equivalent to Claude Code's `CLAUDE.md`:
+
+- The trigger word that activates bro on Codex (likely the same: "bro")
+- Codex-equivalent first-action chain (identity check → onboarding → bootstrap)
+- Codex-equivalent code-touching ask chain
+- Routing table mapping Codex's tool surface
+- Catchphrase + communication style (unchanged from CLAUDE.md)
+
+Most of the doctrine — the planning skill (`tmb_planning-simple` / `tmb_planning-difficult`), the SWE template, the push-gate flow, the bro-as-task-gate role — is already platform-agnostic. Only the trigger mechanism and tool-name mapping change between platforms.
+
+## See also
+
+- [`./CLAUDE.md`](./CLAUDE.md) — the canonical bro persona for Claude Code
+- [`./docs/multi-platform.md`](./docs/multi-platform.md) — the strategy
+- [`./.codex-plugin/`](./.codex-plugin/) — the manifest placeholder

CONTRIBUTING.md

@@ -12,12 +12,28 @@ Thanks for the interest. Public MIT-licensed plugin for Claude Code. Contributio
 
 ## Branching
 
-- `main` — release tip. Tags (`v0.3.2`, `v1.0.0`, …) live here.
-- `dev` — integration branch. All PRs land here first.
+- `main` — release tip. Tags (`v0.1.2`, `v1.0.0`, …) live here.
+- `dev` — integration branch. All work-branch PRs land here first.
 - Work branches — use `<type>/<issue-number>-<slug>`, e.g. `feat/42-dual-backend-issues`, `fix/45-gitguards-missing-branch`, `docs/27-local-testing`. Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`. Embedding the issue number makes every branch self-documenting and auto-links on PR merge.
 
 Direct commits to `dev` or `main` are blocked by `git-guards.sh`. Always work on a branch.
 
+**Releases** go via a `dev → main` PR (the only branch other than work-branches that can target `main`). The hook in `git-guards.sh` permits exactly this case while still blocking `feature → main` PRs (the v0.1.1 release exception).
+
+### Release ritual
+
+Releases are scripted, idempotent, and gated by safety checks. The full ritual:
+
+1. On a work branch off `dev`, bump `version` in both `.claude-plugin/plugin.json` and `mcp/trajectory-server/package.json`. Add the matching `## v<X.Y.Z>` section at the top of `CHANGELOG.md`. Commit + PR into `dev` like any other change.
+2. Once that's merged into `dev`, open a `dev → main` PR. Merge it.
+3. Locally:
+   ```bash
+   git checkout main && git pull origin main
+   bash scripts/release.sh
+   ```
+
+`scripts/release.sh` reads the version from `plugin.json`, validates that `mcp/trajectory-server/package.json` agrees, requires a matching `## v<version>` section in `CHANGELOG.md`, and asks for `y/N` confirmation at each step. It tags `main` HEAD, pushes the tag, and creates a GitHub release with the CHANGELOG section as the body. Re-running after a step succeeds is safe — already-done steps are skipped.
+
 ## Writing code
 
 - Self-documenting code. Prefer deletion over addition.
@@ -35,10 +51,12 @@ Every code change should add or update tests.
 
 ## Pre-PR checklist
 
-- [ ] `bash tests/run-all.sh` passes locally.
+- [ ] `bash tests/run-all.sh` passes locally (lint + MCP integration + hook suites).
 - [ ] Workflow state (issues, tasks, discussions, validation attempts) goes through MCP tools into SQLite — never onto disk.
 - [ ] `CHANGELOG.md` updated for user-visible changes.
-- [ ] If the edit affects a workflow contract, update every agent prompt that cites it — not just one.
+- [ ] If the edit affects a workflow contract, update every agent template body AND every consuming skill that cites it — not just one. Remember: agent templates are the immutable Lego stud, skills are the bricks. Behavior changes go in skills; identity changes go in templates.
+- [ ] If the edit changes a `tmb_*` skill's contract, also update the lint assertions in `tests/lint/` if a contract is involved.
+- [ ] If the edit touches the SQLite schema, regenerate the ER diagram in `docs/architecture/ERD.md` and update the `requireRoles` matrix in `mcp/trajectory-server/src/middleware/agent-scope.ts`.
 - [ ] PR description names the issue (`Closes #N`).
 
 ## Filing an issue
@@ -52,9 +70,36 @@ Every code change should add or update tests.
 If you're proposing a big change, check these first.
 
 1. **SQLite is canonical state.** Files are for SE convention (README, CHANGELOG, ADRs) or agent-loaded context (prompts, skills, rules). Workflow state (issues, tasks, discussions, validation attempts) lives in the trajectory DB, never on disk.
-2. **No bypass in the workflow.** Every code change routes bro → architect → swe → pr-reviewer. The "fast path" is a lighter task spec, not skipping a role.
-3. **Plugin is an agent factory.** Four workflow agents ship (bro, architect, swe, pr-reviewer). Domain agents (ceo, cto, pm, legal-reviewer, …) are user-created on-demand via the `agent-creator` skill with explicit Human approval.
-4. **Override per project.** Any plugin-shipped agent can be overridden by creating a same-named file in the project's `.claude/agents/`. Local wins.
+2. **No bypass in the workflow.** Every non-trivial code change routes Human → bro → SWE, with bro as the **task gate** (verifies after SWE returns) and pr-reviewer as the **push gate** (fires only at `git push`). The "fast path" is a lighter spec, not skipping a gate. Direct Mode is the single narrow exception (≤3 lines, single file, no API/test/docs change).
+3. **Plugin ships ZERO subagents.** Bro is a CLAUDE.md persona on main Claude. SWE, pr-reviewer, and the 4 consultant templates (architect, cto, ceo, pm) live in `templates/agents/` and are copied into `<project>/.claude/agents/` on demand. Domain agents (legal-reviewer, security-reviewer, …) are user-created via the `tmb_agent-creator` skill with explicit Human approval.
+4. **Lego layering.** Three layers, never confused: agent file = identity (immutable), `skills:` array on the project copy = capabilities (additive via `tmb_skill-creator`), spawn prompt = task context (per-call). Don't edit the template body to add behavior — extend `skills:`.
+5. **Override per project.** Any agent template can be overridden by editing the same-named file in the project's `.claude/agents/`. Local wins. Plugin-shipped protocol skills (`tmb_*` in `plugin/skills/`) are reserved and cannot be name-overridden.
+6. **Server-enforced decision chain.** `requireRoles` middleware in `mcp/trajectory-server/src/middleware/agent-scope.ts` rejects calls that violate the chain (e.g. consultants trying to write `task_create_batch`). Doctrine isn't just prompt discipline — it's wire-enforced.
+
+## Performance
+
+The plugin's overhead vs pure Claude Code on the same ask should land in this band:
+
+| Ask shape | Pure Claude | TMB target | Acceptable ceiling |
+|---|---|---|---|
+| Trivial single-file (typo, comment) | ~10s | ~10–20s (Direct Mode) | 30s |
+| Simple task (single feature) | ~30s | ~2–3 min | 5 min |
+| Difficult task (architecture change + ADR) | ~2 min | ~5–8 min | 12 min |
+| Multi-task batch | n/a | ≤ 1.5× single-task per task | 2× per task |
+
+**Doctrine — what's safe to trim, what isn't.** When proposing a perf change, classify the cost into one of three tiers:
+
+- **Tier 1 — pure waste, trim aggressively.** Sequential MCP writes that could batch in one assistant response; eager skill loading that fires on every spawn but is needed in <30% of spawns; forced chain-of-thought blocks for tasks that don't benefit; redundant approval prompts.
+- **Tier 2 — design overhead, trim with care.** Per-task gate spawns (justified for difficult-triage, not for every typo — hence the push-gate vs task-gate split); worktree creation; forced subagent cold-start when bro could just edit (hence Direct Mode).
+- **Tier 3 — load-bearing overhead, do NOT trim.** The trajectory DB writes (the audit trail IS the product); `requireRoles` enforcement (~1ms, structural protection); worktree isolation (prevents cross-task corruption); the push gate (only structural defence against pushing unreviewed commits).
+
+**Re-evaluate** when (a) a SWE or pr-reviewer cold-start in a Layer 3 dogfood takes >2× the previous baseline, (b) a user reports a chain >12 min for a simple-triage task, (c) a new gate / hook / skill fires on the per-task path, (d) CC platform changes subagent cold-start cost, or (e) a new platform adapter (Codex, Cursor, …) gets implemented — re-baseline on that platform.
+
+Historical perf-cycle records live in git history (PR #63 baseline, PR #64 optimizations) and the changelog, not in a separate doc.
+
+## Multi-platform structure
+
+The repo follows the [`obra/superpowers`](https://github.com/obra/superpowers) pattern: shared `skills/`, `templates/`, and `mcp/` at the root, with thin per-platform manifests in `.<platform>-plugin/` directories. Today only `.claude-plugin/` is implemented; `.codex-plugin/`, `.cursor-plugin/`, `.opencode/`, and `gemini-extension.json` are placeholders. See [`docs/multi-platform.md`](docs/multi-platform.md) for the strategy and what an adapter would do. Adapters get built when there's user demand; until then, contributions should target Claude Code only.
 
 ## Code of conduct
 

CURSOR.md

@@ -0,0 +1,18 @@
+# TMB on Cursor — placeholder
+
+> **Status: not implemented.** TMB ships Claude Code only as of v0.1.1. This file is a placeholder for the day a Cursor adapter ships under `.cursor-plugin/`.
+
+## What goes here when ready
+
+The bro persona doctrine, equivalent to Claude Code's `CLAUDE.md`:
+
+- The trigger word that activates bro on Cursor
+- Cursor-equivalent first-action chain
+- Cursor-equivalent push gate (Cursor's hook system is event-driven; the equivalent of `git-push-guard.sh` lives under `../hooks/cursor/`)
+- Tool-name mapping (Cursor's Read/Edit/Bash equivalents)
+
+## See also
+
+- [`./CLAUDE.md`](./CLAUDE.md) — the canonical bro persona for Claude Code
+- [`./docs/multi-platform.md`](./docs/multi-platform.md)
+- [`./.cursor-plugin/`](./.cursor-plugin/)