get-tbd 0.1.13 → 0.1.14

package/dist/docs/README.md

@@ -1,7 +1,6 @@
 # tbd
 
-**Task management, spec-driven planning, and instant knowledge injection for AI coding
-agents.**
+**Task tracking, spec-driven planning, and knowledge injection for AI coding agents.**
 
 **tbd** (short for “To Be Done,” or “TypeScript beads” if you prefer) combines four
 things that are each powerful on their own but work even better together:
@@ -138,7 +137,7 @@ status or context or knowledge and know what to do next:
 | "Let's work on current beads" | Agent finds ready beads and starts working | `tbd ready` |
 | "Review this code" | Agent performs comprehensive code review with all guidelines | [`tbd shortcut review-code`](packages/tbd/docs/shortcuts/standard/review-code.md) |
 | "Review this PR" | Agent reviews a GitHub pull request and can comment/fix | [`tbd shortcut review-github-pr`](packages/tbd/docs/shortcuts/standard/review-github-pr.md) |
-| "Use the shortcut to commit" | Agent runs full pre-commit checks, code review, and commits | [`tbd shortcut commit-code`](packages/tbd/docs/shortcuts/standard/commit-code.md) |
+| "Use the shortcut to commit" | Agent runs full pre-commit checks, code review, and commits | [`tbd shortcut code-review-and-commit`](packages/tbd/docs/shortcuts/standard/code-review-and-commit.md) |
 | "Create a PR" | Agent creates or updates the pull request | [`tbd shortcut create-or-update-pr-simple`](packages/tbd/docs/shortcuts/standard/create-or-update-pr-simple.md) |
 | "Let's create a research brief on …" | Agent creates a research document using a template | [`tbd shortcut new-research-brief`](packages/tbd/docs/shortcuts/standard/new-research-brief.md) |
 | "How could we test this better?" | Agent loads TDD and testing guidelines | [`tbd guidelines general-tdd-guidelines`](packages/tbd/docs/guidelines/general-tdd-guidelines.md) |
