{"owner":"gastownhall","repo":"beads","hasSkills":true,"totalSkillsCount":70,"totalTokensCount":34205,"categories":["anthropic-skill","marketplace","copilot-instructions","root-instruction","plugin-manifest","command-prompt","subagent-persona","claude-rule"],"hasMcp":false,"mcpConfig":null,"found":[".claude/skills/beads-docs/SKILL.md","internal/templates/skills/beads/SKILL.md",".claude-plugin/marketplace.json",".github/copilot-instructions.md","plugins/beads/skills/beads/SKILL.md","AGENTS.md","plugins/beads/README.md","integrations/claude-code/commands/plan-to-beads.md","plugins/beads/agents/task-agent.md","plugins/beads/.copilot-plugin/plugin.json","CLAUDE.md","engdocs/CLAUDE.md","plugins/beads/.codex-plugin/plugin.json","plugins/beads/.claude-plugin/plugin.json",".claude/skills/beads-docs/references/simplification.md",".claude/skills/beads-docs/references/terminology.md",".claude/skills/beads-docs/references/verification.md","internal/templates/agents/defaults/beads-section.md","internal/templates/agents/defaults/beads-section-codex.md","internal/templates/agents/defaults/beads-section-minimal.md","plugins/beads/.codex-plugin/hooks/hooks.json","plugins/beads/skills/beads/CLAUDE.md","plugins/beads/skills/beads/README.md","internal/templates/skills/beads/agents/openai.yaml","plugins/beads/skills/beads/agents/openai.yaml","plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md","plugins/beads/skills/beads/commands/audit.md","plugins/beads/skills/beads/commands/blocked.md","plugins/beads/skills/beads/commands/close.md","plugins/beads/skills/beads/commands/comments.md","plugins/beads/skills/beads/commands/compact.md","plugins/beads/skills/beads/commands/create.md","plugins/beads/skills/beads/commands/decision.md","plugins/beads/skills/beads/commands/delete.md","plugins/beads/skills/beads/commands/dep.md","plugins/beads/skills/beads/commands/epic.md","plugins/beads/skills/beads/commands/export.md","plugins/beads/skills/beads/commands/import.md","plugins/beads/skills/beads/commands/init.md","plugins/beads/skills/beads/commands/label.md","plugins/beads/skills/beads/commands/list.md","plugins/beads/skills/beads/commands/prime.md","plugins/beads/skills/beads/commands/quickstart.md","plugins/beads/skills/beads/commands/ready.md","plugins/beads/skills/beads/commands/rename-prefix.md","plugins/beads/skills/beads/commands/reopen.md","plugins/beads/skills/beads/commands/restore.md","plugins/beads/skills/beads/commands/search.md","plugins/beads/skills/beads/commands/show.md","plugins/beads/skills/beads/commands/stats.md","plugins/beads/skills/beads/commands/sync.md","plugins/beads/skills/beads/commands/template.md","plugins/beads/skills/beads/commands/update.md","plugins/beads/skills/beads/commands/version.md","plugins/beads/skills/beads/commands/workflow.md","plugins/beads/skills/beads/resources/AGENTS.md","plugins/beads/skills/beads/resources/ASYNC_GATES.md","plugins/beads/skills/beads/resources/BOUNDARIES.md","plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md","plugins/beads/skills/beads/resources/CLI_REFERENCE.md","plugins/beads/skills/beads/resources/DEPENDENCIES.md","plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md","plugins/beads/skills/beads/resources/ISSUE_CREATION.md","plugins/beads/skills/beads/resources/MOLECULES.md","plugins/beads/skills/beads/resources/PATTERNS.md","plugins/beads/skills/beads/resources/RESUMABILITY.md","plugins/beads/skills/beads/resources/STATIC_DATA.md","plugins/beads/skills/beads/resources/TROUBLESHOOTING.md","plugins/beads/skills/beads/resources/WORKFLOWS.md","plugins/beads/skills/beads/resources/WORKTREES.md"],"skills":{".claude/skills/beads-docs/SKILL.md":"---\nname: beads-docs\ndescription: >-\n  Project conventions for writing, editing, restructuring, or reviewing the\n  beads user documentation — the Mintlify site under docs/. Use this whenever\n  you touch anything in docs/ (pages, concept docs, reference, integration\n  guides, recovery runbooks, diagrams, docs.json navigation) or write/edit\n  prose about beads, even when the request is just \"fix the docs\", \"write a\n  docs page\", \"the docs are wrong/confusing\", \"rename X across the docs\", or\n  an edit to a file under docs/. It defines the canonical concept model\n  (bead → dependencies → ready work; formula → proto → molecule/wisp; gates;\n  Dolt sync and federation), required terminology, the prose/emphasis/diagram\n  conventions, the rule that generated docs are edited at their source, and\n  the gates to run before docs work is done.\n---\n\n# Writing beads docs\n\nThis is the house style for `docs/` — the beads user documentation, published\nas a Mintlify site. The goal is docs that motivate before they jargon, say the\nsame thing the same way everywhere, show concepts as pictures and snippets\ninstead of walls of prose, and never drift from the code. Apply it to any page\nyou create, edit, or review.\n\nThe audience of `docs/` is a **user** of beads — a human or agent installing\n`bd`, tracking work, and syncing it. Contributor-facing material lives in\n`engdocs/` and `AGENTS.md` and follows different rules (it may describe the\nimplementation literally). When this skill says \"the docs,\" it means `docs/`.\n\n## 1. The canonical model\n\nBeads is a dependency-aware issue graph with a workflow layer on top. Teach it\nconsistently and link to the canonical concept page —\n**`docs/core-concepts/index.md`** — rather than re-explaining it.\n\n| Concept | Role | Key idea |\n|---|---|---|\n| **bead** (issue) | the unit of work | one tracked item with a hash ID (`bd-a1b2`), type, status, priority; \"bead\" and \"issue\" name the same thing |\n| **dependency** | ordering | `blocks` edges hide a bead from agents until its blockers close; `parent-child`, `related`, `discovered-from` organize without blocking |\n| **ready work** | what `bd ready` computes | open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier |\n| **formula** | workflow source | a TOML/JSON file defining a DAG of steps; `bd cook` compiles it into a proto |\n| **proto** | workflow template | a template epic (label `template`) with `{{variables}}`; not live work |\n| **molecule** | instantiated workflow | real beads poured from a proto (`bd mol pour`); persistent |\n| **wisp** | ephemeral molecule | same instantiation, transient lifecycle (`bd mol wisp`); purged by `bd purge` |\n| **gate** | async wait | blocks a workflow step until closed — by a human, a timer, a GitHub run/PR, or a cross-rig bead |\n| **sync** | cross-machine movement | Dolt push/pull over `refs/dolt/data` on the git remote; `.beads/issues.jsonl` is a passive export, never the database |\n| **federation** | cross-repo sync | peer-to-peer sharing of beads across repos/organizations |\n\nThe pipeline worth internalizing: **formula → (cook) → proto → (pour) →\nmolecule** or **→ (wisp) → wisp**. Gates pause molecule steps; `bd ready`\nsurfaces the claimable steps; sync moves the whole graph between machines.\n\nStorage facts that pages keep getting wrong: embedded mode (the default\n`bd init`) stores data at `.beads/embeddeddolt/`; server mode\n(`bd init --server`) uses `.beads/dolt/`. Never present `.beads/dolt/` as the\ngeneral data path.\n\n**Cross-project vocabulary (beads ↔ Gas City).** Gas City (the sibling\nproject) shares the words molecule, formula, wisp, and gate, but the two doc\ncorpora use them differently: Gas City's docs treat molecule/wisp as v1\nimplementation detail (never a user concept), and a Gas City formula is an\norchestration method the orchestrator runs across agents. In beads,\nmolecule/wisp/proto ARE user concepts, and a formula is the TOML source you\ncook into a proto. Never import Gas City's definitions into beads pages (or\nvice versa); when a page must bridge the two projects, say explicitly which\nproject's sense is meant.\n\n## 2. Required terminology\n\nUse the left column; never the right (except as noted). The full\nprose-vs-literal rename discipline is in\n[references/terminology.md](references/terminology.md).\n\n| Use this | Not this | Notes |\n|---|---|---|\n| **bead** / **issue** | \"task\", \"ticket\", \"TODO item\" as the unit's name | Both terms are correct and interchangeable; lead with *bead* when teaching identity, use *issue* when mirroring CLI output or flags (`bd create`, \"issue types\"). \"task\" is one issue *type*, never the generic unit. |\n| **ready work** | \"unblocked queue\", \"available tasks\", \"the ready set\" as a formal term | Say what `bd ready` returns: open beads with no open blockers. |\n| **proto** | \"template\" as a noun for the concept | `template` stays only as the literal label name protos carry. |\n| **molecule** | \"mol\" in prose | `mol` is the command literal (`bd mol pour`); the concept is a molecule. |\n| **formula** | conflating formula with molecule/proto | The formula is the *file*; cooking makes a proto; pouring makes live work. |\n| **gate** | \"barrier\", \"checkpoint\", \"lock\" | Gates are async wait conditions with types (human, timer, gh:run, gh:pr, bead). |\n| **sync** = Dolt push/pull | export/import as a sync workflow | `bd dolt push` / `bd dolt pull` over `refs/dolt/data`. `.beads/issues.jsonl` is a passive export for viewers and interchange. |\n| **embedded mode** / **server mode** | \"local mode\", \"daemon mode\" for storage | Embedded is the default; data at `.beads/embeddeddolt/`. Server mode connects to `dolt sql-server`; data at `.beads/dolt/`. |\n| **federation** | \"multi-repo sync\" as a distinct feature name | Federation is the peer-to-peer cross-repo sharing feature. |\n| **hash ID** | \"random ID\", \"UUID\" | IDs like `bd-a1b2` are content-derived hashes sized adaptively to prevent collisions. |\n\n## 3. Content stance\n\n- **Motivate before you mechanize.** Lead a page with the problem it solves,\n  then the solution, then the mechanics. Never open on vocabulary.\n- **Docs are not the project's history.** No `internal/*` package paths, no\n  \"this was removed in vX\", no \"(v0.20.1+)\" gating on user pages — beads is a\n  1.x product and pre-1.0 archaeology belongs in `engdocs/` or the CHANGELOG.\n- **Lead with the value.** Beads' value is persistent, dependency-aware memory\n  for coding agents — agents that survive context loss because the work graph\n  outlives the session. The comparison framing (vs GitHub Issues, Jira,\n  markdown TODO lists) is the best newcomer conversion tool; keep it early\n  where it exists.\n- **One concrete example beats three abstract sentences.** Where you assert a\n  capability, show a `bd` invocation and what it prints.\n\n## 4. Information architecture\n\nNavigation lives in `docs/docs.json`: Getting Started, Core Concepts,\nArchitecture, Workflows, Recovery, Multi-Agent, Integrations, Community, and\nReference — with the generated CLI Reference nested inside Reference as a\ncollapsed sub-group.\n\n- **Every section has an index/Overview page** that introduces the section in\n  a sentence or two, then lists every child page with a one-line accurate\n  summary and link.\n- One page, one purpose. A page that tries to teach *and* specify does\n  neither — split it and cross-link.\n- Concept material is unified on `core-concepts/index`; don't re-derive the\n  model on other pages — link to it.\n- The repository map belongs in the README, not in `docs/`.\n\n## 5. Prose doctrine — cut words, sharpen points\n\nMost bloat is information stored in the wrong medium. Move it to a cheaper\ncarrier, then delete what isn't pulling weight. Every page must **stand\nalone** — a reader landing cold needs a one-line setup, not a previous page.\n\n**Convert** (move load off prose):\n- A relationship or sequence → a **diagram** (mermaid renders natively;\n  richer diagrams follow the Excalidraw pipeline — see §7).\n- Parallel options/fields/comparisons → a **table**.\n- \"you run X, which does Y\" narration → an **annotated CLI snippet** (show\n  the command and its output, comment the interesting lines).\n- Edge cases and deep mechanics → an `<Accordion>`, or a reference page.\n  Keep the 80% case on the page.\n\n**Delete** (the load was fake): throat-clearing openers (\"In this section\nwe'll…\"), hedge chains (\"generally / typically / in most cases\"),\nrestatement, narrating an artifact a snippet already shows, and adjectives\nstanding in for evidence.\n\nWhen you run a deliberate simplification pass, follow\n[references/simplification.md](references/simplification.md) — the per-page\nloop and the two guardrails that keep a trim honest: a **loss-check** (never\ndrop a fact that lives nowhere else) and a **fact-check** (trimmed prose must\nnot drift from the code).\n\n## 6. Emphasis and formatting\n\n- **Bold** *names a term*, on first mention only. *Italic* marks a property\n  or contrast. ~1–2 marks per paragraph; never re-emphasize a term already\n  introduced; never give one phrase both treatments.\n- No body `# H1` — the frontmatter `title` is the H1. Use `##`/`###`.\n- Links are root-relative and extensionless (`/getting-started/quickstart`).\n  Links out of the site (engdocs/, repo files) use full GitHub URLs.\n- Mintlify parses `.md` as MDX: no HTML comments (`{/* … */}` instead), and\n  angle-bracket placeholders like `<id>` must stay inside backticks or code\n  fences.\n- Mintlify components (`<Note>`, `<Tip>`, `<Warning>`, `<Accordion>`)\n  sparingly — they lose force with repetition.\n\n## 7. Diagrams\n\nMermaid fences render natively — prefer them for graphs and flows. For richer\ndiagrams use the Excalidraw pipeline: author the `.excalidraw` source under\n`docs/diagrams/excalidraw/`, render with `make diagrams-excalidraw` (source\nand rendered `.svg` are both committed), embed as\n`/diagrams/excalidraw-rendered/<name>.svg` with descriptive alt text, and\nkeep labels short (a two-line \"Name / role\" beats a sentence crammed in a\nbox). Two non-negotiables:\n\n- **Rasterize and look at every rendered diagram** — text overflow and layout\n  problems are invisible in a text diff.\n- **Diagrams and images cannot be reviewed in a diff.** Render them and get\n  the maintainer's approval before committing.\n\n## 8. Generated content is edited at its source\n\nNever hand-edit a generated file. The generated surfaces are:\n\n- `docs/cli-reference/*.md` and the CLI Reference pages array inside\n  `docs/docs.json` — bd emits vendor-neutral pages (`bd help --docs-root`,\n  from the Cobra command strings in `cmd/bd/*.go`) into an uncommitted\n  staging tree, and `tools/docsmint` post-processes them into the committed\n  Mintlify form. bd itself never emits Mintlify (or any site-generator)\n  specifics; that lives in docsmint.\n- `docs/CLI_REFERENCE.md` — the single-file reference, emitted directly by\n  `bd help --docs-root`.\n\nTo change wording in any of them, edit the Go source (`Short:`, `Long:`,\n`Example:` strings) and run `./scripts/generate-cli-docs.sh` (which runs both\nstages). To change the Mintlify page form itself (comment markers, link\nstyle, nav), edit `tools/docsmint` and its tests. The drift gates\n(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,\nand the docs-autofix bot) fail or auto-fix any hand edit.\n\n**The docs describe the pinned release, not main.** `docs/cli-docs.pin`\nnames the release tag the whole docs corpus targets; the pipeline builds bd\nfrom that tag and validates against it, so a Go-source edit on main shows up\nin the committed docs only after the pin is bumped (at release time,\nfollowed by a regeneration). Hand-written pages follow the same policy:\ndocument what the pinned release does, never main-only features. See\n`engdocs/decisions/2026-07-17-docs-release-pin.md`.\n\n## 9. Verify before you call it done\n\nRun the gates in [references/verification.md](references/verification.md).\nThe short list: `bazel test //test/docsync:docsync_test --config=ci`\n(nav↔file sync + link conventions),\n`./scripts/generate-cli-docs.sh --check` (generated docs fresh),\n`./scripts/check-doc-freshness.sh` (Last reviewed markers), and a live\npreview with `make docs-dev` (or `./mint.sh dev`) at `localhost:3000`.\n\nWhen you **move or remove a page**: add a redirect to the `redirects` array\nin `docs/docs.json`, rewrite inbound links repo-wide (README, engdocs/,\nexamples/, npm-package/, plugin resources — grep, don't guess), and check\nwhether `bd` prints the old path (if so, fix the Go source and regenerate —\nnever a pointer stub; decision 6 covers old routes with redirects).\n\n## 10. Review and commit discipline\n\n- **Author → the maintainer reviews → commit on explicit approval.** This\n  matters most for diagrams and images, which can't be reviewed in a text\n  diff.\n- Group commits by audience: user docs (`docs/`) separate from contributor\n  docs (`engdocs/`, `AGENTS.md`) separate from generator/Go changes.\n- Track docs work as bd issues per `AGENTS.md`.\n","internal/templates/skills/beads/SKILL.md":"---\nname: beads\ndescription: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.\n---\n\n# Beads\n\nUse Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.\n\n## First Step\n\nRun:\n\n```bash\nbd prime\n```\n\nIf that prints nothing, check whether the repository has an active Beads workspace:\n\n```bash\nbd where\n```\n\n## Preferred Route\n\nUse the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.\n\n## Core CLI Workflow\n\n1. Find work:\n\n```bash\nbd ready\nbd list --status=open\nbd list --status=in_progress\n```\n\n2. Inspect before editing:\n\n```bash\nbd show <id>\n```\n\n3. Claim work atomically:\n\n```bash\nbd update <id> --claim\n```\n\n4. Create durable follow-up work when implementation reveals new tasks:\n\n```bash\nbd create \"Short title\" --description=\"Why this exists and what needs to be done\" --type=task --priority=2\n```\n\n5. Close completed work:\n\n```bash\nbd close <id> --reason=\"Completed\"\n```\n\n## What Belongs In Beads\n\nUse Beads for:\n\n- shared project tasks\n- blockers and dependencies\n- discovered follow-up work\n- work that must survive thread reset, compaction, or handoff\n- status that another person or agent should be able to resume\n\nUse agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.\n\n## Rules\n\n- Do not create markdown TODO files as the source of truth when Beads is available.\n- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.\n- Prefer `--json` when parsing `bd` output programmatically.\n- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.\n- Do not auto-close or mutate tasks unless the work is actually complete.\n",".claude-plugin/marketplace.json":"{\n  \"name\": \"beads-marketplace\",\n  \"description\": \"Local marketplace for beads plugin development\",\n  \"owner\": {\n    \"name\": \"Steve Yegge\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"beads\",\n      \"source\": \"./plugins/beads\",\n      \"description\": \"AI-supervised issue tracker for coding workflows\",\n      \"version\": \"1.3.0\"\n    }\n  ]\n}\n",".github/copilot-instructions.md":"# GitHub Copilot instructions for beads\n\nThe canonical contributor instructions for this repository are in\n[AGENTS.md](../AGENTS.md); area-specific rules are in the nested `AGENTS.md`\nfiles listed in its routing table. Read those, not this file, for workflow,\nbuild, test, and scope rules.\n\nThe rules most often missed in review:\n\n- A PR must close a documented GitHub issue (filed before or alongside it).\n- Build with `make install`, never `go build -o bd ./cmd/bd` or `go install ./cmd/bd`.\n- `make ci-pr-lint` must pass with zero issues; choose tests with\n  [engdocs/TESTING.md](../engdocs/TESTING.md).\n- Never create test issues in a production database; use `t.TempDir()`.\n- CLI output uses small Unicode status symbols, never emoji icons.\n","plugins/beads/skills/beads/SKILL.md":"---\nname: beads\ndescription: >\n  Dolt-powered issue tracker for multi-session work with dependencies and persistent\n  memory across conversation compaction. Use when work spans sessions, has blockers,\n  or needs context recovery after compaction. Trigger with \"create task\", \"what's\n  ready\", \"track this work\", \"resume after compaction\". Make sure to use this skill\n  whenever managing multi-session work, tracking dependencies, or recovering context.\nallowed-tools: \"Read,Bash(bd:*)\"\nversion: \"0.60.0\"\nauthor: \"Steve Yegge <steve.yegge@gmail.com>\"\nlicense: \"MIT\"\ncompatible-with: [claude-code, codex]\ntags: [issue-tracking, task-management, multi-session, dependencies]\n---\n\n# Beads - Persistent Task Memory for AI Agents\n\nGraph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.\n\n## bd vs TodoWrite\n\n**Decision test**: \"Will I need this context in 2 weeks?\" YES = bd, NO = TodoWrite.\n\n| bd (persistent) | TodoWrite (ephemeral) |\n|-----------------|----------------------|\n| Multi-session, dependencies, compaction survival | Single-session linear tasks |\n| Dolt-backed team sync | Conversation-scoped |\n\nSee [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.\n\n## Prerequisites\n\n```bash\nbd --version  # Requires v0.60.0+\n```\n\n- **bd CLI** installed and in PATH\n- **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)\n- **Initialization**: `bd init` run once (humans do this, not agents)\n\n## CLI Reference\n\n**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).\n**Run `bd <command> --help`** for specific command usage.\n\nEssential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd dolt push`\n\n## Session Protocol\n\n1. `bd ready` — Find unblocked work\n2. `bd show <id>` — Get full context\n3. `bd update <id> --claim` — Claim and start work atomically\n4. Add notes as you work (critical for compaction survival)\n5. `bd close <id> --reason \"...\"` — Complete task\n6. `bd dolt push` — Push to Dolt remote (if configured)\n\n## Output\n\nAppend `--json` to any command for structured output. Use `bd show <id> --long` for extended metadata. Status icons: `○` open `◐` in_progress `●` blocked `✓` closed `❄` deferred.\n\n## Error Handling\n\n| Error | Fix |\n|-------|-----|\n| `database not found` | `bd init <prefix>` in project root |\n| `not in a git repository` | `git init` first |\n| `disk I/O error (522)` | Move `.beads/` off cloud-synced filesystem |\n| Status updates lag | Use server mode: `bd dolt start` |\n\nSee [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.\n\n## Examples\n\n**Track a multi-session feature:**\n```bash\nbd create \"OAuth integration\" -t epic -p 1 --json\nbd create \"Token storage\" -t task --deps blocks:oauth-id --json\nbd ready --json                    # Shows unblocked work\nbd update <id> --claim --json      # Claim and start\nbd close <id> --reason \"Implemented with refresh tokens\" --json\n```\n\n**Recover after compaction:** `bd list --status in_progress --json` then `bd show <id> --long`\n\n**Discover work mid-task:** `bd create \"Found bug\" -t bug -p 1 --deps discovered-from:<current-id> --json`\n\n## Advanced Features\n\n| Feature | CLI | Resource |\n|---------|-----|----------|\n| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |\n| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |\n| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |\n| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |\n| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |\n\n## Resources\n\n| Category | Files |\n|----------|-------|\n| **Getting Started** | [BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) (live reference pointers), [WORKFLOWS.md](resources/WORKFLOWS.md) |\n| **Core Concepts** | [DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md) |\n| **Resilience** | [RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) |\n| **Advanced** | [MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md) |\n| **Reference** | [STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) |\n\n## Validation\n\nIf `bd --version` reports newer than `0.60.0`, this skill may be stale. Run `bd prime` for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).\n","AGENTS.md":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","plugins/beads/README.md":"# Beads Plugin\n\nThis is the shared Claude/Codex plugin package for Beads. Claude and Codex use separate manifest files, but they share the same skill tree.\n\n## Layout\n\n- `.codex-plugin/plugin.json` describes the Codex plugin.\n- `.claude-plugin/plugin.json` describes the Claude plugin.\n- `skills/beads/` contains the plugin-owned Beads skill.\n- `.codex-plugin/hooks/hooks.json` contains Codex-only lifecycle hooks for startup and compaction-aware context refresh.\n- The Claude marketplace entry lives at `.claude-plugin/marketplace.json`.\n\n## Codex Hooks\n\nThe Codex plugin exposes native hooks through `.codex-plugin/plugin.json`, which points at `.codex-plugin/hooks/hooks.json`.\nWith Codex 0.129.0+, `/hooks` shows these lifecycle handlers:\n\n- `SessionStart` runs `bd codex-hook SessionStart` for `startup|resume|clear` and injects full `bd prime` output.\n- `PreCompact` runs `bd codex-hook PreCompact` for `manual|auto` and warns if `bd prime --memories-only` cannot run.\n- `PostCompact` runs `bd codex-hook PostCompact` for `manual|auto` and records a one-shot refresh marker in the user cache/temp directory.\n- `UserPromptSubmit` runs `bd codex-hook UserPromptSubmit` and, when a refresh marker exists, injects full `bd prime` output once before clearing it.\n\nIf the plugin is not installed, `bd setup codex` writes an equivalent `.codex/hooks.json` fallback and enables `[features].hooks = true`.\n\n## Local Development\n\nClaude Code uses `.claude-plugin/marketplace.json`, which points at this shared package root.\n","integrations/claude-code/commands/plan-to-beads.md":"# Convert Plan to Beads Tasks\n\n## description:\nConvert a Claude Code plan file into beads epic + tasks for cross-session tracking.\n\n## Arguments\n$ARGUMENTS (optional - path to plan file, defaults to most recent in ~/.claude/plans/)\n\n---\n\nUse the **Task tool** with `subagent_type='general-purpose'` to convert the plan.\n\n## Agent Instructions\n\nThe agent should:\n\n1. **Find the plan file**\n   - If argument provided, use that path\n   - Otherwise: `ls -t ~/.claude/plans/*.md | head -1`\n\n2. **Parse the plan structure**\n   - Title: First `# Plan:` or `#` heading\n   - Description: Content under `## Summary`\n   - Tasks: Each `### Phase N:` or `### N.` section\n   - File list: Include in epic description\n\n3. **Create the epic**\n   ```bash\n   bd create \"[Plan Title]\" -t epic -p 1 -d \"[summary]. Files: N to modify.\" --json\n   ```\n\n4. **Create tasks from phases**\n   - Each phase becomes a task\n   - Use first paragraph of phase content as description\n   ```bash\n   bd create \"[Phase title]\" -t task -p 2 -d \"[description]\" --json\n   ```\n\n5. **Add sequential dependencies**\n   - Phases are sequential: `bd dep add <phase2> <phase1>`\n\n6. **Link tasks to epic**\n   - `bd dep add <epic> <task>` for each task\n\n7. **Return a concise summary** (not raw output):\n   ```\n   Created from: [filename]\n\n   Epic: [title] ([epic-id])\n     ├── [Phase 1] ([id]) - ready\n     ├── [Phase 2] ([id]) - blocked by [prev]\n     └── [Phase 3] ([id]) - blocked by [prev]\n\n   Total: [N] tasks\n   Run `bd ready` to start.\n   ```\n\n## Notes\n\n- Original plan file is preserved for reference\n- Task descriptions use first paragraph only (keeps them scannable)\n- Sequential phases get automatic dependencies\n","plugins/beads/agents/task-agent.md":"---\ndescription: Autonomous agent that finds and completes ready tasks\n---\n\nYou are a task-completion agent for beads. Your goal is to find ready work and complete it autonomously.\n\n# Agent Workflow\n\n1. **Find Ready Work**\n   - Use the `ready` MCP tool to get unblocked tasks\n   - Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)\n   - If no ready tasks, report completion\n\n2. **Claim the Task**\n   - Use the `show` tool to get full task details\n   - Use the `claim` tool for atomic start-work semantics\n   - Report what you're working on\n\n3. **Execute the Task**\n   - Read the task description carefully\n   - Use available tools to complete the work\n   - Follow best practices from project documentation\n   - Run tests if applicable\n\n4. **Track Discoveries**\n   - If you find bugs, TODOs, or related work:\n     - Use `create` tool to file new issues\n     - Use `dep` tool with `discovered-from` to link them\n   - This maintains context for future work\n\n5. **Complete the Task**\n   - Verify the work is done correctly\n   - Use `close` tool with a clear completion message\n   - Report what was accomplished\n\n6. **Continue**\n   - Check for newly unblocked work with `ready`\n   - Repeat the cycle\n\n# Important Guidelines\n\n- Always claim before working (MCP: `claim`; CLI: `--claim`) and close when done\n- Link discovered work with `discovered-from` dependencies\n- Don't close issues unless work is actually complete\n- If blocked, use `update` to set status to `blocked` and explain why\n- Communicate clearly about progress and blockers\n\n# Available Tools\n\nVia beads MCP server:\n- `ready` - Find unblocked tasks\n- `show` - Get task details\n- `claim` - Atomically claim task for work\n- `update` - Update task status/fields\n- `create` - Create new issues\n- `dep` - Manage dependencies\n- `close` - Complete tasks\n- `blocked` - Check blocked issues\n- `stats` - View project stats\n\nYou are autonomous but should communicate your progress clearly. Start by finding ready work!\n","plugins/beads/.copilot-plugin/plugin.json":"{\n  \"name\": \"beads\",\n  \"description\": \"AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.\",\n  \"version\": \"1.3.0\",\n  \"author\": {\n    \"name\": \"Steve Yegge\",\n    \"url\": \"https://github.com/steveyegge\"\n  },\n  \"repository\": \"https://github.com/gastownhall/beads\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://github.com/gastownhall/beads\",\n  \"keywords\": [\n    \"issue-tracker\",\n    \"task-management\",\n    \"ai-workflow\",\n    \"agent-memory\"\n  ],\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bd prime\"\n          }\n        ]\n      }\n    ],\n    \"PreCompact\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bd prime\"\n          }\n        ]\n      }\n    ]\n  }\n}\n","CLAUDE.md":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","engdocs/CLAUDE.md":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","plugins/beads/.codex-plugin/plugin.json":"# codex-plugin Plugin Manifest\n\nPath: `plugins/beads/.codex-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/plugin.json)","plugins/beads/.claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `plugins/beads/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.claude-plugin/plugin.json)",".claude/skills/beads-docs/references/simplification.md":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/simplification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/simplification.md)",".claude/skills/beads-docs/references/terminology.md":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/terminology.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/terminology.md)",".claude/skills/beads-docs/references/verification.md":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/verification.md)","internal/templates/agents/defaults/beads-section.md":"# Subagent: beads-section\n\nPath: `internal/templates/agents/defaults/beads-section.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section.md)","internal/templates/agents/defaults/beads-section-codex.md":"# Subagent: beads-section-codex\n\nPath: `internal/templates/agents/defaults/beads-section-codex.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-codex.md)","internal/templates/agents/defaults/beads-section-minimal.md":"# Subagent: beads-section-minimal\n\nPath: `internal/templates/agents/defaults/beads-section-minimal.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-minimal.md)","plugins/beads/.codex-plugin/hooks/hooks.json":"# Hooks Skill\n\nPath: `plugins/beads/.codex-plugin/hooks/hooks.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/hooks/hooks.json)","plugins/beads/skills/beads/CLAUDE.md":"# Beads Skill\n\nPath: `plugins/beads/skills/beads/CLAUDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/CLAUDE.md)","plugins/beads/skills/beads/README.md":"# beads Documentation\n\nPath: `plugins/beads/skills/beads/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/README.md)","internal/templates/skills/beads/agents/openai.yaml":"# Agents Skill\n\nPath: `internal/templates/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/skills/beads/agents/openai.yaml)","plugins/beads/skills/beads/agents/openai.yaml":"# Agents Skill\n\nPath: `plugins/beads/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/agents/openai.yaml)","plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md":"# Adr Skill\n\nPath: `plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md)","plugins/beads/skills/beads/commands/audit.md":"# Command: /audit\n\nPath: `plugins/beads/skills/beads/commands/audit.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/audit.md)","plugins/beads/skills/beads/commands/blocked.md":"# Command: /blocked\n\nPath: `plugins/beads/skills/beads/commands/blocked.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/blocked.md)","plugins/beads/skills/beads/commands/close.md":"# Command: /close\n\nPath: `plugins/beads/skills/beads/commands/close.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/close.md)","plugins/beads/skills/beads/commands/comments.md":"# Command: /comments\n\nPath: `plugins/beads/skills/beads/commands/comments.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/comments.md)","plugins/beads/skills/beads/commands/compact.md":"# Command: /compact\n\nPath: `plugins/beads/skills/beads/commands/compact.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/compact.md)","plugins/beads/skills/beads/commands/create.md":"# Command: /create\n\nPath: `plugins/beads/skills/beads/commands/create.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/create.md)","plugins/beads/skills/beads/commands/decision.md":"# Command: /decision\n\nPath: `plugins/beads/skills/beads/commands/decision.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/decision.md)","plugins/beads/skills/beads/commands/delete.md":"# Command: /delete\n\nPath: `plugins/beads/skills/beads/commands/delete.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/delete.md)","plugins/beads/skills/beads/commands/dep.md":"# Command: /dep\n\nPath: `plugins/beads/skills/beads/commands/dep.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/dep.md)","plugins/beads/skills/beads/commands/epic.md":"# Command: /epic\n\nPath: `plugins/beads/skills/beads/commands/epic.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/epic.md)","plugins/beads/skills/beads/commands/export.md":"# Command: /export\n\nPath: `plugins/beads/skills/beads/commands/export.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/export.md)","plugins/beads/skills/beads/commands/import.md":"# Command: /import\n\nPath: `plugins/beads/skills/beads/commands/import.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/import.md)","plugins/beads/skills/beads/commands/init.md":"# Command: /init\n\nPath: `plugins/beads/skills/beads/commands/init.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/init.md)","plugins/beads/skills/beads/commands/label.md":"# Command: /label\n\nPath: `plugins/beads/skills/beads/commands/label.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/label.md)","plugins/beads/skills/beads/commands/list.md":"# Command: /list\n\nPath: `plugins/beads/skills/beads/commands/list.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/list.md)","plugins/beads/skills/beads/commands/prime.md":"# Command: /prime\n\nPath: `plugins/beads/skills/beads/commands/prime.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/prime.md)","plugins/beads/skills/beads/commands/quickstart.md":"# Command: /quickstart\n\nPath: `plugins/beads/skills/beads/commands/quickstart.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/quickstart.md)","plugins/beads/skills/beads/commands/ready.md":"# Command: /ready\n\nPath: `plugins/beads/skills/beads/commands/ready.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/ready.md)","plugins/beads/skills/beads/commands/rename-prefix.md":"# Command: /rename-prefix\n\nPath: `plugins/beads/skills/beads/commands/rename-prefix.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/rename-prefix.md)","plugins/beads/skills/beads/commands/reopen.md":"# Command: /reopen\n\nPath: `plugins/beads/skills/beads/commands/reopen.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/reopen.md)","plugins/beads/skills/beads/commands/restore.md":"# Command: /restore\n\nPath: `plugins/beads/skills/beads/commands/restore.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/restore.md)","plugins/beads/skills/beads/commands/search.md":"# Command: /search\n\nPath: `plugins/beads/skills/beads/commands/search.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/search.md)","plugins/beads/skills/beads/commands/show.md":"# Command: /show\n\nPath: `plugins/beads/skills/beads/commands/show.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/show.md)","plugins/beads/skills/beads/commands/stats.md":"# Command: /stats\n\nPath: `plugins/beads/skills/beads/commands/stats.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/stats.md)","plugins/beads/skills/beads/commands/sync.md":"# Command: /sync\n\nPath: `plugins/beads/skills/beads/commands/sync.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/sync.md)","plugins/beads/skills/beads/commands/template.md":"# Command: /template\n\nPath: `plugins/beads/skills/beads/commands/template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/template.md)","plugins/beads/skills/beads/commands/update.md":"# Command: /update\n\nPath: `plugins/beads/skills/beads/commands/update.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/update.md)","plugins/beads/skills/beads/commands/version.md":"# Command: /version\n\nPath: `plugins/beads/skills/beads/commands/version.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/version.md)","plugins/beads/skills/beads/commands/workflow.md":"# Command: /workflow\n\nPath: `plugins/beads/skills/beads/commands/workflow.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/workflow.md)","plugins/beads/skills/beads/resources/AGENTS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/AGENTS.md)","plugins/beads/skills/beads/resources/ASYNC_GATES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ASYNC_GATES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ASYNC_GATES.md)","plugins/beads/skills/beads/resources/BOUNDARIES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/BOUNDARIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/BOUNDARIES.md)","plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md)","plugins/beads/skills/beads/resources/CLI_REFERENCE.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CLI_REFERENCE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CLI_REFERENCE.md)","plugins/beads/skills/beads/resources/DEPENDENCIES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/DEPENDENCIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/DEPENDENCIES.md)","plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md)","plugins/beads/skills/beads/resources/ISSUE_CREATION.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ISSUE_CREATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ISSUE_CREATION.md)","plugins/beads/skills/beads/resources/MOLECULES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/MOLECULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/MOLECULES.md)","plugins/beads/skills/beads/resources/PATTERNS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/PATTERNS.md)","plugins/beads/skills/beads/resources/RESUMABILITY.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/RESUMABILITY.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/RESUMABILITY.md)","plugins/beads/skills/beads/resources/STATIC_DATA.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/STATIC_DATA.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/STATIC_DATA.md)","plugins/beads/skills/beads/resources/TROUBLESHOOTING.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/TROUBLESHOOTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md)","plugins/beads/skills/beads/resources/WORKFLOWS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKFLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKFLOWS.md)","plugins/beads/skills/beads/resources/WORKTREES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKTREES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKTREES.md)"},"files":{".claude/skills/beads-docs/SKILL.md":"---\nname: beads-docs\ndescription: >-\n  Project conventions for writing, editing, restructuring, or reviewing the\n  beads user documentation — the Mintlify site under docs/. Use this whenever\n  you touch anything in docs/ (pages, concept docs, reference, integration\n  guides, recovery runbooks, diagrams, docs.json navigation) or write/edit\n  prose about beads, even when the request is just \"fix the docs\", \"write a\n  docs page\", \"the docs are wrong/confusing\", \"rename X across the docs\", or\n  an edit to a file under docs/. It defines the canonical concept model\n  (bead → dependencies → ready work; formula → proto → molecule/wisp; gates;\n  Dolt sync and federation), required terminology, the prose/emphasis/diagram\n  conventions, the rule that generated docs are edited at their source, and\n  the gates to run before docs work is done.\n---\n\n# Writing beads docs\n\nThis is the house style for `docs/` — the beads user documentation, published\nas a Mintlify site. The goal is docs that motivate before they jargon, say the\nsame thing the same way everywhere, show concepts as pictures and snippets\ninstead of walls of prose, and never drift from the code. Apply it to any page\nyou create, edit, or review.\n\nThe audience of `docs/` is a **user** of beads — a human or agent installing\n`bd`, tracking work, and syncing it. Contributor-facing material lives in\n`engdocs/` and `AGENTS.md` and follows different rules (it may describe the\nimplementation literally). When this skill says \"the docs,\" it means `docs/`.\n\n## 1. The canonical model\n\nBeads is a dependency-aware issue graph with a workflow layer on top. Teach it\nconsistently and link to the canonical concept page —\n**`docs/core-concepts/index.md`** — rather than re-explaining it.\n\n| Concept | Role | Key idea |\n|---|---|---|\n| **bead** (issue) | the unit of work | one tracked item with a hash ID (`bd-a1b2`), type, status, priority; \"bead\" and \"issue\" name the same thing |\n| **dependency** | ordering | `blocks` edges hide a bead from agents until its blockers close; `parent-child`, `related`, `discovered-from` organize without blocking |\n| **ready work** | what `bd ready` computes | open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier |\n| **formula** | workflow source | a TOML/JSON file defining a DAG of steps; `bd cook` compiles it into a proto |\n| **proto** | workflow template | a template epic (label `template`) with `{{variables}}`; not live work |\n| **molecule** | instantiated workflow | real beads poured from a proto (`bd mol pour`); persistent |\n| **wisp** | ephemeral molecule | same instantiation, transient lifecycle (`bd mol wisp`); purged by `bd purge` |\n| **gate** | async wait | blocks a workflow step until closed — by a human, a timer, a GitHub run/PR, or a cross-rig bead |\n| **sync** | cross-machine movement | Dolt push/pull over `refs/dolt/data` on the git remote; `.beads/issues.jsonl` is a passive export, never the database |\n| **federation** | cross-repo sync | peer-to-peer sharing of beads across repos/organizations |\n\nThe pipeline worth internalizing: **formula → (cook) → proto → (pour) →\nmolecule** or **→ (wisp) → wisp**. Gates pause molecule steps; `bd ready`\nsurfaces the claimable steps; sync moves the whole graph between machines.\n\nStorage facts that pages keep getting wrong: embedded mode (the default\n`bd init`) stores data at `.beads/embeddeddolt/`; server mode\n(`bd init --server`) uses `.beads/dolt/`. Never present `.beads/dolt/` as the\ngeneral data path.\n\n**Cross-project vocabulary (beads ↔ Gas City).** Gas City (the sibling\nproject) shares the words molecule, formula, wisp, and gate, but the two doc\ncorpora use them differently: Gas City's docs treat molecule/wisp as v1\nimplementation detail (never a user concept), and a Gas City formula is an\norchestration method the orchestrator runs across agents. In beads,\nmolecule/wisp/proto ARE user concepts, and a formula is the TOML source you\ncook into a proto. Never import Gas City's definitions into beads pages (or\nvice versa); when a page must bridge the two projects, say explicitly which\nproject's sense is meant.\n\n## 2. Required terminology\n\nUse the left column; never the right (except as noted). The full\nprose-vs-literal rename discipline is in\n[references/terminology.md](references/terminology.md).\n\n| Use this | Not this | Notes |\n|---|---|---|\n| **bead** / **issue** | \"task\", \"ticket\", \"TODO item\" as the unit's name | Both terms are correct and interchangeable; lead with *bead* when teaching identity, use *issue* when mirroring CLI output or flags (`bd create`, \"issue types\"). \"task\" is one issue *type*, never the generic unit. |\n| **ready work** | \"unblocked queue\", \"available tasks\", \"the ready set\" as a formal term | Say what `bd ready` returns: open beads with no open blockers. |\n| **proto** | \"template\" as a noun for the concept | `template` stays only as the literal label name protos carry. |\n| **molecule** | \"mol\" in prose | `mol` is the command literal (`bd mol pour`); the concept is a molecule. |\n| **formula** | conflating formula with molecule/proto | The formula is the *file*; cooking makes a proto; pouring makes live work. |\n| **gate** | \"barrier\", \"checkpoint\", \"lock\" | Gates are async wait conditions with types (human, timer, gh:run, gh:pr, bead). |\n| **sync** = Dolt push/pull | export/import as a sync workflow | `bd dolt push` / `bd dolt pull` over `refs/dolt/data`. `.beads/issues.jsonl` is a passive export for viewers and interchange. |\n| **embedded mode** / **server mode** | \"local mode\", \"daemon mode\" for storage | Embedded is the default; data at `.beads/embeddeddolt/`. Server mode connects to `dolt sql-server`; data at `.beads/dolt/`. |\n| **federation** | \"multi-repo sync\" as a distinct feature name | Federation is the peer-to-peer cross-repo sharing feature. |\n| **hash ID** | \"random ID\", \"UUID\" | IDs like `bd-a1b2` are content-derived hashes sized adaptively to prevent collisions. |\n\n## 3. Content stance\n\n- **Motivate before you mechanize.** Lead a page with the problem it solves,\n  then the solution, then the mechanics. Never open on vocabulary.\n- **Docs are not the project's history.** No `internal/*` package paths, no\n  \"this was removed in vX\", no \"(v0.20.1+)\" gating on user pages — beads is a\n  1.x product and pre-1.0 archaeology belongs in `engdocs/` or the CHANGELOG.\n- **Lead with the value.** Beads' value is persistent, dependency-aware memory\n  for coding agents — agents that survive context loss because the work graph\n  outlives the session. The comparison framing (vs GitHub Issues, Jira,\n  markdown TODO lists) is the best newcomer conversion tool; keep it early\n  where it exists.\n- **One concrete example beats three abstract sentences.** Where you assert a\n  capability, show a `bd` invocation and what it prints.\n\n## 4. Information architecture\n\nNavigation lives in `docs/docs.json`: Getting Started, Core Concepts,\nArchitecture, Workflows, Recovery, Multi-Agent, Integrations, Community, and\nReference — with the generated CLI Reference nested inside Reference as a\ncollapsed sub-group.\n\n- **Every section has an index/Overview page** that introduces the section in\n  a sentence or two, then lists every child page with a one-line accurate\n  summary and link.\n- One page, one purpose. A page that tries to teach *and* specify does\n  neither — split it and cross-link.\n- Concept material is unified on `core-concepts/index`; don't re-derive the\n  model on other pages — link to it.\n- The repository map belongs in the README, not in `docs/`.\n\n## 5. Prose doctrine — cut words, sharpen points\n\nMost bloat is information stored in the wrong medium. Move it to a cheaper\ncarrier, then delete what isn't pulling weight. Every page must **stand\nalone** — a reader landing cold needs a one-line setup, not a previous page.\n\n**Convert** (move load off prose):\n- A relationship or sequence → a **diagram** (mermaid renders natively;\n  richer diagrams follow the Excalidraw pipeline — see §7).\n- Parallel options/fields/comparisons → a **table**.\n- \"you run X, which does Y\" narration → an **annotated CLI snippet** (show\n  the command and its output, comment the interesting lines).\n- Edge cases and deep mechanics → an `<Accordion>`, or a reference page.\n  Keep the 80% case on the page.\n\n**Delete** (the load was fake): throat-clearing openers (\"In this section\nwe'll…\"), hedge chains (\"generally / typically / in most cases\"),\nrestatement, narrating an artifact a snippet already shows, and adjectives\nstanding in for evidence.\n\nWhen you run a deliberate simplification pass, follow\n[references/simplification.md](references/simplification.md) — the per-page\nloop and the two guardrails that keep a trim honest: a **loss-check** (never\ndrop a fact that lives nowhere else) and a **fact-check** (trimmed prose must\nnot drift from the code).\n\n## 6. Emphasis and formatting\n\n- **Bold** *names a term*, on first mention only. *Italic* marks a property\n  or contrast. ~1–2 marks per paragraph; never re-emphasize a term already\n  introduced; never give one phrase both treatments.\n- No body `# H1` — the frontmatter `title` is the H1. Use `##`/`###`.\n- Links are root-relative and extensionless (`/getting-started/quickstart`).\n  Links out of the site (engdocs/, repo files) use full GitHub URLs.\n- Mintlify parses `.md` as MDX: no HTML comments (`{/* … */}` instead), and\n  angle-bracket placeholders like `<id>` must stay inside backticks or code\n  fences.\n- Mintlify components (`<Note>`, `<Tip>`, `<Warning>`, `<Accordion>`)\n  sparingly — they lose force with repetition.\n\n## 7. Diagrams\n\nMermaid fences render natively — prefer them for graphs and flows. For richer\ndiagrams use the Excalidraw pipeline: author the `.excalidraw` source under\n`docs/diagrams/excalidraw/`, render with `make diagrams-excalidraw` (source\nand rendered `.svg` are both committed), embed as\n`/diagrams/excalidraw-rendered/<name>.svg` with descriptive alt text, and\nkeep labels short (a two-line \"Name / role\" beats a sentence crammed in a\nbox). Two non-negotiables:\n\n- **Rasterize and look at every rendered diagram** — text overflow and layout\n  problems are invisible in a text diff.\n- **Diagrams and images cannot be reviewed in a diff.** Render them and get\n  the maintainer's approval before committing.\n\n## 8. Generated content is edited at its source\n\nNever hand-edit a generated file. The generated surfaces are:\n\n- `docs/cli-reference/*.md` and the CLI Reference pages array inside\n  `docs/docs.json` — bd emits vendor-neutral pages (`bd help --docs-root`,\n  from the Cobra command strings in `cmd/bd/*.go`) into an uncommitted\n  staging tree, and `tools/docsmint` post-processes them into the committed\n  Mintlify form. bd itself never emits Mintlify (or any site-generator)\n  specifics; that lives in docsmint.\n- `docs/CLI_REFERENCE.md` — the single-file reference, emitted directly by\n  `bd help --docs-root`.\n\nTo change wording in any of them, edit the Go source (`Short:`, `Long:`,\n`Example:` strings) and run `./scripts/generate-cli-docs.sh` (which runs both\nstages). To change the Mintlify page form itself (comment markers, link\nstyle, nav), edit `tools/docsmint` and its tests. The drift gates\n(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,\nand the docs-autofix bot) fail or auto-fix any hand edit.\n\n**The docs describe the pinned release, not main.** `docs/cli-docs.pin`\nnames the release tag the whole docs corpus targets; the pipeline builds bd\nfrom that tag and validates against it, so a Go-source edit on main shows up\nin the committed docs only after the pin is bumped (at release time,\nfollowed by a regeneration). Hand-written pages follow the same policy:\ndocument what the pinned release does, never main-only features. See\n`engdocs/decisions/2026-07-17-docs-release-pin.md`.\n\n## 9. Verify before you call it done\n\nRun the gates in [references/verification.md](references/verification.md).\nThe short list: `bazel test //test/docsync:docsync_test --config=ci`\n(nav↔file sync + link conventions),\n`./scripts/generate-cli-docs.sh --check` (generated docs fresh),\n`./scripts/check-doc-freshness.sh` (Last reviewed markers), and a live\npreview with `make docs-dev` (or `./mint.sh dev`) at `localhost:3000`.\n\nWhen you **move or remove a page**: add a redirect to the `redirects` array\nin `docs/docs.json`, rewrite inbound links repo-wide (README, engdocs/,\nexamples/, npm-package/, plugin resources — grep, don't guess), and check\nwhether `bd` prints the old path (if so, fix the Go source and regenerate —\nnever a pointer stub; decision 6 covers old routes with redirects).\n\n## 10. Review and commit discipline\n\n- **Author → the maintainer reviews → commit on explicit approval.** This\n  matters most for diagrams and images, which can't be reviewed in a text\n  diff.\n- Group commits by audience: user docs (`docs/`) separate from contributor\n  docs (`engdocs/`, `AGENTS.md`) separate from generator/Go changes.\n- Track docs work as bd issues per `AGENTS.md`.\n","internal/templates/skills/beads/SKILL.md":"---\nname: beads\ndescription: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.\n---\n\n# Beads\n\nUse Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.\n\n## First Step\n\nRun:\n\n```bash\nbd prime\n```\n\nIf that prints nothing, check whether the repository has an active Beads workspace:\n\n```bash\nbd where\n```\n\n## Preferred Route\n\nUse the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.\n\n## Core CLI Workflow\n\n1. Find work:\n\n```bash\nbd ready\nbd list --status=open\nbd list --status=in_progress\n```\n\n2. Inspect before editing:\n\n```bash\nbd show <id>\n```\n\n3. Claim work atomically:\n\n```bash\nbd update <id> --claim\n```\n\n4. Create durable follow-up work when implementation reveals new tasks:\n\n```bash\nbd create \"Short title\" --description=\"Why this exists and what needs to be done\" --type=task --priority=2\n```\n\n5. Close completed work:\n\n```bash\nbd close <id> --reason=\"Completed\"\n```\n\n## What Belongs In Beads\n\nUse Beads for:\n\n- shared project tasks\n- blockers and dependencies\n- discovered follow-up work\n- work that must survive thread reset, compaction, or handoff\n- status that another person or agent should be able to resume\n\nUse agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.\n\n## Rules\n\n- Do not create markdown TODO files as the source of truth when Beads is available.\n- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.\n- Prefer `--json` when parsing `bd` output programmatically.\n- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.\n- Do not auto-close or mutate tasks unless the work is actually complete.\n",".claude-plugin/marketplace.json":"{\n  \"name\": \"beads-marketplace\",\n  \"description\": \"Local marketplace for beads plugin development\",\n  \"owner\": {\n    \"name\": \"Steve Yegge\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"beads\",\n      \"source\": \"./plugins/beads\",\n      \"description\": \"AI-supervised issue tracker for coding workflows\",\n      \"version\": \"1.3.0\"\n    }\n  ]\n}\n",".github/copilot-instructions.md":"# GitHub Copilot instructions for beads\n\nThe canonical contributor instructions for this repository are in\n[AGENTS.md](../AGENTS.md); area-specific rules are in the nested `AGENTS.md`\nfiles listed in its routing table. Read those, not this file, for workflow,\nbuild, test, and scope rules.\n\nThe rules most often missed in review:\n\n- A PR must close a documented GitHub issue (filed before or alongside it).\n- Build with `make install`, never `go build -o bd ./cmd/bd` or `go install ./cmd/bd`.\n- `make ci-pr-lint` must pass with zero issues; choose tests with\n  [engdocs/TESTING.md](../engdocs/TESTING.md).\n- Never create test issues in a production database; use `t.TempDir()`.\n- CLI output uses small Unicode status symbols, never emoji icons.\n","plugins/beads/skills/beads/SKILL.md":"---\nname: beads\ndescription: >\n  Dolt-powered issue tracker for multi-session work with dependencies and persistent\n  memory across conversation compaction. Use when work spans sessions, has blockers,\n  or needs context recovery after compaction. Trigger with \"create task\", \"what's\n  ready\", \"track this work\", \"resume after compaction\". Make sure to use this skill\n  whenever managing multi-session work, tracking dependencies, or recovering context.\nallowed-tools: \"Read,Bash(bd:*)\"\nversion: \"0.60.0\"\nauthor: \"Steve Yegge <steve.yegge@gmail.com>\"\nlicense: \"MIT\"\ncompatible-with: [claude-code, codex]\ntags: [issue-tracking, task-management, multi-session, dependencies]\n---\n\n# Beads - Persistent Task Memory for AI Agents\n\nGraph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.\n\n## bd vs TodoWrite\n\n**Decision test**: \"Will I need this context in 2 weeks?\" YES = bd, NO = TodoWrite.\n\n| bd (persistent) | TodoWrite (ephemeral) |\n|-----------------|----------------------|\n| Multi-session, dependencies, compaction survival | Single-session linear tasks |\n| Dolt-backed team sync | Conversation-scoped |\n\nSee [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.\n\n## Prerequisites\n\n```bash\nbd --version  # Requires v0.60.0+\n```\n\n- **bd CLI** installed and in PATH\n- **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)\n- **Initialization**: `bd init` run once (humans do this, not agents)\n\n## CLI Reference\n\n**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).\n**Run `bd <command> --help`** for specific command usage.\n\nEssential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd dolt push`\n\n## Session Protocol\n\n1. `bd ready` — Find unblocked work\n2. `bd show <id>` — Get full context\n3. `bd update <id> --claim` — Claim and start work atomically\n4. Add notes as you work (critical for compaction survival)\n5. `bd close <id> --reason \"...\"` — Complete task\n6. `bd dolt push` — Push to Dolt remote (if configured)\n\n## Output\n\nAppend `--json` to any command for structured output. Use `bd show <id> --long` for extended metadata. Status icons: `○` open `◐` in_progress `●` blocked `✓` closed `❄` deferred.\n\n## Error Handling\n\n| Error | Fix |\n|-------|-----|\n| `database not found` | `bd init <prefix>` in project root |\n| `not in a git repository` | `git init` first |\n| `disk I/O error (522)` | Move `.beads/` off cloud-synced filesystem |\n| Status updates lag | Use server mode: `bd dolt start` |\n\nSee [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.\n\n## Examples\n\n**Track a multi-session feature:**\n```bash\nbd create \"OAuth integration\" -t epic -p 1 --json\nbd create \"Token storage\" -t task --deps blocks:oauth-id --json\nbd ready --json                    # Shows unblocked work\nbd update <id> --claim --json      # Claim and start\nbd close <id> --reason \"Implemented with refresh tokens\" --json\n```\n\n**Recover after compaction:** `bd list --status in_progress --json` then `bd show <id> --long`\n\n**Discover work mid-task:** `bd create \"Found bug\" -t bug -p 1 --deps discovered-from:<current-id> --json`\n\n## Advanced Features\n\n| Feature | CLI | Resource |\n|---------|-----|----------|\n| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |\n| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |\n| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |\n| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |\n| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |\n\n## Resources\n\n| Category | Files |\n|----------|-------|\n| **Getting Started** | [BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) (live reference pointers), [WORKFLOWS.md](resources/WORKFLOWS.md) |\n| **Core Concepts** | [DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md) |\n| **Resilience** | [RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) |\n| **Advanced** | [MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md) |\n| **Reference** | [STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) |\n\n## Validation\n\nIf `bd --version` reports newer than `0.60.0`, this skill may be stale. Run `bd prime` for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).\n","AGENTS.md":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","plugins/beads/README.md":"# Beads Plugin\n\nThis is the shared Claude/Codex plugin package for Beads. Claude and Codex use separate manifest files, but they share the same skill tree.\n\n## Layout\n\n- `.codex-plugin/plugin.json` describes the Codex plugin.\n- `.claude-plugin/plugin.json` describes the Claude plugin.\n- `skills/beads/` contains the plugin-owned Beads skill.\n- `.codex-plugin/hooks/hooks.json` contains Codex-only lifecycle hooks for startup and compaction-aware context refresh.\n- The Claude marketplace entry lives at `.claude-plugin/marketplace.json`.\n\n## Codex Hooks\n\nThe Codex plugin exposes native hooks through `.codex-plugin/plugin.json`, which points at `.codex-plugin/hooks/hooks.json`.\nWith Codex 0.129.0+, `/hooks` shows these lifecycle handlers:\n\n- `SessionStart` runs `bd codex-hook SessionStart` for `startup|resume|clear` and injects full `bd prime` output.\n- `PreCompact` runs `bd codex-hook PreCompact` for `manual|auto` and warns if `bd prime --memories-only` cannot run.\n- `PostCompact` runs `bd codex-hook PostCompact` for `manual|auto` and records a one-shot refresh marker in the user cache/temp directory.\n- `UserPromptSubmit` runs `bd codex-hook UserPromptSubmit` and, when a refresh marker exists, injects full `bd prime` output once before clearing it.\n\nIf the plugin is not installed, `bd setup codex` writes an equivalent `.codex/hooks.json` fallback and enables `[features].hooks = true`.\n\n## Local Development\n\nClaude Code uses `.claude-plugin/marketplace.json`, which points at this shared package root.\n","integrations/claude-code/commands/plan-to-beads.md":"# Convert Plan to Beads Tasks\n\n## description:\nConvert a Claude Code plan file into beads epic + tasks for cross-session tracking.\n\n## Arguments\n$ARGUMENTS (optional - path to plan file, defaults to most recent in ~/.claude/plans/)\n\n---\n\nUse the **Task tool** with `subagent_type='general-purpose'` to convert the plan.\n\n## Agent Instructions\n\nThe agent should:\n\n1. **Find the plan file**\n   - If argument provided, use that path\n   - Otherwise: `ls -t ~/.claude/plans/*.md | head -1`\n\n2. **Parse the plan structure**\n   - Title: First `# Plan:` or `#` heading\n   - Description: Content under `## Summary`\n   - Tasks: Each `### Phase N:` or `### N.` section\n   - File list: Include in epic description\n\n3. **Create the epic**\n   ```bash\n   bd create \"[Plan Title]\" -t epic -p 1 -d \"[summary]. Files: N to modify.\" --json\n   ```\n\n4. **Create tasks from phases**\n   - Each phase becomes a task\n   - Use first paragraph of phase content as description\n   ```bash\n   bd create \"[Phase title]\" -t task -p 2 -d \"[description]\" --json\n   ```\n\n5. **Add sequential dependencies**\n   - Phases are sequential: `bd dep add <phase2> <phase1>`\n\n6. **Link tasks to epic**\n   - `bd dep add <epic> <task>` for each task\n\n7. **Return a concise summary** (not raw output):\n   ```\n   Created from: [filename]\n\n   Epic: [title] ([epic-id])\n     ├── [Phase 1] ([id]) - ready\n     ├── [Phase 2] ([id]) - blocked by [prev]\n     └── [Phase 3] ([id]) - blocked by [prev]\n\n   Total: [N] tasks\n   Run `bd ready` to start.\n   ```\n\n## Notes\n\n- Original plan file is preserved for reference\n- Task descriptions use first paragraph only (keeps them scannable)\n- Sequential phases get automatic dependencies\n","plugins/beads/agents/task-agent.md":"---\ndescription: Autonomous agent that finds and completes ready tasks\n---\n\nYou are a task-completion agent for beads. Your goal is to find ready work and complete it autonomously.\n\n# Agent Workflow\n\n1. **Find Ready Work**\n   - Use the `ready` MCP tool to get unblocked tasks\n   - Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)\n   - If no ready tasks, report completion\n\n2. **Claim the Task**\n   - Use the `show` tool to get full task details\n   - Use the `claim` tool for atomic start-work semantics\n   - Report what you're working on\n\n3. **Execute the Task**\n   - Read the task description carefully\n   - Use available tools to complete the work\n   - Follow best practices from project documentation\n   - Run tests if applicable\n\n4. **Track Discoveries**\n   - If you find bugs, TODOs, or related work:\n     - Use `create` tool to file new issues\n     - Use `dep` tool with `discovered-from` to link them\n   - This maintains context for future work\n\n5. **Complete the Task**\n   - Verify the work is done correctly\n   - Use `close` tool with a clear completion message\n   - Report what was accomplished\n\n6. **Continue**\n   - Check for newly unblocked work with `ready`\n   - Repeat the cycle\n\n# Important Guidelines\n\n- Always claim before working (MCP: `claim`; CLI: `--claim`) and close when done\n- Link discovered work with `discovered-from` dependencies\n- Don't close issues unless work is actually complete\n- If blocked, use `update` to set status to `blocked` and explain why\n- Communicate clearly about progress and blockers\n\n# Available Tools\n\nVia beads MCP server:\n- `ready` - Find unblocked tasks\n- `show` - Get task details\n- `claim` - Atomically claim task for work\n- `update` - Update task status/fields\n- `create` - Create new issues\n- `dep` - Manage dependencies\n- `close` - Complete tasks\n- `blocked` - Check blocked issues\n- `stats` - View project stats\n\nYou are autonomous but should communicate your progress clearly. Start by finding ready work!\n","plugins/beads/.copilot-plugin/plugin.json":"{\n  \"name\": \"beads\",\n  \"description\": \"AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.\",\n  \"version\": \"1.3.0\",\n  \"author\": {\n    \"name\": \"Steve Yegge\",\n    \"url\": \"https://github.com/steveyegge\"\n  },\n  \"repository\": \"https://github.com/gastownhall/beads\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://github.com/gastownhall/beads\",\n  \"keywords\": [\n    \"issue-tracker\",\n    \"task-management\",\n    \"ai-workflow\",\n    \"agent-memory\"\n  ],\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bd prime\"\n          }\n        ]\n      }\n    ],\n    \"PreCompact\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bd prime\"\n          }\n        ]\n      }\n    ]\n  }\n}\n","CLAUDE.md":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","engdocs/CLAUDE.md":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","plugins/beads/.codex-plugin/plugin.json":"# codex-plugin Plugin Manifest\n\nPath: `plugins/beads/.codex-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/plugin.json)","plugins/beads/.claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `plugins/beads/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.claude-plugin/plugin.json)",".claude/skills/beads-docs/references/simplification.md":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/simplification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/simplification.md)",".claude/skills/beads-docs/references/terminology.md":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/terminology.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/terminology.md)",".claude/skills/beads-docs/references/verification.md":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/verification.md)","internal/templates/agents/defaults/beads-section.md":"# Subagent: beads-section\n\nPath: `internal/templates/agents/defaults/beads-section.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section.md)","internal/templates/agents/defaults/beads-section-codex.md":"# Subagent: beads-section-codex\n\nPath: `internal/templates/agents/defaults/beads-section-codex.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-codex.md)","internal/templates/agents/defaults/beads-section-minimal.md":"# Subagent: beads-section-minimal\n\nPath: `internal/templates/agents/defaults/beads-section-minimal.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-minimal.md)","plugins/beads/.codex-plugin/hooks/hooks.json":"# Hooks Skill\n\nPath: `plugins/beads/.codex-plugin/hooks/hooks.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/hooks/hooks.json)","plugins/beads/skills/beads/CLAUDE.md":"# Beads Skill\n\nPath: `plugins/beads/skills/beads/CLAUDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/CLAUDE.md)","plugins/beads/skills/beads/README.md":"# beads Documentation\n\nPath: `plugins/beads/skills/beads/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/README.md)","internal/templates/skills/beads/agents/openai.yaml":"# Agents Skill\n\nPath: `internal/templates/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/skills/beads/agents/openai.yaml)","plugins/beads/skills/beads/agents/openai.yaml":"# Agents Skill\n\nPath: `plugins/beads/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/agents/openai.yaml)","plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md":"# Adr Skill\n\nPath: `plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md)","plugins/beads/skills/beads/commands/audit.md":"# Command: /audit\n\nPath: `plugins/beads/skills/beads/commands/audit.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/audit.md)","plugins/beads/skills/beads/commands/blocked.md":"# Command: /blocked\n\nPath: `plugins/beads/skills/beads/commands/blocked.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/blocked.md)","plugins/beads/skills/beads/commands/close.md":"# Command: /close\n\nPath: `plugins/beads/skills/beads/commands/close.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/close.md)","plugins/beads/skills/beads/commands/comments.md":"# Command: /comments\n\nPath: `plugins/beads/skills/beads/commands/comments.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/comments.md)","plugins/beads/skills/beads/commands/compact.md":"# Command: /compact\n\nPath: `plugins/beads/skills/beads/commands/compact.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/compact.md)","plugins/beads/skills/beads/commands/create.md":"# Command: /create\n\nPath: `plugins/beads/skills/beads/commands/create.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/create.md)","plugins/beads/skills/beads/commands/decision.md":"# Command: /decision\n\nPath: `plugins/beads/skills/beads/commands/decision.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/decision.md)","plugins/beads/skills/beads/commands/delete.md":"# Command: /delete\n\nPath: `plugins/beads/skills/beads/commands/delete.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/delete.md)","plugins/beads/skills/beads/commands/dep.md":"# Command: /dep\n\nPath: `plugins/beads/skills/beads/commands/dep.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/dep.md)","plugins/beads/skills/beads/commands/epic.md":"# Command: /epic\n\nPath: `plugins/beads/skills/beads/commands/epic.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/epic.md)","plugins/beads/skills/beads/commands/export.md":"# Command: /export\n\nPath: `plugins/beads/skills/beads/commands/export.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/export.md)","plugins/beads/skills/beads/commands/import.md":"# Command: /import\n\nPath: `plugins/beads/skills/beads/commands/import.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/import.md)","plugins/beads/skills/beads/commands/init.md":"# Command: /init\n\nPath: `plugins/beads/skills/beads/commands/init.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/init.md)","plugins/beads/skills/beads/commands/label.md":"# Command: /label\n\nPath: `plugins/beads/skills/beads/commands/label.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/label.md)","plugins/beads/skills/beads/commands/list.md":"# Command: /list\n\nPath: `plugins/beads/skills/beads/commands/list.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/list.md)","plugins/beads/skills/beads/commands/prime.md":"# Command: /prime\n\nPath: `plugins/beads/skills/beads/commands/prime.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/prime.md)","plugins/beads/skills/beads/commands/quickstart.md":"# Command: /quickstart\n\nPath: `plugins/beads/skills/beads/commands/quickstart.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/quickstart.md)","plugins/beads/skills/beads/commands/ready.md":"# Command: /ready\n\nPath: `plugins/beads/skills/beads/commands/ready.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/ready.md)","plugins/beads/skills/beads/commands/rename-prefix.md":"# Command: /rename-prefix\n\nPath: `plugins/beads/skills/beads/commands/rename-prefix.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/rename-prefix.md)","plugins/beads/skills/beads/commands/reopen.md":"# Command: /reopen\n\nPath: `plugins/beads/skills/beads/commands/reopen.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/reopen.md)","plugins/beads/skills/beads/commands/restore.md":"# Command: /restore\n\nPath: `plugins/beads/skills/beads/commands/restore.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/restore.md)","plugins/beads/skills/beads/commands/search.md":"# Command: /search\n\nPath: `plugins/beads/skills/beads/commands/search.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/search.md)","plugins/beads/skills/beads/commands/show.md":"# Command: /show\n\nPath: `plugins/beads/skills/beads/commands/show.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/show.md)","plugins/beads/skills/beads/commands/stats.md":"# Command: /stats\n\nPath: `plugins/beads/skills/beads/commands/stats.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/stats.md)","plugins/beads/skills/beads/commands/sync.md":"# Command: /sync\n\nPath: `plugins/beads/skills/beads/commands/sync.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/sync.md)","plugins/beads/skills/beads/commands/template.md":"# Command: /template\n\nPath: `plugins/beads/skills/beads/commands/template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/template.md)","plugins/beads/skills/beads/commands/update.md":"# Command: /update\n\nPath: `plugins/beads/skills/beads/commands/update.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/update.md)","plugins/beads/skills/beads/commands/version.md":"# Command: /version\n\nPath: `plugins/beads/skills/beads/commands/version.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/version.md)","plugins/beads/skills/beads/commands/workflow.md":"# Command: /workflow\n\nPath: `plugins/beads/skills/beads/commands/workflow.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/workflow.md)","plugins/beads/skills/beads/resources/AGENTS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/AGENTS.md)","plugins/beads/skills/beads/resources/ASYNC_GATES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ASYNC_GATES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ASYNC_GATES.md)","plugins/beads/skills/beads/resources/BOUNDARIES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/BOUNDARIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/BOUNDARIES.md)","plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md)","plugins/beads/skills/beads/resources/CLI_REFERENCE.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CLI_REFERENCE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CLI_REFERENCE.md)","plugins/beads/skills/beads/resources/DEPENDENCIES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/DEPENDENCIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/DEPENDENCIES.md)","plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md)","plugins/beads/skills/beads/resources/ISSUE_CREATION.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ISSUE_CREATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ISSUE_CREATION.md)","plugins/beads/skills/beads/resources/MOLECULES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/MOLECULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/MOLECULES.md)","plugins/beads/skills/beads/resources/PATTERNS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/PATTERNS.md)","plugins/beads/skills/beads/resources/RESUMABILITY.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/RESUMABILITY.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/RESUMABILITY.md)","plugins/beads/skills/beads/resources/STATIC_DATA.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/STATIC_DATA.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/STATIC_DATA.md)","plugins/beads/skills/beads/resources/TROUBLESHOOTING.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/TROUBLESHOOTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md)","plugins/beads/skills/beads/resources/WORKFLOWS.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKFLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKFLOWS.md)","plugins/beads/skills/beads/resources/WORKTREES.md":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKTREES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKTREES.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","isInternal":false,"tokens":3286,"sizeBytes":12284},{"name":"simplification.md","path":".claude/skills/beads-docs/references/simplification.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/simplification.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/simplification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/simplification.md)","tokens":300,"sizeBytes":225},{"name":"terminology.md","path":".claude/skills/beads-docs/references/terminology.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/terminology.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/terminology.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/terminology.md)","tokens":300,"sizeBytes":219},{"name":"verification.md","path":".claude/skills/beads-docs/references/verification.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/verification.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.claude/skills/beads-docs/references/verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/verification.md)","tokens":300,"sizeBytes":221},{"name":"SKILL.md","path":".claude/skills/beads-docs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/SKILL.md","title":"beads-docs","category":"anthropic-skill","format":"markdown","content":"---\nname: beads-docs\ndescription: >-\n  Project conventions for writing, editing, restructuring, or reviewing the\n  beads user documentation — the Mintlify site under docs/. Use this whenever\n  you touch anything in docs/ (pages, concept docs, reference, integration\n  guides, recovery runbooks, diagrams, docs.json navigation) or write/edit\n  prose about beads, even when the request is just \"fix the docs\", \"write a\n  docs page\", \"the docs are wrong/confusing\", \"rename X across the docs\", or\n  an edit to a file under docs/. It defines the canonical concept model\n  (bead → dependencies → ready work; formula → proto → molecule/wisp; gates;\n  Dolt sync and federation), required terminology, the prose/emphasis/diagram\n  conventions, the rule that generated docs are edited at their source, and\n  the gates to run before docs work is done.\n---\n\n# Writing beads docs\n\nThis is the house style for `docs/` — the beads user documentation, published\nas a Mintlify site. The goal is docs that motivate before they jargon, say the\nsame thing the same way everywhere, show concepts as pictures and snippets\ninstead of walls of prose, and never drift from the code. Apply it to any page\nyou create, edit, or review.\n\nThe audience of `docs/` is a **user** of beads — a human or agent installing\n`bd`, tracking work, and syncing it. Contributor-facing material lives in\n`engdocs/` and `AGENTS.md` and follows different rules (it may describe the\nimplementation literally). When this skill says \"the docs,\" it means `docs/`.\n\n## 1. The canonical model\n\nBeads is a dependency-aware issue graph with a workflow layer on top. Teach it\nconsistently and link to the canonical concept page —\n**`docs/core-concepts/index.md`** — rather than re-explaining it.\n\n| Concept | Role | Key idea |\n|---|---|---|\n| **bead** (issue) | the unit of work | one tracked item with a hash ID (`bd-a1b2`), type, status, priority; \"bead\" and \"issue\" name the same thing |\n| **dependency** | ordering | `blocks` edges hide a bead from agents until its blockers close; `parent-child`, `related`, `discovered-from` organize without blocking |\n| **ready work** | what `bd ready` computes | open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier |\n| **formula** | workflow source | a TOML/JSON file defining a DAG of steps; `bd cook` compiles it into a proto |\n| **proto** | workflow template | a template epic (label `template`) with `{{variables}}`; not live work |\n| **molecule** | instantiated workflow | real beads poured from a proto (`bd mol pour`); persistent |\n| **wisp** | ephemeral molecule | same instantiation, transient lifecycle (`bd mol wisp`); purged by `bd purge` |\n| **gate** | async wait | blocks a workflow step until closed — by a human, a timer, a GitHub run/PR, or a cross-rig bead |\n| **sync** | cross-machine movement | Dolt push/pull over `refs/dolt/data` on the git remote; `.beads/issues.jsonl` is a passive export, never the database |\n| **federation** | cross-repo sync | peer-to-peer sharing of beads across repos/organizations |\n\nThe pipeline worth internalizing: **formula → (cook) → proto → (pour) →\nmolecule** or **→ (wisp) → wisp**. Gates pause molecule steps; `bd ready`\nsurfaces the claimable steps; sync moves the whole graph between machines.\n\nStorage facts that pages keep getting wrong: embedded mode (the default\n`bd init`) stores data at `.beads/embeddeddolt/`; server mode\n(`bd init --server`) uses `.beads/dolt/`. Never present `.beads/dolt/` as the\ngeneral data path.\n\n**Cross-project vocabulary (beads ↔ Gas City).** Gas City (the sibling\nproject) shares the words molecule, formula, wisp, and gate, but the two doc\ncorpora use them differently: Gas City's docs treat molecule/wisp as v1\nimplementation detail (never a user concept), and a Gas City formula is an\norchestration method the orchestrator runs across agents. In beads,\nmolecule/wisp/proto ARE user concepts, and a formula is the TOML source you\ncook into a proto. Never import Gas City's definitions into beads pages (or\nvice versa); when a page must bridge the two projects, say explicitly which\nproject's sense is meant.\n\n## 2. Required terminology\n\nUse the left column; never the right (except as noted). The full\nprose-vs-literal rename discipline is in\n[references/terminology.md](references/terminology.md).\n\n| Use this | Not this | Notes |\n|---|---|---|\n| **bead** / **issue** | \"task\", \"ticket\", \"TODO item\" as the unit's name | Both terms are correct and interchangeable; lead with *bead* when teaching identity, use *issue* when mirroring CLI output or flags (`bd create`, \"issue types\"). \"task\" is one issue *type*, never the generic unit. |\n| **ready work** | \"unblocked queue\", \"available tasks\", \"the ready set\" as a formal term | Say what `bd ready` returns: open beads with no open blockers. |\n| **proto** | \"template\" as a noun for the concept | `template` stays only as the literal label name protos carry. |\n| **molecule** | \"mol\" in prose | `mol` is the command literal (`bd mol pour`); the concept is a molecule. |\n| **formula** | conflating formula with molecule/proto | The formula is the *file*; cooking makes a proto; pouring makes live work. |\n| **gate** | \"barrier\", \"checkpoint\", \"lock\" | Gates are async wait conditions with types (human, timer, gh:run, gh:pr, bead). |\n| **sync** = Dolt push/pull | export/import as a sync workflow | `bd dolt push` / `bd dolt pull` over `refs/dolt/data`. `.beads/issues.jsonl` is a passive export for viewers and interchange. |\n| **embedded mode** / **server mode** | \"local mode\", \"daemon mode\" for storage | Embedded is the default; data at `.beads/embeddeddolt/`. Server mode connects to `dolt sql-server`; data at `.beads/dolt/`. |\n| **federation** | \"multi-repo sync\" as a distinct feature name | Federation is the peer-to-peer cross-repo sharing feature. |\n| **hash ID** | \"random ID\", \"UUID\" | IDs like `bd-a1b2` are content-derived hashes sized adaptively to prevent collisions. |\n\n## 3. Content stance\n\n- **Motivate before you mechanize.** Lead a page with the problem it solves,\n  then the solution, then the mechanics. Never open on vocabulary.\n- **Docs are not the project's history.** No `internal/*` package paths, no\n  \"this was removed in vX\", no \"(v0.20.1+)\" gating on user pages — beads is a\n  1.x product and pre-1.0 archaeology belongs in `engdocs/` or the CHANGELOG.\n- **Lead with the value.** Beads' value is persistent, dependency-aware memory\n  for coding agents — agents that survive context loss because the work graph\n  outlives the session. The comparison framing (vs GitHub Issues, Jira,\n  markdown TODO lists) is the best newcomer conversion tool; keep it early\n  where it exists.\n- **One concrete example beats three abstract sentences.** Where you assert a\n  capability, show a `bd` invocation and what it prints.\n\n## 4. Information architecture\n\nNavigation lives in `docs/docs.json`: Getting Started, Core Concepts,\nArchitecture, Workflows, Recovery, Multi-Agent, Integrations, Community, and\nReference — with the generated CLI Reference nested inside Reference as a\ncollapsed sub-group.\n\n- **Every section has an index/Overview page** that introduces the section in\n  a sentence or two, then lists every child page with a one-line accurate\n  summary and link.\n- One page, one purpose. A page that tries to teach *and* specify does\n  neither — split it and cross-link.\n- Concept material is unified on `core-concepts/index`; don't re-derive the\n  model on other pages — link to it.\n- The repository map belongs in the README, not in `docs/`.\n\n## 5. Prose doctrine — cut words, sharpen points\n\nMost bloat is information stored in the wrong medium. Move it to a cheaper\ncarrier, then delete what isn't pulling weight. Every page must **stand\nalone** — a reader landing cold needs a one-line setup, not a previous page.\n\n**Convert** (move load off prose):\n- A relationship or sequence → a **diagram** (mermaid renders natively;\n  richer diagrams follow the Excalidraw pipeline — see §7).\n- Parallel options/fields/comparisons → a **table**.\n- \"you run X, which does Y\" narration → an **annotated CLI snippet** (show\n  the command and its output, comment the interesting lines).\n- Edge cases and deep mechanics → an `<Accordion>`, or a reference page.\n  Keep the 80% case on the page.\n\n**Delete** (the load was fake): throat-clearing openers (\"In this section\nwe'll…\"), hedge chains (\"generally / typically / in most cases\"),\nrestatement, narrating an artifact a snippet already shows, and adjectives\nstanding in for evidence.\n\nWhen you run a deliberate simplification pass, follow\n[references/simplification.md](references/simplification.md) — the per-page\nloop and the two guardrails that keep a trim honest: a **loss-check** (never\ndrop a fact that lives nowhere else) and a **fact-check** (trimmed prose must\nnot drift from the code).\n\n## 6. Emphasis and formatting\n\n- **Bold** *names a term*, on first mention only. *Italic* marks a property\n  or contrast. ~1–2 marks per paragraph; never re-emphasize a term already\n  introduced; never give one phrase both treatments.\n- No body `# H1` — the frontmatter `title` is the H1. Use `##`/`###`.\n- Links are root-relative and extensionless (`/getting-started/quickstart`).\n  Links out of the site (engdocs/, repo files) use full GitHub URLs.\n- Mintlify parses `.md` as MDX: no HTML comments (`{/* … */}` instead), and\n  angle-bracket placeholders like `<id>` must stay inside backticks or code\n  fences.\n- Mintlify components (`<Note>`, `<Tip>`, `<Warning>`, `<Accordion>`)\n  sparingly — they lose force with repetition.\n\n## 7. Diagrams\n\nMermaid fences render natively — prefer them for graphs and flows. For richer\ndiagrams use the Excalidraw pipeline: author the `.excalidraw` source under\n`docs/diagrams/excalidraw/`, render with `make diagrams-excalidraw` (source\nand rendered `.svg` are both committed), embed as\n`/diagrams/excalidraw-rendered/<name>.svg` with descriptive alt text, and\nkeep labels short (a two-line \"Name / role\" beats a sentence crammed in a\nbox). Two non-negotiables:\n\n- **Rasterize and look at every rendered diagram** — text overflow and layout\n  problems are invisible in a text diff.\n- **Diagrams and images cannot be reviewed in a diff.** Render them and get\n  the maintainer's approval before committing.\n\n## 8. Generated content is edited at its source\n\nNever hand-edit a generated file. The generated surfaces are:\n\n- `docs/cli-reference/*.md` and the CLI Reference pages array inside\n  `docs/docs.json` — bd emits vendor-neutral pages (`bd help --docs-root`,\n  from the Cobra command strings in `cmd/bd/*.go`) into an uncommitted\n  staging tree, and `tools/docsmint` post-processes them into the committed\n  Mintlify form. bd itself never emits Mintlify (or any site-generator)\n  specifics; that lives in docsmint.\n- `docs/CLI_REFERENCE.md` — the single-file reference, emitted directly by\n  `bd help --docs-root`.\n\nTo change wording in any of them, edit the Go source (`Short:`, `Long:`,\n`Example:` strings) and run `./scripts/generate-cli-docs.sh` (which runs both\nstages). To change the Mintlify page form itself (comment markers, link\nstyle, nav), edit `tools/docsmint` and its tests. The drift gates\n(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,\nand the docs-autofix bot) fail or auto-fix any hand edit.\n\n**The docs describe the pinned release, not main.** `docs/cli-docs.pin`\nnames the release tag the whole docs corpus targets; the pipeline builds bd\nfrom that tag and validates against it, so a Go-source edit on main shows up\nin the committed docs only after the pin is bumped (at release time,\nfollowed by a regeneration). Hand-written pages follow the same policy:\ndocument what the pinned release does, never main-only features. See\n`engdocs/decisions/2026-07-17-docs-release-pin.md`.\n\n## 9. Verify before you call it done\n\nRun the gates in [references/verification.md](references/verification.md).\nThe short list: `bazel test //test/docsync:docsync_test --config=ci`\n(nav↔file sync + link conventions),\n`./scripts/generate-cli-docs.sh --check` (generated docs fresh),\n`./scripts/check-doc-freshness.sh` (Last reviewed markers), and a live\npreview with `make docs-dev` (or `./mint.sh dev`) at `localhost:3000`.\n\nWhen you **move or remove a page**: add a redirect to the `redirects` array\nin `docs/docs.json`, rewrite inbound links repo-wide (README, engdocs/,\nexamples/, npm-package/, plugin resources — grep, don't guess), and check\nwhether `bd` prints the old path (if so, fix the Go source and regenerate —\nnever a pointer stub; decision 6 covers old routes with redirects).\n\n## 10. Review and commit discipline\n\n- **Author → the maintainer reviews → commit on explicit approval.** This\n  matters most for diagrams and images, which can't be reviewed in a text\n  diff.\n- Group commits by audience: user docs (`docs/`) separate from contributor\n  docs (`engdocs/`, `AGENTS.md`) separate from generator/Go changes.\n- Track docs work as bd issues per `AGENTS.md`.\n","frontmatter":{"name":"beads-docs","description":"Project conventions for writing, editing, restructuring, or reviewing the beads user documentation — the Mintlify site under docs/. Use this whenever you touch anything in docs/ (pages, concept docs, reference, integration guides, recovery runbooks, diagrams, docs.json navigation) or write/edit prose about beads, even when the request is just \"fix the docs\", \"write a docs page\", \"the docs are wrong/confusing\", \"rename X across the docs\", or an edit to a file under docs/. It defines the canonical concept model (bead → dependencies → ready work; formula → proto → molecule/wisp; gates; Dolt sync and federation), required terminology, the prose/emphasis/diagram conventions, the rule that generated docs are edited at their source, and the gates to run before docs work is done."},"isInternal":false,"tokens":3274,"sizeBytes":13102},{"name":"openai.yaml","path":"internal/templates/skills/beads/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/skills/beads/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `internal/templates/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/skills/beads/agents/openai.yaml)","tokens":300,"sizeBytes":213},{"name":"SKILL.md","path":"internal/templates/skills/beads/SKILL.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/skills/beads/SKILL.md","title":"beads","category":"anthropic-skill","format":"markdown","content":"---\nname: beads\ndescription: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.\n---\n\n# Beads\n\nUse Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.\n\n## First Step\n\nRun:\n\n```bash\nbd prime\n```\n\nIf that prints nothing, check whether the repository has an active Beads workspace:\n\n```bash\nbd where\n```\n\n## Preferred Route\n\nUse the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.\n\n## Core CLI Workflow\n\n1. Find work:\n\n```bash\nbd ready\nbd list --status=open\nbd list --status=in_progress\n```\n\n2. Inspect before editing:\n\n```bash\nbd show <id>\n```\n\n3. Claim work atomically:\n\n```bash\nbd update <id> --claim\n```\n\n4. Create durable follow-up work when implementation reveals new tasks:\n\n```bash\nbd create \"Short title\" --description=\"Why this exists and what needs to be done\" --type=task --priority=2\n```\n\n5. Close completed work:\n\n```bash\nbd close <id> --reason=\"Completed\"\n```\n\n## What Belongs In Beads\n\nUse Beads for:\n\n- shared project tasks\n- blockers and dependencies\n- discovered follow-up work\n- work that must survive thread reset, compaction, or handoff\n- status that another person or agent should be able to resume\n\nUse agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.\n\n## Rules\n\n- Do not create markdown TODO files as the source of truth when Beads is available.\n- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.\n- Prefer `--json` when parsing `bd` output programmatically.\n- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.\n- Do not auto-close or mutate tasks unless the work is actually complete.\n","frontmatter":{"name":"beads","description":"Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking."},"isInternal":false,"tokens":494,"sizeBytes":2146},{"name":"hooks.json","path":"plugins/beads/.codex-plugin/hooks/hooks.json","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/hooks/hooks.json","title":"Hooks Skill","category":"anthropic-skill","format":"json","content":"# Hooks Skill\n\nPath: `plugins/beads/.codex-plugin/hooks/hooks.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/hooks/hooks.json)","tokens":300,"sizeBytes":200},{"name":"0001-bd-prime-as-source-of-truth.md","path":"plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md","title":"Adr Skill","category":"anthropic-skill","format":"markdown","content":"# Adr Skill\n\nPath: `plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md)","tokens":300,"sizeBytes":242},{"name":"openai.yaml","path":"plugins/beads/skills/beads/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `plugins/beads/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/agents/openai.yaml)","tokens":300,"sizeBytes":203},{"name":"CLAUDE.md","path":"plugins/beads/skills/beads/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/CLAUDE.md","title":"Beads Skill","category":"anthropic-skill","format":"markdown","content":"# Beads Skill\n\nPath: `plugins/beads/skills/beads/CLAUDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/CLAUDE.md)","tokens":300,"sizeBytes":184},{"name":"AGENTS.md","path":"plugins/beads/skills/beads/resources/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/AGENTS.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/AGENTS.md)","tokens":300,"sizeBytes":208},{"name":"ASYNC_GATES.md","path":"plugins/beads/skills/beads/resources/ASYNC_GATES.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ASYNC_GATES.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ASYNC_GATES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ASYNC_GATES.md)","tokens":300,"sizeBytes":218},{"name":"BOUNDARIES.md","path":"plugins/beads/skills/beads/resources/BOUNDARIES.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/BOUNDARIES.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/BOUNDARIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/BOUNDARIES.md)","tokens":300,"sizeBytes":216},{"name":"CHEMISTRY_PATTERNS.md","path":"plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md)","tokens":300,"sizeBytes":232},{"name":"CLI_REFERENCE.md","path":"plugins/beads/skills/beads/resources/CLI_REFERENCE.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CLI_REFERENCE.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CLI_REFERENCE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CLI_REFERENCE.md)","tokens":300,"sizeBytes":222},{"name":"DEPENDENCIES.md","path":"plugins/beads/skills/beads/resources/DEPENDENCIES.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/DEPENDENCIES.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/DEPENDENCIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/DEPENDENCIES.md)","tokens":300,"sizeBytes":220},{"name":"INTEGRATION_PATTERNS.md","path":"plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md)","tokens":300,"sizeBytes":236},{"name":"ISSUE_CREATION.md","path":"plugins/beads/skills/beads/resources/ISSUE_CREATION.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ISSUE_CREATION.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ISSUE_CREATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ISSUE_CREATION.md)","tokens":300,"sizeBytes":224},{"name":"MOLECULES.md","path":"plugins/beads/skills/beads/resources/MOLECULES.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/MOLECULES.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/MOLECULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/MOLECULES.md)","tokens":300,"sizeBytes":214},{"name":"PATTERNS.md","path":"plugins/beads/skills/beads/resources/PATTERNS.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/PATTERNS.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/PATTERNS.md)","tokens":300,"sizeBytes":212},{"name":"RESUMABILITY.md","path":"plugins/beads/skills/beads/resources/RESUMABILITY.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/RESUMABILITY.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/RESUMABILITY.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/RESUMABILITY.md)","tokens":300,"sizeBytes":220},{"name":"STATIC_DATA.md","path":"plugins/beads/skills/beads/resources/STATIC_DATA.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/STATIC_DATA.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/STATIC_DATA.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/STATIC_DATA.md)","tokens":300,"sizeBytes":218},{"name":"TROUBLESHOOTING.md","path":"plugins/beads/skills/beads/resources/TROUBLESHOOTING.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/TROUBLESHOOTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md)","tokens":300,"sizeBytes":226},{"name":"WORKFLOWS.md","path":"plugins/beads/skills/beads/resources/WORKFLOWS.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKFLOWS.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKFLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKFLOWS.md)","tokens":300,"sizeBytes":214},{"name":"WORKTREES.md","path":"plugins/beads/skills/beads/resources/WORKTREES.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKTREES.md","title":"Resources Skill","category":"anthropic-skill","format":"markdown","content":"# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKTREES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKTREES.md)","tokens":300,"sizeBytes":214},{"name":"SKILL.md","path":"plugins/beads/skills/beads/SKILL.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/SKILL.md","title":"beads","category":"anthropic-skill","format":"markdown","content":"---\nname: beads\ndescription: >\n  Dolt-powered issue tracker for multi-session work with dependencies and persistent\n  memory across conversation compaction. Use when work spans sessions, has blockers,\n  or needs context recovery after compaction. Trigger with \"create task\", \"what's\n  ready\", \"track this work\", \"resume after compaction\". Make sure to use this skill\n  whenever managing multi-session work, tracking dependencies, or recovering context.\nallowed-tools: \"Read,Bash(bd:*)\"\nversion: \"0.60.0\"\nauthor: \"Steve Yegge <steve.yegge@gmail.com>\"\nlicense: \"MIT\"\ncompatible-with: [claude-code, codex]\ntags: [issue-tracking, task-management, multi-session, dependencies]\n---\n\n# Beads - Persistent Task Memory for AI Agents\n\nGraph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.\n\n## bd vs TodoWrite\n\n**Decision test**: \"Will I need this context in 2 weeks?\" YES = bd, NO = TodoWrite.\n\n| bd (persistent) | TodoWrite (ephemeral) |\n|-----------------|----------------------|\n| Multi-session, dependencies, compaction survival | Single-session linear tasks |\n| Dolt-backed team sync | Conversation-scoped |\n\nSee [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.\n\n## Prerequisites\n\n```bash\nbd --version  # Requires v0.60.0+\n```\n\n- **bd CLI** installed and in PATH\n- **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)\n- **Initialization**: `bd init` run once (humans do this, not agents)\n\n## CLI Reference\n\n**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).\n**Run `bd <command> --help`** for specific command usage.\n\nEssential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd dolt push`\n\n## Session Protocol\n\n1. `bd ready` — Find unblocked work\n2. `bd show <id>` — Get full context\n3. `bd update <id> --claim` — Claim and start work atomically\n4. Add notes as you work (critical for compaction survival)\n5. `bd close <id> --reason \"...\"` — Complete task\n6. `bd dolt push` — Push to Dolt remote (if configured)\n\n## Output\n\nAppend `--json` to any command for structured output. Use `bd show <id> --long` for extended metadata. Status icons: `○` open `◐` in_progress `●` blocked `✓` closed `❄` deferred.\n\n## Error Handling\n\n| Error | Fix |\n|-------|-----|\n| `database not found` | `bd init <prefix>` in project root |\n| `not in a git repository` | `git init` first |\n| `disk I/O error (522)` | Move `.beads/` off cloud-synced filesystem |\n| Status updates lag | Use server mode: `bd dolt start` |\n\nSee [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.\n\n## Examples\n\n**Track a multi-session feature:**\n```bash\nbd create \"OAuth integration\" -t epic -p 1 --json\nbd create \"Token storage\" -t task --deps blocks:oauth-id --json\nbd ready --json                    # Shows unblocked work\nbd update <id> --claim --json      # Claim and start\nbd close <id> --reason \"Implemented with refresh tokens\" --json\n```\n\n**Recover after compaction:** `bd list --status in_progress --json` then `bd show <id> --long`\n\n**Discover work mid-task:** `bd create \"Found bug\" -t bug -p 1 --deps discovered-from:<current-id> --json`\n\n## Advanced Features\n\n| Feature | CLI | Resource |\n|---------|-----|----------|\n| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |\n| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |\n| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |\n| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |\n| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |\n\n## Resources\n\n| Category | Files |\n|----------|-------|\n| **Getting Started** | [BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) (live reference pointers), [WORKFLOWS.md](resources/WORKFLOWS.md) |\n| **Core Concepts** | [DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md) |\n| **Resilience** | [RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) |\n| **Advanced** | [MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md) |\n| **Reference** | [STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) |\n\n## Validation\n\nIf `bd --version` reports newer than `0.60.0`, this skill may be stale. Run `bd prime` for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).\n","frontmatter":{"name":"beads","description":"Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with \"create task\", \"what's ready\", \"track this work\", \"resume after compaction\". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context.\n","allowed-tools":"Read,Bash(bd:*)","version":"0.60.0","author":"Steve Yegge <steve.yegge@gmail.com>","license":"MIT","compatible-with":["claude-code","codex"],"tags":["issue-tracking","task-management","multi-session","dependencies"],"allowedTools":["Read,Bash(bd:*)"]},"allowedTools":["Read,Bash(bd:*)"],"isInternal":false,"tokens":1345,"sizeBytes":4864},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","isInternal":false,"tokens":3286,"sizeBytes":12284},{"name":"CLAUDE.md","path":"engdocs/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/engdocs/CLAUDE.md","title":"engdocs - Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n","isInternal":false,"tokens":3286,"sizeBytes":12284},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# GitHub Copilot instructions for beads\n\nThe canonical contributor instructions for this repository are in\n[AGENTS.md](../AGENTS.md); area-specific rules are in the nested `AGENTS.md`\nfiles listed in its routing table. Read those, not this file, for workflow,\nbuild, test, and scope rules.\n\nThe rules most often missed in review:\n\n- A PR must close a documented GitHub issue (filed before or alongside it).\n- Build with `make install`, never `go build -o bd ./cmd/bd` or `go install ./cmd/bd`.\n- `make ci-pr-lint` must pass with zero issues; choose tests with\n  [engdocs/TESTING.md](../engdocs/TESTING.md).\n- Never create test issues in a production database; use `t.TempDir()`.\n- CLI output uses small Unicode status symbols, never emoji icons.\n","isInternal":false,"tokens":183,"sizeBytes":746},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude-plugin/marketplace.json","title":"beads-marketplace","category":"marketplace","format":"json","content":"{\n  \"name\": \"beads-marketplace\",\n  \"description\": \"Local marketplace for beads plugin development\",\n  \"owner\": {\n    \"name\": \"Steve Yegge\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"beads\",\n      \"source\": \"./plugins/beads\",\n      \"description\": \"AI-supervised issue tracker for coding workflows\",\n      \"version\": \"1.3.0\"\n    }\n  ]\n}\n","frontmatter":{"name":"beads-marketplace","description":"Local marketplace for beads plugin development","owner":{"name":"Steve Yegge"},"plugins":[{"name":"beads","source":"./plugins/beads","description":"AI-supervised issue tracker for coding workflows","version":"1.3.0"}]},"isInternal":false,"tokens":94,"sizeBytes":333},{"name":"plugin.json","path":"plugins/beads/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `plugins/beads/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":210},{"name":"plugin.json","path":"plugins/beads/.codex-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/plugin.json","title":"codex-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# codex-plugin Plugin Manifest\n\nPath: `plugins/beads/.codex-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/plugin.json)","tokens":300,"sizeBytes":207},{"name":"plugin.json","path":"plugins/beads/.copilot-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.copilot-plugin/plugin.json","title":"beads","category":"plugin-manifest","format":"json","content":"{\n  \"name\": \"beads\",\n  \"description\": \"AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.\",\n  \"version\": \"1.3.0\",\n  \"author\": {\n    \"name\": \"Steve Yegge\",\n    \"url\": \"https://github.com/steveyegge\"\n  },\n  \"repository\": \"https://github.com/gastownhall/beads\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://github.com/gastownhall/beads\",\n  \"keywords\": [\n    \"issue-tracker\",\n    \"task-management\",\n    \"ai-workflow\",\n    \"agent-memory\"\n  ],\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bd prime\"\n          }\n        ]\n      }\n    ],\n    \"PreCompact\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bd prime\"\n          }\n        ]\n      }\n    ]\n  }\n}\n","frontmatter":{"name":"beads","description":"AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.","version":"1.3.0","author":{"name":"Steve Yegge","url":"https://github.com/steveyegge"},"repository":"https://github.com/gastownhall/beads","license":"MIT","homepage":"https://github.com/gastownhall/beads","keywords":["issue-tracker","task-management","ai-workflow","agent-memory"],"hooks":{"SessionStart":[{"matcher":"","hooks":[{"type":"command","command":"bd prime"}]}],"PreCompact":[{"matcher":"","hooks":[{"type":"command","command":"bd prime"}]}]}},"isInternal":false,"tokens":242,"sizeBytes":899},{"name":"README.md","path":"plugins/beads/README.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/README.md","title":"beads Documentation","category":"plugin-manifest","format":"markdown","content":"# Beads Plugin\n\nThis is the shared Claude/Codex plugin package for Beads. Claude and Codex use separate manifest files, but they share the same skill tree.\n\n## Layout\n\n- `.codex-plugin/plugin.json` describes the Codex plugin.\n- `.claude-plugin/plugin.json` describes the Claude plugin.\n- `skills/beads/` contains the plugin-owned Beads skill.\n- `.codex-plugin/hooks/hooks.json` contains Codex-only lifecycle hooks for startup and compaction-aware context refresh.\n- The Claude marketplace entry lives at `.claude-plugin/marketplace.json`.\n\n## Codex Hooks\n\nThe Codex plugin exposes native hooks through `.codex-plugin/plugin.json`, which points at `.codex-plugin/hooks/hooks.json`.\nWith Codex 0.129.0+, `/hooks` shows these lifecycle handlers:\n\n- `SessionStart` runs `bd codex-hook SessionStart` for `startup|resume|clear` and injects full `bd prime` output.\n- `PreCompact` runs `bd codex-hook PreCompact` for `manual|auto` and warns if `bd prime --memories-only` cannot run.\n- `PostCompact` runs `bd codex-hook PostCompact` for `manual|auto` and records a one-shot refresh marker in the user cache/temp directory.\n- `UserPromptSubmit` runs `bd codex-hook UserPromptSubmit` and, when a refresh marker exists, injects full `bd prime` output once before clearing it.\n\nIf the plugin is not installed, `bd setup codex` writes an equivalent `.codex/hooks.json` fallback and enables `[features].hooks = true`.\n\n## Local Development\n\nClaude Code uses `.claude-plugin/marketplace.json`, which points at this shared package root.\n","isInternal":false,"tokens":364,"sizeBytes":1520},{"name":"README.md","path":"plugins/beads/skills/beads/README.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/README.md","title":"beads Documentation","category":"plugin-manifest","format":"markdown","content":"# beads Documentation\n\nPath: `plugins/beads/skills/beads/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/README.md)","tokens":300,"sizeBytes":192},{"name":"plan-to-beads.md","path":"integrations/claude-code/commands/plan-to-beads.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/integrations/claude-code/commands/plan-to-beads.md","title":"Command: /plan-to-beads","category":"command-prompt","format":"markdown","content":"# Convert Plan to Beads Tasks\n\n## description:\nConvert a Claude Code plan file into beads epic + tasks for cross-session tracking.\n\n## Arguments\n$ARGUMENTS (optional - path to plan file, defaults to most recent in ~/.claude/plans/)\n\n---\n\nUse the **Task tool** with `subagent_type='general-purpose'` to convert the plan.\n\n## Agent Instructions\n\nThe agent should:\n\n1. **Find the plan file**\n   - If argument provided, use that path\n   - Otherwise: `ls -t ~/.claude/plans/*.md | head -1`\n\n2. **Parse the plan structure**\n   - Title: First `# Plan:` or `#` heading\n   - Description: Content under `## Summary`\n   - Tasks: Each `### Phase N:` or `### N.` section\n   - File list: Include in epic description\n\n3. **Create the epic**\n   ```bash\n   bd create \"[Plan Title]\" -t epic -p 1 -d \"[summary]. Files: N to modify.\" --json\n   ```\n\n4. **Create tasks from phases**\n   - Each phase becomes a task\n   - Use first paragraph of phase content as description\n   ```bash\n   bd create \"[Phase title]\" -t task -p 2 -d \"[description]\" --json\n   ```\n\n5. **Add sequential dependencies**\n   - Phases are sequential: `bd dep add <phase2> <phase1>`\n\n6. **Link tasks to epic**\n   - `bd dep add <epic> <task>` for each task\n\n7. **Return a concise summary** (not raw output):\n   ```\n   Created from: [filename]\n\n   Epic: [title] ([epic-id])\n     ├── [Phase 1] ([id]) - ready\n     ├── [Phase 2] ([id]) - blocked by [prev]\n     └── [Phase 3] ([id]) - blocked by [prev]\n\n   Total: [N] tasks\n   Run `bd ready` to start.\n   ```\n\n## Notes\n\n- Original plan file is preserved for reference\n- Task descriptions use first paragraph only (keeps them scannable)\n- Sequential phases get automatic dependencies\n","isInternal":false,"tokens":466,"sizeBytes":1693},{"name":"beads-section-codex.md","path":"internal/templates/agents/defaults/beads-section-codex.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-codex.md","title":"Subagent: beads-section-codex","category":"subagent-persona","format":"markdown","content":"# Subagent: beads-section-codex\n\nPath: `internal/templates/agents/defaults/beads-section-codex.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-codex.md)","tokens":300,"sizeBytes":244},{"name":"beads-section-minimal.md","path":"internal/templates/agents/defaults/beads-section-minimal.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-minimal.md","title":"Subagent: beads-section-minimal","category":"subagent-persona","format":"markdown","content":"# Subagent: beads-section-minimal\n\nPath: `internal/templates/agents/defaults/beads-section-minimal.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section-minimal.md)","tokens":300,"sizeBytes":250},{"name":"beads-section.md","path":"internal/templates/agents/defaults/beads-section.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section.md","title":"Subagent: beads-section","category":"subagent-persona","format":"markdown","content":"# Subagent: beads-section\n\nPath: `internal/templates/agents/defaults/beads-section.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/agents/defaults/beads-section.md)","tokens":300,"sizeBytes":226},{"name":"task-agent.md","path":"plugins/beads/agents/task-agent.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/agents/task-agent.md","title":"Subagent: task-agent","category":"subagent-persona","format":"markdown","content":"---\ndescription: Autonomous agent that finds and completes ready tasks\n---\n\nYou are a task-completion agent for beads. Your goal is to find ready work and complete it autonomously.\n\n# Agent Workflow\n\n1. **Find Ready Work**\n   - Use the `ready` MCP tool to get unblocked tasks\n   - Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)\n   - If no ready tasks, report completion\n\n2. **Claim the Task**\n   - Use the `show` tool to get full task details\n   - Use the `claim` tool for atomic start-work semantics\n   - Report what you're working on\n\n3. **Execute the Task**\n   - Read the task description carefully\n   - Use available tools to complete the work\n   - Follow best practices from project documentation\n   - Run tests if applicable\n\n4. **Track Discoveries**\n   - If you find bugs, TODOs, or related work:\n     - Use `create` tool to file new issues\n     - Use `dep` tool with `discovered-from` to link them\n   - This maintains context for future work\n\n5. **Complete the Task**\n   - Verify the work is done correctly\n   - Use `close` tool with a clear completion message\n   - Report what was accomplished\n\n6. **Continue**\n   - Check for newly unblocked work with `ready`\n   - Repeat the cycle\n\n# Important Guidelines\n\n- Always claim before working (MCP: `claim`; CLI: `--claim`) and close when done\n- Link discovered work with `discovered-from` dependencies\n- Don't close issues unless work is actually complete\n- If blocked, use `update` to set status to `blocked` and explain why\n- Communicate clearly about progress and blockers\n\n# Available Tools\n\nVia beads MCP server:\n- `ready` - Find unblocked tasks\n- `show` - Get task details\n- `claim` - Atomically claim task for work\n- `update` - Update task status/fields\n- `create` - Create new issues\n- `dep` - Manage dependencies\n- `close` - Complete tasks\n- `blocked` - Check blocked issues\n- `stats` - View project stats\n\nYou are autonomous but should communicate your progress clearly. Start by finding ready work!\n","frontmatter":{"description":"Autonomous agent that finds and completes ready tasks"},"isInternal":false,"tokens":485,"sizeBytes":1971},{"name":"audit.md","path":"plugins/beads/skills/beads/commands/audit.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/audit.md","title":"Command: /audit","category":"command-prompt","format":"markdown","content":"# Command: /audit\n\nPath: `plugins/beads/skills/beads/commands/audit.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/audit.md)","tokens":300,"sizeBytes":204},{"name":"blocked.md","path":"plugins/beads/skills/beads/commands/blocked.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/blocked.md","title":"Command: /blocked","category":"command-prompt","format":"markdown","content":"# Command: /blocked\n\nPath: `plugins/beads/skills/beads/commands/blocked.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/blocked.md)","tokens":300,"sizeBytes":210},{"name":"close.md","path":"plugins/beads/skills/beads/commands/close.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/close.md","title":"Command: /close","category":"command-prompt","format":"markdown","content":"# Command: /close\n\nPath: `plugins/beads/skills/beads/commands/close.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/close.md)","tokens":300,"sizeBytes":204},{"name":"comments.md","path":"plugins/beads/skills/beads/commands/comments.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/comments.md","title":"Command: /comments","category":"command-prompt","format":"markdown","content":"# Command: /comments\n\nPath: `plugins/beads/skills/beads/commands/comments.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/comments.md)","tokens":300,"sizeBytes":213},{"name":"compact.md","path":"plugins/beads/skills/beads/commands/compact.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/compact.md","title":"Command: /compact","category":"command-prompt","format":"markdown","content":"# Command: /compact\n\nPath: `plugins/beads/skills/beads/commands/compact.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/compact.md)","tokens":300,"sizeBytes":210},{"name":"create.md","path":"plugins/beads/skills/beads/commands/create.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/create.md","title":"Command: /create","category":"command-prompt","format":"markdown","content":"# Command: /create\n\nPath: `plugins/beads/skills/beads/commands/create.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/create.md)","tokens":300,"sizeBytes":207},{"name":"decision.md","path":"plugins/beads/skills/beads/commands/decision.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/decision.md","title":"Command: /decision","category":"command-prompt","format":"markdown","content":"# Command: /decision\n\nPath: `plugins/beads/skills/beads/commands/decision.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/decision.md)","tokens":300,"sizeBytes":213},{"name":"delete.md","path":"plugins/beads/skills/beads/commands/delete.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/delete.md","title":"Command: /delete","category":"command-prompt","format":"markdown","content":"# Command: /delete\n\nPath: `plugins/beads/skills/beads/commands/delete.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/delete.md)","tokens":300,"sizeBytes":207},{"name":"dep.md","path":"plugins/beads/skills/beads/commands/dep.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/dep.md","title":"Command: /dep","category":"command-prompt","format":"markdown","content":"# Command: /dep\n\nPath: `plugins/beads/skills/beads/commands/dep.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/dep.md)","tokens":300,"sizeBytes":198},{"name":"epic.md","path":"plugins/beads/skills/beads/commands/epic.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/epic.md","title":"Command: /epic","category":"command-prompt","format":"markdown","content":"# Command: /epic\n\nPath: `plugins/beads/skills/beads/commands/epic.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/epic.md)","tokens":300,"sizeBytes":201},{"name":"export.md","path":"plugins/beads/skills/beads/commands/export.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/export.md","title":"Command: /export","category":"command-prompt","format":"markdown","content":"# Command: /export\n\nPath: `plugins/beads/skills/beads/commands/export.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/export.md)","tokens":300,"sizeBytes":207},{"name":"import.md","path":"plugins/beads/skills/beads/commands/import.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/import.md","title":"Command: /import","category":"command-prompt","format":"markdown","content":"# Command: /import\n\nPath: `plugins/beads/skills/beads/commands/import.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/import.md)","tokens":300,"sizeBytes":207},{"name":"init.md","path":"plugins/beads/skills/beads/commands/init.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/init.md","title":"Command: /init","category":"command-prompt","format":"markdown","content":"# Command: /init\n\nPath: `plugins/beads/skills/beads/commands/init.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/init.md)","tokens":300,"sizeBytes":201},{"name":"label.md","path":"plugins/beads/skills/beads/commands/label.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/label.md","title":"Command: /label","category":"command-prompt","format":"markdown","content":"# Command: /label\n\nPath: `plugins/beads/skills/beads/commands/label.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/label.md)","tokens":300,"sizeBytes":204},{"name":"list.md","path":"plugins/beads/skills/beads/commands/list.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/list.md","title":"Command: /list","category":"command-prompt","format":"markdown","content":"# Command: /list\n\nPath: `plugins/beads/skills/beads/commands/list.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/list.md)","tokens":300,"sizeBytes":201},{"name":"prime.md","path":"plugins/beads/skills/beads/commands/prime.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/prime.md","title":"Command: /prime","category":"command-prompt","format":"markdown","content":"# Command: /prime\n\nPath: `plugins/beads/skills/beads/commands/prime.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/prime.md)","tokens":300,"sizeBytes":204},{"name":"quickstart.md","path":"plugins/beads/skills/beads/commands/quickstart.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/quickstart.md","title":"Command: /quickstart","category":"command-prompt","format":"markdown","content":"# Command: /quickstart\n\nPath: `plugins/beads/skills/beads/commands/quickstart.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/quickstart.md)","tokens":300,"sizeBytes":219},{"name":"ready.md","path":"plugins/beads/skills/beads/commands/ready.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/ready.md","title":"Command: /ready","category":"command-prompt","format":"markdown","content":"# Command: /ready\n\nPath: `plugins/beads/skills/beads/commands/ready.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/ready.md)","tokens":300,"sizeBytes":204},{"name":"rename-prefix.md","path":"plugins/beads/skills/beads/commands/rename-prefix.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/rename-prefix.md","title":"Command: /rename-prefix","category":"command-prompt","format":"markdown","content":"# Command: /rename-prefix\n\nPath: `plugins/beads/skills/beads/commands/rename-prefix.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/rename-prefix.md)","tokens":300,"sizeBytes":228},{"name":"reopen.md","path":"plugins/beads/skills/beads/commands/reopen.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/reopen.md","title":"Command: /reopen","category":"command-prompt","format":"markdown","content":"# Command: /reopen\n\nPath: `plugins/beads/skills/beads/commands/reopen.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/reopen.md)","tokens":300,"sizeBytes":207},{"name":"restore.md","path":"plugins/beads/skills/beads/commands/restore.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/restore.md","title":"Command: /restore","category":"command-prompt","format":"markdown","content":"# Command: /restore\n\nPath: `plugins/beads/skills/beads/commands/restore.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/restore.md)","tokens":300,"sizeBytes":210},{"name":"search.md","path":"plugins/beads/skills/beads/commands/search.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/search.md","title":"Command: /search","category":"command-prompt","format":"markdown","content":"# Command: /search\n\nPath: `plugins/beads/skills/beads/commands/search.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/search.md)","tokens":300,"sizeBytes":207},{"name":"show.md","path":"plugins/beads/skills/beads/commands/show.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/show.md","title":"Command: /show","category":"command-prompt","format":"markdown","content":"# Command: /show\n\nPath: `plugins/beads/skills/beads/commands/show.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/show.md)","tokens":300,"sizeBytes":201},{"name":"stats.md","path":"plugins/beads/skills/beads/commands/stats.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/stats.md","title":"Command: /stats","category":"command-prompt","format":"markdown","content":"# Command: /stats\n\nPath: `plugins/beads/skills/beads/commands/stats.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/stats.md)","tokens":300,"sizeBytes":204},{"name":"sync.md","path":"plugins/beads/skills/beads/commands/sync.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/sync.md","title":"Command: /sync","category":"command-prompt","format":"markdown","content":"# Command: /sync\n\nPath: `plugins/beads/skills/beads/commands/sync.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/sync.md)","tokens":300,"sizeBytes":201},{"name":"template.md","path":"plugins/beads/skills/beads/commands/template.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/template.md","title":"Command: /template","category":"command-prompt","format":"markdown","content":"# Command: /template\n\nPath: `plugins/beads/skills/beads/commands/template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/template.md)","tokens":300,"sizeBytes":213},{"name":"update.md","path":"plugins/beads/skills/beads/commands/update.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/update.md","title":"Command: /update","category":"command-prompt","format":"markdown","content":"# Command: /update\n\nPath: `plugins/beads/skills/beads/commands/update.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/update.md)","tokens":300,"sizeBytes":207},{"name":"version.md","path":"plugins/beads/skills/beads/commands/version.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/version.md","title":"Command: /version","category":"command-prompt","format":"markdown","content":"# Command: /version\n\nPath: `plugins/beads/skills/beads/commands/version.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/version.md)","tokens":300,"sizeBytes":210},{"name":"workflow.md","path":"plugins/beads/skills/beads/commands/workflow.md","rawUrl":"https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/workflow.md","title":"Command: /workflow","category":"command-prompt","format":"markdown","content":"# Command: /workflow\n\nPath: `plugins/beads/skills/beads/commands/workflow.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/commands/workflow.md)","tokens":300,"sizeBytes":213}],"systemPromptSnippet":"<yakaai_skills repo=\"gastownhall/beads\">\n<!-- File: AGENTS.md (Tokens: ~3286 | Category: root-instruction) -->\n# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n\n<!-- File: .claude/skills/beads-docs/references/simplification.md (Tokens: ~300 | Category: anthropic-skill) -->\n# References Skill\n\nPath: `.claude/skills/beads-docs/references/simplification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/simplification.md)\n\n<!-- File: .claude/skills/beads-docs/references/terminology.md (Tokens: ~300 | Category: anthropic-skill) -->\n# References Skill\n\nPath: `.claude/skills/beads-docs/references/terminology.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/terminology.md)\n\n<!-- File: .claude/skills/beads-docs/references/verification.md (Tokens: ~300 | Category: anthropic-skill) -->\n# References Skill\n\nPath: `.claude/skills/beads-docs/references/verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/.claude/skills/beads-docs/references/verification.md)\n\n<!-- File: .claude/skills/beads-docs/SKILL.md (Tokens: ~3274 | Category: anthropic-skill) -->\n---\nname: beads-docs\ndescription: >-\n  Project conventions for writing, editing, restructuring, or reviewing the\n  beads user documentation — the Mintlify site under docs/. Use this whenever\n  you touch anything in docs/ (pages, concept docs, reference, integration\n  guides, recovery runbooks, diagrams, docs.json navigation) or write/edit\n  prose about beads, even when the request is just \"fix the docs\", \"write a\n  docs page\", \"the docs are wrong/confusing\", \"rename X across the docs\", or\n  an edit to a file under docs/. It defines the canonical concept model\n  (bead → dependencies → ready work; formula → proto → molecule/wisp; gates;\n  Dolt sync and federation), required terminology, the prose/emphasis/diagram\n  conventions, the rule that generated docs are edited at their source, and\n  the gates to run before docs work is done.\n---\n\n# Writing beads docs\n\nThis is the house style for `docs/` — the beads user documentation, published\nas a Mintlify site. The goal is docs that motivate before they jargon, say the\nsame thing the same way everywhere, show concepts as pictures and snippets\ninstead of walls of prose, and never drift from the code. Apply it to any page\nyou create, edit, or review.\n\nThe audience of `docs/` is a **user** of beads — a human or agent installing\n`bd`, tracking work, and syncing it. Contributor-facing material lives in\n`engdocs/` and `AGENTS.md` and follows different rules (it may describe the\nimplementation literally). When this skill says \"the docs,\" it means `docs/`.\n\n## 1. The canonical model\n\nBeads is a dependency-aware issue graph with a workflow layer on top. Teach it\nconsistently and link to the canonical concept page —\n**`docs/core-concepts/index.md`** — rather than re-explaining it.\n\n| Concept | Role | Key idea |\n|---|---|---|\n| **bead** (issue) | the unit of work | one tracked item with a hash ID (`bd-a1b2`), type, status, priority; \"bead\" and \"issue\" name the same thing |\n| **dependency** | ordering | `blocks` edges hide a bead from agents until its blockers close; `parent-child`, `related`, `discovered-from` organize without blocking |\n| **ready work** | what `bd ready` computes | open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier |\n| **formula** | workflow source | a TOML/JSON file defining a DAG of steps; `bd cook` compiles it into a proto |\n| **proto** | workflow template | a template epic (label `template`) with `{{variables}}`; not live work |\n| **molecule** | instantiated workflow | real beads poured from a proto (`bd mol pour`); persistent |\n| **wisp** | ephemeral molecule | same instantiation, transient lifecycle (`bd mol wisp`); purged by `bd purge` |\n| **gate** | async wait | blocks a workflow step until closed — by a human, a timer, a GitHub run/PR, or a cross-rig bead |\n| **sync** | cross-machine movement | Dolt push/pull over `refs/dolt/data` on the git remote; `.beads/issues.jsonl` is a passive export, never the database |\n| **federation** | cross-repo sync | peer-to-peer sharing of beads across repos/organizations |\n\nThe pipeline worth internalizing: **formula → (cook) → proto → (pour) →\nmolecule** or **→ (wisp) → wisp**. Gates pause molecule steps; `bd ready`\nsurfaces the claimable steps; sync moves the whole graph between machines.\n\nStorage facts that pages keep getting wrong: embedded mode (the default\n`bd init`) stores data at `.beads/embeddeddolt/`; server mode\n(`bd init --server`) uses `.beads/dolt/`. Never present `.beads/dolt/` as the\ngeneral data path.\n\n**Cross-project vocabulary (beads ↔ Gas City).** Gas City (the sibling\nproject) shares the words molecule, formula, wisp, and gate, but the two doc\ncorpora use them differently: Gas City's docs treat molecule/wisp as v1\nimplementation detail (never a user concept), and a Gas City formula is an\norchestration method the orchestrator runs across agents. In beads,\nmolecule/wisp/proto ARE user concepts, and a formula is the TOML source you\ncook into a proto. Never import Gas City's definitions into beads pages (or\nvice versa); when a page must bridge the two projects, say explicitly which\nproject's sense is meant.\n\n## 2. Required terminology\n\nUse the left column; never the right (except as noted). The full\nprose-vs-literal rename discipline is in\n[references/terminology.md](references/terminology.md).\n\n| Use this | Not this | Notes |\n|---|---|---|\n| **bead** / **issue** | \"task\", \"ticket\", \"TODO item\" as the unit's name | Both terms are correct and interchangeable; lead with *bead* when teaching identity, use *issue* when mirroring CLI output or flags (`bd create`, \"issue types\"). \"task\" is one issue *type*, never the generic unit. |\n| **ready work** | \"unblocked queue\", \"available tasks\", \"the ready set\" as a formal term | Say what `bd ready` returns: open beads with no open blockers. |\n| **proto** | \"template\" as a noun for the concept | `template` stays only as the literal label name protos carry. |\n| **molecule** | \"mol\" in prose | `mol` is the command literal (`bd mol pour`); the concept is a molecule. |\n| **formula** | conflating formula with molecule/proto | The formula is the *file*; cooking makes a proto; pouring makes live work. |\n| **gate** | \"barrier\", \"checkpoint\", \"lock\" | Gates are async wait conditions with types (human, timer, gh:run, gh:pr, bead). |\n| **sync** = Dolt push/pull | export/import as a sync workflow | `bd dolt push` / `bd dolt pull` over `refs/dolt/data`. `.beads/issues.jsonl` is a passive export for viewers and interchange. |\n| **embedded mode** / **server mode** | \"local mode\", \"daemon mode\" for storage | Embedded is the default; data at `.beads/embeddeddolt/`. Server mode connects to `dolt sql-server`; data at `.beads/dolt/`. |\n| **federation** | \"multi-repo sync\" as a distinct feature name | Federation is the peer-to-peer cross-repo sharing feature. |\n| **hash ID** | \"random ID\", \"UUID\" | IDs like `bd-a1b2` are content-derived hashes sized adaptively to prevent collisions. |\n\n## 3. Content stance\n\n- **Motivate before you mechanize.** Lead a page with the problem it solves,\n  then the solution, then the mechanics. Never open on vocabulary.\n- **Docs are not the project's history.** No `internal/*` package paths, no\n  \"this was removed in vX\", no \"(v0.20.1+)\" gating on user pages — beads is a\n  1.x product and pre-1.0 archaeology belongs in `engdocs/` or the CHANGELOG.\n- **Lead with the value.** Beads' value is persistent, dependency-aware memory\n  for coding agents — agents that survive context loss because the work graph\n  outlives the session. The comparison framing (vs GitHub Issues, Jira,\n  markdown TODO lists) is the best newcomer conversion tool; keep it early\n  where it exists.\n- **One concrete example beats three abstract sentences.** Where you assert a\n  capability, show a `bd` invocation and what it prints.\n\n## 4. Information architecture\n\nNavigation lives in `docs/docs.json`: Getting Started, Core Concepts,\nArchitecture, Workflows, Recovery, Multi-Agent, Integrations, Community, and\nReference — with the generated CLI Reference nested inside Reference as a\ncollapsed sub-group.\n\n- **Every section has an index/Overview page** that introduces the section in\n  a sentence or two, then lists every child page with a one-line accurate\n  summary and link.\n- One page, one purpose. A page that tries to teach *and* specify does\n  neither — split it and cross-link.\n- Concept material is unified on `core-concepts/index`; don't re-derive the\n  model on other pages — link to it.\n- The repository map belongs in the README, not in `docs/`.\n\n## 5. Prose doctrine — cut words, sharpen points\n\nMost bloat is information stored in the wrong medium. Move it to a cheaper\ncarrier, then delete what isn't pulling weight. Every page must **stand\nalone** — a reader landing cold needs a one-line setup, not a previous page.\n\n**Convert** (move load off prose):\n- A relationship or sequence → a **diagram** (mermaid renders natively;\n  richer diagrams follow the Excalidraw pipeline — see §7).\n- Parallel options/fields/comparisons → a **table**.\n- \"you run X, which does Y\" narration → an **annotated CLI snippet** (show\n  the command and its output, comment the interesting lines).\n- Edge cases and deep mechanics → an `<Accordion>`, or a reference page.\n  Keep the 80% case on the page.\n\n**Delete** (the load was fake): throat-clearing openers (\"In this section\nwe'll…\"), hedge chains (\"generally / typically / in most cases\"),\nrestatement, narrating an artifact a snippet already shows, and adjectives\nstanding in for evidence.\n\nWhen you run a deliberate simplification pass, follow\n[references/simplification.md](references/simplification.md) — the per-page\nloop and the two guardrails that keep a trim honest: a **loss-check** (never\ndrop a fact that lives nowhere else) and a **fact-check** (trimmed prose must\nnot drift from the code).\n\n## 6. Emphasis and formatting\n\n- **Bold** *names a term*, on first mention only. *Italic* marks a property\n  or contrast. ~1–2 marks per paragraph; never re-emphasize a term already\n  introduced; never give one phrase both treatments.\n- No body `# H1` — the frontmatter `title` is the H1. Use `##`/`###`.\n- Links are root-relative and extensionless (`/getting-started/quickstart`).\n  Links out of the site (engdocs/, repo files) use full GitHub URLs.\n- Mintlify parses `.md` as MDX: no HTML comments (`{/* … */}` instead), and\n  angle-bracket placeholders like `<id>` must stay inside backticks or code\n  fences.\n- Mintlify components (`<Note>`, `<Tip>`, `<Warning>`, `<Accordion>`)\n  sparingly — they lose force with repetition.\n\n## 7. Diagrams\n\nMermaid fences render natively — prefer them for graphs and flows. For richer\ndiagrams use the Excalidraw pipeline: author the `.excalidraw` source under\n`docs/diagrams/excalidraw/`, render with `make diagrams-excalidraw` (source\nand rendered `.svg` are both committed), embed as\n`/diagrams/excalidraw-rendered/<name>.svg` with descriptive alt text, and\nkeep labels short (a two-line \"Name / role\" beats a sentence crammed in a\nbox). Two non-negotiables:\n\n- **Rasterize and look at every rendered diagram** — text overflow and layout\n  problems are invisible in a text diff.\n- **Diagrams and images cannot be reviewed in a diff.** Render them and get\n  the maintainer's approval before committing.\n\n## 8. Generated content is edited at its source\n\nNever hand-edit a generated file. The generated surfaces are:\n\n- `docs/cli-reference/*.md` and the CLI Reference pages array inside\n  `docs/docs.json` — bd emits vendor-neutral pages (`bd help --docs-root`,\n  from the Cobra command strings in `cmd/bd/*.go`) into an uncommitted\n  staging tree, and `tools/docsmint` post-processes them into the committed\n  Mintlify form. bd itself never emits Mintlify (or any site-generator)\n  specifics; that lives in docsmint.\n- `docs/CLI_REFERENCE.md` — the single-file reference, emitted directly by\n  `bd help --docs-root`.\n\nTo change wording in any of them, edit the Go source (`Short:`, `Long:`,\n`Example:` strings) and run `./scripts/generate-cli-docs.sh` (which runs both\nstages). To change the Mintlify page form itself (comment markers, link\nstyle, nav), edit `tools/docsmint` and its tests. The drift gates\n(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,\nand the docs-autofix bot) fail or auto-fix any hand edit.\n\n**The docs describe the pinned release, not main.** `docs/cli-docs.pin`\nnames the release tag the whole docs corpus targets; the pipeline builds bd\nfrom that tag and validates against it, so a Go-source edit on main shows up\nin the committed docs only after the pin is bumped (at release time,\nfollowed by a regeneration). Hand-written pages follow the same policy:\ndocument what the pinned release does, never main-only features. See\n`engdocs/decisions/2026-07-17-docs-release-pin.md`.\n\n## 9. Verify before you call it done\n\nRun the gates in [references/verification.md](references/verification.md).\nThe short list: `bazel test //test/docsync:docsync_test --config=ci`\n(nav↔file sync + link conventions),\n`./scripts/generate-cli-docs.sh --check` (generated docs fresh),\n`./scripts/check-doc-freshness.sh` (Last reviewed markers), and a live\npreview with `make docs-dev` (or `./mint.sh dev`) at `localhost:3000`.\n\nWhen you **move or remove a page**: add a redirect to the `redirects` array\nin `docs/docs.json`, rewrite inbound links repo-wide (README, engdocs/,\nexamples/, npm-package/, plugin resources — grep, don't guess), and check\nwhether `bd` prints the old path (if so, fix the Go source and regenerate —\nnever a pointer stub; decision 6 covers old routes with redirects).\n\n## 10. Review and commit discipline\n\n- **Author → the maintainer reviews → commit on explicit approval.** This\n  matters most for diagrams and images, which can't be reviewed in a text\n  diff.\n- Group commits by audience: user docs (`docs/`) separate from contributor\n  docs (`engdocs/`, `AGENTS.md`) separate from generator/Go changes.\n- Track docs work as bd issues per `AGENTS.md`.\n\n<!-- File: internal/templates/skills/beads/agents/openai.yaml (Tokens: ~300 | Category: anthropic-skill) -->\n# Agents Skill\n\nPath: `internal/templates/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/internal/templates/skills/beads/agents/openai.yaml)\n\n<!-- File: internal/templates/skills/beads/SKILL.md (Tokens: ~494 | Category: anthropic-skill) -->\n---\nname: beads\ndescription: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.\n---\n\n# Beads\n\nUse Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.\n\n## First Step\n\nRun:\n\n```bash\nbd prime\n```\n\nIf that prints nothing, check whether the repository has an active Beads workspace:\n\n```bash\nbd where\n```\n\n## Preferred Route\n\nUse the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.\n\n## Core CLI Workflow\n\n1. Find work:\n\n```bash\nbd ready\nbd list --status=open\nbd list --status=in_progress\n```\n\n2. Inspect before editing:\n\n```bash\nbd show <id>\n```\n\n3. Claim work atomically:\n\n```bash\nbd update <id> --claim\n```\n\n4. Create durable follow-up work when implementation reveals new tasks:\n\n```bash\nbd create \"Short title\" --description=\"Why this exists and what needs to be done\" --type=task --priority=2\n```\n\n5. Close completed work:\n\n```bash\nbd close <id> --reason=\"Completed\"\n```\n\n## What Belongs In Beads\n\nUse Beads for:\n\n- shared project tasks\n- blockers and dependencies\n- discovered follow-up work\n- work that must survive thread reset, compaction, or handoff\n- status that another person or agent should be able to resume\n\nUse agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.\n\n## Rules\n\n- Do not create markdown TODO files as the source of truth when Beads is available.\n- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.\n- Prefer `--json` when parsing `bd` output programmatically.\n- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.\n- Do not auto-close or mutate tasks unless the work is actually complete.\n\n<!-- File: plugins/beads/.codex-plugin/hooks/hooks.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Hooks Skill\n\nPath: `plugins/beads/.codex-plugin/hooks/hooks.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/.codex-plugin/hooks/hooks.json)\n\n<!-- File: plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Adr Skill\n\nPath: `plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md)\n\n<!-- File: plugins/beads/skills/beads/agents/openai.yaml (Tokens: ~300 | Category: anthropic-skill) -->\n# Agents Skill\n\nPath: `plugins/beads/skills/beads/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/agents/openai.yaml)\n\n<!-- File: plugins/beads/skills/beads/CLAUDE.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Beads Skill\n\nPath: `plugins/beads/skills/beads/CLAUDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/CLAUDE.md)\n\n<!-- File: plugins/beads/skills/beads/resources/AGENTS.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/AGENTS.md)\n\n<!-- File: plugins/beads/skills/beads/resources/ASYNC_GATES.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ASYNC_GATES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ASYNC_GATES.md)\n\n<!-- File: plugins/beads/skills/beads/resources/BOUNDARIES.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/BOUNDARIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/BOUNDARIES.md)\n\n<!-- File: plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md)\n\n<!-- File: plugins/beads/skills/beads/resources/CLI_REFERENCE.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/CLI_REFERENCE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/CLI_REFERENCE.md)\n\n<!-- File: plugins/beads/skills/beads/resources/DEPENDENCIES.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/DEPENDENCIES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/DEPENDENCIES.md)\n\n<!-- File: plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md)\n\n<!-- File: plugins/beads/skills/beads/resources/ISSUE_CREATION.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/ISSUE_CREATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/ISSUE_CREATION.md)\n\n<!-- File: plugins/beads/skills/beads/resources/MOLECULES.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/MOLECULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/MOLECULES.md)\n\n<!-- File: plugins/beads/skills/beads/resources/PATTERNS.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/PATTERNS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/PATTERNS.md)\n\n<!-- File: plugins/beads/skills/beads/resources/RESUMABILITY.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/RESUMABILITY.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/RESUMABILITY.md)\n\n<!-- File: plugins/beads/skills/beads/resources/STATIC_DATA.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/STATIC_DATA.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/STATIC_DATA.md)\n\n<!-- File: plugins/beads/skills/beads/resources/TROUBLESHOOTING.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/TROUBLESHOOTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md)\n\n<!-- File: plugins/beads/skills/beads/resources/WORKFLOWS.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKFLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKFLOWS.md)\n\n<!-- File: plugins/beads/skills/beads/resources/WORKTREES.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Resources Skill\n\nPath: `plugins/beads/skills/beads/resources/WORKTREES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/gastownhall/beads/HEAD/plugins/beads/skills/beads/resources/WORKTREES.md)\n\n<!-- File: plugins/beads/skills/beads/SKILL.md (Tokens: ~1345 | Category: anthropic-skill) -->\n---\nname: beads\ndescription: >\n  Dolt-powered issue tracker for multi-session work with dependencies and persistent\n  memory across conversation compaction. Use when work spans sessions, has blockers,\n  or needs context recovery after compaction. Trigger with \"create task\", \"what's\n  ready\", \"track this work\", \"resume after compaction\". Make sure to use this skill\n  whenever managing multi-session work, tracking dependencies, or recovering context.\nallowed-tools: \"Read,Bash(bd:*)\"\nversion: \"0.60.0\"\nauthor: \"Steve Yegge <steve.yegge@gmail.com>\"\nlicense: \"MIT\"\ncompatible-with: [claude-code, codex]\ntags: [issue-tracking, task-management, multi-session, dependencies]\n---\n\n# Beads - Persistent Task Memory for AI Agents\n\nGraph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.\n\n## bd vs TodoWrite\n\n**Decision test**: \"Will I need this context in 2 weeks?\" YES = bd, NO = TodoWrite.\n\n| bd (persistent) | TodoWrite (ephemeral) |\n|-----------------|----------------------|\n| Multi-session, dependencies, compaction survival | Single-session linear tasks |\n| Dolt-backed team sync | Conversation-scoped |\n\nSee [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.\n\n## Prerequisites\n\n```bash\nbd --version  # Requires v0.60.0+\n```\n\n- **bd CLI** installed and in PATH\n- **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)\n- **Initialization**: `bd init` run once (humans do this, not agents)\n\n## CLI Reference\n\n**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).\n**Run `bd <command> --help`** for specific command usage.\n\nEssential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd dolt push`\n\n## Session Protocol\n\n1. `bd ready` — Find unblocked work\n2. `bd show <id>` — Get full context\n3. `bd update <id> --claim` — Claim and start work atomically\n4. Add notes as you work (critical for compaction survival)\n5. `bd close <id> --reason \"...\"` — Complete task\n6. `bd dolt push` — Push to Dolt remote (if configured)\n\n## Output\n\nAppend `--json` to any command for structured output. Use `bd show <id> --long` for extended metadata. Status icons: `○` open `◐` in_progress `●` blocked `✓` closed `❄` deferred.\n\n## Error Handling\n\n| Error | Fix |\n|-------|-----|\n| `database not found` | `bd init <prefix>` in project root |\n| `not in a git repository` | `git init` first |\n| `disk I/O error (522)` | Move `.beads/` off cloud-synced filesystem |\n| Status updates lag | Use server mode: `bd dolt start` |\n\nSee [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.\n\n## Examples\n\n**Track a multi-session feature:**\n```bash\nbd create \"OAuth integration\" -t epic -p 1 --json\nbd create \"Token storage\" -t task --deps blocks:oauth-id --json\nbd ready --json                    # Shows unblocked work\nbd update <id> --claim --json      # Claim and start\nbd close <id> --reason \"Implemented with refresh tokens\" --json\n```\n\n**Recover after compaction:** `bd list --status in_progress --json` then `bd show <id> --long`\n\n**Discover work mid-task:** `bd create \"Found bug\" -t bug -p 1 --deps discovered-from:<current-id> --json`\n\n## Advanced Features\n\n| Feature | CLI | Resource |\n|---------|-----|----------|\n| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |\n| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |\n| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |\n| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |\n| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |\n\n## Resources\n\n| Category | Files |\n|----------|-------|\n| **Getting Started** | [BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) (live reference pointers), [WORKFLOWS.md](resources/WORKFLOWS.md) |\n| **Core Concepts** | [DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md) |\n| **Resilience** | [RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) |\n| **Advanced** | [MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md) |\n| **Reference** | [STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) |\n\n## Validation\n\nIf `bd --version` reports newer than `0.60.0`, this skill may be stale. Run `bd prime` for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).\n\n<!-- File: CLAUDE.md (Tokens: ~3286 | Category: claude-rule) -->\n# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n\n<!-- File: engdocs/CLAUDE.md (Tokens: ~3286 | Category: claude-rule) -->\n# Beads — Contributor Agent Instructions\n\nThis file is for agents and humans **developing beads** (`bd`). If you are\nusing `bd` to track work in your own project, read the user docs instead:\n[docs site](https://beads.gascity.com/) and\n[IDE and agent setup](docs/getting-started/ide-setup.md).\n\n<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this\ncheckout: they would inject the end-user beads integration block here. -->\n\nNested `AGENTS.md` files hold area-specific rules; the routing table at the\nend lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.\n\n## How work flows here\n\nGitHub Issues is the public tracker. Use an issue when it adds context\nreviewers need: a user-visible bug, a behavior or design change worth\ndiscussing, or work that spans several PRs. The issue carries the\nreproduction, impact, and evidence for a bug, or the motivation, impact, risk,\nand verification plan for a change. Small, self-explanatory changes (typos,\nflaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body\nexplains the why.\n\n1. If the change warrants an issue, find or file one with the bug or feature\n   form. It does not need maintainer approval first; file it before or\n   alongside the PR.\n2. Work on a branch, open a PR against `main` (its body says\n   `Closes #<issue>` when there is one), and let CI and review run.\n3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,\n   `status/needs-repro`, `status/needs-design`, and `status/accepted`\n   (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nMaintainers also keep an internal bd ledger. It is optional for contributors\nand not a substitute for the GitHub issue.\n\n## Agent contribution policy\n\n- File an issue when the change warrants one (see above). When you do, use\n  the bug or feature form fields, fill each from evidence, and answer\n  `NOT_ENOUGH_INFO` where the evidence runs out.\n- A human reviews and stands behind every issue and PR an agent drafts.\n  Evidence that the change works end-to-end is required; \"unit tests pass\"\n  alone is not evidence.\n- Before implementing work, opening a PR, or merging/closing a PR, run the PR\n  preflight:\n  ```bash\n  scripts/pr-preflight.sh --search \"<topic keywords>\" --repo gastownhall/beads\n  scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads\n  ```\n  The preflight is the agent gate for PR handling; do not rely on\n  auto-discovery of CONTRIBUTING.md.\n- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,\n  comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,\n  and pass the file with `gh ... --body-file`. Sign agent-written GitHub\n  comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).\n\n## Contributor protection\n\nExternal contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)\n— it contains promises we've made to contributors — and, before triaging,\nreviewing, landing, closing, or otherwise maintaining PRs,\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing any feature or fix, check for existing open PRs on the\nsame topic. If one exists:\n\n1. **Review it first** — read the diff, understand the approach.\n2. **Build on their work, don't rewrite it** — check out their branch,\n   fix/adapt as needed.\n3. **Preserve their tests** — keep them unless they're wrong.\n4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.\n5. **Never close or supersede their PR silently.** If a rewrite is\n   unavoidable, explain why on the original PR and credit their design/tests.\n\n## Scope: where a change belongs\n\nRead [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding\nfeature surface area. Beads owns issue tracking primitives and should not\nencode orchestration-layer policy, become a storage engine, or casually expand\nthe database schema when metadata would work. Prefer, in order: issue\nmetadata over new fields, a flag on an existing command over a new command,\nan integration or plugin over core, and leave orchestration policy to the\norchestration layer.\n\n**Storage boundary.** Beads talks to storage through a driver interface\n(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine\nintrospection, storage-specific retry or crash-recovery logic, or public SDK\nreturn types that leak driver internals. If the boundary is too narrow, widen\nthe interface or route the issue to the driver instead of patching around it\nin beads. `bd doctor` support for embedded mode is enabled one subcommand at a\ntime, each human-vetted (GH#3794): do not lift the embedded-mode gate in\n`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes\nserver-gated until the driver interface covers them.\n\n**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new\nprimitives at the lowest layer first, one layer per PR, stacked when a fix\nspans layers. See\n[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).\n\n## Build, test, lint\n\nBazel is the build and test system: CI gates on the `bazel test` lanes in\n`.github/workflows/bazel.yml`, and nogo (lint + vet), gofmt and the repository\nguards exist only as Bazel targets. Install\n[Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit\nand pre-push hooks need it.\n\n```bash\nmake test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)\nmake check         # testing.Short policy + make ci-pr-lint + make test\nmake ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin\nmake check-docs    # bazel docsync + doc freshness, then the CLI flag check\nmake bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod\nmake install       # build and install bd to ~/.local/bin (canonical)\n```\n\n- Each other tier has its own lane (`--config=integration`, `doltserver`,\n  `embedded`, ...); [engdocs/TESTING.md](engdocs/TESTING.md) lists the exact\n  command per lane and is the canonical source for test selection, design,\n  and PR-readiness gates.\n- Where actions run: contributors add `--config=fork-cache` (rbe-west's\n  anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west\n  certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the\n  executor neither. Make yours the default with a `build --config=...` line in\n  the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.\n- Agents run tests only with `bazel test`, also while iterating on one\n  behavior:\n\n  ```bash\n  bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all\n  ```\n\n  A target also passes when the test never ran (a filter that matches\n  nothing, a skip, a file the configuration does not compile), so count a run\n  only when its log shows `--- PASS: TestName` and no `--- SKIP` for the test\n  or a `TestName/...` subtest: Go prints `--- PASS` for a test whose every\n  subtest skipped. \"Check That the Test Ran\" in\n  [engdocs/TESTING.md](engdocs/TESTING.md) names the tests `--config=ci` does\n  not run (Dolt-backed, `-short`-gated, integration-tagged, `TestEmbedded*`\n  and embedded-Dolt, files `BUILD.bazel` does not list) and the way into\n  each. An unchanged target returns its cached result, which is the same\n  evidence. Finish with `make test`.\n- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does\n  not enforce it, it skips nogo, gofmt and the guards, and agent hosts may\n  refuse it. It stays a convenience for humans working offline. The exception\n  is regenerating golden files (`make corpus-regen`, `make githooks-regen`,\n  `BD_UPDATE_GOLDEN=1`), which Bazel cannot do: see \"Regenerating Golden\n  Files\" in [engdocs/TESTING.md](engdocs/TESTING.md).\n- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw\n  `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale\n  binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,\n  `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.\n- All new features need tests.\n- **Never pollute a production database with test issues.** Use `t.TempDir()`\n  in Go tests and a disposable working directory for manual `bd` experiments.\n- `make ci-pr-lint` must pass with zero issues; see\n  [engdocs/LINTING.md](engdocs/LINTING.md).\n- If BUILD files are out of sync and you cannot run `make bazel-sync`, CI\n  syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to\n  your branch (pull before pushing again); fork PRs get a comment with an\n  apply recipe.\n- If you changed behavior, update the user docs (`docs/`, via the\n  `beads-docs` skill) or README in the same PR.\n\n## Commits and PRs\n\n- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,\n  `test`, `refactor`, `chore`, `ci`, `perf`).\n- For agent-prepared commits, include the `Agent-Signature:` trailer described\n  in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use\n  `unknown-model` or `unknown-reasoning` when reliable runtime metadata is\n  unavailable.\n- Maintainers working from the internal ledger may also end the subject with\n  the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.\n- Work on a feature branch and open a PR against `main`; direct pushes to\n  `main` are reserved for releases and narrow operational fixes.\n- When the user asks to bump the version, use `./scripts/bump-version.sh`; the\n  full release process is in [RELEASING.md](RELEASING.md).\n\n## Ending a session\n\nDo not push to `main`. Before handing off:\n\n1. Run the quality gates your change needs (`make test`, `make ci-pr-lint`,\n   and the other Bazel lanes [engdocs/TESTING.md](engdocs/TESTING.md)\n   selects). If gates are broken on `main`, report it as a P0 issue.\n2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).\n3. Commit, push, or open a PR only when the person you are working for asked\n   you to. Report changed files, validation run, and anything left open.\n\n## CLI output\n\n**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small\nUnicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a\n`P0`–`P4` label with color (no status glyph). The full visual design system\nand CLI design principles are in\n[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).\n\n## Non-interactive shell commands\n\nAgents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,\n`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;\n`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it\nopens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`\n(pipe text with special characters via `--description=-`).\n\n## Routing table\n\n| When you are touching… | Read first |\n|---|---|\n| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |\n| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |\n| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |\n| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |\n| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |\n| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |\n| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |\n| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |\n| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |\n| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |\n| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |\n| Releases and version bumps | [RELEASING.md](RELEASING.md) |\n| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |\n| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~183 | Category: copilot-instructions) -->\n# GitHub Copilot instructions for beads\n\nThe canonical contributor instructions for this repository are in\n[AGENTS.md](../AGENTS.md); area-specific rules are in the nested `AGENTS.md`\nfiles listed in its routing table. Read those, not this file, for workflow,\nbuild, test, and scope rules.\n\nThe rules most often missed in review:\n\n- A PR must close a documented GitHub issue (filed before or alongside it).\n- Build with `make install`, never `go build -o bd ./cmd/bd` or `go install ./cmd/bd`.\n- `make ci-pr-lint` must pass with zero issues; choose tests with\n  [engdocs/TESTING.md](../engdocs/TESTING.md).\n- Never create test issues in a production database; use `t.TempDir()`.\n- CLI output uses small Unicode status symbols, never emoji icons.\n\n<!-- ... +40 more modular skills available via /api/skills/gastownhall/beads?path={path} -->\n</yakaai_skills>"}