CLAUDE.md

A Claude Code plugin, babysitter, with opinionated skills for people who use OpenSpec inside Conductor. Mostly solo developers, on local and cloud Conductor workspaces. Public, MIT. See README.md for what each skill does.

Layout

• .claude-plugin/plugin.json: the plugin. name is babysitter. No version, on purpose.
• .claude-plugin/marketplace.json: the marketplace, also babysitter, with one plugin at ./.
• skills/<name>/SKILL.md: one skill each. cloud.md beside it holds the cloud steps. skills/hq/conductor-local.py holds babysitter's local, deterministic steps (scan, send, watch); skills/hq/state.py keeps its state file (IDs, workspace table, counts, merge lock) and works locally and in the cloud. skills/hq/watch.py is the cloud watcher and re-scan. skills/doctor/doctor.py is the read-only health check.

Releases

Every commit to main is a release. Users with auto-update get it the next time a session starts (open sessions keep their version until /reload-plugins), so main must always work. Test before merging.

Never add a version to plugin.json. Never rename the plugin (babysitter) without a renames entry in marketplace.json. Don't rename the marketplace (babysitter): renames doesn't cover it, so every install would have to remove it and add it again.

Testing a change

0. tests/check.sh: compiles the scripts and runs their self-tests, checks the prompt invariants that drifted once (explore asks one decision at a time, local and cloud prompts match, the digest pastes state.py table and counts), every skill is in the README, the skills are generic, and the plugin validates. Add a line to it when you fix a drift.
1. claude plugin validate . passes. Three warnings are expected: no version, no icon, and this CLAUDE.md not being loaded as plugin context (it's for working on this repo, not for users).
2. Test-install into a throwaway config:

   export CLAUDE_CONFIG_DIR=$(mktemp -d)
   claude plugin marketplace add "$PWD"
   claude plugin install babysitter@babysitter

3. For a live run, start a session with claude --plugin-dir ..
4. If you touched conductor-local.py, state.py or watch.py: python3 -m py_compile it, and keep its asserts passing (check_stage() runs first on scan; check() in state.py and watch.py runs first on every command). Add an assert when you change logic.

Local and cloud

Each skill checks CONDUCTOR_IS_LOCAL. Locally (1) it uses Conductor's SQLite database (CONDUCTOR_DB_PATH) and conductor:// links. In the cloud (0) it uses the conductor CLI, as written in that skill's cloud.md. A change to one side needs the matching change on the other, so both behave the same. Update the README's "Local vs cloud" table too.

Conductor's database is undocumented. Anything that writes to it backs it up first (sqlite3 "$CONDUCTOR_DB_PATH" ".backup ...") and has a fallback when a Conductor update breaks it. Read with ?mode=ro when you only read.

Keep the skills generic

No details from any one project: accounts, domains, people, product names. The skills read each user's own AGENTS.md/CLAUDE.md for project rules. Say "the user" or "the owner", not a name. Don't assume main; use CONDUCTOR_DEFAULT_BRANCH or origin/HEAD where you can.

Writing skills and the README

• Plain words, short sentences, concrete examples. Write for the reader.
• Skills are prompts: shorter beats longer. Cut what the model would do anyway.
• skills/<name>/examples/*.md are golden examples of what a skill's output should look like: few-shot for the model, and the reference when reviewing a change. Made-up product, no real project. Update them when the shape changes.
• Deterministic steps (queries, parsing, loops) belong in a script, not prose.
• Skill frontmatter: description says what it does and when to use it. Use disable-model-invocation: true for skills that should only run when the user types them (hq, pause, keep-going, better-decision).
• A new skill also goes in the README table and, if it changes what the plugin does, in the descriptions in plugin.json and marketplace.json.

Git

• Commit as Aaron Cohn <32344260+aaroncohn@users.noreply.github.com>.
• Commit messages say what changed for the user, starting with the skill when it's one skill (babysitter: ...).
• Work on a branch, open a PR, and rebase-merge: one commit per change.
• Ask Aaron before pushing to main or merging.