claude-dev-kit 2.1.0

package/.claude/commands/dev-epic.md

@@ -0,0 +1,121 @@
+# Dev Epic Pipeline
+
+Implement all stories in the next priority epic. One branch, one commit per story, one PR for the whole epic. Designed for the **ralph-loop** — each loop iteration implements one story via the `dev-lead` orchestrator.
+
+## Steps
+
+### 1. Detect state — are we mid-epic?
+
+```bash
+git branch --show-current
+```
+
+- If branch matches `epic/*` → **mid-epic, skip to step 3**
+- Otherwise → need to select the epic (step 2)
+
+### 2. Select the next priority epic (only when NOT mid-epic)
+
+```bash
+git checkout master && git pull origin master
+gh issue list --state open --limit 100 --json number,title,milestone | \
+  jq 'group_by(.milestone.title) | map({epic: .[0].milestone.title, lowest: map(.number) | min}) | sort_by(.lowest)'
+```
+
+Pick the milestone whose lowest issue number is smallest (highest priority).
+Create branch: `epic/<slugified-milestone-name>`
+
+```bash
+git checkout -b epic/<slug>
+```
+
+### 3. List stories for this epic
+
+```bash
+gh issue list --state open --milestone "<milestone-name>" --limit 50 --json number,title
+```
+
+Sort by issue number ascending.
+
+### 4. Find the next unimplemented story
+
+```bash
+git log --oneline
+```
+
+Extract all `(#NNN)` references already committed. Pick the **lowest-numbered** story NOT yet committed. If all stories committed → go to step 6 (create PR).
+
+### 5. Implement the story (one story per loop iteration)
+
+Read `CLAUDE.md` for validation commands, then spawn `dev-lead` via Task tool:
+
+```
+description: "Implement story #<number> for epic"
+agent: dev-lead
+prompt: |
+  ## Story #<number>: <title>
+
+  ### Acceptance Criteria
+  [from gh issue view output]
+
+  ## PRP
+  [content of PRPs/<slug>.md if it exists, otherwise "research the codebase"]
+
+  ## Branch
+  epic/<slug> (already checked out)
+
+  ## Validation Commands
+  - Lint:  [from CLAUDE.md]
+  - Test:  [from CLAUDE.md]
+  - E2E:   [from CLAUDE.md or "none"]
+  - Build: [from CLAUDE.md]
+
+  ## Key Conventions
+  [from CLAUDE.md]
+
+  ## Important
+  Do NOT create a PR. Do NOT push. Implement, validate all gates, then commit only:
+    git add <feature files only>
+    git commit -m "feat: <description> (#<story-number>)"
+
+  Return: FILES_CREATED, FILES_MODIFIED, GATE_RESULTS, COMMIT_HASH
+```
+
+After dev-lead returns with successful gates and commit hash, the story is done.
+**The ralph loop will re-invoke this command for the next story.**
+
+### 6. Create the epic PR (only when all stories committed)
+
+```bash
+git push -u origin epic/<slug>
+gh pr create \
+  --title "epic: <milestone name>" \
+  --body "$(cat <<'EOF'
+## Epic: <milestone name>
+
+Closes #NNN
+Closes #NNN
+[one Closes per story]
+
+## Summary
+[brief description of what the epic delivers]
+
+## Stories Implemented
+| # | Title | Size |
+|---|-------|------|
+[table from story list]
+
+🤖 Generated with Claude Dev Kit
+EOF
+)"
+```
+
+Output the PR URL, then output exactly:
+```
+epic pr created
+```
+
+## Important
+- **One branch per epic, one commit per story, one PR per epic**
+- Do NOT commit `.claude/`, `.env`, or settings files
+- If a story depends on another story in the same epic — implement anyway (the branch satisfies the dependency)
+- Never create a per-story PR

package/.claude/commands/dev-issue.md

