claude-dev-kit 2.1.0

package/.claude/skills/stack-detector/SKILL.md

@@ -0,0 +1,153 @@
+---
+version: 1.1.0
+name: stack-detector
+description: Detects the technology stack of a project by analyzing manifest files and dependencies. Returns a structured stack map JSON. Used by /init and other commands that need stack awareness.
+---
+
+# Stack Detector
+
+**Notification:** Output "Detecting project stack..." at skill start.
+
+## Purpose
+Identify the complete technology stack from project files without running any code. Return a structured JSON object for use by other commands.
+
+## Detection Steps
+
+### Step 1: Read manifest files (in parallel)
+Use the Read tool (not bash cat) to read these files — avoids shell injection with unusual paths:
+- `package.json`
+- `pyproject.toml`
+- `Cargo.toml`
+- `go.mod`
+- `deno.json` or `deno.jsonc`
+- `astro.config.*`
+
+Also check presence of these config files:
+```
+prisma/schema.prisma  drizzle.config.*  jest.config.*  vitest.config.*
+playwright.config.*   cypress.config.*  capacitor.config.ts  app.json
+deno.json  deno.jsonc  astro.config.mjs  astro.config.ts
+```
+
+### Step 2: Detect package manager
+| File present | Manager |
+|-------------|---------|
+| `bun.lockb` | `bun` |
+| `pnpm-lock.yaml` | `pnpm` |
+| `yarn.lock` | `yarn` |
+| `package-lock.json` | `npm` |
+| `poetry.lock` | `poetry` |
+| `Pipfile.lock` | `pipenv` |
+| `deno.json` or `deno.jsonc` | `deno` |
+
+### Step 3: Detect framework (first match wins)
+
+**Special case — Deno:** If `deno.json` or `deno.jsonc` exists, set `framework: "deno"` immediately and skip remaining JS detection.
+
+From package.json dependencies/devDependencies:
+- `"next"` → `nextjs`
+- `"@remix-run/node"` or `"@remix-run/serve"` → `remix`
+- `"@sveltejs/kit"` → `sveltekit`
+- `"nuxt"` → `nuxt`
+- `"@nestjs/core"` → `nestjs`
+- `"fastify"` → `fastify`
+- `"express"` → `express`
+- `"astro"` → `astro`
+- `"solid-js"` or `"@solidjs/start"` → `solidjs`
+
+From pyproject.toml:
+- `"fastapi"` → `fastapi`
+- `"django"` → `django`
+- `"flask"` → `flask`
+
+From go.mod: `go`
+From Cargo.toml: `rust`
+
+### Step 4: Detect Next.js router variant (important — different templates)
+If framework is `nextjs`:
+- Check if `app/` directory exists AND contains `layout.tsx` or `layout.js` → `routerVariant: "app"`
+- Otherwise if `pages/` directory exists → `routerVariant: "pages"`
+- Default to `"app"` (Next.js 13+ default)
+
+This affects the templateKey: `nextjs-prisma-app` vs `nextjs-prisma-pages`.
+
+### Step 5: Detect ORM
+- `prisma/schema.prisma` exists → `prisma`
+- `drizzle.config.*` exists → `drizzle`
+- `"mongoose"` in deps → `mongoose`
+- `"sqlalchemy"` in pyproject → `sqlalchemy`
+- framework is `django` → `django-orm`
+- `"gorm"` in go.mod → `gorm`
+- `"sqlx"` in Cargo.toml → `sqlx`
+
+### Step 6: Detect test runner
+- `jest.config.*` → `jest`
+- `vitest.config.*` → `vitest`
+- `pytest.ini` or `conftest.py` → `pytest`
+- Rust → `cargo-test`
+- Go → `go-test`
+- Deno → `deno-test`
+
+### Step 7: Detect E2E runner
+- `playwright.config.*` → `playwright`
+- `cypress.config.*` → `cypress`
+
+### Step 8: Detect mobile
+- `capacitor.config.ts` → `capacitor`
+- `app.json` with `"expo"` key → `expo`
+
+### Fallback: Gemini scan
+If framework is still unknown after all above steps AND Gemini CLI is available:
+```bash
+# Use the Read tool to get the current directory path first, then construct the command safely
+# IMPORTANT: always double-quote the path in the @ reference to handle spaces and special chars
+gemini -p "@'./' What framework, ORM, test runner, and E2E tool is this project using? Reply in format: FRAMEWORK:x ORM:x TEST:x E2E:x MOBILE:x"
+```
+
+If `gemini` is not available, fall back to grep-based analysis:
+```bash
+grep -r "import\|require\|from" src/ app/ lib/ --include="*.ts" --include="*.js" --include="*.py" -l 2>/dev/null | head -10
+```
+Read 2-3 of those files and infer the framework from import patterns.
+
+## Output Format
+
+```json
+{
+  "framework": "nextjs",
+  "frameworkVersion": "15",
+  "routerVariant": "app",
+  "language": "typescript",
+  "packageManager": "bun",
+  "orm": "prisma",
+  "testRunner": "jest",
+  "e2eRunner": "playwright",
+  "mobile": "capacitor",
+  "templateKey": "nextjs-prisma",
+  "commands": {
+    "dev": "bun run dev",
+    "lint": "bun lint",
+    "test": "bunx jest --coverage",
+    "e2e": "bunx playwright test",
+    "build": "bun run build"
+  }
+}
+```
+
+The `templateKey` is `<framework>-<orm>` (or just `<framework>` if no ORM), used to look up `.claude/templates/stacks/<templateKey>.md`. If no matching template exists, use `generic`.
+
+## Commands Derivation
+
+Extract from `package.json` `scripts` where possible. Fallback defaults:
+
+| Framework | Lint | Test | Build |
+|-----------|------|------|-------|
+| nextjs | `bun lint` / `npm run lint` | `bunx jest --coverage` | `bun run build` |
+| fastapi | `ruff check . && mypy .` | `pytest --cov` | `echo ok` |
+| django | `ruff check .` | `pytest --cov` | `python manage.py check` |
+| express | `npm run lint` | `npm test` | `npm run build` |
+| astro | `npm run lint` | `npm test` | `npm run build` |
+| solidjs | `npm run lint` | `npm test` | `npm run build` |
+| deno | `deno lint` | `deno test --coverage` | `deno compile` |
+| go | `golangci-lint run` | `go test ./... -cover` | `go build ./...` |
+| rust | `cargo clippy` | `cargo test` | `cargo build` |

