naming-things

Imported from who/naming-things (AGENTS.md). Install upstream with npx skills add who/naming-things. Copyright stays with the author.

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 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).

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

CodeGraph Index Maintenance

.codegraph/ is machine-local and gitignored, so each clone builds its own graph with codegraph init. Updates after that are incremental, and the file watcher is off in headless runs, so an index can fall behind a subtree added after it was built. worker/ did exactly that: codegraph explore and the codegraph_explore MCP tool answered src/ and test/ queries normally while reporting no match for the Worker's own symbols.

Under this repo's codegraph = "required" policy that is a stop, not a licence to fall back to grep. When a query cannot find code you know is committed, rebuild the whole graph and confirm the paths landed:

codegraph index    # full rebuild from scratch
codegraph files    # the indexed tree, to check the new paths are in it

The rebuild covers the whole tree, so existing coverage returns with it, and a daemon serving the previous database reopens the replacement in place — there is nothing to restart.

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/core-concepts/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.

1. File issues for remaining work - Create beads for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. 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

5. 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.

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/core-concepts/sync-concepts.md for details and anti-patterns.

Ortus session rules

Managed by Ortus 0.4.1.dev21+g00b4d92. Edit outside the markers freely — ortus init rewrites only what sits between them, and ortus check reports drift.

Issue tracking with bd

All work goes through bd. Find ready work, claim it, do it, close it:

bd ready                              # see what has no blockers
bd update <id> --status=in_progress   # claim
# ... do the work ...
bd close <id> --reason "..."          # close

One context window, one issue. Do not carry leftover work on a closed id; file it as a new bead instead.

Issue authoring contract (readiness v1)

Every non-epic issue must satisfy Ortus readiness schema v1 to be workable: ortus grind skips an unready issue rather than running it. Epics are containers and are exempt. Three bd fields carry the contract, each under the exact Markdown headings readiness v1 requires:

• description — the objective, and the behavior before and after.
• design — the schema version, scope and non-goals, concrete file and symbol locations, resolved decisions, compatibility constraints, ordered steps, dependencies, edge cases, and plan-gap guidance.
• acceptance_criteria — observable criteria with stable identifiers, one exact check per identifier, and the targeted test commands.

Every section needs concrete content: TODO, TBD, N/A, and empty or template text are rejected. When something is genuinely absent, write None — <why that is safe>.

Run ortus spec for the authoritative heading list and shape rules. It prints the contract generated from the installed Ortus, so it cannot drift from what grind enforces; this block only points at it.

After authoring or repairing a non-epic issue, run ortus validate <repo> <id> to confirm it is grind-eligible. The verdict is READY or the exact sections grind would reject, so a hand-authored bead is caught at authoring time instead of at claim. ortus plan already validates every issue it writes; this step covers the manual-authoring path and is guidance, not a gate: grind still enforces readiness at claim.

Orchestrator (ortus grind)

Drive the queue to zero via Ortus's subprocess-per-task loop. Each iteration spawns a fresh agent with a narrow per-task condition ("close one issue"); the outer loop trusts only observable bd state to decide success, orphan-claim, or no-change retry.

Claude and Grok workers run /goal (claude -p "/goal ...", grok -p; the Grok surface expands it the same way Claude's does). Codex and opencode workers run a plain prompt (codex exec, opencode run; local is opencode's older name), because codex exec does not expand slash commands and opencode has none. Never invoke ortus grind from inside a worker.

ortus grind .                            # drain bd ready
ortus grind . --tasks 1                  # exactly one task closed
ortus grind . --orphan-policy revert     # revert claimed-but-unclosed
ortus grind . -c "<custom condition>"    # custom per-iteration task text

CodeGraph

CodeGraph is a prerequisite of this repo, not an enhancement. Ask it before grep, find, or opening files: the codegraph_explore MCP tool when it is registered, codegraph explore "<symbols or question>" otherwise. A missing CLI, index, or MCP capability is fatal under codegraph = "required" — stop and report the missing prerequisite instead of falling back to a slower search.

Session-close protocol

Before saying "done", verify:

1. git status — what changed
2. git add the relevant files
3. git commit with a clear message
4. bd close <id> --reason "..." — the issue, not just the code
5. git push to the remote, when one is configured

Work is not done until it is pushed.