diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f76bcf7..57281da0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,16 @@ All notable user-visible changes to the TMB plugin. Versions follow [SemVer](htt ## Unreleased +### Refactored — all plugin-shipped skills now use `tmb_` prefix + +The 7 default workflow skills (`code-quality`, `docs-conventions`, `git-conventions`, `naming-conventions`, `review-findings`, `review-protocol`, `swe-checklist`) were the only plugin-shipped skills without the `tmb_` namespace prefix — an inconsistency with the rule "global plugin skills use `tmb_`; the open namespace is reserved for user/`tmb_skill-creator`-generated project-local skills." Renamed to `tmb_code-quality`, `tmb_docs-conventions`, … + +**Why it matters**: collision-free open namespace. Previously, if a user asked bro to create a `git-conventions` skill, it could collide with the plugin default. Now the open namespace is exclusively user-owned and the plugin-shipped namespace is fully claimed by `tmb_*`. + +**Override semantics unchanged**: a project-local `/.claude/skills/tmb_git-conventions/SKILL.md` still shadows the plugin's by name resolution. The "reservation" was always a social/lint convention, never a CC-enforced lock. + +**Refs updated**: `agents/swe.md`, `docs/AGENTS.md`, `docs/architecture/FILES.md`, `docs/architecture/FLOWS.md`, and 6 cross-referencing SKILL.md files. `CHANGELOG.md` history entries left intact (accurate records of the un-prefixed era). + ### Added — activation-routine UserPromptSubmit hook (#108) Bro's activation routine (`identity_get` + `issue_resume` on every triggered message) is now fired deterministically by `scripts/hooks/activation-routine.sh` instead of relying on prompt discipline. The h4 A/B (5 paired runs × 2 wording arms) showed prompt compliance was 0/10 in *both* arms — the strongest possible imperative ("MANDATORY on every triggered message") still didn't move the needle. With prompt-only enforcement structurally unreliable for high-frequency operations, the only honest fix is to wire it into code. diff --git a/CLAUDE.md b/CLAUDE.md index f58abe1d..e909266f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,17 +21,22 @@ Single Human entry point, planner, and task gate. You discuss, design the implem ## Before answering — verify context -**Don't guess. Don't fabricate. Don't be a yes-man.** Before you plan, decide, or answer a substantive question, run two checks: - -1. **Context check** — *do I have enough?* The trajectory DB is this project's source of truth for plugin state (`file_registry`, `ledger`, `discussions`, `tasks`, plus the auto-regenerated `docs/architecture/`). Query it FIRST via MCP tools. Then branch by state: - - **Git clean** → trust the trajectory DB's `file_registry` index. Don't ad-hoc-browse the codebase. - - **Git dirty** → diff against the trajectory DB index; reach for `Read` / `Glob` / `Grep` only on the changed files. - - **After you Read a file for context** (#45) → if its `summary` was null, follow with `file_registry_update_summaries(updates=[{path, summary: ''}])`. Costs ~5ms; the summary you'd think anyway. Keeps the index alive without an upfront scan. - - **First-time onboarding to an existing repo** OR **right after finishing system design of a new project** → run `tmb_project-prescan` (then `tmb_refresh-architecture` if architecture docs need regeneration) to populate / refresh the index. Don't ad-hoc this either — the scan skill is the canonical way. - - **Upstream specs / external standards / library docs** → web (`WebFetch` / `WebSearch`). - - **Training-data fallback** — last resort, flag it as such. - If context is thin after the lookup, **say so** and ask the Human. Thin context → *"I'm not sure, checking…"* beats inventing. -2. **Standards check** — *is what I'm about to recommend the industry standard or the best way?* If you're not sure, do the lookup. If a domain expert (legal, security, perf, etc.) would handle it better than bro, propose `tmb_agent-creator` to spawn the specialist. Bro should be professional and competent across general SWE work; for genuinely specialized domains, escalate. +**Don't guess. Don't fabricate. Don't be a yes-man.** Two checks before any substantive answer: + +1. **Context check** — *do I have enough?* The trajectory DB is the source of truth (`file_registry`, `ledger`, `discussions`, `tasks`, plus auto-regenerated `docs/architecture/`). Query it FIRST. Pick the source by state: + + | Situation | Where to look | + |---|---| + | Git clean | Trust the trajectory DB's `file_registry` index. No ad-hoc browsing. | + | Git dirty | Diff against `file_registry`; `Read` / `Glob` / `Grep` only the changed files. | + | After you Read a file for context | If its `summary` was null, follow with `file_registry_update_summaries(updates=[{path, summary: '...'}])`. ~5ms; keeps the index alive. | + | First-time onboarding to an existing repo, or right after system-design of a new project | `tmb_project-prescan` (then `tmb_refresh-architecture` if arch docs need regen). Canonical scan path — don't ad-hoc. | + | Upstream specs / external standards / library docs | `WebFetch` / `WebSearch` | + | Training-data fallback | Last resort. Flag it. | + + If context is thin after the lookup, **say so** and ask. *"I'm not sure, checking…"* beats inventing. + +2. **Standards check** — *is this the industry standard or the best way?* If unsure, look it up. If a domain expert (legal, security, perf, etc.) would handle it better than bro, propose `tmb_agent-creator` to spawn the specialist. When you're guessing, label it. Cite the source when relevant. diff --git a/agents/swe.md b/agents/swe.md index 248f34bd..4d9fe592 100644 --- a/agents/swe.md +++ b/agents/swe.md @@ -18,6 +18,6 @@ Atomic close (#W4): batch in one response — commit (using the spec's `## Commi Never push. Never commit secrets. Never edit outside the worktree. Never author the spec body — that's bro's role and the server enforces it. **Never attempt to bypass a PreToolUse hook block** — do not rewrite `.git/HEAD`, fabricate refs, edit `.git/` internals, or use any technique to evade a hook decision. If a hook blocks a legitimate operation, that's a plugin bug — STOP immediately, return the failure summary to bro with the exact hook output, and let bro decide the path forward. Bypass attempts trip CC's security guards and erode the doctrine these hooks exist to enforce. -If you need a stack-specific verification checklist, invoke the project's `swe-checklist` skill via the Skill tool **only when the spec's `## Verification` section needs interpretation** — not by default. Stack-specific style/pattern rules come from skills the project attaches to this agent's `skills:` list — never edit this file. +If you need a stack-specific verification checklist, invoke the project's `tmb_swe-checklist` skill via the Skill tool **only when the spec's `## Verification` section needs interpretation** — not by default. Stack-specific style/pattern rules come from skills the project attaches to this agent's `skills:` list — never edit this file. **Do not read project-level `CLAUDE.md`** — that file is bro's persona; this agent's prompt is canonical for SWE work. diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 75001dbc..8e32b974 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -42,12 +42,12 @@ Never confuse layers: a "more skilled SWE" means swe.md plus added skills, not a `skills/` holds both the `tmb_*` protocol skills (immutable, reserved by plugin) AND the default workflow skills used by global agents: -- `swe-checklist` -- `code-quality` -- `docs-conventions` -- `git-conventions` -- `naming-conventions` -- `review-protocol` -- `review-findings` +- `tmb_swe-checklist` +- `tmb_code-quality` +- `tmb_docs-conventions` +- `tmb_git-conventions` +- `tmb_naming-conventions` +- `tmb_review-protocol` +- `tmb_review-findings` All are globally discoverable. Project-local `/.claude/skills//SKILL.md` overrides by name. Onboarding does NOT copy skills into projects — the global ones serve every project until a customization is needed. diff --git a/docs/architecture/FILES.md b/docs/architecture/FILES.md index 75c4124c..17a6268c 100644 --- a/docs/architecture/FILES.md +++ b/docs/architecture/FILES.md @@ -73,13 +73,13 @@ plugin/ │ ├── tmb_skill-creator/ # propose & write new skill files; appends to consuming agent's skills: │ ├── tmb_swe-spawn-workflow/ # bro's protocol for spawning SWE with task_id + spec │ ├── # Default workflow skills (used by global agents; project overrides per-name) -│ ├── code-quality/ # generic quality gates (error handling, security, edges) -│ ├── docs-conventions/ # docs-update rules + prompt-editing discipline -│ ├── git-conventions/ # emoji-prefixed commits, branch naming -│ ├── naming-conventions/ # file/variable/test naming rules -│ ├── review-findings/ # pr-reviewer output format -│ ├── review-protocol/ # pr-reviewer full protocol -│ └── swe-checklist/ # SWE pre-commit checklist (lazy-loaded by SWE on demand) +│ ├── tmb_code-quality/ # generic quality gates (error handling, security, edges) +│ ├── tmb_docs-conventions/ # docs-update rules + prompt-editing discipline +│ ├── tmb_git-conventions/ # emoji-prefixed commits, branch naming +│ ├── tmb_naming-conventions/ # file/variable/test naming rules +│ ├── tmb_review-findings/ # pr-reviewer output format +│ ├── tmb_review-protocol/ # pr-reviewer full protocol +│ └── tmb_swe-checklist/ # SWE pre-commit checklist (lazy-loaded by SWE on demand) │ ├── # Consultant templates (opt-in — copied per-project on first request via tmb_agent-creator) ├── templates/ diff --git a/docs/architecture/FLOWS.md b/docs/architecture/FLOWS.md index b543e61e..32a8f6ad 100644 --- a/docs/architecture/FLOWS.md +++ b/docs/architecture/FLOWS.md @@ -14,7 +14,7 @@ > and are instantiated per-project on demand via `tmb_agent-creator`. > > All skills — both `tmb_*` protocol skills and the default workflow -> skills (`swe-checklist`, `code-quality`, `docs-conventions`, etc.) — +> skills (`tmb_swe-checklist`, `tmb_code-quality`, `tmb_docs-conventions`, etc.) — > live in `plugin/skills/` and are globally discoverable. Project-local > `/.claude/skills//SKILL.md` overrides by name. @@ -27,11 +27,11 @@ Companion docs: [`ERD.md`](ERD.md) for schema, [`FILES.md`](FILES.md) for the fi | # | Flow | Trigger | Agents | Key skills | DB tables touched | Hooks | |---|---|---|---|---|---|---| | 1 | [First contact](#1-first-contact-defaults-applied-silently) | First activation in a project | bro | (none — inline default-write) | `plugin_config`, `ledger` | — | -| 2 | [Simple task](#2-simple-task) | Code change, no architecture impact | bro → swe (pr-reviewer at push time only) | `tmb_planning-simple` (bro), `swe-checklist` (lazy on demand) | `issues`, `tasks`, `ledger` (per task) + `validation_attempts` (at push) | `require-task-spec`, `git-push-guard`, `git-guards` | +| 2 | [Simple task](#2-simple-task) | Code change, no architecture impact | bro → swe (pr-reviewer at push time only) | `tmb_planning-simple` (bro), `tmb_swe-checklist` (lazy on demand) | `issues`, `tasks`, `ledger` (per task) + `validation_attempts` (at push) | `require-task-spec`, `git-push-guard`, `git-guards` | | 3 | [Difficult task](#3-difficult-task) | Code change touching `docs/trustmybot/architecture/` | bro (full discussion + ADR) → swe (pr-reviewer at push time) | + `tmb_planning-difficult` (env probe, Q+A, ADR) | + `discussions`, ADR file | same | | 4 | [Agent-creator](#4-agent-creator-on-demand-domain-agent) | Routing hits a role not in `.claude/agents/` | bro → human | `tmb_agent-creator` | — | — | | 5 | [Skill creation](#5-skill-creation) | Recurring pattern needs encoding | bro | `tmb_skill-creator` | `skills` (optional, for tracking) | — | -| 6 | [Push gate / PR review](#6-push-gate--pr-review) | `git push` to protected branch | bro → pr-reviewer (one per unsigned task, parallel) | `review-protocol`, `review-findings`, `code-quality` | `tasks` (read), `validation_attempts` (write), `discussions` (optional FAIL) | `git-push-guard` | +| 6 | [Push gate / PR review](#6-push-gate--pr-review) | `git push` to protected branch | bro → pr-reviewer (one per unsigned task, parallel) | `tmb_review-protocol`, `tmb_review-findings`, `tmb_code-quality` | `tasks` (read), `validation_attempts` (write), `discussions` (optional FAIL) | `git-push-guard` | | 7 | [Architecture regen](#7-architecture-regen) | First code-touching ask of session OR `/tmb refresh-architecture` | bro | `tmb_refresh-architecture`, `tmb_lazy-regen-check` | `regen_state`, `file_registry` | — | | 8 | [SWE retry / escalation](#8-swe-retry--escalation) | Bro verification or pr-reviewer verdict='fail' | bro ↔ swe (↔ pr-reviewer when at push gate) | `tmb_feedback-loop` | `validation_attempts` (multiple rows), `discussions` | `git-push-guard` | | 9 | [Roundtable](#9-roundtable-multi-agent-deliberation) | Multi-consultant deliberation | bro orchestrates 2-4 project-local consultants | `tmb_roundtable`, `tmb_roundtable-cleanup` | `discussions`, `ledger` (and reserved: `roundtables`, `roundtable_votes`) | — | @@ -88,7 +88,7 @@ sequenceDiagram **Involved:** - Agents: `bro` (planner + task gate), `swe` (executor) - Skills loaded by bro on demand: `tmb_planning-simple` or `tmb_planning-difficult` per triage, `tmb_swe-spawn-workflow` (right before SWE handoff) -- Skills loaded by swe: `swe-checklist` **only on demand** (when spec verification needs interpretation; not eager) +- Skills loaded by swe: `tmb_swe-checklist` **only on demand** (when spec verification needs interpretation; not eager) - MCP tools: `issue_create`, `discussion_append`, `task_create_batch`, `task_get`, `task_update_status`, `ledger_log` (no `validation_record` per task — that fires at push time) - DB tables: `issues`, `tasks`, `discussions`, `ledger`, `audit` - Hooks: `require-task-spec` (gates SWE spawn), `git-push-guard` (gates `git push`), `git-guards` (commit branch check) diff --git a/skills/code-quality/SKILL.md b/skills/tmb_code-quality/SKILL.md similarity index 99% rename from skills/code-quality/SKILL.md rename to skills/tmb_code-quality/SKILL.md index e3f611c1..865cf74f 100644 --- a/skills/code-quality/SKILL.md +++ b/skills/tmb_code-quality/SKILL.md @@ -1,5 +1,5 @@ --- -name: code-quality +name: tmb_code-quality description: Shared quality criteria for design, implementation, and review. Used by bro (design-time), SWE (implementation-time), and PR Reviewer (review-time). Covers error handling, edge cases, database safety, Python patterns, test isolation, and the self-review checklist. --- @@ -195,4 +195,4 @@ Run before reporting COMPLETED. If any item fails, fix it. **CRITICAL: Every code change must be tested before reporting COMPLETED.** Untested code is rejected. Lint/build passing is necessary but NOT sufficient — you must run the corresponding unit tests and, for behavioral changes, verify the actual runtime behavior. If tests don't exist for the changed code, note that in your report. -> Common review findings: `skills/review-findings/SKILL.md` +> Common review findings: `skills/tmb_review-findings/SKILL.md` diff --git a/skills/tmb_concerns-protocol/SKILL.md b/skills/tmb_concerns-protocol/SKILL.md index d27da9ca..5678006e 100644 --- a/skills/tmb_concerns-protocol/SKILL.md +++ b/skills/tmb_concerns-protocol/SKILL.md @@ -36,7 +36,7 @@ Use when the concern is about HOW the work is being framed — scope, ordering, ### Path B — Spawn a consultant (technical disagreement) -Use when the concern is technical — architecture, security, performance, code-quality — and you want an independent read. +Use when the concern is technical — architecture, security, performance, tmb_code-quality — and you want an independent read. 1. Identify the relevant consultant (`architect`, `cto`, etc.). If absent, invoke `tmb_agent-creator` first. 2. Spawn the consultant with `consultant: analysis-only` marker and the specific question. diff --git a/skills/docs-conventions/SKILL.md b/skills/tmb_docs-conventions/SKILL.md similarity index 99% rename from skills/docs-conventions/SKILL.md rename to skills/tmb_docs-conventions/SKILL.md index e6ab63f0..2072184c 100644 --- a/skills/docs-conventions/SKILL.md +++ b/skills/tmb_docs-conventions/SKILL.md @@ -1,5 +1,5 @@ --- -name: docs-conventions +name: tmb_docs-conventions description: When and how to update docs alongside code changes, plus the discipline for editing agent prompts and skill files. agent: bro, swe, pr-reviewer --- diff --git a/skills/tmb_feedback-loop/SKILL.md b/skills/tmb_feedback-loop/SKILL.md index b7208806..1573a1cb 100644 --- a/skills/tmb_feedback-loop/SKILL.md +++ b/skills/tmb_feedback-loop/SKILL.md @@ -19,22 +19,22 @@ Every bug caught after SWE submits is a system failure. Learn from it. For each bug: 1. **Is this new or known?** - - Check `skills/review-findings/SKILL.md` and `skills/code-quality/SKILL.md` + - Check `skills/tmb_review-findings/SKILL.md` and `skills/tmb_code-quality/SKILL.md` - If already covered → agent ignored criteria - If NOT covered → gap, proceed to Q2 2. **Where should knowledge live?** - - Specific code pattern → `skills/review-findings/SKILL.md` - - Design-time question → `skills/code-quality/SKILL.md` - - Implementation rule → `skills/code-quality/SKILL.md` + - Specific code pattern → `skills/tmb_review-findings/SKILL.md` + - Design-time question → `skills/tmb_code-quality/SKILL.md` + - Implementation rule → `skills/tmb_code-quality/SKILL.md` 3. **Was the task underspecified?** - If SWE had to guess → update task template or quality checklist ## Format for New Entries -- review-findings.md: `- **[pattern name]** — [what happens]. [why wrong]. [what to do].` -- code-quality.md: `- [concise check — one line, actionable]` +- tmb_review-findings.md: `- **[pattern name]** — [what happens]. [why wrong]. [what to do].` +- tmb_code-quality.md: `- [concise check — one line, actionable]` ## What NOT to Add diff --git a/skills/git-conventions/SKILL.md b/skills/tmb_git-conventions/SKILL.md similarity index 99% rename from skills/git-conventions/SKILL.md rename to skills/tmb_git-conventions/SKILL.md index 2b39b01b..cb028819 100644 --- a/skills/git-conventions/SKILL.md +++ b/skills/tmb_git-conventions/SKILL.md @@ -1,5 +1,5 @@ --- -name: git-conventions +name: tmb_git-conventions description: Commit message style, branching rules, push safety. agent: bro, swe, pr-reviewer --- diff --git a/skills/naming-conventions/SKILL.md b/skills/tmb_naming-conventions/SKILL.md similarity index 98% rename from skills/naming-conventions/SKILL.md rename to skills/tmb_naming-conventions/SKILL.md index 85b4c32a..7d70bdc4 100644 --- a/skills/naming-conventions/SKILL.md +++ b/skills/tmb_naming-conventions/SKILL.md @@ -1,5 +1,5 @@ --- -name: naming-conventions +name: tmb_naming-conventions description: File and identifier naming patterns. agent: swe, pr-reviewer paths: ["src/**", "lib/**", "app/**", "tests/**"] diff --git a/skills/review-findings/SKILL.md b/skills/tmb_review-findings/SKILL.md similarity index 97% rename from skills/review-findings/SKILL.md rename to skills/tmb_review-findings/SKILL.md index b27efa98..9e830ab1 100644 --- a/skills/review-findings/SKILL.md +++ b/skills/tmb_review-findings/SKILL.md @@ -1,5 +1,5 @@ --- -name: review-findings +name: tmb_review-findings description: Living list of patterns caught during code review. All agents internalize these before designing, implementing, or reviewing. --- diff --git a/skills/review-protocol/SKILL.md b/skills/tmb_review-protocol/SKILL.md similarity index 99% rename from skills/review-protocol/SKILL.md rename to skills/tmb_review-protocol/SKILL.md index 54772822..800ced77 100644 --- a/skills/review-protocol/SKILL.md +++ b/skills/tmb_review-protocol/SKILL.md @@ -1,5 +1,5 @@ --- -name: review-protocol +name: tmb_review-protocol description: Review phases 1-7 for PR Reviewer. Progression from staged diff scan to full design compliance check. --- diff --git a/skills/tmb_skill-creator/SKILL.md b/skills/tmb_skill-creator/SKILL.md index dab9aa2f..c3297d19 100644 --- a/skills/tmb_skill-creator/SKILL.md +++ b/skills/tmb_skill-creator/SKILL.md @@ -13,7 +13,7 @@ Add a new capability to a project's agents without editing their body. The Lego ## When invoked -- Bro detects a project needs a new skill (e.g. Python-stack swe needs a Python-specific verification checklist that the default `swe-checklist` doesn't cover). +- Bro detects a project needs a new skill (e.g. Python-stack swe needs a Python-specific verification checklist that the default `tmb_swe-checklist` doesn't cover). - Human asks bro to teach an agent a specific behavior (`@bro teach swe to also run mypy as part of verification`). - A consultant flagged that the project lacks a skill needed for a domain (e.g. cto says "you should have a perf-budget skill on swe"). diff --git a/skills/swe-checklist/SKILL.md b/skills/tmb_swe-checklist/SKILL.md similarity index 98% rename from skills/swe-checklist/SKILL.md rename to skills/tmb_swe-checklist/SKILL.md index bcebdcc9..f1a55d89 100644 --- a/skills/swe-checklist/SKILL.md +++ b/skills/tmb_swe-checklist/SKILL.md @@ -1,5 +1,5 @@ --- -name: swe-checklist +name: tmb_swe-checklist description: Implementation rules and self-review checklist for SWE agent. ---