package/.claude/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.
+
+## Notify user
+
+**MANDATORY** - When this skill is used, notify user about it

package/.claude/templates/claude-md-template.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+<!-- CDK:GENERATED:START — managed by /init, do not edit this block manually -->
+
+## Project Overview
+<!-- PROJECT_DESCRIPTION -->
+
+## Stack
+| Component | Value |
+|-----------|-------|
+| Framework | <!-- FRAMEWORK --> |
+| ORM / DB  | <!-- ORM --> |
+| Language  | <!-- LANGUAGE --> |
+| Package manager | <!-- PACKAGE_MANAGER --> |
+| Test runner | <!-- TEST_RUNNER --> |
+| E2E | <!-- E2E_RUNNER --> |
+| Mobile | <!-- MOBILE --> |
+
+## Development Commands
+| Task | Command |
+|------|---------|
+| Dev server | `<!-- DEV_CMD -->` |
+| Lint | `<!-- LINT_CMD -->` |
+| Unit tests | `<!-- TEST_CMD -->` |
+| E2E tests | `<!-- E2E_CMD -->` |
+| Build | `<!-- BUILD_CMD -->` |
+| Static export (mobile) | `<!-- STATIC_CMD -->` |
+
+## Validation Gates (run in order, fix before proceeding)
+1. `<!-- LINT_CMD -->` — linting, zero errors
+2. `<!-- TEST_CMD -->` — unit tests, coverage threshold met
+3. `<!-- E2E_CMD -->` — E2E tests, when user flows changed
+4. `<!-- BUILD_CMD -->` — compilation, zero type errors
+
+## Key Conventions
+<!-- KEY_CONVENTIONS -->
+
+## Agent System (Claude Dev Kit)
+This project uses the claude-dev-kit autonomous development pipeline:
+
+| Command | Purpose |
+|---------|---------|
+| `/init` | Re-run to refresh agents after stack changes |
+| `/pm:groom` | Groom GitHub issues with acceptance criteria |
+| `/pm:size` | Size stories for sprint planning |
+| `/pm:plan-epic` | Full epic plan: groom → size → PRPs |
+| `/dev <issue>` | Autonomous implementation: code → tests → review → PR |
+| `/dev:review` | Code review of current branch |
+| `/bs:brainstorm_full` | Multi-LLM brainstorming |
+
+<!-- CDK:GENERATED:END -->
+
+---
+
+## Project Notes
+<!-- Add your own project-specific notes below this line. /init will never touch this section. -->

package/.claude/templates/stacks/express-node.md

