get-tbd 0.1.13 → 0.1.15

package/dist/docs/guidelines/release-notes-guidelines.md

@@ -0,0 +1,140 @@
+---
+title: Release Notes Guidelines
+description: Guidelines for writing clear, accurate release notes
+---
+# Release Notes Guidelines
+
+Write release notes that are accurate, scannable, and useful to users deciding whether
+to upgrade.
+
+## Structure
+
+Use these sections in order (omit empty sections):
+
+```markdown
+## What's Changed
+
+### Features
+- New capabilities users can now do
+
+### Fixes
+- Bug fixes and corrections
+
+### Refactoring
+- Internal improvements (only if user-visible impact)
+
+### Documentation
+- Doc improvements (only notable ones)
+
+**Full commit history**: [link to compare]
+```
+
+## Core Principle: Describe the Delta
+
+**Think in terms of two points in time:**
+
+1. The state of the application at the previous release
+2. The state of the application at this release
+
+Release notes describe the **aggregate difference** between these two states.
+Don’t recap individual commits or intermediate changes - describe what’s different now
+compared to before.
+
+**Example:** If a feature was added and then bug-fixed before release, don’t list the
+bug fix separately.
+Describe the feature as it now works (the complete, working version).
+
+## Writing Principles
+
+### 1. Consolidate Related Changes
+
+Group sub-features, fixes, and improvements with their parent feature rather than
+listing them separately.
+If a bug fix is for a feature added in the same release, incorporate it into the feature
+description.
+
+**Bad:**
+
+```markdown
+### Features
+- **Workspace sync**: New tbd save command
+- **Workspace list**: Show saved workspaces
+
+### Fixes
+- **Workspace mappings**: Save now filters mappings correctly
+```
+
+**Good:**
+
+```markdown
+### Features
+- **Workspace sync feature**: New commands for managing local workspace backups:
+  - `tbd save` to export issues (filters mappings correctly)
+  - `tbd workspace list` to show saved workspaces with counts
+```
+
+### 2. Write From the User’s Perspective
+
+Describe capabilities users now have, not implementation details.
+A user reading the notes should understand what they can do differently after upgrading.
+
+### 3. Be Specific About Impact
+
+Include the user-facing impact, not just the implementation detail.
+
+**Bad:**
+
+> Increased git maxBuffer
+
+**Good:**
+
+> Git maxBuffer overflow: Increased buffer from 1MB to 50MB to prevent sync failures on
+> large repos
+
+### 4. Use Consistent Formatting
+
+- Bold the feature/fix name
+- Use bullet points for sub-items
+- Include command names in backticks
+- Keep descriptions concise (1-2 lines)
+
+### 5. Skip Internal-Only Changes
+
+Don’t include:
+
+- Test-only changes (unless they fix flaky tests users noticed)
+- Pure refactoring with no user impact
+- CI/tooling changes
+- Minor doc typo fixes
+
+## Review Checklist
+
+Before finalizing release notes:
+
+- [ ] Does each item describe the aggregate delta from the previous release?
+- [ ] Are related changes (features + their fixes) consolidated under one heading?
+- [ ] Would a user understand what’s different after upgrading?
+- [ ] Are feature names/commands in consistent format?
+- [ ] Are internal-only changes excluded?
+
+## Example
+
+```markdown
+## What's Changed
+
+### Features
+
+- **Workspace sync feature**: New commands for managing local workspace backups:
+  - `tbd save` to export issues to workspace directories (supports `--updates-only`)
+  - `tbd workspace list` to show saved workspaces with issue counts
+  - `tbd import --workspace` to restore from workspace backups
+- **Child bead ordering**: New `child_order` field allows explicit ordering of child
+  beads
+
+### Fixes
+
+- **Git maxBuffer overflow**: Increased buffer from 1MB to 50MB to prevent sync
+  failures on large repos
+
+**Full commit history**: https://github.com/org/repo/compare/v0.1.12...v0.1.13
+```

package/dist/docs/guidelines/{sync-troubleshooting.md → tbd-sync-troubleshooting.md}

@@ -1,5 +1,5 @@
 ---
-title: Sync and Workspace Troubleshooting
+title: tbd Sync and Workspace Troubleshooting
 description: Common issues and solutions for tbd sync and workspace operations
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---

package/dist/docs/guidelines/typescript-sorting-patterns.md

