fall-out-bug · fall-out-bug · May 8, 2026
diff --git a/.claude/hooks/PostToolUse.sh b/.claude/hooks/PostToolUse.sh
@@ -1,10 +1,25 @@
 #!/bin/bash
-# PostToolUse hook - runs after any tool use
-echo "🔔 PostToolUse hook triggered" >> /tmp/hook_debug.log
-date >> /tmp/hook_debug.log
-
-# Sync Beads after git commit
-if [[ "$@" == *"git commit"* ]]; then
-  echo "📦 Syncing Beads after commit..." >> /tmp/hook_debug.log
-  bd sync || true
+# PostToolUse hook - runs after any tool use.
+#
+# Claude Code passes tool-use metadata via argv; we detect git-commit calls
+# and sync the beads transport so the dolt mirror stays fresh.
+set -euo pipefail
+
+# Resolve repo root (two levels up from .claude/hooks/) so the hook works
+# regardless of the caller's cwd.
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${HOOK_DIR}/../.." && pwd)"
+
+LOG_FILE="${REPO_ROOT}/.claude/hooks/PostToolUse.log"
+mkdir -p "$(dirname "${LOG_FILE}")"
+
+{
+  echo "🔔 PostToolUse hook triggered"
+  date
+} >> "${LOG_FILE}"
+
+# Sync beads after git commit (use $* so word-array joins cleanly for glob match).
+if [[ "$*" == *"git commit"* ]]; then
+  echo "📦 Syncing Beads after commit..." >> "${LOG_FILE}"
+  "${REPO_ROOT}/scripts/beads_transport.sh" export >> "${LOG_FILE}" 2>&1 || true
 fi
diff --git a/.claude/patterns/git-safety.md b/.claude/patterns/git-safety.md
@@ -29,10 +29,9 @@ git stash list
 ## Branch Convention
 
 ```
-feature/<feature-id>-description    # New feature
-bugfix/sdp-xxx-description  # Bug fix (P1/P2)
-hotfix/sdp-xxx-description  # Emergency fix (P0)
-docs/description            # Documentation only
+feature/FXXX-short-name     # New feature (e.g. feature/F004-sequential-reconciler)
+fix/FXXX-description        # Bug fix within a feature
+docs/topic                  # Documentation only
 ```
 
 ## Commit Convention
@@ -47,8 +46,7 @@ refactor: extract common validation logic
 
 ## PR Rules
 
-- Target `dev` branch (NOT `main`) for features
-- Target `main` only for releases
+- Target `main` branch for all PRs
 - Include test plan in PR body
 - Wait for CI before merge
 

diff --git a/.claude/patterns/session-complete.md b/.claude/patterns/session-complete.md
@@ -39,7 +39,7 @@ git commit -m "type: description"
 bd close <issue-id>
 
 # Sync with remote
