gh-yebot-rad-cc-plugins-plugins-backlog-md-cli/commands/backlog-init.md

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:

   # 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:

   # 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:

   # 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:

   # 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:

     # 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:

     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:

   # 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:

   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:

   # 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:

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