@@ -0,0 +1,234 @@
+---
+title: TypeScript Sorting Patterns
+description: Deterministic sorting patterns and comparison chains for TypeScript
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+# TypeScript Sorting Patterns
+
+**Related**: `tbd guidelines typescript-rules`, `tbd guidelines general-testing-rules`
+
+## 1. Always Make Sorting Deterministic
+
+Never leave a sort with only a primary key.
+When two items have the same primary sort value, the output order is undefined and will
+vary across runs, platforms, and data sizes.
+This causes flaky tests, confusing UI, and unreproducible bugs.
+
+**Always add a secondary (or tertiary) sort key that is guaranteed unique**, such as an
+ID or timestamp.
+
+### BAD: Primary sort only
+
+```typescript
+// If two issues share the same priority, order is random.
+issues.sort((a, b) => a.priority - b.priority);
+```
+
+### GOOD: Secondary sort for determinism
+
+```typescript
+issues.sort((a, b) => {
+  const cmp = a.priority - b.priority;
+  if (cmp !== 0) return cmp;
+  return a.id.localeCompare(b.id);
+});
+```
+
+This pattern applies everywhere: UI lists, CLI output, test assertions, API responses.
+If you can’t guarantee uniqueness of the primary key, you need a tiebreaker.
+
+## 2. Use Comparison Chains for Multi-Field Sorts
+
+Hand-written multi-field comparators are verbose and error-prone.
+A **comparison chain** (inspired by Google Guava’s `ComparisonChain`) provides a fluent
+API that’s easier to read, write, and maintain.
+
+### Before: Manual multi-field sort with nulls
+
+```typescript
+items.sort((a, b) => {
+  // Primary: priority ascending
+  if (a.priority !== b.priority) return a.priority - b.priority;
+  // Secondary: title, nulls last
+  if (a.title === null && b.title !== null) return 1;
+  if (a.title !== null && b.title === null) return -1;
+  if (a.title !== null && b.title !== null) {
+    const cmp = a.title.localeCompare(b.title);
+    if (cmp !== 0) return cmp;
+  }
+  // Tertiary: ID for determinism
+  return a.id.localeCompare(b.id);
+});
+```
+
+### After: Comparison chain
+
+```typescript
+items.sort(
+  comparisonChain<Item>()
+    .compare((i) => i.priority)
+    .compare((i) => i.title, ordering.nullsLast)
+    .compare((i) => i.id)
+    .result(),
+);
+```
+
+The chain short-circuits: once a `.compare()` step returns non-zero, subsequent steps
+are skipped. This matches the semantics of manual `if (cmp !== 0) return cmp` chains.
+
+## 3. Comparison Chain Reference Implementation
+
+The following is a standalone, dependency-free utility.
+Copy it into your project:
+
+```typescript
+export type Selector<T, K> = (item: T) => K;
+export type Comparator<T> = (a: T, b: T) => number;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const defaultCompare: Comparator<any> = (a, b) => {
+  if (typeof a === 'string' && typeof b === 'string') {
+    return a.localeCompare(b);
+  }
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const nullLastCompare: Comparator<any> = (a, b) => {
+  if (a == null) return b == null ? 0 : 1;
+  if (b == null) return -1;
+  return defaultCompare(a, b);
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const nullFirstCompare: Comparator<any> = (a, b) => {
+  if (a == null) return b == null ? 0 : -1;
+  if (b == null) return 1;
+  return defaultCompare(a, b);
+};
+
+/**
+ * A Google Guava-style comparison chain for fluent multi-field sorting.
+ *
+ * items.sort(comparisonChain<Item>()
+ *   .compare(item => item.title, ordering.nullsLast)
+ *   .compare(item => item.url)
+ *   .result());
+ */
+export const comparisonChain = <T>() => {
+  let compare: Comparator<T> = () => 0;
+
+  const chain: {
+    compare: <K>(selector: Selector<T, K>, comparator?: Comparator<K>) => typeof chain;
+    result: () => Comparator<T>;
+  } = {
+    compare: <K>(selector: Selector<T, K>, comparator: Comparator<K> = defaultCompare) => {
+      const prevCompare = compare;
+      compare = (a, b) => prevCompare(a, b) || comparator(selector(a), selector(b));
+      return chain;
+    },
+    result: () => compare,
+  };
+
+  return chain;
+};
+
+export const reverse =
+  <T>(comparator: Comparator<T>) =>
+  (a: T, b: T) =>
+    comparator(b, a);
+
+const manualOrderComparator = <T>(order: readonly T[]): Comparator<T> => {
+  const orderMap = new Map(order.map((value, index) => [value, index]));
+  return (a: T, b: T): number => {
+    const indexA = orderMap.get(a);
+    const indexB = orderMap.get(b);
+    if (indexA === undefined) return indexB === undefined ? 0 : 1;
+    if (indexB === undefined) return -1;
+    return indexA - indexB;
+  };
+};
+
+export const ordering = {
+  nullsLast: nullLastCompare,
+  nullsFirst: nullFirstCompare,
+  default: defaultCompare,
+  reversed: reverse(defaultCompare),
+  manual: manualOrderComparator,
+};
+```
+
+## 4. Common Ordering Strategies
+
+| Ordering | Behavior |
+| --- | --- |
+| `ordering.default` | Strings via `localeCompare`, numbers via `<`/`>` |
+| `ordering.reversed` | Reverse of default (descending) |
+| `ordering.nullsLast` | `null`/`undefined` sort after all non-null values |
+| `ordering.nullsFirst` | `null`/`undefined` sort before all non-null values |
+| `ordering.manual(…)` | Sort by position in an explicit array; unlisted go last |
+| `reverse(cmp)` | Wrap any comparator to invert its direction |
+
+## 5. Usage Examples
+
+### Simple priority + ID sort
+
+```typescript
+issues.sort(
+  comparisonChain<Issue>()
+    .compare((i) => i.priority)
+    .compare((i) => i.id)
+    .result(),
+);
+```
+
+### Descending date with ID tiebreaker
+
+```typescript
+staleItems.sort(
+  comparisonChain<StaleItem>()
+    .compare((s) => s.daysSinceUpdate, ordering.reversed)
+    .compare((s) => s.issue.id)
+    .result(),
+);
+```
+
+### Multi-field with nulls
+
+```typescript
+items.sort(
+  comparisonChain<Item>()
+    .compare((i) => i.title, ordering.nullsLast)
+    .compare((i) => i.url, ordering.nullsLast)
+    .compare((i) => i.sequenceNum, ordering.nullsLast)
+    .result(),
+);
+```
+
+### Custom enum ordering
+
+```typescript
+const statusOrder = ['active', 'pending', 'archived'] as const;
+
+items.sort(
+  comparisonChain<Item>()
+    .compare((i) => i.status, ordering.manual(statusOrder))
+    .compare((i) => i.name)
+    .result(),
+);
+```
+
+### With a custom comparator (e.g. natural sort)
+
+```typescript
+import { naturalCompare } from './sort.js';
+
+items.sort(
+  comparisonChain<Item>()
+    .compare((i) => i.priority)
+    .compare((i) => getShortId(i), (a, b) => naturalCompare(a, b))
+    .result(),
+);
+```

