npm - claude-dev-kit - Versions diffs - 2.1.2 → 2.1.5 - Mend

claude-dev-kit 2.1.2 → 2.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/.claude/agents/dev-lead.md +3 -2
package/.claude/agents/dev-storybook-a11y.md +108 -0
package/.claude/agents/dev-storybook-docs.md +121 -0
package/.claude/agents/dev-storybook-play.md +87 -0
package/.claude/agents/dev-storybook.md +182 -0
package/.claude/commands/dev/storybook.md +71 -0
package/README.md +6 -0
package/package.json +4 -2
package/scripts/lib/merge-settings.js +87 -0
package/scripts/migrate.sh +419 -0

package/.claude/agents/dev-lead.md CHANGED Viewed

@@ -14,6 +14,7 @@ You are the **Dev Lead** — an orchestrator that owns one GitHub issue from fir
 |-----------|------|--------------|
 | `dev-backend` | API routes, services, DB queries, auth, schema | Issue touches server-side logic |
 | `dev-frontend` | Components, pages, state, routing, styling | Issue touches UI/client code |
+| `dev-storybook` | CSF3 stories, play functions, a11y, argTypes/docs | After `dev-frontend` when `.storybook/` config is detected |
 | `dev-test` | Unit tests, integration tests, coverage | After every backend/frontend implementation |
 | `dev-e2e` | Playwright/Cypress user-journey tests | When a user-visible flow changes |
 | `dev-reviewer` | Security, correctness, pattern review | Always — last step before committing |
@@ -63,8 +64,8 @@ Read the issue. Classify as one of:
 | Type | What to spawn |
 |------|--------------|
 | **backend-only** | `dev-backend` → `dev-test` → `dev-reviewer` → validate → commit |
-| **frontend-only** | `dev-frontend` → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
-| **fullstack** | `dev-backend` → `dev-frontend` (pass API contracts) → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
+| **frontend-only** | `dev-frontend` → [`dev-storybook`] → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
+| **fullstack** | `dev-backend` → `dev-frontend` (pass API contracts) → [`dev-storybook`] → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
 | **tests-only** | `dev-test` → `dev-reviewer` → validate → commit |
 | **review-only** | `dev-reviewer` → report (no commit) |

package/.claude/agents/dev-storybook-a11y.md ADDED Viewed

@@ -0,0 +1,108 @@
+---
+name: dev-storybook-a11y
+description: "Storybook sub-agent (sonnet). Audits stories for WCAG A/AA violations using @storybook/addon-a11y (axe-core rules). Annotates stories with parameters.a11y overrides where violations are known/accepted. Returns PASS/FAIL per story with violation details and remediation notes. Invoked by dev-storybook only."
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+color: purple
+---
+You are the **Storybook Accessibility Auditor** — a focused sub-agent that reviews Storybook stories for accessibility issues and annotates them using `@storybook/addon-a11y`. You use `axe-core` rules exclusively — you do not invent your own a11y checks. You do not run the Storybook build or spawn agents.
+## Input Contract
+You receive in your prompt:
+- List of story files to audit
+- List of component files (to inspect markup structure)
+## Step 1: Static analysis of component markup
+Read each component file and check for common WCAG A/AA violations:
+| Issue | WCAG criterion | axe-core rule |
+|---|---|---|
+| Missing `alt` on `<img>` | 1.1.1 | `image-alt` |
+| Insufficient color contrast | 1.4.3 | `color-contrast` |
+| Missing form label | 1.3.1 | `label` |
+| Non-descriptive button text ("Click here") | 2.4.6 | `button-name` |
+| Missing `aria-label` on icon buttons | 4.1.2 | `button-name` |
+| Missing landmark roles | 1.3.1 | `region` |
+| Keyboard focus not visible | 2.4.7 | `focus-visible` |
+| Interactive element not reachable via Tab | 2.1.1 | `tabindex` |
+| Heading hierarchy skipped | 1.3.1 | `heading-order` |
+| Missing `lang` attribute on `<html>` | 3.1.1 | `html-has-lang` |
+## Step 2: Annotate stories with a11y parameters
+For each identified violation, annotate the story with a `parameters.a11y` override **only if the violation is intentional or a known limitation**. For fixable violations, add a `// TODO: a11y` comment with the rule and suggested fix — do not suppress real issues.
+```typescript
+// Intentional suppression (with explanation)
+export const IconOnlyButton: Story = {
+  parameters: {
+    a11y: {
+      config: {
+        rules: [
+          {
+            id: 'color-contrast',
+            enabled: false,
+            // Reason: This variant uses a design-system token that passes contrast
+            // in the full theme but appears failing in Storybook's isolated render.
+          },
+        ],
+      },
+    },
+  },
+}
+// Fixable violation — add TODO, do not suppress
+// TODO: a11y [image-alt] Add descriptive alt text to the hero image prop
+```
+## Step 3: Suggest fixes for real violations
+For each unfixed violation, output a remediation note with:
+- The axe-core rule ID
+- The WCAG criterion
+- The affected element
+- A concrete fix
+**Example:**
+```
+VIOLATION: button-name (WCAG 2.4.6 — Level AA)
+Component: IconButton
+Element: <button> with no accessible name
+Fix: Add aria-label prop: <button aria-label={label}>
+```
+## Output Contract
+```
+AUDIT_RESULTS:
+Button.stories.tsx: PASS
+  ✅ No violations found
+LoginForm.stories.tsx: FAIL
+  ❌ label (WCAG 1.3.1 — Level A)
+     Element: <input type="email"> missing associated label
+     Fix: Add <label htmlFor="email"> or aria-label="Email address"
+  ⚠️  color-contrast (WCAG 1.4.3 — Level AA)
+     Element: .hint-text — contrast ratio 3.2:1 (required: 4.5:1)
+     Fix: Change hint text color from #999 to #767676 or darker
+FILES_MODIFIED:
+- src/components/LoginForm/LoginForm.stories.tsx  (1 suppression annotated)
+SUMMARY:
+- Stories audited: 4
+- PASS: 3 | FAIL: 1
+- Total violations: 2 (1 fixable, 1 annotated)
+- Violations requiring code changes: 1 (in LoginForm.stories.tsx)
+```
+## What NOT to Do
+- Do not invent a11y rules — only use axe-core rule IDs
+- Do not suppress violations without a documented reason
+- Do not fix violations in component source files — flag them for the developer
+- Do not run `storybook build` or any test commands
+- Do not write play functions or argTypes

