get-tbd 0.1.8

package/dist/docs/install/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

package/dist/docs/shortcuts/standard/commit-code.md

@@ -0,0 +1,23 @@
+---
+title: Commit Code
+description: Run pre-commit checks, review changes, and commit code
+---
+Shortcut: Run Pre-Commit Rules, Review, and Commit
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Follow the `tbd shortcut precommit-process` steps to review and run pre-commit
+   checks.
+
+2. If there are issues, ask for guidance.
+   Otherwise, commit directly using the commit message format from
+   `tbd guidelines commit-conventions`. Do NOT ask the user for permission to commit
+   unless there are problems.
+
+3. If commit is successful and if there is a PR already filed, update the PR
+   description.

package/dist/docs/shortcuts/standard/create-or-update-pr-simple.md

@@ -0,0 +1,29 @@
+---
+title: Create or Update PR (Simple)
+description: Create or update a pull request with a concise summary
+---
+Shortcut: Create or Update PR (Simple)
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Check if a PR already exists for this branch using `gh pr view`. If it does, you’ll
+   be updating it. If not, you’ll create one.
+
+2. Review all commits on this branch since it diverged from main:
+   - Run `git log main..HEAD --oneline` to see commits
+   - Run `git diff main...HEAD` to see all changes
+
+3. Write a PR title and description:
+   - Title should be concise and describe the change (e.g., “Add user authentication”)
+   - Description should have a brief summary of what changed and why
+
+4. Create or update the PR:
+   - If creating: `gh pr create --title "..." --body "..."`
+   - If updating: `gh pr edit --title "..." --body "..."`
+
+5. Report the PR URL to the user.

package/dist/docs/shortcuts/standard/create-or-update-pr-with-validation-plan.md

@@ -0,0 +1,48 @@
+---
+title: Create or Update PR with Validation Plan
+description: Create or update a pull request with a detailed test/validation plan
+---
+Shortcut: Create or Update PR with Validation Plan
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Check if a PR already exists for this branch using `gh pr view`. If it does, you’ll
+   be updating it. If not, you’ll create one.
+
+2. Review all commits on this branch since it diverged from main:
+   - Run `git log main..HEAD --oneline` to see commits
+   - Run `git diff main...HEAD` to see all changes
+   - Review any related specs in docs/project/specs/active/
+
+3. Write a PR title and description with these sections:
+
+   ## Summary
+
+   Brief description of the changes (2-3 sentences).
+
+   ## Changes
+
+   Bulleted list of specific changes made.
+
+   ## Test Plan
+
+   Detailed validation checklist:
+   - [ ] Unit tests pass (`npm test`)
+   - [ ] Build succeeds (`npm run build`)
+   - [ ] Manual testing steps (list specific scenarios to test)
+   - [ ] Edge cases considered (list any)
+
+   ## Related Issues
+
+   Link any related tbd issues using their IDs.
+
+4. Create or update the PR:
+   - If creating: `gh pr create --title "..." --body "..."`
+   - If updating: `gh pr edit --title "..." --body "..."`
+
+5. Report the PR URL to the user and summarize the validation plan.

package/dist/docs/shortcuts/standard/implement-beads.md

@@ -0,0 +1,31 @@
+---
+title: Implement Beads
+description: Implement issues from a spec, following TDD and project rules
+---
+Shortcut: Implement Beads
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Run `tbd guidelines --list` to see available guidelines, then review relevant ones
+   for implementing this spec.
+   In particular run `tbd guidelines general-tdd-guidelines` to understand project and
+   testing rules.
+
+2. IMPORTANT: *Track all work with issues using tbd.* Use `tbd create` to create issues,
+   `tbd ready` to find work, and `tbd close` when done.
+
+3. Implement issues specified by the user, highest priority first.
+   If the user did not specify which issues, check all open issues with `tbd ready`.
+   Issues are usually linked to specs so be sure to find specs that are relevant (for
+   that issue or an umbrella issue) for each if possible and review those specs.
+   Follow all rules and workflows and follow `tbd shortcut precommit-process` to commit
+   code and commit or sync issue changes after each issue.
+
+4. Repeat this for all issues where you know how to fix them.
+   If unsure about an issue let the user know at the end of all work which issues had
+   problems.

package/dist/docs/shortcuts/standard/new-architecture-doc.md

