Initial commit

commands/backlog-complete.md

@@ -0,0 +1,160 @@
+# Complete Backlog.md Task
+
+Verify all Definition of Done items before marking a task as complete.
+
+## Instructions
+
+1. **View the task**:
+   ```bash
+   backlog task {id} --plain
+   ```
+   - Show complete task details to verify current state
+
+2. **Verify Definition of Done checklist**:
+
+   ### Via CLI (Required)
+
+   a) **All Acceptance Criteria Checked**:
+      - Look at the task output
+      - Verify ALL ACs show `- [x]` (checked)
+      - If any show `- [ ]` (unchecked):
+        - ❌ STOP - Task cannot be marked complete
+        - Ask user: "AC #{n} is not complete. Should we check it off or is there more work?"
+        - If complete: `backlog task edit {id} --check-ac {n}`
+        - If incomplete: Do not proceed
+
+   b) **Implementation Notes Present**:
+      - Check if "Implementation Notes" section has content
+      - Should be PR-ready description: what was done, how, why
+      - If missing or insufficient:
+        - ❌ STOP - Task cannot be marked complete
+        - Ask user to provide implementation notes
+        - Add with: `backlog task edit {id} --notes "..."`
+
+   c) **Status Ready for "Done"**:
+      - Current status should be "In Progress" or similar
+      - Will change to "Done" after verification
+
+   ### Via Code/Testing (Confirm with User)
+
+   d) **Tests Pass**:
+      - Ask: "Have all tests passed?"
+      - If no: Do not mark complete until tests pass
+
+   e) **Linting/Type Checking Passes**:
+      - Ask: "Does linting and type checking pass?"
+      - If no: Fix issues first
+
+   f) **Documentation Updated** (if applicable):
+      - Ask: "Is documentation updated if needed?"
+
+   g) **Code Reviewed**:
+      - Ask: "Have you self-reviewed the changes?"
+
+   h) **No Regressions**:
+      - Ask: "Any regressions or known issues?"
+      - If yes: Create follow-up tasks
+
+3. **If ALL checks pass, mark as complete**:
+   ```bash
+   backlog task edit {id} -s Done
+   ```
+
+4. **Verify completion**:
+   ```bash
+   backlog task {id} --plain
+   ```
+   - Confirm status is "Done"
+   - Confirm all ACs are checked
+   - Confirm implementation notes are present
+
+5. **Celebrate and remind**:
+   - "✅ Task {id} marked as Done!"
+   - "Summary of completed work:"
+   - Show the implementation notes
+   - Suggest next task if applicable
+
+## Definition of Done Checklist
+
+**DO NOT mark task as Done unless ALL of these are complete:**
+
+### CLI Verifiable
+- [ ] All acceptance criteria checked (`--check-ac`)
+- [ ] Implementation notes added (`--notes`)
+- [ ] Status can be changed to "Done"
+
+### User Confirmed
+- [ ] Tests pass
+- [ ] Linting/type checking passes
+- [ ] Documentation updated (if needed)
+- [ ] Code self-reviewed
+- [ ] No known regressions
+
+## Common Issues
+
+### Issue: User wants to mark done but ACs aren't all checked
+
+**Response**:
+```
+❌ Cannot mark task as Done yet.
+
+Current AC status:
+- [x] AC #1: {text}
+- [ ] AC #2: {text} ❌ NOT COMPLETE
+- [x] AC #3: {text}
+
+Either:
+1. Complete AC #2 and check it off:
+   backlog task edit {id} --check-ac 2
+
+2. Or explain why AC #2 is no longer needed and remove it:
+   backlog task edit {id} --remove-ac 2
+```
+
+### Issue: User wants to mark done but no implementation notes
+
+**Response**:
+```
+❌ Cannot mark task as Done yet.
+
+Implementation notes are missing. Please add a summary of what was implemented (like a PR description):
+
+backlog task edit {id} --notes $'Summary of changes:\n- What was implemented\n- Why this approach\n- Testing done\n- Follow-up tasks'
+```
+
+### Issue: Tests failing but user wants to mark done
+
+**Response**:
+```
+❌ Cannot mark task as Done with failing tests.
+
+Please:
+1. Fix failing tests, OR
+2. Create a follow-up task for test fixes
+
+A task is only "Done" when it's truly complete and shippable.
+```
+
+## Workflow Discipline
+
+This command enforces workflow discipline:
+
+- **No shortcuts**: All DoD items must be complete
+- **Quality gate**: Prevents incomplete work from being marked done
+- **Documentation**: Ensures knowledge is captured in implementation notes
+- **Testing**: Confirms work is validated before completion
+
+## Important Reminders
+
+- **NEVER** mark a task as Done without verifying ALL DoD items
+- **ALWAYS** use `backlog task edit {id} -s Done` (never edit files directly)
+- **VERIFY** the change with `backlog task {id} --plain`
+- **EDUCATE** users on why DoD matters (quality, completeness, documentation)
+
+## Definition of Done for This Command
+
+- [ ] Task DoD checklist verified (all items checked)
+- [ ] Task status changed to "Done" via CLI
+- [ ] Change verified with `backlog task {id} --plain`
+- [ ] User sees confirmation of completion
+- [ ] Implementation notes displayed to user

