claude-dev-kit 2.1.0

package/.claude/commands/improve.md

@@ -0,0 +1,178 @@
+---
+description: "Analyze session learning logs to identify patterns and propose concrete improvements to agents, skills, and commands. The kit's feedback loop."
+argument-hint: [days=14 | all]
+---
+
+# /improve — Self-Improvement Analysis
+
+Read session learning data captured by the learning logger, identify patterns, and propose concrete improvements to the kit's agents, skills, and skill-activation rules. Optionally auto-apply low-risk improvements.
+
+## Steps
+
+### 1. Determine lookback window
+
+```
+DAYS = $ARGUMENTS (default: 14)
+```
+
+If `$ARGUMENTS` is "all", read all available logs.
+If empty, default to last 14 days.
+
+### 2. Read learning logs
+
+```bash
+ls .claude/learning/sessions/ 2>/dev/null | sort -r | head -30
+```
+
+For each relevant log file (within the requested date window):
+```bash
+cat .claude/learning/sessions/<YYYY-MM-DD>.jsonl
+```
+
+### 3. Aggregate statistics
+
+Compute across all sessions:
+
+**Command frequency:**
+- Which slash commands were used most? (`slash_commands` field)
+- Which were never used?
+
+**Agent usage:**
+- Which agents were spawned most? (`agents_spawned` field)
+- Agent-to-turn ratio (efficiency indicator)
+
+**Tool call patterns:**
+- Most-used tools (`tools_called` field)
+- Any tools never used?
+
+**Error patterns:**
+- Common error substrings from `errors` field
+- Which sessions had the most errors?
+
+**Token consumption:**
+- Average tokens per session
+- Most expensive sessions
+
+**Skill activation gaps:**
+- Compare `slash_commands` against `skill-rules.json` triggers
+- Identify user phrases that DIDN'T trigger skills but should have
+
+### 4. Read current skill rules
+
+```bash
+cat .claude/hooks/skill-activation-prompt/skill-rules.json
+```
+
+### 5. Read current agent files (sample)
+
+Read the agents that showed the highest usage or most errors:
+```bash
+cat .claude/agents/<most-used-agent>.md
+```
+
+### 6. Generate improvement report
+
+Using the data, produce a structured analysis:
+
+```markdown
+## /improve Analysis — Last <N> Days
+
+### Usage Summary
+- Sessions analyzed: <count>
+- Total turns: <count>
+- Total tokens consumed: <count>
+- Average tokens/session: <count>
+
+### Most-Used Commands
+1. /<cmd> — <count> times
+2. /<cmd> — <count> times
+...
+
+### Unused Commands (consider removing or improving)
+- /<cmd> — 0 uses in <N> days
+- /<cmd> — 0 uses in <N> days
+
+### Skill Activation Gaps
+Phrases found in user prompts that DIDN'T trigger a skill but likely should have:
+- "<phrase>" → suggest adding trigger to <skill>
+- "<phrase>" → suggest adding trigger to <skill>
+
+### Agent Efficiency
+- <agent>: avg <X> turns per spawn (high = may need tighter prompts)
+- <agent>: avg <X> turns per spawn
+
+### Common Error Patterns
+- "<error snippet>" — appears in <N> sessions
+  → Likely cause: <analysis>
+  → Suggested fix: <fix>
+
+### Token Hotspots
+- Top consuming sessions: <count> tokens — commands used: <list>
+  → Consider: caching results, using Haiku for this task, or splitting into smaller chunks
+
+### Proposed Improvements
+
+#### High Priority (auto-apply candidates)
+1. **Add skill trigger**: Add "<phrase>" to `skill-rules.json` triggers for <skill>
+   - Evidence: seen in <N> sessions
+
+2. **Agent prompt tightening**: <agent>.md — add constraint to reduce turn count
+   - Evidence: avg <X> turns, expected < <Y>
+
+#### Medium Priority (review before applying)
+3. **New skill needed**: Pattern "<X>" appears repeatedly with no skill match
+   - Suggested: create a new skill for <purpose>
+
+4. **Command consolidation**: /<cmd1> and /<cmd2> often used together
+   - Suggested: create /<combined> shorthand
+
+#### Low Priority (future consideration)
+5. **Unused command cleanup**: /<cmd> — 0 uses in 14 days
+   - Suggested: add to README as "advanced" or deprecate
+```
+
+### 7. Offer to apply improvements
+
+After showing the report, ask:
+
+> **Auto-apply safe improvements?**
+> This would update `skill-rules.json` with suggested new triggers only (no agent edits).
+> Agent prompt changes require your review.
+
+Use AskUserQuestion with options:
+- "Yes — update skill-rules.json only"
+- "Yes — update skill-rules.json AND show agent diffs for review"
+- "No — just show the report"
+
+### 8. Apply approved improvements
+
+**For skill-rules.json updates:**
+1. Read current rules
+2. Add new trigger keywords to appropriate skill entries
+3. Write back to `.claude/hooks/skill-activation-prompt/skill-rules.json`
+4. Report which triggers were added
+
+**For agent improvements:**
+Show the proposed diff using a clear before/after format. Only apply after user confirmation.
+
+### 9. Log improvement action
+
+Append to `.claude/learning/improvements.jsonl`:
+```json
+{
+  "ts": <timestamp>,
+  "date": "<YYYY-MM-DD>",
+  "sessions_analyzed": <count>,
+  "improvements_proposed": <count>,
+  "improvements_applied": <count>,
+  "changes": ["<description>", ...]
+}
+```
+
+## Notes
+
+- This command reads only `.claude/learning/` data — no external network calls
+- All analysis is local — session data stays on your machine
+- Learning data is automatically pruned after 90 days (by the learning_logger hook)
+- Run after every few development sessions for best results
+- For AI-powered critique of the kit itself, use `/self-improve`