package/dist/docs/guidelines/typescript-yaml-handling-rules.md

@@ -0,0 +1,195 @@
+---
+title: TypeScript YAML Handling Rules
+description: Best practices for parsing and serializing YAML in TypeScript
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+globs: "*.ts"
+---
+# TypeScript YAML Handling Rules
+
+These guidelines ensure consistent, safe, and readable YAML handling across TypeScript
+codebases. YAML is deceptively tricky—inconsistent quoting, serialization differences,
+and lack of validation cause subtle bugs.
+
+## Use the Right Package
+
+- **Use `yaml` (v2.x)**, not `js-yaml`. The `yaml` package has better TypeScript
+  support, more control over output formatting, and proper handling of edge cases.
+
+  ```ts
+  // Good
+  import { parse, stringify } from 'yaml';
+  
+  // Avoid
+  import yaml from 'js-yaml';
+  ```
+
+## Centralize Serialization Options
+
+- **Externalize settings to a central file** instead of scattering `stringify()` calls
+  with ad-hoc options throughout the codebase.
+
+  ```ts
+  // lib/settings.ts
+  export const DEFAULT_YAML_LINE_WIDTH = 88;
+  
+  // Readable YAML output:
+  // - No forced quoting (YAML only quotes when necessary)
+  // - Line wrapping at 88 chars for readability
+  // - Sorted keys for deterministic diffs
+  export const YAML_STRINGIFY_OPTIONS = {
+    lineWidth: DEFAULT_YAML_LINE_WIDTH,
+    defaultStringType: 'PLAIN',
+    defaultKeyType: 'PLAIN',
+    sortMapEntries: true,
+  } as const;
+  ```
+
+- **Use the centralized options** wherever you serialize YAML:
+
+  ```ts
+  // serialize.ts
+  import { stringify } from 'yaml';
+  import { YAML_STRINGIFY_OPTIONS } from '../lib/settings.js';
+  
+  const yamlStr = stringify(frontmatterObj, YAML_STRINGIFY_OPTIONS);
+  ```
+
+- **Optionally create wrapper functions** for additional convenience:
+
+  ```ts
+  // utils/yaml-utils.ts
+  import { stringify } from 'yaml';
+  import { YAML_STRINGIFY_OPTIONS } from '../lib/settings.js';
+  
+  export function stringifyYaml(data: unknown, options?: object): string {
+    return stringify(data, { ...YAML_STRINGIFY_OPTIONS, ...options });
+  }
+  ```
+
+## Recommended Defaults
+
+These defaults produce clean, readable YAML without unnecessary quoting:
+
+| Option | Value | Rationale |
+| --- | --- | --- |
+| `lineWidth` | 88 | Line wrapping for readability (matches Black formatter) |
+| `defaultStringType` | `'PLAIN'` | No quotes unless necessary (e.g., special chars, colons) |
+| `defaultKeyType` | `'PLAIN'` | Unquoted keys: `name:` not `"name":` |
+| `sortMapEntries` | `true` | Deterministic output for clean diffs |
+
+The key insight: YAML is designed to be human-readable.
+Forcing quotes everywhere (e.g., `"value"` instead of `value`) defeats this purpose.
+Use `PLAIN` types to let YAML quote only when semantically required.
+
+## Validate with Zod
+
+- **Always validate parsed YAML** with a Zod schema.
+  Raw `parse()` returns `unknown` and provides no guarantees about structure.
+
+  ```ts
+  // Good
+  import { z } from 'zod';
+  import { parse } from 'yaml';
+  
+  const ConfigSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+  });
+  
+  const rawData = parse(content);
+  const result = ConfigSchema.safeParse(rawData);
+  if (!result.success) {
+    throw new Error(`Invalid config: ${result.error.message}`);
+  }
+  const config = result.data; // Typed and validated
+  
+  // Avoid
+  const config = parse(content) as Config; // Type assertion with no runtime validation
+  ```
+
+## Handle Merge Conflicts
+
+- **Check for git merge conflict markers** before parsing user-editable files.
+  Conflict markers cause cryptic YAML parse errors.
+
+  ```ts
+  export function parseYamlWithConflictDetection<T>(content: string, filePath?: string): T {
+    if (/^<<<<<<< /m.test(content) || /^=======/m.test(content) || /^>>>>>>> /m.test(content)) {
+      throw new MergeConflictError(
+        `File contains unresolved git merge conflict markers`,
+        filePath
+      );
+    }
+    return parse(content) as T;
+  }
+  ```
+
+## Common Antipatterns
+
+### Antipattern: Manual String Building
+
+```ts
+// Bad: Manual YAML string construction
+const yaml = `name: ${name}\nversion: ${version}`;
+
+// Good: Use stringify()
+const yaml = stringifyYaml({ name, version });
+```
+
+### Antipattern: Inconsistent Quoting
+
+```ts
+// Bad: Inconsistent options across codebase
+stringify(data1, { lineWidth: 80 });
+stringify(data2, { lineWidth: 100, defaultStringType: 'QUOTE_DOUBLE' });
+stringify(data3); // No options
+
+// Good: Use centralized wrapper
+stringifyYaml(data1);
+stringifyYaml(data2);
+stringifyYaml(data3);
+```
+
+### Antipattern: Unvalidated Parsing
+
+```ts
+// Bad: Type assertion without validation
+const config = parse(content) as Config;
+
+// Good: Runtime validation
+const config = ConfigSchema.parse(parse(content));
+```
+
+### Antipattern: Using gray-matter Directly for Serialization
+
+```ts
+// Bad: gray-matter.stringify() has limited formatting control
+import matter from 'gray-matter';
+const output = matter.stringify(body, frontmatter);
+
+// Good: Use gray-matter for parsing, yaml package for serialization
+import matter from 'gray-matter';
+import { stringifyYaml } from './yaml-utils.js';
+
+const { data, content } = matter(input);
+const output = `---\n${stringifyYaml(data)}---\n\n${content}`;
+```
+
+## Testing YAML Output
+
+- **Don’t rely on key order in tests** when using `sortMapEntries: true`. Keys are
+  sorted alphabetically.
+
+  ```ts
+  // Fragile: Depends on key order
+  expect(yaml).toMatch(/^---\nname: foo\nversion: 1/);
+  
+  // Robust: Tests presence, not order
+  expect(yaml).toContain('name: foo');
+  expect(yaml).toContain('version: 1');
+  ```
+
+## Related Guidelines
+
+- For general TypeScript rules, see `tbd guidelines typescript-rules`
+- For error handling patterns, see `tbd guidelines error-handling-rules`

