From d301c7b4f33d478e68142a36e57e05b1eb8ef75a Mon Sep 17 00:00:00 2001 From: Kellan Drucquer Date: Fri, 3 Apr 2026 21:35:14 -0400 Subject: [PATCH] update AGENTS.md with updated beads usage guidelines --- AGENTS.md | 270 ++++++++++++------------ AGENT_INSTRUCTIONS(1).md | 428 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 564 insertions(+), 134 deletions(-) create mode 100644 AGENT_INSTRUCTIONS(1).md diff --git a/AGENTS.md b/AGENTS.md index 430799b..adc0842 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,186 +1,188 @@ -# AGENTS.md — Execution Guardrails for Codex +# Agent Instructions -This file defines **how Codex should think, act, and prioritize** when working in this repository. -Its purpose is to keep development **focused, correct, and non-drifting**. +See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions. -If there is any conflict between speed and correctness, **correctness wins**. +This file exists for compatibility with tools that look for AGENTS.md. ---- +## Key Sections -## Mission +- **Issue Tracking** - How to use bd for work management +- **Development Guidelines** - Code standards and testing +- **Visual Design System** - Status icons, colors, and semantic styling for CLI output -Build a **real-time, non-delayed options flow and off-exchange trade analysis platform** for personal use that is: +## Visual Design Anti-Patterns -- explainable -- deterministic -- replayable -- microstructure-correct -- low-latency -- built on **Bun** +**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. They cause cognitive overload. -Codex is an **engineering executor**, not a product visionary. -Do not invent scope. Do not “improve” the plan. Implement it faithfully. +**ALWAYS use small Unicode symbols** with semantic colors: +- Status: `○ ◐ ● ✓ ❄` +- Priority: `● P0` (filled circle with color) ---- +See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines. -## Non-Negotiable Constraints +## Agent Warning: Interactive Commands -- **Bun is mandatory** - - Use Bun for runtime, package manager, scripts, and dev tooling. - - Do not introduce npm, yarn, pnpm, or Node-only assumptions. -- **TypeScript only** - - No JS-only files unless unavoidable (and document why). -- **No black-box logic** - - All classifiers must be rule-based and explainable. -- **Personal-use architecture** - - No multi-user assumptions. - - No redistribution mechanisms. -- **Deterministic pipelines** - - Live behavior must match replay behavior. +**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. -If a change violates any of the above, **do not implement it**. +Use `bd update` with flags instead: +```bash +bd update --description "new description" +bd update --title "new title" +bd update --design "design notes" +bd update --notes "additional notes" +bd update --acceptance "acceptance criteria" ---- +# Use stdin for descriptions with special characters (backticks, !, nested quotes) +echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=- +echo 'Updated text' | bd update --description=- +``` -## Source of Truth +## Testing Commands (No Ambiguity) -The authoritative documents are, in order: +- Default local test command: `make test` (or `./scripts/test.sh`). +- Full CGO-enabled suite: `make test-full-cgo` (or `./scripts/test-cgo.sh ./...`). +- On macOS, do **not** run raw `CGO_ENABLED=1 go test ./...` unless ICU flags are set; use the script/Make target above. +- If you need package- or test-scoped CGO runs: +```bash +./scripts/test-cgo.sh ./cmd/bd/... +./scripts/test-cgo.sh -run '^TestName$' ./cmd/bd/... +``` -1. `PLAN.md` -2. `AGENTS.md` -3. Code already merged into `main` +## Non-Interactive Shell Commands -If a request contradicts `PLAN.md`, Codex must **stop and ask for clarification**. +**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts. ---- +Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input. -## Development Rules +**Use these forms instead:** +```bash +# Force overwrite without prompting +cp -f source dest # NOT: cp source dest +mv -f source dest # NOT: mv source dest +rm -f file # NOT: rm file -### 1. Never Skip the Event Layer -- All incoming market data becomes **immutable events**. -- Never compute directly off live feeds without persisting the event. -- Never add UI-only logic that bypasses persisted data. +# For recursive operations +rm -rf directory # NOT: rm -r directory +cp -rf source dest # NOT: cp -r source dest +``` -### 2. Separate Fact from Inference -- Raw data (`OptionPrint`, `EquityPrint`) is **fact**. -- Classifiers and dark pool signals are **inference**. -- Store and label them separately. -- Never overwrite facts with inferred labels. +**Other commands that may prompt:** +- `scp` - use `-o BatchMode=yes` for non-interactive +- `ssh` - use `-o BatchMode=yes` to fail instead of prompting +- `apt-get` - use `-y` flag +- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var -### 3. Explainability Is Required -Every classifier must: -- have a unique ID -- expose its inputs -- produce a human-readable explanation string -- link back to evidence prints +## Landing the Plane (Session Completion) -If an alert cannot explain itself, it is invalid. +**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. -### 4. Favor Simple, Explicit Logic -- Prefer clear thresholds over clever heuristics. -- Avoid premature ML or probabilistic tuning. -- If logic becomes complex, break it into named steps. +**MANDATORY WORKFLOW:** -This is a research system, not a trading bot. +1. **File issues for remaining work** - Create issues for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **PUSH TO REMOTE** - This is MANDATORY: + ```bash + git pull --rebase + git push + git status # MUST show "up to date with origin" + ``` +5. **Clean up** - Clear stashes, prune remote branches +6. **Verify** - All changes committed AND pushed +7. **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 -## Classifier Implementation Rules + +## Issue Tracking with bd (beads) -- Classifiers operate on **FlowPackets**, not raw prints. -- Each classifier: - - returns `{ confidence, direction, explanations[] }` - - contributes to alert scoring but does not decide alerts alone -- Never infer intent with certainty. -- Use language like: - - “likely” - - “suggests” - - “consistent with” -- Never use language like: - - “smart money” - - “institutional intent” - - “guaranteed” +**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. ---- +### Why bd? -## Time & Market Structure Rules +- Dependency-aware: Track blockers and relationships between issues +- Git-friendly: Dolt-powered version control with native sync +- Agent-optimized: JSON output, ready work detection, discovered-from links +- Prevents duplicate tracking systems and confusion -- Always join prints to NBBO using bounded time windows. -- Track and expose join quality (`nbbo_age_ms`, etc.). -- Explicitly handle: - - 0DTE - - low-liquidity contracts - - wide spreads -- If confidence is low, say so. +### Quick Start ---- +**Check for ready work:** -## Charting Rules +```bash +bd ready --json +``` -- Candles are built **server-side only**. -- Client never computes OHLC. -- Overlays must be viewport-aware and decimated. -- Performance beats decoration. +**Create new issues:** -If a chart stutters, reduce data density first—not visual quality. +```bash +bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json +bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json ---- +# Use stdin for descriptions with special characters (backticks, !, nested quotes) +echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=- --json +``` -## UI Rules +**Claim and update:** -- Prefer clarity over density. -- Every alert must be clickable to evidence. -- No “magic colors” without legend or explanation. -- Motion must feel physical, not flashy. +```bash +bd update --claim --json +bd update bd-42 --priority 1 --json +``` -UI exists to **inspect**, not to impress. +**Complete work:** ---- +```bash +bd close bd-42 --reason "Completed" --json +``` -## Observability & Safety +### Issue Types -- Add metrics alongside new pipelines. -- Log failures explicitly. -- Never silently drop events. -- During overload: - - persistence > compute > UI (in that priority order) +- `bug` - Something broken +- `feature` - New functionality +- `task` - Work item (tests, docs, refactoring) +- `epic` - Large feature with subtasks +- `chore` - Maintenance (dependencies, tooling) ---- +### Priorities -## What Codex Must NOT Do +- `0` - Critical (security, data loss, broken builds) +- `1` - High (major features, important bugs) +- `2` - Medium (default, nice-to-have) +- `3` - Low (polish, optimization) +- `4` - Backlog (future ideas) -- Do not invent new features or markets. -- Do not introduce predictive claims. -- Do not optimize prematurely. -- Do not refactor without reason. -- Do not replace explicit logic with ML. -- Do not broaden scope beyond personal use. +### Workflow for AI Agents ---- +1. **Check ready work**: `bd ready` shows unblocked issues +2. **Claim your task atomically**: `bd update --claim` +3. **Work on it**: Implement, test, document +4. **Discover new work?** Create linked issue: + - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:` +5. **Complete**: `bd close --reason "Done"` -## When to Stop and Ask +### Auto-Sync -Codex must pause and ask for guidance if: -- a data provider limitation blocks implementation -- licensing or entitlement assumptions change -- a requested change conflicts with `PLAN.md` -- a design decision affects determinism or replayability +bd automatically syncs via Dolt: ---- +- Each write auto-commits to Dolt history +- Use `bd dolt push`/`bd dolt pull` for remote sync +- No manual export/import needed! -## Definition of “Done” +### Important Rules -A task is done only when: -- it matches `PLAN.md` -- it compiles and runs under Bun -- it is deterministic -- it is explainable -- it is testable or replayable +- ✅ Use bd for ALL task tracking +- ✅ Always use `--json` flag for programmatic use +- ✅ Link discovered work with `discovered-from` dependencies +- ✅ Check `bd ready` before asking "what should I work on?" +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT use external issue trackers +- ❌ Do NOT duplicate tracking systems ---- +For more details, see README.md and docs/QUICKSTART.md. -## Final Reminder - -This system is built to **understand markets**, not to mythologize them. - -If something cannot be justified by observable data and clear logic, it does not belong here. + diff --git a/AGENT_INSTRUCTIONS(1).md b/AGENT_INSTRUCTIONS(1).md new file mode 100644 index 0000000..ff46d22 --- /dev/null +++ b/AGENT_INSTRUCTIONS(1).md @@ -0,0 +1,428 @@ +# Detailed Agent Instructions for Beads Development + +**For project overview and quick start, see [AGENTS.md](AGENTS.md)** + +This document contains detailed operational instructions for AI agents working on beads development, testing, and releases. + +## Development Guidelines + +### Code Standards + +- **Go version**: 1.24+ +- **Linting**: `golangci-lint run ./...` (baseline warnings documented in [docs/LINTING.md](docs/LINTING.md)) +- **Testing**: All new features need tests (`make test` for local baseline, `make test-full-cgo` when validating full CGO paths) +- **Documentation**: Update relevant .md files + +### File Organization + +``` +beads/ +├── cmd/bd/ # CLI commands +├── internal/ +│ ├── types/ # Core data types +│ └── storage/ # Storage layer +│ └── dolt/ # Dolt implementation +├── examples/ # Integration examples +└── *.md # Documentation +``` + +### Testing Workflow + +**IMPORTANT:** Never pollute the production database with test issues! + +**For manual testing**, use the `BEADS_DB` environment variable to point to a temporary database: + +```bash +# Create test issues in isolated database +BEADS_DB=/tmp/test.db bd init --quiet --prefix test +BEADS_DB=/tmp/test.db bd create "Test issue" -p 1 + +# Or for quick testing +BEADS_DB=/tmp/test.db bd create "Test feature" -p 1 +``` + +**For automated tests**, use `t.TempDir()` in Go tests: + +```go +func TestMyFeature(t *testing.T) { + tmpDir := t.TempDir() + testDB := filepath.Join(tmpDir, ".beads", "beads.db") + s := newTestStore(t, testDB) + // ... test code +} +``` + +**Git test isolation:** For tests that create temporary git repos, force repo-local hooks: + +```bash +git config core.hooksPath .git/hooks +``` + +Do not rely on the developer's global git config. Global `core.hooksPath` can leak +into temp repos and produce flaky test behavior. + +**Warning:** bd will warn you when creating issues with "Test" prefix in the production database. Always use `BEADS_DB` for manual testing. + +### Before Committing + +1. **Run tests**: `make test` (or `./scripts/test.sh`) + - For full CGO validation: `make test-full-cgo` +2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings) +3. **Update docs**: If you changed behavior, update README.md or other docs +4. **Commit**: With git hooks installed (`bd hooks install`), Dolt changes are auto-committed + +### Commit Message Convention + +When committing work for an issue, include the issue ID in parentheses at the end: + +```bash +git commit -m "Fix auth validation bug (bd-abc)" +git commit -m "Add retry logic for database locks (bd-xyz)" +``` + +This enables `bd doctor` to detect **orphaned issues** - work that was committed but the issue wasn't closed. The doctor check cross-references open issues against git history to find these orphans. + +### Git Workflow + +bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command). + +**Install git hooks** for automatic sync: +```bash +bd hooks install +``` + +### Git Integration + +**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No JSONL export/import needed. + +**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md). + +**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md). + +**Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution. + +## Git Workflow: Push to Main, Never PR + +Crew workers push directly to main. **Never create pull requests.** + +- `git push` to main is the only way to land work +- `gh pr create` is forbidden — PRs are for external contributors, not crew +- Do not create feature branches for your own work — commit and push to main +- When handling external PRs, use fix-merge: checkout the PR branch locally, + fix/rebase onto main, merge locally, `git push`, then close the PR + +This is enforced by pre-use hooks. If you try `gh pr create`, it will be blocked. + +## Landing the Plane + +**When the user says "let's land the plane"**, you MUST complete ALL steps below. The plane is NOT landed until `git push` succeeds. NEVER stop before pushing. NEVER say "ready to push when you are!" - that is a FAILURE. + +**MANDATORY WORKFLOW - COMPLETE ALL STEPS:** + +1. **File beads issues for any remaining work** that needs follow-up +2. **Ensure all quality gates pass** (only if code changes were made): + - Run `make lint` or `golangci-lint run ./...` (if pre-commit installed: `pre-commit run --all-files`) + - Run `make test` (and `make test-full-cgo` when CGO-relevant code changed) + - File P0 issues if quality gates are broken +3. **Update beads issues** - close finished work, update status +4. **PUSH TO REMOTE - NON-NEGOTIABLE** - This step is MANDATORY. Execute ALL commands below: + ```bash + # Pull first to catch any remote changes + git pull --rebase + + # MANDATORY: Push everything to remote + # DO NOT STOP BEFORE THIS COMMAND COMPLETES + git push + + # MANDATORY: Verify push succeeded + git status # MUST show "up to date with origin/main" + ``` + + **CRITICAL RULES:** + - The plane has NOT landed until `git push` completes successfully + - NEVER stop before `git push` - that leaves work stranded locally + - NEVER say "ready to push when you are!" - YOU must push, not the user + - If `git push` fails, resolve the issue and retry until it succeeds + - The user is managing multiple agents - unpushed work breaks their coordination workflow + +5. **Clean up git state** - Clear old stashes and prune dead remote branches: + ```bash + git stash clear # Remove old stashes + git remote prune origin # Clean up deleted remote branches + ``` +6. **Verify clean state** - Ensure all changes are committed AND PUSHED, no untracked files remain +7. **Choose a follow-up issue for next session** + - Provide a prompt for the user to give to you in the next session + - Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]" + +**REMEMBER: Landing the plane means EVERYTHING is pushed to remote. No exceptions. No "ready when you are". PUSH IT.** + +**Example "land the plane" session:** + +```bash +# 1. File remaining work +bd create "Add integration tests for sync" -t task -p 2 --json + +# 2. Run quality gates (only if code changes were made) +go test -short ./... +golangci-lint run ./... + +# 3. Close finished issues +bd close bd-42 bd-43 --reason "Completed" --json + +# 4. PUSH TO REMOTE - MANDATORY, NO STOPPING BEFORE THIS IS DONE +git pull --rebase +git push # MANDATORY - THE PLANE IS STILL IN THE AIR UNTIL THIS SUCCEEDS +git status # MUST verify "up to date with origin/main" + +# 5. Clean up git state +git stash clear +git remote prune origin + +# 6. Verify everything is clean and pushed +git status + +# 7. Choose next work +bd ready --json +bd show bd-44 --json +``` + +**Then provide the user with:** + +- Summary of what was completed this session +- What issues were filed for follow-up +- Status of quality gates (all passing / issues filed) +- Confirmation that ALL changes have been pushed to remote +- Recommended prompt for next session + +**CRITICAL: Never end a "land the plane" session without successfully pushing. The user is coordinating multiple agents and unpushed work causes severe rebase conflicts.** + +## Agent Session Workflow + +**WARNING: DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. Use `bd update` with flags instead: +```bash +bd update --description "new description" +bd update --title "new title" +bd update --design "design notes" +bd update --notes "additional notes" +bd update --acceptance "acceptance criteria" +``` + +**Use stdin for descriptions with special characters** (backticks, `!`, nested quotes): +```bash +# Pipe via stdin to avoid shell escaping issues +echo 'Description with `backticks` and "quotes"' | bd create "Title" --stdin +echo 'Updated description with $variables' | bd update --description=- + +# Or use --body-file for longer content +bd create "Title" --body-file=description.md +``` + +**Example agent session:** + +```bash +# Make changes (each write auto-commits to Dolt) +bd create "Fix bug" -p 1 +bd create "Add tests" -p 1 +bd update bd-42 --claim +bd close bd-40 --reason "Completed" + +# Push Dolt data to remote if configured +bd dolt push + +# Now safe to end session +``` + +This installs: + +- **pre-commit** — Commits pending Dolt changes +- **post-merge** — Pulls remote Dolt changes after git merge + +**Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users). + +## Common Development Tasks + +### CLI Design Principles + +**Minimize cognitive overload.** Every new command, flag, or option adds cognitive burden for users. Before adding anything: + +1. **Recovery/fix operations → `bd doctor --fix`**: Don't create separate commands like `bd recover` or `bd repair`. Doctor already detects problems - let `--fix` handle remediation. This keeps all health-related operations in one discoverable place. + For git hook marker migration specifically: use `bd migrate hooks --dry-run` to preview operations, and `bd doctor --fix` for the standard apply path. + +2. **Prefer flags on existing commands**: Before creating a new command, ask: "Can this be a flag on an existing command?" Example: `bd list --stale` instead of `bd stale`. + +3. **Consolidate related operations**: Related operations should live together. Version control uses `bd vc {log,diff,commit}`, not separate top-level commands. + +4. **Count the commands**: Run `bd --help` and count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping. + +5. **New commands need strong justification**: A new command should represent a fundamentally different operation, not just a convenience wrapper. + +### Adding a New Command + +1. Create file in `cmd/bd/` +2. Add to root command in `cmd/bd/main.go` +3. Implement with Cobra framework +4. Add `--json` flag for agent use +5. Add tests in `cmd/bd/*_test.go` +6. Document in README.md + +### Adding Storage Features + +1. Add Dolt SQL schema changes in `internal/storage/dolt/` +2. Add migration if needed +3. Update `internal/types/types.go` if new types +4. Implement in `internal/storage/dolt/` (queries, issues, etc.) +5. Add tests +6. Update export/import in `cmd/bd/export.go` and `cmd/bd/import.go` + +### Adding Examples + +1. Create directory in `examples/` +2. Add README.md explaining the example +3. Include working code +4. Link from `examples/README.md` +5. Mention in main README.md + +## Building and Testing + +```bash +# Build and install bd to ~/.local/bin (the canonical location) +make install + +# Test (local baseline) +make test + +# Test with full CGO-enabled suite (local/CI parity) +make test-full-cgo + +# Coverage run +go test -coverprofile=coverage.out ./... +go tool cover -html=coverage.out + +# Verify installed binary +bd init --prefix test +bd create "Test issue" -p 1 +bd ready +``` + +> **WARNING**: Do NOT use `go build -o bd ./cmd/bd` or `go install ./cmd/bd`. +> These create stale binaries in the working directory or `~/go/bin/` that +> shadow the canonical install at `~/.local/bin/bd`. Always use `make install`. + +## Version Management + +**IMPORTANT**: When the user asks to "bump the version" or mentions a new version number (e.g., "bump to 0.9.3"), use the version bump script: + +```bash +# Preview changes (shows diff, doesn't commit) +./scripts/bump-version.sh 0.9.3 + +# Auto-commit the version bump +./scripts/bump-version.sh 0.9.3 --commit +git push origin main +``` + +**What it does:** + +- Updates ALL version files (CLI, plugin, MCP server, docs) in one command +- Validates semantic versioning format +- Shows diff preview +- Verifies all versions match after update +- Creates standardized commit message + +**User will typically say:** + +- "Bump to 0.9.3" +- "Update version to 1.0.0" +- "Rev the project to 0.9.4" +- "Increment the version" + +**You should:** + +1. Run `./scripts/bump-version.sh --commit` +2. Push to GitHub +3. Confirm all versions updated correctly + +**Files updated automatically:** + +- `cmd/bd/version.go` - CLI version +- `claude-plugin/.claude-plugin/plugin.json` - Plugin version +- `.claude-plugin/marketplace.json` - Marketplace version +- `integrations/beads-mcp/pyproject.toml` - MCP server version +- `README.md` - Documentation version +- `PLUGIN.md` - Version requirements + +**Why this matters:** We had version mismatches (bd-66) when only `version.go` was updated. This script prevents that by updating all components atomically. + +See `scripts/README.md` for more details. + +## Release Process (Maintainers) + +**Automated (Recommended):** + +```bash +# One command to do everything (version bump, tests, tag, Homebrew update, local install) +./scripts/release.sh 0.9.3 +``` + +This handles the entire release workflow automatically, including waiting ~5 minutes for GitHub Actions to build release artifacts. See [scripts/README.md](scripts/README.md) for details. + +**Manual (Step-by-Step):** + +1. Bump version: `./scripts/bump-version.sh --commit` +2. Update CHANGELOG.md with release notes +3. Run tests: `make test` (and `make test-full-cgo` for CGO-related changes) +4. Push version bump: `git push origin main` +5. Tag release: `git tag v && git push origin v` +6. Update Homebrew: `./scripts/update-homebrew.sh ` (waits for GitHub Actions) +7. Verify: `brew update && brew upgrade beads && bd version` + +See [docs/RELEASING.md](docs/RELEASING.md) for complete manual instructions. + +## Checking GitHub Issues and PRs + +**IMPORTANT**: When asked to check GitHub issues or PRs, use command-line tools like `gh` instead of browser/playwright tools. + +**Preferred approach:** + +```bash +# List open issues with details +gh issue list --limit 30 + +# List open PRs +gh pr list --limit 30 + +# View specific issue +gh issue view 201 +``` + +**Then provide an in-conversation summary** highlighting: + +- Urgent/critical issues (regressions, bugs, broken builds) +- Common themes or patterns +- Feature requests with high engagement +- Items that need immediate attention + +**Why this matters:** + +- Browser tools consume more tokens and are slower +- CLI summaries are easier to scan and discuss +- Keeps the conversation focused and efficient +- Better for quick triage and prioritization + +**Do NOT use:** `browser_navigate`, `browser_snapshot`, or other playwright tools for GitHub PR/issue reviews unless specifically requested by the user. + +## Questions? + +- Check existing issues: `bd list` +- Look at recent commits: `git log --oneline -20` +- Read the docs: README.md, ADVANCED.md, EXTENDING.md +- Create an issue if unsure: `bd create "Question: ..." -t task -p 2` + +## Important Files + +- **README.md** - Main documentation (keep this updated!) +- **EXTENDING.md** - Database extension guide +- **ADVANCED.md** - Advanced features (rename, merge, compaction) +- **CONTRIBUTING.md** - Contribution guidelines +- **SECURITY.md** - Security policy