From c10e8b813993a3cc1508b38917b6cd769d0f5716 Mon Sep 17 00:00:00 2001 From: Sergey Korsik Date: Sun, 3 May 2026 11:53:47 +0200 Subject: [PATCH 01/13] Add AI agent instructions --- .github/copilot-instructions.md | 627 ++++++++++++++++++ AGENTS.md | 627 ++++++++++++++++++ CLAUDE.md | 627 ++++++++++++++++++ GEMINI.md | 627 ++++++++++++++++++ ...oject-management-to-Backlog.md-approach.md | 32 + 5 files changed, 2540 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 CLAUDE.md create mode 100644 Migrate-project-management-to-Backlog.md-approach.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..dcb8023 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,627 @@ + + +# Instructions for the usage of Backlog.md CLI Tool + +## Backlog.md: Comprehensive Project Management Tool via CLI + +### Assistant Objective + +Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata +remains fully synchronized and up-to-date. + +### Core Capabilities + +- ✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata +- ✅ **Search**: Fuzzy search across tasks, documents, and decisions with `backlog search` +- ✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index +- ✅ **Definition of Done checklists**: Per-task DoD items with add/remove/check/uncheck +- ✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`) +- ✅ **Git Integration**: Automatic tracking of task states across branches +- ✅ **Dependencies**: Task relationships and subtask hierarchies +- ✅ **Documentation & Decisions**: Structured docs and architectural decision records +- ✅ **Export & Reporting**: Generate markdown reports and board snapshots +- ✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing + +### Why This Matters to You (AI Agent) + +1. **Comprehensive system** - Full project management capabilities through CLI +2. **The CLI is the interface** - All operations go through `backlog` commands +3. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing ( + `backlog task edit 1`) +4. **Metadata stays synchronized** - The CLI handles all the complex relationships + +### Key Understanding + +- **Tasks** live in `backlog/tasks/` as `task- - .md` files +- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc. +- **Use `--plain` flag** for AI-friendly output when viewing/listing +- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships + +--- + +# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI + +**ALL task operations MUST use the Backlog.md CLI commands** + +- ✅ **DO**: Use `backlog task edit` and other CLI commands +- ✅ **DO**: Use `backlog task create` to create new tasks +- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria +- ❌ **DON'T**: Edit markdown files directly +- ❌ **DON'T**: Manually change checkboxes in files +- ❌ **DON'T**: Add or modify text in task files without using CLI + +**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships. + +--- + +## 1. Source of Truth & File Structure + +### 📖 **UNDERSTANDING** (What you'll see when reading) + +- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**) +- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`) +- Project documentation is in **`backlog/docs/`** +- Project decisions are in **`backlog/decisions/`** + +### 🔧 **ACTING** (How to change things) + +- **All task operations MUST use the Backlog.md CLI tool** +- This ensures metadata is correctly updated and the project stays in sync +- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output + +--- + +## 2. Common Mistakes to Avoid + +### ❌ **WRONG: Direct File Editing** + +```markdown +# DON'T DO THIS: + +1. Open backlog/tasks/task-7 - Feature.md in editor +2. Change "- [ ]" to "- [x]" manually +3. Add notes or final summary directly to the file +4. Save the file +``` + +### ✅ **CORRECT: Using CLI Commands** + +```bash +# DO THIS INSTEAD: +backlog task edit 7 --check-ac 1 # Mark AC #1 as complete +backlog task edit 7 --notes "Implementation complete" # Add notes +backlog task edit 7 --final-summary "PR-style summary" # Add final summary +backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task +``` + +--- + +## 3. Understanding Task Format (Read-Only Reference) + +⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files. +**Never edit these directly! Use CLI commands to make changes.** + +### Task Structure You'll See + +```markdown +--- +id: task-42 +title: Add GraphQL resolver +status: To Do +assignee: [@sara] +labels: [backend, api] +--- + +## Description + +Brief explanation of the task purpose. + +## Acceptance Criteria + +<!-- AC:BEGIN --> + +- [ ] #1 First criterion +- [x] #2 Second criterion (completed) +- [ ] #3 Third criterion + +<!-- AC:END --> + +## Definition of Done + +<!-- DOD:BEGIN --> + +- [ ] #1 Tests pass +- [ ] #2 Docs updated + +<!-- DOD:END --> + +## Implementation Plan + +1. Research approach +2. Implement solution + +## Implementation Notes + +Progress notes captured during implementation. + +## Final Summary + +PR-style summary of what was implemented. +``` + +### How to Modify Each Section + +| What You Want to Change | CLI Command to Use | +|-------------------------|----------------------------------------------------------| +| Title | `backlog task edit 42 -t "New Title"` | +| Status | `backlog task edit 42 -s "In Progress"` | +| Assignee | `backlog task edit 42 -a @sara` | +| Labels | `backlog task edit 42 -l backend,api` | +| Description | `backlog task edit 42 -d "New description"` | +| Add AC | `backlog task edit 42 --ac "New criterion"` | +| Add DoD | `backlog task edit 42 --dod "Ship notes"` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check DoD #1 | `backlog task edit 42 --check-dod 1` | +| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` | +| Uncheck DoD #2 | `backlog task edit 42 --uncheck-dod 2` | +| Remove AC #3 | `backlog task edit 42 --remove-ac 3` | +| Remove DoD #3 | `backlog task edit 42 --remove-dod 3` | +| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add Notes (replace) | `backlog task edit 42 --notes "What I did"` | +| Append Notes | `backlog task edit 42 --append-notes "Another note"` | +| Add Final Summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append Final Summary | `backlog task edit 42 --append-final-summary "Another detail"` | +| Clear Final Summary | `backlog task edit 42 --clear-final-summary` | + +--- + +## 4. Defining Tasks + +### Creating New Tasks + +**Always use CLI to create tasks:** + +```bash +# Example +backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion" +``` + +### Title (one liner) + +Use a clear brief title that summarizes the task. + +### Description (The "why") + +Provide a concise summary of the task purpose and its goal. Explains the context without implementation details. + +### Acceptance Criteria (The "what") + +**Understanding the Format:** + +- Acceptance criteria appear as numbered checkboxes in the markdown files +- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked) + +**Managing Acceptance Criteria via CLI:** + +⚠️ **IMPORTANT: How AC Commands Work** + +- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅ +- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅ +- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅ + +```bash +# Examples + +# Add new criteria (MULTIPLE values allowed) +backlog task edit 42 --ac "User can login" --ac "Session persists" + +# Check specific criteria by index (MULTIPLE values supported) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs +# Or check them individually if you prefer: +backlog task edit 42 --check-ac 1 # Mark #1 as complete +backlog task edit 42 --check-ac 2 # Mark #2 as complete + +# Mixed operations in single command +backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 + +# ❌ STILL WRONG - These formats don't work: +# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values +# backlog task edit 42 --check-ac 1-3 # No ranges +# backlog task edit 42 --check 1 # Wrong flag name + +# Multiple operations of same type +backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs +backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low) +``` + +### Definition of Done checklist (per-task) + +Definition of Done items are a second checklist in each task. Defaults come from `definition_of_done` in the project config file (`backlog/config.yml`, `.backlog/config.yml`, or `backlog.config.yml`) or from Web UI Settings, and can be disabled per task. + +**Managing Definition of Done via CLI:** + +```bash +# Add DoD items (MULTIPLE values allowed) +backlog task edit 42 --dod "Run tests" --dod "Update docs" + +# Check/uncheck DoD items by index (MULTIPLE values supported) +backlog task edit 42 --check-dod 1 --check-dod 2 +backlog task edit 42 --uncheck-dod 1 + +# Remove DoD items by index +backlog task edit 42 --remove-dod 2 + +# Create without defaults +backlog task create "Feature" --no-dod-defaults +``` + +**Key Principles for Good ACs:** + +- **Outcome-Oriented:** Focus on the result, not the method. +- **Testable/Verifiable:** Each criterion should be objectively testable +- **Clear and Concise:** Unambiguous language +- **Complete:** Collectively cover the task scope +- **User-Focused:** Frame from end-user or system behavior perspective + +Good Examples: + +- "User can successfully log in with valid credentials" +- "System processes 1000 requests per second without errors" +- "CLI preserves literal newlines in description/plan/notes/final summary; `\\n` sequences are not auto‑converted" + +Bad Example (Implementation Step): + +- "Add a new function handleLogin() in auth.ts" +- "Define expected behavior and document supported input patterns" + +### Task Breakdown Strategy + +1. Identify foundational components first +2. Create tasks in dependency order (foundations before features) +3. Ensure each task delivers value independently +4. Avoid creating tasks that block each other + +### Task Requirements + +- Tasks must be **atomic** and **testable** or **verifiable** +- Each task should represent a single unit of work for one PR +- **Never** reference future tasks (only tasks with id < current task id) +- Ensure tasks are **independent** and don't depend on future work + +--- + +## 5. Implementing Tasks + +### 5.1. First step when implementing a task + +The very first things you must do when you take over a task are: + +* set the task in progress +* assign it to yourself + +```bash +# Example +backlog task edit 42 -s "In Progress" -a @{myself} +``` + +### 5.2. Review Task References and Documentation + +Before planning, check if the task has any attached `references` or `documentation`: +- **References**: Related code files, GitHub issues, or URLs relevant to the implementation +- **Documentation**: Design docs, API specs, or other materials for understanding context + +These are visible in the task view output. Review them to understand the full context before drafting your plan. + +### 5.3. Create an Implementation Plan (The "how") + +Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a +plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**. +First do a quick check to see if all the tools that you are planning to use are available in the environment you are +working in. +When you are ready, write it down in the task so that you can refer to it later. + +```bash +# Example +backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test" +``` + +## 5.4. Implementation + +Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure +everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you +finish them. + +### 5.5 Implementation Notes (Progress log) + +Use Implementation Notes to log progress, decisions, and blockers as you work. +Append notes progressively during implementation using `--append-notes`: + +``` +backlog task edit 42 --append-notes "Investigated root cause" --append-notes "Added tests for edge case" +``` + +```bash +# Example +backlog task edit 42 --notes "Initial implementation done; pending integration tests" +``` + +### 5.6 Final Summary (PR description) + +When you are done implementing a task you need to prepare a PR description for it. +Because you cannot create PRs directly, write the PR as a clean summary in the Final Summary field. + +**Quality bar:** Write it like a reviewer will see it. A one‑liner is rarely enough unless the change is truly trivial. +Include the key scope so someone can understand the impact without reading the whole diff. + +```bash +# Example +backlog task edit 42 --final-summary "Implemented pattern X because Reason Y; updated files Z and W; added tests" +``` + +**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the +implementation. + +- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee. +- When you begin work, switch to edit, set the task in progress and assign to yourself + `backlog task edit <id> -s "In Progress" -a "..."`. +- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`. +- After updating the plan, share it with the user and ask for confirmation. Do not begin coding until the user approves the plan or explicitly tells you to skip the review. +- Append Implementation Notes during implementation using `--append-notes` as progress is made. +- Add Final Summary only after completing the work: `backlog task edit <id> --final-summary "..."` (replace) or append using `--append-final-summary`. + +## Phase discipline: What goes where + +- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee. +- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself) + Implementation Notes (progress log, appended as you work). +- Wrap-up: Final Summary (PR description), verify AC and Definition of Done checks. + +**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either: + +1. Update the AC first: `backlog task edit 42 --ac "New requirement"` +2. Or create a new follow up task: `backlog task create "Additional feature"` + +--- + +## 6. Typical Workflow + +```bash +# 1. Identify work +backlog task list -s "To Do" --plain + +# 2. Read task details +backlog task 42 --plain + +# 3. Start work: assign yourself & change status +backlog task edit 42 -s "In Progress" -a @myself + +# 4. Add implementation plan +backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test" + +# 5. Share the plan with the user and wait for approval (do not write code yet) + +# 6. Work on the task (write code, test, etc.) + +# 7. Mark acceptance criteria as complete (supports multiple in one command) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once +# Or check them individually if preferred: +# backlog task edit 42 --check-ac 1 +# backlog task edit 42 --check-ac 2 +# backlog task edit 42 --check-ac 3 + +# 8. Add Final Summary (PR Description) +backlog task edit 42 --final-summary "Refactored using strategy pattern, updated tests" + +# 9. Mark task as done +backlog task edit 42 -s Done +``` + +--- + +## 7. Definition of Done (DoD) + +A task is **Done** only when **ALL** of the following are complete: + +### ✅ Via CLI Commands: + +1. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each +2. **All Definition of Done items checked**: Use `backlog task edit <id> --check-dod <index>` for each +3. **Final Summary added**: Use `backlog task edit <id> --final-summary "..."` +4. **Status set to Done**: Use `backlog task edit <id> -s Done` + +### ✅ Via Code/Testing: + +5. **Tests pass**: Run test suite and linting +6. **Documentation updated**: Update relevant docs if needed +7. **Code reviewed**: Self-review your changes +8. **No regressions**: Performance, security checks pass + +⚠️ **NEVER mark a task as Done without completing ALL items above** + +--- + +## 8. Finding Tasks and Content with Search + +When users ask you to find tasks related to a topic, use the `backlog search` command with `--plain` flag: + +```bash +# Search for tasks about authentication +backlog search "auth" --plain + +# Search only in tasks (not docs/decisions) +backlog search "login" --type task --plain + +# Search with filters +backlog search "api" --status "In Progress" --plain +backlog search "bug" --priority high --plain +``` + +**Key points:** +- Uses fuzzy matching - finds "authentication" when searching "auth" +- Searches task titles, descriptions, and content +- Also searches documents and decisions unless filtered with `--type task` +- Always use `--plain` flag for AI-readable output + +--- + +## 9. Quick Reference: DO vs DON'T + +### Viewing and Finding Tasks + +| Task | ✅ DO | ❌ DON'T | +|--------------|-----------------------------|---------------------------------| +| View task | `backlog task 42 --plain` | Open and read .md file directly | +| List tasks | `backlog task list --plain` | Browse backlog/tasks folder | +| Check status | `backlog task 42 --plain` | Look at file content | +| Find by topic| `backlog search "auth" --plain` | Manually grep through files | + +### Modifying Tasks + +| Task | ✅ DO | ❌ DON'T | +|---------------|--------------------------------------|-----------------------------------| +| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file | +| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file | +| Add final summary | `backlog task edit 42 --final-summary "..."` | Type summary into .md file | +| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter | +| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file | + +--- + +## 10. Complete CLI Command Reference + +### Task Creation + +| Action | Command | +|------------------|-------------------------------------------------------------------------------------| +| Create task | `backlog task create "Title"` | +| With description | `backlog task create "Title" -d "Description"` | +| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` | +| With final summary | `backlog task create "Title" --final-summary "PR-style summary"` | +| With references | `backlog task create "Title" --ref src/api.ts --ref https://github.com/issue/123` | +| With documentation | `backlog task create "Title" --doc https://design-docs.example.com` | +| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high --ref src/api.ts --doc docs/spec.md` | +| Create draft | `backlog task create "Title" --draft` | +| Create subtask | `backlog task create "Title" -p 42` | + +### Task Modification + +| Action | Command | +|------------------|---------------------------------------------| +| Edit title | `backlog task edit 42 -t "New Title"` | +| Edit description | `backlog task edit 42 -d "New description"` | +| Change status | `backlog task edit 42 -s "In Progress"` | +| Assign | `backlog task edit 42 -a @sara` | +| Add labels | `backlog task edit 42 -l backend,api` | +| Set priority | `backlog task edit 42 --priority high` | + +### Acceptance Criteria Management + +| Action | Command | +|---------------------|-----------------------------------------------------------------------------| +| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` | +| Remove AC #2 | `backlog task edit 42 --remove-ac 2` | +| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` | +| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` | +| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` | + +### Task Content + +| Action | Command | +|------------------|----------------------------------------------------------| +| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add notes | `backlog task edit 42 --notes "Implementation details"` | +| Add final summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append final summary | `backlog task edit 42 --append-final-summary "More details"` | +| Clear final summary | `backlog task edit 42 --clear-final-summary` | +| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` | +| Add references | `backlog task edit 42 --ref src/api.ts --ref https://github.com/issue/123` | +| Add documentation | `backlog task edit 42 --doc https://design-docs.example.com --doc docs/spec.md` | + +### Multi‑line Input (Description/Plan/Notes/Final Summary) + +The CLI preserves input literally. Shells do not convert `\n` inside normal quotes. Use one of the following to insert real newlines: + +- Bash/Zsh (ANSI‑C quoting): + - Description: `backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'` + - Plan: `backlog task edit 42 --plan $'1. A\n2. B'` + - Notes: `backlog task edit 42 --notes $'Done A\nDoing B'` + - Append notes: `backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'` + - Final summary: `backlog task edit 42 --final-summary $'Shipped A\nAdded B'` + - Append final summary: `backlog task edit 42 --append-final-summary $'Added X\nAdded Y'` +- POSIX portable (printf): + - `backlog task edit 42 --notes "$(printf 'Line1\nLine2')"` +- PowerShell (backtick n): + - `backlog task edit 42 --notes "Line1`nLine2"` + +Do not expect `"...\n..."` to become a newline. That passes the literal backslash + n to the CLI by design. + +Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline. + +### Implementation Notes Formatting + +- Keep implementation notes concise and time-ordered; focus on progress, decisions, and blockers. +- Use short paragraphs or bullet lists instead of a single long line. +- Use Markdown bullets (`-` for unordered, `1.` for ordered) for readability. +- When using CLI flags like `--append-notes`, remember to include explicit + newlines. Example: + + ```bash + backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy' + ``` + +### Final Summary Formatting + +- Treat the Final Summary as a PR description: lead with the outcome, then add key changes and tests. +- Keep it clean and structured so it can be pasted directly into GitHub. +- Prefer short paragraphs or bullet lists and avoid raw progress logs. +- Aim to cover: **what changed**, **why**, **user impact**, **tests run**, and **risks/follow‑ups** when relevant. +- Avoid single‑line summaries unless the change is truly tiny. + +**Example (good, not rigid):** +``` +Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes. + +Changes: +- Added `finalSummary` to task types and markdown section parsing/serialization (ordered after notes). +- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it. + +Tests: +- bun test src/test/final-summary.test.ts +- bun test src/test/cli-final-summary.test.ts +``` + +### Task Operations + +| Action | Command | +|--------------------|----------------------------------------------| +| View task | `backlog task 42 --plain` | +| List tasks | `backlog task list --plain` | +| Search tasks | `backlog search "topic" --plain` | +| Search with filter | `backlog search "api" --status "To Do" --plain` | +| Filter by status | `backlog task list -s "In Progress" --plain` | +| Filter by assignee | `backlog task list -a @sara --plain` | +| Archive task | `backlog task archive 42` | +| Demote to draft | `backlog task demote 42` | + +--- + +## Common Issues + +| Problem | Solution | +|----------------------|--------------------------------------------------------------------| +| Task not found | Check task ID with `backlog task list --plain` | +| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers | +| Changes not saving | Ensure you're using CLI, not editing files | +| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` | + +--- + +## Remember: The Golden Rule + +**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.** +**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.** + +Full help available: `backlog --help` + +<!-- BACKLOG.MD GUIDELINES END --> diff --git a/AGENTS.md b/AGENTS.md index e81ecd5..9fc4fe6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,3 +22,630 @@ Agents not using OpenCode: refer to `.opencode/docs/AGENT_WORKFLOW.md`. - **Triggers**: `/antivibe` or "deep dive" - **Action**: Generate a concise learning guide for recently modified/AI-generated code. Save to `deep-dive/[component]-YYYY-MM-DD.md`. Focus on _why_ decisions were made, tied to doro-cli's TUI/state-machine architecture. See `.opencode/skills/antivibe/SKILL.md`. + +<!-- BACKLOG.MD GUIDELINES START --> +# Instructions for the usage of Backlog.md CLI Tool + +## Backlog.md: Comprehensive Project Management Tool via CLI + +### Assistant Objective + +Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata +remains fully synchronized and up-to-date. + +### Core Capabilities + +- ✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata +- ✅ **Search**: Fuzzy search across tasks, documents, and decisions with `backlog search` +- ✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index +- ✅ **Definition of Done checklists**: Per-task DoD items with add/remove/check/uncheck +- ✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`) +- ✅ **Git Integration**: Automatic tracking of task states across branches +- ✅ **Dependencies**: Task relationships and subtask hierarchies +- ✅ **Documentation & Decisions**: Structured docs and architectural decision records +- ✅ **Export & Reporting**: Generate markdown reports and board snapshots +- ✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing + +### Why This Matters to You (AI Agent) + +1. **Comprehensive system** - Full project management capabilities through CLI +2. **The CLI is the interface** - All operations go through `backlog` commands +3. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing ( + `backlog task edit 1`) +4. **Metadata stays synchronized** - The CLI handles all the complex relationships + +### Key Understanding + +- **Tasks** live in `backlog/tasks/` as `task-<id> - <title>.md` files +- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc. +- **Use `--plain` flag** for AI-friendly output when viewing/listing +- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships + +--- + +# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI + +**ALL task operations MUST use the Backlog.md CLI commands** + +- ✅ **DO**: Use `backlog task edit` and other CLI commands +- ✅ **DO**: Use `backlog task create` to create new tasks +- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria +- ❌ **DON'T**: Edit markdown files directly +- ❌ **DON'T**: Manually change checkboxes in files +- ❌ **DON'T**: Add or modify text in task files without using CLI + +**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships. + +--- + +## 1. Source of Truth & File Structure + +### 📖 **UNDERSTANDING** (What you'll see when reading) + +- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**) +- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`) +- Project documentation is in **`backlog/docs/`** +- Project decisions are in **`backlog/decisions/`** + +### 🔧 **ACTING** (How to change things) + +- **All task operations MUST use the Backlog.md CLI tool** +- This ensures metadata is correctly updated and the project stays in sync +- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output + +--- + +## 2. Common Mistakes to Avoid + +### ❌ **WRONG: Direct File Editing** + +```markdown +# DON'T DO THIS: + +1. Open backlog/tasks/task-7 - Feature.md in editor +2. Change "- [ ]" to "- [x]" manually +3. Add notes or final summary directly to the file +4. Save the file +``` + +### ✅ **CORRECT: Using CLI Commands** + +```bash +# DO THIS INSTEAD: +backlog task edit 7 --check-ac 1 # Mark AC #1 as complete +backlog task edit 7 --notes "Implementation complete" # Add notes +backlog task edit 7 --final-summary "PR-style summary" # Add final summary +backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task +``` + +--- + +## 3. Understanding Task Format (Read-Only Reference) + +⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files. +**Never edit these directly! Use CLI commands to make changes.** + +### Task Structure You'll See + +```markdown +--- +id: task-42 +title: Add GraphQL resolver +status: To Do +assignee: [@sara] +labels: [backend, api] +--- + +## Description + +Brief explanation of the task purpose. + +## Acceptance Criteria + +<!-- AC:BEGIN --> + +- [ ] #1 First criterion +- [x] #2 Second criterion (completed) +- [ ] #3 Third criterion + +<!-- AC:END --> + +## Definition of Done + +<!-- DOD:BEGIN --> + +- [ ] #1 Tests pass +- [ ] #2 Docs updated + +<!-- DOD:END --> + +## Implementation Plan + +1. Research approach +2. Implement solution + +## Implementation Notes + +Progress notes captured during implementation. + +## Final Summary + +PR-style summary of what was implemented. +``` + +### How to Modify Each Section + +| What You Want to Change | CLI Command to Use | +|-------------------------|----------------------------------------------------------| +| Title | `backlog task edit 42 -t "New Title"` | +| Status | `backlog task edit 42 -s "In Progress"` | +| Assignee | `backlog task edit 42 -a @sara` | +| Labels | `backlog task edit 42 -l backend,api` | +| Description | `backlog task edit 42 -d "New description"` | +| Add AC | `backlog task edit 42 --ac "New criterion"` | +| Add DoD | `backlog task edit 42 --dod "Ship notes"` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check DoD #1 | `backlog task edit 42 --check-dod 1` | +| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` | +| Uncheck DoD #2 | `backlog task edit 42 --uncheck-dod 2` | +| Remove AC #3 | `backlog task edit 42 --remove-ac 3` | +| Remove DoD #3 | `backlog task edit 42 --remove-dod 3` | +| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add Notes (replace) | `backlog task edit 42 --notes "What I did"` | +| Append Notes | `backlog task edit 42 --append-notes "Another note"` | +| Add Final Summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append Final Summary | `backlog task edit 42 --append-final-summary "Another detail"` | +| Clear Final Summary | `backlog task edit 42 --clear-final-summary` | + +--- + +## 4. Defining Tasks + +### Creating New Tasks + +**Always use CLI to create tasks:** + +```bash +# Example +backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion" +``` + +### Title (one liner) + +Use a clear brief title that summarizes the task. + +### Description (The "why") + +Provide a concise summary of the task purpose and its goal. Explains the context without implementation details. + +### Acceptance Criteria (The "what") + +**Understanding the Format:** + +- Acceptance criteria appear as numbered checkboxes in the markdown files +- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked) + +**Managing Acceptance Criteria via CLI:** + +⚠️ **IMPORTANT: How AC Commands Work** + +- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅ +- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅ +- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅ + +```bash +# Examples + +# Add new criteria (MULTIPLE values allowed) +backlog task edit 42 --ac "User can login" --ac "Session persists" + +# Check specific criteria by index (MULTIPLE values supported) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs +# Or check them individually if you prefer: +backlog task edit 42 --check-ac 1 # Mark #1 as complete +backlog task edit 42 --check-ac 2 # Mark #2 as complete + +# Mixed operations in single command +backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 + +# ❌ STILL WRONG - These formats don't work: +# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values +# backlog task edit 42 --check-ac 1-3 # No ranges +# backlog task edit 42 --check 1 # Wrong flag name + +# Multiple operations of same type +backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs +backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low) +``` + +### Definition of Done checklist (per-task) + +Definition of Done items are a second checklist in each task. Defaults come from `definition_of_done` in the project config file (`backlog/config.yml`, `.backlog/config.yml`, or `backlog.config.yml`) or from Web UI Settings, and can be disabled per task. + +**Managing Definition of Done via CLI:** + +```bash +# Add DoD items (MULTIPLE values allowed) +backlog task edit 42 --dod "Run tests" --dod "Update docs" + +# Check/uncheck DoD items by index (MULTIPLE values supported) +backlog task edit 42 --check-dod 1 --check-dod 2 +backlog task edit 42 --uncheck-dod 1 + +# Remove DoD items by index +backlog task edit 42 --remove-dod 2 + +# Create without defaults +backlog task create "Feature" --no-dod-defaults +``` + +**Key Principles for Good ACs:** + +- **Outcome-Oriented:** Focus on the result, not the method. +- **Testable/Verifiable:** Each criterion should be objectively testable +- **Clear and Concise:** Unambiguous language +- **Complete:** Collectively cover the task scope +- **User-Focused:** Frame from end-user or system behavior perspective + +Good Examples: + +- "User can successfully log in with valid credentials" +- "System processes 1000 requests per second without errors" +- "CLI preserves literal newlines in description/plan/notes/final summary; `\\n` sequences are not auto‑converted" + +Bad Example (Implementation Step): + +- "Add a new function handleLogin() in auth.ts" +- "Define expected behavior and document supported input patterns" + +### Task Breakdown Strategy + +1. Identify foundational components first +2. Create tasks in dependency order (foundations before features) +3. Ensure each task delivers value independently +4. Avoid creating tasks that block each other + +### Task Requirements + +- Tasks must be **atomic** and **testable** or **verifiable** +- Each task should represent a single unit of work for one PR +- **Never** reference future tasks (only tasks with id < current task id) +- Ensure tasks are **independent** and don't depend on future work + +--- + +## 5. Implementing Tasks + +### 5.1. First step when implementing a task + +The very first things you must do when you take over a task are: + +* set the task in progress +* assign it to yourself + +```bash +# Example +backlog task edit 42 -s "In Progress" -a @{myself} +``` + +### 5.2. Review Task References and Documentation + +Before planning, check if the task has any attached `references` or `documentation`: +- **References**: Related code files, GitHub issues, or URLs relevant to the implementation +- **Documentation**: Design docs, API specs, or other materials for understanding context + +These are visible in the task view output. Review them to understand the full context before drafting your plan. + +### 5.3. Create an Implementation Plan (The "how") + +Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a +plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**. +First do a quick check to see if all the tools that you are planning to use are available in the environment you are +working in. +When you are ready, write it down in the task so that you can refer to it later. + +```bash +# Example +backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test" +``` + +## 5.4. Implementation + +Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure +everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you +finish them. + +### 5.5 Implementation Notes (Progress log) + +Use Implementation Notes to log progress, decisions, and blockers as you work. +Append notes progressively during implementation using `--append-notes`: + +``` +backlog task edit 42 --append-notes "Investigated root cause" --append-notes "Added tests for edge case" +``` + +```bash +# Example +backlog task edit 42 --notes "Initial implementation done; pending integration tests" +``` + +### 5.6 Final Summary (PR description) + +When you are done implementing a task you need to prepare a PR description for it. +Because you cannot create PRs directly, write the PR as a clean summary in the Final Summary field. + +**Quality bar:** Write it like a reviewer will see it. A one‑liner is rarely enough unless the change is truly trivial. +Include the key scope so someone can understand the impact without reading the whole diff. + +```bash +# Example +backlog task edit 42 --final-summary "Implemented pattern X because Reason Y; updated files Z and W; added tests" +``` + +**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the +implementation. + +- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee. +- When you begin work, switch to edit, set the task in progress and assign to yourself + `backlog task edit <id> -s "In Progress" -a "..."`. +- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`. +- After updating the plan, share it with the user and ask for confirmation. Do not begin coding until the user approves the plan or explicitly tells you to skip the review. +- Append Implementation Notes during implementation using `--append-notes` as progress is made. +- Add Final Summary only after completing the work: `backlog task edit <id> --final-summary "..."` (replace) or append using `--append-final-summary`. + +## Phase discipline: What goes where + +- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee. +- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself) + Implementation Notes (progress log, appended as you work). +- Wrap-up: Final Summary (PR description), verify AC and Definition of Done checks. + +**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either: + +1. Update the AC first: `backlog task edit 42 --ac "New requirement"` +2. Or create a new follow up task: `backlog task create "Additional feature"` + +--- + +## 6. Typical Workflow + +```bash +# 1. Identify work +backlog task list -s "To Do" --plain + +# 2. Read task details +backlog task 42 --plain + +# 3. Start work: assign yourself & change status +backlog task edit 42 -s "In Progress" -a @myself + +# 4. Add implementation plan +backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test" + +# 5. Share the plan with the user and wait for approval (do not write code yet) + +# 6. Work on the task (write code, test, etc.) + +# 7. Mark acceptance criteria as complete (supports multiple in one command) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once +# Or check them individually if preferred: +# backlog task edit 42 --check-ac 1 +# backlog task edit 42 --check-ac 2 +# backlog task edit 42 --check-ac 3 + +# 8. Add Final Summary (PR Description) +backlog task edit 42 --final-summary "Refactored using strategy pattern, updated tests" + +# 9. Mark task as done +backlog task edit 42 -s Done +``` + +--- + +## 7. Definition of Done (DoD) + +A task is **Done** only when **ALL** of the following are complete: + +### ✅ Via CLI Commands: + +1. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each +2. **All Definition of Done items checked**: Use `backlog task edit <id> --check-dod <index>` for each +3. **Final Summary added**: Use `backlog task edit <id> --final-summary "..."` +4. **Status set to Done**: Use `backlog task edit <id> -s Done` + +### ✅ Via Code/Testing: + +5. **Tests pass**: Run test suite and linting +6. **Documentation updated**: Update relevant docs if needed +7. **Code reviewed**: Self-review your changes +8. **No regressions**: Performance, security checks pass + +⚠️ **NEVER mark a task as Done without completing ALL items above** + +--- + +## 8. Finding Tasks and Content with Search + +When users ask you to find tasks related to a topic, use the `backlog search` command with `--plain` flag: + +```bash +# Search for tasks about authentication +backlog search "auth" --plain + +# Search only in tasks (not docs/decisions) +backlog search "login" --type task --plain + +# Search with filters +backlog search "api" --status "In Progress" --plain +backlog search "bug" --priority high --plain +``` + +**Key points:** +- Uses fuzzy matching - finds "authentication" when searching "auth" +- Searches task titles, descriptions, and content +- Also searches documents and decisions unless filtered with `--type task` +- Always use `--plain` flag for AI-readable output + +--- + +## 9. Quick Reference: DO vs DON'T + +### Viewing and Finding Tasks + +| Task | ✅ DO | ❌ DON'T | +|--------------|-----------------------------|---------------------------------| +| View task | `backlog task 42 --plain` | Open and read .md file directly | +| List tasks | `backlog task list --plain` | Browse backlog/tasks folder | +| Check status | `backlog task 42 --plain` | Look at file content | +| Find by topic| `backlog search "auth" --plain` | Manually grep through files | + +### Modifying Tasks + +| Task | ✅ DO | ❌ DON'T | +|---------------|--------------------------------------|-----------------------------------| +| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file | +| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file | +| Add final summary | `backlog task edit 42 --final-summary "..."` | Type summary into .md file | +| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter | +| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file | + +--- + +## 10. Complete CLI Command Reference + +### Task Creation + +| Action | Command | +|------------------|-------------------------------------------------------------------------------------| +| Create task | `backlog task create "Title"` | +| With description | `backlog task create "Title" -d "Description"` | +| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` | +| With final summary | `backlog task create "Title" --final-summary "PR-style summary"` | +| With references | `backlog task create "Title" --ref src/api.ts --ref https://github.com/issue/123` | +| With documentation | `backlog task create "Title" --doc https://design-docs.example.com` | +| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high --ref src/api.ts --doc docs/spec.md` | +| Create draft | `backlog task create "Title" --draft` | +| Create subtask | `backlog task create "Title" -p 42` | + +### Task Modification + +| Action | Command | +|------------------|---------------------------------------------| +| Edit title | `backlog task edit 42 -t "New Title"` | +| Edit description | `backlog task edit 42 -d "New description"` | +| Change status | `backlog task edit 42 -s "In Progress"` | +| Assign | `backlog task edit 42 -a @sara` | +| Add labels | `backlog task edit 42 -l backend,api` | +| Set priority | `backlog task edit 42 --priority high` | + +### Acceptance Criteria Management + +| Action | Command | +|---------------------|-----------------------------------------------------------------------------| +| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` | +| Remove AC #2 | `backlog task edit 42 --remove-ac 2` | +| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` | +| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` | +| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` | + +### Task Content + +| Action | Command | +|------------------|----------------------------------------------------------| +| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add notes | `backlog task edit 42 --notes "Implementation details"` | +| Add final summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append final summary | `backlog task edit 42 --append-final-summary "More details"` | +| Clear final summary | `backlog task edit 42 --clear-final-summary` | +| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` | +| Add references | `backlog task edit 42 --ref src/api.ts --ref https://github.com/issue/123` | +| Add documentation | `backlog task edit 42 --doc https://design-docs.example.com --doc docs/spec.md` | + +### Multi‑line Input (Description/Plan/Notes/Final Summary) + +The CLI preserves input literally. Shells do not convert `\n` inside normal quotes. Use one of the following to insert real newlines: + +- Bash/Zsh (ANSI‑C quoting): + - Description: `backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'` + - Plan: `backlog task edit 42 --plan $'1. A\n2. B'` + - Notes: `backlog task edit 42 --notes $'Done A\nDoing B'` + - Append notes: `backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'` + - Final summary: `backlog task edit 42 --final-summary $'Shipped A\nAdded B'` + - Append final summary: `backlog task edit 42 --append-final-summary $'Added X\nAdded Y'` +- POSIX portable (printf): + - `backlog task edit 42 --notes "$(printf 'Line1\nLine2')"` +- PowerShell (backtick n): + - `backlog task edit 42 --notes "Line1`nLine2"` + +Do not expect `"...\n..."` to become a newline. That passes the literal backslash + n to the CLI by design. + +Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline. + +### Implementation Notes Formatting + +- Keep implementation notes concise and time-ordered; focus on progress, decisions, and blockers. +- Use short paragraphs or bullet lists instead of a single long line. +- Use Markdown bullets (`-` for unordered, `1.` for ordered) for readability. +- When using CLI flags like `--append-notes`, remember to include explicit + newlines. Example: + + ```bash + backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy' + ``` + +### Final Summary Formatting + +- Treat the Final Summary as a PR description: lead with the outcome, then add key changes and tests. +- Keep it clean and structured so it can be pasted directly into GitHub. +- Prefer short paragraphs or bullet lists and avoid raw progress logs. +- Aim to cover: **what changed**, **why**, **user impact**, **tests run**, and **risks/follow‑ups** when relevant. +- Avoid single‑line summaries unless the change is truly tiny. + +**Example (good, not rigid):** +``` +Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes. + +Changes: +- Added `finalSummary` to task types and markdown section parsing/serialization (ordered after notes). +- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it. + +Tests: +- bun test src/test/final-summary.test.ts +- bun test src/test/cli-final-summary.test.ts +``` + +### Task Operations + +| Action | Command | +|--------------------|----------------------------------------------| +| View task | `backlog task 42 --plain` | +| List tasks | `backlog task list --plain` | +| Search tasks | `backlog search "topic" --plain` | +| Search with filter | `backlog search "api" --status "To Do" --plain` | +| Filter by status | `backlog task list -s "In Progress" --plain` | +| Filter by assignee | `backlog task list -a @sara --plain` | +| Archive task | `backlog task archive 42` | +| Demote to draft | `backlog task demote 42` | + +--- + +## Common Issues + +| Problem | Solution | +|----------------------|--------------------------------------------------------------------| +| Task not found | Check task ID with `backlog task list --plain` | +| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers | +| Changes not saving | Ensure you're using CLI, not editing files | +| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` | + +--- + +## Remember: The Golden Rule + +**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.** +**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.** + +Full help available: `backlog --help` + +<!-- BACKLOG.MD GUIDELINES END --> diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dcb8023 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,627 @@ + +<!-- BACKLOG.MD GUIDELINES START --> +# Instructions for the usage of Backlog.md CLI Tool + +## Backlog.md: Comprehensive Project Management Tool via CLI + +### Assistant Objective + +Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata +remains fully synchronized and up-to-date. + +### Core Capabilities + +- ✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata +- ✅ **Search**: Fuzzy search across tasks, documents, and decisions with `backlog search` +- ✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index +- ✅ **Definition of Done checklists**: Per-task DoD items with add/remove/check/uncheck +- ✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`) +- ✅ **Git Integration**: Automatic tracking of task states across branches +- ✅ **Dependencies**: Task relationships and subtask hierarchies +- ✅ **Documentation & Decisions**: Structured docs and architectural decision records +- ✅ **Export & Reporting**: Generate markdown reports and board snapshots +- ✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing + +### Why This Matters to You (AI Agent) + +1. **Comprehensive system** - Full project management capabilities through CLI +2. **The CLI is the interface** - All operations go through `backlog` commands +3. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing ( + `backlog task edit 1`) +4. **Metadata stays synchronized** - The CLI handles all the complex relationships + +### Key Understanding + +- **Tasks** live in `backlog/tasks/` as `task-<id> - <title>.md` files +- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc. +- **Use `--plain` flag** for AI-friendly output when viewing/listing +- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships + +--- + +# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI + +**ALL task operations MUST use the Backlog.md CLI commands** + +- ✅ **DO**: Use `backlog task edit` and other CLI commands +- ✅ **DO**: Use `backlog task create` to create new tasks +- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria +- ❌ **DON'T**: Edit markdown files directly +- ❌ **DON'T**: Manually change checkboxes in files +- ❌ **DON'T**: Add or modify text in task files without using CLI + +**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships. + +--- + +## 1. Source of Truth & File Structure + +### 📖 **UNDERSTANDING** (What you'll see when reading) + +- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**) +- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`) +- Project documentation is in **`backlog/docs/`** +- Project decisions are in **`backlog/decisions/`** + +### 🔧 **ACTING** (How to change things) + +- **All task operations MUST use the Backlog.md CLI tool** +- This ensures metadata is correctly updated and the project stays in sync +- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output + +--- + +## 2. Common Mistakes to Avoid + +### ❌ **WRONG: Direct File Editing** + +```markdown +# DON'T DO THIS: + +1. Open backlog/tasks/task-7 - Feature.md in editor +2. Change "- [ ]" to "- [x]" manually +3. Add notes or final summary directly to the file +4. Save the file +``` + +### ✅ **CORRECT: Using CLI Commands** + +```bash +# DO THIS INSTEAD: +backlog task edit 7 --check-ac 1 # Mark AC #1 as complete +backlog task edit 7 --notes "Implementation complete" # Add notes +backlog task edit 7 --final-summary "PR-style summary" # Add final summary +backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task +``` + +--- + +## 3. Understanding Task Format (Read-Only Reference) + +⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files. +**Never edit these directly! Use CLI commands to make changes.** + +### Task Structure You'll See + +```markdown +--- +id: task-42 +title: Add GraphQL resolver +status: To Do +assignee: [@sara] +labels: [backend, api] +--- + +## Description + +Brief explanation of the task purpose. + +## Acceptance Criteria + +<!-- AC:BEGIN --> + +- [ ] #1 First criterion +- [x] #2 Second criterion (completed) +- [ ] #3 Third criterion + +<!-- AC:END --> + +## Definition of Done + +<!-- DOD:BEGIN --> + +- [ ] #1 Tests pass +- [ ] #2 Docs updated + +<!-- DOD:END --> + +## Implementation Plan + +1. Research approach +2. Implement solution + +## Implementation Notes + +Progress notes captured during implementation. + +## Final Summary + +PR-style summary of what was implemented. +``` + +### How to Modify Each Section + +| What You Want to Change | CLI Command to Use | +|-------------------------|----------------------------------------------------------| +| Title | `backlog task edit 42 -t "New Title"` | +| Status | `backlog task edit 42 -s "In Progress"` | +| Assignee | `backlog task edit 42 -a @sara` | +| Labels | `backlog task edit 42 -l backend,api` | +| Description | `backlog task edit 42 -d "New description"` | +| Add AC | `backlog task edit 42 --ac "New criterion"` | +| Add DoD | `backlog task edit 42 --dod "Ship notes"` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check DoD #1 | `backlog task edit 42 --check-dod 1` | +| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` | +| Uncheck DoD #2 | `backlog task edit 42 --uncheck-dod 2` | +| Remove AC #3 | `backlog task edit 42 --remove-ac 3` | +| Remove DoD #3 | `backlog task edit 42 --remove-dod 3` | +| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add Notes (replace) | `backlog task edit 42 --notes "What I did"` | +| Append Notes | `backlog task edit 42 --append-notes "Another note"` | +| Add Final Summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append Final Summary | `backlog task edit 42 --append-final-summary "Another detail"` | +| Clear Final Summary | `backlog task edit 42 --clear-final-summary` | + +--- + +## 4. Defining Tasks + +### Creating New Tasks + +**Always use CLI to create tasks:** + +```bash +# Example +backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion" +``` + +### Title (one liner) + +Use a clear brief title that summarizes the task. + +### Description (The "why") + +Provide a concise summary of the task purpose and its goal. Explains the context without implementation details. + +### Acceptance Criteria (The "what") + +**Understanding the Format:** + +- Acceptance criteria appear as numbered checkboxes in the markdown files +- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked) + +**Managing Acceptance Criteria via CLI:** + +⚠️ **IMPORTANT: How AC Commands Work** + +- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅ +- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅ +- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅ + +```bash +# Examples + +# Add new criteria (MULTIPLE values allowed) +backlog task edit 42 --ac "User can login" --ac "Session persists" + +# Check specific criteria by index (MULTIPLE values supported) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs +# Or check them individually if you prefer: +backlog task edit 42 --check-ac 1 # Mark #1 as complete +backlog task edit 42 --check-ac 2 # Mark #2 as complete + +# Mixed operations in single command +backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 + +# ❌ STILL WRONG - These formats don't work: +# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values +# backlog task edit 42 --check-ac 1-3 # No ranges +# backlog task edit 42 --check 1 # Wrong flag name + +# Multiple operations of same type +backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs +backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low) +``` + +### Definition of Done checklist (per-task) + +Definition of Done items are a second checklist in each task. Defaults come from `definition_of_done` in the project config file (`backlog/config.yml`, `.backlog/config.yml`, or `backlog.config.yml`) or from Web UI Settings, and can be disabled per task. + +**Managing Definition of Done via CLI:** + +```bash +# Add DoD items (MULTIPLE values allowed) +backlog task edit 42 --dod "Run tests" --dod "Update docs" + +# Check/uncheck DoD items by index (MULTIPLE values supported) +backlog task edit 42 --check-dod 1 --check-dod 2 +backlog task edit 42 --uncheck-dod 1 + +# Remove DoD items by index +backlog task edit 42 --remove-dod 2 + +# Create without defaults +backlog task create "Feature" --no-dod-defaults +``` + +**Key Principles for Good ACs:** + +- **Outcome-Oriented:** Focus on the result, not the method. +- **Testable/Verifiable:** Each criterion should be objectively testable +- **Clear and Concise:** Unambiguous language +- **Complete:** Collectively cover the task scope +- **User-Focused:** Frame from end-user or system behavior perspective + +Good Examples: + +- "User can successfully log in with valid credentials" +- "System processes 1000 requests per second without errors" +- "CLI preserves literal newlines in description/plan/notes/final summary; `\\n` sequences are not auto‑converted" + +Bad Example (Implementation Step): + +- "Add a new function handleLogin() in auth.ts" +- "Define expected behavior and document supported input patterns" + +### Task Breakdown Strategy + +1. Identify foundational components first +2. Create tasks in dependency order (foundations before features) +3. Ensure each task delivers value independently +4. Avoid creating tasks that block each other + +### Task Requirements + +- Tasks must be **atomic** and **testable** or **verifiable** +- Each task should represent a single unit of work for one PR +- **Never** reference future tasks (only tasks with id < current task id) +- Ensure tasks are **independent** and don't depend on future work + +--- + +## 5. Implementing Tasks + +### 5.1. First step when implementing a task + +The very first things you must do when you take over a task are: + +* set the task in progress +* assign it to yourself + +```bash +# Example +backlog task edit 42 -s "In Progress" -a @{myself} +``` + +### 5.2. Review Task References and Documentation + +Before planning, check if the task has any attached `references` or `documentation`: +- **References**: Related code files, GitHub issues, or URLs relevant to the implementation +- **Documentation**: Design docs, API specs, or other materials for understanding context + +These are visible in the task view output. Review them to understand the full context before drafting your plan. + +### 5.3. Create an Implementation Plan (The "how") + +Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a +plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**. +First do a quick check to see if all the tools that you are planning to use are available in the environment you are +working in. +When you are ready, write it down in the task so that you can refer to it later. + +```bash +# Example +backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test" +``` + +## 5.4. Implementation + +Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure +everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you +finish them. + +### 5.5 Implementation Notes (Progress log) + +Use Implementation Notes to log progress, decisions, and blockers as you work. +Append notes progressively during implementation using `--append-notes`: + +``` +backlog task edit 42 --append-notes "Investigated root cause" --append-notes "Added tests for edge case" +``` + +```bash +# Example +backlog task edit 42 --notes "Initial implementation done; pending integration tests" +``` + +### 5.6 Final Summary (PR description) + +When you are done implementing a task you need to prepare a PR description for it. +Because you cannot create PRs directly, write the PR as a clean summary in the Final Summary field. + +**Quality bar:** Write it like a reviewer will see it. A one‑liner is rarely enough unless the change is truly trivial. +Include the key scope so someone can understand the impact without reading the whole diff. + +```bash +# Example +backlog task edit 42 --final-summary "Implemented pattern X because Reason Y; updated files Z and W; added tests" +``` + +**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the +implementation. + +- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee. +- When you begin work, switch to edit, set the task in progress and assign to yourself + `backlog task edit <id> -s "In Progress" -a "..."`. +- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`. +- After updating the plan, share it with the user and ask for confirmation. Do not begin coding until the user approves the plan or explicitly tells you to skip the review. +- Append Implementation Notes during implementation using `--append-notes` as progress is made. +- Add Final Summary only after completing the work: `backlog task edit <id> --final-summary "..."` (replace) or append using `--append-final-summary`. + +## Phase discipline: What goes where + +- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee. +- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself) + Implementation Notes (progress log, appended as you work). +- Wrap-up: Final Summary (PR description), verify AC and Definition of Done checks. + +**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either: + +1. Update the AC first: `backlog task edit 42 --ac "New requirement"` +2. Or create a new follow up task: `backlog task create "Additional feature"` + +--- + +## 6. Typical Workflow + +```bash +# 1. Identify work +backlog task list -s "To Do" --plain + +# 2. Read task details +backlog task 42 --plain + +# 3. Start work: assign yourself & change status +backlog task edit 42 -s "In Progress" -a @myself + +# 4. Add implementation plan +backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test" + +# 5. Share the plan with the user and wait for approval (do not write code yet) + +# 6. Work on the task (write code, test, etc.) + +# 7. Mark acceptance criteria as complete (supports multiple in one command) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once +# Or check them individually if preferred: +# backlog task edit 42 --check-ac 1 +# backlog task edit 42 --check-ac 2 +# backlog task edit 42 --check-ac 3 + +# 8. Add Final Summary (PR Description) +backlog task edit 42 --final-summary "Refactored using strategy pattern, updated tests" + +# 9. Mark task as done +backlog task edit 42 -s Done +``` + +--- + +## 7. Definition of Done (DoD) + +A task is **Done** only when **ALL** of the following are complete: + +### ✅ Via CLI Commands: + +1. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each +2. **All Definition of Done items checked**: Use `backlog task edit <id> --check-dod <index>` for each +3. **Final Summary added**: Use `backlog task edit <id> --final-summary "..."` +4. **Status set to Done**: Use `backlog task edit <id> -s Done` + +### ✅ Via Code/Testing: + +5. **Tests pass**: Run test suite and linting +6. **Documentation updated**: Update relevant docs if needed +7. **Code reviewed**: Self-review your changes +8. **No regressions**: Performance, security checks pass + +⚠️ **NEVER mark a task as Done without completing ALL items above** + +--- + +## 8. Finding Tasks and Content with Search + +When users ask you to find tasks related to a topic, use the `backlog search` command with `--plain` flag: + +```bash +# Search for tasks about authentication +backlog search "auth" --plain + +# Search only in tasks (not docs/decisions) +backlog search "login" --type task --plain + +# Search with filters +backlog search "api" --status "In Progress" --plain +backlog search "bug" --priority high --plain +``` + +**Key points:** +- Uses fuzzy matching - finds "authentication" when searching "auth" +- Searches task titles, descriptions, and content +- Also searches documents and decisions unless filtered with `--type task` +- Always use `--plain` flag for AI-readable output + +--- + +## 9. Quick Reference: DO vs DON'T + +### Viewing and Finding Tasks + +| Task | ✅ DO | ❌ DON'T | +|--------------|-----------------------------|---------------------------------| +| View task | `backlog task 42 --plain` | Open and read .md file directly | +| List tasks | `backlog task list --plain` | Browse backlog/tasks folder | +| Check status | `backlog task 42 --plain` | Look at file content | +| Find by topic| `backlog search "auth" --plain` | Manually grep through files | + +### Modifying Tasks + +| Task | ✅ DO | ❌ DON'T | +|---------------|--------------------------------------|-----------------------------------| +| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file | +| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file | +| Add final summary | `backlog task edit 42 --final-summary "..."` | Type summary into .md file | +| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter | +| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file | + +--- + +## 10. Complete CLI Command Reference + +### Task Creation + +| Action | Command | +|------------------|-------------------------------------------------------------------------------------| +| Create task | `backlog task create "Title"` | +| With description | `backlog task create "Title" -d "Description"` | +| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` | +| With final summary | `backlog task create "Title" --final-summary "PR-style summary"` | +| With references | `backlog task create "Title" --ref src/api.ts --ref https://github.com/issue/123` | +| With documentation | `backlog task create "Title" --doc https://design-docs.example.com` | +| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high --ref src/api.ts --doc docs/spec.md` | +| Create draft | `backlog task create "Title" --draft` | +| Create subtask | `backlog task create "Title" -p 42` | + +### Task Modification + +| Action | Command | +|------------------|---------------------------------------------| +| Edit title | `backlog task edit 42 -t "New Title"` | +| Edit description | `backlog task edit 42 -d "New description"` | +| Change status | `backlog task edit 42 -s "In Progress"` | +| Assign | `backlog task edit 42 -a @sara` | +| Add labels | `backlog task edit 42 -l backend,api` | +| Set priority | `backlog task edit 42 --priority high` | + +### Acceptance Criteria Management + +| Action | Command | +|---------------------|-----------------------------------------------------------------------------| +| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` | +| Remove AC #2 | `backlog task edit 42 --remove-ac 2` | +| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` | +| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` | +| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` | + +### Task Content + +| Action | Command | +|------------------|----------------------------------------------------------| +| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add notes | `backlog task edit 42 --notes "Implementation details"` | +| Add final summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append final summary | `backlog task edit 42 --append-final-summary "More details"` | +| Clear final summary | `backlog task edit 42 --clear-final-summary` | +| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` | +| Add references | `backlog task edit 42 --ref src/api.ts --ref https://github.com/issue/123` | +| Add documentation | `backlog task edit 42 --doc https://design-docs.example.com --doc docs/spec.md` | + +### Multi‑line Input (Description/Plan/Notes/Final Summary) + +The CLI preserves input literally. Shells do not convert `\n` inside normal quotes. Use one of the following to insert real newlines: + +- Bash/Zsh (ANSI‑C quoting): + - Description: `backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'` + - Plan: `backlog task edit 42 --plan $'1. A\n2. B'` + - Notes: `backlog task edit 42 --notes $'Done A\nDoing B'` + - Append notes: `backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'` + - Final summary: `backlog task edit 42 --final-summary $'Shipped A\nAdded B'` + - Append final summary: `backlog task edit 42 --append-final-summary $'Added X\nAdded Y'` +- POSIX portable (printf): + - `backlog task edit 42 --notes "$(printf 'Line1\nLine2')"` +- PowerShell (backtick n): + - `backlog task edit 42 --notes "Line1`nLine2"` + +Do not expect `"...\n..."` to become a newline. That passes the literal backslash + n to the CLI by design. + +Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline. + +### Implementation Notes Formatting + +- Keep implementation notes concise and time-ordered; focus on progress, decisions, and blockers. +- Use short paragraphs or bullet lists instead of a single long line. +- Use Markdown bullets (`-` for unordered, `1.` for ordered) for readability. +- When using CLI flags like `--append-notes`, remember to include explicit + newlines. Example: + + ```bash + backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy' + ``` + +### Final Summary Formatting + +- Treat the Final Summary as a PR description: lead with the outcome, then add key changes and tests. +- Keep it clean and structured so it can be pasted directly into GitHub. +- Prefer short paragraphs or bullet lists and avoid raw progress logs. +- Aim to cover: **what changed**, **why**, **user impact**, **tests run**, and **risks/follow‑ups** when relevant. +- Avoid single‑line summaries unless the change is truly tiny. + +**Example (good, not rigid):** +``` +Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes. + +Changes: +- Added `finalSummary` to task types and markdown section parsing/serialization (ordered after notes). +- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it. + +Tests: +- bun test src/test/final-summary.test.ts +- bun test src/test/cli-final-summary.test.ts +``` + +### Task Operations + +| Action | Command | +|--------------------|----------------------------------------------| +| View task | `backlog task 42 --plain` | +| List tasks | `backlog task list --plain` | +| Search tasks | `backlog search "topic" --plain` | +| Search with filter | `backlog search "api" --status "To Do" --plain` | +| Filter by status | `backlog task list -s "In Progress" --plain` | +| Filter by assignee | `backlog task list -a @sara --plain` | +| Archive task | `backlog task archive 42` | +| Demote to draft | `backlog task demote 42` | + +--- + +## Common Issues + +| Problem | Solution | +|----------------------|--------------------------------------------------------------------| +| Task not found | Check task ID with `backlog task list --plain` | +| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers | +| Changes not saving | Ensure you're using CLI, not editing files | +| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` | + +--- + +## Remember: The Golden Rule + +**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.** +**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.** + +Full help available: `backlog --help` + +<!-- BACKLOG.MD GUIDELINES END --> diff --git a/GEMINI.md b/GEMINI.md index fb291cb..ae018dd 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -19,3 +19,630 @@ All agent instructions live in `.opencode/docs/`: - **Dev commands**: `.opencode/docs/DEV_COMMANDS.md` - **Architecture**: `.opencode/docs/ARCHITECTURE.md` - **Conventions & debugging**: `.opencode/docs/DEVELOPMENT_GUIDELINES.md` + +<!-- BACKLOG.MD GUIDELINES START --> +# Instructions for the usage of Backlog.md CLI Tool + +## Backlog.md: Comprehensive Project Management Tool via CLI + +### Assistant Objective + +Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata +remains fully synchronized and up-to-date. + +### Core Capabilities + +- ✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata +- ✅ **Search**: Fuzzy search across tasks, documents, and decisions with `backlog search` +- ✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index +- ✅ **Definition of Done checklists**: Per-task DoD items with add/remove/check/uncheck +- ✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`) +- ✅ **Git Integration**: Automatic tracking of task states across branches +- ✅ **Dependencies**: Task relationships and subtask hierarchies +- ✅ **Documentation & Decisions**: Structured docs and architectural decision records +- ✅ **Export & Reporting**: Generate markdown reports and board snapshots +- ✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing + +### Why This Matters to You (AI Agent) + +1. **Comprehensive system** - Full project management capabilities through CLI +2. **The CLI is the interface** - All operations go through `backlog` commands +3. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing ( + `backlog task edit 1`) +4. **Metadata stays synchronized** - The CLI handles all the complex relationships + +### Key Understanding + +- **Tasks** live in `backlog/tasks/` as `task-<id> - <title>.md` files +- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc. +- **Use `--plain` flag** for AI-friendly output when viewing/listing +- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships + +--- + +# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI + +**ALL task operations MUST use the Backlog.md CLI commands** + +- ✅ **DO**: Use `backlog task edit` and other CLI commands +- ✅ **DO**: Use `backlog task create` to create new tasks +- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria +- ❌ **DON'T**: Edit markdown files directly +- ❌ **DON'T**: Manually change checkboxes in files +- ❌ **DON'T**: Add or modify text in task files without using CLI + +**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships. + +--- + +## 1. Source of Truth & File Structure + +### 📖 **UNDERSTANDING** (What you'll see when reading) + +- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**) +- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`) +- Project documentation is in **`backlog/docs/`** +- Project decisions are in **`backlog/decisions/`** + +### 🔧 **ACTING** (How to change things) + +- **All task operations MUST use the Backlog.md CLI tool** +- This ensures metadata is correctly updated and the project stays in sync +- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output + +--- + +## 2. Common Mistakes to Avoid + +### ❌ **WRONG: Direct File Editing** + +```markdown +# DON'T DO THIS: + +1. Open backlog/tasks/task-7 - Feature.md in editor +2. Change "- [ ]" to "- [x]" manually +3. Add notes or final summary directly to the file +4. Save the file +``` + +### ✅ **CORRECT: Using CLI Commands** + +```bash +# DO THIS INSTEAD: +backlog task edit 7 --check-ac 1 # Mark AC #1 as complete +backlog task edit 7 --notes "Implementation complete" # Add notes +backlog task edit 7 --final-summary "PR-style summary" # Add final summary +backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task +``` + +--- + +## 3. Understanding Task Format (Read-Only Reference) + +⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files. +**Never edit these directly! Use CLI commands to make changes.** + +### Task Structure You'll See + +```markdown +--- +id: task-42 +title: Add GraphQL resolver +status: To Do +assignee: [@sara] +labels: [backend, api] +--- + +## Description + +Brief explanation of the task purpose. + +## Acceptance Criteria + +<!-- AC:BEGIN --> + +- [ ] #1 First criterion +- [x] #2 Second criterion (completed) +- [ ] #3 Third criterion + +<!-- AC:END --> + +## Definition of Done + +<!-- DOD:BEGIN --> + +- [ ] #1 Tests pass +- [ ] #2 Docs updated + +<!-- DOD:END --> + +## Implementation Plan + +1. Research approach +2. Implement solution + +## Implementation Notes + +Progress notes captured during implementation. + +## Final Summary + +PR-style summary of what was implemented. +``` + +### How to Modify Each Section + +| What You Want to Change | CLI Command to Use | +|-------------------------|----------------------------------------------------------| +| Title | `backlog task edit 42 -t "New Title"` | +| Status | `backlog task edit 42 -s "In Progress"` | +| Assignee | `backlog task edit 42 -a @sara` | +| Labels | `backlog task edit 42 -l backend,api` | +| Description | `backlog task edit 42 -d "New description"` | +| Add AC | `backlog task edit 42 --ac "New criterion"` | +| Add DoD | `backlog task edit 42 --dod "Ship notes"` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check DoD #1 | `backlog task edit 42 --check-dod 1` | +| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` | +| Uncheck DoD #2 | `backlog task edit 42 --uncheck-dod 2` | +| Remove AC #3 | `backlog task edit 42 --remove-ac 3` | +| Remove DoD #3 | `backlog task edit 42 --remove-dod 3` | +| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add Notes (replace) | `backlog task edit 42 --notes "What I did"` | +| Append Notes | `backlog task edit 42 --append-notes "Another note"` | +| Add Final Summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append Final Summary | `backlog task edit 42 --append-final-summary "Another detail"` | +| Clear Final Summary | `backlog task edit 42 --clear-final-summary` | + +--- + +## 4. Defining Tasks + +### Creating New Tasks + +**Always use CLI to create tasks:** + +```bash +# Example +backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion" +``` + +### Title (one liner) + +Use a clear brief title that summarizes the task. + +### Description (The "why") + +Provide a concise summary of the task purpose and its goal. Explains the context without implementation details. + +### Acceptance Criteria (The "what") + +**Understanding the Format:** + +- Acceptance criteria appear as numbered checkboxes in the markdown files +- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked) + +**Managing Acceptance Criteria via CLI:** + +⚠️ **IMPORTANT: How AC Commands Work** + +- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅ +- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅ +- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅ + +```bash +# Examples + +# Add new criteria (MULTIPLE values allowed) +backlog task edit 42 --ac "User can login" --ac "Session persists" + +# Check specific criteria by index (MULTIPLE values supported) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs +# Or check them individually if you prefer: +backlog task edit 42 --check-ac 1 # Mark #1 as complete +backlog task edit 42 --check-ac 2 # Mark #2 as complete + +# Mixed operations in single command +backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 + +# ❌ STILL WRONG - These formats don't work: +# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values +# backlog task edit 42 --check-ac 1-3 # No ranges +# backlog task edit 42 --check 1 # Wrong flag name + +# Multiple operations of same type +backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs +backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low) +``` + +### Definition of Done checklist (per-task) + +Definition of Done items are a second checklist in each task. Defaults come from `definition_of_done` in the project config file (`backlog/config.yml`, `.backlog/config.yml`, or `backlog.config.yml`) or from Web UI Settings, and can be disabled per task. + +**Managing Definition of Done via CLI:** + +```bash +# Add DoD items (MULTIPLE values allowed) +backlog task edit 42 --dod "Run tests" --dod "Update docs" + +# Check/uncheck DoD items by index (MULTIPLE values supported) +backlog task edit 42 --check-dod 1 --check-dod 2 +backlog task edit 42 --uncheck-dod 1 + +# Remove DoD items by index +backlog task edit 42 --remove-dod 2 + +# Create without defaults +backlog task create "Feature" --no-dod-defaults +``` + +**Key Principles for Good ACs:** + +- **Outcome-Oriented:** Focus on the result, not the method. +- **Testable/Verifiable:** Each criterion should be objectively testable +- **Clear and Concise:** Unambiguous language +- **Complete:** Collectively cover the task scope +- **User-Focused:** Frame from end-user or system behavior perspective + +Good Examples: + +- "User can successfully log in with valid credentials" +- "System processes 1000 requests per second without errors" +- "CLI preserves literal newlines in description/plan/notes/final summary; `\\n` sequences are not auto‑converted" + +Bad Example (Implementation Step): + +- "Add a new function handleLogin() in auth.ts" +- "Define expected behavior and document supported input patterns" + +### Task Breakdown Strategy + +1. Identify foundational components first +2. Create tasks in dependency order (foundations before features) +3. Ensure each task delivers value independently +4. Avoid creating tasks that block each other + +### Task Requirements + +- Tasks must be **atomic** and **testable** or **verifiable** +- Each task should represent a single unit of work for one PR +- **Never** reference future tasks (only tasks with id < current task id) +- Ensure tasks are **independent** and don't depend on future work + +--- + +## 5. Implementing Tasks + +### 5.1. First step when implementing a task + +The very first things you must do when you take over a task are: + +* set the task in progress +* assign it to yourself + +```bash +# Example +backlog task edit 42 -s "In Progress" -a @{myself} +``` + +### 5.2. Review Task References and Documentation + +Before planning, check if the task has any attached `references` or `documentation`: +- **References**: Related code files, GitHub issues, or URLs relevant to the implementation +- **Documentation**: Design docs, API specs, or other materials for understanding context + +These are visible in the task view output. Review them to understand the full context before drafting your plan. + +### 5.3. Create an Implementation Plan (The "how") + +Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a +plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**. +First do a quick check to see if all the tools that you are planning to use are available in the environment you are +working in. +When you are ready, write it down in the task so that you can refer to it later. + +```bash +# Example +backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test" +``` + +## 5.4. Implementation + +Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure +everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you +finish them. + +### 5.5 Implementation Notes (Progress log) + +Use Implementation Notes to log progress, decisions, and blockers as you work. +Append notes progressively during implementation using `--append-notes`: + +``` +backlog task edit 42 --append-notes "Investigated root cause" --append-notes "Added tests for edge case" +``` + +```bash +# Example +backlog task edit 42 --notes "Initial implementation done; pending integration tests" +``` + +### 5.6 Final Summary (PR description) + +When you are done implementing a task you need to prepare a PR description for it. +Because you cannot create PRs directly, write the PR as a clean summary in the Final Summary field. + +**Quality bar:** Write it like a reviewer will see it. A one‑liner is rarely enough unless the change is truly trivial. +Include the key scope so someone can understand the impact without reading the whole diff. + +```bash +# Example +backlog task edit 42 --final-summary "Implemented pattern X because Reason Y; updated files Z and W; added tests" +``` + +**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the +implementation. + +- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee. +- When you begin work, switch to edit, set the task in progress and assign to yourself + `backlog task edit <id> -s "In Progress" -a "..."`. +- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`. +- After updating the plan, share it with the user and ask for confirmation. Do not begin coding until the user approves the plan or explicitly tells you to skip the review. +- Append Implementation Notes during implementation using `--append-notes` as progress is made. +- Add Final Summary only after completing the work: `backlog task edit <id> --final-summary "..."` (replace) or append using `--append-final-summary`. + +## Phase discipline: What goes where + +- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee. +- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself) + Implementation Notes (progress log, appended as you work). +- Wrap-up: Final Summary (PR description), verify AC and Definition of Done checks. + +**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either: + +1. Update the AC first: `backlog task edit 42 --ac "New requirement"` +2. Or create a new follow up task: `backlog task create "Additional feature"` + +--- + +## 6. Typical Workflow + +```bash +# 1. Identify work +backlog task list -s "To Do" --plain + +# 2. Read task details +backlog task 42 --plain + +# 3. Start work: assign yourself & change status +backlog task edit 42 -s "In Progress" -a @myself + +# 4. Add implementation plan +backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test" + +# 5. Share the plan with the user and wait for approval (do not write code yet) + +# 6. Work on the task (write code, test, etc.) + +# 7. Mark acceptance criteria as complete (supports multiple in one command) +backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once +# Or check them individually if preferred: +# backlog task edit 42 --check-ac 1 +# backlog task edit 42 --check-ac 2 +# backlog task edit 42 --check-ac 3 + +# 8. Add Final Summary (PR Description) +backlog task edit 42 --final-summary "Refactored using strategy pattern, updated tests" + +# 9. Mark task as done +backlog task edit 42 -s Done +``` + +--- + +## 7. Definition of Done (DoD) + +A task is **Done** only when **ALL** of the following are complete: + +### ✅ Via CLI Commands: + +1. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each +2. **All Definition of Done items checked**: Use `backlog task edit <id> --check-dod <index>` for each +3. **Final Summary added**: Use `backlog task edit <id> --final-summary "..."` +4. **Status set to Done**: Use `backlog task edit <id> -s Done` + +### ✅ Via Code/Testing: + +5. **Tests pass**: Run test suite and linting +6. **Documentation updated**: Update relevant docs if needed +7. **Code reviewed**: Self-review your changes +8. **No regressions**: Performance, security checks pass + +⚠️ **NEVER mark a task as Done without completing ALL items above** + +--- + +## 8. Finding Tasks and Content with Search + +When users ask you to find tasks related to a topic, use the `backlog search` command with `--plain` flag: + +```bash +# Search for tasks about authentication +backlog search "auth" --plain + +# Search only in tasks (not docs/decisions) +backlog search "login" --type task --plain + +# Search with filters +backlog search "api" --status "In Progress" --plain +backlog search "bug" --priority high --plain +``` + +**Key points:** +- Uses fuzzy matching - finds "authentication" when searching "auth" +- Searches task titles, descriptions, and content +- Also searches documents and decisions unless filtered with `--type task` +- Always use `--plain` flag for AI-readable output + +--- + +## 9. Quick Reference: DO vs DON'T + +### Viewing and Finding Tasks + +| Task | ✅ DO | ❌ DON'T | +|--------------|-----------------------------|---------------------------------| +| View task | `backlog task 42 --plain` | Open and read .md file directly | +| List tasks | `backlog task list --plain` | Browse backlog/tasks folder | +| Check status | `backlog task 42 --plain` | Look at file content | +| Find by topic| `backlog search "auth" --plain` | Manually grep through files | + +### Modifying Tasks + +| Task | ✅ DO | ❌ DON'T | +|---------------|--------------------------------------|-----------------------------------| +| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file | +| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file | +| Add final summary | `backlog task edit 42 --final-summary "..."` | Type summary into .md file | +| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter | +| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file | + +--- + +## 10. Complete CLI Command Reference + +### Task Creation + +| Action | Command | +|------------------|-------------------------------------------------------------------------------------| +| Create task | `backlog task create "Title"` | +| With description | `backlog task create "Title" -d "Description"` | +| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` | +| With final summary | `backlog task create "Title" --final-summary "PR-style summary"` | +| With references | `backlog task create "Title" --ref src/api.ts --ref https://github.com/issue/123` | +| With documentation | `backlog task create "Title" --doc https://design-docs.example.com` | +| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high --ref src/api.ts --doc docs/spec.md` | +| Create draft | `backlog task create "Title" --draft` | +| Create subtask | `backlog task create "Title" -p 42` | + +### Task Modification + +| Action | Command | +|------------------|---------------------------------------------| +| Edit title | `backlog task edit 42 -t "New Title"` | +| Edit description | `backlog task edit 42 -d "New description"` | +| Change status | `backlog task edit 42 -s "In Progress"` | +| Assign | `backlog task edit 42 -a @sara` | +| Add labels | `backlog task edit 42 -l backend,api` | +| Set priority | `backlog task edit 42 --priority high` | + +### Acceptance Criteria Management + +| Action | Command | +|---------------------|-----------------------------------------------------------------------------| +| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` | +| Remove AC #2 | `backlog task edit 42 --remove-ac 2` | +| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` | +| Check AC #1 | `backlog task edit 42 --check-ac 1` | +| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` | +| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` | +| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` | + +### Task Content + +| Action | Command | +|------------------|----------------------------------------------------------| +| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | +| Add notes | `backlog task edit 42 --notes "Implementation details"` | +| Add final summary | `backlog task edit 42 --final-summary "PR-style summary"` | +| Append final summary | `backlog task edit 42 --append-final-summary "More details"` | +| Clear final summary | `backlog task edit 42 --clear-final-summary` | +| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` | +| Add references | `backlog task edit 42 --ref src/api.ts --ref https://github.com/issue/123` | +| Add documentation | `backlog task edit 42 --doc https://design-docs.example.com --doc docs/spec.md` | + +### Multi‑line Input (Description/Plan/Notes/Final Summary) + +The CLI preserves input literally. Shells do not convert `\n` inside normal quotes. Use one of the following to insert real newlines: + +- Bash/Zsh (ANSI‑C quoting): + - Description: `backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'` + - Plan: `backlog task edit 42 --plan $'1. A\n2. B'` + - Notes: `backlog task edit 42 --notes $'Done A\nDoing B'` + - Append notes: `backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'` + - Final summary: `backlog task edit 42 --final-summary $'Shipped A\nAdded B'` + - Append final summary: `backlog task edit 42 --append-final-summary $'Added X\nAdded Y'` +- POSIX portable (printf): + - `backlog task edit 42 --notes "$(printf 'Line1\nLine2')"` +- PowerShell (backtick n): + - `backlog task edit 42 --notes "Line1`nLine2"` + +Do not expect `"...\n..."` to become a newline. That passes the literal backslash + n to the CLI by design. + +Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline. + +### Implementation Notes Formatting + +- Keep implementation notes concise and time-ordered; focus on progress, decisions, and blockers. +- Use short paragraphs or bullet lists instead of a single long line. +- Use Markdown bullets (`-` for unordered, `1.` for ordered) for readability. +- When using CLI flags like `--append-notes`, remember to include explicit + newlines. Example: + + ```bash + backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy' + ``` + +### Final Summary Formatting + +- Treat the Final Summary as a PR description: lead with the outcome, then add key changes and tests. +- Keep it clean and structured so it can be pasted directly into GitHub. +- Prefer short paragraphs or bullet lists and avoid raw progress logs. +- Aim to cover: **what changed**, **why**, **user impact**, **tests run**, and **risks/follow‑ups** when relevant. +- Avoid single‑line summaries unless the change is truly tiny. + +**Example (good, not rigid):** +``` +Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes. + +Changes: +- Added `finalSummary` to task types and markdown section parsing/serialization (ordered after notes). +- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it. + +Tests: +- bun test src/test/final-summary.test.ts +- bun test src/test/cli-final-summary.test.ts +``` + +### Task Operations + +| Action | Command | +|--------------------|----------------------------------------------| +| View task | `backlog task 42 --plain` | +| List tasks | `backlog task list --plain` | +| Search tasks | `backlog search "topic" --plain` | +| Search with filter | `backlog search "api" --status "To Do" --plain` | +| Filter by status | `backlog task list -s "In Progress" --plain` | +| Filter by assignee | `backlog task list -a @sara --plain` | +| Archive task | `backlog task archive 42` | +| Demote to draft | `backlog task demote 42` | + +--- + +## Common Issues + +| Problem | Solution | +|----------------------|--------------------------------------------------------------------| +| Task not found | Check task ID with `backlog task list --plain` | +| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers | +| Changes not saving | Ensure you're using CLI, not editing files | +| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` | + +--- + +## Remember: The Golden Rule + +**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.** +**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.** + +Full help available: `backlog --help` + +<!-- BACKLOG.MD GUIDELINES END --> diff --git a/Migrate-project-management-to-Backlog.md-approach.md b/Migrate-project-management-to-Backlog.md-approach.md new file mode 100644 index 0000000..d526231 --- /dev/null +++ b/Migrate-project-management-to-Backlog.md-approach.md @@ -0,0 +1,32 @@ +# Task: Migrate to Backlog.md Architecture + +## Context +Currently, the `doro-cli` project uses a hybrid folder structure (`_plans/active/`, `_plans/archive/`) with descriptive filenames like `feat-stats.md` and `fix-tiny-volume-indicator.md`[cite: 3]. To adopt the strict, AI-optimized `Backlog.md` approach, we need to enforce a sequential ID naming convention, introduce distinct lifecycle folders, and migrate our AI agent guidelines[cite: 3, 4]. + +## Acceptance Criteria (Migration Steps) + +### 1. Rebuild the Directory Structure +Create the standardized `backlog/` folder hierarchy at the project root to replace `_plans/`[cite: 3, 4]: +- [ ] Create `backlog/drafts/` for unrefined ideas. +- [ ] Create `backlog/tasks/` for the active queue[cite: 4]. +- [ ] Create `backlog/completed/` for recently finished work[cite: 4]. +- [ ] Create `backlog/archive/` (with internal `drafts`, `tasks`, and `milestones` subfolders) for deep storage[cite: 4]. +- [ ] Create `backlog/milestones/` for high-level goal tracking[cite: 4]. + +### 2. Standardize Task Naming (The ID System) +The `Backlog.md` system relies heavily on parsing IDs for web UI and CLI Kanban views (e.g., `back-100 - Add-embedded-web-server-to-Backlog-CLI.md`)[cite: 4]. +- [ ] Define the project prefix (e.g., `doro-`). +- [ ] Rename all files in `_plans/active/`[cite: 3] to `backlog/tasks/doro-[ID] - [Kebab-Case-Title].md`. + * *Example:* `feat-stats.md` becomes `doro-101 - implement-statistics-dashboard.md`[cite: 3, 4]. + * *Example:* `fix-tiny-volume-indicator.md` becomes `doro-102 - fix-tiny-volume-indicator.md`[cite: 3, 4]. +- [ ] Convert any subtasks to use decimal notation (e.g., `doro-101.1`)[cite: 4]. + +### 3. Migrate AI Agent Instructions +`Backlog.md` treats AI agents as technical project managers with specific skills[cite: 4]. +- [ ] Review the existing `.opencode/docs/AGENT_WORKFLOW.md`[cite: 3]. +- [ ] Adapt it to the `Backlog.md` standard by creating a `.claude/agents/project-manager-backlog.md` file[cite: 4]. +- [ ] Migrate your current `.gemini/skills/`[cite: 3] to match the pattern seen in `.codex/skills/backlog-technical-project-manager/SKILL.md`[cite: 4], ensuring the AI knows how to move files from `tasks/` to `completed/` upon finishing a PR[cite: 4]. + +### 4. Deprecation & Cleanup +- [ ] Move any remaining files from `_plans/archive/`[cite: 3] to `backlog/archive/tasks/`[cite: 4], giving them sequential legacy IDs. +- [ ] Delete the old `_plans/` and `.opencode/plans/` directories[cite: 3] to prevent AI context confusion. From 3847beec71632f7705e54a8c597eae3b2c65c5db Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:10:05 +0200 Subject: [PATCH 02/13] Create task DORO-001 --- ...01 - Integrate-Backlog.md-into-doro-cli.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md diff --git a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md new file mode 100644 index 0000000..6e6f14f --- /dev/null +++ b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md @@ -0,0 +1,27 @@ +--- +id: DORO-001 +title: Integrate Backlog.md into doro-cli +status: To Do +assignee: [] +created_date: '2026-05-03 10:10' +labels: [] +dependencies: [] +--- + +## Description + +<!-- SECTION:DESCRIPTION:BEGIN --> +This task is to fully integrate the Backlog.md task management system into the doro-cli project. This includes migrating existing project plans, setting up the backlog configuration, and creating comprehensive instructions for AI agents. +<!-- SECTION:DESCRIPTION:END --> + +## Acceptance Criteria +<!-- AC:BEGIN --> +- [ ] #1 backlog init is run successfully within the doro-cli project,Existing 'plans' from doro-cli are identified and migrated into backlog tasks,A unified AGENTS.md file is created in doro-cli with instructions for using backlog,The doro-cli project is fully set up to use backlog for task management +<!-- AC:END --> + +## Definition of Done +<!-- DOD:BEGIN --> +- [ ] #1 code coverage is passing +- [ ] #2 VRTs added for ui changes +- [ ] #3 tests/linting/typecheck is green. +<!-- DOD:END --> From 7ff3118ed8a6f8df5cde7dd56dbf390416c0873d Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:10:34 +0200 Subject: [PATCH 03/13] Update task DORO-001 --- .../doro-001 - Integrate-Backlog.md-into-doro-cli.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md index 6e6f14f..8a87fc2 100644 --- a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md +++ b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md @@ -4,6 +4,7 @@ title: Integrate Backlog.md into doro-cli status: To Do assignee: [] created_date: '2026-05-03 10:10' +updated_date: '2026-05-03 10:10' labels: [] dependencies: [] --- @@ -19,6 +20,16 @@ This task is to fully integrate the Backlog.md task management system into the d - [ ] #1 backlog init is run successfully within the doro-cli project,Existing 'plans' from doro-cli are identified and migrated into backlog tasks,A unified AGENTS.md file is created in doro-cli with instructions for using backlog,The doro-cli project is fully set up to use backlog for task management <!-- AC:END --> +## Implementation Plan + +<!-- SECTION:PLAN:BEGIN --> +1. **Analyze 'doro-cli' Project Structure:** I'll start by examining the 'doro-cli' project to understand its structure, find the 'existent plans' that need migration, and identify its main functionalities. I'll look for a README.md, package manager files (like package.json), and any existing task or project management files. +2. **Integrate 'Backlog.md':** I will initialize 'Backlog.md' within the 'doro-cli' project directory. This will create the 'backlog/' directory and configuration files. I will then integrate the 'backlog' CLI tool into the 'doro-cli' project's workflow. This might involve adding scripts to package.json or similar configuration files to make 'backlog' commands easily accessible to developers (and agents). +3. **Migrate 'Existent Plans':** Once I've located the existing plans/tasks within 'doro-cli', I'll map their structure to the 'Backlog.md' task format (title, description, acceptance criteria, etc.). I will create a series of commands to read the old tasks and create new tasks in 'Backlog.md' using the 'backlog task create' command for each. +4. **Generate Agent Instructions:** I will consolidate the agent instructions from 'Backlog.md/AGENTS.md' and the existing 'doro-cli/AGENTS.md'. I will create a new 'AGENTS.md' file in the 'doro-cli' project that provides clear instructions for using 'backlog.md' within the 'doro-cli' context. This will include workflow instructions, command examples, and best practices. +5. **Final 'doro-cli' verification** I will verify that doro-cli tasks can be managed and executed by agents without any issues. +<!-- SECTION:PLAN:END --> + ## Definition of Done <!-- DOD:BEGIN --> - [ ] #1 code coverage is passing From e2d8882289d4da0a73dc0a569be71a8fbe45e5b3 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:14:26 +0200 Subject: [PATCH 04/13] Create task DORO-002 --- .backlog/tasks/doro-002 - Usage-Statistics.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .backlog/tasks/doro-002 - Usage-Statistics.md diff --git a/.backlog/tasks/doro-002 - Usage-Statistics.md b/.backlog/tasks/doro-002 - Usage-Statistics.md new file mode 100644 index 0000000..cf7c7da --- /dev/null +++ b/.backlog/tasks/doro-002 - Usage-Statistics.md @@ -0,0 +1,32 @@ +--- +id: DORO-002 +title: Usage Statistics +status: To Do +assignee: [] +created_date: '2026-05-03 10:14' +labels: [] +dependencies: [] +--- + +## Description + +<!-- SECTION:DESCRIPTION:BEGIN --> +This plan covers recording session statistics to a local file with protection against race conditions from concurrent instances. It adds a new --stats command to display the data. +<!-- SECTION:DESCRIPTION:END --> + +## Acceptance Criteria +<!-- AC:BEGIN --> +- [ ] #1 Install 'proper-lockfile' dependency to manage concurrent file access. +- [ ] #2 Create 'src/stats.ts' module with file-locking logic for reading and writing 'stats.json'. +- [ ] #3 Integrate session recording into 'DoroApp', calling the stats module upon session completion. +- [ ] #4 Add '--stats' flag handling to 'src/cli.ts' to trigger the stats view. +- [ ] #5 Create 'src/stats-ui.ts' to render the statistics in a clean, responsive, full-screen view. +- [ ] #6 Verify changes by running the type checker and adding new unit tests for the stats logic. +<!-- AC:END --> + +## Definition of Done +<!-- DOD:BEGIN --> +- [ ] #1 code coverage is passing +- [ ] #2 VRTs added for ui changes +- [ ] #3 tests/linting/typecheck is green. +<!-- DOD:END --> From e55c1a9851e14b73b638a4a77d0df5a7b28b42d4 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:14:28 +0200 Subject: [PATCH 05/13] Create task DORO-003 --- ...doro-003 - Fix-Tiny-UI-Volume-Indicator.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .backlog/tasks/doro-003 - Fix-Tiny-UI-Volume-Indicator.md diff --git a/.backlog/tasks/doro-003 - Fix-Tiny-UI-Volume-Indicator.md b/.backlog/tasks/doro-003 - Fix-Tiny-UI-Volume-Indicator.md new file mode 100644 index 0000000..09a87dd --- /dev/null +++ b/.backlog/tasks/doro-003 - Fix-Tiny-UI-Volume-Indicator.md @@ -0,0 +1,34 @@ +--- +id: DORO-003 +title: Fix Tiny UI Volume Indicator +status: To Do +assignee: [] +created_date: '2026-05-03 10:14' +labels: [] +dependencies: [] +--- + +## Description + +<!-- SECTION:DESCRIPTION:BEGIN --> +Currently responsive UI hides volume indicators when doro is tiny (16x3). Add compact volume icons and prioritize volume visibility over lock state for ultra-small terminals. Also fix missing sound indicator on medium screens. +<!-- SECTION:DESCRIPTION:END --> + +## Acceptance Criteria +<!-- AC:BEGIN --> +- [ ] #1 Analyze current getRunningStatusText fallback logic in src/ui.ts +- [ ] #2 Add compact volume icons (✕♪♫ for volume, ⊘○ for lock) to status candidates +- [ ] #3 Reorder status fallback to prioritize volume indicators in tiny widths +- [ ] #4 Add unit tests for volume indicator visibility at constrained widths +- [ ] #5 Extend VRT tests to capture volume mode states at tiny/ultra-small sizes +- [ ] #6 Verify changes by running the type checker and unit tests +- [ ] #7 Fix missing sound indicator on medium screen sizes +- [ ] #8 Test across all screen sizes (large, medium, small, ultra-small, tiny) +<!-- AC:END --> + +## Definition of Done +<!-- DOD:BEGIN --> +- [ ] #1 code coverage is passing +- [ ] #2 VRTs added for ui changes +- [ ] #3 tests/linting/typecheck is green. +<!-- DOD:END --> From 24f5cd01dde3c000afabd1d4d578084847cf5d75 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:14:30 +0200 Subject: [PATCH 06/13] Create task DORO-004 --- .../tasks/doro-004 - doro-cli-on-Mobile.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .backlog/tasks/doro-004 - doro-cli-on-Mobile.md diff --git a/.backlog/tasks/doro-004 - doro-cli-on-Mobile.md b/.backlog/tasks/doro-004 - doro-cli-on-Mobile.md new file mode 100644 index 0000000..e0cfd47 --- /dev/null +++ b/.backlog/tasks/doro-004 - doro-cli-on-Mobile.md @@ -0,0 +1,33 @@ +--- +id: DORO-004 +title: doro-cli on Mobile +status: To Do +assignee: [] +created_date: '2026-05-03 10:14' +labels: [] +dependencies: [] +--- + +## Description + +<!-- SECTION:DESCRIPTION:BEGIN --> +This plan explores viable paths to bring doro-cli to mobile. It evaluates zero-code workarounds (SSH, Termux) through to medium-effort in-repo additions (web terminal server) and a longer-term PWA approach. +<!-- SECTION:DESCRIPTION:END --> + +## Acceptance Criteria +<!-- AC:BEGIN --> +- [ ] #1 Add 'Mobile / Remote Access' section to README.md documenting SSH and Termux paths. +- [ ] #2 Create 'src/serve.ts' — HTTP + WebSocket + node-pty bridge for '--serve' mode. +- [ ] #3 Update 'src/cli.ts' to parse '--serve [port]' and invoke 'serve.ts'. +- [ ] #4 Promote 'node-pty' from 'devDependencies' to 'dependencies' in 'package.json'. +- [ ] #5 Add graceful audio-fallback / '--no-audio' flag to support Termux where audio APIs are unavailable. +- [ ] #6 Open a tracking issue for the PWA companion app (Option D) as future work. +- [ ] #7 Verify changes by running the type checker and unit tests. +<!-- AC:END --> + +## Definition of Done +<!-- DOD:BEGIN --> +- [ ] #1 code coverage is passing +- [ ] #2 VRTs added for ui changes +- [ ] #3 tests/linting/typecheck is green. +<!-- DOD:END --> From 64bd48208c92cf94f8a159dca5b47925eda1cbd3 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:14:32 +0200 Subject: [PATCH 07/13] Create task DORO-005 --- .backlog/tasks/doro-005 - UI-Themes.md | 33 ++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .backlog/tasks/doro-005 - UI-Themes.md diff --git a/.backlog/tasks/doro-005 - UI-Themes.md b/.backlog/tasks/doro-005 - UI-Themes.md new file mode 100644 index 0000000..dd2ea0a --- /dev/null +++ b/.backlog/tasks/doro-005 - UI-Themes.md @@ -0,0 +1,33 @@ +--- +id: DORO-005 +title: UI Themes +status: To Do +assignee: [] +created_date: '2026-05-03 10:14' +labels: [] +dependencies: [] +--- + +## Description + +<!-- SECTION:DESCRIPTION:BEGIN --> +Introduce a theme manager, add two extra default themes, and persist the selection via config. Extends existing color scheme system from 2 to 4 themes. +<!-- SECTION:DESCRIPTION:END --> + +## Acceptance Criteria +<!-- AC:BEGIN --> +- [ ] #1 Create 'src/theme.ts' with registry for 'modern', 'calm', 'vivid', 'monochrome' palettes. +- [ ] #2 Refactor UI components to use theme tokens from theme manager. +- [ ] #3 Add '--theme' CLI flag for setting theme at startup. +- [ ] #4 Update config handling to persist selected theme (extends existing colorScheme field). +- [ ] #5 Write unit tests for theme manager. +- [ ] #6 Document usage and customization. +- [ ] #7 Verify changes by running the type checker and unit tests. +<!-- AC:END --> + +## Definition of Done +<!-- DOD:BEGIN --> +- [ ] #1 code coverage is passing +- [ ] #2 VRTs added for ui changes +- [ ] #3 tests/linting/typecheck is green. +<!-- DOD:END --> From 2f932525767a92b9678160d3d04341700670248a Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:16:12 +0200 Subject: [PATCH 08/13] chore(plans): cleanup --- .backlog/config.yml | 17 ++ .claude/agents/project-manager-backlog.md | 193 +++++++++++++++++++++ _plans/TEMPLATE.md | 15 -- _plans/active/feat-stats.md | 18 -- _plans/active/fix-tiny-volume-indicator.md | 33 ---- _plans/active/mobile.md | 138 --------------- _plans/active/ui-themes.md | 19 -- _plans/archive/commit-approval-system.md | 38 ---- _plans/feature-update-notifier.md | 34 ---- 9 files changed, 210 insertions(+), 295 deletions(-) create mode 100644 .backlog/config.yml create mode 100644 .claude/agents/project-manager-backlog.md delete mode 100644 _plans/TEMPLATE.md delete mode 100644 _plans/active/feat-stats.md delete mode 100644 _plans/active/fix-tiny-volume-indicator.md delete mode 100644 _plans/active/mobile.md delete mode 100644 _plans/active/ui-themes.md delete mode 100644 _plans/archive/commit-approval-system.md delete mode 100644 _plans/feature-update-notifier.md diff --git a/.backlog/config.yml b/.backlog/config.yml new file mode 100644 index 0000000..7f0ce1a --- /dev/null +++ b/.backlog/config.yml @@ -0,0 +1,17 @@ +project_name: "doro-cli" +default_status: "To Do" +statuses: ["To Do", "In Progress", "Done"] +labels: [] +definition_of_done: ["code coverage is passing, VRTs added for ui changes, tests/linting/typecheck is green."] +date_format: yyyy-mm-dd +max_column_width: 20 +default_editor: "subl -w" +auto_open_browser: true +default_port: 6420 +remote_operations: true +auto_commit: true +zero_padded_ids: 3 +bypass_git_hooks: true +check_active_branches: true +active_branch_days: 20 +task_prefix: "doro" diff --git a/.claude/agents/project-manager-backlog.md b/.claude/agents/project-manager-backlog.md new file mode 100644 index 0000000..1cc6ad6 --- /dev/null +++ b/.claude/agents/project-manager-backlog.md @@ -0,0 +1,193 @@ +--- +name: project-manager-backlog +description: Use this agent when you need to manage project tasks using the backlog.md CLI tool. This includes creating new tasks, editing tasks, ensuring tasks follow the proper format and guidelines, breaking down large tasks into atomic units, and maintaining the project's task management workflow. Examples: <example>Context: User wants to create a new task for adding a feature. user: "I need to add a new authentication system to the project" assistant: "I'll use the project-manager-backlog agent that will use backlog cli to create a properly structured task for this feature." <commentary>Since the user needs to create a task for the project, use the Task tool to launch the project-manager-backlog agent to ensure the task follows backlog.md guidelines.</commentary></example> <example>Context: User has multiple related features to implement. user: "We need to implement user profiles, settings page, and notification preferences" assistant: "Let me use the project-manager-backlog agent to break these down into atomic, independent tasks." <commentary>The user has a complex set of features that need to be broken down into proper atomic tasks following backlog.md structure.</commentary></example> <example>Context: User wants to review if their task description is properly formatted. user: "Can you check if this task follows our guidelines: 'task-123 - Implement user login'" assistant: "I'll use the project-manager-backlog agent to review this task against our backlog.md standards." <commentary>The user needs task review, so use the project-manager-backlog agent to ensure compliance with project guidelines.</commentary></example> +color: blue +--- + +You are an expert project manager specializing in the backlog.md task management system. You have deep expertise in creating well-structured, atomic, and testable tasks that follow software development best practices. + +## Backlog.md CLI Tool + +**IMPORTANT: Backlog.md uses standard CLI commands, NOT slash commands.** + +You use the `backlog` CLI tool to manage project tasks. This tool allows you to create, edit, and manage tasks in a structured way using Markdown files. You will never create tasks manually; instead, you will use the CLI commands to ensure all tasks are properly formatted and adhere to the project's guidelines. + +The backlog CLI is installed globally and available in the PATH. Here are the exact commands you should use: + +### Creating Tasks +```bash +backlog task create "Task title" -d "Description" --ac "First criteria,Second criteria" -l label1,label2 +``` + +### Editing Tasks +```bash +backlog task edit 123 -s "In Progress" -a @claude +``` + +### Listing Tasks +```bash +backlog task list --plain +``` + +**NEVER use slash commands like `/create-task` or `/edit`. These do not exist in Backlog.md.** +**ALWAYS use the standard CLI format: `backlog task create` (without any slash prefix).** + +### Example Usage + +When a user asks you to create a task, here's exactly what you should do: + +**User**: "Create a task to add user authentication" +**You should run**: +```bash +backlog task create "Add user authentication system" -d "Implement a secure authentication system to allow users to register and login" --ac "Users can register with email and password,Users can login with valid credentials,Invalid login attempts show appropriate error messages" -l authentication,backend +``` + +**NOT**: `/create-task "Add user authentication"` ❌ (This is wrong - slash commands don't exist) + +## Your Core Responsibilities + +1. **Task Creation**: You create tasks that strictly adhere to the backlog.md cli commands. Never create tasks manually. Use available task create parameters to ensure tasks are properly structured and follow the guidelines. +2. **Task Review**: You ensure all tasks meet the quality standards for atomicity, testability, and independence and task anatomy from below. +3. **Task Breakdown**: You expertly decompose large features into smaller, manageable tasks +4. **Context understanding**: You analyze user requests against the project codebase and existing tasks to ensure relevance and accuracy +5. **Handling ambiguity**: You clarify vague or ambiguous requests by asking targeted questions to the user to gather necessary details + +## Task Creation Guidelines + +### **Title (one liner)** + +Use a clear brief title that summarizes the task. + +### **Description**: (The **"why"**) + +Provide a concise summary of the task purpose and its goal. Do not add implementation details here. It +should explain the purpose, the scope and context of the task. Code snippets should be avoided. + +### **Acceptance Criteria**: (The **"what"**) + +List specific, measurable outcomes that define what means to reach the goal from the description. Use checkboxes (`- [ ]`) for tracking. +When defining `## Acceptance Criteria` for a task, focus on **outcomes, behaviors, and verifiable requirements** rather +than step-by-step implementation details. +Acceptance Criteria (AC) define *what* conditions must be met for the task to be considered complete. +They should be testable and confirm that the core purpose of the task is achieved. +**Key Principles for Good ACs:** + +- **Outcome-Oriented:** Focus on the result, not the method. +- **Testable/Verifiable:** Each criterion should be something that can be objectively tested or verified. +- **Clear and Concise:** Unambiguous language. +- **Complete:** Collectively, ACs should cover the scope of the task. +- **User-Focused (where applicable):** Frame ACs from the perspective of the end-user or the system's external behavior. + + - *Good Example:* "- [ ] User can successfully log in with valid credentials." + - *Good Example:* "- [ ] System processes 1000 requests per second without errors." + - *Bad Example (Implementation Step):* "- [ ] Add a new function `handleLogin()` in `auth.ts`." + +### Task file + +Once a task is created using backlog cli, it will be stored in `backlog/tasks/` directory as a Markdown file with the format +`task-<id> - <title>.md` (e.g. `task-42 - Add GraphQL resolver.md`). + +## Task Breakdown Strategy + +When breaking down features: +1. Identify the foundational components first +2. Create tasks in dependency order (foundations before features) +3. Ensure each task delivers value independently +4. Avoid creating tasks that block each other + +### Additional task requirements + +- Tasks must be **atomic** and **testable**. If a task is too large, break it down into smaller subtasks. + Each task should represent a single unit of work that can be completed in a single PR. + +- **Never** reference tasks that are to be done in the future or that are not yet created. You can only reference + previous tasks (id < current task id). + +- When creating multiple tasks, ensure they are **independent** and they do not depend on future tasks. + Example of correct tasks splitting: task 1: "Add system for handling API requests", task 2: "Add user model and DB + schema", task 3: "Add API endpoint for user data". + Example of wrong tasks splitting: task 1: "Add API endpoint for user data", task 2: "Define the user model and DB + schema". + +## Recommended Task Anatomy + +```markdown +# task‑42 - Add GraphQL resolver + +## Description (the why) + +Short, imperative explanation of the goal of the task and why it is needed. + +## Acceptance Criteria (the what) + +- [ ] Resolver returns correct data for happy path +- [ ] Error response matches REST +- [ ] P95 latency ≤ 50 ms under 100 RPS + +## Implementation Plan (the how) (added after putting the task in progress but before implementing any code change) + +1. Research existing GraphQL resolver patterns +2. Implement basic resolver with error handling +3. Add performance monitoring +4. Write unit and integration tests +5. Benchmark performance under load + +## Implementation Notes (for reviewers) (only added after finishing the code implementation of a task) + +- Approach taken +- Features implemented or modified +- Technical decisions and trade-offs +- Modified or added files +``` + +## Quality Checks + +Before finalizing any task creation, verify: +- [ ] Title is clear and brief +- [ ] Description explains WHY without HOW +- [ ] Each AC is outcome-focused and testable +- [ ] Task is atomic (single PR scope) +- [ ] No dependencies on future tasks + +You are meticulous about these standards and will guide users to create high-quality tasks that enhance project productivity and maintainability. + +## Self reflection +When creating a task, always think from the perspective of an AI Agent that will have to work with this task in the future. +Ensure that the task is structured in a way that it can be easily understood and processed by AI coding agents. + +## Handy CLI Commands + +| Action | Example | +|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Create task | `backlog task create "Add OAuth System"` | +| Create with description | `backlog task create "Feature" -d "Add authentication system"` | +| Create with assignee | `backlog task create "Feature" -a @sara` | +| Create with status | `backlog task create "Feature" -s "In Progress"` | +| Create with labels | `backlog task create "Feature" -l auth,backend` | +| Create with priority | `backlog task create "Feature" --priority high` | +| Create with plan | `backlog task create "Feature" --plan "1. Research\n2. Implement"` | +| Create with AC | `backlog task create "Feature" --ac "Must work,Must be tested"` | +| Create with notes | `backlog task create "Feature" --notes "Started initial research"` | +| Create with deps | `backlog task create "Feature" --dep task-1,task-2` | +| Create sub task | `backlog task create -p 14 "Add Login with Google"` | +| Create (all options) | `backlog task create "Feature" -d "Description" -a @sara -s "To Do" -l auth --priority high --ac "Must work" --notes "Initial setup done" --dep task-1 -p 14` | +| List tasks | `backlog task list [-s <status>] [-a <assignee>] [-p <parent>]` | +| List by parent | `backlog task list --parent 42` or `backlog task list -p task-42` | +| View detail | `backlog task 7` (interactive UI, press 'E' to edit in editor) | +| View (AI mode) | `backlog task 7 --plain` | +| Edit | `backlog task edit 7 -a @sara -l auth,backend` | +| Add plan | `backlog task edit 7 --plan "Implementation approach"` | +| Add AC | `backlog task edit 7 --ac "New criterion,Another one"` | +| Add notes | `backlog task edit 7 --notes "Completed X, working on Y"` | +| Add deps | `backlog task edit 7 --dep task-1 --dep task-2` | +| Archive | `backlog task archive 7` | +| Create draft | `backlog task create "Feature" --draft` | +| Draft flow | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` | +| Demote to draft | `backlog task demote <id>` | + +Full help: `backlog --help` + +## Tips for AI Agents + +- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output instead of using Backlog.md + interactive UI. diff --git a/_plans/TEMPLATE.md b/_plans/TEMPLATE.md deleted file mode 100644 index 302759d..0000000 --- a/_plans/TEMPLATE.md +++ /dev/null @@ -1,15 +0,0 @@ -# Plan: [Feature Name] - -- **Feature**: [Brief description of the feature] -- **Branch**: `feature/[branch-name]` -- **Status**: `Pending` -- **Depends On**: [Optional: Reference to another plan file, e.g., `feat-config.md`] -- **Summary**: [A short summary of what this plan covers and any new dependencies.] - ---- - -### Checklist - -- [ ] **(Mandatory)** [Task description] -- [ ] **(Optional)** [Task description] -- [ ] **(Mandatory)** Verify changes by running the type checker and unit tests. diff --git a/_plans/active/feat-stats.md b/_plans/active/feat-stats.md deleted file mode 100644 index 4780092..0000000 --- a/_plans/active/feat-stats.md +++ /dev/null @@ -1,18 +0,0 @@ -# Plan: Usage Statistics - -- **Feature**: Usage statistics collection and display. -- **Branch**: `feature/usage-stats` -- **Status**: `Pending` -- **Depends On**: N/A -- **Summary**: This plan covers recording session statistics to a local file with protection against race conditions from concurrent instances. It adds a new `--stats` command to display the data. It introduces one new dependency. - ---- - -### Checklist - -- [ ] **(Mandatory)** Install `proper-lockfile` dependency to manage concurrent file access. -- [ ] **(Mandatory)** Create `src/stats.ts` module with file-locking logic for reading and writing `stats.json`. -- [ ] **(Mandatory)** Integrate session recording into `DoroApp`, calling the stats module upon session completion. -- [ ] **(Mandatory)** Add `--stats` flag handling to `src/cli.ts` to trigger the stats view. -- [ ] **(Mandatory)** Create `src/stats-ui.ts` to render the statistics in a clean, responsive, full-screen view. -- [ ] **(Mandatory)** Verify changes by running the type checker and adding new unit tests for the stats logic. diff --git a/_plans/active/fix-tiny-volume-indicator.md b/_plans/active/fix-tiny-volume-indicator.md deleted file mode 100644 index edb1f11..0000000 --- a/_plans/active/fix-tiny-volume-indicator.md +++ /dev/null @@ -1,33 +0,0 @@ -# Plan: Fix Tiny UI Volume Indicator - -- **Feature**: Show volume state (normal/quiet/muted) in responsive UI even at extremely small terminal sizes -- **Branch**: `fix/tiny-ui-volume-indicator` -- **Status**: `In Progress` -- **Depends On**: None -- **Summary**: Currently responsive UI hides volume indicators when doro is tiny (16x3). Add compact volume icons and prioritize volume visibility over lock state for ultra-small terminals. Also fix missing sound indicator on medium screens. - ---- - -### Issues Found - -1. **Tiny Terminal (16x3)**: Volume indicators completely missing ✅ FIXED -2. **Medium Terminal**: Sound indicator not displaying in status line (see image: shows "RUNNING | OPEN" but no volume indicator) - -### Checklist - -- [x] **(Mandatory)** Analyze current getRunningStatusText fallback logic in src/ui.ts -- [x] **(Mandatory)** Add compact volume icons (✕♪♫ for volume, ⊘○ for lock) to status candidates -- [x] **(Mandatory)** Reorder status fallback to prioritize volume indicators in tiny widths -- [x] **(Mandatory)** Add unit tests for volume indicator visibility at constrained widths -- [x] **(Mandatory)** Extend VRT tests to capture volume mode states at tiny/ultra-small sizes -- [x] **(Mandatory)** Verify changes by running the type checker and unit tests -- [ ] **(Critical)** Fix missing sound indicator on medium screen sizes -- [ ] **(Mandatory)** Test across all screen sizes (large, medium, small, ultra-small, tiny) - -### Implementation Notes - -- Used classic Unicode characters for broad compatibility: ⊘ (locked), ○ (unlocked), ✕ (muted), ♪ (quiet), ♫ (normal) -- Status line fallback now prioritizes volume over lock state at ultra-tiny widths -- Added new status candidates: `${status} ${volumeIcon}` and `${lockIcon} ${volumeIcon}` -- Volume indicator appears even at 1-character width -- **NEW**: Need to investigate why medium screens don't show volume indicator despite having space diff --git a/_plans/active/mobile.md b/_plans/active/mobile.md deleted file mode 100644 index 575abd7..0000000 --- a/_plans/active/mobile.md +++ /dev/null @@ -1,138 +0,0 @@ -# Plan: doro-cli on Mobile - -- **Feature**: Research and plan for running doro-cli on mobile devices. -- **Branch**: `feature/mobile` -- **Status**: `Research` -- **Depends On**: N/A -- **Summary**: This plan explores viable paths to bring doro-cli to mobile. It evaluates zero-code workarounds (SSH, Termux) through to medium-effort in-repo additions (web terminal server) and a longer-term PWA approach. A concrete implementation path is recommended based on effort vs. value. - ---- - -## Context - -`doro-cli` is a Node.js ≥22, `neo-blessed`-based TUI application. Its architecture has two -strengths relevant to mobile: - -1. **Pure timer logic** — `src/stateMachine.ts` has zero Node.js-specific imports and can - run in a browser or React Native environment unchanged. -2. **xterm.js + node-pty already in the repo** — both packages are listed as `devDependencies` - (used by visual regression tests in `tests/`), so a web-terminal bridge requires no new - production dependencies. - ---- - -## Possible Approaches - -### Option A — SSH into a Remote Host (Zero Code) - -Run doro-cli on a Linux server or desktop, then connect from a mobile SSH client. - -| Aspect | Detail | -|---|---| -| **Mobile SSH clients** | Termius (iOS/Android), Blink Shell (iOS), JuiceSSH (Android), Mosh for flaky connections | -| **Code changes** | None | -| **Audio** | Works if the server has audio; silent on the mobile side (acceptable for remote use) | -| **Pros** | Full feature parity, zero maintenance overhead for the project | -| **Cons** | Requires an always-on server or desktop; not fully offline/mobile-native | - -**Best for**: power users with a home server or cloud VM. - ---- - -### Option B — Termux (Android) / iSH (iOS) Native Terminal - -Install Node.js inside a mobile Linux environment and run doro-cli directly on the device. - -| Aspect | Detail | -|---|---| -| **Android** | Termux supports Node.js via `pkg install nodejs`. As of early 2025, Termux stable ships Node 20.x; Node 22 availability should be verified against the current Termux package index before recommending it. | -| **iOS** | iSH (Alpine Linux userspace) can run Node.js but performance is limited; not recommended for production use. | -| **Code changes** | Possibly none for core timer; audio will silently fail on Termux (acceptable). May need a `--no-audio` flag or graceful silence. | -| **Packaging** | `@yao-pkg/pkg` (already a devDependency) can produce a self-contained binary targeting `node22-linux-arm64`, removing the Node.js install requirement. | -| **Pros** | Fully offline, runs on-device, no server required | -| **Cons** | Node 22 may require Termux nightly/unstable repos (verify before documenting); audio is a no-op; small terminal size handling is assumed to work based on existing responsive design — this should be tested on a real device during implementation. | - -**Best for**: Android users comfortable with a terminal. - ---- - -### Option C — Web Terminal Bridge / `--serve` Mode (Medium Effort ★ Recommended) - -Add a `--serve [port]` flag to `src/cli.ts` that starts a minimal HTTP server embedding -xterm.js and piping a `node-pty` pseudo-terminal to a WebSocket. Any device on the same -network (including a mobile phone) can open the URL in a browser and interact with doro-cli -through the full TUI. - -``` -doro --serve # starts on http://localhost:7625 -doro --serve 9000 # custom port -``` - -The server: -1. Serves a single HTML page (similar to `tests/terminal.html`) with xterm.js loaded from a CDN. -2. Opens a WebSocket; on connect it spawns `node-pty` with `doro` (no `--serve` flag) and - bridges PTY ↔ WebSocket. -3. Resizes the PTY when the xterm.js `Terminal` fires a `resize` event. -4. Shuts down when all clients disconnect (or on SIGINT). - -**Files to create/modify:** - -| File | Change | -|---|---| -| `src/cli.ts` | Parse `--serve [port]` flag; call new `serve()` function | -| `src/serve.ts` | New module: HTTP + WebSocket + node-pty bridge | -| `README.md` | Document `--serve` mode | - -**Dependencies needed:** - -- `node-pty` — already a devDependency; promote to `dependencies`. -- `ws` — lightweight WebSocket server (~55 kB, no sub-dependencies). Note: Node.js 22 ships experimental _client-side_ WebSocket support (`--experimental-websocket`) but does not include a built-in WebSocket _server_ API. The `ws` package is required for the server side. - -| Aspect | Detail | -|---|---| -| **New npm packages** | `ws` for WebSocket server (or verify if a future Node.js LTS ships a built-in server API) | -| **Audio** | Works on the server; the mobile browser receives xterm output only (no audio forwarded — acceptable) | -| **Pros** | Any browser on the LAN works (no app install on mobile); reuses existing xterm + node-pty infra; single codebase | -| **Cons** | Requires the serve host to run Node.js; LAN-only without extra tunneling (ngrok, Tailscale) | - -**Best for**: users who want to use doro from mobile without a dedicated SSH client. - ---- - -### Option D — Progressive Web App (High Effort, Long-term) - -Port `src/stateMachine.ts` (which has zero Node.js imports) and the audio synth logic into a -standalone React/Vite PWA. The PWA runs entirely in the browser, installs to the home screen, -and works fully offline via a service worker. - -| Aspect | Detail | -|---|---| -| **Reusable today** | `src/stateMachine.ts`, `src/constants.ts`, `src/audio/synth.ts` | -| **New work** | Mobile-first UI (replaces `neo-blessed`); service worker; push/local notifications for timer end | -| **Audio** | Web Audio API — programmatic synthesis identical to the current approach | -| **Pros** | True native-feel mobile app; fully offline; can use iOS/Android home screen install | -| **Cons** | Largest scope; diverges from the CLI as a separate product; ongoing maintenance | - -**Best for**: a future v2 companion app. - ---- - -## Recommendation & Phased Plan - -| Phase | Approach | Effort | Value | -|---|---|---|---| -| **Now** | Document SSH + Termux paths in `README.md` | XS | High (immediate user value) | -| **Short-term** | Implement `--serve` mode (Option C) | M | High (LAN mobile access without extra tools) | -| **Long-term** | Evaluate PWA (Option D) as a separate repository | XL | Very High (true mobile app) | - ---- - -### Checklist - -- [ ] **(Mandatory)** Add "Mobile / Remote Access" section to `README.md` documenting SSH and Termux paths. -- [ ] **(Mandatory)** Create `src/serve.ts` — HTTP + WebSocket + node-pty bridge for `--serve` mode. -- [ ] **(Mandatory)** Update `src/cli.ts` to parse `--serve [port]` and invoke `serve.ts`. -- [ ] **(Mandatory)** Promote `node-pty` from `devDependencies` to `dependencies` in `package.json`. -- [ ] **(Optional)** Add graceful audio-fallback / `--no-audio` flag to support Termux where audio APIs are unavailable. -- [ ] **(Optional)** Open a tracking issue for the PWA companion app (Option D) as future work. -- [ ] **(Mandatory)** Verify changes by running the type checker and unit tests. diff --git a/_plans/active/ui-themes.md b/_plans/active/ui-themes.md deleted file mode 100644 index 34293d3..0000000 --- a/_plans/active/ui-themes.md +++ /dev/null @@ -1,19 +0,0 @@ -# Plan: UI Themes - -- **Feature**: Premium UI theme system with multiple palettes and user selection. -- **Branch**: `feature/ui-themes` -- **Status**: `Pending` -- **Depends On**: N/A (config system already implemented) -- **Summary**: Introduce a theme manager, add two extra default themes, and persist the selection via config. Extends existing color scheme system from 2 to 4 themes. - ---- - -### Checklist - -- [ ] **(Mandatory)** Create `src/theme.ts` with registry for `modern`, `calm`, `vivid`, `monochrome` palettes. -- [ ] **(Mandatory)** Refactor UI components to use theme tokens from theme manager. -- [ ] **(Mandatory)** Add `--theme` CLI flag for setting theme at startup. -- [ ] **(Mandatory)** Update config handling to persist selected theme (extends existing colorScheme field). -- [ ] **(Mandatory)** Write unit tests for theme manager. -- [ ] **(Optional)** Document usage and customization. -- [ ] **(Mandatory)** Verify changes by running the type checker and unit tests. diff --git a/_plans/archive/commit-approval-system.md b/_plans/archive/commit-approval-system.md deleted file mode 100644 index 73d8dad..0000000 --- a/_plans/archive/commit-approval-system.md +++ /dev/null @@ -1,38 +0,0 @@ -# Plan: Commit Approval System for AI Agents - -- **Feature**: Implement a system to prevent AI agents from committing code without explicit user approval -- **Branch**: `feature/commit-approval-system` -- **Status**: `In Progress` -- **Depends On**: None -- **Summary**: Research and implement safeguards to ensure AI agents always ask for user permission before making git commits, addressing the issue of unauthorized commits despite instructions. - ---- - -### Acceptance Criteria - -- Documentation clearly explains existing OpenCode commit protections -- Workflow instructions are explicit about pre-commit approval requirements -- Agents understand how to properly request commit approval -- Manual human commits work without friction -- Clear guidance on troubleshooting commit permission issues - -### Research Findings - -**OpenCode already prevents unauthorized commits via:** - -1. `opencode.json` permission system: `"git commit *": "deny"` for plan/general agents -2. Environment variables: `OPENCODE=1`, `OPENCODE_RUN_ID`, `OPENCODE_PROCESS_ROLE=worker` -3. Workflow requirement: `.opencode/docs/AGENT_WORKFLOW.md:34` mandates pre-commit approval - -**Root issue:** Agent compliance with existing instructions, not missing safeguards. - -### Checklist - -- [x] **(Mandatory)** Research OpenCode-specific integration points and commit mechanisms -- [x] **(Decision)** Evaluate strategy: OpenCode's existing permission system is sufficient -- [ ] **(Mandatory)** Update workflow documentation to clarify existing protections -- [ ] **(Mandatory)** Add explicit guidance for agents on commit approval workflow -- [ ] **(Mandatory)** Document troubleshooting steps for commit permission issues -- [ ] **(Optional)** Add examples of proper commit request patterns -- [ ] **(Mandatory)** Test documentation with current OpenCode setup -- [ ] **(Mandatory)** Verify changes by running the type checker and unit tests diff --git a/_plans/feature-update-notifier.md b/_plans/feature-update-notifier.md deleted file mode 100644 index 96ff539..0000000 --- a/_plans/feature-update-notifier.md +++ /dev/null @@ -1,34 +0,0 @@ -# Plan: Update Notifier - -- **Feature**: App update notification system with responsive UI and clipboard integration -- **Branch**: `feature/update-notifier` -- **Status**: `In Progress` -- **Depends On**: None -- **Summary**: Implement periodic update checking, responsive update prompts (including micro screens), clipboard integration for update commands, manual update trigger via Shift+U, and retry-on-failure behavior. Extends config schema for update policy persistence and adds npm registry version checking. Adds comprehensive VRT coverage for update prompt UI states. - ---- - -### Implementation Decisions - -- **Network Failure Policy**: Retry on next launch (do not update `lastCheckedAt` on failure) -- **Manual Trigger**: `Shift+U` shortcut to manually trigger update check flow -- **VRT Coverage**: 32 additional snapshots (4 update states × 2 themes × 4 screen sizes) - ---- - -### Checklist - -- [x] **(Mandatory)** Extend settings schema in `src/config.ts` with update fields: `lastCheckedAt`, `checkIntervalHours` (default 24), `skippedVersion` -- [x] **(Mandatory)** Create `src/update.ts` for version checking: fetch latest npm version, compare with current version, handle network failures gracefully -- [x] **(Mandatory)** Implement periodic check policy: only check when interval is due, persist `lastCheckedAt`, skip if `skippedVersion` matches latest -- [x] **(Mandatory)** Add update prompt state to `src/input.ts` with `y/n` handling that takes priority over normal shortcuts -- [x] **(Mandatory)** Add manual update trigger with `Shift+U` shortcut -- [x] **(Mandatory)** Integrate update check into app startup flow without blocking timer responsiveness -- [x] **(Mandatory)** Implement responsive update UI in `src/ui.ts` for wide, narrow, and micro screens with fallback to minimal one-line prompt -- [x] **(Mandatory)** Add clipboard integration for update command copy on "yes" selection with platform-aware fallback -- [x] **(Mandatory)** Implement "no" action: persist `skippedVersion` and continue app normally -- [x] **(Mandatory)** Implement "yes" action: copy update command to clipboard, show confirmation/fallback message, exit cleanly -- [x] **(Mandatory)** Add unit tests for config schema migration, update check logic, periodic gating, and UI responsiveness -- [x] **(Mandatory)** Extend VRT with update prompt scenarios: manual trigger, accept+copy-success, accept+copy-fallback, decline states (32 snapshots total) -- [x] **(Mandatory)** Verify changes by running the type checker and unit tests -- [x] **(Optional)** Add post-MVP auto-update mode with opt-in setting for automatic update execution From 14e1d63eb6fb19cf57dc2d0aa9c6ddcc09805f1e Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:17:00 +0200 Subject: [PATCH 09/13] Update task DORO-001 --- .../tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md index 8a87fc2..ace1b3c 100644 --- a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md +++ b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md @@ -1,10 +1,11 @@ --- id: DORO-001 title: Integrate Backlog.md into doro-cli -status: To Do -assignee: [] +status: In Progress +assignee: + - '@opencode' created_date: '2026-05-03 10:10' -updated_date: '2026-05-03 10:10' +updated_date: '2026-05-03 10:16' labels: [] dependencies: [] --- From 7d06763fb5b49360c0a9d585650a53306a1bb308 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:17:12 +0200 Subject: [PATCH 10/13] Update task DORO-002 --- .backlog/tasks/doro-002 - Usage-Statistics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.backlog/tasks/doro-002 - Usage-Statistics.md b/.backlog/tasks/doro-002 - Usage-Statistics.md index cf7c7da..059d3cd 100644 --- a/.backlog/tasks/doro-002 - Usage-Statistics.md +++ b/.backlog/tasks/doro-002 - Usage-Statistics.md @@ -4,6 +4,7 @@ title: Usage Statistics status: To Do assignee: [] created_date: '2026-05-03 10:14' +updated_date: '2026-05-03 10:17' labels: [] dependencies: [] --- @@ -16,7 +17,7 @@ This plan covers recording session statistics to a local file with protection ag ## Acceptance Criteria <!-- AC:BEGIN --> -- [ ] #1 Install 'proper-lockfile' dependency to manage concurrent file access. +- [x] #1 Install 'proper-lockfile' dependency to manage concurrent file access. - [ ] #2 Create 'src/stats.ts' module with file-locking logic for reading and writing 'stats.json'. - [ ] #3 Integrate session recording into 'DoroApp', calling the stats module upon session completion. - [ ] #4 Add '--stats' flag handling to 'src/cli.ts' to trigger the stats view. From 13964093b43ab00ca3e383dfebccf4f267f7c03a Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:18:09 +0200 Subject: [PATCH 11/13] Update task DORO-001 --- .../tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md index ace1b3c..e677690 100644 --- a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md +++ b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md @@ -5,7 +5,7 @@ status: In Progress assignee: - '@opencode' created_date: '2026-05-03 10:10' -updated_date: '2026-05-03 10:16' +updated_date: '2026-05-03 10:18' labels: [] dependencies: [] --- @@ -18,7 +18,7 @@ This task is to fully integrate the Backlog.md task management system into the d ## Acceptance Criteria <!-- AC:BEGIN --> -- [ ] #1 backlog init is run successfully within the doro-cli project,Existing 'plans' from doro-cli are identified and migrated into backlog tasks,A unified AGENTS.md file is created in doro-cli with instructions for using backlog,The doro-cli project is fully set up to use backlog for task management +- [x] #1 backlog init is run successfully within the doro-cli project,Existing 'plans' from doro-cli are identified and migrated into backlog tasks,A unified AGENTS.md file is created in doro-cli with instructions for using backlog,The doro-cli project is fully set up to use backlog for task management <!-- AC:END --> ## Implementation Plan From ba4b469611dbd5e26c5855c31fc7241210815230 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:21:05 +0200 Subject: [PATCH 12/13] Update task DORO-001 --- .../tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md index e677690..34266f9 100644 --- a/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md +++ b/.backlog/tasks/doro-001 - Integrate-Backlog.md-into-doro-cli.md @@ -1,11 +1,11 @@ --- id: DORO-001 title: Integrate Backlog.md into doro-cli -status: In Progress +status: Done assignee: - '@opencode' created_date: '2026-05-03 10:10' -updated_date: '2026-05-03 10:18' +updated_date: '2026-05-03 10:21' labels: [] dependencies: [] --- From c28fb2123a532382f794ca77f4e5a7d3eb8f42d6 Mon Sep 17 00:00:00 2001 From: Sergey Korsik <serg.korsik@gmail.com> Date: Sun, 3 May 2026 12:22:01 +0200 Subject: [PATCH 13/13] docs(ai): update agents to follow backlog.md strategy --- AGENTS.md | 665 ++++++------------------------------------------------ 1 file changed, 70 insertions(+), 595 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9fc4fe6..1730798 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,629 +23,104 @@ Agents not using OpenCode: refer to `.opencode/docs/AGENT_WORKFLOW.md`. - **Triggers**: `/antivibe` or "deep dive" - **Action**: Generate a concise learning guide for recently modified/AI-generated code. Save to `deep-dive/[component]-YYYY-MM-DD.md`. Focus on _why_ decisions were made, tied to doro-cli's TUI/state-machine architecture. See `.opencode/skills/antivibe/SKILL.md`. -<!-- BACKLOG.MD GUIDELINES START --> -# Instructions for the usage of Backlog.md CLI Tool +<!-- BACKLOG.MD MCP GUIDELINES START --> -## Backlog.md: Comprehensive Project Management Tool via CLI +<CRITICAL_INSTRUCTION> -### Assistant Objective +## BACKLOG WORKFLOW INSTRUCTIONS -Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata -remains fully synchronized and up-to-date. +This project uses Backlog.md MCP for all task and project management activities. -### Core Capabilities +**CRITICAL GUIDANCE** -- ✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata -- ✅ **Search**: Fuzzy search across tasks, documents, and decisions with `backlog search` -- ✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index -- ✅ **Definition of Done checklists**: Per-task DoD items with add/remove/check/uncheck -- ✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`) -- ✅ **Git Integration**: Automatic tracking of task states across branches -- ✅ **Dependencies**: Task relationships and subtask hierarchies -- ✅ **Documentation & Decisions**: Structured docs and architectural decision records -- ✅ **Export & Reporting**: Generate markdown reports and board snapshots -- ✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing +- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project. +- If your client only supports tools or the above request fails, call `backlog.get_backlog_instructions()` to load the tool-oriented overview. Use the `instruction` selector when you need `task-creation`, `task-execution`, or `task-finalization`. -### Why This Matters to You (AI Agent) +- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow +- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)") +- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work -1. **Comprehensive system** - Full project management capabilities through CLI -2. **The CLI is the interface** - All operations go through `backlog` commands -3. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing ( - `backlog task edit 1`) -4. **Metadata stays synchronized** - The CLI handles all the complex relationships +These guides cover: +- Decision framework for when to create tasks +- Search-first workflow to avoid duplicates +- Links to detailed guides for task creation, execution, and finalization +- MCP tools reference -### Key Understanding +You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here. -- **Tasks** live in `backlog/tasks/` as `task-<id> - <title>.md` files -- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc. -- **Use `--plain` flag** for AI-friendly output when viewing/listing -- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships +</CRITICAL_INSTRUCTION> ---- +<!-- BACKLOG.MD MCP GUIDELINES END --> -# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI +When you're working on a task, you should assign it yourself: -a @{your-name} -**ALL task operations MUST use the Backlog.md CLI commands** +In addition to the rules above, please consider the following: +At the end of every task implementation, try to take a moment to see if you can simplify it. +When you are done implementing, you know much more about a task than when you started. +At this point you can better judge retrospectively what can be the simplest architecture to solve the problem. +If you can simplify the code, do it. -- ✅ **DO**: Use `backlog task edit` and other CLI commands -- ✅ **DO**: Use `backlog task create` to create new tasks -- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria -- ❌ **DON'T**: Edit markdown files directly -- ❌ **DON'T**: Manually change checkboxes in files -- ❌ **DON'T**: Add or modify text in task files without using CLI +## Simplicity-first implementation rules -**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships. +- Prefer a single implementation for similar concerns. Reuse or refactor to a shared helper instead of duplicating. +- Keep APIs minimal. Favor load + upsert over load/save/update, and do not add unused methods. +- Avoid extra layers (services, normalizers, versioning) unless there is an immediate, proven need. +- Keep behavior consistent across similar stores (defaults, parse errors, locking). Divergence requires a clear reason. +- Don't add new exported helpers just to compute a path; derive from existing paths or add one shared helper only when reused. ---- -## 1. Source of Truth & File Structure +## Commands -### 📖 **UNDERSTANDING** (What you'll see when reading) +### Development -- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**) -- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`) -- Project documentation is in **`backlog/docs/`** -- Project decisions are in **`backlog/decisions/`** +- `npm install` - Install dependencies +- `npm run dev` - Run the CLI tool in development mode +- `npm run build` - Build the CLI tool +- `npm run typecheck` - Type-check code +- `npm run lint` - Run all ESLint checks +- `npm run format` - Format code with Prettier -### 🔧 **ACTING** (How to change things) +### Testing -- **All task operations MUST use the Backlog.md CLI tool** -- This ensures metadata is correctly updated and the project stays in sync -- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output +- `npm run test:unit` - Run all unit tests +- `npm run test:visual` - Run all visual regression tests +- `npm run test:visual:update` - Update visual regression test snapshots ---- +### Configuration Management -## 2. Common Mistakes to Avoid +- `bun run cli config list` - View all configuration values +- `bun run cli config get <key>` - Get a specific config value (e.g. defaultEditor) +- `bun run cli config set <key> <value>` - Set a config value with validation -### ❌ **WRONG: Direct File Editing** +## Core Structure -```markdown -# DON'T DO THIS: +- **CLI Tool**: Built with TypeScript and intended to be used with `npx doro-cli` or as a global npm package (`npm i -g doro-cli`) +- **Source Code**: Located in `/src` directory with modular TypeScript structure +- **Task Management**: Uses markdown files in `.backlog/` directory structure +- **Workflow**: Git-integrated with task IDs referenced in commits and PRs -1. Open backlog/tasks/task-7 - Feature.md in editor -2. Change "- [ ]" to "- [x]" manually -3. Add notes or final summary directly to the file -4. Save the file -``` +## Agent POV -### ✅ **CORRECT: Using CLI Commands** +- Treat Backlog.md as a shipped CLI/MCP binary that may be used from other repositories where agents cannot inspect this source tree. +- Backlog.md is not a supported JavaScript or TypeScript library API for external consumers. Do not treat exported source symbols, classes, or methods in `/src` as stable public interfaces unless they are explicitly documented in shipped CLI/MCP/instruction surfaces. +- When you decide what another agent can rely on, use only the public surface: MCP workflow resources, MCP tool descriptions/schemas, CLI help, and instruction files shipped with the project. +- Do not assume external agents know internal implementation details, constants, or source-only conventions. +- When reviewing changes, do not ask for compatibility shims just because a source-level method exists or was removed. Only preserve compatibility for behavior that is part of the documented CLI, MCP, config, or instruction contract. +- If a convention matters for agent behavior, document it in the public MCP/instruction surface rather than relying on source-code discovery. -```bash -# DO THIS INSTEAD: -backlog task edit 7 --check-ac 1 # Mark AC #1 as complete -backlog task edit 7 --notes "Implementation complete" # Add notes -backlog task edit 7 --final-summary "PR-style summary" # Add final summary -backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task -``` +## Code Standards ---- +- **Runtime**: Node.js >=22 with TypeScript +- **Formatting**: Prettier +- **Linting**: ESLint +- **Testing**: Jest for unit tests, Playwright for visual regression tests +- **Pre-commit**: Husky runs linting and testing before commits -## 3. Understanding Task Format (Read-Only Reference) +The pre-commit hook automatically runs linting and tests on staged files to ensure code quality. If any errors are found, the commit will be blocked until fixed. -⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files. -**Never edit these directly! Use CLI commands to make changes.** +## Git Workflow -### Task Structure You'll See - -```markdown ---- -id: task-42 -title: Add GraphQL resolver -status: To Do -assignee: [@sara] -labels: [backend, api] ---- - -## Description - -Brief explanation of the task purpose. - -## Acceptance Criteria - -<!-- AC:BEGIN --> - -- [ ] #1 First criterion -- [x] #2 Second criterion (completed) -- [ ] #3 Third criterion - -<!-- AC:END --> - -## Definition of Done - -<!-- DOD:BEGIN --> - -- [ ] #1 Tests pass -- [ ] #2 Docs updated - -<!-- DOD:END --> - -## Implementation Plan - -1. Research approach -2. Implement solution - -## Implementation Notes - -Progress notes captured during implementation. - -## Final Summary - -PR-style summary of what was implemented. -``` - -### How to Modify Each Section - -| What You Want to Change | CLI Command to Use | -|-------------------------|----------------------------------------------------------| -| Title | `backlog task edit 42 -t "New Title"` | -| Status | `backlog task edit 42 -s "In Progress"` | -| Assignee | `backlog task edit 42 -a @sara` | -| Labels | `backlog task edit 42 -l backend,api` | -| Description | `backlog task edit 42 -d "New description"` | -| Add AC | `backlog task edit 42 --ac "New criterion"` | -| Add DoD | `backlog task edit 42 --dod "Ship notes"` | -| Check AC #1 | `backlog task edit 42 --check-ac 1` | -| Check DoD #1 | `backlog task edit 42 --check-dod 1` | -| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` | -| Uncheck DoD #2 | `backlog task edit 42 --uncheck-dod 2` | -| Remove AC #3 | `backlog task edit 42 --remove-ac 3` | -| Remove DoD #3 | `backlog task edit 42 --remove-dod 3` | -| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | -| Add Notes (replace) | `backlog task edit 42 --notes "What I did"` | -| Append Notes | `backlog task edit 42 --append-notes "Another note"` | -| Add Final Summary | `backlog task edit 42 --final-summary "PR-style summary"` | -| Append Final Summary | `backlog task edit 42 --append-final-summary "Another detail"` | -| Clear Final Summary | `backlog task edit 42 --clear-final-summary` | - ---- - -## 4. Defining Tasks - -### Creating New Tasks - -**Always use CLI to create tasks:** - -```bash -# Example -backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion" -``` - -### Title (one liner) - -Use a clear brief title that summarizes the task. - -### Description (The "why") - -Provide a concise summary of the task purpose and its goal. Explains the context without implementation details. - -### Acceptance Criteria (The "what") - -**Understanding the Format:** - -- Acceptance criteria appear as numbered checkboxes in the markdown files -- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked) - -**Managing Acceptance Criteria via CLI:** - -⚠️ **IMPORTANT: How AC Commands Work** - -- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅ -- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅ -- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅ - -```bash -# Examples - -# Add new criteria (MULTIPLE values allowed) -backlog task edit 42 --ac "User can login" --ac "Session persists" - -# Check specific criteria by index (MULTIPLE values supported) -backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs -# Or check them individually if you prefer: -backlog task edit 42 --check-ac 1 # Mark #1 as complete -backlog task edit 42 --check-ac 2 # Mark #2 as complete - -# Mixed operations in single command -backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 - -# ❌ STILL WRONG - These formats don't work: -# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values -# backlog task edit 42 --check-ac 1-3 # No ranges -# backlog task edit 42 --check 1 # Wrong flag name - -# Multiple operations of same type -backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs -backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low) -``` - -### Definition of Done checklist (per-task) - -Definition of Done items are a second checklist in each task. Defaults come from `definition_of_done` in the project config file (`backlog/config.yml`, `.backlog/config.yml`, or `backlog.config.yml`) or from Web UI Settings, and can be disabled per task. - -**Managing Definition of Done via CLI:** - -```bash -# Add DoD items (MULTIPLE values allowed) -backlog task edit 42 --dod "Run tests" --dod "Update docs" - -# Check/uncheck DoD items by index (MULTIPLE values supported) -backlog task edit 42 --check-dod 1 --check-dod 2 -backlog task edit 42 --uncheck-dod 1 - -# Remove DoD items by index -backlog task edit 42 --remove-dod 2 - -# Create without defaults -backlog task create "Feature" --no-dod-defaults -``` - -**Key Principles for Good ACs:** - -- **Outcome-Oriented:** Focus on the result, not the method. -- **Testable/Verifiable:** Each criterion should be objectively testable -- **Clear and Concise:** Unambiguous language -- **Complete:** Collectively cover the task scope -- **User-Focused:** Frame from end-user or system behavior perspective - -Good Examples: - -- "User can successfully log in with valid credentials" -- "System processes 1000 requests per second without errors" -- "CLI preserves literal newlines in description/plan/notes/final summary; `\\n` sequences are not auto‑converted" - -Bad Example (Implementation Step): - -- "Add a new function handleLogin() in auth.ts" -- "Define expected behavior and document supported input patterns" - -### Task Breakdown Strategy - -1. Identify foundational components first -2. Create tasks in dependency order (foundations before features) -3. Ensure each task delivers value independently -4. Avoid creating tasks that block each other - -### Task Requirements - -- Tasks must be **atomic** and **testable** or **verifiable** -- Each task should represent a single unit of work for one PR -- **Never** reference future tasks (only tasks with id < current task id) -- Ensure tasks are **independent** and don't depend on future work - ---- - -## 5. Implementing Tasks - -### 5.1. First step when implementing a task - -The very first things you must do when you take over a task are: - -* set the task in progress -* assign it to yourself - -```bash -# Example -backlog task edit 42 -s "In Progress" -a @{myself} -``` - -### 5.2. Review Task References and Documentation - -Before planning, check if the task has any attached `references` or `documentation`: -- **References**: Related code files, GitHub issues, or URLs relevant to the implementation -- **Documentation**: Design docs, API specs, or other materials for understanding context - -These are visible in the task view output. Review them to understand the full context before drafting your plan. - -### 5.3. Create an Implementation Plan (The "how") - -Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a -plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**. -First do a quick check to see if all the tools that you are planning to use are available in the environment you are -working in. -When you are ready, write it down in the task so that you can refer to it later. - -```bash -# Example -backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test" -``` - -## 5.4. Implementation - -Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure -everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you -finish them. - -### 5.5 Implementation Notes (Progress log) - -Use Implementation Notes to log progress, decisions, and blockers as you work. -Append notes progressively during implementation using `--append-notes`: - -``` -backlog task edit 42 --append-notes "Investigated root cause" --append-notes "Added tests for edge case" -``` - -```bash -# Example -backlog task edit 42 --notes "Initial implementation done; pending integration tests" -``` - -### 5.6 Final Summary (PR description) - -When you are done implementing a task you need to prepare a PR description for it. -Because you cannot create PRs directly, write the PR as a clean summary in the Final Summary field. - -**Quality bar:** Write it like a reviewer will see it. A one‑liner is rarely enough unless the change is truly trivial. -Include the key scope so someone can understand the impact without reading the whole diff. - -```bash -# Example -backlog task edit 42 --final-summary "Implemented pattern X because Reason Y; updated files Z and W; added tests" -``` - -**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the -implementation. - -- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee. -- When you begin work, switch to edit, set the task in progress and assign to yourself - `backlog task edit <id> -s "In Progress" -a "..."`. -- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`. -- After updating the plan, share it with the user and ask for confirmation. Do not begin coding until the user approves the plan or explicitly tells you to skip the review. -- Append Implementation Notes during implementation using `--append-notes` as progress is made. -- Add Final Summary only after completing the work: `backlog task edit <id> --final-summary "..."` (replace) or append using `--append-final-summary`. - -## Phase discipline: What goes where - -- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee. -- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself) + Implementation Notes (progress log, appended as you work). -- Wrap-up: Final Summary (PR description), verify AC and Definition of Done checks. - -**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either: - -1. Update the AC first: `backlog task edit 42 --ac "New requirement"` -2. Or create a new follow up task: `backlog task create "Additional feature"` - ---- - -## 6. Typical Workflow - -```bash -# 1. Identify work -backlog task list -s "To Do" --plain - -# 2. Read task details -backlog task 42 --plain - -# 3. Start work: assign yourself & change status -backlog task edit 42 -s "In Progress" -a @myself - -# 4. Add implementation plan -backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test" - -# 5. Share the plan with the user and wait for approval (do not write code yet) - -# 6. Work on the task (write code, test, etc.) - -# 7. Mark acceptance criteria as complete (supports multiple in one command) -backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once -# Or check them individually if preferred: -# backlog task edit 42 --check-ac 1 -# backlog task edit 42 --check-ac 2 -# backlog task edit 42 --check-ac 3 - -# 8. Add Final Summary (PR Description) -backlog task edit 42 --final-summary "Refactored using strategy pattern, updated tests" - -# 9. Mark task as done -backlog task edit 42 -s Done -``` - ---- - -## 7. Definition of Done (DoD) - -A task is **Done** only when **ALL** of the following are complete: - -### ✅ Via CLI Commands: - -1. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each -2. **All Definition of Done items checked**: Use `backlog task edit <id> --check-dod <index>` for each -3. **Final Summary added**: Use `backlog task edit <id> --final-summary "..."` -4. **Status set to Done**: Use `backlog task edit <id> -s Done` - -### ✅ Via Code/Testing: - -5. **Tests pass**: Run test suite and linting -6. **Documentation updated**: Update relevant docs if needed -7. **Code reviewed**: Self-review your changes -8. **No regressions**: Performance, security checks pass - -⚠️ **NEVER mark a task as Done without completing ALL items above** - ---- - -## 8. Finding Tasks and Content with Search - -When users ask you to find tasks related to a topic, use the `backlog search` command with `--plain` flag: - -```bash -# Search for tasks about authentication -backlog search "auth" --plain - -# Search only in tasks (not docs/decisions) -backlog search "login" --type task --plain - -# Search with filters -backlog search "api" --status "In Progress" --plain -backlog search "bug" --priority high --plain -``` - -**Key points:** -- Uses fuzzy matching - finds "authentication" when searching "auth" -- Searches task titles, descriptions, and content -- Also searches documents and decisions unless filtered with `--type task` -- Always use `--plain` flag for AI-readable output - ---- - -## 9. Quick Reference: DO vs DON'T - -### Viewing and Finding Tasks - -| Task | ✅ DO | ❌ DON'T | -|--------------|-----------------------------|---------------------------------| -| View task | `backlog task 42 --plain` | Open and read .md file directly | -| List tasks | `backlog task list --plain` | Browse backlog/tasks folder | -| Check status | `backlog task 42 --plain` | Look at file content | -| Find by topic| `backlog search "auth" --plain` | Manually grep through files | - -### Modifying Tasks - -| Task | ✅ DO | ❌ DON'T | -|---------------|--------------------------------------|-----------------------------------| -| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file | -| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file | -| Add final summary | `backlog task edit 42 --final-summary "..."` | Type summary into .md file | -| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter | -| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file | - ---- - -## 10. Complete CLI Command Reference - -### Task Creation - -| Action | Command | -|------------------|-------------------------------------------------------------------------------------| -| Create task | `backlog task create "Title"` | -| With description | `backlog task create "Title" -d "Description"` | -| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` | -| With final summary | `backlog task create "Title" --final-summary "PR-style summary"` | -| With references | `backlog task create "Title" --ref src/api.ts --ref https://github.com/issue/123` | -| With documentation | `backlog task create "Title" --doc https://design-docs.example.com` | -| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high --ref src/api.ts --doc docs/spec.md` | -| Create draft | `backlog task create "Title" --draft` | -| Create subtask | `backlog task create "Title" -p 42` | - -### Task Modification - -| Action | Command | -|------------------|---------------------------------------------| -| Edit title | `backlog task edit 42 -t "New Title"` | -| Edit description | `backlog task edit 42 -d "New description"` | -| Change status | `backlog task edit 42 -s "In Progress"` | -| Assign | `backlog task edit 42 -a @sara` | -| Add labels | `backlog task edit 42 -l backend,api` | -| Set priority | `backlog task edit 42 --priority high` | - -### Acceptance Criteria Management - -| Action | Command | -|---------------------|-----------------------------------------------------------------------------| -| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` | -| Remove AC #2 | `backlog task edit 42 --remove-ac 2` | -| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` | -| Check AC #1 | `backlog task edit 42 --check-ac 1` | -| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` | -| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` | -| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` | - -### Task Content - -| Action | Command | -|------------------|----------------------------------------------------------| -| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` | -| Add notes | `backlog task edit 42 --notes "Implementation details"` | -| Add final summary | `backlog task edit 42 --final-summary "PR-style summary"` | -| Append final summary | `backlog task edit 42 --append-final-summary "More details"` | -| Clear final summary | `backlog task edit 42 --clear-final-summary` | -| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` | -| Add references | `backlog task edit 42 --ref src/api.ts --ref https://github.com/issue/123` | -| Add documentation | `backlog task edit 42 --doc https://design-docs.example.com --doc docs/spec.md` | - -### Multi‑line Input (Description/Plan/Notes/Final Summary) - -The CLI preserves input literally. Shells do not convert `\n` inside normal quotes. Use one of the following to insert real newlines: - -- Bash/Zsh (ANSI‑C quoting): - - Description: `backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'` - - Plan: `backlog task edit 42 --plan $'1. A\n2. B'` - - Notes: `backlog task edit 42 --notes $'Done A\nDoing B'` - - Append notes: `backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'` - - Final summary: `backlog task edit 42 --final-summary $'Shipped A\nAdded B'` - - Append final summary: `backlog task edit 42 --append-final-summary $'Added X\nAdded Y'` -- POSIX portable (printf): - - `backlog task edit 42 --notes "$(printf 'Line1\nLine2')"` -- PowerShell (backtick n): - - `backlog task edit 42 --notes "Line1`nLine2"` - -Do not expect `"...\n..."` to become a newline. That passes the literal backslash + n to the CLI by design. - -Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline. - -### Implementation Notes Formatting - -- Keep implementation notes concise and time-ordered; focus on progress, decisions, and blockers. -- Use short paragraphs or bullet lists instead of a single long line. -- Use Markdown bullets (`-` for unordered, `1.` for ordered) for readability. -- When using CLI flags like `--append-notes`, remember to include explicit - newlines. Example: - - ```bash - backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy' - ``` - -### Final Summary Formatting - -- Treat the Final Summary as a PR description: lead with the outcome, then add key changes and tests. -- Keep it clean and structured so it can be pasted directly into GitHub. -- Prefer short paragraphs or bullet lists and avoid raw progress logs. -- Aim to cover: **what changed**, **why**, **user impact**, **tests run**, and **risks/follow‑ups** when relevant. -- Avoid single‑line summaries unless the change is truly tiny. - -**Example (good, not rigid):** -``` -Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes. - -Changes: -- Added `finalSummary` to task types and markdown section parsing/serialization (ordered after notes). -- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it. - -Tests: -- bun test src/test/final-summary.test.ts -- bun test src/test/cli-final-summary.test.ts -``` - -### Task Operations - -| Action | Command | -|--------------------|----------------------------------------------| -| View task | `backlog task 42 --plain` | -| List tasks | `backlog task list --plain` | -| Search tasks | `backlog search "topic" --plain` | -| Search with filter | `backlog search "api" --status "To Do" --plain` | -| Filter by status | `backlog task list -s "In Progress" --plain` | -| Filter by assignee | `backlog task list -a @sara --plain` | -| Archive task | `backlog task archive 42` | -| Demote to draft | `backlog task demote 42` | - ---- - -## Common Issues - -| Problem | Solution | -|----------------------|--------------------------------------------------------------------| -| Task not found | Check task ID with `backlog task list --plain` | -| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers | -| Changes not saving | Ensure you're using CLI, not editing files | -| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` | - ---- - -## Remember: The Golden Rule - -**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.** -**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.** - -Full help available: `backlog --help` - -<!-- BACKLOG.MD GUIDELINES END --> +- **Branching**: Use feature branches when working on tasks (e.g. `tasks/doro-123-feature-name`) +- **Committing**: Use the following format: `DORO-123: Title of the task` +- **PR titles**: Use `{taskId}: {taskTitle}` (e.g. `DORO-123: Title of the task`) +- **Github CLI**: Use `gh` whenever possible for PRs and issues