-bd sync
+scripts/beads_transport.sh export
 ```
 
 ### 4. Push
@@ -71,7 +71,7 @@ git fetch --prune
 | Mistake | Consequence | Fix |
 |---------|-------------|-----|
 | Forgot `bd close` | Issue stays open | Run `bd close` |
-| Forgot `bd sync` | Remote out of sync | Run `bd sync` |
+| Forgot `scripts/beads_transport.sh export` | Remote out of sync | Run `scripts/beads_transport.sh export` |
 | Forgot `git push` | Work not saved | Run `git push` |
 | Forgot `git status` check | Unknown state | Always verify |
 

diff --git a/.claude/patterns/tdd.md b/.claude/patterns/tdd.md
@@ -61,4 +61,4 @@ go tool cover -func=coverage.out | grep total
 
 - `@build` - Executes workstream with TDD enforcement
 - `@bugfix` - Bug fixes follow TDD
-- `.claude/skills/tdd.md` - Full skill definition
+- `prompts/skills/tdd/SKILL.md` - Full skill definition
diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md
@@ -0,0 +1,77 @@
+# SDP Codex Instructions
+
+You are operating in a repository that uses Spec-Driven Protocol (SDP).
+SDP is a structured workflow for AI-assisted software development:
+explicit scope, workstreams, quality gates, review, and evidence before ship.
+
+## Quick Start
+
+Read these in order:
+
+1. `AGENTS.md`
+2. `docs/reference/project-map.md`
+3. `prompts/commands.yml`
+4. `docs/reference/FALLBACK_MODE.md` if your Codex runtime cannot spawn subagents
+
+## Main Commands
+
+### Planning and analysis
+
+- `@vision` — strategic product shaping
+- `@feature` — feature planning
+- `@idea` — requirements gathering
+- `@design` — workstream design
+- `@understand`, `@scout`, `@architect`, `@reality`, `@metrics` — repo analysis
+
+### Execution
+
+- `@build` — execute one scoped workstream
+- `@oneshot` — end-to-end feature execution
+- `@operate` / `@deploy` — release and operations work
+
+### Bugs and review
+
+- `@fix`, `@bugfix`, `@hotfix`, `@issue`, `@debug`
+- `@review`, `@verify-workstream`, `@ci-triage`
+
+### Coordination
+
+- `@llm-council` — multi-model synthesis for hard decisions
+- `@git-worktree` — safe parallel work setup
+- `@parallel-dispatch` — parallel subagent delegation
+
+## Quality Gates
+
+Run the relevant gates before claiming a task is complete:
+
+| Language | Build | Test | Lint |
+|---|---|---|---|
+| Go | `go build ./...` | `go test ./...` | `go vet ./...` |
+| Python | `pip install .` | `pytest` | `ruff check .` |
+| Node.js | `npm run build` | `npm test` | `npm run lint` |
+| Rust | `cargo build` | `cargo test` | `cargo clippy` |
+| Java | `mvn compile` | `mvn test` | `mvn checkstyle:check` |
+
+## Operating Rules
+
+- No code change without a clear scope.
+- Prefer TDD for behavior changes.
+- Do not hide broken assumptions. Call them out and resolve them.
+- Use `prompts/commands.yml` as the canonical command mapping.
+- Use `prompts/skills/` as the canonical skill source.
+
+## Landing The Plane
+
+Before ending a session:
+
+1. Run the relevant quality gates.
+2. Verify acceptance criteria with evidence.
+3. Update docs if behavior or UX changed.
+4. Commit and push from a harness that has git access if your Codex sandbox does not.
+
+## Related Files
+
+- `prompts/commands.yml`
+- `prompts/skills/`
+- `prompts/agents/`
+- `docs/reference/FALLBACK_MODE.md`
diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md
@@ -1,47 +1,29 @@
-# SDP — Codex setup
+# SDP — Codex Setup
 
-This project uses [Spec-Driven Protocol (SDP)](https://github.com/fall-out-bug/sdp). Codex reads this file for setup.
+This repository ships Codex-oriented guidance and compatibility files.
 
-## Project-level skills
+## Start Here
 
-Project skills source of truth lives in `prompts/skills/` (this repo). Tool folders (`.codex`, `.claude`, `.cursor`, `.opencode`) use symlinks to this source.
+1. Read [`AGENTS.md`](../AGENTS.md)
+2. Read [`.codex/AGENTS.md`](AGENTS.md) in this directory for Codex-specific guidance
+3. Use [`prompts/commands.yml`](../prompts/commands.yml) as the canonical command map
 
-## Quick start
+## Canonical Prompt Sources
 
-1. Install SDP into your project with Codex integration:
-   ```bash
-   SDP_IDE=codex curl -sSL https://raw.githubusercontent.com/fall-out-bug/sdp/main/install.sh | sh
-   ```
-2. Run project init:
-   ```bash
-   sdp init --auto
-   ```
-3. Use `@build 00-XXX-YY` or `sdp plan`, `sdp apply`, `sdp log trace` per [CLAUDE.md](../CLAUDE.md).
+- `prompts/commands/`
+- `prompts/skills/`
+- `prompts/agents/`
 
-If you want the CLI only, use:
+Tool folders such as `.codex/`, `.cursor/`, and `.opencode/` are harness entry
+points and lightweight adapters. Prompt logic belongs in `prompts/`.
 
-```bash
-curl -sSL https://raw.githubusercontent.com/fall-out-bug/sdp/main/install.sh | sh -s -- --binary-only
-```
-
-## Directory layout
+## Typical Flow
 
+```text
+@feature "description"
+@build 00-XXX-YY
+@review FXXX
 ```
-.codex/
-├── INSTALL.md   # This file (read by Codex)
-├── agents/      # Project-level agent symlink
-└── skills/
-    ├── README.md
-    └── sdp/     # Project-level skills sourced from prompts/skills
-
-~/.codex/
-└── skills/      # User-level skills (persistent)
-```
-
-## Beads (optional)
-
-If Beads is installed (`bd --version`), use `bd ready`, `bd update`, `bd close` for task tracking. See [AGENTS.md](../AGENTS.md).
-
-## Updates
 