@@ -0,0 +1,31 @@
+---
+title: New Architecture Doc
+description: Create an architecture document for a system or component design
+---
+Shortcut: New Architecture Doc
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Clarify the architecture scope with the user:
+   - What system or component are we designing?
+   - Is this a new design or documenting existing architecture?
+   - What level of detail is needed?
+
+2. Review existing architecture docs in docs/project/architecture/ if available.
+   Also review any related specs in docs/project/specs/active/.
+
+3. Create the architecture document using the template:
+   ```
+   tbd template architecture-doc > docs/project/architecture/arch-YYYY-MM-DD-component-name.md
+   ```
+   (Fill in the date and an appropriate component name.)
+
+4. If documenting existing architecture, review the codebase to ensure accuracy.
+   If designing new architecture, iterate with the user on the design.
+
+5. Summarize the architecture and ask the user to review.

package/dist/docs/shortcuts/standard/new-implementation-beads-from-spec.md

@@ -0,0 +1,28 @@
+---
+title: New Implementation Beads from Spec
+description: Create implementation issues (beads) from a feature planning spec
+---
+Shortcut: New Implementation Beads from Spec
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Make sure it’s clear what plan spec will be used for this implementation.
+   The user should provide it and you should find it in docs/project/specs/active/ with
+   a plan- prefix (e.g., plan-YYYY-MM-DD-\*.md).
+   If isn’t clear, stop and ask!
+
+2. Create a new top-level issue for this work using `tbd create`, referencing the spec.
+   Reference any other related specs or docs too.
+
+3. Then using all the context you now have, begin to plan the implementation step by
+   step, step by step, reviewing existing code carefully as you go and creating issues
+   with `tbd create`. Always double-check all referenced code fits with the spec code
+   you write. Be sure to track dependencies between issues correctly.
+
+4. Summarize what you have done and ask the user to review and if you should begin
+   implementation using `tbd shortcut implement-beads`.

package/dist/docs/shortcuts/standard/new-plan-spec.md

@@ -0,0 +1,49 @@
+---
+title: New Plan Spec
+description: Create a new feature planning specification document
+---
+Shortcut: New Plan Spec
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Review docs/project/specs/active/ to see the list of recent feature specs, feature
+   plans, and implementation spec docs.
+
+2. Create the spec file using the template:
+   ```
+   tbd template plan-spec > docs/project/specs/active/plan-YYYY-MM-DD-feature-name.md
+   ```
+   (Fill in the date and an appropriate feature name.)
+
+3. Begin to fill in the new feature plan doc based on the user’s instructions, stopping
+   and asking for clarifications as soon as you need them.
+
+   Rules:
+
+   - You may break work into a few phases (phases) if it helps with incremental testing.
+     But **use as few phases as possible.** If it is straightforward, use one phase.
+
+   - NEVER GIVE TIME FRAMES IN PLANS, like “4-6 hours” or “1 week”.
+     Work will be done in one day.
+
+4. After completing the spec, link issues to it using the `--spec` flag:
+   ```
+   tbd create "Implement feature X" --spec docs/project/specs/active/plan-YYYY-MM-DD-feature-name.md
+   ```
+   Or use just the filename for brevity:
+   ```
+   tbd create "Implement feature X" --spec plan-YYYY-MM-DD-feature-name.md
+   ```
+   You can also update an existing issue to link it to a spec:
+   ```
+   tbd update <id> --spec plan-YYYY-MM-DD-feature-name.md
+   ```
+   To clear a spec link: `tbd update <id> --spec ""`
+
+5. To list issues linked to a spec, use `tbd list --spec` (see `tbd list --help` for
+   details on filtering and path matching).

package/dist/docs/shortcuts/standard/new-research-brief.md

@@ -0,0 +1,30 @@
+---
+title: New Research Doc
+description: Create a research document for investigating a topic or technology
+---
+Shortcut: New Research Doc
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Clarify the research topic with the user:
+   - What question or problem are we investigating?
+   - What is the scope and depth needed?
+   - Are there specific technologies or approaches to evaluate?
+
+2. Review existing research in docs/project/research/ if available.
+
+3. Create the research document using the template:
+   ```
+   tbd template research-brief > docs/project/research/research-YYYY-MM-DD-topic.md
+   ```
+   (Fill in the date and an appropriate topic name.)
+
+4. Begin research, updating the document as you learn.
+   Ask the user for guidance when you need clarification or hit decision points.
+
+5. Summarize findings and ask the user to review.

package/dist/docs/shortcuts/standard/new-validation-plan.md

