ai-development-framework 0.1.0

package/.claude/skills/e2e-test/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: e2e-test
+description: End-to-end testing orchestration. Discovers user journeys, runs browser tests, validates database state, auto-fixes bugs found during testing, generates report.
+---
+
+# E2E Test Skill
+
+Orchestrates a comprehensive end-to-end testing run across the application.
+
+## When to Use
+
+- After implementing a feature (before /ship)
+- As part of /validate
+- When verifying existing functionality still works
+
+## Process
+
+### Phase 1: Pre-flight
+1. Check that the application is running (curl the base URL)
+2. If not running, start it using the dev command from test-patterns.md
+3. Verify agent-browser or playwright-cli is available
+
+### Phase 2: Discovery
+Launch 2-3 parallel sub-agents to gather intelligence:
+
+**Agent 1 — App Structure:**
+- Read tester-agent/test-patterns.md
+- Identify all user-facing pages/routes
+- Map critical user journeys (signup, login, use feature, logout)
+
+**Agent 2 — Data Flows:**
+- Read architect-agent knowledge base
+- Identify data-modifying operations (create, update, delete)
+- Note expected database state changes
+
+**Agent 3 — Bug Hunting:**
+- Read recent git changes (git diff main...HEAD)
+- Identify areas most likely to have bugs
+- Prioritize testing for changed code paths
+
+### Phase 3: Test Execution
+
+For each discovered user journey:
+
+1. **Navigate** to the starting page
+2. **Execute** each step in the journey
+3. **Verify** UI state after each step (elements visible, correct content)
+4. **Verify** database state after data-modifying steps (query DB directly)
+5. **Test** at 3 viewports: desktop (1440px), tablet (768px), mobile (375px)
+6. **Screenshot** on failures only
+
+### Phase 4: Fix Loop
+
+When a test fails:
+1. Diagnose the root cause
+2. Fix the code
+3. Re-run the failing step
+4. Screenshot the fix
+5. Continue testing
+
+### Phase 5: Report
+
+Generate a test report:
+
+```markdown
+# E2E Test Report — YYYY-MM-DD
+
+## Summary
+- Journeys tested: N
+- Steps executed: N
+- Passed: N
+- Failed: N (M auto-fixed)
+
+## Journeys
+
+### [Journey Name]
+- Status: PASS / FAIL
+- Steps: N/N passed
+- Viewports: desktop, tablet, mobile
+- Fixes applied: [list if any]
+
+## Auto-Fixes Applied
+- [File: change description]
+
+## Remaining Issues
+- [Issue description — create GitHub issue]
+```

