ai-development-framework 0.1.0

package/.claude/references/claude-md-template.md

@@ -0,0 +1,90 @@
+# CLAUDE.md Generation Template
+
+Used by `/create-rules` to auto-generate a project CLAUDE.md.
+Fill in sections based on codebase analysis.
+
+---
+
+# [Project Name]
+
+## Overview
+
+[Auto-generated: 1-2 sentences about the project, detected from README/package.json]
+
+## Tech Stack
+
+[Auto-detected from package.json, requirements.txt, go.mod, etc.]
+
+| Layer | Technology |
+|-------|-----------|
+| Language | |
+| Framework | |
+| Database | |
+| ORM | |
+| Auth | |
+| Styling | |
+| Testing | |
+| Package Manager | |
+
+## Pipeline Commands (PIV+E)
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/start` | Router | Detects scope level, routes to correct pipeline |
+| `/prime` | Plan | Loads codebase context |
+| `/create-prd` | Plan | Generates PRD (includes brainstorming) |
+| `/plan-project` | Plan | PRD → GitHub milestones + issues |
+| `/plan-feature` | Plan | Creates implementation plan |
+| `/execute` | Implement | Executes plan with TDD |
+| `/validate` | Validate | Verification + testing agents |
+| `/ship` | Validate | Commit + push + PR |
+| `/evolve` | Evolve | Updates rules + knowledge base |
+| `/setup` | Utility | Checks plugin/skill health |
+
+## Project Structure
+
+[Auto-generated: tree -L 2 output of key directories]
+
+```
+project/
+├── src/          # [detected purpose]
+├── tests/        # [detected purpose]
+└── ...
+```
+
+## Development Commands
+
+[Auto-detected from package.json scripts, Makefile, etc.]
+
+```bash
+# Start development
+<detected dev command>
+
+# Run tests
+<detected test command>
+
+# Build
+<detected build command>
+```
+
+## Code Conventions
+
+[Auto-detected from codebase analysis]
+
+- [Naming convention: camelCase/snake_case/etc.]
+- [Import style: absolute/relative]
+- [Component pattern: functional/class]
+- [Error handling pattern]
+
+## Agents
+
+- **architect-agent** — Call before structural changes (RETRIEVE/IMPACT/RECORD/PATTERN)
+- **tester-agent** — Web UI testing after changes (VERIFY/FLOW)
+- **mobile-tester-agent** — Mobile testing after changes (VERIFY/FLOW)
+- **ui-ux-analyzer** — Design audits on request
+
+## Rules & References
+
+- Domain rules auto-load from `.claude/rules/` based on file paths
+- Code patterns in `.claude/references/code-patterns.md`
+- See `docs/customization.md` for extending the framework

package/.claude/references/code-patterns.md

@@ -0,0 +1,37 @@
+# Code Patterns
+
+This file is generated per-project by `/create-rules`. It contains real code patterns detected from your codebase.
+
+Run `/create-rules` to populate this file with patterns from your actual code.
+
+## How This File Works
+
+When `/create-rules` scans your codebase, it extracts:
+
+1. **Controller/Route patterns** — how endpoints are structured
+2. **Service/business logic patterns** — how business logic is organized
+3. **Data access patterns** — how database queries are written
+4. **Component patterns** — how UI components are structured
+5. **Form patterns** — how forms and validation work
+6. **Error handling patterns** — how errors are caught and reported
+7. **Test patterns** — how tests are structured
+8. **Common pitfalls** — mistakes specific to your codebase
+
+Each pattern includes a real code example from your project, so the AI follows YOUR conventions, not generic ones.
+
+## Template
+
+When populating, use this format per pattern:
+
+### [Pattern Name]
+
+**File:** `path/to/example.ts`
+**When:** [When to use this pattern]
+
+```language
+// Actual code from the project
+```
+
+**Key points:**
+- [What makes this pattern important]
+- [Common mistake to avoid]

package/.claude/references/issue-template.md

@@ -0,0 +1,56 @@
+# GitHub Issue Template
+
+Used by `/plan-project` and `/plan-feature` to create structured issues.
+
+---
+
+## Issue Structure
+
+### Title Format
+`[type]: brief description`
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
+
+### Body Template
+
+```markdown
+## Description
+
+[1-2 sentences: what needs to be built/fixed and why]
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Technical Notes
+
+- Key files to modify: `path/to/file`
+- Pattern to follow: [reference existing similar implementation]
+- Dependencies: [other issues that must be completed first]
+
+## Size Estimate
+
+[S / M / L / XL]
+
+- **S** (< 1 hour): Config change, copy update, simple fix
+- **M** (1-4 hours): Single component/endpoint, moderate logic
+- **L** (4-16 hours): Multi-file feature, new module
+- **XL** (> 16 hours): Consider breaking into smaller issues
+```
+
+### Labels
+
+Apply these labels via `gh issue create --label`:
+
+| Label | When |
+|-------|------|
+| `feat` | New functionality |
+| `fix` | Bug fix |
+| `refactor` | Code improvement, no behavior change |
+| `docs` | Documentation only |
+| `priority:high` | Blocks other work or critical path |
+| `priority:medium` | Important but not blocking |
+| `priority:low` | Nice to have |
+| `size:S/M/L/XL` | Estimated effort |

package/.claude/references/plan-template.md

@@ -0,0 +1,92 @@
+# Implementation Plan Template
+
+Use this structure when generating plans via `/plan-feature`.
+
+---
+
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** [One sentence]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies]
+
+**Confidence Score:** [1-10] for one-pass implementation success
+
+**Context Reset:** [Recommended / Not needed] between planning and implementation
+
+---
+
+## Mandatory Reading
+
+Before implementing, read these files to understand the codebase context:
+
+| File | Lines | What to Learn |
+|------|-------|--------------|
+| `path/to/file` | 1-50 | Pattern for X |
+
+## File Map
+
+### New Files
+| File | Responsibility |
+|------|---------------|
+| `path/to/new/file` | Description |
+
+### Modified Files
+| File | Changes |
+|------|---------|
+| `path/to/existing` | What changes and why |
+
+## Dependencies
+
+Install before starting:
+```bash
+<install commands if any>
+```
+
+## Tasks
+
+### Task 1: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file`
+- Modify: `exact/path/to/existing:lines`
+- Test: `tests/exact/path/to/test`
+
+- [ ] Step 1: Write the failing test
+  ```language
+  <actual test code>
+  ```
+
+- [ ] Step 2: Run test to verify it fails
+  Run: `<exact command>`
+  Expected: FAIL with "<message>"
+
+- [ ] Step 3: Write minimal implementation
+  ```language
+  <actual implementation code>
+  ```
+
+- [ ] Step 4: Run test to verify it passes
+  Run: `<exact command>`
+  Expected: PASS
+
+- [ ] Step 5: Commit
+  ```bash
+  git add <files>
+  git commit -m "<conventional commit message>"
+  ```
+
+### Task 2: ...
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## GOTCHA Warnings
+
+- **GOTCHA:** [Specific pitfall and how to avoid it]