package/.claude/commands/init.md

@@ -0,0 +1,311 @@
+---
+description: "Smart project setup. Detects your stack and generates customized agents, CLAUDE.md, and settings.json. Or interviews you to design a new project from scratch. Run once when adding Claude Dev Kit to any project."
+argument-hint: [existing | new]
+---
+
+# /init — Project Initialization
+
+Set up Claude Dev Kit for this project. This command either detects an existing codebase and configures agents to match, or interviews you to design a new project from scratch.
+
+## Phase 0: Determine Mode
+
+```
+If $ARGUMENTS is "new" → skip to Phase 3 (New Project Interview)
+If $ARGUMENTS is "existing" → run Phase 1
+Otherwise → auto-detect:
+  Run: ls -la
+  If fewer than 8 non-hidden files in root → likely new project → ask user
+  If package.json / pyproject.toml / Cargo.toml / go.mod found → existing project
+```
+
+---
+
+## Phase 1: File Inventory (Existing Projects)
+
+Run these reads in parallel to build a complete picture of the project:
+
+```bash
+# Project manifest files
+cat package.json 2>/dev/null || echo "NO_PACKAGE_JSON"
+cat pyproject.toml 2>/dev/null || echo "NO_PYPROJECT"
+cat Cargo.toml 2>/dev/null || echo "NO_CARGO"
+cat go.mod 2>/dev/null || echo "NO_GO_MOD"
+
+# Framework config
+ls next.config.* nuxt.config.* svelte.config.* remix.config.* astro.config.* vite.config.* 2>/dev/null
+
+# Database/ORM
+ls prisma/schema.prisma drizzle.config.* 2>/dev/null
+
+# Testing
+ls jest.config.* vitest.config.* playwright.config.* cypress.config.* pytest.ini conftest.py 2>/dev/null
+
+# Mobile
+ls capacitor.config.ts app.json 2>/dev/null
+
+# CI/CD
+ls .github/workflows/ 2>/dev/null | head -5
+ls Dockerfile docker-compose.yml 2>/dev/null
+
+# Project structure (top-level only)
+tree -L 2 --gitignore 2>/dev/null || find . -maxdepth 2 -not -path './.git/*' -not -path './node_modules/*' -not -path './.next/*' | sort
+```
+
+---
+
+## Phase 2: Stack Detection
+
+Analyze the inventory to produce a detection JSON. Use this decision tree — first match wins per category:
+
+### Framework
+| Detection | Result |
+|-----------|--------|
+| `"next"` in package.json deps | `nextjs` |
+| `"@remix-run/node"` or `"@remix-run/serve"` | `remix` |
+| `"@sveltejs/kit"` | `sveltekit` |
+| `"nuxt"` | `nuxt` |
+| `"@nestjs/core"` | `nestjs` |
+| `"fastify"` | `fastify` |
+| `"express"` | `express` |
+| `"fastapi"` in pyproject deps | `fastapi` |
+| `"django"` in pyproject deps | `django` |
+| `"flask"` in pyproject deps | `flask` |
+| go.mod exists + detect router from imports | `go` |
+| Cargo.toml exists + detect crate from deps | `rust` |
+
+### Package Manager
+| Detection | Result |
+|-----------|--------|
+| `bun.lockb` exists | `bun` |
+| `pnpm-lock.yaml` exists | `pnpm` |
+| `yarn.lock` exists | `yarn` |
+| `package-lock.json` exists | `npm` |
+| `Pipfile.lock` / `poetry.lock` | `poetry` |
+
+### ORM / Database Layer
+| Detection | Result |
+|-----------|--------|
+| `prisma/schema.prisma` | `prisma` |
+| `drizzle.config.*` | `drizzle` |
+| `"mongoose"` in deps | `mongoose` |
+| `"sqlalchemy"` in pyproject | `sqlalchemy` |
+| `"django"` already detected | `django-orm` |
+| `"gorm"` in go.mod | `gorm` |
+| `"sqlx"` in Cargo.toml | `sqlx` |
+
+### Test Runner
+| Detection | Result |
+|-----------|--------|
+| `jest.config.*` | `jest` |
+| `vitest.config.*` | `vitest` |
+| `pytest.ini` or `conftest.py` | `pytest` |
+| `cargo test` (Rust) | `cargo-test` |
+| `go test` (Go) | `go-test` |
+
+### E2E
+| Detection | Result |
+|-----------|--------|
+| `playwright.config.*` | `playwright` |
+| `cypress.config.*` | `cypress` |
+
+### Mobile
+| Detection | Result |
+|-----------|--------|
+| `capacitor.config.ts` | `capacitor` |
+| `app.json` with `"expo"` key | `expo` |
+
+### Ambiguous / Large Codebase Fallback
+If the framework is not detectable from manifest files, use Gemini:
+```bash
+gemini -p "@./ Identify the web framework, ORM/database layer, test runner, E2E tool, and mobile platform used in this project. Respond in exactly this format:
+FRAMEWORK: <name>
+ORM: <name or none>
+TEST_RUNNER: <name or none>
+E2E: <name or none>
+MOBILE: <name or none>
+PACKAGE_MANAGER: <name>"
+```
+
+---
+
+## Phase 3: New Project Interview
+
+Ask these questions sequentially using the AskUserQuestion tool. Wait for each answer before asking the next.
+
+**Q1**: What are you building?
+- A web application
+- A mobile app (iOS/Android)
+- A REST/GraphQL API
+- A full-stack platform (web + mobile + API)
+- Something else
+
+**Q2**: Describe your idea in 2-3 sentences (free text — ask this as plain text, not multiple choice)
+
+**Q3**: Expected scale and usage?
+- Personal / hobby project
+- Small team startup (< 50 users initially)
+- Production SaaS (100s–1000s of users)
+- Enterprise / high-scale
+
+**Q4**: What language ecosystem do you prefer?
+- TypeScript / JavaScript
+- Python
+- Go
+- Rust
+- Undecided — recommend for me
+
+**Q5** (if TypeScript): Which framework?
+- Next.js (full-stack, server + client)
+- Remix (full-stack, web standards)
+- SvelteKit (full-stack, lightweight)
+- Nuxt (full-stack, Vue)
+- Express / Fastify (API-only, no frontend)
+- NestJS (enterprise API)
+- Undecided — recommend for me
+
+**Q6** (if TypeScript/fullstack): Database?
+- PostgreSQL with Prisma ORM
+- PostgreSQL with Drizzle ORM
+- MongoDB with Mongoose
+- SQLite (local / edge)
+- Undecided — recommend for me
+
+**Q7**: Authentication needed?
+- Yes — Auth.js / NextAuth (for Next.js)
+- Yes — BetterAuth (framework-agnostic)
+- Yes — Clerk (managed service)
+- Yes — Custom JWT
+- No authentication needed
+
+**Q8**: Payments?
+- Stripe
+- Other payment provider
+- No payments needed
+
+**Q9**: Mobile app?
+- Yes — Capacitor (wrap web app for iOS/Android)
+- Yes — Expo (React Native)
+- No mobile needed
+
+**Q10**: Testing approach?
+- Full coverage: unit tests + E2E + coverage enforcement
+- Unit tests only
+- Minimal (lint + build only)
+
+Build the stack map from answers. For "Undecided — recommend for me" answers, apply these defaults:
+- TypeScript + small/medium scale + web → Next.js + Prisma + PostgreSQL
+- TypeScript + API-only → Fastify + Drizzle
+- Python → FastAPI + SQLAlchemy
+- Go → Gin + GORM
+
+---
+
+## Phase 4: Read Stack Templates
+
+Based on the detection result, read the matching templates from `.claude/templates/`:
+
+```
+Primary template:  .claude/templates/stacks/<framework>-<orm>.md
+                   (or .claude/templates/stacks/<framework>.md if no ORM)
+Test template:     .claude/templates/test-runners/<test-runner>.md
+E2E template:      .claude/templates/test-runners/<e2e-runner>.md  (if applicable)
+Mobile template:   .claude/templates/mobile/<mobile>.md            (if applicable)
+Fallback:          .claude/templates/stacks/generic.md
+```
+
+Extract from each template:
+- `BACKEND_AGENT_BODY` section → replaces body in `.claude/agents/dev-backend.md`
+- `FRONTEND_AGENT_BODY` section → replaces body in `.claude/agents/dev-frontend.md`
+- `TEST_AGENT_BODY` section → replaces body in `.claude/agents/dev-test.md`
+- `E2E_AGENT_BODY` section → replaces body in `.claude/agents/dev-e2e.md`
+- `LINT_CMD`, `TEST_CMD`, `BUILD_CMD`, `E2E_CMD` → used in CLAUDE.md + settings.json
+
+---
+
+## Phase 5: Generate Files
+
+### 5a. Update engineering agents
+
+For each agent: preserve the YAML frontmatter exactly. Replace everything after the closing `---` with the stack-specific body from the template.
+
+Files to update:
+- `.claude/agents/dev-backend.md`
+- `.claude/agents/dev-frontend.md`
+- `.claude/agents/dev-test.md`
+- `.claude/agents/dev-e2e.md`
+
+### 5b. Generate or update CLAUDE.md
+
+**If CLAUDE.md exists:** Preserve content outside `<!-- CDK:START -->` / `<!-- CDK:END -->` fences. Only replace the fenced section.
+
+**If new:** Generate the full file using `.claude/templates/claude-md-template.md` as the structure.
+
+**Content to populate:**
+- Project name from `package.json` `name` field (or ask for new projects)
+- Stack summary
+- Dev commands table (extracted from `package.json` `scripts` or language conventions)
+- Validation gate commands
+
+### 5c. Update .claude/settings.json
+
+Read existing settings.json. Preserve the `hooks` section verbatim. Replace only the `permissions.allow` array with:
+
+**Always include:**
+```json
+"Read", "Write", "Edit",
+"Bash(gh:*)", "Bash(git:*)", "Bash(ls:*)", "Bash(grep:*)", "Bash(tree:*)",
+"Bash(gemini:*)", "Bash(gemini -p:*)"
+```
+
+**Per package manager:**
+- bun → `"Bash(bun:*)"`, `"Bash(bunx:*)"`
+- npm → `"Bash(npm run:*)"`, `"Bash(npx:*)"`
+- pnpm → `"Bash(pnpm:*)"`, `"Bash(pnpm dlx:*)"`
+- yarn → `"Bash(yarn:*)"`
+- poetry → `"Bash(poetry:*)"`, `"Bash(python:*)"`
+- go → `"Bash(go:*)"`
+- cargo → `"Bash(cargo:*)"`
+
+**Per tools:**
+- Docker present → `"Bash(docker:*)"`, `"Bash(docker compose:*)"`
+- Playwright → `"Bash(npx playwright:*)"` or `"Bash(bunx playwright:*)"`
+
+---
+
+## Phase 6: Completion Report
+
+```markdown
+## /init Complete ✅
+
+### Detected / Configured Stack
+| Component | Value |
+|-----------|-------|
+| Framework | Next.js 15 (App Router) |
+| ORM | Prisma 7 + PostgreSQL |
+| Package manager | Bun |
+| Test runner | Jest |
+| E2E | Playwright |
+| Mobile | Capacitor |
+
+### Files Generated/Updated
+- `.claude/agents/dev-backend.md` — Next.js + Prisma patterns
+- `.claude/agents/dev-frontend.md` — Next.js App Router + Tailwind patterns
+- `.claude/agents/dev-test.md` — Jest + Bun + DI mock patterns
+- `.claude/agents/dev-e2e.md` — Playwright patterns
+- `CLAUDE.md` — project guide created/updated
+- `.claude/settings.json` — permissions updated
+
+### Next Steps
+1. **Review** `CLAUDE.md` and add any project-specific conventions
+2. **Run** `/primer` to verify Claude understands the project
+3. **Plan** your backlog: `/pm:groom` → `/pm:size` → `/pm:plan-epic`
+4. **Build**: `/dev <issue-number>` to implement your first feature
+```
+
+---
+
+## Important Notes
+
+- `/init` is safe to re-run — it preserves manual customizations in CLAUDE.md (outside CDK fences) and preserves all hooks in settings.json
+- After a major stack change (e.g., adding a new ORM), re-run `/init` to refresh the engineering agents
+- The `project-manager` and `dev-lead` orchestrators are stack-agnostic — they are never modified by `/init`

