johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add agent-first 'bd onboard' command (bd-173)

Browse Source 
- Refactor bd onboard to output instructions instead of doing string replacement
- Leverage agent intelligence to naturally integrate bd into documentation
- Bootstrap via 'BEFORE ANYTHING ELSE: run bd onboard' in AGENTS.md
- Agent receives formatted instructions to update AGENTS.md and CLAUDE.md
- More agentic approach - adapts to existing project structure
- Update README with new bootstrap workflow

Amp-Thread-ID: https://ampcode.com/threads/T-d70fd1bf-8d44-48b6-bb55-5ae49efb23b8
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-10-20 15:04:33 -07:00
parent 01aeed6997
commit e10e34b221
5 changed files with 300 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.beads/issues.jsonl
View File

@@ -76,6 +76,8 @@
{"id":"bd-167","title":"Test issue with labels","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-19T22:42:23.516678-07:00","updated_at":"2025-10-19T22:47:07.915048-07:00","closed_at":"2025-10-19T22:46:09.247654-07:00"}
{"id":"bd-168","title":"Test with labels","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-19T22:43:56.761279-07:00","updated_at":"2025-10-19T22:47:07.915193-07:00","closed_at":"2025-10-19T22:46:09.24785-07:00","labels":["frontend"]}
{"id":"bd-17","title":"Improve session management","description":"Current session management is basic. Need to improve with better expiration handling.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.879664-07:00","closed_at":"2025-10-16T10:07:34.005199-07:00"}
{"id":"bd-172","title":"Fix MCP server None/null crashes in list/ready/stats","description":"","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-19T23:22:56.591289-07:00","updated_at":"2025-10-19T23:23:25.755169-07:00","closed_at":"2025-10-19T23:23:25.755169-07:00"}
{"id":"bd-173","title":"Add 'bd onboard' command to configure AGENTS.md for AI agents","description":"Create a 'bd onboard' command that automatically sets up AGENTS.md (and adds a note to CLAUDE.md if present) with instructions for AI agents to use beads instead of markdown TODOs.\n\nProblem: Users report that AI agents get confused between beads issue tracking and markdown-based planning, leading to duplicate tracking systems and confusion about which to use.\n\nSolution: Add 'bd onboard' command that:\n1. Appends (or creates) AGENTS.md with beads workflow instructions\n2. Includes command examples, issue types, priorities, and workflow\n3. Adds note to CLAUDE.md if it exists, directing agents to use beads\n4. Makes it clear agents should abandon markdown TODOs in favor of bd\n5. Idempotent - safe to run multiple times\n\nThe onboarding content should emphasize:\n- Use bd for ALL task tracking, not markdown TODOs\n- How to check ready work, create/update/close issues\n- When to use discovered-from dependencies\n- Priority and issue type conventions\n- Auto-sync behavior\n\nThis will reduce onboarding friction and prevent agents from creating parallel tracking systems.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-10-20T14:34:52.483607-07:00","updated_at":"2025-10-20T14:57:39.014109-07:00","closed_at":"2025-10-20T14:57:39.014109-07:00"}
{"id":"bd-18","title":"Fix: bd init --prefix test -q flag not recognized","description":"The init command doesn't recognize the -q flag. When running 'bd init --prefix test -q', it fails silently or behaves unexpectedly. The flag should either be implemented for quiet mode or removed from documentation if not supported.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.87987-07:00","closed_at":"2025-10-17T00:09:18.921816-07:00"}
{"id":"bd-19","title":"Implement storage driver interface for pluggable backends","description":"Create abstraction layer for storage to support multiple backends (SQLite, Postgres, Turso, in-memory testing, etc.).\n\n**Current state:** All storage logic hardcoded to SQLite in internal/storage/sqlite/sqlite.go\n\n**Proposed design:**\n\n```go\n// internal/storage/storage.go\ntype Store interface {\n // Issue CRUD\n CreateIssue(issue *Issue) error\n GetIssue(id string) (*Issue, error)\n UpdateIssue(id string, updates *Issue) error\n DeleteIssue(id string) error\n ListIssues(filter *Filter) ([]*Issue, error)\n \n // Dependencies\n AddDependency(from, to string, depType DependencyType) error\n RemoveDependency(from, to string, depType DependencyType) error\n GetDependencies(id string) ([]*Dependency, error)\n \n // Counters, stats\n GetNextID(prefix string) (string, error)\n GetStats() (*Stats, error)\n \n Close() error\n}\n```\n\n**Benefits:**\n- Better testing (mock/in-memory stores)\n- Future flexibility (Postgres, cloud APIs, etc.)\n- Clean architecture (business logic decoupled from storage)\n- Enable Turso or other backends without refactoring everything\n\n**Implementation steps:**\n1. Define Store interface in internal/storage/storage.go\n2. Refactor SQLiteStore to implement interface\n3. Update all commands to use interface, not concrete type\n4. Add MemoryStore for testing\n5. Add driver selection via config (storage.driver = sqlite|turso|postgres)\n6. Update tests to use interface\n\n**Note:** This is valuable even without adopting Turso. Good architecture practice.\n\n**Context:** From GH issue #2 RFC evaluation. Driver interface is low-cost, high-value regardless of whether we add alternative backends.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.880038-07:00","closed_at":"2025-10-17T23:46:22.447301-07:00"}
{"id":"bd-2","title":"Sub-task under A","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.876832-07:00","closed_at":"2025-10-16T10:07:34.130096-07:00"}
@@ -88,7 +90,7 @@
{"id":"bd-26","title":"Add EXPLAIN QUERY PLAN tests for ready work query","description":"Verify that the hierarchical blocking query uses proper indexes and doesn't do full table scans.\n\n**Queries to analyze:**\n1. The recursive CTE (both base case and recursive case)\n2. The final SELECT with NOT EXISTS\n3. Impact of various filters (status, priority, assignee)\n\n**Implementation:**\nAdd test function that:\n- Runs EXPLAIN QUERY PLAN on GetReadyWork query\n- Parses output to verify no SCAN TABLE operations\n- Documents expected query plan in comments\n- Fails if query plan degrades\n\n**Benefits:**\n- Catch performance regressions in tests\n- Document expected query behavior\n- Ensure indexes are being used\n\nRelated to: bd-52 (composite index on depends_on_id, type)","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.915924-07:00","closed_at":"2025-10-18T12:47:44.284846-07:00"}
{"id":"bd-27","title":"Add performance benchmarks document","description":"Document actual performance metrics with hyperfine tests","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.881528-07:00","closed_at":"2025-10-18T10:09:23.532938-07:00"}
{"id":"bd-28","title":"Investigate vector/semantic search for issue discovery","description":"From GH issue #2 RFC discussion: Evaluate if vector/semantic search over issues would provide value for beads.\n\n**Use case:** Find semantically related issues (e.g., 'login broken' finds 'authentication failure', 'session expired').\n\n**Questions to answer:**\n1. What workflows would this enable that we can't do now?\n2. Is dataset size (typically 50-200 issues) large enough to benefit?\n3. Do structured features (deps, tags, types) already provide better relationships?\n4. What's the maintenance cost (embeddings, storage, recomputation)?\n\n**Alternatives to consider:**\n- Improve 'bd list' filtering with regex/boolean queries\n- Add 'bd related \u003cid\u003e' showing deps + mentions + same tags\n- Export to JSON and pipe to external AI tools\n\n**Decision:** Only implement if clear use case emerges. Don't add complexity for theoretical benefits.\n\n**Context:** Part of evaluating Turso RFC ideas (GH #2). Vector search was proposed but unclear if needed for typical beads usage.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.881732-07:00","closed_at":"2025-10-18T10:09:23.532858-07:00"}
{"id":"bd-29","title":"Add visual indicators for nodes with multiple parents in dep tree","description":"When a node appears in the dependency tree via multiple paths (diamond dependencies), add a visual indicator like (*) or (multiple parents) to help users understand the graph structure. This would make it clear when deduplication has occurred. Example: 'bd-503: Shared dependency (*) [P1] (open)'","status":"open","priority":3,"issue_type":"feature","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.881917-07:00"}
{"id":"bd-29","title":"Add visual indicators for nodes with multiple parents in dep tree","description":"When a node appears in the dependency tree via multiple paths (diamond dependencies), add a visual indicator like (*) or (multiple parents) to help users understand the graph structure. This would make it clear when deduplication has occurred. Example: 'bd-503: Shared dependency (*) [P1] (open)'","status":"closed","priority":3,"issue_type":"feature","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-20T14:34:52.483358-07:00","closed_at":"2025-10-20T14:34:52.483358-07:00"}
{"id":"bd-3","title":"Remove unused issueMap in scoreCollisions","description":"scoreCollisions() creates issueMap and populates it (lines 135-138) but never uses it. Either remove it or add a TODO comment explaining future use. Located in collision.go:135-138. Cosmetic cleanup.","status":"closed","priority":4,"issue_type":"chore","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.877007-07:00","closed_at":"2025-10-19T19:27:34.230312-07:00"}
{"id":"bd-30","title":"Add cross-type cycle detection warnings to dependency operations","description":"When adding a dependency with 'bd dep add', run DetectCycles() afterwards and warn users if any cycles exist (across all dependency types, not just 'blocks'). This provides visibility into circular dependencies without blocking the operation.","design":"Implementation approach:\n1. After successfully adding a dependency in AddDependency, call DetectCycles()\n2. If cycles are found, print a warning to stderr showing:\n - The cycle path(s) detected\n - Which dependency types are involved\n - A note that this may cause confusion in dependency visualization\n3. Do NOT fail the operation - this is informational only\n4. Consider adding a --quiet flag to suppress warnings if needed\n\nThe warning should be clear and actionable, e.g.:\nWARNING: Circular dependency detected:\n vc-5 (blocks) → vc-13 (parent-child) → vc-5\nThis may cause confusion in dependency visualization.","acceptance_criteria":"- After 'bd dep add' creates a cross-type cycle, a warning is printed to stderr\n- Warning includes the full cycle path with dependency types\n- Operation still succeeds (warning only, not an error)\n- No warning is printed when no cycles exist\n- Warning message is clear and actionable","notes":"Current behavior: bd PREVENTS cycles (errors out). This issue wants to ALLOW cycles but WARN. \n\nDecision: Current behavior is better. Cycles break the ready work algorithm and dep tree visualization. Prevention is safer than warnings users might ignore.\n\nCode at dep.go:70-92 has cycle detection but it's unreachable - AddDependency errors before that code runs.\n\nRecommend closing as won't-do or changing requirement to match current behavior.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.882116-07:00","closed_at":"2025-10-17T23:08:00.079059-07:00"}
{"id":"bd-31","title":"Cache compiled regexes in replaceIDReferences for performance","description":"replaceIDReferences() compiles the same regex patterns on every call. With 100 issues and 10 ID mappings, that's 1000 regex compilations. Pre-compile regexes once and reuse. Can use a struct with compiled regex, placeholder, and newID. Located in collision.go:329. Estimated performance improvement: 10-100x for large batches.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T22:47:07.882317-07:00","closed_at":"2025-10-16T10:07:22.469891-07:00"}