package/.claude/references/prd-template.md

@@ -0,0 +1,119 @@
+# PRD Template
+
+Use this structure when generating a PRD via `/create-prd`.
+
+---
+
+# [Project Name] — Product Requirements Document
+
+## 1. Executive Summary
+
+One paragraph: what is this product, who is it for, what problem does it solve.
+
+## 2. Problem Statement
+
+- What pain point exists today?
+- Who experiences it?
+- What are they currently doing instead?
+
+## 3. Goals & Success Criteria
+
+| Goal | Metric | Target |
+|------|--------|--------|
+| | | |
+
+## 4. Target Users
+
+| Persona | Description | Key Needs |
+|---------|-------------|-----------|
+| | | |
+
+## 5. User Stories
+
+### Epic: [Epic Name]
+
+- [ ] As a [user], I want to [action] so that [benefit]
+- [ ] As a [user], I want to [action] so that [benefit]
+
+### Epic: [Epic Name]
+
+- [ ] ...
+
+## 6. Scope
+
+### In Scope (MVP)
+
+- [x] Feature 1
+- [x] Feature 2
+
+### Out of Scope (Future)
+
+- [ ] Feature 3
+- [ ] Feature 4
+
+## 7. Technical Architecture
+
+### Tech Stack
+
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| Frontend | | |
+| Backend | | |
+| Database | | |
+| Auth | | |
+| Hosting | | |
+
+### System Diagram
+
+Describe the high-level architecture: which services exist, how they communicate, where data lives.
+
+## 8. Data Model
+
+List core entities, their key fields, and relationships.
+
+## 9. API Design
+
+List key endpoints or API surface area.
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| | | |
+
+## 10. UI/UX Overview
+
+Describe key screens/pages and user flows. Reference wireframes if available.
+
+## 11. Implementation Phases
+
+### Phase 1: Foundation (MVP)
+- ...
+
+### Phase 2: Enhancement
+- ...
+
+### Phase 3: Scale
+- ...
+
+## 12. Security Considerations
+
+- Authentication method
+- Authorization model
+- Data protection
+- OWASP concerns
+
+## 13. Performance Requirements
+
+- Response time targets
+- Concurrent user capacity
+- Data volume expectations
+
+## 14. Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|-----------|------------|
+| | | | |
+
+## 15. Open Questions
+
+- [ ] Question 1
+- [ ] Question 2