package/.claude/commands/pm/groom.md

@@ -0,0 +1,58 @@
+---
+description: "Groom GitHub/Linear/Jira issues. Adds acceptance criteria, Definition of Done, and sub-tasks. Pass an issue number, milestone name, or leave empty to groom all ungroomed issues."
+argument-hint: [issue-number | milestone-name | empty]
+---
+
+# /pm:groom
+
+Invoke the `project-manager` orchestrator to groom issues. The PM will internally spawn `pm-groomer` for each issue.
+
+## Steps
+
+### 0. Rate limit preflight
+
+```bash
+# Check GitHub API availability before making bulk calls
+gh api rate_limit --jq '.rate | "Remaining: \(.remaining)/\(.limit) (resets \(.reset | strftime("%H:%M")))"' 2>/dev/null || true
+```
+
+If remaining < 10, warn: "GitHub API rate limit is nearly exhausted. Wait until reset before grooming."
+
+### 1. Identify issues to groom
+
+```bash
+# If $ARGUMENTS is an issue number:
+gh issue view $ARGUMENTS
+
+# If $ARGUMENTS is a milestone name:
+gh issue list --state open --milestone "$ARGUMENTS" --limit 50 --json number,title,body
+
+# If $ARGUMENTS is empty — find ungroomed issues (no "Acceptance Criteria" heading):
+gh issue list --state open --limit 50 --json number,title,body
+```
+
+Filter for issues whose body does NOT contain "Acceptance Criteria".
+
+### 2. Gather domain context
+For each issue, search for 2-3 related source files using Grep on the issue title keywords. These file paths will be passed to the groomer as context.
+
+### 3. Spawn project-manager
+
+Use the Task tool with the `project-manager` agent:
+```
+Goal: "Groom the following issues and return updated issue bodies"
+Context: [issue content + relevant file paths]
+```
+
+The project-manager will spawn `pm-groomer` for each issue or batch.
+
+### 4. Present for confirmation
+Show all updated issue bodies to the user. Ask: "Apply these updates to GitHub?"
+
+If confirmed, run for each issue:
+```bash
+gh issue edit <number> --body "<updated-body>"
+```
+
+### 5. Report
+List all issues groomed with their new titles.

