diff --git a/.claude/.gitignore b/.claude/.gitignore new file mode 100644 index 0000000..d884526 --- /dev/null +++ b/.claude/.gitignore @@ -0,0 +1,2 @@ +# Backup files +*.bak diff --git a/.claude/scripts/tbd-session.sh b/.claude/scripts/tbd-session.sh new file mode 100755 index 0000000..ab249be --- /dev/null +++ b/.claude/scripts/tbd-session.sh @@ -0,0 +1,77 @@ +#!/bin/bash +# Ensure tbd CLI is installed and run tbd prime for Claude Code sessions +# Installed by: tbd setup --auto +# This script runs on SessionStart and PreCompact + +# Get npm global bin directory (if npm is available) +NPM_GLOBAL_BIN="" +if command -v npm &> /dev/null; then + NPM_PREFIX=$(npm config get prefix 2>/dev/null) + if [ -n "$NPM_PREFIX" ] && [ -d "$NPM_PREFIX/bin" ]; then + NPM_GLOBAL_BIN="$NPM_PREFIX/bin" + fi +fi + +# Add common binary locations to PATH (persists for entire script) +# Include npm global bin if found +export PATH="$NPM_GLOBAL_BIN:$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH" + +# Function to ensure tbd is available +ensure_tbd() { + # Check if tbd is already installed + if command -v tbd &> /dev/null; then + return 0 + fi + + echo "[tbd] CLI not found, installing..." + + # Try npm first (most common for Node.js tools) + if command -v npm &> /dev/null; then + echo "[tbd] Installing via npm..." + npm install -g get-tbd 2>/dev/null || { + # If global install fails (permissions), try local install + echo "[tbd] Global npm install failed, trying user install..." + mkdir -p ~/.local/bin + npm install --prefix ~/.local get-tbd + # Create symlink if needed + if [ -f ~/.local/node_modules/.bin/tbd ]; then + ln -sf ~/.local/node_modules/.bin/tbd ~/.local/bin/tbd + fi + } + elif command -v pnpm &> /dev/null; then + echo "[tbd] Installing via pnpm..." + pnpm add -g get-tbd + elif command -v yarn &> /dev/null; then + echo "[tbd] Installing via yarn..." + yarn global add get-tbd + else + echo "[tbd] ERROR: No package manager found (npm, pnpm, or yarn required)" + echo "[tbd] Please install Node.js and npm, then run: npm install -g get-tbd" + return 1 + fi + + # Verify installation + if command -v tbd &> /dev/null; then + echo "[tbd] Successfully installed to $(which tbd)" + return 0 + else + echo "[tbd] WARNING: tbd installed but not found in PATH" + echo "[tbd] Checking common locations..." + # Try to find and add to path (include npm global bin) + for dir in "$NPM_GLOBAL_BIN" ~/.local/bin ~/.local/node_modules/.bin /usr/local/bin; do + if [ -n "$dir" ] && [ -x "$dir/tbd" ]; then + export PATH="$dir:$PATH" + echo "[tbd] Found at $dir/tbd" + return 0 + fi + done + echo "[tbd] Could not locate tbd after installation" + return 1 + fi +} + +# Main +ensure_tbd || exit 1 + +# Run tbd prime with any passed arguments (e.g., --brief for PreCompact) +tbd prime "$@" diff --git a/.claude/settings.json b/.claude/settings.json index f3bfe80..2e33638 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -10,6 +10,15 @@ "timeout": 120 } ] + }, + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bash .claude/scripts/tbd-session.sh" + } + ] } ], "PostToolUse": [ @@ -22,6 +31,17 @@ } ] } + ], + "PreCompact": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bash .claude/scripts/tbd-session.sh --brief" + } + ] + } ] } } diff --git a/.claude/skills/tbd/SKILL.md b/.claude/skills/tbd/SKILL.md index 91441f8..38f184e 100644 --- a/.claude/skills/tbd/SKILL.md +++ b/.claude/skills/tbd/SKILL.md @@ -1,128 +1,254 @@ --- -name: tbd -description: Lightweight, git-native issue tracking (aka beads) for AI agents. Use for creating, planning, updating, and tracking issues with dependencies. Invoke when user mentions tbd, beads, to-do lists, planning, tracking tasks, issues, or bugs. allowed-tools: Bash(tbd:*), Read, Write +description: |- + Git-native issue tracking (beads), coding guidelines, knowledge injection, and spec-driven planning for AI agents. Drop-in replacement for bd/Beads with simpler architecture. + Use for: tracking issues/beads with dependencies, creating bugs/features/tasks, planning specs, implementing features from specs, code reviews, committing code, creating PRs, loading coding guidelines (TypeScript, Python, TDD, golden testing, Convex, monorepo patterns), code cleanup, research briefs, architecture docs, agent handoffs, and checking out third-party library source code. + Invoke when user mentions: tbd, beads, bd, shortcuts, issues, bugs, tasks, features, epics, todo, tracking, specs, planning, implementation, validation, guidelines, templates, commit, PR, pull request, code review, testing, TDD, test-driven, golden testing, snapshot testing, TypeScript, Python, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, checkout library, source code review, or any workflow shortcut. +name: tbd --- -# tbd Workflow - -`tbd` provides lightweight, git-native task and issue tracking using beads, which are -just lightweight issues managed from the CLI. + -> **Context Recovery**: Run `tbd prime` after compaction, clear, or new session. -> Hooks auto-call this in Claude Code when .tbd/ detected. +--- +title: tbd Workflow +description: Full tbd workflow guide for agents +--- +**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.** -# SESSION CLOSING PROTOCOL +1. **Beads**: Git-native issue tracking (tasks, bugs, features). + Never lose work across sessions. + Drop-in replacement for `bd`. +2. **Spec-Driven Workflows**: Plan features → break into beads → implement + systematically. +3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD, + testing, Convex, monorepos) available on demand. +4. **Shortcuts**: Reusable instruction templates for common workflows (code review, + commits, PRs, cleanup, handoffs). -**CRITICAL**: Before saying “done” or “complete”, you MUST run this checklist: +## Installation -``` -[ ] 1. Stage and commit: git add + git commit -[ ] 2. Push to remote: git push -[ ] 3. Start CI watch (BLOCKS until done): gh pr checks --watch 2>&1 -[ ] 4. While CI runs: tbd close/update for issues worked on -[ ] 5. While CI runs: tbd sync -[ ] 6. Return to step 3 and CONFIRM CI passed -[ ] 7. If CI failed: fix, re-push, restart from step 3 +```bash +npm install -g get-tbd@latest +tbd setup --auto --prefix= # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it) +tbd setup --auto # Existing tbd project (prefix already set) +tbd setup --from-beads # Migration from .beads/ if `bd` has been used ``` -## NON-NEGOTIABLE Requirements +## Routine Commands -### CI: Wait for `--watch` to finish +```bash +tbd --help # Command reference +tbd status # Status +tbd doctor # If there are problems -The `--watch` flag blocks until ALL checks complete. -Do NOT see “passing” in early output and move on—wait for the **final summary** showing -all checks passed. +tbd setup --auto # Run any time to refresh setup +tbd prime # Restore full context on tbd after compaction +``` -### tbd: Update issues and sync +## CRITICAL: You Operate tbd — The User Doesn’t + +**You are the tbd operator:** Users talk naturally; you translate their requests to tbd +actions. DO NOT tell users to run tbd commands. +That’s your job. + +- **WRONG**: "Run `tbd create` to track this bug" + +- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)* + +**Welcoming a user:** When users ask “what is tbd?” +or want help → run `tbd shortcut welcome-user` + +## User Request → Agent Action + +| User Says | You (the Agent) Run | +| --- | --- | +| **Issues/Beads** | | +| "There's a bug where ..." | `tbd create "..." --type=bug` | +| "Create a task/feature for ..." | `tbd create "..." --type=task` or `--type=feature` | +| "Let's work on issues/beads" | `tbd ready` | +| "Show me issue X" | `tbd show ` | +| "Close this issue" | `tbd close ` | +| "Search issues for X" | `tbd search "X"` | +| "Add label X to issue" | `tbd label add