package/.claude/skills/playwright-cli/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: playwright-cli
+description: Browser automation command reference for playwright-cli. Navigation, interaction, screenshots, forms, state management, debugging.
+---
+
+# Playwright CLI Reference
+
+## Core Commands
+
+### Navigation
+```bash
+npx playwright-cli open <url>              # Open URL
+npx playwright-cli navigate <url>          # Navigate to URL
+npx playwright-cli snapshot                # Get DOM snapshot with element refs
+```
+
+### Interaction
+```bash
+npx playwright-cli click <ref>             # Click element by ref from snapshot
+npx playwright-cli fill <ref> <value>      # Fill input field
+npx playwright-cli select <ref> <value>    # Select dropdown option
+npx playwright-cli check <ref>             # Check checkbox
+npx playwright-cli uncheck <ref>           # Uncheck checkbox
+npx playwright-cli hover <ref>             # Hover over element
+npx playwright-cli press <key>             # Press keyboard key
+npx playwright-cli type <text>             # Type text (character by character)
+```
+
+### Screenshots and Recording
+```bash
+npx playwright-cli screenshot <path>       # Take screenshot
+npx playwright-cli screenshot --full <path> # Full page screenshot
+npx playwright-cli video start <path>      # Start recording
+npx playwright-cli video stop              # Stop recording
+```
+
+### Waiting
+```bash
+npx playwright-cli wait <ref>              # Wait for element visible
+npx playwright-cli wait-hidden <ref>       # Wait for element hidden
+npx playwright-cli wait-navigation         # Wait for page navigation
+```
+
+### Dialog Handling
+```bash
+npx playwright-cli dialog accept           # Accept alert/confirm/prompt
+npx playwright-cli dialog dismiss          # Dismiss dialog
+npx playwright-cli dialog accept <text>    # Accept prompt with text
+```
+
+### Session and State
+```bash
+npx playwright-cli storage save <path>     # Save browser state (cookies, localStorage)
+npx playwright-cli storage load <path>     # Load saved state
+npx playwright-cli cookies get             # Get all cookies
+npx playwright-cli cookies clear           # Clear cookies
+```
+
+### Network
+```bash
+npx playwright-cli network intercept <pattern> <response-file>  # Mock network request
+npx playwright-cli network log             # Show network requests
+```
+
+### Viewport
+```bash
+npx playwright-cli viewport <width> <height>  # Set viewport size
+```
+
+## Common Patterns
+
+### Login Flow
+```bash
+npx playwright-cli open http://localhost:3000/login
+npx playwright-cli snapshot
+npx playwright-cli fill ref:email "test@example.com"
+npx playwright-cli fill ref:password "testpassword123"
+npx playwright-cli click ref:submit
+npx playwright-cli wait-navigation
+npx playwright-cli snapshot  # Verify dashboard loaded
+npx playwright-cli storage save auth-state.json  # Save for reuse
+```
+
+### Responsive Testing
+```bash
+# Desktop
+npx playwright-cli viewport 1440 900
+npx playwright-cli screenshot desktop.png
+
+# Tablet
+npx playwright-cli viewport 768 1024
+npx playwright-cli screenshot tablet.png
+
+# Mobile
+npx playwright-cli viewport 375 812
+npx playwright-cli screenshot mobile.png
+```

package/CLAUDE.md

