Initial commit

2025-11-30 09:07:45 +08:00
commit b02323e3ac
16 changed files with 1203 additions and 0 deletions
--- a/commands/backlog-init.md
+++ 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
--- a/commands/board.md
+++ 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) |
--- a/commands/deps.md
+++ 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 <task-id> --dep task-5
+
+# Add multiple dependencies
+backlog task edit <task-id> --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 <id>` 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
--- a/commands/epic.md
+++ 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 <parent-id>`
+- 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 <epic-id> "Design auth database schema"
+   backlog task create -p <epic-id> "Implement session management"
+   backlog task create -p <epic-id> "Add OAuth2 providers"
+   backlog task create -p <epic-id> "Create login/logout UI"
+   backlog task create -p <epic-id> "Add security middleware"
+   ```
+
+3. **Set dependencies between subtasks**:
+   ```bash
+   backlog task edit <subtask-id> --dep <blocking-task-id>
+   ```
+
+### Viewing Epic Progress
+
+- **List all subtasks**: `backlog task list -p <epic-id>`
+- **View epic details**: `backlog task <epic-id>`
+- **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
--- a/commands/learnings.md
+++ 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 <task-id> --notes "Discovered that the API requires OAuth2 tokens"
+
+# Append to existing notes (preserves history)
+backlog task edit <task-id> --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 <task-id> --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 <task-id> --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 <task-id>
+
+# Plain text output (good for scripts/AI)
+backlog task <task-id> --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
+```
--- a/commands/task-align.md
+++ 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 "<keywords from changes>"`
+
+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 <number>`
+
+   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
--- a/commands/task-create.md
+++ 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 "<keywords>"`
+   - 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 <parent-id> "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"
+```
--- a/commands/work.md
+++ 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 <id>
+   ```
+
+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 <id> --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 <id> --check-ac <criterion-number>
+     ```
+   - Append implementation notes for future reference:
+     ```bash
+     backlog task edit <id> --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 <id> --status "Done"
+   ```
+
+3. **Add completion notes**:
+   ```bash
+   backlog task edit <id> --append-notes $'Completed: <summary of what was done>'
+   ```
+
+### Phase 4: Transition
+
+After completing the task, perform the following:
+
+1. **Offer context compaction**:
+
+   Ask the user:
+   > "Task <id> 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-<next-id>: <title>** (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