commands/backlog-create.md

@@ -0,0 +1,129 @@
+# Create New Backlog.md Task
+
+Guide the user through creating a well-structured Backlog.md task with proper metadata.
+
+## Instructions
+
+1. **Gather task information**:
+
+   a) **Title** (required):
+      - Ask: "What's the task title?" (one-liner summary)
+      - Format: Clear, action-oriented
+      - Example: "Add user authentication" or "Fix payment processing bug"
+
+   b) **Description** (required):
+      - Ask: "What's the description?" (the "why")
+      - Should explain: Purpose, goal, and context
+      - NOT implementation details
+
+   c) **Acceptance Criteria** (required):
+      - Ask: "What are the acceptance criteria?" (the "what")
+      - Guide user to write outcome-focused, testable criteria
+      - Good: "User can log in with valid credentials"
+      - Bad: "Add login() function to auth.ts"
+      - Collect multiple ACs (at least 2-3 recommended)
+
+   d) **Optional metadata**:
+      - Labels: `backend`, `frontend`, `api`, `bug`, `feature`, etc.
+      - Priority: `low`, `medium`, `high`
+      - Assignee: `@username`
+      - Status: Default is "To Do" (don't change unless user specifies)
+
+2. **Create the task**:
+   ```bash
+   backlog task create "Title" \
+     -d "Description" \
+     --ac "First acceptance criterion" \
+     --ac "Second acceptance criterion" \
+     --ac "Third acceptance criterion" \
+     -l label1,label2 \
+     --priority medium
+   ```
+
+3. **Verify creation**:
+   ```bash
+   # List most recent task
+   backlog task list --plain | tail -5
+   ```
+
+   - Confirm the task was created
+   - Note the task ID assigned
+
+4. **Validate file naming**:
+   ```bash
+   # Check the most recent task file
+   ls -t backlog/tasks/ | head -1
+   ```
+
+   - **CRITICAL**: Verify it matches pattern `task-{id} - {title}.md`
+   - If naming is incorrect:
+     - ⚠️ ALERT: "File naming violation detected!"
+     - Show the incorrect filename
+     - Explain the correct pattern
+     - This shouldn't happen with CLI, but verify anyway
+
+5. **View the created task**:
+   ```bash
+   backlog task {id} --plain
+   ```
+   - Show the complete task to the user
+   - Confirm all details are correct
+
+6. **Remind about workflow**:
+   - "Task created successfully!"
+   - "When you're ready to work on it, use `/backlog-start` or:"
+   - `backlog task edit {id} -s "In Progress" -a @myself`
+   - "Remember: Add implementation plan only when you start work, not now"
+
+## Important Guidelines
+
+### What to Include During Creation
+- ✅ Title (one-liner)
+- ✅ Description (the "why")
+- ✅ Acceptance Criteria (the "what")
+- ✅ Labels, priority, assignee (optional)
+
+### What NOT to Include During Creation
+- ❌ Implementation plan (comes later when work starts)
+- ❌ Implementation notes (comes at end when work completes)
+- ❌ Status other than "To Do" (unless specifically requested)
+
+### Acceptance Criteria Best Practices
+
+Guide users to write good ACs:
+
+**Good ACs** (outcome-focused, testable):
+- "User can successfully log in with valid credentials"
+- "System processes 1000 requests per second"
+- "API returns 404 for non-existent resources"
+
+**Bad ACs** (implementation-focused):
+- "Add a login() function to auth.ts"
+- "Use bcrypt for password hashing"
+- "Install express middleware"
+
+## Multi-line Input
+
+For descriptions with multiple paragraphs:
+```bash
+backlog task create "Title" \
+  -d $'First paragraph explaining context.\n\nSecond paragraph with more details.' \
+  --ac "AC 1" \
+  --ac "AC 2"
+```
+
+## Error Handling
+
+- If `backlog` command not found: Guide user to install Backlog.md
+- If creation fails: Show error and suggest fixes
+- If naming violation detected: Alert and explain the pattern
+- If user provides implementation details: Redirect to ACs instead
+
+## Definition of Done for This Command
+
+- [ ] All required information gathered (title, description, ACs)
+- [ ] Task created using CLI
+- [ ] Creation verified with `backlog task list`
+- [ ] File naming validated (matches `task-{id} - {title}.md`)
+- [ ] Task displayed to user for confirmation
+- [ ] User understands next steps (use `/backlog-start` when ready)

commands/backlog-init.md

@@ -0,0 +1,299 @@
+# Initialize Backlog.md in Repository
+
+Guide the user through initializing a Backlog.md presence in the current repository with proper directory structure.
+
+## Instructions
+
+1. **Determine repository name**:
+   ```bash
+   # Get the repository name from git
+   basename -s .git `git config --get remote.origin.url` 2>/dev/null || basename "$(pwd)"
+   ```
+
+   - This extracts the repo name from the git remote URL
+   - Falls back to current directory name if not a git repo
+
+2. **Ask user for backlog name**:
+
+   Use the AskUserQuestion tool to ask:
+
+   - Question: "What should the backlog be named?"
+   - Header: "Backlog Name"
+   - Options:
+     - Label: "Use repository name"
+       Description: "Use '{repo_name}' as detected from the repository"
+     - Label: "Custom name"
+       Description: "Specify a different name for the backlog"
+
+   If user selects "Custom name" or "Other", ask them to provide the custom name.
+
+3. **Ask user for connection preference (MCP vs CLI)**:
+
+   Use the AskUserQuestion tool to ask:
+
+   - Question: "How would you like Claude Code to interact with Backlog.md?"
+   - Header: "Connection"
+   - Options:
+     - Label: "MCP Server"
+       Description: "Use Model Context Protocol for direct integration (recommended for Claude Code workflows)"
+     - Label: "CLI Commands"
+       Description: "Use backlog-md-cli commands via bash (requires CLI installation)"
+
+   **Understanding the options:**
+
+   - **MCP Server**:
+     - Direct integration with Claude Code
+     - No CLI installation required
+     - Claude uses native tools to read/write task files
+     - Faster and more seamless workflow
+     - Recommended for most users
+
+   - **CLI Commands**:
+     - Uses the backlog-md-cli command-line tool
+     - Requires separate installation (`npm install -g @backlog-md/cli`)
+     - Traditional CLI workflow
+     - Good for users who want to use backlog-md-cli outside Claude Code
+
+   **Note the user's preference** for use in subsequent steps.
+
+4. **Verify backlog directory doesn't exist**:
+   ```bash
+   # Check if backlog directory already exists
+   if [ -d "backlog" ]; then
+     echo "ERROR: backlog directory already exists"
+     exit 1
+   fi
+   ```
+
+   - If directory exists, warn the user and ask if they want to:
+     - Abort initialization
+     - Reinitialize (will preserve existing tasks)
+     - Delete and start fresh (DANGEROUS - confirm twice)
+
+5. **Create directory structure**:
+   ```bash
+   # Create the backlog directory hierarchy
+   mkdir -p backlog/tasks
+   mkdir -p backlog/drafts
+   mkdir -p backlog/docs
+   mkdir -p backlog/decisions
+   ```
+
+6. **Initialize based on connection preference**:
+
+   **If user chose CLI Commands:**
+   ```bash
+   # Initialize the backlog with the chosen name
+   backlog init "{backlog_name}"
+   ```
+
+   - Replace `{backlog_name}` with the name chosen by the user
+   - This creates the necessary configuration files
+
+   **If backlog CLI is not installed:**
+   - Show installation instructions:
+     ```bash
+     # Install backlog-md-cli
+     npm install -g @backlog-md/cli
+     # or
+     brew install backlog-md-cli
+     ```
+   - Ask user to install, then retry
+
+   **If user chose MCP Server:**
+   - Create a basic `.backlog/config.json` file:
+     ```bash
+     mkdir -p .backlog
+     cat > .backlog/config.json <<EOF
+{
+  "name": "{backlog_name}",
+  "version": "1.0.0",
+  "connection": "mcp"
+}
+EOF
+     ```
+   - Inform user: "Backlog.md is configured for MCP. Claude Code will interact directly with task files."
+   - Note: MCP server configuration is handled in Claude Code settings, not here
+
+7. **Verify initialization**:
+   ```bash
+   # Verify directory structure
+   tree backlog -L 2
+
+   # Or if tree is not available
+   find backlog -type d -maxdepth 2
+   ```
+
+   - Confirm all directories were created:
+     - `backlog/tasks/`
+     - `backlog/drafts/`
+     - `backlog/docs/`
+     - `backlog/decisions/`
+
+8. **Create initial README** (optional but recommended):
+
+   **If user chose CLI Commands:**
+   ```bash
+   backlog doc create "README" -c "# {backlog_name}
+
+This project uses Backlog.md for task management.
+
+## Quick Start
+
+- Create tasks: \`backlog task create \"Task title\" -d \"Description\"\`
+- List tasks: \`backlog task list --plain\`
+- Start work: \`backlog task edit {id} -s \"In Progress\" -a @myself\`
+
+See the full documentation for more details."
+   ```
+
+   **If user chose MCP Server:**
+   ```bash
+   cat > backlog/docs/README.md <<EOF
+# {backlog_name}
+
+This project uses Backlog.md for task management with MCP integration.
+
+## Quick Start
+
+- Create tasks: Use Claude Code's \`/backlog-create\` command
+- List tasks: Claude can read from \`backlog/tasks/\` directly
+- Start work: Use \`/backlog-start\` command
+
+Claude Code interacts with task files directly through MCP.
+
+See the full documentation for more details.
+EOF
+   ```
+
+9. **Add to .gitignore** (optional):
+
+   Ask user if they want to ignore certain backlog files:
+   - Options:
+     - Ignore drafts only (`backlog/drafts/`)
+     - Ignore nothing (track everything in git)
+     - Custom gitignore rules
+
+   If user wants to ignore drafts:
+   ```bash
+   # Add to .gitignore
+   echo "" >> .gitignore
+   echo "# Backlog.md - ignore drafts" >> .gitignore
+   echo "backlog/drafts/" >> .gitignore
+   ```
+
+10. **Show initialization summary**:
+
+   Display to the user:
+
+   **If user chose CLI Commands:**
+   ```
+   ✅ Backlog.md initialized successfully!
+
+   Backlog name: {backlog_name}
+   Location: ./backlog
+   Connection: CLI Commands
+
+   Directory structure created:
+   - backlog/tasks/     (Task files)
+   - backlog/drafts/    (Draft tasks)
+   - backlog/docs/      (Documentation)
+   - backlog/decisions/ (ADRs and decisions)
+
+   Next steps:
+   1. Create your first task: `backlog task create "Title"`
+   2. View available commands: `backlog --help`
+   3. Explore the task board: `backlog board`
+   4. Use Claude Code commands: `/backlog-create`, `/backlog-start`
+   ```
+
+   **If user chose MCP Server:**
+   ```
+   ✅ Backlog.md initialized successfully!
+
+   Backlog name: {backlog_name}
+   Location: ./backlog
+   Connection: MCP Server (direct integration)
+
+   Directory structure created:
+   - backlog/tasks/     (Task files)
+   - backlog/drafts/    (Draft tasks)
+   - backlog/docs/      (Documentation)
+   - backlog/decisions/ (ADRs and decisions)
+
+   Next steps:
+   1. Create your first task: `/backlog-create`
+   2. Use `/backlog-start` to begin working on a task
+   3. Claude Code will interact with task files directly
+   4. No CLI installation needed!
+   ```
+
+11. **Remind about workflow**:
+
+   **If user chose CLI Commands:**
+   - "Use `backlog task create` or `/backlog-create` to create your first task"
+   - "Use `backlog task edit` or `/backlog-start` to begin working on a task"
+   - "Use `/backlog-validate` to check backlog health"
+   - "All operations should use the backlog CLI - never edit task files directly"
+
+   **If user chose MCP Server:**
+   - "Use `/backlog-create` to create your first task"
+   - "Use `/backlog-start` to begin working on a task"
+   - "Use `/backlog-validate` to check backlog health"
+   - "Claude Code will handle task file operations automatically"
+   - "Never edit task files directly - use Claude Code commands"
+
+## Important Guidelines
+
+### Directory Structure
+- **backlog/tasks/**: Active tasks (tracked in git)
+- **backlog/drafts/**: Draft tasks (optionally ignored in git)
+- **backlog/docs/**: Project documentation
+- **backlog/decisions/**: Architectural Decision Records (ADRs)
+
+### Naming Conventions
+- Task files: `task-{id} - {title}.md`
+- Never create these manually - always use CLI
+
+### What to Initialize
+- ✅ Create directory structure
+- ✅ Run `backlog init` command
+- ✅ Optionally create README documentation
+- ✅ Optionally configure .gitignore
+
+### What NOT to Do
+- ❌ Create task files manually
+- ❌ Skip the `backlog init` command
+- ❌ Initialize if backlog directory already exists (without confirmation)
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| backlog directory exists | Confirm with user before proceeding |
+| backlog CLI not found | Show installation instructions |
+| Not in git repository | Still allow initialization (name defaults to directory) |
+| Permission denied | Check directory permissions, suggest sudo if needed |
+| backlog init fails | Show error, verify CLI version, check for conflicts |
+
+## Multi-line Content
+
+When creating initial documentation with newlines:
+```bash
+backlog doc create "Title" -c $'# Heading\n\nParagraph one.\n\nParagraph two.'
+```
+
+## Definition of Done for This Command
+
+- [ ] Repository/backlog name determined
+- [ ] User confirmed backlog name (custom or default)
+- [ ] User selected connection preference (MCP or CLI)
+- [ ] Directory structure created (tasks, drafts, docs, decisions)
+- [ ] Initialization completed based on connection choice:
+  - [ ] CLI: `backlog init` command executed successfully
+  - [ ] MCP: `.backlog/config.json` created
+- [ ] Directory structure verified
+- [ ] Optional: README documentation created (appropriate for connection type)
+- [ ] Optional: .gitignore configured
+- [ ] Initialization summary displayed to user (showing connection type)
+- [ ] User understands next steps and available commands for their connection type

commands/backlog-start.md

@@ -0,0 +1,57 @@
+# Start Working on Backlog.md Task
+
+Help the user start work on a Backlog.md task following the proper workflow.
+
+## Instructions
+
+1. **Identify the task**:
+   - Ask the user which task they want to work on (by ID or search keyword)
+   - If searching: `backlog search "{keyword}" --plain`
+   - If by ID: Verify it exists with `backlog task {id} --plain`
+
+2. **View the task**:
+   ```bash
+   backlog task {id} --plain
+   ```
+   - Show the task details to the user
+   - Confirm this is the correct task
+
+3. **Start the task** (mark as In Progress and assign):
+   ```bash
+   backlog task edit {id} -s "In Progress" -a @myself
+   ```
+   - This is the "start task ritual" - never skip it!
+   - Verify the change: `backlog task {id} --plain`
+
+4. **Create implementation plan**:
+   - Ask the user about their approach OR
+   - Analyze the task and propose a plan
+   - Create plan with proper newlines:
+   ```bash
+   backlog task edit {id} --plan $'1. First step\n2. Second step\n3. Third step'
+   ```
+
+5. **Present plan for approval**:
+   - Show the implementation plan to the user
+   - **CRITICAL**: Wait for user approval before coding
+   - Say: "I've created the implementation plan. Please review before I proceed with coding."
+
+6. **Only after approval**:
+   - Proceed with implementation
+   - Remind user to check off ACs as they're completed
+   - Remind about adding implementation notes
+
+## Important Reminders
+
+- **NEVER** edit task files directly
+- **ALWAYS** use `backlog task edit` commands
+- **WAIT** for user approval of plan before coding
+- **VERIFY** all changes with `backlog task {id} --plain`
+
+## Definition of Done for This Command
+
+- [ ] Task status changed to "In Progress"
+- [ ] Task assigned to user
+- [ ] Implementation plan created and added to task
+- [ ] Plan presented to user for approval
+- [ ] User understands next steps

commands/backlog-validate.md

@@ -0,0 +1,164 @@
+# Validate Backlog.md Structure
+
+Audit the backlog directory for naming violations, structural issues, and metadata inconsistencies.
+
+## Instructions
+
+Launch the `backlog-validator` agent to perform comprehensive validation:
+
+```
+Use the backlog-validator agent to:
+1. Check all task files match the `task-{id} - {title}.md` pattern
+2. Verify CLI can read all task files
+3. Detect orphaned or malformed files
+4. Identify metadata inconsistencies
+5. Generate a comprehensive validation report
+6. Recommend remediation steps for any issues found
+```
+
+The validator will perform these checks:
+
+## Validation Scope
+
+### Critical Checks (Block Functionality)
+- **File Naming Pattern**: All files match `task-{id} - {title}.md`
+- **CLI Accessibility**: Can `backlog task list` see all files?
+- **Directory Structure**: Required directories exist
+- **Task ID Integrity**: No duplicate or missing IDs
+
+### Warning Checks (Impact Workflow)
+- **Task Completeness**: Missing acceptance criteria or descriptions
+- **Workflow Issues**: Stale "In Progress" tasks, Done tasks with unchecked ACs
+- **Metadata Quality**: Tasks without assignees, missing priorities
+
+### Info Checks (Project Health)
+- **Status Distribution**: How tasks are distributed across To Do/In Progress/Done
+- **Label Usage**: Which labels are most common
+- **Assignee Workload**: How work is distributed across team
+
+## Expected Output
+
+The validator will generate a report like:
+
+```markdown
+# Backlog.md Validation Report
+
+## Executive Summary
+- 📁 Total Files: 47
+- ✅ Valid Tasks: 45
+- ❌ Violations: 2
+- 🏥 Health Score: 95%
+
+## Critical Issues
+
+### Naming Violations
+❌ task-23-Fix bug.md
+   Expected: task-23 - Fix bug.md
+   Issue: Missing spaces around separator
+
+❌ Fix login issue.md
+   Expected: task-{id} - Fix login issue.md
+   Issue: Missing task ID prefix
+
+## Warnings
+
+### Incomplete Tasks
+⚠️  task-15 - Add API endpoint.md
+   Missing acceptance criteria
+
+⚠️  task-28 - Refactor components.md
+   Status "In Progress" but no recent activity (14 days)
+
+## Recommendations
+
+### Immediate Fixes
+1. Fix naming for task-23:
+   backlog task edit 23 -t "Fix bug"
+   (CLI will update filename automatically)
+
+2. Recreate orphaned task:
+   backlog task create "Fix login issue" -d "..."
+
+3. Add ACs to task-15:
+   backlog task edit 15 --ac "First criterion"
+
+## Project Health
+- To Do: 12 (26%)
+- In Progress: 8 (17%)
+- Done: 27 (57%)
+```
+
+## When to Run Validation
+
+Use this command when:
+
+1. **Troubleshooting Issues**:
+   - "Task not showing up in list"
+   - "CLI can't find task"
+   - "Board not displaying correctly"
+
+2. **After Bulk Operations**:
+   - Created multiple tasks
+   - Imported tasks from other systems
+   - Reorganized backlog structure
+
+3. **Periodic Health Checks**:
+   - Weekly validation recommended
+   - Before major milestones
+   - After team onboarding
+
+4. **Quality Assurance**:
+   - Ensuring naming compliance
+   - Checking workflow state health
+   - Validating metadata quality
+
+## What Gets Validated
+
+### File Naming Pattern
+```
+Valid:   task-42 - Add authentication.md
+Invalid: task-42-Add authentication.md
+Invalid: 42 - Add authentication.md
+Invalid: task-42.md
+```
+
+### Directory Structure
+```
+Required:
+- backlog/tasks/     (all task files)
+- backlog/docs/      (documentation)
+- backlog/decisions/ (ADRs)
+- backlog/drafts/    (draft tasks)
+```
+
+### Task Metadata
+- Frontmatter exists and is valid YAML
+- Required fields present (id, title, status)
+- Status values are valid
+- Task ID matches filename
+
+## Important Notes
+
+- **Non-destructive**: Validation never modifies files
+- **Comprehensive**: Checks multiple layers (naming, metadata, workflow)
+- **Actionable**: Provides specific CLI commands to fix issues
+- **Educational**: Explains why violations matter
+
+## After Validation
+
+If issues are found:
+
+1. **Review the report** with the user
+2. **Prioritize fixes**: Critical > Warning > Info
+3. **Offer to help** fix issues using proper CLI commands
+4. **Educate** on prevention (use hooks, use agents)
+5. **Run validation again** after fixes to confirm
+
+## Definition of Done for This Command
+
+- [ ] backlog-validator agent launched
+- [ ] Comprehensive validation performed
+- [ ] Report generated and presented to user
+- [ ] Issues categorized by severity
+- [ ] Remediation commands provided for all issues
+- [ ] User understands how to prevent future violations