bmad-issue-tracking-setup

name	bmad-issue-tracking-setup
description	One-time setup for issue tracking integration. Use after installing the module to deploy TOML overrides and shared tasks.

Issue Tracking Setup

One-time setup for BMAD Issue Tracking integration. Deploys TOML overrides to _bmad/custom/ and a shared task to _bmad/_config/custom/.

Prerequisites

• BMAD Method module (BMM) 6.4.0+ installed
• This module installed via npx bmad-method install --custom-source https://github.com/jrevillard/bmad-issue-tracking

Instructions

IMPORTANT: When a step asks you to configure a value with a default, you MUST present the default as a suggestion and wait for the user's answer before writing anything. Never silently apply a default. Check that `_bmad/bmm/config.yaml` exists and contains `# Version:` header with version 6.4.0+. ERROR: BMM 6.4.0+ required. TOML overrides need customize.toml support for all 6 workflows. Stop here The sync logic has been converted to workflow YAML files. The old markdown file `bmad-bmm-issue-sync.md` is no longer needed.

Remove the file if it exists in the consuming project:

rm -f _bmad/_config/custom/bmad-bmm-issue-sync.md

Confirm that the file no longer exists.

Locate the TOML overrides. Check these locations in order: 1. `~/.bmad/cache/custom-modules/github.com/jrevillard/bmad-issue-tracking/skills/bmad-issue-tracking-setup/assets/custom/` 2. Ask the user for the path to the cloned `bmad-issue-tracking` repo

IMPORTANT: Always overwrite existing TOML files — this is an update, not a first install. New versions may have changed TOML content.

Copy all TOML files to _bmad/custom/, overwriting existing files:

cp -f <path>/*.toml _bmad/custom/

Remove any bmad-*.toml files in _bmad/custom/ that no longer exist in the source (files may have been renamed or removed in a new version).

The following TOML files should now exist in _bmad/custom/:

• bmad-check-implementation-readiness.toml (requires BMM 6.4.0+)
• bmad-code-review.toml (requires BMM 6.4.0+)
• bmad-correct-course.toml (requires BMM 6.4.0+)
• bmad-create-architecture.toml (requires BMM 6.4.0+)
• bmad-create-epics-and-stories.toml (requires BMM 6.4.0+)
• bmad-create-prd.toml (requires BMM 6.4.0+, superseded by bmad-prd.toml on BMM 6.8.0+)
• bmad-create-story.toml (requires BMM 6.4.0+)
• bmad-create-ux-design.toml (requires BMM 6.4.0+)
• bmad-dev-story.toml (requires BMM 6.4.0+)
• bmad-edit-prd.toml (requires BMM 6.4.0+, superseded by bmad-prd.toml on BMM 6.8.0+)
• bmad-prd.toml (requires BMM 6.8.0+)
• bmad-retrospective.toml (requires BMM 6.4.0+)
• bmad-sprint-planning.toml (requires BMM 6.4.0+)
• bmad-sprint-status.toml (requires BMM 6.4.0+)

Note: All TOML files are in pointer format — they reference workflow YAML files deployed in step 3b. Verify each TOML file is valid by checking it contains a [workflow] section and at least one hook key (on_complete, activation_steps_append, etc.).

The TOML overrides reference workflow language YAML files. These are deployed separately to keep the TOML files as simple pointers.

Locate the workflow language files. They are siblings of the custom/ directory (in the same assets/ parent):

1. ~/.bmad/cache/custom-modules/github.com/jrevillard/bmad-issue-tracking/skills/bmad-issue-tracking-setup/assets/
2. Ask the user for the path to the cloned bmad-issue-tracking repo

IMPORTANT: Always overwrite existing files — new versions may have changed workflow content.

Copy the workflow language specification and workflow YAML files, overwriting existing files:

cp -f <path>/bmad-workflow-lang.md _bmad/_config/custom/
mkdir -p _bmad/_config/custom/workflows
cp -rf <path>/workflows/* _bmad/_config/custom/workflows/

Remove any workflow YAML files in _bmad/_config/custom/workflows/ that no longer exist in the source (files may have been renamed or removed in a new version).

Verify the following files exist:

• _bmad/_config/custom/bmad-workflow-lang.md
• _bmad/_config/custom/workflows/common/check-config.yaml
• _bmad/_config/custom/workflows/common/create-issue.yaml
• _bmad/_config/custom/workflows/common/create-label.yaml
• _bmad/_config/custom/workflows/common/ensure-board.yaml
• _bmad/_config/custom/workflows/common/ensure-labels.yaml
• _bmad/_config/custom/workflows/common/find-issue.yaml
• _bmad/_config/custom/workflows/common/find-prd.yaml
• _bmad/_config/custom/workflows/common/find-stories.yaml
• _bmad/_config/custom/workflows/common/set-story-status.yaml
• _bmad/_config/custom/workflows/common/update-issue-description.yaml
• _bmad/_config/custom/workflows/common/update-issue-status.yaml
• _bmad/_config/custom/workflows/check-implementation-readiness/activation.yaml
• _bmad/_config/custom/workflows/check-implementation-readiness/complete.yaml
• _bmad/_config/custom/workflows/code-review/activation.yaml
• _bmad/_config/custom/workflows/create-architecture/activation.yaml
• _bmad/_config/custom/workflows/create-architecture/complete.yaml
• _bmad/_config/custom/workflows/create-ux-design/activation.yaml
• _bmad/_config/custom/workflows/create-ux-design/complete.yaml
• _bmad/_config/custom/workflows/code-review/complete.yaml
• _bmad/_config/custom/workflows/correct-course/activation.yaml
• _bmad/_config/custom/workflows/correct-course/complete.yaml
• _bmad/_config/custom/workflows/create-epics-and-stories/activation.yaml
• _bmad/_config/custom/workflows/create-epics-and-stories/complete.yaml
• _bmad/_config/custom/workflows/bmad-prd/activation.yaml
• _bmad/_config/custom/workflows/bmad-prd/complete.yaml
• _bmad/_config/custom/workflows/create-prd/activation.yaml
• _bmad/_config/custom/workflows/create-prd/complete.yaml
• _bmad/_config/custom/workflows/create-story/activation.yaml
• _bmad/_config/custom/workflows/create-story/complete.yaml
• _bmad/_config/custom/workflows/dev-story/activation.yaml
• _bmad/_config/custom/workflows/dev-story/complete.yaml
• _bmad/_config/custom/workflows/edit-prd/activation.yaml
• _bmad/_config/custom/workflows/edit-prd/complete.yaml
• _bmad/_config/custom/workflows/retrospective/activation.yaml
• _bmad/_config/custom/workflows/retrospective/complete.yaml
• _bmad/_config/custom/workflows/sprint-planning/activation.yaml
• _bmad/_config/custom/workflows/sprint-planning/complete.yaml
• _bmad/_config/custom/workflows/sprint-status/activation.yaml
• _bmad/_config/custom/workflows/sprint-status/complete.yaml

Check if `_bmad/custom/issue-tracking.yaml` already exists. Create `_bmad/custom/issue-tracking.yaml` with the following content (this file is independent from BMM and survives BMM updates):

```yaml
issue_tracking:
  enabled: true
  platform: gitlab  # or github — configure in next step
  # worktree_base, host, project configured in steps 4-5
```

worktree_base already configured: {worktree_base}. Ask the user for their worktree base directory. Default: `_bmad/worktrees` Set `issue_tracking.worktree_base` to the user's answer in `_bmad/custom/issue-tracking.yaml`. Ensure the worktree base directory is in `.gitignore`. Read the configured `worktree_base` value and check if it is listed. If not, append it. Detect the git remote by running `git remote get-url origin`. Determine the git remote platform from the remote URL (gitlab.com → gitlab, github.com → github, GHE/GitLab self-hosted → ask user). Extract `git_host` (hostname) and `git_project` (group/project or owner/repo) from the remote URL. Always set `issue_tracking.git_platform` to the git remote platform in `_bmad/custom/issue-tracking.yaml`. Platform already configured: {platform}. Ask the user which platform they use for issue tracking: GitLab or GitHub. Set `issue_tracking.platform` to the chosen value. git_platform already configured: {git_platform}. Set `issue_tracking.git_platform` to the git remote platform in `_bmad/custom/issue-tracking.yaml`. NOTE: The issue tracker ({platform}) differs from the git remote ({git_platform}). This is valid — e.g. code on GitLab but issues on GitHub. MRs/PRs will target the git remote, so `git_host` and `git_project` are also needed. git_host already configured: {git_host}. Set `issue_tracking.git_host` to the git remote hostname (already extracted from the remote URL above). git_project already configured: {git_project}. Set `issue_tracking.git_project` to the git remote project path (already extracted from the remote URL above). NOTE: Platform and git remote match — `git_host` is no longer needed. Removing it. Remove `issue_tracking.git_host` from `_bmad/custom/issue-tracking.yaml`. NOTE: Platform and git remote match — `git_project` is no longer needed. Removing it. Remove `issue_tracking.git_project` from `_bmad/custom/issue-tracking.yaml`. host already configured: {host}. Ask the user for the issue tracker host (e.g. `gitlab.company.com` or `github.com`). Set `issue_tracking.host` in `_bmad/custom/issue-tracking.yaml`. project already configured: {project}. Ask the user for the issue tracker project path (e.g. `my-group/my-project`). Set `issue_tracking.project` in `_bmad/custom/issue-tracking.yaml`. Run the platform auth check (use `--hostname {host}` for self-hosted instances): - GitLab: `glab auth status --hostname {host}` - GitHub: `gh auth status --hostname {host}` WARN: CLI not authenticated. Issue tracking will fall back to file-system until authenticated. Explain: "Branch patterns control automatic branch and MR/PR creation when developing PRD stories. Placeholders: `{prd_key}` (e.g. `auth-refactor`), `{story_key}` (e.g. `3-4-automatic-department-routing`)."

Ask the user for their PRD branch pattern. Default: feat/{prd_key}/prd Ask the user for their story branch pattern. Default: feat/{prd_key}/{story_key}

WARN: PRD branch pattern must contain `{prd_key}` placeholder. Using default. Set PRD pattern to `feat/{prd_key}/prd` WARN: Story branch pattern must contain both `{prd_key}` and `{story_key}` placeholders. Using default. Set story pattern to `feat/{prd_key}/{story_key}`

Write branch_patterns under issue_tracking in _bmad/custom/issue-tracking.yaml:

issue_tracking:
  enabled: true
  platform: <platform>
  git_platform: <git_platform>  # git remote platform (same as platform in nominal case)
  host: <host>
  project: <project>
  worktree_base: <configured_worktree_base>
  # Only present when git remote differs from issue tracker:
  # git_host: <git_hostname>
  # git_project: <git_group>/<git_project>
  branch_patterns:
    prd: "<resolved PRD pattern>"
    story: "<resolved story pattern>"

Verify the section was written correctly by reading it back.