Imported from jlevy/markform (AGENTS.md). Install upstream with npx skills add jlevy/markform. Copyright stays with the author.

IMPORTANT: You MUST read ./docs/development.md and ./docs/docs-overview.md for project documentation. (This project uses Speculate project structure.)

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

File issues for remaining work - Create issues for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

PUSH TO REMOTE - This is MANDATORY:

git pull --rebase
git add .beads/issues.jsonl   # Include issue changes
git commit -m "..." --amend   # Or new commit if needed
git push
git status  # MUST show "up to date with origin"

Clean up - Clear stashes, prune remote branches
Verify - All changes committed AND pushed
Hand off - Provide context for next session

CRITICAL RULES:

Work is NOT complete until git push succeeds
NEVER stop before pushing - that leaves work stranded locally
NEVER say “ready to push when you are” - YOU must push
If push fails, resolve and retry until it succeeds
Do NOT run bd sync - this project uses no-db mode (JSONL is the database)

title: tbd Workflow

description: Full tbd workflow guide for agents

tbd helps humans and agents ship code with greater speed, quality, and discipline.

Beads: Git-native issue tracking (tasks, bugs, features). Never lose work across sessions. Drop-in replacement for bd.
Spec-Driven Workflows: Plan features → break into beads → implement systematically.
Knowledge Injection: 17+ engineering guidelines (TypeScript, Python, TDD, testing, Convex, monorepos) available on demand.
Shortcuts: Reusable instruction templates for common workflows (code review, commits, PRs, cleanup, handoffs).

Installation

npm install -g get-tbd@latest
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

Routine Commands

tbd --help    # Command reference
tbd status    # Status
tbd doctor    # If there are problems

tbd setup --auto   # Run any time to refresh setup
tbd prime      # Restore full context on tbd after compaction

CRITICAL: You Operate tbd — The User Doesn’t

You are the tbd operator: Users talk naturally; you translate their requests to tbd actions. DO NOT tell users to run tbd commands. That’s your job.

WRONG: “Run tbd create to track this bug”
RIGHT: (you run tbd create yourself and tell the user it’s tracked)

Welcoming a user: When users ask “what is tbd?” or want help → run tbd shortcut welcome-user

User Request → Agent Action

User Says	You (the Agent) Run
Issues/Beads
“There’s a bug where …”	`tbd create "..." --type=bug`
“Create a task/feature for …”	`tbd create "..." --type=task` or `--type=feature`
“Let’s work on issues/beads”	`tbd ready`
“Show me issue X”	`tbd show <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`
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

Before saying “done”, you MUST complete this checklist:

[ ] 1. git add + git commit
[ ] 2. git push
[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
[ ] 4. tbd close/update <id> for all beads worked on
[ ] 5. tbd sync
[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)

Work is not done until pushed, CI passes, and tbd is synced.

Bead Tracking Rules

Track all task work not done immediately as beads (discovered work, TODOs, multi-session work)
When in doubt, create a bead
Check tbd ready when not given specific directions
Always close/update beads and run tbd sync at session end

Commands

Finding Work

Command	Purpose
`tbd ready`	Beads ready to work (no blockers)
`tbd list --status open`	All open beads
`tbd list --status in_progress`	Your active work
`tbd show <id>`	Bead details with dependencies

Creating & Updating

Command	Purpose
`tbd create "title" --type task\|bug\|feature --priority=P2`	New bead (P0-P4, not “high/medium/low”)
`tbd update <id> --status in_progress`	Claim work
`tbd close <id> [--reason "..."]`	Mark complete

Dependencies & Sync

Command	Purpose
`tbd dep add <bead> <depends-on>`	Add dependency
`tbd blocked`	Show blocked beads
`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

Command	Purpose
`tbd shortcut <name>`	Run a shortcut
`tbd shortcut --list`	List shortcuts
`tbd guidelines <name>`	Load coding guidelines
`tbd guidelines --list`	List guidelines
`tbd template <name>`	Output a template

Quick Reference

Priority: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
Types: task, bug, feature, epic
Status: open, in_progress, closed
JSON output: Add --json to any command

Available Shortcuts

Run tbd shortcut <name> to use any of these shortcuts:

Name	Description
agent-handoff	Generate a concise handoff prompt for another coding agent to continue work
checkout-third-party-repo	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).
code-cleanup-all	Full cleanup cycle including duplicate removal, dead code, and code quality improvements
code-cleanup-docstrings	Review and add concise docstrings to major functions and types
code-cleanup-tests	Review and remove tests that do not add meaningful coverage
code-review-and-commit	Run pre-commit checks, review changes, and commit code
create-or-update-pr-simple	Create or update a pull request with a concise summary
create-or-update-pr-with-validation-plan	Create or update a pull request with a detailed test/validation plan
implement-beads	Implement beads from a spec, following TDD and project rules
merge-upstream	Merge origin/main into current branch with conflict resolution
new-architecture-doc	Create an architecture document for a system or component design
new-guideline	Create a new coding guideline document for tbd
new-plan-spec	Create a new feature planning specification document
new-research-brief	Create a research document for investigating a topic or technology
new-shortcut	Create a new shortcut (reusable instruction template) for tbd
new-validation-plan	Create a validation/test plan showing what’s tested and what remains
plan-implementation-with-beads	Create implementation beads from a feature planning spec
precommit-process	Full pre-commit checklist including spec sync, code review, and testing
review-code	Comprehensive code review for uncommitted changes, branch work, or GitHub PRs
review-code-python	Python-focused code review (language-specific rules only)
review-code-typescript	TypeScript-focused code review (language-specific rules only)
review-github-pr	Review a GitHub pull request with follow-up actions (comment, fix, CI check)
revise-all-architecture-docs	Comprehensive revision of all current architecture documents
revise-architecture-doc	Update an architecture document to reflect current codebase state
setup-github-cli	Ensure GitHub CLI (gh) is installed and working
sync-failure-recovery	Handle tbd sync failures by saving to workspace and recovering later
update-specs-status	Review active specs and sync their status with tbd issues
welcome-user	Welcome message for users after tbd installation or setup

Available Guidelines

Run tbd guidelines <name> to apply any of these guidelines:

Name	Description
backward-compatibility-rules	Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas
cli-agent-skill-patterns	Best practices for building TypeScript CLIs that function as agent skills in Claude Code and other AI coding agents
commit-conventions	Conventional Commits format with extensions for agentic workflows
convex-limits-best-practices	Comprehensive reference for Convex platform limits, workarounds, and performance best practices
convex-rules	Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples
error-handling-rules	Rules for handling errors, failures, and exceptional conditions
general-coding-rules	Rules for constants, magic numbers, and general coding practices
general-comment-rules	Language-agnostic rules for writing clean, maintainable comments
general-eng-assistant-rules	Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines
general-style-rules	Style guidelines for auto-formatting, emoji usage, and output formatting
general-tdd-guidelines	Test-Driven Development methodology and best practices
general-testing-rules	Rules for writing minimal, effective tests with maximum coverage
golden-testing-guidelines	Guidelines for implementing golden/snapshot testing for complex systems
python-cli-patterns	Modern patterns for Python CLI application architecture
python-modern-guidelines	Guidelines for modern Python projects using uv, with a few more opinionated practices
python-rules	General Python coding rules and best practices
release-notes-guidelines	Guidelines for writing clear, accurate release notes
sync-troubleshooting	Common issues and solutions for tbd sync and workspace operations
typescript-cli-tool-rules	Rules for building CLI tools with Commander.js, picocolors, and TypeScript
typescript-code-coverage	Best practices for code coverage in TypeScript with Vitest and v8 provider
typescript-monorepo-patterns	Modern patterns for TypeScript monorepo architecture
typescript-rules	TypeScript coding rules and best practices
typescript-yaml-handling-rules	Best practices for parsing and serializing YAML in TypeScript

markform

About