✂️🛡️ refactor: slim CLAUDE.md 268→149 + extract headless-fallback / mcp-errors / direct-mode / push-gate to skills#124
Merged
Conversation
L6 run #24966945645 (artifact #122) confirmed bro halts in `claude -p` mode whenever a skill calls AskUserQuestion — no Human, error, halt. 3 of 4 wired flows died this way. Plus 95-anonymous-cold-restart revealed bro short-circuiting the first-action chain on casual messages, contradicting the documented "every triggered message" rule. Doctrine fix: 1. **CLAUDE.md** gains an "AskUserQuestion fallback — never halt" section. Every fallback MUST record both `ledger_log(event_type= 'headless_fallback', ...)` AND `discussion_append(kind='note', ...)` so the autonomous decision is auditable. 2. **First-action chain** clarified: "No exceptions. Casual messages like @bro hi still run the full chain." Removes the wiggle-room bro was using to skip identity_get/config_get/issue_resume. 3. **4 in-DB skills** (tmb_first-run-onboarding, tmb_branch-id-proposal, tmb_reonboard, tmb_planning-difficult) get a "## Headless fallback" section listing question→default→audit-write protocol. 4. **2 file-writing skills** (tmb_skill-creator, tmb_agent-creator) get a "## Headless mode — HALT" section. Auto-approving silent skill/agent generation in CI is the foot-gun the rule guards against; halt with `ledger_log(event_type='headless_creator_blocked')` instead. 5. **tmb_reonboard** also halts (re-onboarding flips policy keys that drive git-guards.sh; silent fallback could break the project's git workflow with no audit trace). Defaults table summary: - identity name → "Anonymous" (recoverable via tmb_reonboard) - branching_model → github-flow - pr_target → main - protected_branches → ["main"] - branch-id-proposal confirm → "Yes, proceed" - planning-difficult scope → "proceed as proposed"
User feedback on PR #124: AskUserQuestion fallback (+ much more) belongs in skills, not in the always-loaded CLAUDE.md. Recommended target: under 200 lines, ideally 60. Extracted to new reactive skills (load on trigger, not on every turn): - tmb_headless-fallback — AskUserQuestion fallback doctrine + ledger/discussion audit (was the new section from #124) - tmb_mcp-error-handling — is_error halt rule + forbidden-tools list - tmb_direct-mode — ≤3-line single-file bypass protocol - tmb_push-gate — pr-reviewer-at-push-time orchestration CLAUDE.md retains only what bro needs on EVERY message: - Trigger rule - Identity / role / two-layer agent model (compressed) - MCP caller identity + forbidden-tools one-liner - First-action chain (no exceptions for casual messages — preserved from #124) - Routing decision table - Code-touching ask chain (with skill pointers) - "Skills bro loads reactively" lookup table - Catchphrase + communication style - Reference pointers (state, perf, config keys) Net: 268 → 149 lines (44% reduction). Reference-style sections (Agents shipped, Where state lives) collapsed to one-liners pointing at CONTRIBUTING.md and existing architecture docs.
ZaxShen
changed the title
This was referenced Apr 26, 2026
ZaxShen
added a commit
that referenced
this pull request
Apr 26, 2026
…rotocol to skills/docs (#126) User feedback: 'audit every single word' — CLAUDE.md is loaded EVERY turn, must contain only what bro needs every turn (trigger, identity, routing, reactive skills lookup). Detail and reference moved out. Extracted: - 'Subagent prompt precedence' (4 lines) — DELETED. Subagent prompts declare themselves; CC handles dispatch automatically. - 'Two-layer agent model' (5 lines) → new docs/AGENTS.md. - 'Forbidden tools' detail (5 lines) → expanded existing tmb_mcp-error-handling skill (now also covers policy-key writes). - First-action chain rationale paragraph (3 lines) → compressed to the section header itself ('no exceptions, no shortcuts'). - 'Bro verification' + 'Tool-call batching' detail (5 lines) → already documented in planning skills; CLAUDE.md now points there. - 'Direct ops' verbose section (3 lines) → folded into routing table as one row. - 'Concerns + second opinions' (8 lines) → new tmb_concerns-protocol skill (procedural, loads on demand when bro disagrees). - 'Reference' pointer block (7 lines) → new docs/REFERENCE.md. Net: 268 → 99 lines (63% reduction over 3 PRs: #124, #125, this one). What's left in CLAUDE.md: - Trigger rule (when bro activates) — must be every turn - Identity (compressed Role) — must be every turn - MCP caller-id rule (every-turn rule) - First-action chain (mandatory routine on every triggered message) - Routing table (decision tree) - Code-touching ask chain (the planning workflow diagram) - Reactive skills lookup (so bro knows what to load when) - Catchphrase + Communication style (identity) - Reference pointer (2 lines pointing at docs/) Approaching the 60-line aspirational target — further compression would gut essential routing. Co-authored-by: Zax Shen <ZaxShen@users.noreply.github.com>
ZaxShen
added a commit
that referenced
this pull request
May 20, 2026
Adds a "Pre-write check — no noise-citations" rule + Why section to tmb_agent-creator and tmb_skill-creator. Audits and fixes existing plugin prompt files (CLAUDE.md / agents/ / skills/ / templates/agents/) for issue-number citations, memory file paths, origin attributions, and tombstone commentary. Re-does the AskUserQuestion mandate: adds CLAUDE.md "## Asking the Human" section with inline constraints (no memory-path tail), and the corresponding tmb_review-findings entry under "Bro Persona Patterns" without a "Caught in" line. Drops the "Caught in: PR / commit / file:line" row from the review-findings template — the field itself trained future authors to write the noise-citations the doctrine now forbids. Closes #124. Re-does #95.
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
Two changes bundled — both touch the same files (CLAUDE.md + skill set), so shipping together avoids interleaving conflicts.
1. Headless-bro doctrine (original PR scope)
L6 run #24966945645 revealed bro halts in headless
claude -pmode whenever a skill callsAskUserQuestion— no Human → error → halt. 3 of 4 wired flows died this way. Plus 95-anonymous-cold-restart showed bro short-circuiting the first-action chain on casual messages.Doctrine fix:
tmb_first-run-onboarding,tmb_branch-id-proposal,tmb_planning-difficultget## Headless fallbacksections with documented per-question defaults.tmb_reonboardHALTs in headless mode (policy keys would silently break git-guards.sh otherwise).tmb_skill-creator,tmb_agent-creatorHALT (silent file-creation in CI is the foot-gun).ledger_log(event_type='headless_fallback', ...)ANDdiscussion_append(kind='note', ...)— audit trail non-negotiable.2. CLAUDE.md slim-down (per user feedback during review)
User flagged CLAUDE.md as way too long (268 lines, recommended under 200, ideally 60). The headless-fallback rule itself was contributing to the bloat — belongs in a skill, not the always-loaded persona.
Extracted 4 reactive skills (load only when triggered, not every turn):
tmb_headless-fallbackTMB_HEADLESS=1tmb_mcp-error-handlingis_error: truetmb_direct-modetmb_push-gategit pushblocked / "review before push"CLAUDE.md retains only what bro needs on EVERY message: trigger rule, identity, MCP caller rules, first-action chain, routing table, code-touching ask chain, skills lookup, catchphrase. Reference content (agent layer detail, state locations) collapsed to pointers at
CONTRIBUTING.mdanddocs/architecture/FLOWS.md.Net: 268 → 149 lines (44% reduction). Still over the 60-line aspirational target — further compression would lose essential routing — but well under the 200 ceiling.
Test plan (after merge)
tmb_headless-fallback)tmb_direct-modeskill explicitly for the typo, hit thedirect_mode_usedledger event. If still failing, that's a separate Direct-Mode-detection bug.headless_fallbackledger events appear with the documented question→default mapping.