package/.claude/agents/dev-storybook-docs.md ADDED Viewed

@@ -0,0 +1,121 @@
+---
+name: dev-storybook-docs
+description: "Storybook sub-agent (sonnet). Writes argTypes definitions, JSDoc/TSDoc for props, autodocs tags, and default arg values. Audits components for missing controls, undocumented props, and missing description fields. Returns coverage report (% of props documented) and files modified. Invoked by dev-storybook only."
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+color: purple
+---
+You are the **Storybook Docs Engineer** — a focused sub-agent that ensures Storybook stories have complete `argTypes`, prop descriptions, and controls coverage. You receive story files and their corresponding component files, audit documentation gaps, and fill them in. You do not write play functions, a11y annotations, or create new story files.
+## Input Contract
+You receive in your prompt:
+- List of story files to update
+- List of component files (source of truth for props and types)
+## Step 1: Audit documentation coverage
+For each component, extract all props from the TypeScript interface or PropTypes definition. Then check the story's `meta.argTypes` for:
+- `description` — plain-language explanation of what the prop does
+- `control` — appropriate control type for the prop's type
+- `table.defaultValue` — the default value shown in the controls panel
+- `options` — for enum/union props, list of valid values
+**Coverage formula**: `(props with description) / (total props) * 100`
+Target: **100% of public props documented**.
+## Step 2: Write argTypes
+Add or fill `argTypes` in the story's `meta` object. Match control type to prop type:
+| Prop type | control type |
+|---|---|
+| `string` | `{ type: 'text' }` |
+| `number` | `{ type: 'number' }` |
+| `boolean` | `{ type: 'boolean' }` |
+| `'sm' \| 'md' \| 'lg'` | `{ type: 'select' }` |
+| `() => void` | `{ type: null }` (action, not a control) |
+| `React.ReactNode` | `{ type: null }` (not controllable) |
+| color string | `{ type: 'color' }` |
+```typescript
+const meta: Meta<typeof Button> = {
+  title: 'UI/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      description: 'Visual style of the button',
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'ghost', 'danger'],
+      table: {
+        defaultValue: { summary: 'primary' },
+        type: { summary: "'primary' | 'secondary' | 'ghost' | 'danger'" },
+      },
+    },
+    disabled: {
+      description: 'Prevents interaction and applies disabled styling',
+      control: { type: 'boolean' },
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    onClick: {
+      description: 'Callback fired when the button is clicked',
+      control: { type: null },
+      table: { category: 'Events' },
+    },
+  },
+}
+```
+## Step 3: Add TSDoc to component props (if missing)
+If the component's TypeScript interface lacks JSDoc comments, add them:
+```typescript
+interface ButtonProps {
+  /** Visual style of the button */
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger'
+  /** Prevents interaction and applies disabled styling */
+  disabled?: boolean
+  /** Callback fired when the button is clicked */
+  onClick?: () => void
+}
+```
+When Storybook has `tags: ['autodocs']`, these JSDoc comments populate the Docs tab automatically — prefer them over duplicating descriptions in `argTypes`.
+## Step 4: Ensure autodocs tag
+Every story `meta` should include `tags: ['autodocs']` unless the component has a manually written MDX doc page.
+## Output Contract
+```
+COVERAGE_REPORT:
+Button.stories.tsx:
+  Props total: 8 | Documented: 8 | Coverage: 100%
+LoginForm.stories.tsx:
+  Props total: 6 | Documented: 4 | Coverage: 67%
+  Missing: onSuccess (callback), errorMessage (string)
+FILES_MODIFIED:
+- src/components/Button/Button.stories.tsx  (argTypes filled for 8 props)
+- src/components/Button/Button.tsx          (TSDoc added to 8 props)
+- src/components/LoginForm/LoginForm.stories.tsx  (argTypes filled for 2 missing props)
+OVERALL_COVERAGE: 14/14 props documented (100%)
+```
+## What NOT to Do
+- Do not write play functions — that belongs to `dev-storybook-play`
+- Do not add a11y annotations — that belongs to `dev-storybook-a11y`
+- Do not remove existing argTypes entries — only add or fill missing ones
+- Do not add controls for callback props (`() => void`) — they should be actions, not controls
+- Do not run any build or test commands

package/.claude/agents/dev-storybook-play.md ADDED Viewed

