🌐 chore: multi-platform placeholder structure (Codex, Cursor, OpenCode, Gemini)#73
Merged
Conversation
…e, Gemini) Per Zax's vision: TMB shouldn't be Claude-Code-only forever. Following [obra/superpowers](https://github.com/obra/superpowers)' canonical pattern — shared skills/agents/MCP at the root, thin per-platform manifests in `.<platform>-plugin/` adapters — this commit lays the structural groundwork without claiming features that don't exist yet. ### Explicit goal: placeholders, not pretend-support Every new file says "PLACEHOLDER — not implemented." TMB ships Claude Code only as of v0.1.1. The multi-platform directories exist so: 1. **Discoverability** — anyone browsing the repo sees `.codex-plugin/` and immediately understands the vision. 2. **Path-precedent** — when we DO ship an adapter, the directory structure is already there. Implementation shrinks to "fill in the manifest" rather than "restructure the repo." ### Files added ``` .codex-plugin/ ├── plugin.json # placeholder manifest └── README.md # "not implemented" + pointer to docs/multi-platform.md .cursor-plugin/ # same shape .opencode/ # README only (OpenCode uses entry-point JS, no manifest) gemini-extension.json # root-level manifest per Gemini convention CODEX.md # placeholder for the Codex bro persona CURSOR.md # placeholder for the Cursor bro persona GEMINI.md # placeholder for the Gemini context file docs/multi-platform.md # strategy doc — what's portable, what's # platform-specific, when adapters get built, # cross-reference to Superpowers as the canonical # example ``` ### README update Added a banner section after the headline noting that TMB ships Claude Code only today + structural readiness for other platforms. Sets reader expectations: don't try `/plugin install tmb@<other-platform>` and be surprised it doesn't exist. ### What stayed unchanged - `.claude-plugin/` — still the only working adapter - `agents/`, `templates/agents/`, `templates/skills/`, `skills/` — already cross-platform-shaped (most content portable; Claude-specific frontmatter on agent templates would need adapter-side translation) - `mcp/trajectory-server/` — already cross-platform (MCP is the emerging standard across Anthropic, OpenAI, Cursor) - `hooks/`, `scripts/hooks/` — currently Claude-specific. Future per-platform layout would be `hooks/<platform>/`; not today. ### Layer 1 + 2 status ``` Onboarding contract lint: PASS Lego cap (≤30 lines): PASS MCP server unit + integration: PASS Hook tests: PASS ``` No code, skill, agent, or hook behavior changed. Pure additive structure. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
11 tasks
CHANGELOG, plugin.json, mcp pkg.json bumped 0.1.1 → 0.1.2. - FLOWS.md: refreshed Flow 3/5/8/9 to bro-as-planner; added Flow D (Direct Mode); replaced require-review-sign with git-push-guard; dropped validate-swe-output references. - FILES.md: full file-map refresh (empty agents/, tmb_-prefixed protocol skills, templates/, multi-platform placeholder dirs, current MCP test layout). - ERD.md: "How agents use this" rewritten for bro-as-planner role matrix; bumped plugin_version reference. - CONTRIBUTING.md: design principles 2-6 rewritten (zero shipped subagents, Lego layering, server-enforced chain). Added multi- platform section. Pre-PR checklist expanded. - PERFORMANCE.md: clarified v0.1.1/v0.1.2 didn't change perf; added re-evaluation trigger for future platform adapters. - scenarios.md: header updated; full template-rewrite still in #51. No agent / hook / MCP behavior change — docs-only release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…release.sh Reads version from plugin.json (single source of truth) instead of hardcoding. Validates mcp/trajectory-server/package.json agrees. Requires a matching '## v<version>' CHANGELOG section. Same y/N-per-step idempotent flow as the v0.1.0 script (tag → push → gh release create). Drops the one-time v0.2.0 revoke step. Strips trailing '---' separators from extracted CHANGELOG notes so the release body doesn't end with a horizontal rule. Documented as the "Release ritual" section in CONTRIBUTING.md so the next release just runs: git checkout main && git pull origin main bash scripts/release.sh Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restructured README to lead with the three structural pillars that
distinguish TMB from single-agent Claude Code:
1. Agent Harness — split planning (bro) from execution (swe), with
wire-enforced separation via requireRoles middleware.
2. Trajectory Memory — per-project SQLite that survives session kills.
3. Agentic Workflow — bro's task gate + pr-reviewer's push gate, both
hook-enforced.
Each pillar carries a "single-agent equivalent" comparison and links to
the deep doc for that area (CLAUDE.md, FLOWS.md, ERD.md, FILES.md,
PERFORMANCE.md, swe.md, pr-reviewer.md).
Drops:
- "Compared to adjacent tools" comparison table
- claude-mem / claude-brain attribution
- Superpowers reference (kept in docs/multi-platform.md only, where it
remains technical attribution for the structural pattern)
Order is install → how to use → why TMB → roster on disk → contributing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The single-agent comparison in pillar #1 was too soft. "Marking your own homework" is the standard English idiom for the exact conflict of interest — same actor judging their own work — and lands harder than the vaguer "wishful thinking" phrasing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "Single-agent equivalent:" label was too vague. Renamed each pillar callout to lead with the specific failure mode the structural gap creates: Pillar 1 → Single-agent (conflict of interest) Pillar 2 → Single-agent (amnesia) Pillar 3 → Single-agent (no brakes) Pillar 1 also adds the SV-native framing — "you should never trust a guy self-merging their own PR" — alongside the British "marking its own homework" idiom. Two angles on the same conflict-of-interest scenario, one British, one Silicon Valley. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ence Trajectory Memory wasn't just about resume — it's also a structural token saver because each agent only loads the slice it needs: - SWE gets task_get(id) → ~1-2KB spec, not the full discussion - Bro doesn't carry SWE's tool outputs forward (they land in audit) - Consultants return distilled analyses, not raw reasoning - issue_resume returns a tight summary, not the full session replay Renamed the pillar 2 single-agent failure mode from "amnesia" to "amnesia + bloat" since the corollary of no persistence is also that the single context grows linearly with conversation length. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PERFORMANCE.md was 2/3 PR-cycle ephemera (PR #63 baseline timeline, "changes shipped in #64" table, "verification pending" TODO) and 1/3 evergreen doctrine (target latency band, Tier 1/2/3 trim guidance, re-eval triggers). The ephemera was rotting on every perf cycle. Moved the evergreen 1/3 into CONTRIBUTING.md § Performance. Deleted the doc. Filed #75 as a standing re-baseline issue — opens when a re-eval trigger fires, closes when the timing posts back to green. Updated references: - README.md → links to CONTRIBUTING.md#performance - CLAUDE.md → same - FILES.md → drops the doc from the file map - CHANGELOG.md → notes the relocation in v0.1.2 and updates the v0.1.0 historical references so they're not broken links Doctrine durable in CONTRIBUTING.md. Measurements ephemeral in issues + git. No more standing doc that grows stale. Closes the perf-doc-staleness side of the v0.1.2 cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Previous framing led with per-agent context split (SWE doesn't see
bro's conversation, consultants return distilled analyses, etc.) —
but that's really an Agent Harness benefit, not a Trajectory Memory
benefit.
The genuine memory-side token win is sidestepping the codebase-
rediscovery tax that single-agent setups pay every cold start:
- Auto-regen pipeline pre-computes codebase-tree.md, module-graph.md,
erd.md, changelog.md (~4 files, ~20 KB). Bro reads those once and
knows the project shape — no glob+read round-trips bouncing into
context.
- Local SQLite means no remote memory service, no API round-trips,
no rate limits. issue_resume is one local read.
Renamed the failure mode from "amnesia + bloat" to "amnesia +
rediscovery tax" since that's the precise cost: the agent re-derives
the project from scratch every cold start.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Single line — make it explicit that the tasks table is the hand-off contract: bro plans, swe executes. Reinforces the agent harness story when reading pillar 2. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The bare '## Verification' / '## Files' / '## Success Criteria' refs read like markdown headings in the README itself, which is confusing. They're actually section headings inside each task-spec markdown body that bro writes to MCP and SWE reads back. Made the convention explicit in one sentence — "every task spec is a markdown contract with three sections" — so the reader understands what bro is checking against on the verification step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User's feedback: too many script paths, SQL columns, and MCP tool names
in a repo-level README. The example was pillar 3's
"scripts/hooks/git-push-guard.sh blocks git push to protected branches
until every commit in the push range has a passing
validation_attempts.verdict='pass' row" — but the principle extends.
Changes:
Pillar 1: "requireRoles middleware in the bundled MCP server rejects
out-of-role calls" → "Out-of-role calls are rejected at the wire."
Pillar 2: drops issue_resume, task_get, the .claude/tmb/trajectory.db
path, the docs/trustmybot/architecture/auto/ path, and the ≥25-commit
threshold. Concept stays — pre-computed snapshots, local SQLite — the
exact paths/numbers move to FLOWS.md / ERD.md / FILES.md.
Pillar 3: drops the script name, the SQL column reference, requireRoles,
and the MCP tool list. Now reads as plain English: "git push blocked by
a pre-push hook unless every commit's been signed off." Wire-enforcement
framing kept (it's the doctrine), specific function names dropped.
State-table list in pillar 2 keeps its table names — that's conceptual
disclosure ("here are the buckets your data lives in"), not enforcement
leak. Curious readers click through to ERD.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User's restructure: Evaluation deserves its own pillar because it's where the long-term-engineering-quality story lives. Splitting it from "Agentic Workflow" makes both sharper. New shape: 1. Agent Harness — split planning from execution (the WHO) 2. Trajectory Memory — state + token dividend (the WHAT-PERSISTS) 3. Evaluation System — gates + persisted audit trail (the QUALITY-FLOOR) 4. Agentic Workflow — composable workflow shapes (the HOW-IT-FLOWS) Pillar 3 (Evaluation) leads with "Long-term engineering quality decays when verification is implicit" — the load-bearing why TMB exists. Both gates (bro's task gate + pr-reviewer's push gate) live here. Crucial new framing: verdicts persist next to the code they judged in the trajectory DB, so the *reasoning* survives, not just the diff. Bridges back to pillar 2. Pillar 4 (Workflow) reframes around the four ask shapes (Direct Mode, simple, difficult, batch) — the "scales by ask" story is what makes the agentic workflow actually useful, not just a fixed pipeline. Failure-mode pattern continues: P1: conflict of interest P2: amnesia + rediscovery tax P3: no audit P4: one-shape-fits-all Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Lays the multi-platform structural groundwork without claiming features that don't exist. TMB still ships Claude Code only as of v0.1.1 — but anyone browsing the repo now sees
.codex-plugin/,.cursor-plugin/,.opencode/,gemini-extension.jsonand immediately understands the vision.Pattern lifted from obra/superpowers: single shared source-of-truth (
skills/,templates/agents/,mcp/) + thin per-platform manifests under.<platform>-plugin/adapters that point at the shared content via relative paths. No content duplication.Files added
.codex-plugin/{plugin.json,README.md}.cursor-plugin/{plugin.json,README.md}.opencode/README.mdgemini-extension.jsonCODEX.md,CURSOR.md,GEMINI.mddocs/multi-platform.mdREADME.mdupdatedHard rule per file
Every placeholder file says "PLACEHOLDER — not implemented" explicitly. We don't pretend to support what we don't. Sets reader expectations: don't try
/plugin install tmb@<other-platform>expecting it to work.What this does NOT do
When adapters actually get built
Driven by user demand. Tracking issue (filed alongside this PR) covers per-platform roadmap. If 100 people ask for Codex support, we build a Codex adapter. If nobody asks, the placeholders stay placeholders forever — and the repo still benefits from the structural clarity.
Layer 1 + 2 status
Pure additive — zero behavior change.
🤖 Generated with Claude Code