@@ -0,0 +1,65 @@
+# AIDevelopmentFramework
+
+## Overview
+
+Open-source agentic AI coding framework built on the PIV+E loop (Plan, Implement, Validate, Evolve). Claude Code primary, methodology portable to any AI coding tool.
+
+## Tech Stack
+
+- Claude Code CLI (commands, agents, skills, rules, hooks)
+- Node.js (CLI tool)
+- GitHub (issues, milestones, PRs)
+
+## Core Principles
+
+1. **Context is precious** — manage it deliberately; recommend context resets for complex work
+2. **Plans are artifacts** — they survive session boundaries and pass the "no prior knowledge" test
+3. **Discipline scales with complexity** — XL features get full ceremony, S tweaks get fast-tracked
+4. **The system self-improves** — every AI mistake becomes a rule, pattern, or guardrail
+5. **Ship everything, install nothing** — framework works out of the box; external plugins stay fresh from source
+
+## Pipeline Commands (PIV+E)
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/start` | Router | Detects scope level, routes to correct pipeline |
+| `/prime` | Plan | Loads codebase context into session |
+| `/create-prd` | Plan | Generates PRD from idea (includes brainstorming) |
+| `/plan-project` | Plan | Decomposes PRD into GitHub milestones + issues |
+| `/plan-feature` | Plan | Creates detailed implementation plan for a feature |
+| `/execute` | Implement | Executes plan with TDD, domain skills, parallel agents |
+| `/validate` | Validate | Runs verification, testing agents, code review |
+| `/ship` | Validate | Commits, pushes, creates PR, finishes branch |
+| `/evolve` | Evolve | Updates rules and knowledge base from learnings |
+| `/setup` | Utility | Checks installed plugins/skills, reports health |
+
+## Scope Levels
+
+- **L0 (Project):** /brainstorm → /create-prd → /plan-project → /create-rules → per-issue L2
+- **L1 (Feature):** /brainstorm → /plan-feature → creates issue(s) → per-issue L2
+- **L2 (Issue):** gh issue view → /prime → /writing-plans → /execute → /validate → /ship
+- **L3 (Bug):** gh issue view → /prime → /systematic-debugging → fix → /validate → /ship
+
+## Mode Selection
+
+For non-trivial tasks, choose your discipline level:
+
+- **Superpowers Mode:** Full PIV+E pipeline — brainstorm → plan → TDD → execute → verify → review → ship → evolve
+- **Standard Mode:** Lighter workflow — plan → implement → validate → ship
+
+## Agents
+
+- **architect-agent** — Codebase knowledge base. Call before structural changes (RETRIEVE/IMPACT/RECORD/PATTERN)
+- **tester-agent** — Web browser testing via playwright-cli (VERIFY/FLOW)
+- **mobile-tester-agent** — Mobile app testing via mobile-mcp (VERIFY/FLOW)
+- **ui-ux-analyzer** — Design audit agent with screenshots and reports
+
+## Rules & References
+
+- Domain-specific rules auto-load from `.claude/rules/` based on file paths being edited
+- Reference templates in `.claude/references/` are loaded on-demand by commands
+- See `docs/customization.md` for adding custom rules and agents
+
+## External Dependencies
+
+Run `/setup` to check what's installed. See `docs/plugin-install-guide.md` for full list.

package/README.md

@@ -0,0 +1,83 @@
+# AIDevelopmentFramework
+
+The system around the AI that makes the AI reliable.
+
+An open-source framework for structured AI-assisted software development. Built on the **PIV+E loop** (Plan, Implement, Validate, Evolve) — a methodology where the human owns planning and validation, the AI owns implementation, and the system gets smarter with every cycle.
+
+## Why This Exists
+
+AI coding assistants are powerful but unpredictable. They lose context, repeat mistakes, and produce code that looks right but isn't. The solution isn't a better AI — it's a better **system around the AI**: plans that survive session boundaries, rules that prevent known mistakes, agents that maintain architectural knowledge, and a self-improving feedback loop.
+
+## Quick Start
+
+### Existing Project
+1. Copy `.claude/` into your project root
+2. Run `/setup` to check installed plugins
+3. Run `/prime` to load context
+4. Run `/start` to begin
+
+### New Project
+1. Copy `.claude/` into your project root
+2. Run `/setup` to install dependencies
+3. Run `/start` and choose "Starting a new project"
+
+## The PIV+E Loop
+
+**Plan** — Brainstorm, write specs, decompose into issues
+**Implement** — TDD, execute plans, use specialist agents
+**Validate** — Automated checks, visual testing, code review
+**Evolve** — Update rules and knowledge from what was learned
+
+## Pipeline Commands
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/start` | Router | Detects what you're doing, routes to the right pipeline |
+| `/prime` | Plan | Loads codebase context into session |
+| `/create-prd` | Plan | Brainstorms and generates a PRD |
+| `/plan-project` | Plan | Decomposes PRD into GitHub milestones and issues |
+| `/plan-feature` | Plan | Creates detailed implementation plan |
+| `/execute` | Implement | Executes plan with TDD, step by step |
+| `/validate` | Validate | Runs lint, tests, visual testing, code review |
+| `/ship` | Validate | Commits, pushes, creates PR |
+| `/evolve` | Evolve | Updates rules and knowledge base |
+| `/setup` | Utility | Checks framework health |
+
+## What's Inside
+
+```
+.claude/
+├── commands/       10 pipeline commands (the workflow)
+├── agents/         4 specialist agents + template
+├── skills/         Framework-specific skills
+├── rules/          Auto-loading domain rules
+├── references/     Templates (PRD, plan, issue, patterns)
+└── hooks/          Guardrails (branch protection, reminders)
+```
+
+## Scope Levels
+
+| Level | Entry Point | Pipeline |
+|-------|------------|---------|
+| L0 | "I have an idea" | /create-prd then /plan-project then per-issue L2 |
+| L1 | "I need a feature" | /plan-feature then per-issue L2 |
+| L2 | "I have issue #42" | /prime then /plan then /execute then /validate then /ship |
+| L3 | "There's a bug" | /prime then debug then fix then /validate then /ship |
+
+## Documentation
+
+- [Methodology](docs/methodology.md) — The PIV+E loop explained
+- [Getting Started](docs/getting-started.md) — Setup and walkthrough
+- [Command Reference](docs/command-reference.md) — All commands
+- [Customization](docs/customization.md) — Adding agents, rules, skills
+- [Plugin Install Guide](docs/plugin-install-guide.md) — Dependencies
+
+## Credits
+
+Synthesizes approaches from:
+- [Cole Medin's AI Coding Summit Workshop](https://github.com/coleam00/ai-coding-summit-workshop-2) — PIV loop, context resets, plan-as-specification
+- Real-world battle-tested Claude Code configurations from production development
+
+## License
+
+MIT

package/cli/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'init':
+    require('./init.js');
+    break;
+  case 'update':
+    require('./update.js');
+    break;
+  case '--version':
+  case '-v':
+    console.log(require('../package.json').version);
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(`
+AIDevelopmentFramework — The system around the AI that makes the AI reliable.
+
+Usage:
+  npx ai-framework init          Download and set up the framework in the current project
+  npx ai-framework update        Update framework files to the latest version
+  npx ai-framework --version     Show version
+  npx ai-framework --help        Show this help message
+
+Docs: https://github.com/cristian-robert/AIDevelopmentFramework
+    `);
+    break;
+  default:
+    console.error('Unknown command: ' + command);
+    console.log('Run "npx ai-framework --help" for usage information.');
+    process.exit(1);
+}

