---
name: eck:switch-tracker
version: "0.7.4"
description: "Switch the project's tracker type (JIRA, GitHub Issues, Linear, Local) and update all dependent configuration."
disable-model-invocation: false
---

# Switch Tracker

Change the project's issue tracker type and update all dependent configuration, primitives, and skills.

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

---

## Task Registration

| Stage | Subject             | Active Form       | Statusline     |
| ----- | ------------------- | ----------------- | -------------- |
| 1     | Stage 1: Pre-Flight | Checking project  | PreFlght (1/7) |
| 2     | Stage 2: Interview  | Gathering config  | Intrvw (2/7)   |
| 3     | Stage 3: Plan       | Computing changes | Plan (3/7)     |
| 4     | Stage 4: Backup     | Backing up files  | Backup (4/7)   |
| 5     | Stage 5: Apply      | Applying changes  | Apply (5/7)    |
| 6     | Stage 6: Validate   | Validating config | Validate (6/7) |
| 7     | Stage 7: Finalize   | Updating registry | Finalize (7/7) |

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

## Usage

```
/eck:switch-tracker
/eck:switch-tracker --to jira
/eck:switch-tracker --to local
/eck:switch-tracker --dry-run
```

| Flag          | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| `--to <type>` | Target tracker type (skip interview). Values: `jira`, `github-issues`, `linear`, `local` |
| `--dry-run`   | Show planned changes without applying them                                               |

---

## Stage 1: Pre-Flight

### Inputs

- `.claude/project-constants.md` — current project configuration
- `$ECK_HOME/` — global template source

### Activities

1. Verify this is an ECK-managed project (`.claude/project-constants.md` exists)
   - If missing → STOP: "Not an ECK project. Run `/eck:new-project` first."
2. Read current `<TRACKER_TYPE>` from `project-constants.md`
3. Verify global templates exist at `$ECK_HOME/`
   - If missing → STOP: "ECK global install not found. Run `npx @evolvconsulting/evolv-coder-kit --global`."

### Outputs

- Current tracker type identified
- Global template source verified

### Exit Criteria

- Project is confirmed ECK-managed
- Current tracker type is known

---

## Stage 2: Interview

### Inputs

- Current `<TRACKER_TYPE>`
- `--to` flag value (if provided)

### Activities

1. If `--to` flag provided, use that value. Otherwise ask:
   - "Current tracker: <TRACKER_TYPE>. Which tracker type do you want to switch to?"
   - Options: JIRA, GitHub Issues, Linear, Local markdown
   - Exclude current type from options
2. If switching TO JIRA: ask for `<BOARD_ID>`, `<ASSIGNEE_ID>`, `<ASSIGNEE_NAME>`, `<TRACKER_URL>`, `<JIRA_DONE_TRANSITION_ID>`
3. If switching TO GitHub Issues: ask for `<GITHUB_OWNER>`, `<GITHUB_REPO>`, `<GITHUB_USERNAME>` (optional)
4. If switching TO Linear: ask for `<LINEAR_TEAM_ID>`, `<LINEAR_ASSIGNEE_ID>` (optional), `<LINEAR_CYCLE_ID>` (optional)
5. If switching FROM GitHub Issues: ask whether to keep `gh-cli/` primitives (used for PRs/releases regardless of tracker)

### Outputs

- Target tracker type selected
- All required configuration values collected

### Exit Criteria

- Target type is different from current type
- All required constants for target type are provided

---

## Stage 3: Plan

### Inputs

- Current and target tracker types
- Configuration values from Stage 2

### Activities

1. Compute change set:
   - **project-constants.md**: fields to update/add/remove
   - **Primitives**: tracker backend directories to deploy/remove
   - **Skills**: tracker-specific skills to deploy/remove (e.g., `jira/SKILL.md`)
   - **project-catalog.yaml**: entries to add/remove
   - **MCP guidance**: `.mcp.json` server additions/removals needed
2. Display change set as a diff summary
3. If `--dry-run`: display plan and exit
4. Ask for approval via AskUserQuestion

### Outputs

- Complete change set computed and displayed

### Exit Criteria

- User has approved the change set (or skill exits on `--dry-run`)

---

## Stage 4: Backup

### Inputs

- List of files to modify from Stage 3

### Activities

1. Create backup directory: `.claude-backup-switch-tracker-{YYYY-MM-DD}/`
2. Copy all affected files to backup directory
3. Display backup location

### Outputs

- Backup directory with copies of all affected files

### Exit Criteria

- All affected files are backed up
- Backup directory path is recorded

---

## Stage 5: Apply

### Inputs

