ai-development-framework 0.1.0

package/.claude/agents/_template/AGENT.md

@@ -0,0 +1,36 @@
+# [Agent Name]
+
+[One-line description of what this agent does]
+
+## Query Types
+
+### [QUERY_TYPE_1] [parameters]
+[Description of what this query does and what it returns]
+
+### [QUERY_TYPE_2] [parameters]
+[Description]
+
+## Tools
+
+- [Tool 1] — [what it's used for]
+- [Tool 2] — [what it's used for]
+
+## Response Format
+
+- Max ~[20-30] lines per response
+- [Format guidelines]
+
+## Knowledge Base
+
+```
+agent-name/
+├── AGENT.md      ← This file (protocol definition)
+└── [other files]  ← Agent-specific knowledge files
+```
+
+## Usage Example
+
+```
+Agent: [QUERY_TYPE_1] [example parameters]
+→ Agent responds with: [example output format]
+```

package/.claude/agents/architect-agent/AGENT.md

@@ -0,0 +1,60 @@
+# Architect Agent
+
+Project architecture knowledge base. Call before creating/modifying modules, routes, DB tables, or endpoints.
+
+## Query Types
+
+### RETRIEVE domain:<area>
+Returns: file map, endpoints, DB tables, integration points, gotchas for the specified domain.
+Read `index.md` to find the right domain file, then read that file.
+
+### IMPACT
+Analyzes what a planned change will affect.
+Read relevant domain files, trace dependencies, report:
+- Files that will need changes
+- Other modules that integrate with this area
+- Database tables affected
+- Potential breaking changes
+- Patterns to follow (from shared/patterns.md)
+
+### RECORD domain:<area>
+Main agent reports that changes were made. Verify the changes exist, then update the relevant domain file and index.md.
+- Use Glob and Grep to verify new files/endpoints exist
+- Update the domain knowledge file with new information
+- Add a decision to decisions/log.md if this was an architectural choice
+
+### PATTERN
+Returns established conventions from shared/patterns.md.
+Read the patterns file and return relevant conventions.
+
+## Tools
+
+- Read, Glob, Grep — for codebase exploration
+- Edit, Write — for updating knowledge base files
+
+## Response Format
+
+- Max ~30 lines per response
+- Structured: use tables and bullet lists
+- Include file paths with line numbers where relevant
+- Flag GOTCHA warnings for known pitfalls
+
+## Knowledge Base Structure
+
+```
+architect-agent/
+├── index.md          ← TOC: lists all domains with brief descriptions
+├── modules/          ← One file per backend module/domain
+├── frontend/         ← Frontend-specific knowledge (routes, components)
+├── shared/
+│   └── patterns.md   ← Cross-cutting conventions and patterns
+└── decisions/
+    └── log.md        ← Architecture decision records
+```
+
+## Initialization
+
+When first set up for a project, the main agent should:
+1. Run /prime to understand the codebase
+2. Use RECORD to populate initial domain files from codebase exploration
+3. The knowledge base grows organically as RECORD queries accumulate

package/.claude/agents/architect-agent/decisions/log.md

@@ -0,0 +1,18 @@
+# Architecture Decision Log
+
+Records of significant architectural choices and their rationale.
+Added by architect-agent RECORD when structural decisions are made.
+
+## Format
+
+### ADR-NNN: [Decision Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted / Superseded by ADR-XXX
+**Context:** Why was this decision needed?
+**Decision:** What was decided?
+**Consequences:** What are the implications (positive and negative)?
+
+---
+
+> No decisions recorded yet. Decisions are added as the project evolves.

package/.claude/agents/architect-agent/index.md

@@ -0,0 +1,32 @@
+# Architecture Knowledge Base — Index
+
+This file is the table of contents for the architect-agent knowledge base.
+It is populated by RECORD queries as the project evolves.
+
+## How to Use
+
+- **RETRIEVE domain:X** — Look up domain X below, read the linked file
+- **IMPACT** — Read relevant domains, trace dependencies
+- **RECORD domain:X** — After changes, update the linked file
+- **PATTERN** — Read `shared/patterns.md`
+
+## Domains
+
+> This section is populated as the project grows. Run architect-agent RECORD to add domains.
+
+| Domain | File | Description |
+|--------|------|-------------|
+| _example_ | `modules/example.md` | _Example: authentication module — endpoints, guards, strategies_ |
+
+## Frontend
+
+| Area | File | Description |
+|------|------|-------------|
+| _example_ | `frontend/routes.md` | _Example: route map and page inventory_ |
+
+## Shared
+
+| Resource | File |
+|----------|------|
+| Cross-cutting patterns | `shared/patterns.md` |
+| Architecture decisions | `decisions/log.md` |

package/.claude/agents/architect-agent/shared/patterns.md

@@ -0,0 +1,19 @@
+# Cross-Cutting Patterns
+
+Conventions that apply across all domains. Updated by architect-agent RECORD and /evolve.
+
+## Naming Conventions
+
+> Populated by /create-rules when it analyzes the codebase.
+
+## File Organization
+
+> Populated by /create-rules when it analyzes the codebase.
+
+## Error Handling
+
+> Populated by /create-rules when it analyzes the codebase.
+
+## API Design
+
+> Populated by /create-rules when it analyzes the codebase.

package/.claude/agents/mobile-tester-agent/AGENT.md

@@ -0,0 +1,46 @@
+# Mobile Tester Agent
+
+Mobile app testing agent. Uses mobile-mcp tools to test Expo/React Native apps on iOS simulator. Reports concise pass/fail results.
+
+## Query Types
+
+### VERIFY screen:<ScreenName> Checks: <list>
+Spot-checks on a single screen.
+
+Example:
+```
+VERIFY screen:HomeScreen Checks: renders header, shows tab bar, lists 3 items
+```
+
+### FLOW: <scenario> Steps: 1. ... 2. ...
+Multi-step user journey on mobile.
+
+Example:
+```
+FLOW: Add item Steps: 1. Tap + button 2. Fill title field 3. Tap save 4. Verify item appears in list
+```
+
+## Tools
+
+- **mobile-mcp tools:** mobile_list_available_devices, mobile_launch_app, mobile_take_screenshot, mobile_click_on_screen_at_coordinates, mobile_type_keys, mobile_swipe_on_screen, mobile_press_button, mobile_list_elements_on_screen
+- **Read** — read screen-patterns.md and auth-state.md
+
+## App Launch Sequence
+
+1. `mobile_list_available_devices` — find booted iOS simulator
+2. `mobile_launch_app` or `mobile_open_url` with Expo URL
+3. `mobile_take_screenshot` — verify app loaded
+4. If login required: read `../tester-agent/auth-state.md` and authenticate
+
+## Response Format
+
+- Max ~20 lines per response
+- PASS or FAIL per check
+- On FAIL: include screenshot and brief description
+- On PASS: one-line confirmation, no screenshot
+
+## Navigation
+
+- **Tab bar:** Tap coordinates from screen-patterns.md
+- **Back:** `mobile_swipe_on_screen` from left edge or tap back button
+- **Scroll:** `mobile_swipe_on_screen` vertical

package/.claude/agents/mobile-tester-agent/screen-patterns.md

@@ -0,0 +1,42 @@
+# Screen Patterns
+
+Screen inventory and navigation patterns for the mobile-tester-agent.
+Populated by /create-rules and updated by /evolve.
+
+## Configuration
+
+- **App URL:** exp://localhost:8081
+- **Dev command:** `npx expo start`
+- **Platform:** iOS Simulator
+
+## Navigation Structure
+
+> Populated when /create-rules scans the mobile app's routing.
+
+### Tab Bar
+| Tab | Screen | Icon Position (approx) |
+|-----|--------|----------------------|
+| Home | HomeScreen | Bottom-left |
+| Search | SearchScreen | Bottom-center-left |
+| Profile | ProfileScreen | Bottom-right |
+
+### Stack Screens
+| Parent | Screen | Trigger |
+|--------|--------|---------|
+| Home | DetailScreen | Tap list item |
+
+## Screen Inventory
+
+> Populated when /create-rules scans the mobile app's screens.
+
+| Screen | Auth Required | Key Elements |
+|--------|--------------|-------------|
+| HomeScreen | No | Header, list, tab bar |
+| LoginScreen | No | Email field, password field, submit |
+| ProfileScreen | Yes | Avatar, name, settings list |
+
+## Common Patterns
+
+- **Pull to refresh:** Swipe down from top of list
+- **Infinite scroll:** Swipe up at bottom of list
+- **Modal dismiss:** Swipe down from modal header or tap X

package/.claude/agents/tester-agent/AGENT.md

@@ -0,0 +1,44 @@
+# Tester Agent
+
+Browser testing agent. Runs playwright-cli to verify web UI renders correctly and user flows work. Reports concise pass/fail results.
+
+## Query Types
+
+### VERIFY page:<path> Checks: <list>
+Spot-checks on a single page. Navigate to the page, verify each check.
+
+Example:
+```
+VERIFY page:/dashboard Checks: renders heading, shows user name, sidebar has 5 links
+```
+
+### FLOW: <scenario> Steps: 1. ... 2. ...
+Multi-step user journey. Execute steps in order, verify each one.
+
+Example:
+```
+FLOW: User login Steps: 1. Navigate to /login 2. Fill email and password 3. Click submit 4. Verify redirected to /dashboard
+```
+
+## Tools
+
+- **Bash** — run playwright-cli commands
+- **Read** — read test-patterns.md and auth-state.md
+
+## Setup
+
+1. Read `test-patterns.md` to understand the page inventory
+2. Read `auth-state.md` for login credentials if testing authenticated pages
+3. Launch browser: `npx playwright-cli open <base-url>`
+
+## Configuration
+
+- **Base URL:** Read from test-patterns.md (default: http://localhost:3000)
+- **Dev command:** Read from test-patterns.md
+
+## Response Format
+
+- Max ~20 lines per response
+- PASS or FAIL per check
+- On FAIL: include screenshot and brief description of what went wrong
+- On PASS: one-line confirmation, no screenshot

package/.claude/agents/tester-agent/auth-state.md

@@ -0,0 +1,22 @@
+# Auth State
+
+Test credentials for the tester-agent. Fill in when setting up the project.
+
+## Test User
+
+- **Email:** test@example.com
+- **Password:** testpassword123
+
+## Login Flow
+
+1. Navigate to `/login`
+2. Fill email field
+3. Fill password field
+4. Click submit button
+5. Wait for redirect to `/dashboard`
+
+## Session Management
+
+- Auth state is stored in browser cookies/localStorage
+- If session expires, re-run the login flow above
+- For persistent state, save browser state after login

package/.claude/agents/tester-agent/test-patterns.md

@@ -0,0 +1,36 @@
+# Test Patterns
+
+Page inventory and common test patterns for the tester-agent.
+Populated by /create-rules and updated by /evolve.
+
+## Configuration
+
+- **Base URL:** http://localhost:3000
+- **Dev command:** `npm run dev`
+- **Auth required:** Yes/No
+
+## Page Inventory
+
+> Populated when /create-rules scans the project's routes/pages.
+
+| Route | Auth Required | Key Elements |
+|-------|--------------|-------------|
+| `/` | No | Hero section, navigation |
+| `/login` | No | Email field, password field, submit button |
+| `/dashboard` | Yes | User greeting, sidebar, main content |
+
+## Common UI Elements
+
+> Populated when /create-rules detects component patterns.
+
+- Navigation: [describe nav pattern]
+- Forms: [describe form pattern]
+- Modals: [describe modal pattern]
+- Tables: [describe table pattern]
+
+## Form Patterns
+
+> Populated from codebase analysis.
+
+| Form | Route | Fields | Validation |
+|------|-------|--------|------------|

package/.claude/agents/ui-ux-analyzer/AGENT.md

@@ -0,0 +1,75 @@
+# UI/UX Analyzer Agent
+
+Professional UI/UX audit agent. Discovers pages, captures full-page screenshots (desktop and mobile viewports), analyzes design quality, and produces a detailed audit report with actionable findings.
+
+## How to Invoke
+
+Provide the base URL and optionally credentials:
+```
+Audit the UI at http://localhost:3000
+Credentials: test@example.com / testpassword123
+```
+
+## Process
+
+1. **Discover pages** — Read tester-agent/test-patterns.md for page inventory, or crawl from the base URL
+2. **Capture screenshots** — For each page:
+   - Desktop viewport (1440px)
+   - Tablet viewport (768px)
+   - Mobile viewport (375px)
+3. **Analyze** each page for:
+   - Visual hierarchy and layout
+   - Typography consistency
+   - Color usage and contrast (WCAG AA)
+   - Spacing and alignment
+   - Responsive behavior
+   - Interactive element sizing (touch targets)
+   - Loading states and empty states
+   - Error state handling
+4. **Generate report** — Write to `.claude/ui-audit/AUDIT_REPORT.md`
+
+## Tools
+
+- **Bash** — run agent-browser commands for navigation and screenshots
+- **Read, Glob, Grep** — read project files and patterns
+- **Write** — generate audit report
+
+## Report Format
+
+```markdown
+# UI/UX Audit Report
+
+**Date:** YYYY-MM-DD
+**Base URL:** <url>
+**Pages audited:** N
+
+## Summary
+
+[Overall assessment: 1-2 paragraphs]
+
+## Findings
+
+### [Finding Title]
+- **Severity:** Critical / Major / Minor / Enhancement
+- **Page(s):** /path
+- **Description:** What the issue is
+- **Screenshot:** [reference]
+- **Recommendation:** How to fix it
+
+## Scores
+
+| Category | Score (1-10) |
+|----------|-------------|
+| Visual Design | |
+| Consistency | |
+| Accessibility | |
+| Responsiveness | |
+| Overall | |
+```
+
+## After Audit
+
+The main agent should:
+1. Read `.claude/ui-audit/AUDIT_REPORT.md`
+2. Create GitHub issues for each Critical/Major finding
+3. Add Minor/Enhancement findings to a tracking issue

package/.claude/commands/create-prd.md

@@ -0,0 +1,55 @@
+# /create-prd — Product Requirements Document Generator
+
+Generate a comprehensive PRD from a product idea. This command ALWAYS starts with brainstorming.
+
+## Arguments
+
+- `$ARGUMENTS` — optional: the product idea in brief (can also be discussed interactively)
+
+## Process
+
+### Phase 1: Brainstorm (MANDATORY)
+
+Invoke the brainstorming skill to explore the idea before writing anything:
+
+1. If `$ARGUMENTS` is provided, use it as the starting point
+2. If not, ask: "What are you building? Give me the elevator pitch."
+3. Explore through conversation:
+   - What problem does this solve?
+   - Who is the target user?
+   - What are the constraints (timeline, budget, team size, tech preferences)?
+   - What does success look like?
+   - What's explicitly OUT of scope?
+4. Propose 2-3 architectural approaches with tradeoffs
+5. Get user's choice before proceeding
+
+### Phase 2: Generate PRD
+
+1. Read `.claude/references/prd-template.md` for the structure
+2. Fill in every section based on the brainstorming conversation
+3. Be specific — no placeholder text, no "TBD" sections
+4. User stories should be concrete and testable
+5. Implementation phases should be ordered by dependency and value
+
+### Phase 3: Review and Save
+
+1. Present the PRD to the user section by section
+2. Ask for feedback on each major section
+3. Incorporate feedback
+4. Save to `docs/plans/PRD.md`
+
+### Phase 4: Next Steps
+
+After saving, tell the user:
+
+> **PRD saved to `docs/plans/PRD.md`.**
+>
+> Next steps:
+> - Run `/plan-project` to decompose this into GitHub milestones and issues
+> - Or run `/plan-feature` to start planning a specific feature from the PRD
+
+Commit the PRD:
+```bash
+git add docs/plans/PRD.md
+git commit -m "docs: add product requirements document"
+```

package/.claude/commands/evolve.md

@@ -0,0 +1,84 @@
+# /evolve — Self-Improvement
+
+Updates the framework's rules, knowledge base, and patterns from what was learned in this session. This is what makes the system get smarter over time.
+
+## Philosophy
+
+"Every bug from the AI coding assistant isn't just something to fix — it's an opportunity to address the root cause in your system."
+
+## Process
+
+### Step 1: Reflect on Session
+
+Review what happened in this session:
+1. `git log --oneline main..HEAD` — what was built
+2. Were there any:
+   - Bugs that took multiple attempts to fix?
+   - Patterns the AI got wrong repeatedly?
+   - Missing context that caused mistakes?
+   - New conventions established?
+   - Architecture decisions made?
+
+### Step 2: Update CLAUDE.md
+
+Invoke the revise-claude-md skill (from claude-md-management plugin) to:
+- Add new conventions discovered
+- Update tech stack if it changed
+- Add new commands or scripts
+- Remove outdated information
+
+If the plugin isn't available, manually check CLAUDE.md for needed updates.
+
+### Step 3: Update Architect Knowledge Base
+
+If structural changes were made:
+1. Dispatch architect-agent with RECORD query
+2. Agent verifies changes exist in codebase
+3. Agent updates relevant domain files in modules/ and frontend/
+4. Agent updates index.md if new domains were added
+5. If an architectural decision was made, add to decisions/log.md
+
+### Step 4: Update Rules
+
+Check if any domain rules need updating:
+- Did a new pattern emerge in backend code? Update rules/backend.md
+- Did a new component pattern emerge? Update rules/frontend.md
+- Did a testing anti-pattern surface? Update rules/testing.md
+
+### Step 5: Update Code Patterns
+
+If the /execute phase revealed patterns the AI should follow:
+- Add to .claude/references/code-patterns.md
+- Include real code examples from the current codebase
+- Note common pitfalls with before/after examples
+
+### Step 6: Update Test Patterns
+
+If new pages or screens were created:
+- Update .claude/agents/tester-agent/test-patterns.md with new routes
+- Update .claude/agents/mobile-tester-agent/screen-patterns.md if mobile
+
+### Step 7: Report
+
+```
+=== System Evolution ===
+
+Updated:
+- [ ] CLAUDE.md — [what changed]
+- [ ] architect-agent knowledge base — [domains updated]
+- [ ] rules/[domain].md — [what changed]
+- [ ] references/code-patterns.md — [patterns added]
+- [ ] test-patterns.md — [routes added]
+
+New decisions recorded:
+- ADR-N: [decision title]
+
+System health:
+The framework is now better equipped to handle [specific scenario].
+```
+
+Commit all updates:
+```bash
+git add CLAUDE.md .claude/
+git commit -m "chore: evolve framework — update rules and knowledge base"
+```

package/.claude/commands/execute.md

@@ -0,0 +1,76 @@
+# /execute — Plan Executor
+
+Executes an implementation plan task by task with TDD discipline.
+
+## Arguments
+
+- `$ARGUMENTS` — path to plan file (auto-detected from current branch if omitted)
+
+## Prerequisites
+
+- A plan file must exist
+- If the plan specifies dependencies to install, install them first
+- Read the plan's "Mandatory Reading" section before starting
+
+## Process
+
+### Step 1: Load Plan
+
+1. If path provided, read that file
+2. If not, search for plan files:
+   - `docs/plans/` and `docs/superpowers/plans/`
+   - Match against current branch name
+   - If multiple found, ask user which one
+3. Parse the plan into tasks and steps
+
+### Step 2: Read Mandatory Files
+
+Read every file listed in the plan's "Mandatory Reading" section. This ensures you have the codebase context needed for implementation.
+
+### Step 3: Execute Tasks
+
+For each task in the plan:
+
+1. **Announce:** "Starting Task N: [task name]"
+2. **Read** all files listed in the task's "Files" section
+3. **For each step:**
+   - If it's a test step: write the test exactly as specified
+   - If it's a verification step: run the exact command, check output matches expected
+   - If it's an implementation step: write the code as specified
+   - If it's a commit step: stage and commit with the specified message
+4. **If a test fails unexpectedly:**
+   - Read the error output carefully
+   - Fix the implementation (not the test, unless the test has a bug)
+   - Re-run the test
+   - If stuck after 3 attempts, stop and report the issue
+5. **After task completion:** mark the task checkbox as done in the plan file
+
+### Step 4: Validation
+
+After all tasks are complete:
+1. Run the project's full test suite
+2. Run lint/type-check if available
+3. Verify the application starts without errors
+
+### Step 5: Completion Report
+
+```
+=== Execution Complete ===
+
+Plan: [plan file path]
+Tasks completed: N/N
+Tests passing: all / N failures
+Lint: pass / N issues
+Type check: pass / N errors
+
+Next steps:
+- Run /validate for full verification
+- Run /ship when ready to commit and create PR
+```
+
+## Error Handling
+
+- If a task fails and cannot be fixed in 3 attempts: stop, report the issue, ask the user
+- If the plan has a bug (wrong file path, missing step): fix the plan and continue
+- If a dependency is missing: install it and continue
+- Never skip a failing test — either fix the code or report the issue