@@ -0,0 +1,51 @@
+---
+title: New Validation Plan
+description: Create a validation/test plan for a feature or change
+---
+Shortcut: New Validation Plan
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Identify the feature or change that needs a validation plan:
+   - Review the relevant spec in docs/project/specs/active/ if available
+   - Understand the scope of changes
+
+2. Create a validation plan with these sections:
+
+   ## Overview
+
+   Brief description of what’s being validated.
+
+   ## Automated Testing
+
+   - [ ] Unit tests cover new functionality
+   - [ ] Integration tests cover component interactions
+   - [ ] Edge cases have test coverage
+
+   ## Manual Testing Checklist
+
+   List specific scenarios to manually verify:
+   - [ ] Happy path scenarios
+   - [ ] Error handling scenarios
+   - [ ] Edge cases and boundary conditions
+
+   ## Performance Considerations
+
+   - [ ] No performance regressions
+   - [ ] Load testing if applicable
+
+   ## Rollback Plan
+
+   How to revert if issues are found in production.
+
+3. Ask the user where to save the validation plan:
+   - In the PR description (use `tbd shortcut create-or-update-pr-with-validation-plan`)
+   - As a separate document in docs/project/specs/active/
+   - Both
+
+4. Create the validation plan in the chosen location(s).

package/dist/docs/shortcuts/standard/precommit-process.md

@@ -0,0 +1,88 @@
+---
+title: Pre-Commit Process
+description: Full pre-commit checklist including spec sync, code review, and testing
+---
+Shortcut: Pre-Commit Process
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+This process must be followed before committing code!
+
+Create a to-do list with the following items then perform all of them:
+
+1. **Confirm spec is in sync:**
+
+   If the work has been done using a feature spec or bugfix spec (typically in
+   docs/project/specs/active/) review and make any updates to the spec to be sure it is
+   current with respect to the current code.
+
+   Add any status updates to the spec to include accomplished tasks and remaining tasks,
+   if any.
+
+2. **Code style enforcement:**
+
+   Before code is committed all changes must be reviewed and ensure they comply with the
+   coding rules. Run `tbd guidelines --list` to see available guidelines.
+
+3. **Code review:**
+
+   Read all changes and ensure they follow best practices for modern TypeScript.
+   Code should be clean, with brief and maintainable comments.
+
+   You must review all outstanding changes that are not committed in the current repo.
+
+   For background, read the project README.md and the package.json files.
+
+   Make a checklist for this review based on the following list, then go through the
+   checklist one step at a time.
+
+   - Step 3.1: Ensure code follows general rules:
+
+     - `tbd guidelines general-eng-assistant-rules`
+
+     - `tbd guidelines general-coding-rules`
+
+     - `tbd guidelines general-comment-rules`
+
+     - `tbd guidelines general-style-rules`
+
+     - `tbd guidelines general-testing-rules`
+
+   - Step 3.2: Ensure code follows language-specific rules:
+     - `tbd guidelines typescript-rules`
+
+   - Step 3.3: Ensure code follows framework-specific rules (if applicable):
+     - `tbd guidelines convex-rules`
+
+   - Step 3.4: Ensure code follows backward-compatibility rules:
+     - `tbd guidelines backward-compatibility-rules`
+
+4. **Unit testing and integration testing:**
+
+   BE SURE YOU RUN ALL TESTS (npm run precommit) as this includes codegen, formatting,
+   linting, unit tests and integration tests.
+
+   Read docs/development.md for additional background on test workflows.
+
+   After any significant changes, ALWAYS run the precommit check:
+
+   ```
+   npm run precommit  # Runs: codegen, format, lint, test:unit, test:integration
+   ```
+
+   This will generate code, auto-format, lint, and run unit and integration tests.
+
+   Then YOU MUST FIX all issues found.
+
+5. **Review spec once more:**
+
+   Make any updates to the spec based on the fixes or issues discovered during review
+   and testing.
+
+6. **Summarize and commit:** Summarize what was done and write a clear commit message
+   following `tbd guidelines commit-conventions` (use conventional commits format with
+   appropriate type). If all checks pass, commit directly.
+   Only ask the user if there are unresolved issues or problems.

package/dist/docs/shortcuts/standard/review-code-python.md

@@ -0,0 +1,47 @@
+---
+title: Review Code (Python)
+description: Perform a code review for Python code following best practices
+---
+Shortcut: Review Code (Python)
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Identify the code to review:
+   - If changes are staged, review `git diff --cached`
+   - If changes are unstaged, review `git diff`
+   - Or review specific files the user mentions
+
+2. Review the Python rules and guidelines:
+   - Run `tbd guidelines python-rules` for language-specific rules
+   - Run `tbd guidelines general-coding-rules` for general rules
+
+3. Check for common Python issues:
+   - [ ] Type hints are used for function signatures
+   - [ ] Docstrings follow conventions (Google/NumPy style)
+   - [ ] Exception handling is appropriate (not bare except)
+   - [ ] Context managers used for resources (with statements)
+   - [ ] No mutable default arguments
+   - [ ] Imports are organized (stdlib, third-party, local)
+
+4. Check for code quality:
+   - [ ] Functions are small and focused
+   - [ ] Names follow PEP 8 conventions
+   - [ ] No code duplication
+   - [ ] Appropriate use of Python idioms
+   - [ ] List comprehensions used where appropriate
+
+5. Check for security issues:
+   - [ ] No hardcoded secrets or credentials
+   - [ ] Input validation where needed
+   - [ ] Safe handling of user data
+   - [ ] No use of eval() or exec() with untrusted input
+
+6. Summarize findings:
+   - List issues found (if any) with file:line references
+   - Suggest specific fixes
+   - Note any patterns that should be addressed

