bdboard

Imported from xiaotiantakumi/bdboard (AGENTS.md). Install upstream with npx skills add xiaotiantakumi/bdboard. Copyright stays with the author.

Project Instructions for AI Agents

AI コーディングエージェント向けの常時ロードされる指示 (CLAUDE.md はこのファイルへの シンボリックリンク)。200 行以下に保つ — 詳細は各節が指す skill / .claude/rules/ / docs/ に置き、ここには「常に必要なこと」と「いつそれを読むか」だけ書く。課題管理は bd (beads): 全体像は bd prime。bd issue 履歴はメンテナのローカル環境限定で git 追跡していない — clone に .beads/ が無いのは正常、他に取得すべきものは無い。貢献は GitHub Issues/PR で。

Non-Interactive Shell Commands

ALWAYS use non-interactive flags. cp / mv / rm は -i に alias されていることがあり、 y/n 待ちでエージェントが無限にハングする。cp -f / mv -f / rm -f / rm -rf / cp -rf、 apt-get -y、scp / ssh は -o BatchMode=yes、brew は HOMEBREW_NO_AUTO_UPDATE=1。

Beads Issue Tracker

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

Quick Reference

bd ready --exclude-label gt:slot   # Find available work (merge-slot bead除外)
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

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

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

Agent Context Profiles

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

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

Session Completion

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

1. File issues for remaining work - Create beads for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. Handle git/sync by active profile:

   # Conservative/minimal/default: report status and proposed commands; wait for approval.
   git status
   
   # Team-maintainer opt-in only, unless current instructions forbid it:
   git pull --rebase
   git push
   git status

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

Critical rules:

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

Beads Issue Tracker

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

Quick Reference

bd ready --exclude-label gt:slot   # Find available work (merge-slot bead除外)
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

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

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

bd init Re-runs: Reviewing the Managed AGENTS.md Block

