From 6865560e89c6b6a19a3809074ad9935acdc5239b Mon Sep 17 00:00:00 2001 From: Hadrien David Date: Fri, 17 Jul 2026 10:58:02 -0400 Subject: [PATCH] chore: initialize beads integration --- .agents/skills/beads/SKILL.md | 92 +++++++++++++++++++ .agents/skills/beads/agents/openai.yaml | 4 + .beads/.gitignore | 61 +++++++++---- .beads/config.yaml | 4 +- .beads/interactions.jsonl | 1 + .beads/metadata.json | 5 +- .claude/settings.json | 3 + .codex/config.toml | 2 + .codex/hooks.json | 51 +++++++++++ .gitignore | 6 ++ AGENTS.md | 115 +++++++++++++++++++++++- CLAUDE.md | 1 + 12 files changed, 322 insertions(+), 23 deletions(-) create mode 100644 .agents/skills/beads/SKILL.md create mode 100644 .agents/skills/beads/agents/openai.yaml create mode 100644 .claude/settings.json create mode 100644 .codex/config.toml create mode 100644 .codex/hooks.json create mode 120000 CLAUDE.md diff --git a/.agents/skills/beads/SKILL.md b/.agents/skills/beads/SKILL.md new file mode 100644 index 0000000..32bb40f --- /dev/null +++ b/.agents/skills/beads/SKILL.md @@ -0,0 +1,92 @@ +--- +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. +--- + +# Beads + +Use 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. + +## First Step + +Run: + +```bash +bd prime +``` + +If that prints nothing, check whether the repository has an active Beads workspace: + +```bash +bd where +``` + +## Preferred Route + +Use the `bd` CLI when shell access is available. It is the most compact and direct +Beads interface. + +## Core CLI Workflow + +1. Find work: + +```bash +bd ready +bd list --status=open +bd list --status=in_progress +``` + +2. Inspect before editing: + +```bash +bd show +``` + +3. Claim work atomically: + +```bash +bd update --claim +``` + +4. Create durable follow-up work when implementation reveals new tasks: + +```bash +bd create "Short title" \ + --description="Why this exists and what needs to be done" \ + --type=task \ + --priority=2 +``` + +5. Close completed work: + +```bash +bd close --reason="Completed" +``` + +## What Belongs In Beads + +Use Beads for: + +- shared project tasks +- blockers and dependencies +- discovered follow-up work +- work that must survive thread reset, compaction, or handoff +- status that another person or agent should be able to resume + +Use agent-local planning tools only for the current turn's execution checklist. Do not +treat them as shared project state. + +## Rules + +- Do not create markdown TODO files as the source of truth when Beads is available. +- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead. +- Prefer `--json` when parsing `bd` output programmatically. +- If hooks are installed, `bd prime` may already be injected. Run it manually when + context is missing. +- Do not auto-close or mutate tasks unless the work is actually complete. diff --git a/.agents/skills/beads/agents/openai.yaml b/.agents/skills/beads/agents/openai.yaml new file mode 100644 index 0000000..09c3b8f --- /dev/null +++ b/.agents/skills/beads/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Beads" + short_description: "Project task tracking with bd" + default_prompt: "Use $beads to inspect ready work and manage durable project tasks." diff --git a/.beads/.gitignore b/.beads/.gitignore index dba6914..f773858 100644 --- a/.beads/.gitignore +++ b/.beads/.gitignore @@ -1,16 +1,32 @@ # Dolt database (managed by Dolt, not git) dolt/ -dolt-access.lock +embeddeddolt/ +proxieddb/ # Runtime files bd.sock bd.sock.startlock sync-state.json last-touched +.exclusive-lock + +# Daemon runtime (lock, log, pid) +daemon.* + +# Push state (runtime, per-machine) +push-state.json + +# Lock files (various runtime locks) +*.lock + +# Credential key (encryption key for federation peer auth — never commit) +.beads-credential-key # Local version tracking (prevents upgrade notification spam after git ops) .local_version +proxied_server_client_info.json + # Worktree redirect file (contains relative path to main repo's .beads/) # Must not be committed as paths would be wrong in other clones redirect @@ -18,9 +34,9 @@ redirect # Sync state (local-only, per-machine) # These files are machine-specific and should not be shared across clones .sync.lock -.jsonl.lock -sync_base.jsonl export-state/ +export-state.json +last_pull # Ephemeral store (SQLite - wisps/molecules, intentionally not versioned) ephemeral.sqlite3 @@ -28,6 +44,25 @@ ephemeral.sqlite3-journal ephemeral.sqlite3-wal ephemeral.sqlite3-shm +# Dolt server management (auto-started by bd) +dolt-server.pid +dolt-server.log +dolt-server.lock +dolt-server.port +dolt-server.activity + +# Debug-mode pprof artifacts (written when dolt.debug: true in config.yaml) +dolt-pprof/ + +# Corrupt backup directories (created by bd doctor --fix recovery) +*.corrupt.backup/ + +# Backup data (auto-exported JSONL, local-only) +backup/ + +# Per-project environment file (Dolt connection config, GH#2520) +.env + # Legacy files (from pre-Dolt versions) *.db *.db?* @@ -36,19 +71,7 @@ ephemeral.sqlite3-shm *.db-shm db.sqlite bd.db -daemon.lock -daemon.log -daemon-*.log.gz -daemon.pid -beads.base.jsonl -beads.base.meta.json -beads.left.jsonl -beads.left.meta.json -beads.right.jsonl -beads.right.meta.json - -# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here. -# They would override fork protection in .git/info/exclude, allowing -# contributors to accidentally commit upstream issue databases. -# The JSONL files (issues.jsonl, interactions.jsonl) and config files -# are tracked by git by default since no pattern above ignores them. +# NOTE: Do NOT add negation patterns here. +# They would override fork protection in .git/info/exclude. +# Config files (metadata.json, config.yaml) are tracked by git by default +# since no pattern above ignores them. diff --git a/.beads/config.yaml b/.beads/config.yaml index 56db572..6d589f7 100644 --- a/.beads/config.yaml +++ b/.beads/config.yaml @@ -6,7 +6,9 @@ # Issue prefix for this repository (used by bd init) # If not set, bd init will auto-detect from directory name # Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc. -# issue-prefix: "" +issue-prefix: "fs" +sync: + remote: "git+ssh://git@github.com/hadrien/FastSQLA.git" # Use no-db mode: load from JSONL, write back after each command # When true, bd will use .beads/issues.jsonl as the source of truth diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index e69de29..af83192 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -0,0 +1 @@ +{"id":"int-8e643c17940be7b82385710ff7ff0bf4","kind":"field_change","created_at":"2026-07-17T15:26:25.427956Z","actor":"Hadrien David","issue_id":"fs-pkw","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Resolved via PR #95: added .github/workflows/dependabot-automerge.yml using the built-in GITHUB_TOKEN for approval and squash auto-merge. Enabled repository auto-merge, required Tests (fastapi-pre121), Tests (fastapi-post121), Tests (sqlmodel), and Ruff in the main ruleset, and enabled can_approve_pull_request_reviews while preserving default workflow permissions as read. The first runtime approval on PR #88 failed because the repository approval gate was false; corrected the setting and verified end-to-end auto-approval and auto-merge on PRs #88 and #87 after green CI. human_minutes: spec=5, design=15, review=5, testing=20, ops=15."}} diff --git a/.beads/metadata.json b/.beads/metadata.json index f917592..e883405 100644 --- a/.beads/metadata.json +++ b/.beads/metadata.json @@ -1,6 +1,7 @@ { "database": "dolt", - "jsonl_export": "issues.jsonl", "backend": "dolt", - "dolt_database": "beads_fastsqla" + "dolt_mode": "embedded", + "dolt_database": "beads_fastsqla", + "project_id": "77e9debd-5928-4488-ad31-c390e573f863" } \ No newline at end of file diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..ad64a63 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,3 @@ +{ + "hooks": {} +} \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..146af7e --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,2 @@ +[features] +hooks = true diff --git a/.codex/hooks.json b/.codex/hooks.json new file mode 100644 index 0000000..13c7229 --- /dev/null +++ b/.codex/hooks.json @@ -0,0 +1,51 @@ +{ + "hooks": { + "PostCompact": [ + { + "hooks": [ + { + "command": "bd codex-hook PostCompact", + "statusMessage": "Scheduling Beads context refresh", + "type": "command" + } + ], + "matcher": "manual|auto" + } + ], + "PreCompact": [ + { + "hooks": [ + { + "command": "bd codex-hook PreCompact", + "statusMessage": "Checking Beads context", + "type": "command" + } + ], + "matcher": "manual|auto" + } + ], + "SessionStart": [ + { + "hooks": [ + { + "command": "bd codex-hook SessionStart", + "statusMessage": "Loading Beads context", + "type": "command" + } + ], + "matcher": "startup|resume|clear" + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "command": "bd codex-hook UserPromptSubmit", + "statusMessage": "Refreshing Beads context", + "type": "command" + } + ] + } + ] + } +} diff --git a/.gitignore b/.gitignore index 8d5ec30..00a9232 100644 --- a/.gitignore +++ b/.gitignore @@ -163,3 +163,9 @@ cython_debug/ .beads/backup .beads/embeddeddolt .beads/dolt-server.* + +# Beads / Dolt files (added by bd init) +.dolt/ +*.db +.beads-credential-key +.beads/proxieddb/ diff --git a/AGENTS.md b/AGENTS.md index df7a4af..fd40efa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,8 @@ bd sync # Sync with git ## Landing the Plane (Session Completion) -**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. +**When ending a work session**, you MUST complete ALL steps below. Work is NOT +complete until `git push` succeeds. **MANDATORY WORKFLOW:** @@ -38,3 +39,115 @@ bd sync # Sync with git - NEVER say "ready to push when you are" - YOU must push - If push fails, resolve and retry until it succeeds +## Beads Remote + +All Beads Dolt pushes disable the optional visible info branch: + +```bash +DOLT_REMOTE_INFO_BRANCH='' bd dolt push +``` + +Do not run a bare `bd dolt push`; it recreates `__dolt_remote_info__`. + + + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full +workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # 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**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + bd dolt push + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked + sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current + user request. +- If a required sync or push is blocked, stop and report the exact command and error. + + + +## Beads Issue Tracker + +Use Beads (`bd`) for durable task tracking in repositories that include it. Use the +`beads` skill at `.agents/skills/beads/SKILL.md` (project install) or +`~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then +use the `bd` CLI for issue operations. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # 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. + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file