cc-tooling

name: cc-tooling description: Claude Code tooling standards — MCP server inventory and selection criteria, mermaid diagram rendering (mmdc), skill integration patterns with agent-skill mapping table, and shared config architecture. Use when working with MCP servers, rendering diagrams, managing skills, or configuring shared project settings. allowed-tools: Read, Glob, Grep, Bash

Tooling Standards

Loaded on-demand when working with MCP, diagrams, skills, or config. Not in system prompt. For core rules: rules/CORE.md | For deploy: rules/DEPLOY.md

MCP Server Inventory

Full evaluation: ~/.claude/reference/MCP-evaluation-2026-02.md

Removed: playwright MCP — replaced by agent-browser CLI tool (Rust, Vercel Labs). Use via Bash: agent-browser open <url>, agent-browser snapshot -i, agent-browser click @ref. All mcp__playwright__* tools are denied in settings.json. Benchmark showed agent-browser -i produces 86% fewer tokens than Playwright MCP snapshots (4.4K vs 31.5K tokens across 4 test pages). Playwright MCP also pollutes repos with .playwright-mcp/ user data directories.

Security Standards

• Store tokens in .env (gitignored), never hardcoded
• Docker containers for write-access servers (e.g., github)
• Prefer read-only access, minimum required scopes
• Config location: ~/.claude/mcp.json

MCP Resilience Bundle (env)

Three independent settings.json env knobs harden MCP against connection + tool-call hangs. They are different axes — set all three for long autonomous runs (/apply:all, ralph loops):

The idle-timeout default is 5min when unset; cc pins it to 3min (set 2026-06-27 via /workflow:evolve, v2.1.187 signal) for faster wave recovery while leaving headroom for legitimately slow tools (large Notion/Linear queries). MCP_TOOL_TIMEOUT (the ~28h hard wall-clock cap) is intentionally left at default — it is not the recovery lever. Capability discovery (tools/list) auto-retries transient network errors with backoff since v2.1.191 — no config needed.

MCP Selection Criteria

Add a new MCP server ONLY if ALL criteria are met:

Anti-Patterns

Adding a New Server

1. Evaluate against criteria above
2. Test in isolated environment
3. Secure with env vars and Docker if needed
4. Document in this file (add to inventory)
5. Monitor session startup time and stability

Mermaid Diagrams

Rendering, syntax gotchas, and tooling for .mmd diagrams

Tooling

No MCP server needed — mmdc handles rendering locally.

mermaid-cli (mmdc)

# Installed globally via pnpm
pnpm add -g @mermaid-js/mermaid-cli

# Render to PNG (transparent background)
PUPPETEER_EXECUTABLE_PATH=~/.cache/puppeteer/chrome-headless-shell/linux-146.0.7680.31/chrome-headless-shell-linux64/chrome-headless-shell \
  mmdc -i input.mmd -o output.png -b transparent

# Render to SVG
PUPPETEER_EXECUTABLE_PATH=~/.cache/puppeteer/chrome-headless-shell/linux-146.0.7680.31/chrome-headless-shell-linux64/chrome-headless-shell \
  mmdc -i input.mmd -o output.svg -b transparent

# If Chrome missing or version changes: install headless shell, then update path above
npx puppeteer browsers install chrome-headless-shell
ls ~/.cache/puppeteer/chrome-headless-shell/  # check new version dir

Puppeteer gotcha: mmdc pins an older puppeteer. The PUPPETEER_EXECUTABLE_PATH must be the exact resolved path — shell globs (linux-*) do NOT expand inside env var assignments.

IMPORTANT: Always use mmdc for rendering. Do NOT generate Mermaid Live URLs — they are fragile (pako encoding issues, padding bugs, <br/> incompatibilities) and open on the homelab, not the user's Mac.

Syntax Rules (Flowcharts)

Line breaks:

Rule: Use <br/> in node labels, plain text in edge labels. Edge labels don't support HTML.

Comments (%%):

• %% comments work at the top level of a flowchart
• %% comments break inside subgraphs — Mermaid Live throws JSON parse errors
• To "comment out" nodes inside subgraphs, delete them instead

Special characters in edge labels:

• No HTML entities (—, →) — use ASCII (--, ->, to)
• No emoji — can cause JSON parse errors in Mermaid Live
• Keep edge labels short and plain: |"deployment_status: success, Preview"|

Unicode in node labels:

• Emoji work in node labels but may render inconsistently across platforms
• Prefer ASCII descriptions over emoji for reliability

File Placement

