克劳德开发工具包

Requirements

• Claude Code — CLI, desktop app, or IDE extension
• macOS / Linux
• Python 3.11+
• Git
• GitHub CLI (gh) — authenticated

Migrate — Upgrade dependencies or runtime

/migrate [target, e.g. "Django 5.0" or "Python 3.12"]

Scans the codebase for impact, generates a step-by-step migration plan with rollback instructions, and applies changes incrementally with test verification.

1. Build a product from scratch

``` /prd → /kickoff → /uiux → /sprint

Installation

claude-dev-kit ships as a Claude Code plugin marketplace (.claude-plugin/marketplace.json).

1. Install the plugin

Inside a Claude Code session:

```bash

Add the marketplace (the repo itself), then install the plugin

/plugin marketplace add pillip/claude-dev-kit /plugin install claude-dev-kit@claude-dev-kit

Or from a shell (same effect, scriptable):

Namespacing: plugin skills are namespaced by plugin name — e.g. /claude-dev-kit:implement, /claude-dev-kit:review. This is mandatory for plugins (it prevents cross-plugin collisions).

Script resolution: kit helper scripts (checkpoints, worktree wrappers) resolve through ${CLAUDE_PLUGIN_ROOT}, which Claude Code substitutes into skill text at load time — no files are copied into your project, and the absolute prefix keeps working from inside worktrees.

2. Install user tools (optional)

Installs the status line script to ~/.claude/kit/bin/. Run once per machine (needs a clone of this repo):

bash scripts/install_user.sh

Migrating from the retired submodule installer? The symlink-based project installer was removed after the plugin path reached parity (ISSUE-027). Remove the old symlinks from your project's .claude/agents/, .claude/skills/, and .claude/hooks/, drop the .claude-kit submodule if you no longer need it, and install the plugin as above. Skill names gain the /claude-dev-kit: prefix.

Implement — Build an issue

/implement ISSUE-001

1. Reads issue spec from issues.md
2. Creates GH Issue if missing
3. Creates branch → implements → tests → commits → pushes
4. Creates PR with Closes #<issue_number> in body
5. Updates issues.md metadata

Ship — Deploy

/ship

Verifies tests pass, updates documentation, merges the PR, and reports test coverage gaps in shipped code with suggestions to run /testgen.

Uninstalling

claude plugin uninstall claude-dev-kit
claude plugin marketplace remove claude-dev-kit

Or in-session via /plugin. Plugin files live in Claude Code's cache (~/.claude/plugins/), so uninstalling leaves nothing behind in your project — any .claude-kit/ runtime state in a project can be deleted freely.

Core Use Cases

Team-scale usage

The kit assumes the repo IS the team boundary. Two adoption patterns cover the common shapes — and there is deliberately no separate "team layer."

Usage

(optional pre-PRD: /brainstorm → /bizanalysis → /prd)