package/.claude/commands/pm/plan-epic.md

@@ -0,0 +1,74 @@
+---
+description: "Full epic planning pipeline: groom all stories → size them → write PRPs for L/XL stories. Pass a milestone name."
+argument-hint: [milestone-name]
+---
+
+# /pm:plan-epic
+
+Run the full planning pipeline for an epic (GitHub milestone). At the end, every story is groomed, sized, and L/XL stories have PRPs.
+
+## Steps
+
+### 0. Rate limit preflight
+
+```bash
+gh api rate_limit --jq '.rate | "Remaining: \(.remaining)/\(.limit) (resets \(.reset | strftime("%H:%M")))"' 2>/dev/null || true
+```
+
+If remaining < 20, warn: "GitHub API rate limit is low. Epic planning makes many API calls — wait until reset or reduce the epic size."
+
+### 1. Identify the epic
+
+```bash
+# List milestones to pick from if $ARGUMENTS is empty
+gh api repos/:owner/:repo/milestones --jq '.[].title'
+```
+
+If `$ARGUMENTS` is provided, use it as the milestone name.
+
+### 2. List all stories in the epic
+
+```bash
+gh issue list --state open --milestone "$ARGUMENTS" --limit 50 --json number,title,body,labels
+```
+
+### 3. Grooming pass
+
+For any issue without "Acceptance Criteria" in body:
+- Run the `/pm:groom` flow (spawn project-manager with grooming goal)
+- Confirm and apply before proceeding to sizing
+
+### 4. Sizing pass
+
+Run `/pm:size` flow for all stories in the epic.
+Present sizing table. Confirm before applying labels.
+
+### 5. PRP generation for L/XL stories
+
+For each story sized L or XL, or with confidence < 0.7:
+
+Spawn the `project-manager` with goal:
+```
+"Write a PRP for issue #<N>. Research the codebase and produce PRPs/<slug>.md"
+```
+
+The PM will internally spawn `pm-prp-writer`.
+
+### 6. Epic summary report
+
+```markdown
+## Epic Plan: <Milestone Name>
+
+| # | Title | Size | Confidence | PRP |
+|---|-------|------|------------|-----|
+| #142 | Add pagination | M | 0.9 | — |
+| #143 | Fix race condition | S | 0.8 | — |
+| #144 | Stripe refunds | L | 0.6 | PRPs/stripe-refunds.md |
+
+### Sprint Allocation
+Sprint 1: #142, #143 (3 days total)
+Sprint 2: #144 (after PRP review)
+
+### Ready for development
+Run: `/dev 142` to begin implementation
+```

