/dev-kit-setup

name: dev-kit-setup
description: First-use bootstrap for the dev kit. Detects the team's issue tracker, discovers what it can via MCP/CLI, asks only what cannot be discovered, and persists the result to .claude/dev-kit.json in the consuming repo. Use when that file is missing, when the user asks to set up or reconfigure the kit, or when issue-fetch cannot resolve its configuration.

Dev Kit Setup

Make the kit self-sufficient: detect the tracker, discover everything possible automatically, ask the user only for genuine choices, and persist the result so **nobody on the team has to configure anything again**.

When to run

• `.claude/dev-kit.json` does not exist (or lacks a `tracker` block) and a kit skill (e.g. `issue-fetch`) needs it.
• The user explicitly asks to set up or reconfigure the kit.
• A stored value turns out to be invalid (e.g. a field ID no longer exists) — re-discover just that value.

1. Determine the tracker

Pick `tracker.type` with the least friction:

1. If the triggering reference makes it obvious, use it (`PROJ-1234`/`ENG-42` → Jira/Linear key style; `#123` → GitHub/Azure). 2. Check which backends are actually available: is an Atlassian or Linear MCP authenticated? Is `gh` logged in for this repo? Is Azure DevOps configured? 3. If still ambiguous, **ask the user once** which tracker the team uses: Jira, Linear, GitHub Issues, or Azure DevOps.

Then run the matching discovery below. For any MCP/CLI that is not authenticated, **offer to set it up for them** (users are encouraged to just ask "connect my Jira" — do the work, don't only hand back a command):

• **Claude Code:** the tracker/design MCPs are plugin-declared (`atlassian`, `linear`, `figma`) — authorize with `claude mcp login <server>` (or tell them to run `/mcp` inside the session; the OAuth browser step is theirs to complete).
• **Codex:** install the curated connector and have them sign in from the app — `codex plugin add atlassian-rovo@openai-curated` (Jira/Confluence) · `linear@openai-curated` · `figma@openai-curated`.
• **GitHub / Azure:** `gh auth login` / `az login` (no MCP).

Run the command for them when you can; the OAuth/browser sign-in is always the user's step. Then stop — never continue with invented values until the backend is actually reachable.

2. Discover per tracker

Jira

• **Auth mode**: default is the **Atlassian MCP**. **If the Atlassian MCP is unavailable or blocked** (not installed, not authorized, or disabled by an enterprise policy), set `authMode: "rest"` and persist it — so the kit stops retrying the blocked MCP and uses REST from then on. In REST mode the kit calls the Jira REST API with credentials from the **environment**: `JIRA_EMAIL` + `JIRA_API_TOKEN` (Cloud, Basic auth) or `JIRA_PAT` (Server/DC, Bearer), plus `JIRA_BASE_URL`. Tell the user to put the credentials in `.env` and add `.env` to `.gitignore` — they never go in `.claude/dev-kit.json`.
• **Site**: list accessible sites via the Atlassian MCP — one → use it; several → ask which. (In `rest` mode, use `JIRA_BASE_URL` / the site the user gives.)
• **Project key**: derive from the triggering ticket prefix and verify it exists; otherwise list projects and ask.
• **Custom fields (auto-detect, no questions)**: resolve field IDs by matching names case-insensitively — Acceptance Criteria ("Acceptance Criteria"/"AC"), Sprint ("Sprint"), Story Points ("Story Points"/"Story point estimate"). If a name matches nothing, inspect a recent issue's custom fields; if still ambiguous, ask once showing the candidates. (In `rest` mode, resolve field IDs via `GET <base>/rest/api/3/field`.)

Linear

• **Team**: list teams via the Linear MCP — one → use it; several → ask which. Store its `teamKey`.
• No custom-field discovery needed; acceptance criteria come from the issue body.

GitHub Issues

• **Repo**: default to the current repo's `origin` (`gh repo view --json nameWithOwner`); confirm if the kit will track issues in a different repo.
• Nothing else to configure.

Azure DevOps

• **Org and project**: read from the configured Azure DevOps connection or ask once. Store `org` and `project`.

3. Detect the stack(s)

Identify the tech stack from the project's files so the kit can load the right baseline commands. Match against the profiles in `instructions/stacks/` (each profile lists its detection signals), e.g.:

| Signal | Stack id | |---|---| | `package.json` | `node` | | `angular.json` | `angular` | | `react` / `react-dom` in `package.json` | `react` | | `vue` in `package.json` | `vue` | | `pyproject.toml` / `requirements*.txt` | `python` | | `*.csproj` / `*.sln` | `dotnet` | | `pom.xml` / `build.gradle` | `java` | | `go.mod` | `go` | | `Gemfile` | `ruby` | | `composer.json` | `php` | | `Cargo.toml` | `rust` |

A JS/TS frontend matches **both** `node` and its framework — prefer the **more specific** one (`angular`/`react`/`vue`); those profiles reference `node` for the shared toolchain. A monorepo may match several — record all of them (e.g. `["dotnet", "angular"]`). If nothing matches a shipped profile, record the closest label anyway and tell the user there is no stack profile yet (the kit still works from the repo's `CLAUDE.md` and generic rules — and contributing `instructions/stacks/<id>.md` is one small PR).

4. Persist

Write `.claude/dev-kit.json` at the consuming repo root. Only the active tracker's block is required:

{
  "tracker": {
    "type": "jira",
    "site": "https://<org>.atlassian.net",
    "cloudId": "<discovered-cloud-id>",
    "authMode": "mcp",
    "projectKey": "PROJ",
    "fields": {
      "acceptanceCriteria": "customfield_XXXXX",
      "sprint": "customfield_XXXXX",
      "storyPoints": "customfield_XXXXX"
    },
    "reviewState": null
  },
  "stacks": ["node"],
  "prHost": "github",
  "gates": {
    "coverage": { "mode": "auto", "min": 95 },
    "e2e": { "mode": "auto" }
  },
  "test": {
    "coverageCommands": []
  }
}

Shape of `tracker` per type: **jira*