@@ -168,7 +167,7 @@ You just talk naturally.
   [FAQ: How does `tbd` compare to Beads?](#how-does-tbd-compare-to-beads)).
 - **Shortcuts:** Over a dozen reusable workflow documents—plan specs, code reviews,
   commit processes, PR creation, research briefs, and more.
-- **Guidelines:** [17+ guideline docs](packages/tbd/docs/guidelines/) of coding rules
+- **Guidelines:** [20+ guideline docs](packages/tbd/docs/guidelines/) of coding rules
   and best practices (see
   [Built-in Engineering Knowledge](#built-in-engineering-knowledge)).
 - **Templates:** Document templates for planning specs, research briefs, architecture
@@ -213,7 +212,7 @@ And yes, all the code *and* all the specs of `tbd` are agent written—see
 ## Built-in Engineering Knowledge
 
 When you run `tbd setup`, your agent gets instant access to
-[17+ guideline documents](packages/tbd/docs/guidelines/) covering real-world engineering
+[20+ guideline documents](packages/tbd/docs/guidelines/) covering real-world engineering
 practices. These aren’t generic tips; they’re mostly my own detailed and sometimes
 opinionated rules with concrete examples, built from months of heavy agentic coding.
 
@@ -237,6 +236,7 @@ opinionated rules with concrete examples, built from months of heavy agentic cod
 | [typescript-rules](packages/tbd/docs/guidelines/typescript-rules.md) | Strict type safety, no `any`, type guards, null safety, async patterns |
 | [typescript-monorepo-patterns](packages/tbd/docs/guidelines/typescript-monorepo-patterns.md) | pnpm workspaces, package setup, tsdown, Changesets, publint, dual ESM/CJS |
 | [typescript-cli-tool-rules](packages/tbd/docs/guidelines/typescript-cli-tool-rules.md) | Commander.js patterns, picocolors, terminal formatting |
+| [typescript-yaml-handling-rules](packages/tbd/docs/guidelines/typescript-yaml-handling-rules.md) | YAML parsing/serialization with the `yaml` package, Zod validation, consistent formatting |
 | [python-rules](packages/tbd/docs/guidelines/python-rules.md) | Type hints, docstrings, exception handling, resource management |
 | [python-cli-patterns](packages/tbd/docs/guidelines/python-cli-patterns.md) | Modern Python CLI stack: uv, Typer, Rich, Ruff, BasedPyright |
 | [backward-compatibility-rules](packages/tbd/docs/guidelines/backward-compatibility-rules.md) | Compatibility across code, APIs, file formats, and database schemas |
@@ -267,7 +267,7 @@ npm install -g get-tbd@latest
 ### Setup
 
 ```bash
-# Fresh project (--prefix is REQUIRED—it appears in every bead ID, e.g. myapp-a1b2)
+# Fresh project (--prefix is REQUIRED—2-8 alphabetic chars, e.g. myapp-a1b2)
 tbd setup --auto --prefix=myapp
 
 # Joining an existing tbd project (no prefix needed—reads existing config)
@@ -388,26 +388,39 @@ tbd template --add=<url> --name=<name>
 
 **Available shortcuts:**
 
-| Shortcut | Purpose |
-| --- | --- |
-| `new-plan-spec` | Create a feature planning spec |
-| `new-research-brief` | Create a research document |
-| `new-architecture-doc` | Create an architecture document |
-| `new-validation-plan` | Create a test/validation plan |
-| `plan-implementation-with-beads` | Break a spec into implementation beads |
-| `implement-beads` | Implement beads from a spec |
-| `review-code` | Comprehensive code review (uncommitted, branch, or PR) |
-| `review-github-pr` | Review a GitHub PR with commenting and CI checks |
-| `review-code-typescript` | TypeScript-focused code review |
-| `review-code-python` | Python-focused code review |
-| `precommit-process` | Pre-commit review and testing |
-| `commit-code` | Commit with pre-commit checks |
-| `create-or-update-pr-simple` | Basic PR creation |
-| `create-or-update-pr-with-validation-plan` | PR with a validation plan |
+| Category | Shortcut | Purpose |
+| --- | --- | --- |
+| **Planning** | `new-plan-spec` | Create a feature planning spec |
+|  | `plan-implementation-with-beads` | Break a spec into implementation beads |
+|  | `implement-beads` | Implement beads from a spec |
+|  | `new-validation-plan` | Create a test/validation plan |
+|  | `update-specs-status` | Review active specs and sync with tbd issues |
+| **Documentation** | `new-research-brief` | Create a research document |
+|  | `new-architecture-doc` | Create an architecture document |
+|  | `revise-architecture-doc` | Update an architecture doc to match current code |
+|  | `revise-all-architecture-docs` | Revise all current architecture documents |
+| **Review** | `review-code` | Comprehensive code review (uncommitted, branch, or PR) |
+|  | `review-github-pr` | Review a GitHub PR with commenting and CI checks |
+|  | `review-code-typescript` | TypeScript-focused code review |
+|  | `review-code-python` | Python-focused code review |
+| **Git** | `precommit-process` | Pre-commit review and testing |
+|  | `code-review-and-commit` | Commit with pre-commit checks |
+|  | `create-or-update-pr-simple` | Basic PR creation |
+|  | `create-or-update-pr-with-validation-plan` | PR with a validation plan |
+|  | `merge-upstream` | Merge origin/main with conflict resolution |
+| **Cleanup** | `code-cleanup-all` | Full code cleanup (duplicates, dead code, quality) |
+|  | `code-cleanup-tests` | Remove trivial/low-value tests |
+|  | `code-cleanup-docstrings` | Add docstrings to major functions |
+| **Session** | `agent-handoff` | Generate handoff prompt for another agent |
+|  | `welcome-user` | Welcome message after tbd installation |
+|  | `setup-github-cli` | Ensure GitHub CLI is installed and working |
+|  | `sync-failure-recovery` | Handle tbd sync failures |
+| **Meta** | `new-guideline` | Create a new coding guideline for tbd |
+|  | `new-shortcut` | Create a new shortcut for tbd |
 
 **Available guidelines:** See
 [Built-in Engineering Knowledge](#built-in-engineering-knowledge) for the full list of
-17+ guidelines covering TypeScript, Python, testing, TDD, and more.
+20+ guidelines covering TypeScript, Python, testing, TDD, and more.
 
 **Available templates:**
 
@@ -564,7 +577,7 @@ $
 
 ### Can I add my own guidelines?
 
-Yes. `tbd` comes with 17+ bundled guidelines, but you can add your own team’s docs from
+Yes. `tbd` comes with 20+ bundled guidelines, but you can add your own team’s docs from
 any URL:
 
 ```bash

package/dist/docs/SKILL.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
 ---
 
@@ -18,16 +25,19 @@ description: Full tbd workflow guide for agents
 
 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. **Shortcuts**: Reusable instruction templates for common workflows.
-4. **Guidelines**: Coding rules and best practices.
+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=<name>   # Fresh project (--prefix is REQUIRED and should be short. For new project setup, ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
+tbd setup --auto --prefix=<name>   # 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
 ```
@@ -60,20 +70,42 @@ or want help → run `tbd shortcut welcome-user`
 
 | User Says | You (the Agent) Run |
 | --- | --- |
+| **Issues/Beads** |  |
 | "There's a bug where ..." | `tbd create "..." --type=bug` |
-| "Let's work on issues" | `tbd ready` |
-| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
-| "Improve eslint/monorepo" | `tbd guidelines typescript-monorepo-patterns` |
-| "Add e2e/golden testing" | `tbd guidelines golden-testing-guidelines` |
-| "Review changes" (TS) | `tbd guidelines typescript-rules` |
-| "Review changes" (Python) | `tbd guidelines python-rules` |
-| "Plan a new feature" | `tbd shortcut new-plan-spec` |
+| "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 <id>` |
+| "Close this issue" | `tbd close <id>` |
+| "Search issues for X" | `tbd search "X"` |
+| "Add label X to issue" | `tbd label add <id> <label>` |
+| "What issues are stale?" | `tbd stale` |
+| **Planning & Specs** |  |
+| "Plan a new feature" / "Create a spec" | `tbd shortcut new-plan-spec` |
 | "Break spec into beads" | `tbd shortcut plan-implementation-with-beads` |
 | "Implement these beads" | `tbd shortcut implement-beads` |
-| "Commit this" | `tbd shortcut commit-code` |
-| "Create a PR" | `tbd shortcut create-or-update-pr-simple` |
+| **Code Review & Commits** |  |
+| "Review this code" / "Code review" | `tbd shortcut review-code` |
+| "Review this PR" | `tbd shortcut review-github-pr` |
+| "Commit this" / "Use the commit shortcut" | `tbd shortcut code-review-and-commit` |
+| "Create a PR" / "File a PR" | `tbd shortcut create-or-update-pr-simple` |
+| "Merge main into my branch" | `tbd shortcut merge-upstream` |
+| **Guidelines & Knowledge** |  |
+| "Use TypeScript best practices" | `tbd guidelines typescript-rules` |
+| "Use Python best practices" | `tbd guidelines python-rules` |
+| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
+| "Improve monorepo setup" | `tbd guidelines typescript-monorepo-patterns` |
+| "Add golden/e2e testing" | `tbd guidelines golden-testing-guidelines` |
+| "Use TDD" / "Test-driven development" | `tbd guidelines general-tdd-guidelines` |
+| "Convex best practices" | `tbd guidelines convex-rules` |
+| **Documentation** |  |
 | "Research this topic" | `tbd shortcut new-research-brief` |
 | "Document architecture" | `tbd shortcut new-architecture-doc` |
+| **Cleanup & Maintenance** |  |
+| "Clean up this code" / "Remove dead code" | `tbd shortcut code-cleanup-all` |
+| "Fix repository problems" | `tbd doctor --fix` |
+| **Sessions & Handoffs** |  |
+| "Hand off to another agent" | `tbd shortcut agent-handoff` |
+| "Check out this library's source" | `tbd shortcut checkout-third-party-repo` |
 | *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
 
 ## CRITICAL: Session Closing Protocol
@@ -127,6 +159,17 @@ or want help → run `tbd shortcut welcome-user`
 | `tbd sync` | Sync with git remote (run at session end) |
 | `tbd stats` | Project statistics |
 | `tbd doctor` | Check for problems |
+| `tbd doctor --fix` | Auto-fix repository problems |
+
+### Labels & Search
+
+| Command | Purpose |
+| --- | --- |
+| `tbd search <query>` | Search issues by text |
+| `tbd label add <id> <label>` | Add label to issue |
+| `tbd label remove <id> <label>` | Remove label from issue |
+| `tbd label list` | List all labels in use |
+| `tbd stale` | List issues not updated recently |
 
 ### Documentation
 

package/dist/docs/guidelines/cli-agent-skill-patterns.md

@@ -183,6 +183,15 @@ This minimizes token overhead while maintaining full capability.
 Skill activation relies on **pure LLM reasoning**, not keyword matching or embeddings.
 Description quality directly impacts activation reliability.
 
+**Activation Reliability Data** (from real-world testing across 200+ prompts):
+
+| Approach | Success Rate |
+| --- | --- |
+| No optimization / vague descriptions | ~20% |
+| Optimized descriptions with "Use when..." | ~50% |
+| Descriptions with concrete examples | 72-90% |
+| Forced evaluation hooks | 80-84% |
+
 **The Two-Part Rule**: Every description must answer:
 
 1. **What does it do?** (capabilities)
@@ -206,9 +215,55 @@ description: >
 **Writing Guidelines**:
 
 - Use third person always ("Processes files" not “I can help you”)
-- Include explicit trigger phrases reflecting user language
+- Include explicit “Use when …” triggers with concrete scenarios
 - Be specific with keywords users would naturally say
 - State both capabilities AND activation conditions
+- Front-load the most important trigger keywords in the first 50 characters
+  (descriptions may be truncated in large skill collections)
+
+### 2.4 Description Length and Budget Constraints
+
+Claude Code has a **cumulative character budget** for all skill descriptions combined.
+Understanding these limits is critical for CLIs that install multiple skills.
+
+**Hard Limits**:
+
+| Constraint | Limit | Notes |
+| --- | --- | --- |
+| Individual description | 1,024 characters | Per-skill maximum |
+| Skill name | 64 characters | Lowercase, numbers, hyphens only |
+| SKILL.md body | ~500 lines | Soft limit; use supporting files for more |
+| **Cumulative budget** | ~15,000-16,000 chars | For ALL skill descriptions combined |
+
+**Per-Skill Overhead**: Each skill consumes ~109 characters of XML overhead (tags, name,
+location) plus the description length.
+
+**Truncation Behavior**: When the cumulative budget is exceeded, skills are hidden:
+
+| Skills Installed | Skills Visible | Hidden |
+| --- | --- | --- |
+| 63 | 42 | 33% |
+| 92 | 36 | 60% |
+
+**No warning is shown** when skills are truncated.
+Run `/context` to check for excluded skills.
+
+**Description Length Guidelines by Collection Size**:
+
+| Skill Collection Size | Recommended Description Length |
+| --- | --- |
+| < 40 skills | Up to 1,024 characters (full limit) |
+| 40-60 skills | ≤150 characters |
+| 60+ skills | ≤130 characters |
+
+**Override**: Set `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable to increase the
+limit.
+
+**Meta-Skill Pattern**: For CLIs with many resources (50+), use a single meta-skill that
+exposes resources via CLI commands rather than individual skills.
+This consumes only one description slot (~200 chars) instead of 50+ slots that would
+exceed the budget. See
+[Skills vs Meta-Skill Architecture Research](../../project/research/current/research-skills-vs-meta-skill-architecture.md).
 
 * * *
 
@@ -351,7 +406,7 @@ resource name. This removes friction for agents.
 
 ```markdown
 ## Available Shortcuts
-- commit-code
+- code-review-and-commit
 - create-or-update-pr-simple
 - new-plan-spec
 ```
@@ -363,7 +418,7 @@ resource name. This removes friction for agents.
 
 | Command | Purpose | Description |
 |---------|---------|-------------|
-| `mycli shortcut commit-code` | Commit Code | How to run pre-commit checks and commit |
+| `mycli shortcut code-review-and-commit` | Commit Code | How to run pre-commit checks and commit |
 | `mycli shortcut create-pr` | Create PR | How to create a pull request |
 | `mycli shortcut new-plan-spec` | Plan Feature | How to create a planning specification |
 ```
@@ -642,6 +697,10 @@ Understanding when to use each is critical.
     + When to use it?
 11. **Write in third person**: “Processes files” not “I can help you”
 12. **Include explicit trigger phrases**: Match how users naturally describe needs
+13. **Front-load keywords**: Put most important triggers in first 50 characters
+14. **Respect cumulative budget**: All descriptions share a ~15K character limit
+15. **Use meta-skill pattern for 50+ resources**: One skill + CLI beats 50 individual
+    skills
 
 ### Self-Documentation
 
@@ -715,7 +774,17 @@ Understanding when to use each is critical.
 
 - [ ] Two-part description: capabilities + activation triggers
 - [ ] Third-person language only
-- [ ] Explicit trigger phrases matching user language
+- [ ] Explicit “Use when …” trigger phrases matching user language
+- [ ] Front-load important keywords in first 50 characters
+- [ ] Description length appropriate for skill collection size (≤130 chars for 60+
+  skills)
+
+**Budget Management** (for CLIs installing multiple skills)
+
+- [ ] Calculate cumulative description size (descriptions + ~109 chars overhead each)
+- [ ] Verify total stays under 15K character budget
+- [ ] Use meta-skill pattern if resources exceed 50
+- [ ] Run `/context` to verify skills aren’t being truncated
 
 **Context Management**
 
@@ -776,6 +845,10 @@ Understanding when to use each is critical.
 - Claude Code Skills Guide (Gist):
   https://gist.github.com/mellanon/50816550ecb5f3b239aa77eef7b8ed8d
 - Awesome Claude Skills: https://github.com/travisvn/awesome-claude-skills
+- Skills Character Budget Research:
+  https://github.com/anthropics/claude-code/issues/11045
+- Skill Activation Reliability Testing:
+  https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably
 
 ### MCP Resources
 

package/dist/docs/guidelines/error-handling-rules.md

@@ -446,6 +446,51 @@ catch (e) {
 
 **Tip**: Use `Error.cause` (ES2022) to chain errors without losing the original.
 
+### Anti-Pattern 9: Catch-and-Replace with Generic Error
+
+**The pattern**: Catching an exception and throwing a new generic error that loses the
+original message and stack trace.
+
+```typescript
+// ❌ BAD: Original error details lost
+try {
+  dataCtx = await loadDataContext(tbdRoot);
+  issues = await listIssues(dataCtx.dataSyncDir);
+} catch {
+  throw new CLIError('Failed to read issues');
+}
+// User sees: "Error: Failed to read issues"
+// Actual error was: "Implicit keys need to be on a single line at line 1..."
+// (YAML parse error due to merge conflict markers in file)
+```
+
+**Why it happens**: Developer wants to “clean up” the error message for users, assuming
+the original error is too technical.
+But this makes debugging impossible—the user can’t report the real problem, and even
+`--debug` mode shows nothing useful.
+
+**The fix**: Let errors propagate naturally, or include the original message.
+
+```typescript
+// ✅ GOOD: Let errors propagate (preferred for most cases)
+const dataCtx = await loadDataContext(tbdRoot);
+const issues = await listIssues(dataCtx.dataSyncDir);
+// Errors propagate to central handler which shows message + stack in debug mode
+
+// ✅ GOOD: If you must catch, preserve the original message
+try {
+  dataCtx = await loadDataContext(tbdRoot);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  throw new CLIError(`Failed to load data: ${message}`, { cause: error });
+}
+```
+
+**Key insight**: The central error handler should add debug info (stack traces,
+context).
+Individual commands should not catch-and-replace unless adding genuinely useful
+context.
+
 ## Error Messages
 
 ### Make Errors Actionable
@@ -495,3 +540,24 @@ When implementing any operation that can fail:
 | Optimistic success | Search for success messages, trace back to verify guards |
 | Catch-and-continue | Audit catch blocks that log but don't throw/return |
 | Lost exception context | Grep for `new Error.*\.message` (wrapping without cause) |
+| Catch-and-replace | Grep for `} catch {` followed by `throw new` (bare catch discards error) |
+
+### Finding Catch-and-Replace Anti-Pattern
+
+This command finds catch blocks that throw new errors without using the original:
+
+```bash
+# Find catch blocks that throw new errors without capturing the original
+grep -rn -A2 "} catch {" --include="*.ts" | grep -B1 "throw new"
+```
+
+**What to look for**: Any `} catch {` (no error variable) followed by
+`throw new SomeError`. This means the original error is discarded.
+
+**Acceptable patterns**:
+- `throw new NotFoundError('Entity', id)` - Transforming “not found” to semantic error
+- `throw new NotInitializedError(...)` - Expected failure with clear guidance
+
+**Problematic patterns**:
+- `throw new CLIError('Failed to do X')` - Loses WHY it failed
+- `throw new Error('Operation failed')` - Generic message hides root cause

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
+```