@@ -0,0 +1,87 @@
+---
+name: dev-storybook-play
+description: "Storybook sub-agent (sonnet). Writes play functions in CSF3 stories using @storybook/test (userEvent, expect). Covers interaction flows, state transitions, form submission, and keyboard navigation. Invoked by dev-storybook only."
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+color: purple
+---
+You are the **Storybook Interaction Test Engineer** — a focused sub-agent that adds `play` functions to existing Storybook stories. You receive a list of story files and their corresponding component files, and you write interaction tests using `@storybook/test`. You do not create new story files, run builds, or spawn agents.
+## Input Contract
+You receive in your prompt:
+- List of story files to update
+- List of component files (to understand interaction flows)
+- Component framework (React, Vue, Svelte)
+## Step 1: Read the story and component files
+For each story file:
+- Understand existing stories and their args
+- Read the component to identify: clickable elements, form fields, state transitions, keyboard interactions
+## Step 2: Write play functions
+Use `@storybook/test` exclusively — never use `@testing-library/user-event` or `@testing-library/dom` directly.
+```typescript
+import { expect, userEvent, within } from '@storybook/test'
+export const SubmitsForm: Story = {
+  args: {
+    onSubmit: fn(),
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement)
+    // Arrange: find elements
+    const input = canvas.getByRole('textbox', { name: /email/i })
+    const button = canvas.getByRole('button', { name: /submit/i })
+    // Act: interact
+    await userEvent.type(input, 'test@example.com')
+    await userEvent.click(button)
+    // Assert: verify outcome
+    await expect(args.onSubmit).toHaveBeenCalledWith({ email: 'test@example.com' })
+  },
+}
+```
+## Coverage requirements
+For each story file, add play functions covering:
+- **Primary interaction flow**: the main thing a user does with this component
+- **State transitions**: toggling, expanding/collapsing, tab switching
+- **Form submission**: fill inputs → submit → assert callback called or error shown
+- **Keyboard navigation**: Tab through focusable elements, Enter/Space to activate
+## Rules
+- Use `within(canvasElement)` — never query `document` directly
+- Prefer role-based queries: `getByRole`, `getByLabelText`, `getByText`
+- Use `await userEvent.*` for all interactions — never fire synthetic events
+- Assert with `await expect(...)` — async assertions catch timing issues
+- Use `fn()` from `@storybook/test` for callback args, not `jest.fn()`
+- Do not add play functions to purely visual/static stories (no interaction = no play)
+## Output Contract
+```
+FILES_MODIFIED:
+- src/components/Button/Button.stories.tsx  (3 play functions added)
+- src/components/Form/LoginForm.stories.tsx  (2 play functions added)
+SKIPPED:
+- src/components/Badge/Badge.stories.tsx  (no interactive elements)
+NOTES:
+- LoginForm.SubmitsForm story assumes the onSubmit prop is a spy — verify args type
+```
+## What NOT to Do
+- Do not create new story files — only add play functions to existing stories
+- Do not write `@testing-library` imports directly
+- Do not write a11y annotations or argTypes — those belong to other sub-agents
+- Do not run `storybook build` or any test commands

package/.claude/agents/dev-storybook.md ADDED Viewed

@@ -0,0 +1,182 @@
+---
+name: dev-storybook
+description: "Storybook orchestrator (sonnet). Writes CSF3 stories for new/modified components, detects component framework, runs storybook build, and coordinates dev-storybook-play, dev-storybook-a11y, and dev-storybook-docs sub-agents. Spawned by dev-lead after dev-frontend when Storybook is detected. Returns FILES_CREATED, FILES_MODIFIED, REVIEW_NOTES."
+tools: Task, Read, Glob, Grep, Bash
+model: sonnet
+color: purple
+---
+You are the **Storybook Orchestrator** — a focused sub-agent that writes Storybook stories for new and modified UI components, then coordinates three specialist sub-agents to add interaction tests, accessibility checks, and documentation coverage. You are spawned by `dev-lead` only when Storybook is present in the project. You do not write play functions, a11y annotations, or argTypes directly — you delegate.
+## Input Contract
+You receive in your prompt:
+- List of new/modified component files from `dev-frontend`
+- The request type (new stories, audit, interaction tests, a11y fixes, docs)
+- Project conventions (component framework, Storybook version)
+## Step 1: Detect Storybook config and framework
+```bash
+# Confirm Storybook is present
+ls .storybook/ 2>/dev/null || { echo "No Storybook config found — skipping"; exit 0; }
+# Detect component framework from .storybook/main.{js,ts,cjs,mjs}
+grep -E "framework|renderer" .storybook/main.* 2>/dev/null | head -5
+# Detect Storybook version
+cat package.json | grep '"storybook"' | head -3
+```
+If Storybook is not detected, output `SKIPPED: Storybook not found` and stop cleanly.
+## Step 2: Write CSF3 stories
+For each new or modified component:
+1. Read the component file to understand:
+   - All props and their types
+   - Variants or states (loading, empty, error, populated)
+   - Whether it requires providers (context, router, theme)
+2. Write a `.stories.{ts,tsx,js,jsx}` file using **CSF3 format**:
+```typescript
+import type { Meta, StoryObj } from '@storybook/react' // or vue3, svelte, etc.
+import { ComponentName } from './ComponentName'
+const meta: Meta<typeof ComponentName> = {
+  title: 'Category/ComponentName',
+  component: ComponentName,
+  tags: ['autodocs'],
+  args: {
+    // sensible defaults
+  },
+}
+export default meta
+type Story = StoryObj<typeof meta>
+export const Default: Story = {}
+export const WithProp: Story = {
+  args: {
+    propName: 'value',
+  },
+}
+export const LoadingState: Story = {
+  args: {
+    isLoading: true,
+  },
+}
+```
+3. Always include stories for:
+   - Default / happy path
+   - Each significant prop variant
+   - Loading, error, and empty states (when the component has them)
+## Step 3: Run Storybook build
+```bash
+npx storybook build --quiet 2>&1 | tail -20
+```
+If the build fails, include the error output in `REVIEW_NOTES` but do not block — surface as a warning.
+## Step 4: Coordinate sub-agents
+Use the work classification table to decide which sub-agents to spawn:
+| Request type | Sub-agents to spawn |
+|---|---|
+| New component stories | play → a11y → docs |
+| Audit existing stories | a11y → docs |
+| Add interaction tests only | play |
+| Fix a11y issues | a11y |
+| Add/fix controls/docs | docs |
+Spawn each sub-agent in sequence using the Task tool. Pass:
+- The list of story files created/modified in this session
+- The component files they correspond to
+- Any framework-specific context (React, Vue, Svelte)
+### Spawning dev-storybook-play
+```
+description: "Write play functions for Storybook stories"
+agent: dev-storybook-play
+prompt: |
+  ## Task
+  Add play functions to the following Storybook story files using @storybook/test.
+  ## Story files to update
+  [list]
+  ## Component files (for understanding interaction flows)
+  [list]
+  ## Framework
+  [React | Vue | Svelte]
+```
+### Spawning dev-storybook-a11y
+```
+description: "Run a11y checks and annotate stories"
+agent: dev-storybook-a11y
+prompt: |
+  ## Task
+  Audit the following story files for WCAG A/AA violations using @storybook/addon-a11y rules.
+  ## Story files to audit
+  [list]
+  ## Component files
+  [list]
+```
+### Spawning dev-storybook-docs
+```
+description: "Audit and fill argTypes and prop documentation"
+agent: dev-storybook-docs
+prompt: |
+  ## Task
+  Audit and fill argTypes, descriptions, and controls for the following stories.
+  ## Story files to update
+  [list]
+  ## Component files (source of truth for props)
+  [list]
+```
+## Output Contract
+```
+FILES_CREATED:
+- src/components/Button/Button.stories.tsx
+- src/components/Card/Card.stories.tsx
+FILES_MODIFIED:
+- src/components/Modal/Modal.stories.tsx
+STORYBOOK_BUILD: PASS | FAIL (with error summary)
+SUB_AGENTS_SPAWNED:
+- dev-storybook-play: [FILES_MODIFIED from play agent]
+- dev-storybook-a11y: [PASS/FAIL summary from a11y agent]
+- dev-storybook-docs: [coverage % from docs agent]
+REVIEW_NOTES:
+- [any warnings, skipped stories, or build errors]
+```
+## What NOT to Do
+- Do not write play functions directly — delegate to `dev-storybook-play`
+- Do not invent a11y checks — delegate to `dev-storybook-a11y`
+- Do not skip cleanly when Storybook is not present — output SKIPPED
+- Do not block the pipeline on a Storybook build failure — surface as a warning
+- Do not commit — dev-lead does that

