get-tbd 0.1.8

package/dist/docs/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: tbd
+description: >-
+  Git-native issue tracking (beads), coding guidelines, and spec-driven planning for AI agents.
+  Use for tracking issues with dependencies, creating and closing bugs, features, and tasks,
+  planning specs for new features, implementing features from specs, code reviews, committing code,
+  creating PRs, research briefs, and architecture docs. Invoke when user mentions: tbd, beads,
+  issues, bugs, tasks, todo, tracking, specs, planning, implementation, validation, guidelines,
+  shortcuts, templates, commit, PR workflows, code review, testing best practices, or monorepo patterns.
+allowed-tools: Bash(tbd:*), Read, Write
+---
+
+# tbd Workflow
+
+**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**
+
+1. **Issue Tracking**: Git-native tasks/bugs.
+   Never lose work across sessions.
+2. **Spec-Driven Workflows**: Plan features → break into issues → implement
+   systematically.
+3. **Shortcuts**: Pre-built processes for commits, PRs, reviews.
+4. **Guidelines**: Best practices for TypeScript, Python, testing.
+
+These features work together to create high-quality workflows.
+Be sure to apply the workflows below for all issue tracking, spec driven planning and
+implementation, and code review.
+
+## Installation
+
+If `tbd` is not installed, install and set up:
+
+```bash
+npm install -g get-tbd@latest
+tbd                                # Gives full orientation
+tbd setup --auto --prefix=<name>   # Fresh project (--prefix REQUIRED)
+tbd setup --auto                   # Existing tbd project (prefix already set)
+```
+
+The prefix appears in every issue ID (e.g., `myapp-a1b2`) and is a matter of user
+preference for a given project.
+
+**IMPORTANT NOTES ON SETUP:**
+- **Fresh projects**: `--prefix` is REQUIRED. NEVER guess or invent a prefix.
+  Always ask the user first.
+- **Existing tbd projects** (`.tbd/` exists): No `--prefix` needed, just run
+  `tbd setup --auto`.
+- **Beads migration** (`.beads/` exists): Use `tbd setup --from-beads` (uses beads
+  prefix).
+- **Refresh configs**: Run `tbd setup --auto` anytime to update skill files, hooks, and
+  get the latest shortcuts/guidelines/templates.
+
+> `tbd prime` restores context after compaction/clear (auto-called by hooks).
+
+## CRITICAL: You Use tbd — The User Doesn’t
+
+**You are the tbd operator.** The user talks to you naturally; you translate their
+requests into tbd actions.
+Never tell the user to run tbd commands themselves.
+
+- **WRONG**: "Run `tbd create` to track this bug"
+
+- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*
+
+- **WRONG**: "You can use `tbd ready` to see available work"
+
+- **RIGHT**: *(you run `tbd ready` yourself and show the user what’s available)*
+
+## Orientation and Help
+
+When users ask for orientation, help getting started, or want to understand tbd:
+
+- Run `tbd shortcut welcome-user` and follow its instructions
+- Show the user what they can **say** (natural language), not commands to run
+- The welcome message explains tbd’s value through examples of what the user can ask
+
+**DO NOT** respond to “what is tbd?”
+or “help me get started” by listing CLI commands.
+Instead, welcome them and show them the kinds of things they can ask you to do.
+
+## How to Use tbd to Help Users
+
+Use tbd proactively on behalf of the user:
+
+- User describes a bug → You run `tbd create "Bug: ..." --type=bug`
+- User wants a feature → You create a plan spec, then break into issues
+- Starting a session → You check `tbd ready` for available work
+- Completing work → You run `tbd close <id>` with clear reason
+- User asks what tbd does → You run `tbd shortcut welcome-user`
+- User asks for help/orientation → You run `tbd shortcut welcome-user`
+
+### Quick Reference Table
+
+This table shows what the user says naturally and what you (the agent) do in response.
+
+| What the User Says | What You (Agent) Do | What Happens |
+| --- | --- | --- |
+| "There's a bug where ..." | `tbd create "..." --type=bug` | Creates and tracks a bug |
+| "Let's work on current issues" | `tbd ready` | Shows ready issues |
+| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` | You follow the guidelines |
+| "Improve eslint setup" | `tbd guidelines typescript-monorepo-patterns` | You follow the guidelines |
+| "Add better e2e testing" | `tbd guidelines golden-testing-guidelines` | You follow the guidelines |
+| "Review these changes" (TypeScript) | `tbd guidelines typescript-rules` | You follow the guidelines |
+| "Review these changes" (Python) | `tbd guidelines python-rules` | You follow the guidelines |
+| "Let's plan a new feature" | `tbd shortcut new-plan-spec` | You follow the spec template |
+| "Break spec into issues" | `tbd shortcut new-implementation-beads-from-spec` | You create implementation issues |
+| "Implement these issues" | `tbd shortcut implement-beads` | You implement systematically |
+| "Commit this" | `tbd shortcut commit-code` | You review and commit |
+| "Create a PR" | `tbd shortcut create-or-update-pr-simple` | You create the PR |
+| "Research this topic" | `tbd shortcut new-research-brief` | You research and document |
+| "Document this architecture" | `tbd shortcut new-architecture-doc` | You create the doc |
+| *(your judgment)* | `tbd dep add`, `tbd close`, `tbd sync` | You manage issues as needed |
+
+## IMPORTANT: Session Closing Protocol
+
+**CRITICAL**: Before saying “done” or “complete”, you MUST run this checklist:
+
+```
+[ ] 1. Stage and commit: git add + git commit
+[ ] 2. Push to remote: git push
+[ ] 3. Start CI watch (BLOCKS until done): gh pr checks <PR> --watch 2>&1
+[ ] 4. While CI runs: tbd close/update <id> 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
+```
+
+### NON-NEGOTIABLE Requirements
+
+#### CI: Wait for `--watch` to finish
+
+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: Update issues and sync
+
+Every session must end with tbd in a clean state:
+- Close/update **every issue** you worked on
+- Run `tbd sync` and confirm it completed
+
+**Work is not done until pushed, CI passes, and tbd is synced.**
+
+## IMPORTANT: Issue Tracking Rules
+
+- Track *all task work* not being done immediately as beads using `tbd` (discovered
+  work, future work, TODOs for the session, multi-session work)
+- When in doubt, prefer tbd for tracking tasks, bugs, and issues
+- Use `tbd create` for creating beads
+- Git workflow: update or close issues and run `tbd sync` at session end
+- If not given specific directions, check `tbd ready` for available work
+
+## Essential Commands
+
+### Finding Work
+
+- `tbd ready` - Show issues ready to work (no blockers)
+- `tbd list --status open` - All open issues
+- `tbd list --status in_progress` - Your active work
+- `tbd show <id>` - Detailed issue view with dependencies
+
+### Creating & Updating
+
+- `tbd create "title" --type task|bug|feature --priority=P2` - New issue
+  - Priority: P0-P4 (P0=critical, P2=medium, P4=backlog).
+    Do NOT use "high"/"medium"/"low"
+- `tbd update <id> --status in_progress` - Claim work
+- `tbd update <id> --assignee username` - Assign to someone
+- `tbd close <id>` - Mark complete
+- `tbd close <id> --reason "explanation"` - Close with reason
+- **Tip**: When creating multiple issues, use parallel subagents for efficiency
+
+### Dependencies & Blocking
+
+- `tbd dep add <issue> <depends-on>` - Add dependency (issue depends on depends-on)
+- `tbd blocked` - Show all blocked issues
+- `tbd show <id>` - See what’s blocking/blocked by this issue
+
+### Sync & Collaboration
+
+- `tbd sync` - Sync with git remote (run at session end)
+- `tbd sync --status` - Check sync status without syncing
+
+Note: `tbd sync` handles all git operations for issues--no manual git push needed.
+
+### Project Health
+
+- `tbd stats` - Project statistics (open/closed/blocked counts)
+- `tbd doctor` - Check for issues (sync problems, missing hooks)
+
+## Documentation Commands
+
+### Shortcuts
+
+Reusable instruction templates for common tasks:
+
+- `tbd shortcut <name>` - Output a shortcut by name
+- `tbd shortcut --list` - List all available shortcuts
+
+### Guidelines
+
+Coding rules and best practices:
+
+- `tbd guidelines <name>` - Output a guideline by name
+- `tbd guidelines --list` - List all available guidelines
+
+Example: `tbd guidelines typescript-rules`
+
+### Templates
+
+Document templates for specs, research, architecture:
+
+- `tbd template <name>` - Output a template by name
+- `tbd template --list` - List all available templates
+
+Example: `tbd template plan-spec > docs/project/specs/active/plan-YYYY-MM-DD-feature.md`
+
+## Quick Reference
+
+- **Priority levels**: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
+- **Issue types**: task, bug, feature, epic
+- **Status values**: open, in_progress, closed
+- **JSON output**: Add `--json` to any command for machine-readable output

package/dist/docs/guidelines/backward-compatibility-rules.md

@@ -0,0 +1,78 @@
+---
+title: Backward Compatibility Rules
+description: Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas
+---
+## Backward Compatibility Guidelines
+
+### Types of Backward Compatibility
+
+When making code changes, you should be aware of compatibility requirements for:
+
+- Code compatibility internal to a single application (types and method or function
+  signatures)
+
+- API compatibility for libraries (types and method or function signatures)
+
+- Server API compatibility (REST, GraphQL, gRPC, etc.)
+
+- File format compatibility
+
+- Database schema compatibility
+
+### Backward Compatibility Template
+
+> Use the following template when clarifying backward compatibility requirements:
+
+For the following areas:
+
+- “DO NOT MAINTAIN” means simply make the changes and DO NOT preserve any old stubs or
+  add comments about past changes
+
+- “KEEP DEPRECATED” means to add new features but also preserve support, function stubs,
+  and comments about past changes
+
+- “SUPPORT BOTH” means to add new features but also preserve support, function
+
+- “MIGRATE” means to add new features but also document and use database migrations or
+  automated tasks to migrate to new formats or schemas
+
+- “N/A” means this area isn’t applicable
+
+**BACKWARD COMPATIBILITY REQUIREMENTS:**
+
+- **Code types, methods, and function signatures**:
+  [DO NOT MAINTAIN or KEEP DEPRECATED, additional notes if necessary]
+
+- **Library APIs**:
+  [DO NOT MAINTAIN or KEEP DEPRECATED or N/A, plus any additional notes]
+
+- **Server APIs**:
+  [DO NOT MAINTAIN or KEEP DEPRECATED or N/A, plus any additional notes]
+
+- **File formats**: [DO NOT MAINTAIN or SUPPORT BOTH or N/A, plus any additional notes]
+
+- **Database schemas**: [DO NOT MAINTAIN or MIGRATE or N/A, plus any additional notes]
+
+### Always Clarify Backward Compatibility Requirements
+
+- ALWAYS be clear on backward compatibility requirements when making changes.
+  These should ALWAYS be clear in any specification.
+
+- If they are not clear, stop and ask the user for clarification.
+
+### When Backward Compatibility Is Important
+
+- In general, compatibility for libraries, servers, file formats and database schemas is
+  VERY IMPORTANT. Compatibility and migration should be planned carefully.
+
+- Backward compatibility and legacy support *within* a single application is usually NOT
+  important and should NOT be done if it needlessly complicates code changes.
+  But if not specified, it also should be clarified to be sure it is not needed.
+
+### Single Application Code Backward Compatibility
+
+- Unless stated in the spec or stated by the user, deprecated and backward compatibility
+  code support should NOT be left after refactors to a single application repository.
+
+- When doing normal refactoring or reorganizing code, REMOVE deprecated functions,
+  methods, classes, or files completely if backward compatibility is not needed.

package/dist/docs/guidelines/commit-conventions.md

@@ -0,0 +1,78 @@
+---
+title: Commit Conventions
+description: Conventional Commits format with extensions for agentic workflows
+---
+# Commit Conventions
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) with extensions for
+agentic use cases, including use for content work and operational tasks in addition to
+software development.
+
+## Format
+
+```
+<type>[optional scope][!]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- First line short, ideally 72 characters or less
+- Use imperative mood ("Add feature" not “Added feature”)
+- No scope by default; only use when disambiguation is needed (e.g., `fix(parser):`)
+- For breaking changes: add `!` before `:` AND include `BREAKING CHANGE:` in the footer
+
+## Types
+
+Classic software development work:
+
+- `feat`: New feature (improved software functionality)
+- `fix`: Bug fix (corrected software functionality)
+- `style`: Code formatting (no logic change)
+- `refactor`: Code restructuring (no behavior change)
+- `test`: Adding or updating tests
+- `chore`: Software maintenance (deps, config, build, upgrades)
+- `docs`: User-facing docs (README, API docs, guides, tutorials)
+
+Agentic project work:
+
+- `plan`: Internal design, plans, specs, architecture, requirements docs
+- `research`: Internal research docs, notes, resources, reports
+- `ops`: Operational tasks (issue tracking, syncing, publishing, maintenance)
+- `process`: Changes to processes, methodology, conventions, policies
+
+Commit types can drive automated versioning and changelogs.
+See your project’s release process for specific rules.
+
+The type indicates the *category of artifact* being changed.
+Corrections within a category use that category’s type (e.g., fixing a typo in docs is
+`docs:`, not `fix:`).
+
+Note: `plan`, `research`, `ops`, and `process` are extensions for agentic development,
+not part of the standard Conventional Commits spec.
+
+**Key distinctions:** `docs` is for users; `plan` is design/specs for building;
+`research` is internal learning/investigation; `ops` is operational work; `process` is
+methodology.
+
+## Examples
+
+```
+feat: Add support for custom labels
+feat(parser): Add YAML front matter support
+fix: Handle empty issue list gracefully
+fix(api): Return 404 for missing resources
+docs: Update CLI usage examples
+docs: Fix typo in API reference
+style: Format with prettier
+refactor: Extract validation logic to separate module
+test: Add golden tests for sync command
+chore: Update dependencies
+plan: Add design document for dependency resolution
+research: Comparison of TypeScript monorepo build tools
+research: A summary of SEO best practices in 2026
+ops: Update issue status for auth feature
+ops: Sync beads with remote
+process: Add TDD guidelines for agent workflows
+```

