setup

setup

Install Backlog.md in the current repository without clobbering existing agent directives.

When This Skill Runs

Trigger phrases:

• "set up backlog.md", "install backlog.md", "adopt Backlog.md"
• "set up task management for this repo"
• "register the backlog MCP server"
• "introduce a backlog/ directory"

Prerequisites

• The user's working directory is a git repository (git rev-parse --show-toplevel succeeds).
• mise (https://mise.jdx.dev) is the chosen tool manager. If the project uses a different one (asdf, plain npm), adapt the install step accordingly.
• An MCP-aware client (Claude Code, Cursor, Codex) is the consumer.

Allowed Tools

Bash, Read, Write, Edit, Grep, Glob.

Input

Parameter	Source	Required
--dry-run	Skill argument	No (default: apply changes)

Why this skill exists

backlog init's interactive wizard auto-generates AGENTS.md, CLAUDE.md, and .cursorrules. In a repository that already has hand-curated agent directives, that overwrite is destructive. This skill runs backlog init with non-interactive flags that disable the auto-generation, then injects a ## Task Management section into the existing AGENTS.md instead.

It also handles a real-world snag: corporate npm proxies do not always mirror backlog.md, so the first install may need the public registry as a one-shot override.

Execution Steps

Step 1 — Detect current state

Read all four signals before changing anything. Each one may already be in place from a prior run; never duplicate.

ROOT=$(git rev-parse --show-toplevel)
test -f "$ROOT/.mise.toml" && grep -q '"npm:backlog.md"' "$ROOT/.mise.toml" && echo "mise: PRESENT" || echo "mise: MISSING"
test -f "$ROOT/.mcp.json"   && grep -q '"backlog"' "$ROOT/.mcp.json"        && echo "mcp:  PRESENT" || echo "mcp:  MISSING"
test -d "$ROOT/backlog/tasks"                                              && echo "dir:  PRESENT" || echo "dir:  MISSING"
test -f "$ROOT/AGENTS.md"   && grep -q '## Task Management' "$ROOT/AGENTS.md" && echo "doc:  PRESENT" || echo "doc:  MISSING"

Report the signal map to the user before continuing. If --dry-run, stop here.

Step 2 — Register the mise tool entry

Add the line to .mise.toml [tools]. Create the file if it does not exist.

[tools]
"npm:backlog.md" = "latest"

If [tools] is already present, append "npm:backlog.md" = "latest" under it. Preserve other entries.

Step 3 — Install (with public registry fallback)

Try the standard install first. If it fails with a "404 Not Found" or registry error (typical of corporate npm proxies that do not mirror backlog.md), retry with the public registry override.

mise install || npm_config_registry=https://registry.npmjs.org/ mise install
mise x -- backlog --version    # expect 1.44.0 or higher

Surface both outcomes to the user. If the second attempt also fails, stop and ask before guessing further.

Step 4 — Run backlog init with safe flags

The flags below disable the interactive wizard and the AGENTS.md/CLAUDE.md/.cursorrules auto-generation. Memorize this exact incantation — anyone re-running backlog init later (e.g. after upgrading) must reuse it.

mise x -- backlog init "$(basename "$ROOT")" \
  --integration-mode mcp \
  --defaults \
  --auto-open-browser false \
  --check-branches false \
  --include-remote false

This creates backlog/{tasks,drafts,archive,completed,decisions,docs,milestones} and backlog/config.yml.

Step 5 — Register the MCP server

Edit .mcp.json (create if missing). Add the backlog server while preserving any existing entries (e.g. playwright):

{
  "mcpServers": {
    "backlog": {
      "command": "mise",
      "args": ["x", "--", "backlog", "mcp", "start"]
    }
  }
}

Use Edit (not Write) so existing servers survive.

Step 6 — .gitignore

Add this single line to .gitignore (idempotent — skip if already present):

/backlog/.user-config.json

The rest of backlog/ is intentionally committed — that is the core value proposition of Backlog.md.

Step 7 — Inject AGENTS.md "Task Management" section

Read ${CLAUDE_PLUGIN_ROOT}/assets/agents-md-section.md and insert it into the project's AGENTS.md. If AGENTS.md does not exist, create it with a minimal header plus this section. If ## Task Management already exists, leave it alone and tell the user — manual diff review is safer than auto-merging directive content.

Mention to the user that CLAUDE.md typically just @AGENTS.md includes, so a single edit covers both.

Step 8 — (Optional) Install conventions memory

If the project has any of these directories, ask before writing:

• .ai/memories/ (some teams use this for cross-session agent memory)
• .claude/memories/
• docs/agents/

If yes, copy ${CLAUDE_PLUGIN_ROOT}/assets/conventions.md to <dir>/task_management.md. If no such directory, skip — the conventions skill in this plugin already surfaces the same content on demand.

Step 9 — Verify

mise x -- backlog task list           # should show the empty board
mise x -- backlog --version            # confirm CLI works
python3 -c "import json; json.load(open('.mcp.json'))"   # JSON validity

Report:

• Files changed
• New directory tree under backlog/
• One-line reminder that the user must restart their MCP client (Claude Code / Cursor) for the new server to register.

Error Handling

• Already installed: Report the signal map and stop. Do not overwrite.
• No git repo: Stop and ask the user to git init first.
• backlog init fails with "AGENTS.md already exists": Confirm the safe flags from Step 4 are passed; if the failure persists, stop and surface the error.
• mise install fails on both attempts: Surface the full error. Likely cause: offline, no mise installed, or both registries blocked. Do not attempt npm install directly without consent — the project may use a different tool manager.

Constraints

• Never overwrite an existing AGENTS.md or CLAUDE.md. Inject a section into it instead.
• Never add auto_commit: true to backlog/config.yml. Commits remain a human/agent decision.
• Never commit backlog/.user-config.json — it is per-user.