package/.claude/rules/_global.md

@@ -0,0 +1,22 @@
+# Global Rules
+
+## Git Workflow
+
+- Branch naming: `{type}/{description}` (e.g., `feat/user-auth`, `fix/login-redirect`)
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`
+- Always link PRs to GitHub issues
+- Never commit directly to main/master — use feature branches
+
+## Code Standards
+
+- TypeScript strict mode where applicable
+- Self-documenting code — comments only for non-obvious logic
+- No unnecessary abstractions or over-engineering (YAGNI)
+- DRY — but three similar lines beats a premature abstraction
+
+## Pipeline Discipline
+
+- For non-trivial work: choose Superpowers or Standard mode before starting
+- Plans are mandatory for L/XL tasks — run `/plan-feature` first
+- Run `/validate` before claiming work is done
+- Run `/evolve` after merging to keep the system improving

package/.claude/rules/_template.md

@@ -0,0 +1,23 @@
+---
+description: <Describe when this rule should load>
+globs: ["<glob pattern for file paths>"]
+---
+
+# [Domain] Rules
+
+## Skill Chain
+
+1. <First skill or agent to use>
+2. <Second skill>
+3. <Verification step>
+
+## Conventions
+
+- <Convention 1>
+- <Convention 2>
+- <Convention 3>
+
+## Checklist
+
+- [ ] <Post-implementation check 1>
+- [ ] <Post-implementation check 2>

package/.claude/rules/backend.md

@@ -0,0 +1,29 @@
+---
+description: Backend development rules — auto-loads when editing backend/server files
+globs: ["**/backend/**", "**/server/**", "**/api/**", "**/*.controller.*", "**/*.service.*", "**/*.module.*", "**/*.guard.*", "**/*.middleware.*", "**/*.resolver.*"]
+---
+
+# Backend Rules
+
+## Skill Chain
+
+When working on backend code, follow this order:
+1. **architect-agent RETRIEVE** — understand current module structure before changes
+2. **context7 MCP** — verify framework API (NestJS, FastAPI, Express, etc.) before writing
+3. **Database MCP** — if schema changes needed, use Supabase MCP or direct SQL
+4. **Implement** — follow patterns from `.claude/references/code-patterns.md`
+5. **architect-agent RECORD** — update knowledge base after structural changes
+
+## Conventions
+
+- Every endpoint needs input validation (DTOs/schemas)
+- Error responses follow consistent format: `{ error: string, statusCode: number }`
+- Business logic lives in services, not controllers
+- Database queries go through a repository/service layer
+- Environment-specific config via env vars, never hardcoded
+
+## Testing
+
+- Service methods: unit test with mocked dependencies
+- Controllers: integration test with real service, mocked DB if needed
+- E2E: API endpoint tests with real DB for critical paths

package/.claude/rules/database.md

@@ -0,0 +1,28 @@
+---
+description: Database rules — auto-loads when editing migrations, schemas, SQL files
+globs: ["**/migrations/**", "**/*.sql", "**/schema*", "**/prisma/**", "**/drizzle/**", "**/supabase/**"]
+---
+
+# Database Rules
+
+## Skill Chain
+
+1. **Supabase MCP** (if using Supabase): `list_tables` → `execute_sql` → `apply_migration` → `get_advisors`
+2. **`/supabase-postgres-best-practices`** — for schema design and query optimization
+3. **`/mongodb`** or **`/mongodb-development`** — if using MongoDB
+
+## Conventions
+
+- Every migration is reversible (include up AND down)
+- Never modify existing migrations — always create new ones
+- Add indexes for frequently queried columns
+- Use foreign key constraints for referential integrity
+- RLS policies on all user-facing tables (Supabase)
+
+## Post-DDL Checklist
+
+After any schema change:
+- [ ] Run Supabase advisors (`get_advisors`) or equivalent linter
+- [ ] Verify RLS policies still work
+- [ ] Update TypeScript types (`generate_typescript_types` or equivalent)
+- [ ] Update architect-agent knowledge base

package/.claude/rules/frontend.md

@@ -0,0 +1,34 @@
+---
+description: Frontend development rules — auto-loads when editing frontend/web files
+globs: ["**/web/**", "**/frontend/**", "**/app/**", "**/*.tsx", "**/*.jsx", "**/components/**", "**/pages/**"]
+---
+
+# Frontend Rules
+
+## Design Skill Gate (MANDATORY)
+
+Before creating any UI component or page, ask the user which design approach:
+
+1. **`/frontend-design`** — Full page/component creation with bold aesthetics
+2. **`/frontend-aesthetics`** — Lightweight guardrails (typography, color, motion)
+3. **`/ui-ux-pro-max`** — Design planning and exploration (50 styles, 21 palettes)
+
+Combination rules:
+- `/frontend-aesthetics` can combine with either of the other two
+- Never combine `/frontend-design` + `/ui-ux-pro-max` — they conflict
+
+## Skill Chain
+
+1. **architect-agent RETRIEVE** — understand page/component structure
+2. **Design skill** — chosen via gate above
+3. **shadcn MCP** — search and install components: `search_items_in_registries`, `view_items_in_registries`, `get_add_command_for_items`
+4. **context7 MCP** — verify framework API (Next.js, React, etc.)
+5. **tester-agent VERIFY/FLOW** — verify UI after implementation
+
+## Conventions
+
+- Functional components with hooks
+- Form handling: React Hook Form + Zod validation
+- State: prefer server state (React Query/SWR) over client state
+- Styling: follow project convention (Tailwind, CSS Modules, etc.)
+- Accessibility: semantic HTML, ARIA labels, keyboard navigation

package/.claude/rules/mobile.md

@@ -0,0 +1,33 @@
+---
+description: Mobile development rules — auto-loads when editing mobile/native files
+globs: ["**/mobile/**", "**/native/**", "**/*.native.*", "**/expo/**"]
+---
+
+# Mobile Rules
+
+## Expo Skills (use the right one for the task)
+
+| Task | Skill |
+|------|-------|
+| Building screens, components, navigation | `/expo-app-design:building-native-ui` |
+| API calls, caching, offline support | `/expo-app-design:native-data-fetching` |
+| Tailwind/NativeWind setup | `/expo-app-design:expo-tailwind-setup` |
+| Dev client builds, TestFlight | `/expo-app-design:expo-dev-client` |
+| API routes with EAS Hosting | `/expo-app-design:expo-api-routes` |
+| Web code in native webview | `/expo-app-design:use-dom` |
+| SwiftUI components | `/expo-app-design:expo-ui-swift-ui` |
+| Jetpack Compose components | `/expo-app-design:expo-ui-jetpack-compose` |
+
+## Skill Chain
+
+1. **architect-agent RETRIEVE** — understand screen/navigation structure
+2. **Expo skill** — appropriate skill from table above
+3. **context7 MCP** — verify Expo/React Native API
+4. **mobile-tester-agent VERIFY/FLOW** — verify on simulator after implementation
+
+## Conventions
+
+- Follow Expo Router file-based routing
+- Use platform-specific extensions (`.ios.tsx`, `.android.tsx`) only when necessary
+- Animations via `react-native-reanimated`
+- Navigation state managed by Expo Router, not manually

package/.claude/rules/testing.md

@@ -0,0 +1,37 @@
+---
+description: Testing rules — auto-loads when editing test files
+globs: ["**/*.test.*", "**/*.spec.*", "**/test/**", "**/tests/**", "**/__tests__/**", "**/e2e/**"]
+---
+
+# Testing Rules
+
+## Test Naming
+
+- Describe behavior, not implementation: `it('returns 404 when user not found')` not `it('tests getUserById')`
+- Group by feature/module with `describe` blocks
+
+## Test Structure
+
+- **Arrange** — set up test data and dependencies
+- **Act** — call the function/endpoint under test
+- **Assert** — verify the result
+
+## What to Test
+
+- Happy path (expected inputs → expected outputs)
+- Edge cases (empty inputs, boundary values, null/undefined)
+- Error cases (invalid inputs, network failures, permission denied)
+- Do NOT test framework internals or third-party libraries
+
+## Mock Policy
+
+- Use real databases for integration tests where possible
+- Mock external APIs and third-party services
+- Never mock the module under test
+- Prefer dependency injection over module mocking
+
+## Coverage
+
+- Critical business logic: aim for high coverage
+- UI components: test behavior (clicks, form submissions), not rendering details
+- Don't chase 100% — test what matters

package/.claude/settings.local.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(gh *)",
+      "Bash(ls *)",
+      "Bash(tree *)",
+      "Bash(cat *)",
+      "Bash(mkdir *)",
+      "Bash(npx *)",
+      "Bash(npm *)",
+      "Bash(pnpm *)",
+      "Bash(node *)",
+      "WebFetch(*)",
+      "WebSearch(*)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs",
+      "mcp__shadcn__search_items_in_registries",
+      "mcp__shadcn__view_items_in_registries",
+      "mcp__shadcn__get_item_examples_from_registries",
+      "mcp__shadcn__get_add_command_for_items",
+      "mcp__shadcn__list_items_in_registries"
+    ],
+    "deny": []
+  },
+  "enableAllProjectMcpServers": true
+}