@@ -0,0 +1,79 @@
+# Dev Issue Pipeline
+
+Implement a GitHub issue end-to-end using the `dev-lead` orchestrator. This command is equivalent to `/dev` and delegates all work to specialist sub-agents with clean context windows.
+
+## Arguments
+- `$ARGUMENTS` — GitHub issue number (optional, defaults to next open issue)
+
+## Steps
+
+### 1. Identify the issue
+If no issue number: `gh issue list --state open --limit 10 --json number,title` → pick the lowest-numbered non-epic issue.
+
+```bash
+gh issue view <number>
+```
+
+### 2. Check for PRP
+```bash
+ls PRPs/ 2>/dev/null
+```
+Read PRP if a matching slug file exists.
+
+### 3. Create branch
+```bash
+git checkout master && git pull origin master
+git checkout -b feature/#<number>-<slugified-title>
+```
+
+### 4. Read CLAUDE.md
+Extract: lint command, test command, E2E command, build command, key conventions.
+
+### 5. Spawn dev-lead via Task tool
+
+```
+description: "Implement issue #<number>"
+agent: dev-lead
+prompt: |
+  ## Issue #<number>: <title>
+
+  ### Acceptance Criteria
+  [extracted from issue body]
+
+  ### Definition of Done
+  [extracted from issue body]
+
+  ## PRP
+  [full PRP content, or "none — research the codebase"]
+
+  ## Branch
+  feature/#<number>-<slugified-title>
+
+  ## Validation Commands
+  - Lint:  [LINT_CMD from CLAUDE.md]
+  - Test:  [TEST_CMD from CLAUDE.md]
+  - E2E:   [E2E_CMD from CLAUDE.md, or "none"]
+  - Build: [BUILD_CMD from CLAUDE.md]
+
+  ## Key Conventions
+  [3-5 bullet points from CLAUDE.md — patterns, naming, file limits]
+
+  Classify the work (backend/frontend/fullstack), spawn appropriate sub-agents,
+  run all validation gates, return FILES_CREATED, FILES_MODIFIED, GATE_RESULTS.
+```
+
+### 6. Ship
+After dev-lead reports all gates passing:
+```bash
+git push -u origin feature/#<number>-<slugified-title>
+gh pr create \
+  --title "feat: <title> (#<number>)" \
+  --body "Closes #<number>\n\n[summary from dev-lead]\n\n🤖 Generated with Claude Dev Kit"
+```
+
+Output the PR URL.
+
+## Important
+- Never commit `.claude/`, `.env`, or settings files
+- Do not push if any validation gate failed
+- One branch per issue, one PR per issue

package/.claude/commands/dev.md

