feat: add skills for various agents

.agents/skills/beads/SKILL.md

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

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

.claude/settings.json

@@ -1,8 +1,27 @@
 {
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      },
+      {
+        "hooks": [
+          {
+            "command": "bd prime --hook-json",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ]
+  },
   "permissions": {
-    "deny": [
-      "Write(./.beads/issues.jsonl)"
-    ],
     "allow": [
       "Bash(cargo build:*)",
       "Bash(cargo test:*)",
@@ -25,34 +44,9 @@
       "Bash(git branch:*)",
       "Bash(git fetch:*)",
       "Bash(git ls-remote:*)"
-    ]
-  },
-  "hooks": {
-    "PreCompact": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bd prime"
-          }
-        ]
-      }
     ],
-    "SessionStart": [
+    "deny": [
-      {
+      "Edit(./.beads/issues.jsonl)"
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
-          },
-          {
-            "type": "command",
-            "command": "bd prime"
-          }
-        ]
-      }
     ]
   }
-}
+}

.codex/config.toml

@@ -0,0 +1,2 @@
+[features]
+hooks = true

.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"
+          }
+        ]
+      }
+    ]
+  }
+}

AGENTS.md

@@ -272,3 +272,27 @@ bd close <id>         # Complete work
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
 <!-- 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 -->

CLAUDE.md

@@ -64,7 +64,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
 
-<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
+<!-- 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.
@@ -80,33 +80,42 @@ bd close <id>         # Complete work
 
 ### Rules
 
-- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists (the exception being that you must maintain context/design-principles.md and context/repo-map.md)
+- 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 (the exception being that you must maintain context/design-principles.md and context/repo-map.md)
+- 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
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
 
-**MANDATORY WORKFLOW:**
+1. **File issues for remaining work** - Create beads for anything that needs follow-up
-
-1. **File issues for remaining work** - Create issues 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. **PUSH TO REMOTE** - This is MANDATORY:
+4. **Handle git/sync by active profile**:
    ```bash
-   git merge origin/main
+   # 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
    bd dolt push
    git push
-   git status  # MUST show "up to date with origin"
+   git status
    ```
-5. **Clean up** - Clear stashes, prune remote branches
+5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
 
-**CRITICAL RULES:**
+**Critical rules:**
-- Work is NOT complete until `git push` succeeds
+- Explicit user or orchestrator instructions override this Beads block.
-- NEVER stop before pushing - that leaves work stranded locally
+- Do not commit or push without clear authority from the active profile or the current user request.
-- NEVER say "ready to push when you are" - YOU must push
+- If a required sync or push is blocked, stop and report the exact command and error.
-- If push fails, resolve and retry until it succeeds
 <!-- END BEADS INTEGRATION -->