package/.claude/commands/pm/size.md

@@ -0,0 +1,46 @@
+---
+description: "Size stories for sprint planning. Adds t-shirt size labels (size:XS/S/M/L/XL) and confidence scores. Pass a milestone name, issue numbers, or leave empty for all groomed issues."
+argument-hint: [milestone-name | issue-numbers | empty]
+---
+
+# /pm:size
+
+Invoke the `project-manager` orchestrator to size stories. The PM will internally spawn `pm-sizer`.
+
+## Steps
+
+### 1. Fetch stories to size
+
+```bash
+# If $ARGUMENTS is a milestone:
+gh issue list --state open --milestone "$ARGUMENTS" --limit 50 --json number,title,body,labels
+
+# If $ARGUMENTS is issue numbers (space-separated):
+# Fetch each: gh issue view <N>
+
+# If empty — all groomed issues (have "Acceptance Criteria"):
+gh issue list --state open --limit 100 --json number,title,body,labels
+```
+
+Filter for issues that have "Acceptance Criteria" in body (groomed) but do NOT already have a `size:*` label.
+
+### 2. Get sprint capacity
+Ask the user: "What is your sprint capacity in days?" (default: 10)
+
+### 3. Spawn project-manager
+
+Use the Task tool:
+```
+Goal: "Size the following groomed stories and produce a sprint plan"
+Context: [full issue bodies + sprint capacity]
+```
+
+The project-manager will spawn `pm-sizer`.
+
+### 4. Present sizing table
+Show the sizing table and sprint plan. Ask: "Apply size labels to GitHub?"
+
+If confirmed, run the `gh issue edit --add-label` commands returned by the sizer.
+
+### 5. Flag L/XL stories
+For any L or XL story, suggest: "Run `/pm:plan-epic` for issue #N to generate a PRP before scheduling."