The Minimal BOB_HOME Core

The Minimal BOB_HOME Core

Demotion audit for #1132 (part of #1129) — audited 2026-07-16.

BOB_HOME’s global surface carries a context tax: every universal skill’s name and description is loaded into every session on every project, whether or not that project can use it. This document is the written audit that shrinks the global tier to the invariant core, demoting everything project-shaped to the registry where per-project provisioning picks it up.

The invariance test

An item stays global only if it is needed before or independent of any project context:

1. Session-start surface — machine/harness-level controls exercised before any project intent exists (automation levels, promotion ceilings, remote-decision mode).
2. Bootstrap invariant — anything the provisioning/deploy path itself touches must be present before a manifest exists (you cannot provision the provisioner).
3. Dependency floor — an item referenced by another retained item cannot demote, traced through explicit references and required_with chains.
4. Universal workflow — genuinely project-independent activities (git commit/PR flow, the work-tracking hierarchy, the autonomous loop and its safety controls).

Episodic-but-critical items (incident runbooks) are judged on criticality, not frequency — rarely-used is not a demotion reason on its own.

Skills: 9 → 9 global

Keep global (9)

Skill	Justification
automation	Session-start surface: permission profiles are machine/harness state, set before project intent.
commit	Universal workflow: git commits are identical in every repo; no project shape.
orchestrator	Bootstrap invariant: it is the provisioning interview — must exist before a manifest does.
pr	Universal workflow: pairs with commit; GitHub PR flow is project-independent.
promotion	Session-start surface: promotion ceiling is machine/harness state, sibling of automation.
rdb	Session-start surface: remote-decision mode is machine state, toggled independent of project.
stop-warp-drive	Dependency floor: safety control for the universally-available warp-drive loop (bin/warp references it); must exist wherever the loop can run.
timelord	Dependency floor: mandated by CLAUDE.md for all PM writes and referenced by 14 retained commands.
todo-writing	Dependency floor: warp-drive’s todo contract mandates it whenever a todo issue is filed (timeout path fires on any project).

Demote to registry (11)

Skill	Justification	Orchestrator metadata
agent-builder	Authoring/meta activity — episodic, chosen deliberately, not session-invariant.	category authoring, recommended_for meta
code-expert	Stack-shaped (TS/SvelteKit/Workers) — belongs beside the registry’s other stack skills.	applies_to stacks, category backend-runtime
code-simplifying	Code-work-shaped; provisioned for dev projects, meaningless pre-project.	recommended_for development
doc-audit	Episodic docs governance on a project’s docs tree.	category docs, pairs doc-sync
doc-sync	Applies doc-audit findings; demotes with it (required_with).	category docs, required_with skills/doc-audit
docs-site	Project doc-site tooling; recommend.js’s universal special-case is updated as part of the demotion.	category docs
explaining-code	Generic but project-work-shaped; no pre-project use.	recommended_for development
research	A research project is a project; the activity has full project shape.	category pm
runbook-gen	Episodic authoring of ops docs.	category docs/authoring
skill-creator	Authoring/meta, sibling of agent-builder.	category authoring, recommended_for meta
software-project-manager	PM thinking applied to a project; largest single description payload (886 chars).	category pm

Commands: 26 → 18 universal

Commands are symlinked per-project by cdi (not auto-loaded), so their tax is surface clutter rather than per-session tokens — but the same test applies.

Keep universal (18)

business-case, capability, dev-up, finish-work, groom, journal, pr, provision, rebob, report-bug, requirement, session-summary, start-work, use-case, vision, warp-drive, what-next, where

Justifications: the product-hierarchy commands (vision → business-case → capability → requirement, plus use-case) and reporting (journal, session-summary, report-bug) are the work-tracking core CLAUDE.md promises on every project; warp-drive + what-next + groom are the autonomous-loop core (groom manufactures the approved queue the loop consumes); start-work/finish-work/pr are the universal branch flow; provision/rebob are the bootstrap invariant; dev-up is the dev-lifecycle entry every project may declare; where is orientation in any repo.

Demote to registry (8)

Command	Justification
auto-loop	Deprecated alias of warp-drive — registry with deprecated marker; candidate for removal.
autonomous-pm	L4 vision-to-queue front-end; episodic, opt-in.
cdfork	Parallel fan-out needs tmux + worktree appetite — a capability, not an invariant.
doc-bootstrap	One-time brownfield onboarding — episodic by definition.
flightplan	Authoring a run plan is opt-in; warp-drive --flightplan consumes plans via scripts, not this command.
swarm	Multi-agent orchestration is an opt-in capability.
trace-mining	Outer improvement loop — episodic, BoB-development-shaped.
update-story	Narrative page refresh for projects that opted into a story page.

Agents: 5 → 3 universal

Agent	Verdict	Justification
requirements-analyst	Keep	Dependency floor: retained business-case and use-case invoke it.
solution-architect	Keep	Dependency floor: retained business-case invokes it.
project-historian	Keep	Dependency floor: retained what-next invokes it.
doc-keeper	Demote	Referenced only by demoted items (doc-bootstrap, docs-site, doc-audit, doc-sync) — required_with those skills.
lessons-extractor	Demote	Referenced only by demoted trace-mining — required_with it.

Runbooks: 5 → 3 universal

Runbook	Verdict	Justification
agent-handoff	Keep	Universal ops procedure between any two sessions.
incident-response	Keep	Episodic-but-critical: must be findable during an incident on any project, before anyone thinks to provision it.
project-onboarding	Keep	Bootstrap invariant: consumed when a project has no tooling yet.
launchpad-serving	Demote	Launchpad-feature-specific operations.
tellbob-token-lifecycle	Demote	TellBoB-specific operations.

Bootstrap invariant verification

The provisioning/deploy path was traced for item references: provision.sh, deploy.sh, bin/cdi, bin/cdprov, bin/rebob, and scripts/orchestrator/*.js. Findings:

• cdi symlinks all of commands/ and a hard-coded core agents/ list — demoted commands/agents leave those trees, so no dangling references.
• recommend.js special-cases skills/docs-site as universal (its only universal-item reference); updated to treat docs-site as a registry item in the demotion commit.
• The orchestrator skill and provision/rebob commands are the interactive faces of the bootstrap path — retained.
• No other bootstrap script references a universal item by name.

Manifest drift found during audit

provisions/_bob-home.json had drifted from the deployed tree before this audit: skills promotion, runbook-gen; commands autonomous-pm, business-case, doc-bootstrap, flightplan, groom, report-bug, swarm, use-case, where; runbooks launchpad-serving, tellbob-token-lifecycle were present on disk but undeclared. The demotion apply rewrites the manifest to the audited core, resolving the drift.

Context-tax measurement

Measured as frontmatter name + description payload (the per-session global load), before the demotion:

	Skills	Chars	~Tokens
Before	20	8,563	~2,141
After (core)	9	2,773	~693
Reduction	−11	−5,790	~−68%

The after figure was re-measured post-apply: 9 skills, 2,773 chars (~693 tokens) — matching the projection exactly.

What projects must reconcile

Any project actually using a demoted item must gain it in its own provision manifest (no silent tooling loss). Evidence sources: the session evidence ledger (#1131) where populated, plus grep of project trees for explicit references. The reconciliation pass over all project manifests is applied with the demotion (see #1132).