# 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