solo-orchestrator: Instructions file for Claude Code

CLAUDE.md — agent orientation for the solo-orchestrator repo

Read this first. It is the map for working effectively in THIS repository. Counts are date-stamped (they drift); prefer the grep/command recipes — run them to get current truth. Verified 2026-07-23.

WHAT THIS REPO IS

This is the framework repo that GENERATES downstream projects — it is not itself a scaffolded project. init.sh scaffolds a new project elsewhere; the files a downstream agent reads at kickoff live in the GENERATED project, not here.

• The README "Quick Start" no longer carries a kickoff prompt of its own (BL-202 residual 2). It points at bash scripts/resume.sh — the single state-aware first-message generator, whose three branches are the intake prompt, PROJECT_INTAKE.md § 13 verbatim, and the classic resume prompt. That script and everything its output names (CLAUDE.md, PROJECT_INTAKE.md, docs/reference/…, .claude/phase-state.json) exist in generated projects only; the README says so in as many words, because it is read by people who have not run init yet. Do not re-add a verbatim paste block here — the hand-maintained copy is what drifted, and tests/test-bl202-readme-kickoff-consolidation.sh now fails if one comes back (literal signatures and a structural bare-fence net, five mutation proofs).
• init.sh ships the guide downstream to docs/reference/: see the cp "$SCRIPT_DIR/docs/builders-guide.md" docs/reference/ line (grep builders-guide in init.sh). In THIS repo the guide is docs/builders-guide.md (top level), and there is no PROJECT_INTAKE.md and no .claude/phase-state.json.
• docs/INDEX.md is the documentation map — a one-screen index of docs/** and Reports/**. Start there to find a doc.

ENVIRONMENT TRAPS

• No timeout / gtimeout on this macOS host. Wrapping a command in them yields a spurious rc=127 (command-not-found), not a real timeout. Do not use them.
• The repo path contains a space (Claude Projects/…). Quote every path in every command, always.
• bash is 3.2 (/bin/bash, GNU bash 3.2.57). In product code: no ${var,,} lowercasing, no associative arrays (declare -A), no nullglob. Use temp files / indexed arrays instead.
• sed with a | delimiter and a shell-code replacement bites, and it bites SILENTLY. Shell replacements are |-dense (||), so s|old|new| where new contains || either errors (bad flag in substitute command) or — worse — terminates the expression early and leaves the file unchanged while sed reports success. It has bitten three times (twice inside a mutation harness, once ad-hoc), and 25 files carry s|-delimited sed. Two rules: pick a delimiter absent from the replacement, and assert the edit actually applied (a changed-line count), because "sed ran" is not "sed edited". A related one-liner: & in a sed replacement means the whole match — an unescaped && splices the original line back in, and that mutant passes bash -n. See ## BL-224: for the sibling case where a lint's own regex over-matched for the same reason.
• This Mac's git is configured and an ubuntu-latest runner's is not — and the difference is silent. Xcode ships /Applications/Xcode.app/Contents/Developer/usr/share/git-core/gitconfig carrying init.defaultbranch=main, so git init --bare here produces HEAD -> refs/heads/main for free. On CI there is no such setting and you get refs/heads/master. A fixture that inits a bare, pushes main, then clones it back out therefore works locally and is broken on CI: cloning a repo whose HEAD is a dangling symref prints a warning, exits 0, and produces a directory with nothing but .git in it — so || return 1 cannot see it and the next line fails on a path that was never created. That is BL-234's PR #351 in one paragraph. Name the branch on every bare you create (# BL-234-FIXTURE-BARE-HEAD), and never treat a clone's exit code as proof it checked anything out (# BL-234-FIXTURE-CLONE-RECEIPT). Reproduce the runner's git on this host — this turns a CI-only failure into a local one:

  GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null bash tests/<file>.sh
  

  It emulates git configuration divergence only — not the runner's git version, and not its filesystem (this Mac is case-insensitive, ext4 is not). Run it before blaming CI for anything a fixture does with git config. Derive the affected set, never transcribe it — a hand-copied list of this is what the reviewer refuted on PR #351 (said six, named seven, derived eight, and the omitted file was the one the same PR had just edited):

  grep -rln -- "init .*--bare\|init --bare" tests/
  

  Every hit that later clones back out of its bare must name the branch. None but the BL-234 suite does today, so none of the rest is broken by this defect — which is not the same as "not broken": the e2e-init* trio is already red on main for unrelated reasons, and four of the hits (test-bl084-tier-aware-remote-policy.sh plus that trio) are full-lane only, so a break there would not gate a PR at all. Do not pin this on the host's default branch. git-init(1) says the built-in fallback "will change to main when Git 3.0 is released" — a test that relies on a runner producing master stops discriminating everywhere, silently, the day runners ship it. Force the condition instead: GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=init.defaultBranch GIT_CONFIG_VALUE_0=master (that is what case H3 in the BL-234 suite does, and it is why that suite's mutant now dies on this Mac rather than only on CI).
• Two repos required. Tests and init.sh need the Claude Dev Framework cloned at ~/.claude-dev-framework (the path is hard-required). Per CONTRIBUTING.md:

  git clone https://github.com/kraulerson/claude-dev-framework.git ~/.claude-dev-framework
  

• Install the gate hook yourself. Contributors working on the framework install the pre-commit gate manually (init.sh does it for user projects, not here). Per CONTRIBUTING.md:

  cp scripts/pre-commit-gate.sh .git/hooks/pre-commit
  chmod +x .git/hooks/pre-commit