diff --git a/.claude/.beads/config.yaml b/.claude/.beads/config.yaml index 46b9e82..5d0ceec 100644 --- a/.claude/.beads/config.yaml +++ b/.claude/.beads/config.yaml @@ -26,11 +26,6 @@ # Default actor for audit trails (overridden by BD_ACTOR or --actor) # actor: "" -# Export events (audit trail) to .beads/events.jsonl on each flush/sync -# When enabled, new events are appended incrementally using a high-water mark. -# Use 'bd export --events' to trigger manually regardless of this setting. -# events-export: false - # Multi-repo configuration (experimental - bd-307) # Allows hydrating from multiple repositories and routing writes to the correct JSONL # repos: diff --git a/.claude/commands/add-command.md b/.claude/commands/add-command.md index ceb45a2..23be23e 100644 --- a/.claude/commands/add-command.md +++ b/.claude/commands/add-command.md @@ -11,7 +11,7 @@ argument-hint: - Write natural, descriptive code without meta-commentary about the development process - The code should speak for itself - TDD is the process, not the product -Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands). +Beads is available for task tracking. Use `bd` CLI commands to manage issues. ## Plan File Restriction diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md index e40205e..2ac4ec5 100644 --- a/.claude/commands/commit.md +++ b/.claude/commands/commit.md @@ -11,7 +11,7 @@ argument-hint: [optional-commit-description] - Write natural, descriptive code without meta-commentary about the development process - The code should speak for itself - TDD is the process, not the product -Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands). +Beads is available for task tracking. Use `bd` CLI commands to manage issues. ## Plan File Restriction diff --git a/.claude/commands/create-adr.md b/.claude/commands/create-adr.md index 68bab70..4b79f29 100644 --- a/.claude/commands/create-adr.md +++ b/.claude/commands/create-adr.md @@ -17,7 +17,7 @@ Create a new ADR to document an architectural decision. ADRs capture the "why" b - Write natural, descriptive code without meta-commentary about the development process - The code should speak for itself - TDD is the process, not the product -Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands). +Beads is available for task tracking. Use `bd` CLI commands to manage issues. ## Plan File Restriction diff --git a/.claude/commands/create-issues.md b/.claude/commands/create-issues.md index 7c1ec62..ae37f02 100644 --- a/.claude/commands/create-issues.md +++ b/.claude/commands/create-issues.md @@ -15,7 +15,7 @@ Create structured implementation plan that bridges product thinking (PRD) with t - Write natural, descriptive code without meta-commentary about the development process - The code should speak for itself - TDD is the process, not the product -Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands). +Beads is available for task tracking. Use `bd` CLI commands to manage issues. ## Plan File Restriction @@ -113,7 +113,7 @@ For each task, create a bd issue with: ```bash bd create "Task title" \ - --type [feature|bug|task|chore] \ + --type [feature|bug|task|epic|chore|decision] \ --priority [1-3] \ --description "Context and what needs to be built" \ --design "Technical approach, architecture notes" \ @@ -149,8 +149,10 @@ bd create "Task title" \ **Dependencies**: Link related issues +The first argument is the issue that becomes blocked; the second is the blocker it waits on. + ```bash -bd dep add ISSUE-123 ISSUE-456 --type blocks +bd dep add --type blocks ``` ### Validation @@ -179,20 +181,20 @@ After creating issues, verify: ### Beads Integration -Use Beads MCP to: +Use the `bd` CLI to: - Track work with `bd ready` to find next task - Create issues with `bd create "description"` - Track dependencies with `bd dep add` -See for more information. +See for more information. ## Integration with Other Commands - **Before /create-issues**: Use `/spike` if you need technical exploration first - **After /create-issues**: Use `/red` to start TDD on first task - **During work**: Use `bd update` to add notes/findings back to issues -- **When stuck**: Check `bd show ISSUE-ID` to review acceptance criteria +- **When stuck**: Check `bd show ` to review acceptance criteria -## Issue Tracking with bd (beads) +## Work Tracking with bd (beads) -**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. +**IMPORTANT**: Use **bd (beads)** to break down and track your own work while implementing a ticket. Within a working session it is the only place to track that breakdown — do NOT use markdown TODOs, task lists, or other scratch tracking methods. + +bd is not the team's ticket tracker. It is a local tool for a developer and an AI agent working together: `bd init --stealth` adds `.beads/` to `.git/info/exclude`, so neither the database nor its JSONL export is committed, and nothing recorded in bd is visible to reviewers, teammates, or CI. The ticket a session is implementing lives in whatever system the team owning the repository uses — GitHub Issues, Jira, Linear, or something else. ### Why bd? -- Dependency-aware: Track blockers and relationships between issues -- Git-friendly: Auto-syncs to JSONL for version control +- Dependency-aware: Track blockers and relationships between the pieces of work in a session - Agent-optimized: JSON output, ready work detection, discovered-from links -- Prevents duplicate tracking systems and confusion +- Keeps session breakdown out of the team's ticket tracker, and out of the codebase ### Quick Start @@ -115,20 +120,20 @@ bd ready --json ```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 +bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from: --json ``` **Claim and update:** ```bash -bd update bd-42 --status in_progress --json -bd update bd-42 --priority 1 --json +bd update --status in_progress --json +bd update --priority 1 --json ``` **Complete work:** ```bash -bd close bd-42 --reason "Completed" --json +bd close --reason "Completed" --json ``` **Creating human readable file:** @@ -145,6 +150,7 @@ bd export -o [relative path to repository root]/.claude/.beads/issues-dump.jsonl - `task` - Work item (tests, docs, refactoring) - `epic` - Large feature with subtasks - `chore` - Maintenance (dependencies, tooling) +- `decision` - An architectural decision (aliases: `dec`, `adr`) ### Priorities @@ -166,15 +172,15 @@ bd export -o [relative path to repository root]/.claude/.beads/issues-dump.jsonl ### Important Rules -- ✅ Use bd for ALL task tracking +- ✅ Use bd for ALL tracking of your own work within a session - ✅ 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 +- ❌ Do NOT create markdown TODO lists to track session work +- ❌ Do NOT stand up a second scratch tracking system alongside bd +- ❌ Do NOT propose bd for work that needs tracking beyond the session — a bd issue is invisible to everyone else. Suggest a code comment, or a ticket in the team's own tracker, and do not assume which tracker that is -For more details, see README.md and docs/QUICKSTART.md. +For more details, run `bd quickstart` or see . # Copier-Managed Files diff --git a/README.md b/README.md index 23e9804..91c2020 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,9 @@ Documentation is hosted on [ReadTheDocs](https://cloud-courier.readthedocs.io/en/latest/?badge=latest). # Development + +Multi-step workflows are defined as [Task](https://taskfile.dev) tasks. Run `task --list` to see them; the definitions live in `.config/taskfiles/`, and `Taskfile.yaml` in the repo root is only a shim that includes them. + This project has a dev container. If you already have VS Code and Docker installed, you can click the badge above or [here](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/LabAutomationAndScreening/cloud-courier) to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use. The `Release` workflow reuses the checks from CI instead of re-running them: it requires that the `CI` workflow has already completed successfully for the current commit (including the `workflow-summary` job) and reuses the artifacts CI built rather than rebuilding. Trigger it manually with `workflow_dispatch`; a real release must be run from `main`, while the `dry_run` option lets you exercise the workflow from any branch without tagging or releasing. A real run pushes the `v` git tag and creates a GitHub Release, attaching the executable that CI built for every OS and Python version. @@ -22,8 +25,7 @@ The `Release` workflow reuses the checks from CI instead of re-running them: it ## Updating from the template -This repository uses a copier template. To pull in the latest updates from the template, use the command: -`copier update --answers-file .config/.copier-answers.yml --trust --conflict rej --defaults` +This repository uses a copier template. To pull in the latest updates from the template, run `task copier-update`