Diagram source files: docs/*.mmd Rendered output: docs/*.svg or docs/*.png

Skill Integration

How agents discover and reference skills in ~/.agents/skills/

Discovery Patterns

Agent-Skill Mapping

27 agents total (3 archived, 4 merged/consolidated). Not every agent needs skills — only those with clear skill matches are listed.

* = preloaded via agent frontmatter skills key (available without manual invocation)

Engineering-Discipline Skills (obra/superpowers)

Six methodology-enforcement skills cross-cut multiple agents. Unlike the domain table above, these are broad by design: every engineer benefits from test-driven-development, every agent benefits from verification-before-completion.

Maintenance

• Keep 3-5 skill refs per agent — not exhaustive, just most relevant
• Review on /workflow:evolve cycles — update as skill library grows
• Skills are additive — agents can discover skills not in their list via find-skills
• Skill search index: ~/.agents/skills/skill-index.json (regenerate when skills change)

Quick Reference

Shared Config Architecture

Reusable configuration structure for all projects

Directory Structure

~/.claude/shared/
├── eslint-config/             # ESLint flat config
│   ├── base.js
│   ├── nextjs.js
│   └── oxlintrc.json
└── templates/                 # Project scaffolding templates

Global Directories (not in shared/)

• rules/ - Standards documentation (SHARED.md, etc.)
• agents/ - Agent definitions (29 active + 3 archived)
• skills/ - Skill library with search index
• commands/ - Slash commands

Project Overrides

Each project's .claude/ directory can:

• Override shared files by creating same-named files locally
• Add project-specific configuration in CLAUDE.md
• Extend settings.json hooks with project-specific logic
• Define custom agents/commands

Machine-Local Overrides

The .claude/local/ directory (gitignored) allows:

• Developer-specific overrides without affecting team
• Local API keys, tokens, paths
• Experimental configuration

Shared Config Legend

See Project Registry in CLAUDE.md for per-project shared config status.

RTK (Rust Token Killer)

Token-optimized CLI proxy (60-90% savings on dev operations). All commands are automatically rewritten by the Claude Code hook (e.g., git status → rtk git status).

Meta Commands (use rtk directly)

rtk gain              # Show token savings analytics
rtk gain --history    # Show command usage history with savings
rtk discover          # Analyze Claude Code history for missed opportunities
rtk proxy <cmd>       # Execute raw command without filtering (for debugging)

Verification

rtk --version         # Should show: rtk X.Y.Z
which rtk             # Verify correct binary

Name collision: if rtk gain fails, check for reachingforthejack/rtk (Rust Type Kit).

Opening Files in a Browser (ropen)

What: ropen <file> is a thin client that registers a mount, dispatches a Mac browser open via SSH+AppleScript, and exits in 30ms. Source-of-truth lives at `/dev/cc/tools/ropen/(symlinked into~/.local/bin/). The HTTP server is a long-lived systemd-user unit (ropen.service`, port 8889) — the CLI never starts or stops it.

Why: This machine is headless Arch Linux accessed over SSH. open / xdg-open fail silently because there's no display. Use ropen whenever you want Leo to see a file (HTML review pages, visual explainers, rendered Markdown).

How:

• Fire-and-forget. ropen <file> returns immediately (URL printed, SSH+osascript runs in detached subshell with all three fds severed). Safe to call from pipelines or Claude's Bash tool — it will not block stdout capture.
• Server lifecycle is systemd's job. Inspect with systemctl --user status ropen. If the unit is down, the CLI fails loud with exit 2 and tells you to systemctl --user start ropen. Do NOT try to start the server by invoking ropen --serve directly — that's only the ExecStart path systemd uses.
• Mount-only registration: ropen --mount <dir> registers a directory as a mount and prints the URL prefix without dispatching a Mac open. Use when you want to expose a directory ahead of time, or when scripts need URL prefixes without a side-effect tab open.
• List active mounts: ropen --list.
• gate.sh Stage C auto-rewrites xdg-open → ropen — so writing xdg-open file.html works too.
• Serves from the file's git root so relative links resolve correctly.
• Renders Markdown dynamically; for raw files just serves them.
• Falls through to native open on macOS (safe to use in shared scripts).

Don't:

• Write HTML to /tmp/ and try to open it — ropen serves from git root, so files outside a repo won't have a stable URL. Keep generated viewers in the project's docs/ directory.
• Wrap ropen <file> in Bash({run_in_background: true}) — it already exits in ~30ms. Backgrounding it adds noise without value.
• Use --stop — flag was removed (server is owned by systemd, not the CLI).

OpenSpec CLI Patterns (non-interactive)

Agents running openspec CLI must use non-interactive flags — the CLI reads confirmation prompts from /dev/tty, so echo "y" | and printf piping DO NOT work and produce loops.

Anti-patterns that burn loops:

• openspec archive <name> (no flag) → hangs on confirmation
• echo "y" \| openspec archive <name> → prompts use /dev/tty, stdin is ignored
• mkdir archive && mv openspec/changes/<name> openspec/changes/archive/ → blocked by gate.sh
• openspec archive <name> -y ... \|\| openspec archive -y ... \|\| openspec archive --help → OR-chains swallow the first success

Rule of thumb for any interactive CLI in agent context: before piping stdin or looping, run <cmd> --help ONCE and look for --yes, --no-interactive, or --force flags.

Related Skills

• mcp-builder — Build and configure new MCP servers with decision trees and TS templates
• mermaid-diagrams — Syntax reference and diagram type selection for creating new diagrams
• orchestrator-patterns — Multi-agent orchestration patterns for complex workflows