claudetools/specs/claudetools-harness-optimization/shape.md

ClaudeTools Harness Optimization — Shape & Constraints

Spec created: 2026-06-08. Authored as a 3-way review (Claude + Grok + Gemini); see review-3way.md for each model's independent input and the points of consensus.

What this is

Optimize the ClaudeTools harness itself (not its projects) for day-to-day MSP ops. Primary goal: accuracy + completeness, with context pressure as a first-class constraint. Secondary: token efficiency. The harness is strong on capability surface (skills, coord, wiki, vault) but weak on two axes the three reviewers independently agreed on:

• Distributed-write safety — git add -A + a git submodule + concurrent multi-machine wiki recompiles produce footguns (stale gitlinks, committed conflict markers).
• Context economics — large static prose (the skill/command registry with paragraph descriptions, CLAUDE.md ~4.9k tokens, multi-K command bodies) is injected repeatedly, crowding attention and inflating tokens.

Scope (prioritized)

P0 — Reliability footguns (do first):

1. Submodule-safe sync.sh (eliminate the manual detach-to-pin/restore dance).
2. Decouple wiki recompile from /save; serialize synthesis (one machine / lock) and merge-not-rewrite.
3. Single source of truth for command-vs-standard (the /syncro add_line_item vs the timer_entry standard contradiction on a billing path).
4. Pre-commit guard: block conflict markers, unflagged submodule gitlink bumps, and vault-plaintext patterns.

P1 — Context diet:

1. Trim every skill/command registry description to one line; move detail into the SKILL.md body (loads only on activation).
2. CLAUDE.md -> lean CORE (identity, security/vault, routing, delegation thresholds; target <=1.5k tokens) + on-demand EXTENDED.
3. Make /save and /sync thin wrappers around deterministic scripts that return a short summary, not multi-K instruction bodies injected on every invoke.
4. Shard the largest command bodies (syncro 1139 lines, rmm 783) into a core flow
   • lazy reference sections.

P2 — Coordinator/sub-agent model: re-tune from "delegate almost everything; code/db = ALWAYS delegate" to "act directly by default; delegate only for high-volume output, broad blast radius (>3 files/layers), genuine domain shift, or parallel work."

P3 — Knowledge architecture: tier logs (write-only archive) / wiki (synthesized, dated, cited, on-demand) / memory (small ephemeral + quirks, ~40-60 files). Recall order log-index -> wiki -> memory; add a session-logs/INDEX; graduate finished-project memories into wiki/standards.

Deterministic Bash fixes (in this spec): jq -n --arg for ALL shell JSON (fixes the post-bot-alert.sh 400), a now-phoenix timestamp helper (never TZ=America/Phoenix date on Git Bash), skills-deploy parity (shipped 2026-06-08).

P4 — Code-over-prompt Python port (MOVED OUT — separate future spec): porting the core harness (sync/save/hooks) to one cross-platform language is its own spec per the 3-way review; this spec lands the cheap deterministic Bash fixes above, not a rewrite.

What this is NOT (out of scope)

• NOT touching any project (GuruRMM, GuruConnect, Dataforth, client work) — harness only.
• NOT changing the SOPS vault, the coordination API, or Gitea hosting.
• NOT removing any capability — skills/commands stay; only their CONTEXT footprint and reliability change.
• P4 (Python port) is a stretch goal; v1 may land the deterministic fixes in Bash and port incrementally. Do not block P0-P3 on a full rewrite.
• NOT a redesign of the multi-user identity or work-mode model.

Hard constraints

• Changes are FLEET-WIDE (every machine syncs them) — each change must be safe to roll out via the existing sync, reversible, and announced via coord broadcast.
• Must not break the existing /save /sync contracts mid-flight (other sessions rely on them); change behavior behind the same entry points.
• No secrets in context or logs; keep the SOPS-vault discipline.
• NO EMOJIS; ASCII markers.

Key decisions

• Accuracy first, tokens second (per Mike): never compress safety rules, billing SSOT, or vault discipline to save tokens. Cut redundancy and lazy-load reference, not guardrails.
• Determinism over prompt for mechanical workflows: anything needing >500 tokens of English to run correctly should be a script the model calls.
• Single source of truth: a fact lives in exactly one layer (CORE rule, standard, command, wiki, or memory) and is referenced, not duplicated.
• Serialize distributed writes: wiki synthesis and any shared-file regeneration run behind a coord lock or on one designated node.

Priority

P1 (this is the operator's daily experience). Reviewer consensus: P0 removes real operational risk; P1 buys back the context headroom that makes everything else land.

Provenance

Independent reviews by Claude (firsthand session friction), Grok (xAI), and Gemini (Google) on 2026-06-08 converged on the same P0/P1/P2/P3 priorities. Full per-model input + consensus/dissent in review-3way.md.