@@ -0,0 +1,134 @@
+---
+description: "Run the dev-lead orchestrator for a single GitHub issue. Reads the issue, classifies the work, spawns engineering sub-agents, validates all gates, and ships a PR. The fully automated dev pipeline."
+argument-hint: [issue-number]
+---
+
+# /dev — Dev Lead Pipeline
+
+Implement a GitHub issue end-to-end using the `dev-lead` orchestrator. Claude spawns the right specialist sub-agents with narrow context, runs all 5 validation gates, and ships.
+
+## Steps
+
+### 1. Identify the issue
+
+If `$ARGUMENTS` is empty:
+```bash
+gh issue list --state open --limit 10 --json number,title,labels
+```
+Pick the lowest-numbered issue that is not an epic.
+
+Read the issue:
+```bash
+gh issue view <number>
+```
+
+If the `gh` command returns an error containing "API rate limit", stop and inform the user:
+> GitHub API rate limit reached. Wait ~60 minutes or check your token scopes at https://github.com/settings/tokens
+
+### 2. Check for existing PRP
+```bash
+ls PRPs/ 2>/dev/null
+```
+If a PRP file matches the issue slug:
+- Read it — pass to dev-lead as context
+- Verify it is non-empty before using it
+
+### 3. Detect default branch and create feature branch
+```bash
+# Detect the default branch (main, master, or whatever the repo uses)
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+# Fallback chain: if the above fails, try common names
+if [ -z "$DEFAULT_BRANCH" ]; then
+  git fetch origin 2>/dev/null || true
+  DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+fi
+if [ -z "$DEFAULT_BRANCH" ]; then
+  DEFAULT_BRANCH=$(git branch -r | grep -E '(main|master)' | head -1 | sed 's/.*origin\///' | tr -d ' ')
+fi
+if [ -z "$DEFAULT_BRANCH" ]; then
+  DEFAULT_BRANCH="main"
+fi
+
+git checkout "$DEFAULT_BRANCH" && git pull origin "$DEFAULT_BRANCH"
+git checkout -b feature/#<number>-<slugified-title>
+```
+
+### 4. Verify CLAUDE.md exists
+```bash
+[ -f CLAUDE.md ] || echo "WARNING: CLAUDE.md not found. Run /init first to configure agents for this stack."
+```
+
+### 5. Read CLAUDE.md for project conventions
+Extract: stack, lint command, test command, build command, key patterns.
+
+### 6. Spawn dev-lead
+
+Use the Task tool:
+```
+description: "Implement issue #<number>"
+agent: dev-lead
+prompt: |
+  ## Issue #<number>: <title>
+
+  ### Acceptance Criteria
+  [from issue body]
+
+  ### Definition of Done
+  [from issue body]
+
+  ## PRP
+  [full PRP content if available, otherwise "none"]
+
+  ## Branch
+  feature/#<number>-<slugified-title>
+
+  ## Project Validation Commands (from CLAUDE.md)
+  - Lint: [LINT_CMD]
+  - Test: [TEST_CMD]
+  - E2E: [E2E_CMD]
+  - Build: [BUILD_CMD]
+
+  ## Key Conventions
+  [2-5 bullet points from CLAUDE.md — patterns, naming, file limits]
+
+  ## Instruction
+  Implement this issue fully. Classify backend/frontend/fullstack work.
+  Spawn the appropriate engineering sub-agents with narrow context.
+  Run all validation gates. Return FILES_CREATED, FILES_MODIFIED, and GATE_RESULTS.
+```
+
+### 7. Pre-push safety check
+
+Before pushing, scan for accidental secrets or sensitive files in the diff:
+```bash
+# Warn if any staged file looks like a secrets file
+git diff "$DEFAULT_BRANCH"..HEAD --name-only | grep -iE '\.env$|\.env\.|\.key$|\.pem$|credentials|secrets' \
+  && echo "WARNING: Sensitive filename detected in diff — review before pushing" || true
+
+# Warn if diff contains likely secret values
+git diff "$DEFAULT_BRANCH"..HEAD | grep -iE '(secret|api_key|private_key|password)\s*[:=]\s*["\x27]?[A-Za-z0-9+/]{16,}' \
+  && echo "WARNING: Possible secret value detected in diff — review before pushing" || true
+```
+
+If warnings appear, surface them to the user and ask for confirmation before proceeding.
+
+### 8. Ship after dev-lead confirms success
+
+```bash
+git push -u origin feature/#<number>-<slugified-title>
+gh pr create \
+  --title "feat: <issue-title> (#<number>)" \
+  --body "Closes #<number>
+
+## Changes
+[summary from dev-lead]
+
+🤖 Generated with Claude Dev Kit"
+```
+
+Output the PR URL.
+
+## Important
+- Do not push if dev-lead reports any validation gate failure
+- Do not commit `.claude/`, `.env`, or settings files
+- Do not proceed if the pre-push safety check flags secrets without user confirmation

package/.claude/commands/execute-prp.md

