bd init: initialize beads issue tracking
This commit is contained in:
1 parent
0b91a8a2a7
commit
f37c3dce5e
17 files changed
+754
No files matched your search
@@ -0,0 +1,80 @@
|
|||||||
|
---
|
||||||
|
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 <id>
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Claim work atomically:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bd update <id> --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 <id> --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.
|
||||||
@@ -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."
|
||||||
@@ -68,3 +68,10 @@ bd.db
|
|||||||
# They would override fork protection in .git/info/exclude.
|
# They would override fork protection in .git/info/exclude.
|
||||||
# Config files (metadata.json, config.yaml) are tracked by git by default
|
# Config files (metadata.json, config.yaml) are tracked by git by default
|
||||||
# since no pattern above ignores them.
|
# since no pattern above ignores them.
|
||||||
|
|
||||||
|
# Added by bd (missing required patterns)
|
||||||
|
*.gate.lock*
|
||||||
|
last_pull
|
||||||
|
proxieddb/
|
||||||
|
dolt-server-config.yaml
|
||||||
|
proxied_server_client_info.json
|
||||||
@@ -1 +1,5 @@
|
|||||||
no-git-ops: true
|
no-git-ops: true
|
||||||
|
sync:
|
||||||
|
remote: "git+ssh://gitea@code.m3ta.dev/m3tam3re/agent-lib.git"
|
||||||
|
export:
|
||||||
|
auto: true
|
||||||
Executable
+59
@@ -0,0 +1,59 @@
|
|||||||
|
#!/usr/bin/env sh
|
||||||
|
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
|
||||||
|
# This section is managed by beads. Do not remove these markers.
|
||||||
|
if command -v bd >/dev/null 2>&1; then
|
||||||
|
export BD_GIT_HOOK=1
|
||||||
|
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||||
|
case "$_bd_timeout" in
|
||||||
|
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
|
||||||
|
*[1-9]*) _bd_timeout_invalid=0 ;;
|
||||||
|
*) _bd_timeout_invalid=1 ;;
|
||||||
|
esac
|
||||||
|
if [ "$_bd_timeout_invalid" -eq 1 ]; then
|
||||||
|
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
|
||||||
|
_bd_timeout=300
|
||||||
|
fi
|
||||||
|
_bd_timeout_backend=none
|
||||||
|
_bd_timeout_command=
|
||||||
|
for _bd_timeout_candidate in timeout gtimeout; do
|
||||||
|
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
|
||||||
|
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
|
||||||
|
case "$_bd_timeout_version" in
|
||||||
|
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
|
||||||
|
esac
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
if [ -n "$_bd_timeout_command" ]; then
|
||||||
|
_bd_timeout_backend=coreutils
|
||||||
|
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run post-checkout "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
elif command -v perl >/dev/null 2>&1; then
|
||||||
|
_bd_timeout_backend=perl
|
||||||
|
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run post-checkout "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo >&2 "beads: hook 'post-checkout' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||||
|
if bd hooks run post-checkout "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
|
||||||
|
echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -eq 3 ]; then
|
||||||
|
echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||||
|
fi
|
||||||
|
# --- END BEADS INTEGRATION v1.3.2 ---
|
||||||
Executable
+59
@@ -0,0 +1,59 @@
|
|||||||
|
#!/usr/bin/env sh
|
||||||
|
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
|
||||||
|
# This section is managed by beads. Do not remove these markers.
|
||||||
|
if command -v bd >/dev/null 2>&1; then
|
||||||
|
export BD_GIT_HOOK=1
|
||||||
|
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||||
|
case "$_bd_timeout" in
|
||||||
|
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
|
||||||
|
*[1-9]*) _bd_timeout_invalid=0 ;;
|
||||||
|
*) _bd_timeout_invalid=1 ;;
|
||||||
|
esac
|
||||||
|
if [ "$_bd_timeout_invalid" -eq 1 ]; then
|
||||||
|
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
|
||||||
|
_bd_timeout=300
|
||||||
|
fi
|
||||||
|
_bd_timeout_backend=none
|
||||||
|
_bd_timeout_command=
|
||||||
|
for _bd_timeout_candidate in timeout gtimeout; do
|
||||||
|
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
|
||||||
|
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
|
||||||
|
case "$_bd_timeout_version" in
|
||||||
|
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
|
||||||
|
esac
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
if [ -n "$_bd_timeout_command" ]; then
|
||||||
|
_bd_timeout_backend=coreutils
|
||||||
|
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run post-merge "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
elif command -v perl >/dev/null 2>&1; then
|
||||||
|
_bd_timeout_backend=perl
|
||||||
|
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run post-merge "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo >&2 "beads: hook 'post-merge' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||||
|
if bd hooks run post-merge "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
|
||||||
|
echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -eq 3 ]; then
|
||||||
|
echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||||
|
fi
|
||||||
|
# --- END BEADS INTEGRATION v1.3.2 ---
|
||||||
Executable
+59
@@ -0,0 +1,59 @@
|
|||||||
|
#!/usr/bin/env sh
|
||||||
|
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
|
||||||
|
# This section is managed by beads. Do not remove these markers.
|
||||||
|
if command -v bd >/dev/null 2>&1; then
|
||||||
|
export BD_GIT_HOOK=1
|
||||||
|
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||||
|
case "$_bd_timeout" in
|
||||||
|
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
|
||||||
|
*[1-9]*) _bd_timeout_invalid=0 ;;
|
||||||
|
*) _bd_timeout_invalid=1 ;;
|
||||||
|
esac
|
||||||
|
if [ "$_bd_timeout_invalid" -eq 1 ]; then
|
||||||
|
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
|
||||||
|
_bd_timeout=300
|
||||||
|
fi
|
||||||
|
_bd_timeout_backend=none
|
||||||
|
_bd_timeout_command=
|
||||||
|
for _bd_timeout_candidate in timeout gtimeout; do
|
||||||
|
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
|
||||||
|
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
|
||||||
|
case "$_bd_timeout_version" in
|
||||||
|
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
|
||||||
|
esac
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
if [ -n "$_bd_timeout_command" ]; then
|
||||||
|
_bd_timeout_backend=coreutils
|
||||||
|
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run pre-commit "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
elif command -v perl >/dev/null 2>&1; then
|
||||||
|
_bd_timeout_backend=perl
|
||||||
|
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run pre-commit "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo >&2 "beads: hook 'pre-commit' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||||
|
if bd hooks run pre-commit "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
|
||||||
|
echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -eq 3 ]; then
|
||||||
|
echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||||
|
fi
|
||||||
|
# --- END BEADS INTEGRATION v1.3.2 ---
|
||||||
Executable
+59
@@ -0,0 +1,59 @@
|
|||||||
|
#!/usr/bin/env sh
|
||||||
|
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
|
||||||
|
# This section is managed by beads. Do not remove these markers.
|
||||||
|
if command -v bd >/dev/null 2>&1; then
|
||||||
|
export BD_GIT_HOOK=1
|
||||||
|
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||||
|
case "$_bd_timeout" in
|
||||||
|
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
|
||||||
|
*[1-9]*) _bd_timeout_invalid=0 ;;
|
||||||
|
*) _bd_timeout_invalid=1 ;;
|
||||||
|
esac
|
||||||
|
if [ "$_bd_timeout_invalid" -eq 1 ]; then
|
||||||
|
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
|
||||||
|
_bd_timeout=300
|
||||||
|
fi
|
||||||
|
_bd_timeout_backend=none
|
||||||
|
_bd_timeout_command=
|
||||||
|
for _bd_timeout_candidate in timeout gtimeout; do
|
||||||
|
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
|
||||||
|
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
|
||||||
|
case "$_bd_timeout_version" in
|
||||||
|
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
|
||||||
|
esac
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
if [ -n "$_bd_timeout_command" ]; then
|
||||||
|
_bd_timeout_backend=coreutils
|
||||||
|
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run pre-push "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
elif command -v perl >/dev/null 2>&1; then
|
||||||
|
_bd_timeout_backend=perl
|
||||||
|
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run pre-push "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo >&2 "beads: hook 'pre-push' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||||
|
if bd hooks run pre-push "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
|
||||||
|
echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -eq 3 ]; then
|
||||||
|
echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||||
|
fi
|
||||||
|
# --- END BEADS INTEGRATION v1.3.2 ---
|
||||||
Executable
+59
@@ -0,0 +1,59 @@
|
|||||||
|
#!/usr/bin/env sh
|
||||||
|
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
|
||||||
|
# This section is managed by beads. Do not remove these markers.
|
||||||
|
if command -v bd >/dev/null 2>&1; then
|
||||||
|
export BD_GIT_HOOK=1
|
||||||
|
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||||
|
case "$_bd_timeout" in
|
||||||
|
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
|
||||||
|
*[1-9]*) _bd_timeout_invalid=0 ;;
|
||||||
|
*) _bd_timeout_invalid=1 ;;
|
||||||
|
esac
|
||||||
|
if [ "$_bd_timeout_invalid" -eq 1 ]; then
|
||||||
|
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
|
||||||
|
_bd_timeout=300
|
||||||
|
fi
|
||||||
|
_bd_timeout_backend=none
|
||||||
|
_bd_timeout_command=
|
||||||
|
for _bd_timeout_candidate in timeout gtimeout; do
|
||||||
|
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
|
||||||
|
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
|
||||||
|
case "$_bd_timeout_version" in
|
||||||
|
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
|
||||||
|
esac
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
if [ -n "$_bd_timeout_command" ]; then
|
||||||
|
_bd_timeout_backend=coreutils
|
||||||
|
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run prepare-commit-msg "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
elif command -v perl >/dev/null 2>&1; then
|
||||||
|
_bd_timeout_backend=perl
|
||||||
|
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run prepare-commit-msg "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo >&2 "beads: hook 'prepare-commit-msg' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||||
|
if bd hooks run prepare-commit-msg "$@"; then
|
||||||
|
_bd_exit=0
|
||||||
|
else
|
||||||
|
_bd_exit=$?
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
|
||||||
|
echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -eq 3 ]; then
|
||||||
|
echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
|
||||||
|
_bd_exit=0
|
||||||
|
fi
|
||||||
|
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
|
||||||
|
fi
|
||||||
|
# --- END BEADS INTEGRATION v1.3.2 ---
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"SessionStart": [
|
||||||
|
{
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"command": "bd prime --hook-json",
|
||||||
|
"type": "command"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"matcher": ""
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
[features]
|
||||||
|
hooks = true
|
||||||
@@ -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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,20 @@
|
|||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"postToolUse": [
|
||||||
|
{
|
||||||
|
"command": "bd cursor-hook postToolUse"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"preCompact": [
|
||||||
|
{
|
||||||
|
"command": "bd cursor-hook preCompact"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"sessionStart": [
|
||||||
|
{
|
||||||
|
"command": "bd cursor-hook sessionStart"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"version": 1
|
||||||
|
}
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
alwaysApply: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- BEGIN BEADS INTEGRATION -->
|
||||||
|
<!-- Auto-generated by 'bd setup cursor'. Content between these markers is managed by bd. -->
|
||||||
|
|
||||||
|
# Beads Issue Tracking
|
||||||
|
|
||||||
|
This project uses [Beads (bd)](https://github.com/gastownhall/beads) for issue tracking.
|
||||||
|
|
||||||
|
## Core Rules
|
||||||
|
|
||||||
|
- Track ALL work in bd (never use markdown TODOs or comment-based task lists)
|
||||||
|
- Use `bd ready` to find available work
|
||||||
|
- Use `bd create` to track new issues/tasks/bugs
|
||||||
|
- Treat commit, push, and Dolt remote sync as policy-controlled handoff actions
|
||||||
|
- Run `bd prime` for complete workflow context (SSOT for operational commands)
|
||||||
|
- Default to conservative git authority: report status and proposed commands unless the user, orchestrator, or repository profile explicitly authorizes commit/sync/push
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bd prime # Load complete workflow context (SSOT)
|
||||||
|
bd ready # Show issues ready to work (no blockers)
|
||||||
|
bd list --status=open # List all open issues
|
||||||
|
bd create "title" -t task -p 2 # Create new issue
|
||||||
|
bd update <id> --claim # Claim work atomically
|
||||||
|
bd unclaim <id> # Release stuck issue (agent crashed)
|
||||||
|
bd close <id> # Mark complete
|
||||||
|
bd dep add <issue> <depends-on> # Add dependency
|
||||||
|
bd dolt push # Sync with remote when authorized
|
||||||
|
```
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
1. Check for ready work: `bd ready`
|
||||||
|
2. Claim an issue atomically: `bd update <id> --claim`
|
||||||
|
3. Do the work
|
||||||
|
4. Mark complete: `bd close <id>`
|
||||||
|
5. Handoff: report changed files, validation, issue status, and any proposed commit/sync/push commands
|
||||||
|
|
||||||
|
## Issue Types
|
||||||
|
|
||||||
|
- `bug` - Something broken
|
||||||
|
- `feature` - New functionality
|
||||||
|
- `task` - Work item (tests, docs, refactoring)
|
||||||
|
- `epic` - Large feature with subtasks
|
||||||
|
- `chore` - Maintenance (dependencies, tooling)
|
||||||
|
|
||||||
|
## Priorities
|
||||||
|
|
||||||
|
- `0` - Critical (security, data loss, broken builds)
|
||||||
|
- `1` - High (major features, important bugs)
|
||||||
|
- `2` - Medium (default, nice-to-have)
|
||||||
|
- `3` - Low (polish, optimization)
|
||||||
|
- `4` - Backlog (future ideas)
|
||||||
|
|
||||||
|
## Context Loading
|
||||||
|
|
||||||
|
Run `bd prime` to get complete workflow documentation in AI-optimized format.
|
||||||
|
`bd prime` is the single source of truth for operational commands and session workflow.
|
||||||
|
|
||||||
|
For detailed docs: see AGENTS.md, the beads quickstart
|
||||||
|
(https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md), or run `bd --help`
|
||||||
|
|
||||||
|
<!-- END BEADS INTEGRATION -->
|
||||||
@@ -25,3 +25,7 @@ coverage.*
|
|||||||
# Local env overrides (never commit)
|
# Local env overrides (never commit)
|
||||||
.env
|
.env
|
||||||
.env.local
|
.env.local
|
||||||
|
|
||||||
|
# Beads / Dolt files (added by bd init)
|
||||||
|
.beads/proxieddb/
|
||||||
|
*.gate.lock*
|
||||||
@@ -0,0 +1,128 @@
|
|||||||
|
# Agent Instructions
|
||||||
|
|
||||||
|
This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
|
||||||
|
|
||||||
|
> **Architecture in one line:** Issues live in a local Dolt database
|
||||||
|
> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a
|
||||||
|
> git-compatible protocol), stored under `refs/dolt/data` on your git
|
||||||
|
> remote — separate from `refs/heads/*` where your code lives.
|
||||||
|
> `.beads/issues.jsonl` is a passive export, not the wire protocol.
|
||||||
|
>
|
||||||
|
> See [sync-concepts](https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md)
|
||||||
|
> for the one-screen overview and anti-patterns (don't treat JSONL as the
|
||||||
|
> source of truth; don't `bd import` during normal operation; don't
|
||||||
|
> reach for third-party Dolt hosting before trying the default).
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bd ready # Find available work
|
||||||
|
bd show <id> # View issue details
|
||||||
|
bd update <id> --claim # Claim work atomically
|
||||||
|
bd close <id> # Complete work
|
||||||
|
bd dolt push # Push beads data to remote
|
||||||
|
```
|
||||||
|
|
||||||
|
## Non-Interactive Shell Commands
|
||||||
|
|
||||||
|
**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
|
||||||
|
|
||||||
|
Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
|
||||||
|
|
||||||
|
**Use these forms instead:**
|
||||||
|
```bash
|
||||||
|
# Force overwrite without prompting
|
||||||
|
cp -f source dest # NOT: cp source dest
|
||||||
|
mv -f source dest # NOT: mv source dest
|
||||||
|
rm -f file # NOT: rm file
|
||||||
|
|
||||||
|
# For recursive operations
|
||||||
|
rm -rf directory # NOT: rm -r directory
|
||||||
|
cp -rf source dest # NOT: cp -r source dest
|
||||||
|
```
|
||||||
|
|
||||||
|
**Other commands that may prompt:**
|
||||||
|
- `scp` - use `-o BatchMode=yes` for non-interactive
|
||||||
|
- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
|
||||||
|
- `apt-get` - use `-y` flag
|
||||||
|
- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
|
||||||
|
|
||||||
|
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:46cd31e7 -->
|
||||||
|
## 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 <id> # View issue details
|
||||||
|
bd update <id> --claim # Claim work
|
||||||
|
bd close <id> # Complete work
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rules
|
||||||
|
|
||||||
|
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
|
||||||
|
- Run `bd prime` for detailed command reference and session close protocol
|
||||||
|
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
|
||||||
|
|
||||||
|
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
|
||||||
|
|
||||||
|
## Agent Context Profiles
|
||||||
|
|
||||||
|
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
|
||||||
|
|
||||||
|
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
|
||||||
|
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
|
||||||
|
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
|
||||||
|
|
||||||
|
## Session Completion
|
||||||
|
|
||||||
|
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
|
||||||
|
|
||||||
|
1. **File issues for remaining work** - Create beads for anything that needs follow-up
|
||||||
|
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
||||||
|
3. **Update issue status** - Close finished work, update in-progress items
|
||||||
|
4. **Handle git/sync by active profile**:
|
||||||
|
```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.
|
||||||
|
<!-- END BEADS INTEGRATION -->
|
||||||
|
|
||||||
|
<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
|
||||||
|
## 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 <id> # View issue details
|
||||||
|
bd update <id> --claim # Claim work
|
||||||
|
bd close <id> # Complete work
|
||||||
|
bd prime # Refresh Beads context
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rules
|
||||||
|
|
||||||
|
- Use `bd` for all task tracking; do not create markdown TODO lists.
|
||||||
|
- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
|
||||||
|
- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.
|
||||||
|
|
||||||
|
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
|
||||||
|
<!-- END BEADS CODEX SETUP -->
|
||||||
@@ -0,0 +1,77 @@
|
|||||||
|
# Project Instructions for AI Agents
|
||||||
|
|
||||||
|
This file provides instructions and context for AI coding agents working on this project.
|
||||||
|
|
||||||
|
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:1105d646 -->
|
||||||
|
## 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 <id> # View issue details
|
||||||
|
bd update <id> --claim # Claim work
|
||||||
|
bd close <id> # Complete work
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rules
|
||||||
|
|
||||||
|
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
|
||||||
|
- Run `bd prime` for detailed command reference and session close protocol
|
||||||
|
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
|
||||||
|
|
||||||
|
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
|
||||||
|
|
||||||
|
## Agent Context Profiles
|
||||||
|
|
||||||
|
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
|
||||||
|
|
||||||
|
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
|
||||||
|
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
|
||||||
|
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
|
||||||
|
|
||||||
|
## Session Completion
|
||||||
|
|
||||||
|
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
|
||||||
|
|
||||||
|
1. **File issues for remaining work** - Create beads for anything that needs follow-up
|
||||||
|
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
||||||
|
3. **Update issue status** - Close finished work, update in-progress items
|
||||||
|
4. **Handle git/sync by active profile**:
|
||||||
|
```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
|
||||||
|
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.
|
||||||
|
<!-- END BEADS INTEGRATION -->
|
||||||
|
|
||||||
|
|
||||||
|
## Build & Test
|
||||||
|
|
||||||
|
_Add your build and test commands here_
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Example:
|
||||||
|
# npm install
|
||||||
|
# npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
_Add a brief overview of your project architecture_
|
||||||
|
|
||||||
|
## Conventions & Patterns
|
||||||
|
|
||||||
|
_Add your project-specific conventions here_
|
||||||
Reference in new issue
Block a user