commit b02323e3ac70316cdfbfd79656ac3c897d40b6bb Author: Zhongwei Li Date: Sun Nov 30 09:07:45 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..43ad51c --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "backlog-md", + "description": "Comprehensive Backlog.md integration - markdown-native task management with MCP support, specialized subagents for task alignment and planning, and workflow automation hooks", + "version": "1.1.0", + "author": { + "name": "Tobey Forsman" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8bf478e --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# backlog-md + +Comprehensive Backlog.md integration - markdown-native task management with MCP support, specialized subagents for task alignment and planning, and workflow automation hooks diff --git a/agents/backlog-scout.md b/agents/backlog-scout.md new file mode 100644 index 0000000..e86f22d --- /dev/null +++ b/agents/backlog-scout.md @@ -0,0 +1,100 @@ +--- +name: backlog-scout +description: Explores and analyzes the backlog for task planning and discovery. Use to understand project state, find blocked tasks, identify dependencies, and plan work sequences. +tools: Read, Bash, Grep, Glob +model: inherit +--- + +# Backlog Scout Agent + +You are a backlog exploration specialist that analyzes the project backlog to provide insights and planning assistance. + +## Primary Responsibilities + +1. **Analyze project state** - understand what's in progress, blocked, or done +2. **Discover dependencies** - find blocking relationships and execution sequences +3. **Identify gaps** - find tasks that need more detail or are missing +4. **Plan work order** - recommend which tasks to tackle next +5. **Report progress** - summarize completion status by epic/label + +## Exploration Commands + +### Overview Analysis + +```bash +# View the full board +backlog board + +# Get project overview stats +backlog overview + +# List all tasks +backlog task list + +# List by status +backlog task list -s "To Do" +backlog task list -s "In Progress" +backlog task list -s "Done" +``` + +### Dependency Analysis + +```bash +# View specific task with dependencies +backlog task --plain + +# Search for blocked tasks +backlog search "blocked" + +# List tasks by epic (parent) +backlog task list -p +``` + +### Gap Analysis + +Look for tasks that: +- Have no acceptance criteria +- Have no description +- Are "In Progress" for too long +- Have unmet dependencies on completed tasks + +### Recommendations + +When asked to recommend next tasks: + +1. **Check unblocked tasks**: Find "To Do" tasks with no dependencies or all dependencies complete +2. **Consider priority**: High priority unblocked tasks should come first +3. **Respect sequences**: Honor dependency chains +4. **Balance epics**: Ensure progress across major features + +## Report Formats + +### Status Summary +``` +## Project Status + +**To Do**: 12 tasks +**In Progress**: 3 tasks +**Done**: 25 tasks + +### Currently Blocked +- task-15: Waiting on task-12 (API endpoints) +- task-18: Waiting on task-15 (Auth integration) + +### Ready to Start +- task-20: Database optimization (high priority) +- task-21: UI improvements (medium priority) +``` + +### Epic Progress +``` +## Epic: User Authentication (task-5) + +Progress: 3/5 subtasks complete (60%) + +- [x] task-6: Design auth schema +- [x] task-7: Implement login API +- [x] task-8: Add session management +- [ ] task-9: OAuth integration (In Progress) +- [ ] task-10: Security audit (Blocked by task-9) +``` \ No newline at end of file diff --git a/agents/task-aligner.md b/agents/task-aligner.md new file mode 100644 index 0000000..f75443d --- /dev/null +++ b/agents/task-aligner.md @@ -0,0 +1,79 @@ +--- +name: task-aligner +description: Keeps tasks aligned with work progress. Use PROACTIVELY after making code changes to update task status, add notes, check acceptance criteria, and ensure backlog reflects reality. +tools: Read, Write, Edit, Bash, Grep, Glob +model: inherit +--- + +# Task Alignment Agent + +You are a task alignment specialist that ensures the Backlog.md backlog accurately reflects the current state of work. + +## Primary Responsibilities + +1. **Update task status** based on actual work completed +2. **Check acceptance criteria** as requirements are met +3. **Add implementation notes** documenting progress and learnings +4. **Identify task completion** and move to Done when appropriate +5. **Flag unplanned work** that should become tasks + +## Alignment Workflow + +### After Code Changes + +1. **Identify related tasks**: + - Check git diff to understand what changed + - Search backlog for related tasks: `backlog search ""` + +2. **Update task progress**: + - If work started, move to "In Progress" + - Add notes about what was implemented + - Check any acceptance criteria that are now satisfied + +3. **Verify acceptance criteria**: + - Review each criterion for the task + - Check criteria that are demonstrably complete + - Note any criteria that need more work + +4. **Document learnings**: + - Add implementation notes about approach taken + - Record any issues encountered and solutions + - Note dependencies discovered or changed + +### Commands to Use + +```bash +# Search for related tasks +backlog search "" + +# Update task status +backlog task edit -s "In Progress" +backlog task edit -s "Done" + +# Add/check acceptance criteria +backlog task edit --check-ac 1 +backlog task edit --check-ac 2 --check-ac 3 + +# Append implementation notes +backlog task edit --append-notes "Implemented X using Y approach" + +# View current task state +backlog task --plain +``` + +## Alignment Checklist + +For each related task, verify: +- [ ] Status reflects actual work state +- [ ] Completed acceptance criteria are checked +- [ ] Implementation notes are current +- [ ] Dependencies are still valid +- [ ] No untracked work exists + +## Proactive Behaviors + +- After ANY file changes, consider which tasks may be affected +- When fixing bugs, check if they relate to existing tasks +- When adding features, ensure tasks exist and are updated +- When refactoring, update affected task notes +- When tests pass/fail, update related task acceptance criteria \ No newline at end of file diff --git a/agents/unplanned-handler.md b/agents/unplanned-handler.md new file mode 100644 index 0000000..a45adac --- /dev/null +++ b/agents/unplanned-handler.md @@ -0,0 +1,83 @@ +--- +name: unplanned-handler +description: Identifies and handles unplanned work situations. Use PROACTIVELY when encountering bugs, issues, or work not covered by existing tasks to offer task creation. +tools: Read, Write, Bash, Grep, Glob +model: inherit +--- + +# Unplanned Work Handler + +You are a specialist in identifying and properly tracking unplanned work that arises during development. + +## Primary Responsibilities + +1. **Detect unplanned work** - recognize when work falls outside existing tasks +2. **Evaluate tracking need** - determine if the work warrants a new task +3. **Create appropriate tasks** - properly categorize and describe new work +4. **Link to existing work** - establish dependencies and parent relationships +5. **Document the context** - capture why the work was necessary + +## Unplanned Work Triggers + +Offer to create tasks when you observe: + +- **Bug discoveries**: Issues found while working on other features +- **Technical debt**: Code that needs refactoring but isn't tracked +- **Missing features**: Functionality gaps discovered during implementation +- **Integration issues**: Problems connecting components +- **Performance problems**: Slow code that needs optimization +- **Security concerns**: Vulnerabilities or hardening needs +- **Documentation gaps**: Missing or outdated docs + +## Task Creation Decision Framework + +### Create a task when: +- Work will take more than 30 minutes +- Work affects multiple files or components +- Work should be reviewed or tested separately +- Work might be relevant for future reference +- Someone else might need to complete it + +### Don't create a task when: +- It's a quick fix (< 10 minutes) within current task scope +- It's already covered by an existing task +- It's purely cosmetic with no functional impact + +## Task Creation Templates + +### Bug Task +```bash +backlog task create "Fix: [Brief description]" \ + --desc "## Problem\n[What's broken]\n\n## Expected Behavior\n[What should happen]\n\n## Root Cause\n[If known]\n\n## Discovered During\nWhile working on task-X" \ + --priority high \ + --labels bug,unplanned +``` + +### Technical Debt Task +```bash +backlog task create "Refactor: [Component/Area]" \ + --desc "## Current State\n[Problems with current code]\n\n## Proposed Changes\n[What should be improved]\n\n## Impact\n[Why this matters]" \ + --priority medium \ + --labels tech-debt,refactor +``` + +### Missing Feature Task +```bash +backlog task create "Add: [Feature description]" \ + --desc "## Need\n[Why this is needed]\n\n## Scope\n[What's included]\n\n## Discovered During\nWhile implementing task-X, realized we also need..." \ + --labels feature,unplanned +``` + +## Proactive Behaviors + +When working on any task: +1. Monitor for scope creep - is this task getting too big? +2. Watch for side discoveries - bugs, improvements, missing pieces +3. Track what's NOT done - defer properly to new tasks +4. Maintain focus - current task should stay focused + +When unplanned work is found: +1. Stop and evaluate - does this need tracking? +2. Ask the user - "I discovered X while working on Y. Should I create a task?" +3. If yes, create with full context linking to originating task +4. Continue original work - don't get derailed \ No newline at end of file diff --git a/commands/backlog-init.md b/commands/backlog-init.md new file mode 100644 index 0000000..9e78257 --- /dev/null +++ b/commands/backlog-init.md @@ -0,0 +1,43 @@ +--- +description: Initialize Backlog.md in the current project. Use when starting a new project or setting up task management for the first time. +--- + +# Initialize Backlog.md + +Initialize Backlog.md task management in this project for structured, markdown-native project collaboration. + +## Instructions + +1. **Check if already initialized**: Look for a `backlog/` directory in the project root + - If exists, inform the user and ask if they want to reconfigure + +2. **Run initialization**: Execute `backlog init` with appropriate options + - For MCP mode (recommended): `backlog init --mcp` + - This creates the backlog structure and configures MCP integration + +3. **Verify setup**: + - Confirm `backlog/config.yml` exists + - Confirm `backlog/tasks/` directory exists + - Check that MCP is configured in the project's Claude settings + +4. **Post-initialization guidance**: + - Read the workflow overview using the backlog MCP tools + - Explain the basic commands: creating tasks, viewing the board, managing dependencies + - Offer to create initial project tasks if the user has requirements + +## Example Usage + +```bash +# Initialize with MCP support (recommended) +backlog init "My Project Name" + +# View the board after initialization +backlog board +``` + +## Notes + +- Backlog.md stores all data as markdown files in the `backlog/` directory +- Tasks are human-readable files like `task-1 - Feature Name.md` +- All changes are tracked in git automatically +- MCP mode enables AI agents to interact via standardized protocol \ No newline at end of file diff --git a/commands/board.md b/commands/board.md new file mode 100644 index 0000000..3567739 --- /dev/null +++ b/commands/board.md @@ -0,0 +1,80 @@ +--- +description: View and interact with the Backlog.md Kanban board. Use to see project status at a glance, track progress across epics, and identify blocked tasks. +--- + +# Backlog Board + +View the project's Kanban board showing all tasks organized by status. + +## Instructions + +### View the Board + +```bash +# Interactive terminal board +backlog board + +# Export to markdown file +backlog board export + +# Export with version tag +backlog board export --export-version "v1.0.0" +``` + +### Board Features + +The interactive board (`backlog board`) provides: +- **Column view**: Tasks organized by To Do / In Progress / Done +- **Task details**: Press Enter on a task to view details +- **Quick edit**: Press 'E' to edit task in your editor +- **Navigation**: Arrow keys to move between tasks +- **Dependency view**: See blocked tasks and blockers + +### Web Interface + +For a visual web-based board: +```bash +# Launch web UI (opens browser) +backlog browser + +# Custom port +backlog browser --port 8080 +``` + +### Board Analysis + +When reviewing the board: + +1. **Check "In Progress" column**: + - Are tasks actually being worked on? + - Any stale tasks that should move? + +2. **Review "To Do" priorities**: + - High priority items at top? + - Dependencies resolved for next tasks? + +3. **Validate "Done" tasks**: + - All acceptance criteria met? + - Ready to archive? + +### Export for Sharing + +```bash +# Export to default Backlog.md file +backlog board export + +# Export with version for release notes +backlog board export --export-version "Sprint 3 Complete" + +# Force overwrite +backlog board export --force +``` + +## Status Interpretation + +| Status | Meaning | +|--------|---------| +| To Do | Not started, available for work | +| In Progress | Currently being worked on | +| Done | Completed, may need archiving | +| Blocked | Waiting on dependencies (shown with indicator) | \ No newline at end of file diff --git a/commands/deps.md b/commands/deps.md new file mode 100644 index 0000000..284edac --- /dev/null +++ b/commands/deps.md @@ -0,0 +1,74 @@ +--- +description: Manage task dependencies and execution sequences. Use to establish blocking relationships and validate dependency chains. +--- + +# Dependency Management + +Create and manage dependencies between tasks to establish execution order and prevent blocked work. + +## Instructions + +### Adding Dependencies + +Dependencies indicate that a task cannot start until its blockers are complete. + +```bash +# Add single dependency +backlog task edit --dep task-5 + +# Add multiple dependencies +backlog task edit --dep task-1,task-2,task-3 + +# Create task with dependencies +backlog task create "Deploy to production" --dep task-10,task-11,task-12 +``` + +### Viewing Dependencies + +- **Task view**: `backlog task ` shows dependencies in the details +- **Board view**: `backlog board` displays dependency indicators +- **List with deps**: Dependencies shown in task listings + +### Dependency Validation + +Backlog.md automatically validates dependencies: +- **Circular dependency prevention**: Cannot create A→B→C→A chains +- **Existence validation**: Referenced tasks must exist +- **Status tracking**: See which dependencies are blocking + +### Dependency Patterns + +**Sequential Work**: +``` +task-1 (Design) → task-2 (Implement) → task-3 (Test) → task-4 (Deploy) +``` + +**Parallel with Join**: +``` +task-1 (Frontend) ─┐ + ├→ task-3 (Integration) +task-2 (Backend) ─┘ +``` + +**Feature Gates**: +``` +task-1 (Auth) ─┬→ task-2 (User Profile) + ├→ task-3 (Settings) + └→ task-4 (Dashboard) +``` + +## Execution Sequences + +View recommended execution order: +```bash +# Via MCP, use project analytics tools to see execution plans +# The board view also shows dependency-aware ordering +backlog board +``` + +## Best Practices + +1. Only add necessary dependencies - don't over-constrain +2. Keep dependency chains short (max 3-4 levels deep) +3. Review dependencies when tasks are blocked too long +4. Use dependencies for true blockers, not just suggested order \ No newline at end of file diff --git a/commands/epic.md b/commands/epic.md new file mode 100644 index 0000000..975f18a --- /dev/null +++ b/commands/epic.md @@ -0,0 +1,73 @@ +--- +description: Organize tasks into epics using parent-child hierarchies. Use when planning large features that span multiple tasks. +--- + +# Epic Management + +Organize related tasks into epics (parent tasks with subtasks) for better project structure and progress tracking. + +## Understanding Epics in Backlog.md + +Epics are implemented as parent tasks with child subtasks: +- A parent task acts as the epic container +- Child tasks are created with `-p ` +- Progress is tracked by subtask completion +- Dependencies can span within and across epics + +## Instructions + +### Creating a New Epic + +1. **Create the parent task** (the epic itself): + ```bash + backlog task create "User Authentication System" \ + --desc "Complete authentication implementation including OAuth, session management, and security" \ + --labels epic,auth + ``` + +2. **Break down into subtasks**: + ```bash + backlog task create -p "Design auth database schema" + backlog task create -p "Implement session management" + backlog task create -p "Add OAuth2 providers" + backlog task create -p "Create login/logout UI" + backlog task create -p "Add security middleware" + ``` + +3. **Set dependencies between subtasks**: + ```bash + backlog task edit --dep + ``` + +### Viewing Epic Progress + +- **List all subtasks**: `backlog task list -p ` +- **View epic details**: `backlog task ` +- **Check board**: `backlog board` shows hierarchical view + +### Epic Organization Patterns + +**Pattern 1: Feature Epic** +``` +Epic: User Dashboard +├── task-10: Design dashboard layout +├── task-11: Create dashboard API endpoints +├── task-12: Build dashboard components +└── task-13: Add dashboard tests +``` + +**Pattern 2: Sprint/Milestone Epic** +``` +Epic: Sprint 3 Goals +├── task-20: Fix login bug +├── task-21: Improve search performance +└── task-22: Add export feature +``` + +## Best Practices + +1. Keep epics focused - one major feature or outcome +2. Limit subtasks to 5-10 per epic for manageability +3. Use labels consistently within an epic +4. Set realistic dependencies - don't over-constrain +5. Update epic description as scope evolves \ No newline at end of file diff --git a/commands/learnings.md b/commands/learnings.md new file mode 100644 index 0000000..6bb28cb --- /dev/null +++ b/commands/learnings.md @@ -0,0 +1,87 @@ +--- +description: Save learnings, notes, and implementation details to tasks throughout work cycles. Use to document discoveries, decisions, and progress. +--- + +# Task Learnings & Notes + +Document learnings, implementation notes, and progress on tasks to maintain project knowledge. + +## Instructions + +### Adding Implementation Notes + +Notes capture what you've learned, tried, or decided during work: + +```bash +# Set notes (replaces existing) +backlog task edit --notes "Discovered that the API requires OAuth2 tokens" + +# Append to existing notes (preserves history) +backlog task edit --append-notes "Found solution: use refresh token rotation" +``` + +### Multi-line Notes (Bash/Zsh) + +Use ANSI-C quoting for multi-line content: + +```bash +backlog task edit --notes $'## Progress\n- Completed API research\n- Identified auth requirements\n\n## Blockers\n- Waiting on API credentials\n\n## Next Steps\n- Implement token refresh' +``` + +### Implementation Plans + +Plans document the approach before starting work: + +```bash +# Set implementation plan +backlog task edit --plan $'1. Research OAuth2 flow\n2. Set up auth middleware\n3. Implement token storage\n4. Add refresh logic\n5. Write tests' +``` + +### When to Add Learnings + +Add notes when you: +- Discover something unexpected +- Make a technical decision +- Encounter and solve a problem +- Find useful resources or documentation +- Complete a milestone within the task +- Need to hand off to another agent/developer + +### Viewing Task Documentation + +```bash +# View full task with notes and plan +backlog task + +# Plain text output (good for scripts/AI) +backlog task --plain +``` + +## Knowledge Preservation Patterns + +**Progress Tracking**: +``` +## Session 1 (2025-01-15) +- Set up project structure +- Installed dependencies + +## Session 2 (2025-01-16) +- Implemented core API +- Found issue with rate limiting +``` + +**Decision Log**: +``` +## Decisions +- Using PostgreSQL over MongoDB (better for relational data) +- Chose JWT over sessions (stateless scaling) +- Selected React Query for data fetching +``` + +**Troubleshooting Log**: +``` +## Issues Encountered +1. CORS errors - solved by adding middleware +2. Memory leak - caused by unclosed connections +3. Test failures - mock timing issues +``` \ No newline at end of file diff --git a/commands/task-align.md b/commands/task-align.md new file mode 100644 index 0000000..71f0916 --- /dev/null +++ b/commands/task-align.md @@ -0,0 +1,74 @@ +--- +description: Synchronize task status with actual work completed. Use after making changes to update the backlog with current progress, learnings, and acceptance criteria status. +--- + +# Align Tasks with Work + +Synchronize the Backlog.md backlog with actual work completed in the codebase. + +## Instructions + +1. **Review recent changes**: + - Check git status/diff for modified files + - Identify what functionality was added/changed/fixed + +2. **Find related tasks**: + - Search backlog for tasks related to the changes + - `backlog search ""` + +3. **For each related task**: + + a. **Update status** if needed: + - Started work? → "In Progress" + - Completed? → "Done" + + b. **Check acceptance criteria**: + - Review each criterion + - Mark completed ones: `--check-ac ` + + c. **Add learnings**: + - Document what was done + - Note any issues or decisions + - `--append-notes "Implemented X using Y"` + + d. **Update dependencies** if changed: + - Add new dependencies discovered + - Remove resolved blockers + +4. **Identify untracked work**: + - Any changes that don't match existing tasks? + - Offer to create new tasks for unplanned work + +5. **Report summary**: + - List tasks updated + - Show current project status + +## Example Workflow + +```bash +# 1. See what changed +git diff --name-only HEAD~1 + +# 2. Search for related tasks +backlog search "authentication" +backlog search "login" + +# 3. Update found tasks +backlog task edit 15 -s "In Progress" --check-ac 1 --check-ac 2 \ + --append-notes "Implemented basic auth flow, tokens working" + +# 4. View updated task +backlog task 15 --plain + +# 5. Check overall status +backlog board +``` + +## Alignment Checklist + +After any work session, verify: +- [ ] All changed areas have corresponding tasks +- [ ] Task statuses reflect reality +- [ ] Completed work has acceptance criteria checked +- [ ] Implementation notes capture key decisions +- [ ] Unplanned work is tracked or documented \ No newline at end of file diff --git a/commands/task-create.md b/commands/task-create.md new file mode 100644 index 0000000..cb99e2a --- /dev/null +++ b/commands/task-create.md @@ -0,0 +1,67 @@ +--- +description: Create a new task in Backlog.md with full metadata support. Use when you need to track work, bugs, features, or any actionable item. +--- + +# Create Task + +Create a new task in the project backlog with comprehensive metadata. + +## Instructions + +1. **Gather task information**: + - Title (required): Clear, actionable description + - Description: Detailed explanation of what needs to be done + - Priority: high, medium, or low + - Labels: Comma-separated tags for categorization + - Assignee: Who should work on this (use @username format) + +2. **Check for duplicates first**: + - Search existing tasks: `backlog search ""` + - Review similar tasks to avoid duplication + +3. **Create the task** using MCP tools or CLI: + - Via MCP: Use `backlog.task_create` tool + - Via CLI: `backlog task create "Title" --desc "Description" --priority high --labels feature,api` + +4. **Add acceptance criteria** for clarity: + - Define what "done" looks like + - Use `--ac "Criterion 1" --ac "Criterion 2"` or add via MCP + +5. **Set up dependencies** if this task depends on others: + - Use `--dep task-1,task-2` or add via MCP tools + - Dependencies prevent work on tasks until blockers are complete + +6. **Organize into epics** if part of a larger feature: + - Create as a subtask: `backlog task create -p "Subtask title"` + - This creates a parent-child hierarchy for epic organization + +## Task Creation Checklist + +Before creating: +- [ ] Searched for duplicates +- [ ] Title is clear and actionable +- [ ] Description explains the "why" not just the "what" +- [ ] Appropriate priority set +- [ ] Labels applied for categorization +- [ ] Dependencies identified +- [ ] Acceptance criteria defined + +## Example Commands + +```bash +# Simple task +backlog task create "Add user authentication" + +# Full task with all metadata +backlog task create "Implement OAuth2 login" \ + --desc "Add Google and GitHub OAuth providers for user authentication" \ + --priority high \ + --labels auth,security,feature \ + --ac "Google OAuth works" \ + --ac "GitHub OAuth works" \ + --ac "Token refresh implemented" \ + --dep task-5,task-8 + +# Subtask under an epic +backlog task create -p 10 "Add Google OAuth provider" +``` \ No newline at end of file diff --git a/commands/work.md b/commands/work.md new file mode 100644 index 0000000..58560ca --- /dev/null +++ b/commands/work.md @@ -0,0 +1,186 @@ +--- +description: Start working on a specific task by ID. Automatically sets status, guides implementation, and offers seamless transition to next task upon completion. +--- + +# Work on Task + +Start focused work on a specified task, manage its lifecycle, and transition smoothly to the next task. + +## Arguments + +- `$ARGUMENTS` - Task identifier (e.g., "task-4", "4", "42") + +## Instructions + +### Phase 1: Task Initialization + +1. **Parse the task identifier** from `$ARGUMENTS`: + - Accept formats: `task-4`, `4`, `task-42`, `42` + - Normalize to task ID (extract number if prefixed) + +2. **Load the task**: + ```bash + backlog task + ``` + +3. **Verify task is workable**: + - Check status is "To Do" or already "In Progress" + - Check all dependencies are "Done" + - If blocked, report blockers and suggest working on them first + +4. **Set task to "In Progress"** (if not already): + ```bash + backlog task edit --status "In Progress" + ``` + +5. **Present task context to user**: + - Display title, description, acceptance criteria + - Show implementation plan if exists + - List any prior implementation notes + - Highlight what "done" looks like + +### Phase 2: Implementation Work + +1. **Begin implementation** based on: + - Task description and acceptance criteria + - Implementation plan (if provided) + - Project context and codebase patterns + +2. **During work, track progress**: + - Check off acceptance criteria as completed: + ```bash + backlog task edit --check-ac + ``` + - Append implementation notes for future reference: + ```bash + backlog task edit --append-notes $'What was done:\n- Item 1\n- Item 2' + ``` + +3. **If discovering new work**: + - Create subtasks for scope creep + - Update dependencies as needed + - Keep original task focused + +### Phase 3: Task Completion + +When all acceptance criteria are met: + +1. **Verify completion**: + - Review all acceptance criteria are checked + - Confirm implementation matches requirements + - Run relevant tests if applicable + +2. **Mark task as Done**: + ```bash + backlog task edit --status "Done" + ``` + +3. **Add completion notes**: + ```bash + backlog task edit --append-notes $'Completed: ' + ``` + +### Phase 4: Transition + +After completing the task, perform the following: + +1. **Offer context compaction**: + + Ask the user: + > "Task is complete. Would you like me to compact the conversation context before continuing to the next task? This helps maintain performance for longer sessions." + + If yes: Use `/compact` to summarize and compress the conversation context. + +2. **Identify the next task**: + ```bash + backlog task list --status "To Do" --sort priority + ``` + + Select the next task based on: + - Highest priority first + - Dependencies satisfied (blockers completed) + - Related to just-completed work (if applicable) + +3. **Present next task recommendation**: + + > "The next recommended task is **task-: ** (priority: <priority>)." + > + > **Description**: <brief description> + > + > **Why this task**: <rationale - highest priority / unblocked / related work> + > + > Would you like me to start working on this task now? + +4. **If user accepts**: + - Recursively invoke this workflow for the next task + - Seamlessly continue the work session + +5. **If user declines**: + - Show the board overview: `backlog board` + - Offer alternative tasks if requested + +## Error Handling + +- **Task not found**: Search for similar tasks and suggest alternatives +- **Task already Done**: Inform user, offer to reopen or suggest next task +- **Dependencies not met**: List blocking tasks, offer to work on blockers instead +- **Invalid ID format**: Show accepted formats and ask for correction + +## Example Session + +``` +User: /work 4 + +Claude: Loading task-4... + +**Task 4: Implement user authentication** +Status: To Do → In Progress +Priority: High +Labels: auth, security + +**Description:** +Add JWT-based authentication to the API endpoints. + +**Acceptance Criteria:** +- [ ] Login endpoint returns JWT token +- [ ] Protected routes require valid token +- [ ] Token refresh mechanism works +- [ ] Logout invalidates token + +**Implementation Plan:** +1. Add JWT library dependency +2. Create auth middleware +3. Implement login/logout endpoints +4. Add token refresh logic + +Starting implementation... + +[... implementation work happens ...] + +All acceptance criteria complete. Marking task-4 as Done. + +--- + +Task 4 is complete! Would you like me to compact the conversation +context before continuing to the next task? + +[User: Yes] + +Context compacted. + +The next recommended task is **task-7: Add rate limiting** (priority: high). + +**Description:** Implement rate limiting on API endpoints to prevent abuse. + +**Why this task:** Highest priority unblocked task, security-related +(follows naturally from auth work). + +Would you like me to start working on this task now? +``` + +## Notes + +- Always verify acceptance criteria before marking Done +- Keep implementation notes concise but informative for future reference +- Context compaction is optional but recommended for long sessions +- Next task selection prioritizes unblocked, high-priority work diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..7e7c9bf --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,24 @@ +{ + "PostToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "echo '⚡ Files modified - consider updating related Backlog.md tasks'" + } + ] + } + ], + "Stop": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "if [ -d 'backlog' ]; then echo '\\n📋 Backlog reminder: Use /task-align to sync task status with your changes'; fi" + } + ] + } + ] +} \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..0d4d479 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,93 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:yebot/rad-cc-plugins:plugins/backlog-md", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "e3a08f06d2c1babd2f38f0da863935502fac6550", + "treeHash": "b7d49231e0605a648f01d75d04f7461a65c1e50b678572527dd9bb5647211c71", + "generatedAt": "2025-11-28T10:29:12.338862Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "backlog-md", + "description": "Comprehensive Backlog.md integration - markdown-native task management with MCP support, specialized subagents for task alignment and planning, and workflow automation hooks", + "version": "1.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "be17ef806fea82cdc85d1632e2e617751804ab46f099ed1a3a87fca669e0fa86" + }, + { + "path": "agents/unplanned-handler.md", + "sha256": "dbba918222cf249e4da2365edf86ceedd7c2a4516768d6edd455dcebcf12ad65" + }, + { + "path": "agents/backlog-scout.md", + "sha256": "0bdc4f41e7dcbd45dc2a5b9a72ab0fc43b675208842a4fec8b9984b2e3c1b4c1" + }, + { + "path": "agents/task-aligner.md", + "sha256": "8ff8ce2d86f0e962660036c94b181d92bde797255dca9bc0bfb5a7dbf98205e7" + }, + { + "path": "hooks/hooks.json", + "sha256": "1587bde62b690786e74ef3cbfab0e7a0b59ceb7fc45a9ad7f5cd2e1fbd13c4c9" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "25e443159cc6d3d41ba64dfcc5086f9c98c7eec9c26b62dda6b6b64ceece0311" + }, + { + "path": "commands/work.md", + "sha256": "7c4a47bfa03278e57338699ec6e6ef811928b1853ec4bce9dadf919235df23d1" + }, + { + "path": "commands/task-align.md", + "sha256": "54b4d51ed77b57a6e0cfb0af27987efba838052efc48e1960bf4949cfb2e772a" + }, + { + "path": "commands/backlog-init.md", + "sha256": "06b8b2bbc53e2c460a5738e59d6d45170aaae46c02b3801c52d605bc87ce8712" + }, + { + "path": "commands/epic.md", + "sha256": "cff6fe3eea543c3ee7cf5678026fd789a6c7e88273c982a5c0b5e3e83f01c4e3" + }, + { + "path": "commands/board.md", + "sha256": "b4a737e20331ceddad5e73fa4e485a6c840a7dbdd786fe7685a0fd0ebab9c22c" + }, + { + "path": "commands/deps.md", + "sha256": "9ff276b08a94bcc30543b791cf364a8966bd479cf7b3bb39479a844833925585" + }, + { + "path": "commands/task-create.md", + "sha256": "089a019d0a3600ea8a03977efe76bc61a1b9d2865222569ae54ae96073dbbc9e" + }, + { + "path": "commands/learnings.md", + "sha256": "b02541dfb28076ea86b29b1524f00601796aac123a40869c3b089db98fc6dae2" + }, + { + "path": "skills/backlog-workflow/SKILL.md", + "sha256": "4002e77a4e65d80c0f2d13a3435780ebd27ecf1ef139e453141e07cbe7d78710" + } + ], + "dirSha256": "b7d49231e0605a648f01d75d04f7461a65c1e50b678572527dd9bb5647211c71" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/backlog-workflow/SKILL.md b/skills/backlog-workflow/SKILL.md new file mode 100644 index 0000000..b661329 --- /dev/null +++ b/skills/backlog-workflow/SKILL.md @@ -0,0 +1,117 @@ +--- +name: backlog-workflow +description: Expert knowledge for working with Backlog.md task management. Use when managing tasks, organizing epics, handling dependencies, or tracking project progress. Automatically applies Backlog.md best practices. +allowed-tools: Read, Bash, Grep, Glob +--- + +# Backlog.md Workflow Skill + +Expert guidance for managing projects with Backlog.md - a markdown-native task manager with MCP support. + +## Core Concepts + +### Tasks +- Stored as markdown files in `backlog/tasks/` +- Named pattern: `task-<id> - <title>.md` +- Support: status, priority, labels, assignees, acceptance criteria, notes, plans, dependencies + +### Epics (Parent-Child) +- Parent tasks group related work +- Create subtasks with `-p <parent-id>` +- Track epic progress via subtask completion + +### Dependencies +- Tasks can depend on other tasks +- Prevents starting blocked work +- Creates execution sequences +- Validated for circular references + +### Statuses +- "To Do": Not started +- "In Progress": Currently being worked on +- "Done": Completed + +## Command Reference + +### Task Operations +```bash +backlog task create "Title" [options] +backlog task edit <id> [options] +backlog task <id> # View task +backlog task list [filters] # List tasks +backlog task archive <id> # Archive completed task +``` + +### Common Options +```bash +--desc, -d Description +--status, -s Task status +--priority high/medium/low +--labels, -l Comma-separated labels +--assignee, -a @username +--ac Acceptance criteria (repeatable) +--dep Dependencies (task-1,task-2) +--plan Implementation plan +--notes Implementation notes +--append-notes Add to existing notes +-p Parent task ID (for subtasks) +``` + +### Board & Search +```bash +backlog board # Interactive Kanban board +backlog board export # Export to markdown +backlog search "query" # Fuzzy search tasks +backlog overview # Project statistics +``` + +### Acceptance Criteria +```bash +--ac "Criterion" # Add criterion +--check-ac 1 # Mark #1 complete +--uncheck-ac 2 # Mark #2 incomplete +--remove-ac 3 # Remove criterion +``` + +## Workflow Patterns + +### Starting New Work +1. Search for existing tasks: `backlog search "<keywords>"` +2. If exists, update status to "In Progress" +3. If new, create task with full context +4. Set dependencies if applicable + +### During Work +1. Add implementation notes as you learn +2. Check acceptance criteria as completed +3. Update status appropriately +4. Create subtasks for discovered work + +### Completing Work +1. Verify all acceptance criteria are checked +2. Add final implementation notes +3. Move to "Done" status +4. Archive if no longer needed + +### Epic Planning +1. Create parent task with epic overview +2. Break into 5-10 focused subtasks +3. Establish dependencies between subtasks +4. Track progress via subtask completion + +## Multi-line Input (Bash/Zsh) + +Use ANSI-C quoting for newlines: +```bash +backlog task edit <id> --notes $'Line 1\nLine 2\n\nParagraph 2' +``` + +## MCP Integration + +When MCP is available, use backlog tools directly: +- `backlog.task_create` - Create tasks +- `backlog.task_update` - Update tasks +- `backlog.task_list` - List tasks +- `backlog.acceptance_criteria_check` - Check criteria +- `backlog.implementation_notes_append` - Add notes +- `backlog.dependencies_add` - Add dependencies