- Change set from Stage 3
- Configuration values from Stage 2
- Global templates from `$ECK_HOME/`

### Activities

1. Update `project-constants.md`:
   - Set `<TRACKER_TYPE>` to new value
   - Add/update tracker-specific constants
   - Remove old tracker-specific constants (unless shared)
2. Deploy new tracker primitives from `$ECK_HOME/.claude/primitives/tracker/{backend}/`
3. Remove old tracker primitives (unless `gh-cli/` retained per Stage 2)
4. Deploy/remove tracker-specific skills (e.g., `jira/SKILL.md`, `confluence/SKILL.md`)
5. Update `project-catalog.yaml` entries for added/removed components
6. Display `.mcp.json` guidance:
   - If switching TO MCP-based tracker: "Add a `{type}` server to `.mcp.json` in your project root. Minimal stanza:"

     ```json
     {
       "mcpServers": {
         "{type}": {
           "type": "http",
           "url": "http://localhost:PORT/mcp",
           "headers": { "Authorization": "Bearer ${MCP_API_KEY}" }
         }
       }
     }
     ```

     JIRA, Confluence, and Linear are also available as official plugins — run `/eck:plugin-status` to check.

   - If switching FROM MCP-based tracker: "You may remove the `{type}` server from `.mcp.json`"

### Outputs

- All configuration files updated
- Primitives and skills deployed/removed
- MCP guidance displayed

### Exit Criteria

- `project-constants.md` reflects new tracker type
- Correct primitives and skills are deployed

---

## Stage 6: Validate

### Inputs

- New tracker type from Stage 2
- Updated project configuration

### Activities

1. If new tracker requires MCP: run `core/ops:mcp-preflight` with `blocking: false`
   - If available: `[x] {tracker} MCP: connected`
   - If unavailable: `[!] {tracker} MCP: not responding — tracker features will be blocked until configured.`
   - This is a warning, NOT a rollback trigger
2. **MUST** run `/eck:update-permissions --auto-apply` to regenerate permissions for new MCP servers. Do NOT skip permission regeneration after a tracker switch

### Outputs

- MCP connectivity status displayed
- Permissions updated

### Exit Criteria

- Validation checks completed (warnings acceptable)
- Permissions regenerated

---

## Stage 7: Finalize

### Inputs

- All changes from Stages 5-6
- `$ECK_HOME/registry.yaml`

### Activities

1. **MUST** update `registry.yaml` for this project. Do NOT skip registry update after a successful switch:
   - Set `tracker_type` to new value
   - Append to `sync_history`:
     ```yaml
     - date: "<DATE>"
       action: "switch-tracker"
       performed_by: "/eck:switch-tracker"
       summary: "Changed tracker from {old} to {new}"
     ```
   - Recompute `project_summary`
   - Atomic write per `ops:registry-update`
2. Display completion summary via the Bash tool:

   ```bash
   source $ECK_HOME/colors.sh

   echo ""
   printf '%b\n' "${ORANGE}${BOLD}Tracker Switched${RESET}"
   echo ""
   printf '%b\n' "${GREEN}[x]${RESET} Tracker switched: {old} → {new}"
   printf '%b\n' "${GREEN}[x]${RESET} {N} files updated"
   printf '%b\n' "${GREEN}[x]${RESET} Backup at: .claude-backup-switch-tracker-{date}/"
   echo ""
   printf '%b\n' "${DIM}To rollback: restore files from the backup directory.${RESET}"
   echo ""
   ```

3. Reset statusline

### Outputs

- Registry updated with new tracker type
- Completion summary displayed

### Exit Criteria

- Registry reflects new tracker type
- Summary displayed with rollback instructions

---

## Error Handling

Follow the error handling protocol defined in the `output:error-handler` primitive.

- **Not an ECK project**: STOP with guidance to run `/eck:new-project`
- **Same tracker type selected**: STOP: "Already using {type}. No changes needed."
- **Backup failure**: STOP: "Could not create backup. Resolve permissions and retry."
- **Apply failure mid-way**: Display which changes succeeded, point to backup for rollback
- **On error**: Reset the statusline before exiting.
  ```bash
  bash $ECK_HOME/update-stage.sh
  ```

---

## Related Documents

- [/eck:new-project](../new-project/SKILL.md) — Initial project setup with tracker selection
- [/eck:switch-docs](../switch-docs/SKILL.md) — Switch documentation platform
- [tracker:router](../../project/primitives/tracker/_router.md) — Tracker dispatch
- [core/ops:mcp-preflight](../../project/primitives/core/ops/mcp-preflight.md) — MCP validation