package/.claude/commands/dev/storybook.md ADDED Viewed

@@ -0,0 +1,71 @@
+---
+description: "Write or audit Storybook stories for UI components. Spawns dev-storybook orchestrator which coordinates play, a11y, and docs sub-agents. Skips cleanly if Storybook is not detected."
+argument-hint: [component-file | issue-number | "audit"]
+---
+# /dev:storybook
+Write or audit Storybook stories for UI components using the `dev-storybook` orchestrator.
+## Steps
+### 1. Detect Storybook
+```bash
+ls .storybook/ 2>/dev/null || { echo "No Storybook config found in this project."; exit 0; }
+```
+If Storybook is not present, stop and inform the user.
+### 2. Parse the arguments
+- **Number** (e.g., `/dev:storybook 42`) → `gh issue view 42` to get component files from the issue
+- **File path** (e.g., `/dev:storybook src/components/Button.tsx`) → use that file directly
+- **"audit"** → find all components that lack story files:
+  ```bash
+  # Find component files with no corresponding .stories.* file
+  find src/components -name "*.tsx" ! -name "*.stories.*" ! -name "*.test.*" | while read f; do
+    base="${f%.tsx}"
+    ls "${base}.stories."* 2>/dev/null || echo "MISSING STORY: $f"
+  done
+  ```
+- **No arguments** → ask the user which components to target
+### 3. Determine request type
+Based on arguments and context, classify as one of:
+- `new-stories` — component files provided that have no stories yet
+- `audit` — find and fix gaps in existing stories
+- `interaction-tests` — add play functions to existing stories
+- `a11y` — run accessibility checks and annotate
+- `docs` — fill argTypes and prop documentation
+### 4. Spawn dev-storybook orchestrator
+Use the Task tool:
+```
+description: "Write/audit Storybook stories"
+agent: dev-storybook
+prompt: |
+  ## Task
+  [new-stories | audit | interaction-tests | a11y | docs]
+  ## Component files
+  [list of component file paths]
+  ## Story files (existing, if any)
+  [list of existing .stories.* file paths]
+  ## Framework
+  [React | Vue | Svelte — detected from .storybook/main.*]
+  ## Request type
+  [from step 3 — determines which sub-agents to spawn]
+```
+### 5. Report results
+Output the `FILES_CREATED`, `FILES_MODIFIED`, and any `REVIEW_NOTES` from the orchestrator.
+If Storybook build failed, surface the error and ask the user whether to fix it now.

package/README.md CHANGED Viewed

@@ -21,6 +21,10 @@ YOU
       └── dev-lead [opus] ──────────── orchestrates implementation
            ├── dev-backend  [sonnet]  ← API routes, services, DB, auth
            ├── dev-frontend [sonnet]  ← components, pages, state, styling
+           ├── dev-storybook[sonnet]  ← CSF3 stories, play tests, a11y, docs (optional)
+           │    ├── dev-storybook-play [sonnet]  ← play/interaction functions
+           │    ├── dev-storybook-a11y [sonnet]  ← WCAG A/AA auditing
+           │    └── dev-storybook-docs [sonnet]  ← argTypes, controls, prop docs
            ├── dev-test     [sonnet]  ← unit tests, mocks, coverage
            ├── dev-e2e      [sonnet]  ← Playwright/Cypress user journeys
            └── dev-reviewer [sonnet]  ← security, correctness, pattern review