package/dist/docs/guidelines/convex-limits-best-practices.md

@@ -0,0 +1,170 @@
+---
+title: Convex Limits and Best Practices
+description: Comprehensive reference for Convex platform limits, workarounds, and performance best practices
+---
+# Convex Database Limits, Best Practices, and Workarounds
+
+## Core Limits Reference
+
+### Transaction Read/Write Limits
+
+| Limit Type | Value |
+| --- | --- |
+| Maximum data read | 8 MiB per query/mutation |
+| Maximum documents scanned | 16,384 per query/mutation |
+| Maximum data written | 8 MiB per mutation |
+| Maximum documents written | 8,192 per mutation |
+| Maximum db.get/db.query calls | 4,096 per transaction |
+
+The read limit includes **all scanned document bytes**, not just returned results.
+Convex does not support field projection.
+
+### Document Size and Structure Limits
+
+| Limit | Value |
+| --- | --- |
+| Maximum document size | 1 MiB |
+| Maximum fields per document | 1,024 |
+| Maximum nesting depth | 16 levels |
+| Maximum array elements | 8,192 per array |
+| Maximum field name length | 1,024 characters |
+| Maximum identifier length | 64 characters |
+
+The 8,192 array limit also applies to arrays **returned** by query functions.
+Use `.take(8000)` to stay safely under this limit.
+
+### Concurrency and Execution Limits
+
+| Limit | Value |
+| --- | --- |
+| Concurrent queries/mutations/actions (default) | 16 each |
+| Scheduled job parallelism | 10 concurrent |
+| Query/Mutation user timeout | 1 second |
+| Action timeout | 10 minutes |
+| Log lines per execution | 256 (silently truncated) |
+| Max scheduled per mutation | 1,000 |
+
+### Action Memory Limits
+
+| Runtime | Memory Limit |
+| --- | --- |
+| Convex Runtime (default) | 64 MB |
+| Node.js Runtime (`"use node;"`) | 512 MB |
+
+### Index and Schema Limits
+
+| Limit | Value |
+| --- | --- |
+| Indexes per table | 32 (source code: 64) |
+| Fields per index | 16 |
+| Full-text indexes per table | 4 |
+| Vector indexes per table | 4 |
+| Vector index max documents | 100,000 |
+| Maximum tables | 10,000 |
+
+### Storage and Bandwidth (Starter / Professional)
+
+| Resource | Starter | Professional |
+| --- | --- | --- |
+| Database storage | 0.5 GB | 50 GB |
+| Database bandwidth/month | 1 GB | 50 GB |
+| File storage | 1 GB | 100 GB |
+| Function calls/month | 1,000,000 | 25,000,000 |
+
+## Function Calling Rules
+
+| Caller | Can Call | Method |
+| --- | --- | --- |
+| Query | Helper functions only | Direct call |
+| Mutation | Helper functions only | Direct call |
+| Action | Queries, mutations, actions | `ctx.runQuery/runMutation/runAction` |
+
+- Queries and mutations cannot call other queries/mutations
+- Actions orchestrate across transactions (not atomic)
+- Avoid nested same-runtime action calls; use helper functions instead
+
+## Common Pitfalls and Workarounds
+
+### 1. Exceeding 8 MiB Read Limit with `.collect()`
+
+Never use `.collect()` on unbounded tables.
+Use `.take(n)` or `.paginate()`.
+
+### 2. Large Documents Causing Read Limit Issues
+
+Keep documents used for listing/counting small (<10KB). Store large payloads in separate
+detail tables.
+
+### 3. Counting/Aggregating Large Datasets
+
+Use the [Convex Aggregate Component](https://github.com/get-convex/aggregate) for O(log
+n) counts and sums.
+
+### 4. Post-Index Filtering
+
+Create composite indexes instead of `.withIndex()` followed by `.filter()`.
+
+```typescript
+// BAD: reads all items for parentId, then filters
+.withIndex('by_parent', q => q.eq('parentId', id))
+.filter(q => q.eq(q.field('status'), 'active'))
+
+// GOOD: composite index
+.withIndex('by_parent_and_status', q => q.eq('parentId', id).eq('status', 'active'))
+```
+
+### 5. OCC Conflicts
+
+- Consolidate related writes into single mutations
+- Batch create operations
+- Use namespacing to isolate writes
+- Stagger scheduled mutations with delays
+
+### 6. Pagination Loops in Queries
+
+Never use pagination loops in queries/mutations (1s timeout, test hangs).
+Use actions for pagination loops (10-minute limit).
+
+### 7. Bucket Timestamp Keys
+
+Bucket monotonically increasing keys to spread writes across B-tree nodes:
+
+```typescript
+const bucketedTime = Math.floor(timestamp / 60000) * 60000;
+```
+
+### 8. Dangling Promises in Actions
+
+Always `await` every async call.
+Never use `void asyncFn()` or `asyncFn().catch()`. Use `ctx.scheduler.runAfter` for
+truly independent operations.
+
+### 9. Nested Same-Runtime Action Calls
+
+Use `ctx.runAction()` only for cross-runtime calls (V8 to Node.js).
+Extract shared logic into plain TypeScript helper functions.
+
+## Best Practices Checklist
+
+- Never `.collect()` on unbounded tables; use `.take()` or `.paginate()`
+- Use composite indexes matching query patterns
+- Keep listing documents small (<10KB); separate large payloads
+- Use Aggregate Component for stats over >100 records
+- Bound all aggregate reads with `lower`/`upper`
+- Namespace writes to avoid OCC contention
+- Keep queries/mutations under 1 second; use actions for heavy work
+- Await all promises in actions
+- Use `internalQuery`/`internalMutation`/`internalAction` for private functions
+- Always include `args` and `returns` validators
+
+## Decision Matrix
+
+| Use Case | Pattern |
+| --- | --- |
+| Count <100 records | Direct `.collect()` |
+| Count 100-1000 records | `.take(limit)` with head+1 |
+| Count >1000 records | Aggregate Component |
+| List unbounded records | `.paginate()` |
+| Large text fields (>10KB) | Separate detail table |
+| Processing <10 min | Action with progress logging |
+| Processing >10 min | Resumable action or scheduled jobs |