@@ -0,0 +1,113 @@
+# Execute BASE PRP
+
+Implement a feature using using the PRP file.
+
+## PRP File: $ARGUMENTS
+
+## Execution Process
+
+1. **Load PRP**
+   - Read the specified PRP file
+   - Understand all context and requirements
+   - Follow all instructions in the PRP and extend the research if needed
+   - Ensure you have all needed context to implement the PRP fully
+   - Do more web searches and codebase exploration as needed
+
+2. **ULTRATHINK**
+   - Think hard before you execute the plan. Create a comprehensive plan addressing all requirements.
+   - Break down complex tasks into smaller, manageable steps using your todos tools.
+   - Use the TodoWrite tool to create and track your implementation plan.
+   - Identify implementation patterns from existing code to follow.
+
+3. **Execute the plan**
+   - Execute the PRP
+   - Implement all the code
+   - Follow performance best practices (see Performance section below)
+
+4. **Unit Testing**
+   - Write unit tests for ALL new logic and functions
+   - Ensure comprehensive coverage of edge cases and error conditions
+   - Run unit tests: `bun test` or appropriate test command
+   - Fix any failing tests
+   - Re-run until all unit tests pass
+
+5. **E2E Testing**
+   - Create E2E tests for new user-facing features and flows
+   - Test critical paths and integration points
+   - Run E2E tests: `bun run test:e2e` or appropriate E2E command
+   - Fix any failing E2E tests
+   - Re-run until all E2E tests pass
+
+6. **Storybook**
+   - Create or update Storybook stories for all new/modified UI components
+   - Include stories for different component states (default, loading, error, empty, etc.)
+   - Add stories for different variants and prop combinations
+   - Run Storybook: `bun run storybook` to verify stories render correctly
+   - Fix any rendering issues or warnings
+   - Ensure stories are documented with proper controls and descriptions
+
+7. **Validate**
+   - Run each validation command
+   - Run full test suite (unit + E2E)
+   - Fix any failures
+   - Re-run until all pass
+
+8. **Performance Audit**
+   - Run Lighthouse audit: `bun run build && npx lighthouse http://localhost:3000 --view`
+   - Check bundle size impact: `bun run build` and review output sizes
+   - Verify no performance regressions in Core Web Vitals (LCP, FID, CLS)
+   - Review and optimize any new images (use next/image, proper sizing, lazy loading)
+   - Check for unnecessary re-renders in React components
+   - Ensure proper code splitting and lazy loading for new routes/components
+   - Verify API calls are optimized (pagination, caching, debouncing where appropriate)
+   - Run `bun run analyze` if available to check bundle composition
+
+9. **Complete**
+   - Ensure all checklist items done
+   - Verify all unit tests pass
+   - Verify all E2E tests pass
+   - Verify all Storybook stories render correctly
+   - Verify performance audit passed with no regressions
+   - Run final validation suite
+   - Report completion status with test coverage summary
+   - Read the PRP again to ensure you have implemented everything
+
+10. **Reference the PRP**
+    - You can always reference the PRP again if needed
+
+Note: If validation fails, use error patterns in PRP to fix and retry.
+
+---
+
+## Performance Best Practices
+
+Always consider these during implementation:
+
+### Bundle Size
+- Use dynamic imports (`next/dynamic`) for heavy components not needed on initial load
+- Avoid importing entire libraries when only specific functions are needed
+- Tree-shake unused code by using named imports
+
+### Rendering
+- Memoize expensive computations with `useMemo`
+- Prevent unnecessary re-renders with `React.memo` and `useCallback`
+- Use virtualization for long lists (react-window, react-virtualized)
+- Avoid inline function definitions in render where possible
+
+### Images & Media
+- Always use `next/image` for automatic optimization
+- Specify width and height to prevent layout shifts
+- Use appropriate formats (WebP, AVIF) and sizes
+- Implement lazy loading for below-the-fold images
+
+### Data Fetching
+- Implement proper caching strategies (SWR, React Query, or Next.js caching)
+- Use pagination or infinite scroll for large datasets
+- Debounce search inputs and frequent API calls
+- Prefetch data for anticipated navigation
+
+### Mobile Performance
+- Test on real devices or throttled connections
+- Minimize JavaScript execution on mobile
+- Ensure touch targets are appropriately sized
+- Consider reduced motion preferences

