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/hooks/tbd-closing-reminder.sh b/.claude/hooks/tbd-closing-reminder.sh new file mode 100755 index 0000000..a6056b0 --- /dev/null +++ b/.claude/hooks/tbd-closing-reminder.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# Remind about close protocol after git push +# Installed by: tbd setup claude + +input=$(cat) +command=$(echo "$input" | jq -r '.tool_input.command // empty') + +# Check if this is a git push command and .tbd exists +if [[ "$command" == git\ push* ]] || [[ "$command" == *"&& git push"* ]] || [[ "$command" == *"; git push"* ]]; then + if [ -d ".tbd" ]; then + tbd closing + fi +fi + +exit 0 diff --git a/.claude/scripts/ensure-gh-cli.sh b/.claude/scripts/ensure-gh-cli.sh new file mode 100755 index 0000000..aac98e4 --- /dev/null +++ b/.claude/scripts/ensure-gh-cli.sh @@ -0,0 +1,88 @@ +#!/bin/bash +# Automated GitHub CLI setup for Claude Code sessions +# This script runs on SessionStart to ensure gh CLI is available and authenticated + +set -e + +# Add common binary locations to PATH +export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH" + +# Check if gh is already installed +if command -v gh &> /dev/null; then + echo "[gh] CLI found at $(which gh)" +else + echo "[gh] CLI not found, installing..." + + # Detect platform + OS=$(uname -s | tr '[:upper:]' '[:lower:]') + ARCH=$(uname -m) + [ "$ARCH" = "x86_64" ] && ARCH="amd64" + [ "$ARCH" = "aarch64" ] && ARCH="arm64" + + echo "[gh] Detected platform: ${OS}_${ARCH}" + + # Get latest version from GitHub API (with fallback) + GH_VERSION=$(curl -fsSL https://api.github.com/repos/cli/cli/releases/latest 2>/dev/null \ + | grep -o '"tag_name": *"v[^"]*"' | head -1 | sed 's/.*"v\([^"]*\)".*/\1/') + + # Fallback version if API fails + GH_VERSION=${GH_VERSION:-2.83.1} + + echo "[gh] Version: ${GH_VERSION}" + + # Build download URL based on platform + if [ "$OS" = "darwin" ]; then + DOWNLOAD_URL="https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_macOS_${ARCH}.zip" + ARCHIVE_EXT="zip" + else + DOWNLOAD_URL="https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_${OS}_${ARCH}.tar.gz" + ARCHIVE_EXT="tar.gz" + fi + + echo "[gh] Downloading from ${DOWNLOAD_URL}..." + + # Download + curl -fsSL -o "/tmp/gh.${ARCHIVE_EXT}" "$DOWNLOAD_URL" + + # Extract based on archive type + if [ "$ARCHIVE_EXT" = "zip" ]; then + unzip -q "/tmp/gh.zip" -d /tmp + EXTRACT_DIR="/tmp/gh_${GH_VERSION}_macOS_${ARCH}" + else + tar -xzf "/tmp/gh.tar.gz" -C /tmp + EXTRACT_DIR="/tmp/gh_${GH_VERSION}_${OS}_${ARCH}" + fi + + # Install to ~/.local/bin (works in cloud and local) + mkdir -p ~/.local/bin + cp "${EXTRACT_DIR}/bin/gh" ~/.local/bin/gh + chmod +x ~/.local/bin/gh + + # Clean up + rm -rf "${EXTRACT_DIR}" "/tmp/gh.${ARCHIVE_EXT}" + + echo "[gh] Installed to ~/.local/bin/gh" +fi + +# Verify gh is now in PATH +if ! command -v gh &> /dev/null; then + echo "[gh] ERROR: gh CLI still not found in PATH after installation" + echo "[gh] Ensure ~/.local/bin is in your PATH" + exit 1 +fi + +# Check authentication status +if [ -n "$GH_TOKEN" ]; then + # GH_TOKEN is set, verify it works + if gh auth status &> /dev/null; then + echo "[gh] Authenticated successfully" + else + echo "[gh] WARNING: GH_TOKEN is set but authentication check failed" + echo "[gh] Token may be invalid or expired" + fi +else + echo "[gh] NOTE: GH_TOKEN not set - some operations may require authentication" + echo "[gh] See: docs/general/agent-setup/github-cli-setup.md" +fi + +exit 0 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 new file mode 100644 index 0000000..31d9eef --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,47 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bash .claude/scripts/tbd-session.sh" + } + ] + }, + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bash .claude/scripts/ensure-gh-cli.sh", + "timeout": 120 + } + ] + } + ], + "PreCompact": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bash .claude/scripts/tbd-session.sh --brief" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tbd-closing-reminder.sh" + } + ] + } + ] + } +} diff --git a/.claude/skills/tbd/SKILL.md b/.claude/skills/tbd/SKILL.md new file mode 100644 index 0000000..f7ea19d --- /dev/null +++ b/.claude/skills/tbd/SKILL.md @@ -0,0 +1,259 @@ +--- +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 +--- + + +--- +title: tbd Workflow +description: Full tbd workflow guide for agents +--- +**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.** + +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). + +## Installation + +```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 +``` + +## Routine Commands + +```bash +tbd --help # Command reference +tbd status # Status +tbd doctor # If there are problems + +tbd setup --auto # Run any time to refresh setup +tbd prime # Restore full context on tbd after compaction +``` + +## 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