ai-development-framework 0.1.0

package/.claude/commands/plan-feature.md

@@ -0,0 +1,100 @@
+# /plan-feature — Feature Implementation Planner
+
+Creates a detailed implementation plan for a feature. The plan must pass the "no prior knowledge" test — an engineer unfamiliar with the codebase can implement using only the plan.
+
+## Arguments
+
+- `$ARGUMENTS` — feature description OR GitHub issue number (e.g., `#42`)
+
+## Process
+
+### Phase 1: Feature Understanding
+
+1. If an issue number is provided, read it: `gh issue view <number>`
+2. If a description is provided, clarify:
+   - What user-facing behavior should change?
+   - What are the acceptance criteria?
+   - Is this S/M/L/XL scope?
+3. For L/XL features, invoke brainstorming skill first
+4. Write user stories in "As a [user], I want [action] so that [benefit]" format
+
+### Phase 2: Codebase Intelligence (Parallel Sub-Agents)
+
+Launch 2-3 parallel sub-agents for speed:
+
+**Agent 1 — Structure and Patterns:**
+- Run `/prime` if not already primed
+- Glob for files related to the feature
+- Identify existing patterns (how similar features are built)
+- Map the directory structure for relevant areas
+
+**Agent 2 — Dependencies and Integration:**
+- architect-agent RETRIEVE for relevant domains
+- architect-agent IMPACT to understand what this change affects
+- Identify integration points with other modules
+- Check for shared utilities, types, or components to reuse
+
+**Agent 3 — Testing and Validation:**
+- Find existing test patterns for similar features
+- Identify what test infrastructure exists
+- Note validation commands (lint, type-check, test runners)
+
+### Phase 3: External Research
+
+- Use context7 MCP to verify framework APIs you plan to use
+- Check library documentation for any unfamiliar APIs
+- Note any dependencies that need to be installed
+
+### Phase 4: Strategic Thinking
+
+Before writing the plan, think through:
+- Does this fit the existing architecture? If not, is refactoring needed first?
+- What are the edge cases? (empty states, error states, concurrent access)
+- Security implications? (input validation, auth checks, data exposure)
+- Performance concerns? (N+1 queries, large payloads, unnecessary re-renders)
+- What could go wrong during implementation?
+
+### Phase 5: Plan Generation
+
+Read `.claude/references/plan-template.md` and generate a complete plan.
+
+Requirements for every plan:
+- Exact file paths for every file to create or modify
+- Complete code in every step (no placeholders)
+- Exact terminal commands with expected output for every verification step
+- TDD: tests before implementation in every task
+- Conventional commit after every task
+- GOTCHA warnings for known pitfalls
+- Confidence score (1-10) for one-pass success
+
+### Phase 6: GitHub Issue
+
+If no issue exists for this feature:
+```bash
+gh issue create --title "[type]: description" --body "..." --label "feat,size:M"
+```
+
+If issue exists, add a comment linking to the plan:
+```bash
+gh issue comment <number> --body "Implementation plan: docs/plans/<plan-file>.md"
+```
+
+### Phase 7: Save and Offer Execution
+
+Save to `docs/plans/<kebab-case-feature-name>.md`
+
+Commit:
+```bash
+git add docs/plans/<plan-file>.md
+git commit -m "docs: add implementation plan for <feature>"
+```
+
+Then offer:
+
+> **Plan saved. Ready to implement?**
+>
+> For complex features (context reset recommended):
+> Start a new session, run `/prime`, then `/execute docs/plans/<plan-file>.md`
+>
+> For simpler features (stay in session):
+> Run `/execute docs/plans/<plan-file>.md`

package/.claude/commands/plan-project.md