package/.claude/commands/fix-github-issue.md

@@ -0,0 +1,14 @@
+Please analyze and fix the GitHub issue: $ARGUMENTS.
+
+Follow these steps:
+
+1. Use `gh issue view` to get the issue details
+2. Understand the problem described in the issue
+3. Search the codebase for relevant files
+4. Implement the necessary changes to fix the issue
+5. Write and run tests to verify the fix
+6. Ensure code passes linting and type checking
+7. Create a descriptive commit message
+8. Push and create a PR
+
+Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

package/.claude/commands/generate-prp.md

@@ -0,0 +1,73 @@
+# Create PRP
+
+## Feature file: $ARGUMENTS
+
+Generate a complete PRP for general feature implementation with thorough research. Ensure context is passed to the AI agent to enable self-validation and iterative refinement. Read the feature file first to understand what needs to be created, how the examples provided help, and any other considerations.
+
+The AI agent only gets the context you are appending to the PRP and training data. Assuma the AI agent has access to the codebase and the same knowledge cutoff as you, so its important that your research findings are included or referenced in the PRP. The Agent has Websearch capabilities, so pass urls to documentation and examples.
+
+## Research Process
+
+1. **Codebase Analysis**
+   - Search for similar features/patterns in the codebase
+   - Identify files to reference in PRP
+   - Note existing conventions to follow
+   - Check test patterns for validation approach
+
+2. **External Research**
+   - Search for similar features/patterns online
+   - Library documentation (include specific URLs)
+   - Implementation examples (GitHub/StackOverflow/blogs)
+   - Best practices and common pitfalls
+
+3. **User Clarification** (if needed)
+   - Specific patterns to mirror and where to find them?
+   - Integration requirements and where to find them?
+
+## PRP Generation
+
+Using PRPs/templates/prp_base.md as template:
+
+### Critical Context to Include and pass to the AI agent as part of the PRP
+- **Documentation**: URLs with specific sections
+- **Code Examples**: Real snippets from codebase
+- **Gotchas**: Library quirks, version issues
+- **Patterns**: Existing approaches to follow
+
+### Implementation Blueprint
+- Start with pseudocode showing approach
+- Reference real files for patterns
+- Include error handling strategy
+- list tasks to be completed to fullfill the PRP in the order they should be completed
+
+
+### Validation Gates (Must be Executable) eg for python
+```bash
+# Syntax/Style
+cd frontend/ && yarn lint
+
+# Unit Tests
+yarn test:frontend:coverage 
+
+# Storybook Testing 
+yarn test:storybook
+
+```
+
+*** CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP ***
+
+*** ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH THEN START WRITING THE PRP ***
+
+## Output
+Save as: `PRPs/{feature-name}.md`
+
+## Quality Checklist
+- [ ] All necessary context included
+- [ ] Validation gates are executable by AI
+- [ ] References existing patterns
+- [ ] Clear implementation path
+- [ ] Error handling documented
+
+Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using claude codes)
+
+Remember: The goal is one-pass implementation success through comprehensive context.

package/.claude/commands/git/status.md

@@ -0,0 +1,14 @@
+---
+description: Understand the current state of the git repository
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git branch:*)
+---
+
+# Git Status
+
+Run the `Commands` and summarize the current state of the git repository.
+
+## Commands
+
+- Current Status: !`git status`
+- Current diff: !`git diff HEAD origin/main`
+- Current branch: !`git branch --show-current`

package/.claude/commands/haiku.md

@@ -0,0 +1,13 @@
+---
+description: Run a task in a fresh Haiku sub-context and post the result back here.
+---
+Use the **@agents/haiku-executor.md** subagent to perform this task:
+
+$ARGUMENTS
+
+Then return to this Sonnet thread with:
+- A short summary of what you did
+- The final answer or artifact (code blocks, diffs, or file paths)
+- Any follow-ups or next steps
+
+If tools are needed, invoke them within the haiku-executor subagent.