package/dist/docs/install/claude-header.md

@@ -1,12 +1,19 @@
 ---
 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.
+  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.
 allowed-tools: Bash(tbd:*), Read, Write
 ---
 

package/dist/docs/shortcuts/standard/agent-handoff.md

@@ -1,6 +1,7 @@
 ---
 title: Agent Handoff
 description: Generate a concise handoff prompt for another coding agent to continue work
+category: session
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Generate a high-signal handoff prompt for the next agent.

package/dist/docs/shortcuts/standard/checkout-third-party-repo.md

@@ -0,0 +1,50 @@
+---
+title: Checkout Third-Party Repo
+description: Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website).
+category: research
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+Clone a third-party library or tool’s repository locally to review its source code.
+
+## Why This Approach
+
+**Do not** use web search or try to scrape GitHub.com for source code.
+GitHub blocks scraping, results are messy, and you lose full codebase context.
+Cloning locally gives you reliable, complete, searchable access to the exact version you
+need.
+
+## Steps
+
+1. **Create attic directory** (if not exists):
+   ```bash
+   mkdir -p attic
+   ```
+
+2. **Add to .gitignore** (if not already):
+   ```bash
+   echo "attic/" >> .gitignore
+   ```
+
+3. **Identify the version in use**: Check `package.json`, `requirements.txt`,
+   `Cargo.toml`, etc. for the exact version of the dependency you’re investigating.
+
+4. **Clone the repo**:
+   ```bash
+   git clone <repo-url> attic/<repo-name>
+   ```
+
+5. **Checkout the matching version**: Find the tag or branch matching your project’s
+   version:
+   ```bash
+   cd attic/<repo-name>
+   git tag -l | grep <version>   # Find matching tag
+   git checkout <tag-or-branch>
+   ```
+
+6. **Explore**: Now use standard tools (Grep, Read, Glob) to investigate the source.
+
+## Notes
+
+- The `attic/` directory is gitignored—cloned repos won’t pollute your project
+- You can clone multiple repos into attic/ as needed
+- Delete cloned repos when done to save disk space