@@ -0,0 +1,110 @@
+# /plan-project — PRD to GitHub Issues Decomposer
+
+Decomposes a PRD into GitHub milestones and issues. This bridges the gap between project vision and actionable work items.
+
+## Arguments
+
+- `$ARGUMENTS` — optional: path to PRD file (default: `docs/plans/PRD.md`)
+
+## Prerequisites
+
+- A PRD must exist (run `/create-prd` first if it doesn't)
+- GitHub CLI (`gh`) must be authenticated
+- Repository must have a GitHub remote
+
+## Process
+
+### Phase 1: Parse PRD
+
+1. Read the PRD file
+2. Identify the implementation phases — each becomes a **GitHub milestone**
+3. Within each phase, identify discrete features — each becomes a **GitHub issue**
+
+### Phase 2: Decompose into Issues
+
+For each feature/task identified:
+
+1. Write issue title: `[type]: brief description`
+2. Write issue body using `.claude/references/issue-template.md` format:
+   - Description (what and why)
+   - Acceptance criteria (testable checkboxes)
+   - Technical notes (files to modify, patterns to follow)
+   - Size estimate (S/M/L/XL)
+3. Assign labels: type (`feat`/`fix`/`chore`), priority, size
+4. Map dependencies: which issues block which
+
+### Phase 3: Determine Order
+
+1. Build dependency graph
+2. Identify critical path (longest chain of blocking dependencies)
+3. Identify parallelizable work (independent issues that can be worked simultaneously)
+4. Order issues by: dependencies first, then critical path, then highest value, then smallest size
+
+### Phase 4: Present for Review
+
+Present the full breakdown to the user:
+
+```
+## Milestone 1: [Phase Name]
+
+### Issue 1: [feat: description] (Size: M, Priority: High)
+- Acceptance criteria: ...
+- Depends on: nothing
+- Blocks: Issue 2, Issue 3
+
+### Issue 2: [feat: description] (Size: L, Priority: High)
+- Acceptance criteria: ...
+- Depends on: Issue 1
+- Blocks: Issue 5
+```
+
+Ask: "Does this breakdown look right? Any issues to add, remove, or resize?"
+
+### Phase 5: Create in GitHub
+
+After user approval, create milestones and issues using `gh` CLI:
+
+```bash
+# Create milestones
+gh api repos/{owner}/{repo}/milestones -f title="Phase 1: [Name]" -f description="[Description]"
+
+# Create issues with labels and milestone
+gh issue create --title "[type]: description" --body "..." --label "feat,priority:high,size:M" --milestone "Phase 1: [Name]"
+```
+
+For issues with dependencies, add a "Blocked by #N" line in the issue body.
+
+### Phase 6: Generate Roadmap
+
+Save a roadmap file to `docs/plans/roadmap.md`:
+
+```markdown
+# Project Roadmap
+
+Generated from PRD on YYYY-MM-DD
+
+## Milestone 1: [Phase Name]
+- [ ] #1 — [title] (Size: M)
+- [ ] #2 — [title] (Size: L) — blocked by #1
+
+## Critical Path
+#1 → #2 → #4 → #7 → #9
+
+## Parallel Tracks
+Track A: #1 → #2 → #4
+Track B: #1 → #3 → #5
+```
+
+Commit:
+```bash
+git add docs/plans/roadmap.md
+git commit -m "docs: add project roadmap with GitHub issues"
+```
+
+## Re-running
+
+When the PRD is updated, run `/plan-project` again. It will:
+1. Read existing GitHub issues
+2. Diff against updated PRD
+3. Suggest: new issues to create, existing issues to update, obsolete issues to close
+4. Present changes for approval before executing

package/.claude/commands/prime.md

@@ -0,0 +1,71 @@
+# /prime — Context Loader
+
+Load the full codebase context into the current session. Run at the start of any session, after a context reset, or when switching tasks.
+
+## Process
+
+Run these in parallel for speed:
+
+### 1. Project Structure
+```bash
+git ls-files | head -200
+```
+```bash
+tree -L 3 -I 'node_modules|.next|dist|build|.git|__pycache__|.expo' --dirsfirst
+```
+
+### 2. Project Documentation
+Read these files if they exist:
+- `CLAUDE.md` (project root)
+- `README.md`
+- `docs/plans/PRD.md` (or latest PRD)
+- Any plan file matching the current branch name
+
+### 3. Recent History
+```bash
+git log --oneline -10
+```
+```bash
+git status --short
+```
+```bash
+git branch --show-current
+```
+
+### 4. Active Context
+- If on a feature branch, extract the issue number from the branch name
+- If issue number found: `gh issue view <number>`
+- Check for existing plan: look for files in `docs/plans/` or `docs/superpowers/plans/` matching branch name
+
+### 5. Configuration
+- Read `.claude/agents/architect-agent/index.md` (knowledge base TOC)
+- Read `.claude/agents/tester-agent/test-patterns.md` (page inventory)
+- Check `package.json` or equivalent for available scripts/commands
+
+## Output Format
+
+Present a structured summary:
+
+```
+=== Project Context ===
+
+Project: [name from package.json/CLAUDE.md]
+Branch: [current branch]
+Issue: [linked issue if found, or "none"]
+Plan: [active plan file if found, or "none"]
+
+Structure: [key directories and their purposes]
+
+Recent Activity:
+[last 5 commits, one line each]
+
+Uncommitted Changes:
+[summary of staged/unstaged changes]
+
+Available Commands:
+[dev, test, build commands from package.json]
+
+Knowledge Base: [N domains documented in architect-agent]
+
+=== Ready. Run /start to begin or specify a command. ===
+```

package/.claude/commands/setup.md

@@ -0,0 +1,81 @@
+# /setup — Framework Health Check
+
+Checks what external plugins, skills, and MCP servers are installed and reports any gaps.
+
+## Process
+
+### Step 1: Check Plugins
+
+Verify each required plugin is installed. Present results as a checklist.
+
+**Core Workflow (required):**
+
+| Plugin | Install Command |
+|--------|----------------|
+| superpowers | `claude plugin install superpowers` |
+| feature-dev | `claude plugin install feature-dev` |
+| code-review | `claude plugin install code-review` |
+| commit-commands | `claude plugin install commit-commands` |
+| claude-md-management | `claude plugin install claude-md-management` |
+| security-guidance | `claude plugin install security-guidance` |
+| skill-creator | `claude plugin install skill-creator` |
+
+**Framework Support (recommended):**
+
+| Plugin | Install Command |
+|--------|----------------|
+| firecrawl | `claude plugin install firecrawl` |
+| frontend-design | `claude plugin install frontend-design` |
+| claude-code-setup | `claude plugin install claude-code-setup` |
+| agent-sdk-dev | `claude plugin install agent-sdk-dev` |
+
+**Stack-Specific (install what applies):**
+
+| Plugin | When Needed | Install Command |
+|--------|------------|----------------|
+| context7 | Any framework/library project | `claude plugin install context7` |
+| supabase | Supabase projects | `claude plugin install supabase` |
+| typescript-lsp | TypeScript projects | `claude plugin install typescript-lsp` |
+| expo-app-design | Expo/React Native projects | `claude plugin install expo-app-design --marketplace expo-plugins` |
+
+### Step 2: Check MCP Servers
+
+Verify project-level MCP server configuration if applicable:
+- shadcn — for shadcn/ui component projects
+- context7 — for documentation lookup
+- supabase — for database operations
+- mobile-mcp — for mobile testing
+
+### Step 3: Check Framework Files
+
+Verify .claude/ structure is complete:
+- commands/ (10 files)
+- agents/ (4 agents + template)
+- rules/ (6 rules + template)
+- references/ (5 templates)
+- hooks/ (5 scripts)
+- settings.local.json
+
+### Step 4: Report
+
+```
+=== Framework Health Check ===
+
+Plugins:
+  [check] superpowers
+  [check] feature-dev
+  [missing] firecrawl — run: claude plugin install firecrawl
+
+MCP Servers:
+  [check] context7
+  [missing] shadcn — add to .mcp.json if using shadcn/ui
+
+Framework Files:
+  [check] .claude/commands/ (10 commands)
+  [check] .claude/agents/ (4 agents)
+  [check] .claude/rules/ (6 rules)
+  [check] .claude/references/ (5 templates)
+  [check] .claude/hooks/ (5 hooks)
+
+Status: Ready (install missing items above for full functionality)
+```

package/.claude/commands/ship.md

@@ -0,0 +1,73 @@
+# /ship — Commit, Push, and Create PR
+
+Handles the full shipping workflow: staging, committing, pushing, and creating a pull request.
+
+## Process
+
+### Step 1: Pre-flight Check
+
+1. Verify all tests pass: `npm test` (or detected test command)
+2. Verify no uncommitted changes that shouldn't be included
+3. Check current branch is not main/master
+
+### Step 2: Stage and Commit
+
+Use the `/commit` skill (from commit-commands plugin) for proper conventional commit formatting.
+
+If the commit-commands plugin is not available, fall back to:
+
+1. Show `git status` and `git diff --stat`
+2. Ask which files to stage (or confirm staging all)
+3. Generate conventional commit message from changes:
+   - `feat:` for new features
+   - `fix:` for bug fixes
+   - `refactor:` for code improvements
+   - `docs:` for documentation
+   - `test:` for test additions/changes
+   - `chore:` for maintenance
+4. Commit with the generated message
+
+### Step 3: Push
+
+```bash
+git push -u origin $(git branch --show-current)
+```
+
+### Step 4: Create Pull Request
+
+Detect the linked GitHub issue from:
+- Branch name (e.g., `feat/user-auth-42` implies issue #42)
+- Recent commit messages
+- Active plan file
+
+Create PR:
+```bash
+gh pr create \
+  --title "[type]: brief description" \
+  --body "## Summary
+- [what changed and why]
+
+## Linked Issue
+Closes #[number]
+
+## Test Plan
+- [ ] Automated tests pass
+- [ ] Manual verification of [key behavior]
+- [ ] Tested on [viewports/devices if applicable]
+"
+```
+
+### Step 5: Report
+
+```
+=== Shipped ===
+
+Branch: [branch name]
+Commit: [hash] — [message]
+PR: [PR URL]
+Closes: #[issue number]
+
+Next steps:
+- Wait for review
+- After merge: run /evolve to update the system
+```

package/.claude/commands/start.md

@@ -0,0 +1,63 @@
+# /start — Smart Pipeline Router
+
+You are the entry point to the AIDevelopmentFramework PIV+E pipeline. Your job is to detect where the user is in their workflow and route them to the right commands.
+
+## Step 1: Gather Context
+
+Run these in parallel:
+1. Check if `CLAUDE.md` exists in the project root (not the framework's own CLAUDE.md)
+2. Check if any PRD exists: `find docs/plans -name "PRD*" -o -name "prd*" 2>/dev/null`
+3. Check current git branch and status
+4. Check for existing GitHub issues: `gh issue list --limit 5 2>/dev/null`
+5. Check for existing plan files: `find docs/plans docs/superpowers/plans -name "*.md" 2>/dev/null`
+
+## Step 2: Detect Scope Level
+
+Based on context, determine the entry point:
+
+**L-1 (Onboard)** — No CLAUDE.md found for the project
+→ "This project hasn't been set up with the framework yet."
+→ Suggest: `/prime` then `/create-rules` then come back to `/start`
+
+**L0 (New Project)** — No PRD, no issues, minimal/no code
+→ "Looks like a fresh project. Let's plan it from scratch."
+→ Route to: `/create-prd` then `/plan-project`
+
+**L1 (New Feature)** — Project exists, user has a feature idea (no specific issue)
+→ "Let's plan this feature."
+→ Route to: `/plan-feature`
+
+**L2 (Issue Work)** — User has or references a specific issue number
+→ "Let's work on this issue."
+→ Route to: `/prime` then `/plan-feature #<issue>` or direct `/execute` if plan exists
+
+**L3 (Bug Fix)** — User describes a bug or references a bug issue
+→ "Let's debug this."
+→ Route to: `/prime` then use superpowers:systematic-debugging
+
+## Step 3: Ask if Uncertain
+
+If the scope level isn't clear from context, ask:
+
+> **What are you working on today?**
+>
+> 1. **Starting a new project from an idea** (L0 — full planning pipeline)
+> 2. **Building a new feature** (L1 — brainstorm + plan + implement)
+> 3. **Working on a specific GitHub issue** (L2 — plan + implement)
+> 4. **Fixing a bug** (L3 — debug + fix)
+> 5. **Joining this project for the first time** (L-1 — onboard)
+
+## Step 4: Mode Selection
+
+For L0, L1, and complex L2 tasks, ask:
+
+> **Which mode?**
+>
+> - **Superpowers Mode** — Full discipline: brainstorm, plan, TDD, execute, verify, review, ship, evolve
+> - **Standard Mode** — Lighter: plan, implement, validate, ship
+
+For L3 (bugs) and simple L2 (size S/M), default to Standard Mode without asking.
+
+## Step 5: Route
+
+Execute the appropriate command chain based on the detected level and chosen mode. Provide the user with a brief summary of what will happen next.

package/.claude/commands/validate.md

@@ -0,0 +1,72 @@
+# /validate — Verification Orchestrator
+
+Runs comprehensive verification: automated checks, visual testing, and code review.
+
+## Process
+
+### Phase 1: Automated Checks
+
+Run in parallel:
+
+```bash
+# Lint (detect from project)
+npm run lint 2>/dev/null || npx eslint . 2>/dev/null || echo "No linter configured"
+
+# Type check (detect from project)
+npx tsc --noEmit 2>/dev/null || echo "No TypeScript configured"
+
+# Tests (detect from project)
+npm test 2>/dev/null || npx jest 2>/dev/null || npx vitest run 2>/dev/null || echo "No test runner configured"
+```
+
+If any check fails, report the failure and offer to fix it before continuing.
+
+### Phase 2: Visual Verification (if applicable)
+
+Detect what was changed:
+```bash
+git diff --name-only main...HEAD
+```
+
+**If frontend files changed:**
+- Dispatch tester-agent with VERIFY queries for affected pages
+- Test at minimum: desktop and mobile viewports
+- Check: elements render, navigation works, forms submit
+
+**If mobile files changed:**
+- Dispatch mobile-tester-agent with VERIFY queries for affected screens
+- Check: elements visible, navigation works, interactions respond
+
+**If API/backend files changed:**
+- Run API tests if they exist
+- Check: endpoints respond with correct status codes
+- If Supabase: run `get_advisors` for schema safety
+
+### Phase 3: Code Review
+
+Invoke the code review skill:
+- Review against the implementation plan (does the code match the plan?)
+- Check for common issues: error handling, edge cases, security
+- Verify no debug code left (console.log, TODO comments, commented-out code)
+
+### Phase 4: Report
+
+```
+=== Validation Report ===
+
+Automated Checks:
+- Lint: PASS / N issues
+- Types: PASS / N errors
+- Tests: PASS (N/N) / N failures
+
+Visual Verification:
+- [Page/Screen]: PASS / FAIL — [description]
+
+Code Review:
+- [Finding 1]
+- [Finding 2]
+
+Verdict: Ready to ship / Needs fixes
+
+Next: Run /ship when ready, or fix issues and re-run /validate
+```

package/.claude/hooks/architect-sync.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Hook: PostToolUse on Write/Edit
+# Purpose: Reminds to update architect-agent after structural changes
+# Behavior: REMIND
+
+FILE="$1"
+
+if echo "$FILE" | grep -qE '\.(module|controller|service|guard|middleware|resolver)\.(ts|js)$'; then
+  echo "REMINDER: Structural file changed. After completing this feature,"
+  echo "run architect-agent RECORD to update the codebase knowledge base."
+fi
+
+if echo "$FILE" | grep -qE '(migration|schema|\.sql)'; then
+  echo "REMINDER: Database schema changed. Run architect-agent RECORD"
+  echo "and check Supabase advisors (get_advisors) for security/performance."
+fi
+
+exit 0

package/.claude/hooks/branch-guard.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Hook: PreToolUse on Bash
+# Purpose: Prevents direct commits and pushes to main/master
+# Behavior: BLOCK
+
+COMMAND="$*"
+
+if echo "$COMMAND" | grep -qE 'git (commit|push).*(main|master)'; then
+  echo "BLOCKED: Direct commits/pushes to main/master are not allowed."
+  echo "Create a feature branch first: git checkout -b feat/your-feature"
+  echo "Then use /ship to commit, push, and create a PR."
+  exit 1
+fi
+
+exit 0

package/.claude/hooks/evolve-reminder.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Hook: Stop (after PR-related commands)
+# Purpose: Reminds to run /evolve after merging
+# Behavior: REMIND
+
+echo ""
+echo "If you just merged a PR, run /evolve to:"
+echo "  - Update CLAUDE.md with learnings from this session"
+echo "  - Update architect-agent knowledge base"
+echo "  - Improve the system for next time"
+echo ""
+
+exit 0

package/.claude/hooks/plan-required.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Hook: PreToolUse on Edit/Write (implementation files only)
+# Purpose: Warns if no plan file exists for the current branch
+# Behavior: WARN (does not block)
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+
+if [ -z "$BRANCH" ] || [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  exit 0
+fi
+
+PLAN_EXISTS=$(find docs/plans docs/superpowers/plans -name "*.md" 2>/dev/null | head -1)
+
+if [ -z "$PLAN_EXISTS" ]; then
+  echo "NOTE: No implementation plan found for this branch."
+  echo "For L/XL tasks, consider running /plan-feature first."
+  echo "For small tasks, this is fine — carry on."
+fi
+
+exit 0

package/.claude/hooks/session-primer.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Hook: Notification (session start)
+# Purpose: Shows quick context on session start
+# Behavior: INFORM
+
+echo "=== Session Context ==="
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+if [ -n "$BRANCH" ]; then
+  echo "Branch: $BRANCH"
+fi
+
+RECENT=$(git log --oneline -3 2>/dev/null)
+if [ -n "$RECENT" ]; then
+  echo ""
+  echo "Recent commits:"
+  echo "$RECENT"
+fi
+
+if [ -n "$BRANCH" ] && [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then
+  PLANS=$(find docs/plans docs/superpowers/plans -name "*.md" -newer .git/HEAD 2>/dev/null | head -3)
+  if [ -n "$PLANS" ]; then
+    echo ""
+    echo "Active plans:"
+    echo "$PLANS"
+  fi
+fi
+
+STATUS=$(git status --short 2>/dev/null | wc -l | tr -d ' ')
+if [ "$STATUS" != "0" ]; then
+  echo ""
+  echo "Uncommitted changes: $STATUS files"
+fi
+
+echo "========================"
+echo "Run /start to begin or /prime for full context."
+
+exit 0