-Rerun the same installer command to refresh the vendored `sdp/` checkout and managed Codex links after upstream changes.
+If your Codex runtime cannot spawn subagents, use the manual workflows in
+[`docs/reference/FALLBACK_MODE.md`](../docs/reference/FALLBACK_MODE.md).
diff --git a/.codex/skills/README.md b/.codex/skills/README.md
@@ -1,9 +1,17 @@
-# Project-level skills (Codex)
+# Project-Level Skills (Codex)
 
-SDP project skills are defined in `prompts/skills/` (source of truth). This folder contains symlinks for Codex compatibility.
+SDP project skills are defined in `prompts/skills/`.
 
-- **@build** — Execute workstream (TDD, guard). See `prompts/skills/build/SKILL.md`.
-- **@design** — Plan workstreams. See `prompts/skills/design/SKILL.md`.
-- **@review** — Multi-agent quality review. See `prompts/skills/review/SKILL.md`.
+This directory exists only for Codex-facing compatibility and discovery.
+The source of truth is still:
 
-Full list: `prompts/skills/` (build, design, feature, guard, oneshot, review, tdd, etc.).
+- `prompts/skills/`
+- `prompts/commands.yml`
+- `prompts/agents/`
+
+Start with:
+
+- `@feature`
+- `@build`
+- `@review`
+- `@fix`
diff --git a/.cursor/README.md b/.cursor/README.md
@@ -1,27 +1,43 @@
 # Cursor Integration
 
-**Canonical skill source:** `../prompts/skills/`
+**Primary context source:** [`.cursorrules`](../.cursorrules)
 
-All SDP command prompts are unified in `prompts/skills/` with symlink adapters in tool folders.
+Cursor reads `.cursorrules` automatically at the project root. Keep that file
+small and operational: role, decision tree, quality gates, and where to find
+canonical prompts.
+
+## Canonical Prompt Source
+
+- Commands: `../prompts/commands/`
+- Skills: `../prompts/skills/`
+- Agents: `../prompts/agents/`
+- Command mapping: `../prompts/commands.yml`
+
+Edit canonical prompt sources only. Do not fork Cursor-only copies of prompt
+logic unless the harness format itself requires it.
 
 ## Usage
 
-Use `@` prefix to invoke skills:
-
-```bash
-@feature "description"  # Unified entry point
-@idea "description"     # Requirements gathering
-@design {id}            # Plan workstreams
-@build {ws-id}          # Execute workstream
-@review {feature}       # Quality review
-@deploy {feature}       # Production deployment
-@debug "issue"          # Systematic debugging
-@hotfix "critical"      # Emergency fix
-@bugfix "issue"         # Quality fix
+Use `@` commands for the main SDP flows:
+
+```text
+@feature "description"
+@idea "description"
+@design 00-XXX-YY
+@build 00-XXX-YY
+@review FXXX
+@fix "regression description"
+@operate "deploy or release task"
 ```
 
+## Fallback Mode
+
+If your Cursor runtime cannot spawn subagents, use the manual checklists in
+[`docs/reference/FALLBACK_MODE.md`](../docs/reference/FALLBACK_MODE.md).
+
 ## See Also
 
-- [CLAUDE.md](../CLAUDE.md) - Full protocol
-- [prompts/skills/](../prompts/skills/) - Canonical skill definitions
-- [.claude/skills/](../.claude/skills/) - Claude compatibility symlink
+- [`AGENTS.md`](../AGENTS.md)
+- [`docs/reference/project-map.md`](../docs/reference/project-map.md)
+- [`docs/reference/FALLBACK_MODE.md`](../docs/reference/FALLBACK_MODE.md)
+- [`prompts/commands.yml`](../prompts/commands.yml)
diff --git a/.cursor/worktrees.json b/.cursor/worktrees.json
@@ -1,11 +1,9 @@
 {
   "setup_commands_unix": [
-    "cd sdp-plugin && go mod download 2>/dev/null || echo 'Go modules not configured'",
-    "echo '✅ Worktree ready (Go project)'"
+    "echo 'Worktree ready (SDP project)'"
   ],
   "setup_commands_windows": [
-    "cd sdp-plugin && go mod download 2>nul || echo Go modules not configured",
-    "echo Worktree ready (Go project)"
+    "echo Worktree ready (SDP project)"
   ],
-  "description": "Template for SDP project worktree setup. Go-first project."
+  "description": "Template for SDP project worktree setup."
 }