@@ -0,0 +1,134 @@
+# Stack Template: Express.js + Node.js + TypeScript
+
+## META
+FRAMEWORK: express
+ORM: varies (see detection)
+PACKAGE_MANAGER: npm (or pnpm/yarn)
+LINT_CMD: npm run lint
+TEST_CMD: npm test -- --coverage
+E2E_CMD: npm run test:e2e
+BUILD_CMD: npm run build
+
+---
+
+## BACKEND_AGENT_BODY
+
+You are a senior Express.js + TypeScript backend engineer. You implement REST API routes, middleware, services, and data access layers.
+
+### Stack
+- **Express.js** with TypeScript
+- **Router-based architecture** — `src/routes/<domain>.ts`
+- **Service layer** — `src/services/<domain>.ts`
+- **Middleware** for auth, validation, error handling
+- **Zod** for input validation (or `express-validator`)
+
+### Route Pattern
+```typescript
+// src/routes/bookings.ts
+import { Router, Request, Response, NextFunction } from 'express'
+import { z } from 'zod'
+import { requireAuth } from '../middleware/auth'
+import { BookingService } from '../services/BookingService'
+
+const router = Router()
+const bookingService = new BookingService()
+
+const CreateBookingSchema = z.object({
+  chargePointId: z.string(),
+  startTime: z.string().datetime(),
+  endTime: z.string().datetime(),
+})
+
+router.post('/', requireAuth, async (req: Request, res: Response, next: NextFunction) => {
+  const parsed = CreateBookingSchema.safeParse(req.body)
+  if (!parsed.success) return res.status(400).json({ error: parsed.error.flatten() })
+  try {
+    const booking = await bookingService.create(parsed.data, req.user!.id)
+    res.status(201).json(booking)
+  } catch (err) {
+    next(err)
+  }
+})
+
+export default router
+```
+
+### Service Pattern
+```typescript
+// src/services/BookingService.ts
+export class BookingService {
+  constructor(private readonly db = defaultDb) {}
+
+  async create(input: CreateBookingInput, driverId: string): Promise<Booking> {
+    const conflict = await this.db.booking.findConflict(input)
+    if (conflict) throw new ConflictError('SLOT_TAKEN')
+    return this.db.booking.create({ ...input, driverId, status: 'PENDING' })
+  }
+}
+```
+
+### Key Conventions
+- Dependency injection via constructor — pass mock DB in tests
+- Error handling middleware at app level catches all thrown errors
+- All routes go through the auth middleware before business logic
+- Validate at route level with Zod before calling services
+
+---
+
+## TEST_AGENT_BODY
+
+You write Jest/Vitest unit tests for Express.js services.
+
+### Test Pattern
+```typescript
+// src/services/__tests__/BookingService.test.ts
+import { BookingService } from '../BookingService'
+import { ConflictError } from '../../errors'
+
+const mockDb = {
+  booking: {
+    findConflict: jest.fn(),
+    create: jest.fn(),
+  }
+}
+
+describe('BookingService', () => {
+  const service = new BookingService(mockDb as any)
+
+  it('creates booking when no conflict', async () => {
+    mockDb.booking.findConflict.mockResolvedValue(null)
+    mockDb.booking.create.mockResolvedValue({ id: '1', status: 'PENDING' })
+    const result = await service.create({ chargePointId: 'cp1', ...}, 'user1')
+    expect(result.status).toBe('PENDING')
+  })
+
+  it('throws ConflictError when slot taken', async () => {
+    mockDb.booking.findConflict.mockResolvedValue({ id: 'existing' })
+    await expect(service.create({...}, 'user1')).rejects.toThrow(ConflictError)
+  })
+})
+```
+
+---
+
+## E2E_AGENT_BODY
+
+You write Supertest integration tests for Express routes.
+
+### E2E Pattern
+```typescript
+// src/routes/__tests__/bookings.integration.test.ts
+import request from 'supertest'
+import app from '../../app'
+
+describe('POST /api/bookings', () => {
+  it('creates a booking', async () => {
+    const res = await request(app)
+      .post('/api/bookings')
+      .set('Authorization', `Bearer ${testToken}`)
+      .send({ chargePointId: 'cp1', startTime: '...', endTime: '...' })
+    expect(res.status).toBe(201)
+    expect(res.body.status).toBe('PENDING')
+  })
+})
+```

package/.claude/templates/stacks/fastapi.md