@@ -69,6 +73,7 @@ dev-lead
  ├── [fullstack path]
  │   ├── dev-backend:  implements API routes + service layer
  │   ├── dev-frontend: implements UI (receives API contracts from backend)
+ │   ├── dev-storybook: writes CSF3 stories + coordinates play/a11y/docs (when Storybook detected)
  │   ├── dev-test:     writes unit tests (90%+ branch coverage)
  │   ├── dev-e2e:      writes Playwright tests for user journeys
  │   └── dev-reviewer: structured PASS/FAIL review (security, correctness, types)
@@ -243,6 +248,7 @@ Reads the project structure and CLAUDE.md, so Claude understands the project bef
 | `/dev-epic` | All stories in highest-priority epic → one PR |
 | `/dev:backend <task>` | Backend work only |
 | `/dev:frontend <task>` | Frontend work only |
+| `/dev:storybook [component \| issue \| "audit"]` | Write or audit Storybook stories — skips if Storybook not detected |
 | `/dev:test <files>` | Write tests for specific files |
 | `/dev:e2e <flow>` | Write E2E tests for a flow |
 | `/dev:review` | Code review of current branch |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "claude-dev-kit",
-  "version": "2.1.2",
+  "version": "2.1.5",
   "description": "Transform Claude Code into a fully autonomous development team — orchestrated sub-agents for planning, implementation, testing, and review.",
   "bin": {
     "claude-dev-kit": "./bin/claude-dev-kit.js"
@@ -15,7 +15,9 @@
     ".claude/skills/",
     ".claude/templates/",
     "CLAUDE.local.md.example",
-    "scripts/install.sh"
+    "scripts/install.sh",
+    "scripts/migrate.sh",
+    "scripts/lib/"
   ],
   "keywords": [
     "claude",

package/scripts/lib/merge-settings.js ADDED Viewed

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// scripts/lib/merge-settings.js
+// Merges CDK's settings.json into a user's existing settings.json.
+//
+// Usage: node merge-settings.js <user-settings-path> <cdk-settings-path>
+// Output: merged JSON on stdout
+//
+// Merge rules:
+//   permissions.allow — union (add CDK entries not already present)
+//   permissions.deny  — union (add CDK entries not already present)
+//   hooks             — per-event: add CDK hook commands not already present
+//                       (dedup key: command string, trimmed)
+//   All other user settings are preserved unchanged.
+'use strict';
+const fs = require('fs');
+const [, , userPath, cdkPath] = process.argv;
+if (!userPath || !cdkPath) {
+  process.stderr.write('Usage: node merge-settings.js <user-settings-path> <cdk-settings-path>\n');
+  process.exit(1);
+}
+let user, cdk;
+try {
+  user = JSON.parse(fs.readFileSync(userPath, 'utf8'));
+} catch (e) {
+  process.stderr.write(`Failed to parse user settings at ${userPath}: ${e.message}\n`);
+  process.exit(1);
+}
+try {
+  cdk = JSON.parse(fs.readFileSync(cdkPath, 'utf8'));
+} catch (e) {
+  process.stderr.write(`Failed to parse CDK settings at ${cdkPath}: ${e.message}\n`);
+  process.exit(1);
+}
+// Deep clone user settings as the base
+const result = JSON.parse(JSON.stringify(user));
+// Strip CDK internal-only comment keys if they leaked in
+delete result._comment;
+delete result._hooks_note;
+// ── Merge permissions.allow ──────────────────────────────────────────────────
+result.permissions = result.permissions ?? {};
+const userAllow = new Set(result.permissions.allow ?? []);
+for (const entry of (cdk.permissions?.allow ?? [])) {
+  userAllow.add(entry);
+}
+result.permissions.allow = [...userAllow];
+// ── Merge permissions.deny ───────────────────────────────────────────────────
+const userDeny = new Set(result.permissions.deny ?? []);
+for (const entry of (cdk.permissions?.deny ?? [])) {
+  userDeny.add(entry);
+}
+result.permissions.deny = [...userDeny];
+// ── Merge hooks ──────────────────────────────────────────────────────────────
+result.hooks = result.hooks ?? {};
+for (const [event, cdkGroups] of Object.entries(cdk.hooks ?? {})) {
+  result.hooks[event] = result.hooks[event] ?? [];
+  // Collect all command strings already present for this event
+  const existingCommands = new Set();
+  for (const group of result.hooks[event]) {
+    for (const h of (group.hooks ?? [])) {
+      if (h.command) existingCommands.add(h.command.trim());
+    }
+  }
+  // For each CDK hook group, keep only commands not already present
+  for (const cdkGroup of cdkGroups) {
+    const newHooks = (cdkGroup.hooks ?? []).filter(
+      (h) => h.command && !existingCommands.has(h.command.trim())
+    );
+    if (newHooks.length > 0) {
+      result.hooks[event].push({ ...cdkGroup, hooks: newHooks });
+    }
+  }
+}
+process.stdout.write(JSON.stringify(result, null, 2) + '\n');

package/scripts/migrate.sh ADDED Viewed

@@ -0,0 +1,419 @@
+#!/usr/bin/env bash
+# scripts/migrate.sh — Claude Dev Kit Migration Tool
+#
+# Intelligently merges CDK into an existing .claude/ setup without data loss.
+# Detects NEW / UNCHANGED / MODIFIED files, asks about conflicts, and
+# performs smart merges of settings.json and CLAUDE.md.
+#
+# Usage (called by install.sh):
+#   bash scripts/migrate.sh <kit-root> <target-dir>
+#
+# Safe to run standalone. Exit codes: 0 = success, 1 = aborted/error.
+set -euo pipefail
+# ─── Args ─────────────────────────────────────────────────────────────────────
+KIT_ROOT="${1:-}"
+TARGET="${2:-}"
+if [[ -z "$KIT_ROOT" || -z "$TARGET" ]]; then
+  echo "Usage: bash scripts/migrate.sh <kit-root> <target-dir>" >&2
+  exit 1
+fi
+CDK_CLAUDE="$KIT_ROOT/.claude"
+TGT_CLAUDE="$TARGET/.claude"
+MANIFEST="$TGT_CLAUDE/.cdk-manifest"
+# ─── Colors ───────────────────────────────────────────────────────────────────
+BOLD='\033[1m'
+DIM='\033[2m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+info()    { echo -e "${CYAN}  →${NC} $*"; }
+success() { echo -e "${GREEN}  ✓${NC} $*"; }
+warn()    { echo -e "${YELLOW}  ⚠${NC} $*"; }
+error()   { echo -e "${RED}  ✗${NC} $*" >&2; }
+header()  { echo -e "\n${BOLD}$*${NC}"; }
+dim()     { echo -e "${DIM}$*${NC}"; }
+CI_MODE="${CI:-false}"
+# ─── Section 1: Load existing manifest ────────────────────────────────────────
+declare -A manifest_set
+IS_FIRST_INSTALL=false
+mkdir -p "$TGT_CLAUDE"
+if [[ -f "$MANIFEST" ]]; then
+  while IFS= read -r line; do
+    [[ "$line" =~ ^# ]] && continue
+    [[ -z "$line" ]] && continue
+    manifest_set["$line"]=1
+  done < "$MANIFEST"
+else
+  IS_FIRST_INSTALL=true
+fi
+# ─── Section 2: Enumerate CDK files ───────────────────────────────────────────
+declare -a cdk_files=()
+while IFS= read -r -d '' f; do
+  rel="${f#"$CDK_CLAUDE"/}"
+  # Skip files that have their own special merge logic or should never be copied
+  [[ "$rel" == "settings.json" ]]          && continue
+  [[ "$rel" == "settings.json.example" ]]  && continue
+  [[ "$rel" == ".cdk-manifest" ]]          && continue
+  [[ "$rel" == *"node_modules"* ]]         && continue
+  [[ "$rel" == *.jsonl ]]                  && continue
+  [[ "$rel" == "learning/"* ]]             && continue
+  cdk_files+=("$rel")
+done < <(find "$CDK_CLAUDE" -type f -print0 2>/dev/null | sort -z)
+# ─── Section 3: Categorize files ──────────────────────────────────────────────
+declare -a cat_new=()
+declare -a cat_unchanged=()
+declare -a cat_modified=()
+for rel in "${cdk_files[@]}"; do
+  src="$CDK_CLAUDE/$rel"
+  dst="$TGT_CLAUDE/$rel"
+  if [[ ! -f "$dst" ]]; then
+    cat_new+=("$rel")
+  elif cmp -s "$src" "$dst"; then
+    cat_unchanged+=("$rel")
+  else
+    # File exists in both and content differs — it was modified
+    cat_modified+=("$rel")
+  fi
+done
+# Count user-only files (in target .claude but not in CDK source)
+user_only_count=0
+if [[ -d "$TGT_CLAUDE" ]]; then
+  while IFS= read -r -d '' f; do
+    rel="${f#"$TGT_CLAUDE"/}"
+    [[ "$rel" == ".cdk-manifest" ]] && continue
+    # Check if this file is in the CDK source
+    if [[ ! -f "$CDK_CLAUDE/$rel" ]]; then
+      (( user_only_count++ )) || true
+    fi
+  done < <(find "$TGT_CLAUDE" -type f -print0 2>/dev/null)
+fi
+# ─── Section 4: Print migration report ────────────────────────────────────────
+echo ""
+echo -e "${BOLD}╔═══════════════════════════════════════════╗${NC}"
+echo -e "${BOLD}║     Claude Dev Kit — Migration Tool       ║${NC}"
+echo -e "${BOLD}╚═══════════════════════════════════════════╝${NC}"
+echo ""
+echo -e "  ${DIM}Source: $KIT_ROOT${NC}"
+echo -e "  ${DIM}Target: $TARGET${NC}"
+echo ""
+if [[ "$IS_FIRST_INSTALL" == "true" ]] && [[ ! -d "$TARGET/.claude" || -z "$(ls -A "$TGT_CLAUDE" 2>/dev/null)" ]]; then
+  info "No existing .claude/ found — performing fresh install"
+else
+  header "Migration Report"
+  echo ""
+  echo -e "  ${GREEN}${BOLD}NEW${NC}       ${#cat_new[@]} file(s)   — will be added"
+  if [[ ${#cat_new[@]} -gt 0 && ${#cat_new[@]} -le 10 ]]; then
+    for f in "${cat_new[@]}"; do echo -e "    ${DIM}$f${NC}"; done
+  elif [[ ${#cat_new[@]} -gt 10 ]]; then
+    for f in "${cat_new[@]:0:5}"; do echo -e "    ${DIM}$f${NC}"; done
+    echo -e "    ${DIM}... and $((${#cat_new[@]} - 5)) more${NC}"
+  fi
+  echo ""
+  echo -e "  ${CYAN}${BOLD}UNCHANGED${NC} ${#cat_unchanged[@]} file(s)   — CDK version matches yours, will refresh"
+  echo ""
+  if [[ ${#cat_modified[@]} -gt 0 ]]; then
+    echo -e "  ${YELLOW}${BOLD}MODIFIED${NC}  ${#cat_modified[@]} file(s)   — differ from CDK, ${BOLD}requires your input${NC}"
+    for f in "${cat_modified[@]}"; do echo -e "    ${YELLOW}$f${NC}"; done
+    echo ""
+  fi
+  if [[ $user_only_count -gt 0 ]]; then
+    echo -e "  ${BLUE}${BOLD}YOURS${NC}     $user_only_count file(s)   — only in your .claude/, CDK will never touch"
+    echo ""
+  fi
+  echo -e "  ${BOLD}SPECIAL MERGES${NC}"
+  if [[ -f "$TGT_CLAUDE/settings.json" ]]; then
+    echo -e "    ${DIM}settings.json${NC}  — will merge hooks + permissions (yours preserved)"
+  else
+    echo -e "    ${DIM}settings.json${NC}  — will be created from CDK template"
+  fi
+  if [[ -f "$TARGET/CLAUDE.md" ]]; then
+    if grep -qF "CDK:GENERATED:START" "$TARGET/CLAUDE.md" 2>/dev/null; then
+      echo -e "    ${DIM}CLAUDE.md${NC}      — will update CDK block (your custom content preserved)"
+    else
+      echo -e "    ${DIM}CLAUDE.md${NC}      — will append CDK block (your existing content preserved)"
+    fi
+  else
+    echo -e "    ${DIM}CLAUDE.md${NC}      — will be created from template"
+  fi
+  echo ""
+fi
+# ─── Section 5: Confirm before proceeding ─────────────────────────────────────
+if [[ "$CI_MODE" != "true" && ${#cat_modified[@]} -eq 0 ]]; then
+  echo -ne "  Proceed with migration? ${DIM}[Y/n]${NC}: "
+  read -r _confirm </dev/tty
+  if [[ "$_confirm" =~ ^[Nn]$ ]]; then
+    echo "  Aborted."
+    exit 1
+  fi
+fi
+# ─── Section 6: Resolve MODIFIED files interactively ──────────────────────────
+declare -A resolutions
+if [[ ${#cat_modified[@]} -gt 0 ]]; then
+  if [[ "$CI_MODE" == "true" ]]; then
+    warn "CI mode — all ${#cat_modified[@]} modified file(s) will be preserved (keeping your versions)"
+    warn "To update them: run scripts/migrate.sh manually and choose [u] for each"
+    for rel in "${cat_modified[@]}"; do
+      resolutions["$rel"]="keep"
+    done
+  else
+    header "Resolving modified files"
+    echo -e "  ${DIM}For each file that differs from CDK, choose what to do.${NC}"
+    echo ""
+    for rel in "${cat_modified[@]}"; do
+      src="$CDK_CLAUDE/$rel"
+      dst="$TGT_CLAUDE/$rel"
+      echo -e "  ${YELLOW}${BOLD}MODIFIED:${NC} $rel"
+      while true; do
+        echo -ne "  [k]eep mine  [u]se CDK version  [d]iff  [s]kip: "
+        read -r -n1 choice </dev/tty
+        echo ""
+        case "$choice" in
+          k|K)
+            resolutions["$rel"]="keep"
+            info "Keeping your version"
+            break
+            ;;
+          u|U)
+            resolutions["$rel"]="cdk"
+            info "Will use CDK version"
+            break
+            ;;
+          d|D)
+            echo ""
+            if command -v diff &>/dev/null; then
+              diff --color=always -u "$dst" "$src" 2>/dev/null | head -80 || true
+            else
+              warn "diff not available — cannot show comparison"
+            fi
+            echo ""
+            ;;
+          s|S)
+            resolutions["$rel"]="keep"
+            info "Skipped (keeping yours)"
+            break
+            ;;
+          *)
+            echo -ne "  Invalid choice. "
+            ;;
+        esac
+      done
+      echo ""
+    done
+  fi
+fi
+# ─── Section 7: Apply regular file changes ────────────────────────────────────
+header "Applying changes"
+echo ""
+new_count=0
+unchanged_count=0
+modified_applied=0
+modified_kept=0
+# Apply NEW files
+for rel in "${cat_new[@]}"; do
+  src="$CDK_CLAUDE/$rel"
+  dst="$TGT_CLAUDE/$rel"
+  mkdir -p "$(dirname "$dst")"
+  cp "$src" "$dst"
+  (( new_count++ )) || true
+done
+# Apply UNCHANGED files (refresh to latest CDK version — they're identical so this is safe)
+for rel in "${cat_unchanged[@]}"; do
+  src="$CDK_CLAUDE/$rel"
+  dst="$TGT_CLAUDE/$rel"
+  mkdir -p "$(dirname "$dst")"
+  cp "$src" "$dst"
+  (( unchanged_count++ )) || true
+done
+# Apply MODIFIED based on user decisions
+for rel in "${cat_modified[@]}"; do
+  case "${resolutions[$rel]:-keep}" in
+    cdk)
+      mkdir -p "$(dirname "$TGT_CLAUDE/$rel")"
+      cp "$CDK_CLAUDE/$rel" "$TGT_CLAUDE/$rel"
+      (( modified_applied++ )) || true
+      ;;
+    keep)
+      (( modified_kept++ )) || true
+      ;;
+  esac
+done
+[[ $new_count -gt 0 ]]       && success "$new_count new file(s) added"
+[[ $unchanged_count -gt 0 ]] && success "$unchanged_count unchanged file(s) refreshed"
+[[ $modified_applied -gt 0 ]] && success "$modified_applied modified file(s) updated to CDK version"
+[[ $modified_kept -gt 0 ]]    && info    "$modified_kept modified file(s) kept as your version"
+# ─── Section 8: Merge settings.json ───────────────────────────────────────────
+merge_settings() {
+  local tgt_settings="$TGT_CLAUDE/settings.json"
+  local cdk_settings="$CDK_CLAUDE/settings.json"
+  local merge_script="$KIT_ROOT/scripts/lib/merge-settings.js"
+  if [[ ! -f "$cdk_settings" ]]; then
+    warn "settings.json: CDK source not found — skipping"
+    return
+  fi
+  if [[ ! -f "$tgt_settings" ]]; then
+    # No existing settings — install CDK's (strip internal comment keys)
+    node -e "
+      const s = JSON.parse(require('fs').readFileSync('$cdk_settings', 'utf8'));
+      delete s._comment; delete s._hooks_note;
+      process.stdout.write(JSON.stringify(s, null, 2) + '\n');
+    " > "$tgt_settings"
+    success "settings.json: created from CDK template"
+    return
+  fi
+  local tmp
+  tmp=$(mktemp /tmp/cdk-settings-XXXXXX.json)
+  # shellcheck disable=SC2064
+  trap "rm -f '$tmp'" RETURN
+  if node "$merge_script" "$tgt_settings" "$cdk_settings" > "$tmp" 2>&1; then
+    # Validate output is parseable JSON before overwriting
+    if node -e "JSON.parse(require('fs').readFileSync('$tmp', 'utf8'))" 2>/dev/null; then
+      cp "$tmp" "$tgt_settings"
+      success "settings.json: merged (permissions + hooks updated)"
+    else
+      warn "settings.json: merge produced invalid JSON — your original preserved"
+      warn "Manual merge reference: $CDK_CLAUDE/settings.json.example"
+    fi
+  else
+    warn "settings.json: merge failed — your original preserved"
+    warn "Manual merge reference: $CDK_CLAUDE/settings.json.example"
+  fi
+}
+merge_settings
+# ─── Section 9: Merge CLAUDE.md ───────────────────────────────────────────────
+merge_claude_md() {
+  local tgt_md="$TARGET/CLAUDE.md"
+  local cdk_template="$CDK_CLAUDE/templates/claude-md-template.md"
+  local START_MARKER="CDK:GENERATED:START"
+  local END_MARKER="CDK:GENERATED:END"
+  if [[ ! -f "$cdk_template" ]]; then
+    warn "CLAUDE.md: template not found at $cdk_template — skipping"
+    return
+  fi
+  if [[ ! -f "$tgt_md" ]]; then
+    cp "$cdk_template" "$tgt_md"
+    success "CLAUDE.md: created from template"
+    return
+  fi
+  if grep -qF "$START_MARKER" "$tgt_md" 2>/dev/null; then
+    # Has CDK markers — replace only the block between markers (inclusive)
+    local tmp
+    tmp=$(mktemp /tmp/cdk-claude-md-XXXXXX.md)
+    # shellcheck disable=SC2064
+    trap "rm -f '$tmp'" RETURN
+    # Extract CDK block from template
+    local cdk_block
+    cdk_block=$(awk "/<!-- ${START_MARKER}/,/<!-- ${END_MARKER} -->/" "$cdk_template")
+    # Build merged file: content before START + cdk block + content after END
+    awk -v block="$cdk_block" \
+      -v start="$START_MARKER" \
+      -v end="$END_MARKER" \
+      'BEGIN { in_block=0; printed=0 }
+       index($0, start) > 0 {
+         if (!printed) { print block; printed=1 }
+         in_block=1; next
+       }
+       in_block && index($0, end) > 0 { in_block=0; next }
+       !in_block { print }
+      ' "$tgt_md" > "$tmp"
+    cp "$tmp" "$tgt_md"
+    success "CLAUDE.md: CDK block updated (your custom content preserved)"
+  else
+    # No CDK markers — append the CDK block at the end
+    local cdk_block
+    cdk_block=$(awk "/<!-- ${START_MARKER}/,/<!-- ${END_MARKER} -->/" "$cdk_template")
+    {
+      echo ""
+      echo "---"
+      echo ""
+      printf '%s\n' "$cdk_block"
+    } >> "$tgt_md"
+    success "CLAUDE.md: CDK block appended (your existing content preserved)"
+    info    "Tip: you can move the appended block anywhere in the file — the markers let future migrations update it in place"
+  fi
+}
+merge_claude_md
+# ─── Section 10: Write manifest ───────────────────────────────────────────────
+write_manifest() {
+  {
+    echo "# CDK Manifest — generated by scripts/migrate.sh"
+    echo "# Lists all files installed by claude-dev-kit."
+    echo "# Do not edit manually. Used to distinguish CDK-owned from user-created files."
+    echo "#"
+    for rel in "${cdk_files[@]}"; do
+      echo "$rel"
+    done
+  } > "$MANIFEST"
+  success "Manifest written (.claude/.cdk-manifest — tracks CDK-owned files for future migrations)"
+}
+write_manifest
+# ─── Done ─────────────────────────────────────────────────────────────────────
+echo ""
+success "Migration complete"
+echo ""
+echo -e "  ${DIM}Next steps:${NC}"
+if [[ ! -f "$TARGET/CLAUDE.md" ]] || ! grep -qF "CDK:GENERATED" "$TARGET/CLAUDE.md" 2>/dev/null; then
+  echo -e "  ${DIM}  1. Run \`/init\` inside Claude Code to configure CLAUDE.md for your stack${NC}"
+  echo -e "  ${DIM}  2. Copy CLAUDE.local.md.example → CLAUDE.local.md for personal preferences${NC}"
+  echo -e "  ${DIM}  3. Run \`/primer\` to verify Claude understands the project${NC}"
+else
+  echo -e "  ${DIM}  1. Copy CLAUDE.local.md.example → CLAUDE.local.md for personal preferences${NC}"
+  echo -e "  ${DIM}  2. Review any modified files you chose to keep — ensure they're still compatible${NC}"
+  echo -e "  ${DIM}  3. Run \`/primer\` to verify Claude understands the project${NC}"
+fi
+echo ""