bd init / bd setup <tool> は上のマーカー内側を毎回再生成する。2026-08-17 に別マシンの bd init がカスタマイズ 2 件を黙って戻し、main へ直接コミットした (bdboard-ejz)。 走らせたら staging/commit の前に git diff -- AGENTS.md を必ず確認する。 チェック項目・ --agents-template の限界・main 直コミット時の復旧手順は .claude/rules/bd-init-agents-md.md (AGENTS.md / CLAUDE.md / .beads/** を触ると読み込まれる path-scoped rule)。

Build & Test

Before committing any change (server or web), run the full verification chain — it must be clean:

npm run verify   # check:file-size + lint:verify + build + build:web + test:server + test:web + check:boundaries

• フルチェーンは必ず npm run verify で回す。npm run verify:steps の直叩きは禁止 — プロセスグループ kill (bdboard-kia) とスロットの両方を迂回する。反復中の個別ステップは可。lint は ESLint + typescript-eslint (src/ web/src/ scripts/ のみ、詳細は docs/VERIFY.md)。
• Verify slots: verify は 1 マシン最大 2 並列に自分でスロット制限する (2026-08-18 に 6 並列が load average 190–258 を数時間続けた事故 bdboard-d48 の対策)。verify: waiting for a verify slot (queue position N/M …) が 10 秒ごとに出るのはハングではなく FIFO 待ち。kill して 再実行すると列の最後尾に戻るだけなので、長めのタイムアウトで待つ。
• ポートは BDBOARD_PORT (既定 8787)。worktree で npm run dev を回さない (メインチェック アウトのポートと衝突)。vitest / tsc / depcruise は並列 worktree で問題ない。
• tsc 3 プロジェクトの表、slot の stale 処理と env ノブ、npm run check:file-size の baseline 運用、npm run check:commits とコミットメッセージの括弧ガード: docs/VERIFY.md。

Always-On Local Hosting (main checkout)

メインチェックアウト (worktree ではない) は、エージェントセッション中つねにボードを serve して いること。セッション開始時に確認する:

curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8787/api/health

• curl の exit status ではなくステータスコードで判定する。 200 が正常 (ローカル直アクセスは Basic 認証を迂回する)。401/503 はリスナーは居るので二重起動しない。000 (exit 7) だけが停止。
• 000 だった / リスナーは居るのに応答しない / マージ後に作り直す / トンネルが同居している — いずれも skill bdboard-server-ops を読んでから動く (.claude/skills/bdboard-server-ops/SKILL.md)。ブラウザのタブが描画されていることは生存証明に ならない (キャッシュで動いて見える)。
• worktree からは preview_start 禁止 — .claude/launch.json は各 worktree にもあるため 8787 を奪い、そのブランチの古い UI を配ってしまう (実測 2026-08-29、12 worktree 中 9 が該当)。
• 止める・作り直しは scripts/always-on-server.sh 経由だけ (議長のみ): BDBOARD_SERVER_CALLER=chair scripts/always-on-server.sh restart --expect-pid <PID> [--pull] (--pull 無しでは pull しない。 マージ直後は deploy を使う。PID は status で確認)。pkill/killall 等のパターン指定の停止は全 エージェントで禁止 (Claude Code では permissions.deny でも拒否される)。isolation: "worktree" が塞ぐのは bdboard-worker が main checkout で直接打つ pull/start だけ。always-on-server.sh の実行と、非隔離の子の pull/start を止めるのは文書規律だけ (bdboard-25n3・bdboard-cm2q.10)。
• launchd plist 等の常駐デーモン化はしない (別途ユーザー承認が要る変更)。

Git Workflow (multi-session: per-ticket worktree + branch + PR)

2026-08-15 以降、direct-to-main ではなく 1 チケット = 1 worktree = 1 ブランチ = 1 PR (bdboard-3tw.74)。手順の詳細・根拠・事故記録は docs/GIT-WORKFLOW.md。

• Branch bd/<ticket-id> (ID をそのまま使う。非チケットの探索は spike/ で PR にしない) / worktree .claude/worktrees/<ticket-id>/ (origin/main から作成、マージ後に削除。 worktree ごとに npm install && npm --prefix web install が要る)。
• Lifecycle: bd update <id> --claim → worktree+branch 作成 → 実装 → 機能追加/変更なら ヘルプ原本 docs/help-content.json の追従を確認 → npm run drift (PR が数時間開いていたら 再実行) → npm run verify (PR を開く前にクリーンであること) → gh pr create --fill --body "Closes: <ticket-id> …" → bd comment <id> "PR: <url>" → CI green → マージ (マージは議長のみ。S1/S2 の gate/finish は BDBOARD_MERGER=chair を要求。origin/main の merge.mode で分岐。S0: drift → bd merge-slot acquire → ls-remote で CAS → gh pr merge --squash --delete-branch → 着地後検証 → release / S1・S2: npm run merge-pr -- prepare|gate|finish <N> で枠は CAS とマージの間だけ・着地後検証は commit status。docs/GIT-WORKFLOW.md) → bd close <id> はマージ成功後だけ (PR を開いた時点では閉じない — bd ready が他セッションに嘘をつく)。
• Direct-to-main commits are banned, no exceptions. CI 復旧も PR 経由 (bypass は pull requests only、2026-09-26 変更)。
• .beads/ はこのリポジトリで git 追跡していない (ルート .gitignore 参照)。PR で .beads/ 配下を追加・変更しない — CI が origin/main との diff に含めば PR を落とす。
• Dolt remote は必ず --remote <name> を明示する（--remote origin も不可）。素の bd dolt push / bd dolt pull は この repo で禁止 — origin を Dolt 層が黙って採用しうる (bdboard-23v / bdboard-jb1)。事前に bd dolt remote list で origin が無いことを確認する。Dolt remote を使う環境では push はセッション終わりに。
• Cleanup after merge (マージしたセッションの責任): git worktree remove → git branch -D bd/<id> → git remote prune origin。常時稼働サーバーの再起動は掃除に含めず 議長が行う (Always-On 節。サブエージェントは報告のみ)。remove 前に lsof -a -d cwd +D <worktree> で他セッションが居ないか確認する (bdboard-3tw.61)。

Architecture Overview

See docs/ARCHITECTURE.md for the onion 4-layer breakdown (domain/application/infrastructure/interface), the port list, the bd CLI → cache → SSE → UI data flow, and the safety guarantees (readonly bd calls, the write-guard middleware, and the agent Runner — reachable only via POST /api/runs behind agent-run-guard; local runs allowed, remote off by default, the remote toggle is local-only and read once at startup). Original design doc: docs/PLAN.md.

Conventions & Patterns

• テストの username/password ペアは明らかに偽の形にする — example-user / example-password (2 組目が要るなら example-tunnel-user のような区別付き)。隣接する username/password フィールド、USER/PASSWORD 定数、scheme://user:pass@host の URL リテラルが対象。GitGuardian の "Username Password" 検出器は値ではなく形で発火するので、 偽の値でも触れた PR ごとに人手のトリアージを発生させる。値を消して回避するのは不可 (テストが 弱くなる)。bdboard-3tw.81、先例 bdboard-1qm PR#3 web/src/components/TunnelControl.test.tsx。
• ヘルプドキュメントの追従: ユーザーから見える機能・操作・画面/ビュー名を追加・変更・削除する PR は、単一原本 docs/help-content.json の該当セクションを同じ PR 内で更新する (「更新不要」も正当な結論だが、確認自体は省略しない)。Web ヘルプ・チャット system prompt・ ボード上部の Tips はすべてここから派生する。詳細: docs/HELP-CONTENT.md (bdboard-3tw.138.4)。
• aimix は .claude/skills/bdboard-harness/scripts/aimix-run.sh 経由で呼ぶ (素の aimix run は deny。bdboard-cm2q.12)。
• 工程ごとの使用モデルを bd に記録する: bd update <id> --set-metadata bdboard.model.<工程>=<モデル名> (例 bdboard.model.implement=composer-2.5、解除は --unset-metadata bdboard.model.<工程>)。 工程名は自由文字列で、慣用は implement / test / review / check (この順で詳細パネルに 表示され、未知の工程はその後にアルファベット順)。bdboard 側は表示専用で入力 UI は無く、記録は 作業したエージェント自身が行う (bdboard-aeg)。