``` Start with an idea, validate it, write a PRD, generate planning docs, design the UI, and let the team-lead auto-implement everything.

(optional pre-PRD: /brainstorm → /bizanalysis → /prd)

**Existing codebase (no PRD):**

**Single issue:**

**Add a feature to existing product:**

Optional pre-PRD: /brainstorm (Socratic exploration) and /bizanalysis (market + SWOT) are stand-alone primitives, not part of the default flow. If your idea is clear, start from /prd. These exist for the case where you genuinely don't know what to build yet. /uiux, /mobile-uiux, and /desktop-uiux are optional for UI projects. Backend/CLI projects go directly from /kickoff to /sprint. /sprint auto-orchestrates multiple issues. For a single issue, use /implement directly. /scan is for existing codebases without a PRD. It reverse-engineers planning docs from code.

Behaviour-control environment variables

A few environment variables tune gate behaviour without editing code. All are optional — the defaults are safe for local and CI runs:

- KIT_CHECKPOINT_TEST_TIMEOUT — seconds allowed for test-phase checkpoints (/implement RED/test, /ship smoke) and the verify_gates.py unit gate. Default 600; invalid or non-positive values fall back to the default. - KIT_SPRINT_QUEUE_GH_TIMEOUT — default 10; seconds for the sprint queue's gh pr view merge-state probe (scripts/sprint_queue.py). On timeout the probe degrades to a phase-only decision so an offline or hung gh never blocks the frequently-run queue. - KIT_SPRINT_DISPATCH_ABOVE_WATERMARK — set to 1 (also true/yes/on) to let the sprint queue autonomously dispatch Board issues above the roster boundary pinned in docs/sprint_state.md's ## Meta as Roster-Watermark (scripts/sprint_queue.py). Unset (the default) or any other value — 0 and false included — keeps out-of-scope work flagged but never targeted: above-boundary issues appear in unrostered (and in stranded when the run reports DONE) but never in the dispatched targets. Either way the boundary in force is named in reason as a [roster-watermark: …] note, and whenever the gate actually withheld or released work a [dispatch: …] note names this knob — so a deliberately widened sprint is distinguishable from a runaway one. Note the boundary is only enforced when the Roster-Watermark field is present (a malformed field still counts as present and still closes the gate) — a sprint_state with no such field keeps the pre-ISSUE-069 behaviour of dispatching above the re-derived max(rostered IDs). That fail-open belongs to the dispatch gate alone, and it is not a steady state inside a /sprint run: step 4f's scripts/sprint_queue.py validate refuses a sprint_state that declares Status: running while its boundary is absent or malformed — valid: false, a roster_boundary object naming the cause, and the distinct exit class 3, which /sprint treats as a hard stop even though exit 3 does print JSON. Restoring an accepted Roster-Watermark line in ## Meta is what clears it — this knob does not. - KIT_WORKTREE_FETCH_TIMEOUT — default 60; wall-clock seconds allowed for each remote consultation scripts/worktree.sh create makes when the branch exists only on the remote (git ls-remote, then a single-branch git fetch). Invalid or non-positive values fall back to the default. Only that one path consults the remote — a local ref or a genuinely new branch stays offline. Exceeding the bound is reported as its own reason=remote-fetch-timeout refusal, distinct from reason=remote-unreachable, because an offline remote stalls rather than failing fast. Requires timeout (or gtimeout); where neither exists the consultation runs unbounded and says so on stderr. - KIT_ALLOW_BROWSER_INSTALL — set to 1 to let the visual-diff and computed-styles gates auto-install Playwright + Chromium (heavy network + subprocess provisioning) when the browser is missing. Unset (the default) or any other value keeps the gate side-effect-free: it skips with a "browser unavailable" note instead of mutating the environment. - KIT_GATE_RESULTS_FILE — path to a runtime test-execution results JSON (the SPEC-058 delegation handoff artifact, validated as untrusted input by scripts/synthesize_gate_results.py; must live under the gitignored .claude/run/ directory). Unset (the default, until the runtime capability ships): gate runs take the verify_gates.py path unchanged. Setting it alone never delegates: ingest additionally requires the per-run provenance binding — a <artifact>.sig sidecar holding the HMAC of the artifact bytes under an in-process key (never exposed via env), artifact freshness (written after the checkpoint process started), and one-shot consumption (ingest renames the artifact to <artifact>.consumed, so byte-identical replays refuse). Any binding failure degrades to running the real gates, with one loud stdout line and telemetry reason binding-rejected. When the binding verifies, the checkpoint prints a GATES DELEGATED marker — delegated runs are never silent. - KIT_RUN_ID — run id for the kit's best-effort telemetry appends to .claude/runs/<run-id>.jsonl (see docs/telemetry_schema.md). Nothing in the kit sets it; supply it yourself when you want a run's events grouped under one file. Unset (the default): the shared emitter (scripts/kit_telemetry.py) still writes the event — under the unattributed fallback run id, with a run_id_fallback field in the event body — and prints nothing, because a line on 100% of runs is noise rather than signal (ISSUE-071). Set to a value outside [A-Za-z0-9_-]{1,64}: the same fallback plus one [kit-telemetry] stdout line naming this knob, because that one is a misconfiguration you can fix. Read the events back — both this stream and the ISSUE-001 hook trace, on the default path — with python3 scripts/trace_query.py summary, whose unattributed events count is the aggregate the per-emit line used to report. .claude/runs/ is run-scoped scratch: add it to your project's .gitignore so event files are never committed. - CLAUDE_PROJECT_DIR — set by the Claude Code runtime, never by the kit. The shared telemetry emitter reads it (ISSUE-070) as the fallback containment root: an emit may only write inside the main git work-tree root of the process's current directory, and when that directory is not in a git work tree this knob supplies the root instead (with the current directory as the last resort). A --project-path that resolves outside that root is refused with one [kit-telemetry] line and nothing is written. A linked worktree created inside its repo — the only shape scripts/worktree.sh create produces — resolves to the MAIN repo root, so <repo>/.worktrees/<branch> and the repo root admit each other. A worktree placed outside its repo, or backed by a bare repo, resolves to itself instead: the emitter refuses to widen its own write boundary on the strength of a .git file, which is ordinary writable workspace content (review fix, PR #141). Under a plugin install the root is the user's project — never the kit's install directory.

Configuring gates via `docs/test_plan.md`

qa-designer generates a ## Verify Gates Configuration section in docs/test_plan.md. Users can edit it to override defaults without touching Python:

```markdown

Verify Gates Configuration

Server start command: npm run dev Server health URL: http://localhost:3000 Server startup timeout: 30 Mobile test framework: maestro Mobile build command: npm run build:ios Mobile Detox config: ios.sim.debug

Workflow

New project: ``` /prd → /kickoff → /uiux → /sprint