package/dist/docs/shortcuts/standard/{cleanup-all.md → code-cleanup-all.md}

@@ -1,6 +1,7 @@
 ---
 title: Clean Up All Code
 description: Full cleanup cycle including duplicate removal, dead code, and code quality improvements
+category: cleanup
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # Shortcut: Clean Up Code
@@ -52,9 +53,9 @@ cycle afterwords, fixing all build or test issues.
    - Review types and eliminate use of optional types as possible so we don’t spread
      state checks throughout the codebase.
 
-7. **Remove trivial tests**: Follow `tbd shortcut cleanup-remove-trivial-tests`.
+7. **Remove trivial tests**: Follow `tbd shortcut code-cleanup-tests`.
 
-8. **Update docstrings**: Follow `tbd shortcut cleanup-update-docstrings`.
+8. **Update docstrings**: Follow `tbd shortcut code-cleanup-docstrings`.
 
 9. **Consolidate constants and settings**: Determine what files hold shared settings
    (such as `settings.ts` or similar).

package/dist/docs/shortcuts/standard/{cleanup-update-docstrings.md → code-cleanup-docstrings.md}

@@ -1,6 +1,7 @@
 ---
 title: "Cleanup: Update Docstrings"
 description: Review and add concise docstrings to major functions and types
+category: cleanup
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # Shortcut: Update Docstrings

package/dist/docs/shortcuts/standard/{cleanup-remove-trivial-tests.md → code-cleanup-tests.md}

@@ -1,6 +1,7 @@
 ---
 title: "Cleanup: Remove Trivial Tests"
 description: Review and remove tests that do not add meaningful coverage
+category: cleanup
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # Shortcut: Remove Trivial Tests