claude-sdk-rs: Instructions file for Claude Code

CLAUDE.md — claude-code-rs

A lean async Rust SDK that runs Claude Code as a subprocess on Brandon's flat-rate subscription (not API credits).

Before you start

• Strategic context: planning/context.md (read first) → planning/status.md (current state)
• Symlink warning: the planning/ directory is actually a local symlink pointing to the company brain repo's _planning/ vault (e.g. core/_planning/claude-code-rs/). The brain repo is responsible for tracking all planning files under Git. Do not track planning/ in this project's public Git repository (it is gitignored).
• Symlink traps: rg/grep/find are symlink-blind by default — a search that must include planning/ content needs -L/--follow. git mv fails through the symlink face ("source directory is empty") — move planning files via the real vault path (.../_planning/<slug>/...), never via planning/.... Planning changes are committed in the brain repo (agentic-portfolio) with an explicit pathspec, never in this repo.
• Plan: planning/master-plan.md — the phase/block sequence
• Pipeline config: planning/harness.json — the validation commands + UI-test config the SDLC engines run (see planning/harness.examples.md for ready-made stack profiles)
• Decisions log: planning/decisions/ (start at planning/decisions/index.md) — check before relitigating any settled choice

Standing rules

1. Every block/task ships with tests covering its core functionality. No exceptions.
2. Every new .md under docs/ or planning/ must open with OKF YAML frontmatter. Required fields: type (e.g. Decision, Index, Reference, Plan, Log, ProjectStatus, LocalContext, Guide); title (human-readable); description (one-line summary for embedding). Optional but strongly encouraged: doc_id (kebab-case stable id, defaults to filename stem); layer (list from closed vocab: factory · brain · engine · console · surface · infra · business · content · meta); project (the project's own slug — see docs/okf-frontmatter.md in the company brain for the controlled vocabulary); status (active · draft · deprecated · superseded · archived); keywords (3–7 topic terms); related (list of doc_ids). Canonical guide: agentic-portfolio/docs/okf-frontmatter.md (governed by brain decision D27). Adding a file to a directory requires updating that directory's index.md — propagate up the chain as needed.
3. Sequence, not calendar — work the order in master-plan.md; pick up where you left off.
4. Decisions are append-only — never edit a settled decision; supersede it with a new atomic file in planning/decisions/ and link back.
5. Verified identity / handles: none — treat these as the only authoritative identities/URLs; flag any other handle or profile link as unverified before publishing it.
6. Never git push this repo directly from inside it. engine-rs path-depends on this repo, and every Rust repo's CI clones its sibling path-deps at their unpinned default branch — pushing out of order breaks a sibling's CI on code that was actually fine (the 2026-08-18 mev/bastion outage is the canonical example of this failure mode). Route every push through the company-brain's agentic-portfolio/scripts/git_push.sh --all, which pushes the whole fleet in dependency order and skips a repo flagged ci-blocked (a Cargo dependency is red on GitHub with nothing queued to fix it). Branching, committing, and opening/reviewing/merging PRs to main locally are all fine from inside this repo — only the final git push of main to origin must go through that script.