fix(infra): bundle skills/ in wheel, surface install failures, rename /bicameral:* → /bicameral-*

[Knapp-Kevin]

Summary

End-to-end fix for "skills are not invocable after install" — the cause was three layered bugs:

• Wheel didn't ship skills/ despite the artifacts directive (verified empty pre-fix). Claude Code skills require folder copies that the installer reads from Path(__file__).parent / "skills", so the wheel must contain that path.
• _install_skills failed silently when source was missing; the summary suppressed the zero count.
• All /bicameral:* slash commands were unresolvable. Claude Code resolves slash commands by skill folder name, and the folders use hyphens (bicameral-ingest, etc.). The colon form would only work for plugin-namespaced skills — and bicameral-mcp does not ship a Claude Code plugin. Renaming everywhere is the right fix; switching to a plugin distribution was considered and rejected as out-of-scope (multi-agent strategy, plugin maturity, separate engine layer).
• _detect_runner had a broken python -m bicameral_mcp fallback that produced non-functional MCP configs (no such package; entry is server:cli_main).
• Stale Note: using ... -m bicameral_mcp ... advisory printed regardless of selected runner.

Linked issues

Closes #177

Plan / Audit / Seal

• Plan: plan-installer-skills-remediation.md (originally authored against main; adapted on dev after discovering significant divergence and verifying via wheel build that dev had the same packaging bug)
• Audit: PASS (binary verdict; one VETO cycle resolved on F1 specification-drift around the runner-note text — fixed inline before re-audit)
• Seal: advisory PASS — all 24 installer/hook/SessionEnd tests pass; setup_wizard and server import cleanly; manual smoke (_BICAMERAL_SESSION_END_COMMAND ends with '/bicameral-capture-corrections --auto-ingest')
• Risk: L2 (touches packaging contract, installer behavior, hook commands, and ~18 files of cross-references)

Test plan

• pytest tests/test_setup_wizard.py -v — 6 passed (incl. new test_session_end_command_uses_hyphen_slash_command regression guard)
• pytest tests/test_installer_packaging.py -v — 2 passed (real python -m build + zipfile inspection; skill members enumerated dynamically from source)
• pytest tests/test_post_commit_sync_hook.py -v — 11 passed (hook reminder text now references /bicameral-sync)
• pytest tests/test_session_end_hook_drift.py -v — 5 passed (canonical SessionEnd command + drift checks)
• python -c "import setup_wizard, server" — clean imports, RunnerNotFoundError exported
• Manual verify (reviewer): build the wheel, pip install --force-reinstall it into a fresh venv, run bicameral-mcp setup <some-target-repo>. Expect: all 12 skill folders populated under <repo>/.claude/skills/, summary advertises /bicameral-<name> (hyphen) commands, no -m bicameral_mcp text anywhere.
• Manual verify (reviewer): with no bicameral-mcp script on PATH, run setup. Expect: RunnerNotFoundError with install hint, not silent broken config.

Scope summary

Functional code (must change for the fix to work end-to-end):

• pyproject.toml — [tool.hatch.build.targets.wheel.force-include] with "skills" = "skills"
• setup_wizard.py — RunnerNotFoundError; clean _detect_runner; WARNING in _install_skills; drop if num_skills: gate; surface RunnerNotFoundError in run_setup; delete stale runner-note; rename advertised slash commands; rename hook command string
• .claude/settings.json — SessionEnd hook command
• scripts/hooks/post_commit_sync_reminder.py — PostToolUse reminder text
• server.py — 11 tool-description "Slash alias:" lines
• skills/*/SKILL.md — 6 skill files with cross-references / self-references / hook examples

User-facing docs:

• README.md — slash-commands table (5 rows + skills column reference)
• docs/DEV_CYCLE.md — one example
• assets/git-for-specs-deck.html — presentation chip

Tests (lockstep + regression guard):

• tests/test_post_commit_sync_hook.py, tests/test_session_end_hook_drift.py, tests/e2e/_harness_setup.py, tests/e2e/run_e2e_flows.py — references in test text/asserts
• tests/test_setup_wizard.py, tests/test_installer_packaging.py — new (TDD)

Intentionally NOT changed:

• CHANGELOG.md — historical entries are archival
• .claude/skills/* — repo-local dupes regenerated by bicameral-mcp setup .
• pyproject.toml artifacts = ["skills/**/*.md", ...] — left alongside force-include (removing would be tangential cleanup)

Notes for reviewer

• Pre-existing setup_wizard.py size (~970 LOC) is over the Razor 250-LOC file limit; not addressed here. Suggest a follow-up refactor issue.
• Plugin distribution (so /bicameral:ingest could work natively) was considered and explicitly rejected — the multi-agent surface (Cursor + Codex don't have plugin systems) makes a Python-packaged engine + per-agent installer the right shape. The plugin route would be a several-week migration with no net win.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 203cb931-5c97-437c-bd02-4ec2d6c1c40c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 177-installer-skills-bundle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}