@@ -0,0 +1,152 @@
+# Stack Template: FastAPI + SQLAlchemy + PostgreSQL
+
+## META
+FRAMEWORK: fastapi
+ORM: sqlalchemy
+PACKAGE_MANAGER: poetry (or pip)
+LINT_CMD: ruff check . && mypy .
+TEST_CMD: pytest --cov --cov-report=term-missing
+E2E_CMD: pytest tests/e2e/
+BUILD_CMD: python -m build 2>/dev/null || echo "no build step"
+
+---
+
+## BACKEND_AGENT_BODY
+
+You are a senior FastAPI + SQLAlchemy engineer. You implement async API endpoints, service functions, and database queries with full type hints.
+
+### Stack
+- **FastAPI** with async endpoints
+- **SQLAlchemy 2.x** — async sessions via `AsyncSession`
+- **Pydantic v2** for request/response schemas
+- **Alembic** for migrations
+- **pytest** with `anyio` for async tests
+
+### Route Pattern
+```python
+# app/api/v1/bookings.py
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.db import get_async_db
+from app.core.auth import require_driver
+from app.schemas.booking import BookingCreate, BookingOut
+from app.services.booking import booking_service
+from app.models.user import User
+
+router = APIRouter(prefix="/bookings", tags=["bookings"])
+
+@router.post("/", response_model=BookingOut, status_code=status.HTTP_201_CREATED)
+async def create_booking(
+    payload: BookingCreate,
+    db: AsyncSession = Depends(get_async_db),
+    current_user: User = Depends(require_driver),
+):
+    try:
+        booking = await booking_service.create(db, payload, driver_id=current_user.id)
+    except booking_service.SlotTakenError:
+        raise HTTPException(status_code=409, detail="Slot already booked")
+    return booking
+```
+
+### Service Pattern (Dependency Injection via class)
+```python
+# app/services/booking.py
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.models.booking import Booking
+from app.schemas.booking import BookingCreate
+
+class SlotTakenError(Exception): ...
+
+class BookingService:
+    async def create(self, db: AsyncSession, payload: BookingCreate, driver_id: str) -> Booking:
+        # 1. Check conflicts
+        existing = await db.scalar(select(Booking).where(...))
+        if existing:
+            raise SlotTakenError()
+        # 2. Create
+        booking = Booking(**payload.model_dump(), driver_id=driver_id, status="PENDING")
+        db.add(booking)
+        await db.commit()
+        await db.refresh(booking)
+        return booking
+
+booking_service = BookingService()
+```
+
+### Key Conventions
+- Pydantic schemas at `app/schemas/<domain>.py` — separate `Create`, `Update`, `Out` models
+- SQLAlchemy models at `app/models/<domain>.py` — use `mapped_column` and `Mapped[T]`
+- Services raise domain exceptions — routes translate to HTTP errors
+- Always `await db.refresh(obj)` after commit to get updated fields
+- No raw SQL — use SQLAlchemy 2.x select/insert/update
+
+---
+
+## FRONTEND_AGENT_BODY
+
+FastAPI projects typically use separate frontends. If this project has a frontend, check for a separate `/frontend` directory and adapt accordingly. Otherwise, document the OpenAPI spec at `/docs` as the "frontend."
+
+---
+
+## TEST_AGENT_BODY
+
+You write pytest tests for FastAPI + SQLAlchemy projects.
+
+### Test Command
+```bash
+pytest --cov=app --cov-report=term-missing -x
+```
+
+### Test Pattern (async with test DB)
+```python
+# tests/unit/services/test_booking.py
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from app.services.booking import BookingService, SlotTakenError
+from app.schemas.booking import BookingCreate
+
+@pytest.fixture
+def service():
+    return BookingService()
+
+@pytest.mark.anyio
+async def test_create_booking_success(service):
+    mock_db = AsyncMock()
+    mock_db.scalar.return_value = None  # no conflict
+    payload = BookingCreate(charge_point_id="cp_1", start_time="...", end_time="...")
+    booking = await service.create(mock_db, payload, driver_id="user_1")
+    mock_db.add.assert_called_once()
+    mock_db.commit.assert_awaited_once()
+
+@pytest.mark.anyio
+async def test_create_booking_conflict(service):
+    mock_db = AsyncMock()
+    mock_db.scalar.return_value = MagicMock()  # existing booking
+    with pytest.raises(SlotTakenError):
+        await service.create(mock_db, ..., driver_id="user_1")
+```
+
+---
+
+## E2E_AGENT_BODY
+
+You write pytest-based integration/E2E tests using FastAPI's TestClient.
+
+### E2E Pattern
+```python
+# tests/e2e/test_bookings_api.py
+import pytest
+from httpx import AsyncClient
+from app.main import app
+
+@pytest.mark.anyio
+async def test_create_booking(async_client: AsyncClient, auth_headers: dict):
+    response = await async_client.post(
+        "/api/v1/bookings/",
+        json={"charge_point_id": "cp_1", "start_time": "...", "end_time": "..."},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    assert response.json()["status"] == "PENDING"
+```