Agent Instructions

This project uses bd (beads) for issue tracking. Run bd prime for full workflow context.

Architecture in one line: Issues live in a local Dolt database (.beads/dolt/); cross-machine sync uses bd dolt push/pull (a git-compatible protocol), stored under refs/dolt/data on your git remote — separate from refs/heads/* where your code lives. .beads/issues.jsonl is a passive export, not the wire protocol.

See SYNC_CONCEPTS.md for the one-screen overview and anti-patterns (don't treat JSONL as the source of truth; don't bd import during normal operation; don't reach for third-party Dolt hosting before trying the default).

Slice Tracking Contract

The triage board (docs/templates/triage-board.html) is a projection of beads and data/last_run.json. It is read-only. If it disagrees with reality, beads wins.

Moving a card on the board is a proposal. Applying it means running bd.
End every inner-loop cycle with a bead write (bd close <id> or bd update <id> --status open) for the slice you worked, before the next cycle.
Rebuild the view when you need a fresh projection: python3 scripts/build_board_json.py

Full contract: docs/templates/slice-tracking-contract.md.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work
bd dolt push          # Push beads data to remote

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

scp - use -o BatchMode=yes for non-interactive
ssh - use -o BatchMode=yes to fail instead of prompting
apt-get - use -y flag
brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
Run bd prime for detailed command reference and session close protocol
Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

File issues for remaining work - Create beads for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

Handle git/sync by active profile:

# Conservative/minimal/default: report status and proposed commands; wait for approval.
git status

# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
bd dolt push
git push
git status

Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

Explicit user or orchestrator instructions override this Beads block.
Do not commit or push without clear authority from the active profile or the current user request.
If a required sync or push is blocked, stop and report the exact command and error.

Beads Issue Tracker

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

Use bd for all task tracking; do not create markdown TODO lists.
Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
Keep persistent project memory in Beads via bd remember; do not create ad hoc memory files.

Live Vault (Obsidian) + Orca Bridge — session survival guide

Quickest way to test if the bridge is up: python3 scripts/obsidian_client.py doctor (exit 0 = usable).

If it's down (container restart), do:

scripts/bridge_live_vault.sh up     # tailscale re-downloads only if cache gone; state persists under data/tailscale
# ^ this prints an auth URL you MUST give the user to click (Tailscale re-auth, only after a fresh node create)
scripts/bridge_live_vault.sh status # verify mac online + Obsidian HTTP 200
export OBSIDIAN_API_KEY="..."       # from Obsidian → Local REST API plugin settings

# Orca remote (same tailnet) — one command, no code needed if already paired:
scripts/orca_pair.sh up             # starts SOCKS5 forwarder 6768->Mac, re-points endpoint
scripts/orca_cli.sh worktree list --environment mac

Durability (this sandbox): /workspace is the only real disk (ext4 at /dev/nvme0n2). /tmp and $HOME are container overlay and get wiped on pod recycle. Therefore ALL state lives under the repo's data/:

State	Durable path	Why
tailscale binary/state/socket	`data/tailscale/`	survives recycle; re-auth not needed
Orca CLI (node, no Electron)	`data/orca-cli/<ver>/`	182MB extracted once
Orca paired env (device token)	`data/orca-config/` (via `ORCA_USER_DATA_PATH`)	E2EE pairing persists

data/* is gitignored and these dirs are chmod 700 (they hold the E2EE device token + tailscale identity). Never commit them, never loosen perms.

Privacy contract (do not violate):

The client is scripts/obsidian_client.py — pure stdlib (no requests), read-only, folder-confined. It never surfaces 00-Inbox, 05-Daily, 06-Archive, or 01-Projects/Brandon Career — including from search (filtered per-result).
context_orchestrator adds a [Live Vault] probe only when OBSIDIAN_API_KEY is set. No key → no probe (fail open). Tests disable it by default via tests/conftest.py.
The curated vault (data/vault/) is allowlist-guarded (config/vault_allowlist.yaml + scripts/check_vault_allowlist.py). Both layer-3 paths enforce the same boundary.

Tests: tests/test_obsidian_client.py (path safety + search filtering), tests/test_context_orchestrator.py::TestLiveVaultIntegration.

Prime / ticket-scoping direction (from 2026-09-13 thread)

The inner-loop "Prime" step should emit a ticket-scoped context block in the shape of docs/templates/ handoff format (Metadata / Task / Code Paths / Pre-Dispatch Evidence / Guardrails / Verification). Implemented in scripts/prime.py — the working command is:

python3 scripts/prime.py --ticket '#123'      # GitHub issue (owner/repo#N, #N, URL)
python3 scripts/prime.py --ticket 'BEAD-7'    # beads id (if bd CLI or .beads/issues.jsonl exists)
python3 scripts/prime.py --ticket 'docs/plans/foo.md'   # plan/spec markdown path
python3 scripts/prime.py --ticket '#26' --out docs/dispatch/26.md   # write a dispatch block
python3 scripts/prime.py --ticket '#26' --json               # machine-readable (tooling)

Recommended keying: beads issue id first (--ticket BEAD-123), optional --plan <wayfinder plan path> alias. bd is not on PATH in this container; .beads/ raw data exists if a read path is needed.

The context layers your vault documents (and their order): codegraph → serena → cocoindex → obsidian (see 04-Reference/Tools/MCP-Tools.md

ADR-0001). Those MCP tool servers run on the Mac and are NOT reachable from this sandbox; the only live context pipe here is the Obsidian safe-vault bridge. Build Prime to use code tools when reachable and fall back to Obsidian.

Prime's context probes degrade gracefully and in this order: local repo (repo_reader tree + keyword-scored candidate files, always) → Obsidian live-vault search (bridge + OBSIDIAN_API_KEY present) → Orca worktree radar (paired mac env). Missing bridges are reported as skipped, not errors. Ticket sources are tried in order: bd CLI → .beads/issues.jsonl → GitHub (gh) → local plan/spec path. Tests: tests/test_prime_tool.py.

envit: repo context

Additional context is available in .envit/. The source of each external repository declared in envit.json is at .envit/repos/<name>/, read-only, at a pinned commit. Read .envit/AGENTS.md for the inventory.

When you work with a dependency, read its actual code there instead of guessing from memory. The entries are symlinks: use rg --follow or fd -L when you search them.