package/cli/init.js

@@ -0,0 +1,219 @@
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const readline = require('readline');
+
+const REPO = 'cristian-robert/AIDevelopmentFramework';
+const BRANCH = 'main';
+const TARBALL_URL = 'https://github.com/' + REPO + '/archive/refs/heads/' + BRANCH + '.tar.gz';
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(question) {
+  return new Promise(function (resolve) {
+    rl.question(question, resolve);
+  });
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  var entries = fs.readdirSync(src, { withFileTypes: true });
+  for (var i = 0; i < entries.length; i++) {
+    var entry = entries[i];
+    var srcPath = path.join(src, entry.name);
+    var destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function downloadFramework(targetDir) {
+  var tmpDir = path.join(require('os').tmpdir(), 'ai-framework-' + Date.now());
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  console.log('Downloading latest framework from GitHub...');
+
+  try {
+    // Download and extract tarball
+    execFileSync('curl', ['-sL', TARBALL_URL, '-o', path.join(tmpDir, 'framework.tar.gz')]);
+    execFileSync('tar', ['-xzf', path.join(tmpDir, 'framework.tar.gz'), '-C', tmpDir, '--strip-components=1']);
+
+    // Copy .claude/ folder
+    var sourceClaudeDir = path.join(tmpDir, '.claude');
+    var targetClaudeDir = path.join(targetDir, '.claude');
+
+    if (fs.existsSync(sourceClaudeDir)) {
+      console.log('Installing .claude/ framework structure...');
+      copyDirRecursive(sourceClaudeDir, targetClaudeDir);
+    }
+
+    // Copy docs/ folder
+    var sourceDocsDir = path.join(tmpDir, 'docs');
+    var targetDocsDir = path.join(targetDir, 'docs');
+
+    if (fs.existsSync(sourceDocsDir)) {
+      console.log('Installing docs/...');
+      copyDirRecursive(sourceDocsDir, targetDocsDir);
+    }
+
+    return true;
+  } catch (err) {
+    console.error('Download failed: ' + err.message);
+    console.log('');
+    console.log('Falling back to local copy...');
+    return false;
+  } finally {
+    // Cleanup tmp
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch (e) {
+      // ignore cleanup errors
+    }
+  }
+}
+
+function detectTechStack() {
+  var detected = [];
+  try {
+    var pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+    var deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+    if (deps['next']) detected.push('Next.js');
+    if (deps['react']) detected.push('React');
+    if (deps['vue']) detected.push('Vue');
+    if (deps['svelte'] || deps['@sveltejs/kit']) detected.push('Svelte');
+    if (deps['express']) detected.push('Express');
+    if (deps['@nestjs/core']) detected.push('NestJS');
+    if (deps['expo']) detected.push('Expo');
+    if (deps['@supabase/supabase-js']) detected.push('Supabase');
+    if (deps['tailwindcss']) detected.push('Tailwind');
+    if (deps['stripe']) detected.push('Stripe');
+    if (deps['prisma'] || deps['@prisma/client']) detected.push('Prisma');
+    if (deps['drizzle-orm']) detected.push('Drizzle');
+    if (deps['mongoose']) detected.push('MongoDB/Mongoose');
+  } catch (e) {
+    // No package.json or parse error
+  }
+
+  if (fs.existsSync('requirements.txt') || fs.existsSync('pyproject.toml')) {
+    detected.push('Python');
+    try {
+      var reqContent = '';
+      if (fs.existsSync('requirements.txt')) {
+        reqContent = fs.readFileSync('requirements.txt', 'utf-8');
+      } else if (fs.existsSync('pyproject.toml')) {
+        reqContent = fs.readFileSync('pyproject.toml', 'utf-8');
+      }
+      if (reqContent.includes('fastapi')) detected.push('FastAPI');
+      if (reqContent.includes('django')) detected.push('Django');
+      if (reqContent.includes('flask')) detected.push('Flask');
+    } catch (e) {
+      // ignore read errors
+    }
+  }
+  if (fs.existsSync('go.mod')) detected.push('Go');
+  if (fs.existsSync('Cargo.toml')) detected.push('Rust');
+
+  return detected;
+}
+
+async function main() {
+  console.log('');
+  console.log('  AIDevelopmentFramework');
+  console.log('  The system around the AI that makes the AI reliable.');
+  console.log('');
+
+  var targetDir = process.cwd();
+  var hasGit = fs.existsSync('.git');
+  var hasClaudeDir = fs.existsSync('.claude');
+
+  // Check if .claude/ already exists
+  if (hasClaudeDir) {
+    var overwrite = await ask('.claude/ already exists. Overwrite? (yes/no): ');
+    if (overwrite.toLowerCase() !== 'yes' && overwrite.toLowerCase() !== 'y') {
+      console.log('Aborted. Use "npx ai-framework update" to update existing installation.');
+      rl.close();
+      return;
+    }
+  }
+
+  // Detect tech stack
+  var stack = detectTechStack();
+  if (stack.length > 0) {
+    console.log('Detected tech stack: ' + stack.join(', '));
+  }
+
+  // Download from GitHub (latest version)
+  var downloaded = downloadFramework(targetDir);
+
+  // Fall back to local copy if download fails (when installed via npm)
+  if (!downloaded) {
+    var frameworkDir = path.join(__dirname, '..');
+    var localClaudeDir = path.join(frameworkDir, '.claude');
+    if (fs.existsSync(localClaudeDir)) {
+      console.log('Copying from local package...');
+      copyDirRecursive(localClaudeDir, path.join(targetDir, '.claude'));
+
+      var localDocsDir = path.join(frameworkDir, 'docs');
+      if (fs.existsSync(localDocsDir)) {
+        copyDirRecursive(localDocsDir, path.join(targetDir, 'docs'));
+      }
+    } else {
+      console.error('No local framework files found. Please check your installation.');
+      rl.close();
+      process.exit(1);
+    }
+  }
+
+  // Create docs/plans directory
+  var plansDir = path.join(targetDir, 'docs', 'plans');
+  if (!fs.existsSync(plansDir)) {
+    fs.mkdirSync(plansDir, { recursive: true });
+  }
+
+  // Init git if needed
+  if (!hasGit) {
+    var initGit = await ask('No git repo found. Initialize one? (yes/no): ');
+    if (initGit.toLowerCase() === 'yes' || initGit.toLowerCase() === 'y') {
+      try {
+        execFileSync('git', ['init']);
+        execFileSync('git', ['branch', '-m', 'main']);
+        console.log('Git repository initialized.');
+      } catch (e) {
+        console.log('Could not initialize git: ' + e.message);
+      }
+    }
+  }
+
+  console.log('');
+  console.log('Setup complete!');
+  console.log('');
+  console.log('Installed:');
+  console.log('  .claude/commands/    10 pipeline commands');
+  console.log('  .claude/agents/      4 specialist agents + template');
+  console.log('  .claude/skills/      2 framework skills');
+  console.log('  .claude/rules/       6 domain rules + template');
+  console.log('  .claude/references/  5 templates');
+  console.log('  .claude/hooks/       5 guardrails');
+  console.log('  docs/                methodology + guides');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Open Claude Code in this project');
+  console.log('  2. Run /setup to check plugin dependencies');
+  console.log('  3. Run /start to begin');
+  console.log('');
+
+  rl.close();
+}
+
+main().catch(function (err) {
+  console.error('Error: ' + err.message);
+  process.exit(1);
+});