package/dist/docs/shortcuts/standard/review-code-typescript.md

@@ -0,0 +1,46 @@
+---
+title: Review Code (TypeScript)
+description: Perform a code review for TypeScript code following best practices
+---
+Shortcut: Review Code (TypeScript)
+
+We track issues with tbd.
+Run `tbd` for more on using tbd and current status.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Identify the code to review:
+   - If changes are staged, review `git diff --cached`
+   - If changes are unstaged, review `git diff`
+   - Or review specific files the user mentions
+
+2. Review the TypeScript rules and guidelines:
+   - Run `tbd guidelines typescript-rules` for language-specific rules
+   - Run `tbd guidelines general-coding-rules` for general rules
+
+3. Check for common TypeScript issues:
+   - [ ] Types are properly defined (avoid `any` unless necessary)
+   - [ ] Interfaces/types are used for complex objects
+   - [ ] Null/undefined handled properly (strict null checks)
+   - [ ] Async/await used correctly (no floating promises)
+   - [ ] Error handling is appropriate
+   - [ ] No unused imports or variables
+
+4. Check for code quality:
+   - [ ] Functions are small and focused
+   - [ ] Names are descriptive and consistent
+   - [ ] Comments explain “why” not “what”
+   - [ ] No code duplication
+   - [ ] Appropriate use of TypeScript features
+
+5. Check for security issues:
+   - [ ] No hardcoded secrets or credentials
+   - [ ] Input validation where needed
+   - [ ] Safe handling of user data
+
+6. Summarize findings:
+   - List issues found (if any) with file:line references
+   - Suggest specific fixes
+   - Note any patterns that should be addressed

package/dist/docs/shortcuts/standard/welcome-user.md

@@ -0,0 +1,65 @@
+---
+title: Welcome User
+description: Welcome message for users after tbd installation or setup
+---
+# Welcome User After tbd Setup
+
+Welcome the user with the message below.
+This applies whether this is a new installation or the user is joining an existing
+project.
+
+## Instructions
+
+First, run `tbd status` to check the current state.
+Give a brief summary of the status (repository, sync status, integrations).
+
+Then show the welcome message:
+
+* * *
+
+**Welcome! tbd is ready for this project.**
+
+tbd helps you ship code with greater speed, quality, and discipline.
+It tracks work as **beads** (issues) and provides shortcuts for common workflows.
+
+Here are examples of things you can say and what happens:
+
+### Beads (Issues)
+
+| What You Can Say | What Happens |
+| --- | --- |
+| "There's a bug where ..." | Creates and tracks a bug bead (`tbd create`) |
+| "Let's work on current issues" | Shows ready beads to tackle (`tbd ready`) |
+| "Track this as a task" | Creates a task bead (`tbd create`) |
+
+### Shortcuts and Workflows
+
+| What You Can Say | What Happens |
+| --- | --- |
+| "Let's plan a new feature" | Walks you through creating a planning spec (`tbd shortcut new-plan-spec`) |
+| "Break the spec into issues" | Creates implementation beads from your spec (`tbd shortcut new-implementation-beads-from-spec`) |
+| "Implement these issues" | Works through beads systematically (`tbd shortcut implement-beads`) |
+| "Commit this code" | Reviews changes and commits properly (`tbd shortcut commit-code`) |
+| "Create a PR" | Creates a pull request with summary (`tbd shortcut create-or-update-pr-simple`) |
+| "Review this for best practices" | Performs a code review with guidelines |
+
+### Guidelines
+
+| What You Can Say | What Happens |
+| --- | --- |
+| "I'm building a TypeScript CLI" | Applies TypeScript CLI guidelines |
+| "Help me set up better testing" | Applies testing guidelines |
+| "What are the Python best practices?" | Applies Python guidelines |
+
+**Tips:**
+
+- Say **“Use beads to …”** and I will track everything with beads.
+  This works much better than the usual to-do lists for long lists of tasks.
+
+- Say **“Is there a shortcut for ...?”** or **“Use the shortcut to …”** and I’ll look
+  for the shortcut for that workflow.
+
+* * *
+
+Then ask if they’d like to explore any of tbd’s capabilities or get started on
+something.