ai-development-framework 0.1.0

package/cli/update.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const REPO = 'cristian-robert/AIDevelopmentFramework';
+const BRANCH = 'main';
+const TARBALL_URL = 'https://github.com/' + REPO + '/archive/refs/heads/' + BRANCH + '.tar.gz';
+
+// Files that are project-specific and should NOT be overwritten
+var PROTECTED_FILES = [
+  '.claude/agents/architect-agent/index.md',
+  '.claude/agents/architect-agent/shared/patterns.md',
+  '.claude/agents/architect-agent/decisions/log.md',
+  '.claude/agents/tester-agent/test-patterns.md',
+  '.claude/agents/tester-agent/auth-state.md',
+  '.claude/agents/mobile-tester-agent/screen-patterns.md',
+  '.claude/references/code-patterns.md',
+  '.claude/settings.local.json',
+];
+
+// Directories with project-specific content that should NOT be overwritten
+var PROTECTED_DIRS = [
+  '.claude/agents/architect-agent/modules',
+  '.claude/agents/architect-agent/frontend',
+];
+
+function copyDirRecursive(src, dest, protectedFiles, protectedDirs) {
+  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);
+    var relativePath = path.relative(process.cwd(), destPath);
+
+    if (entry.isDirectory()) {
+      // Skip protected directories entirely
+      if (protectedDirs.some(function (d) { return relativePath.startsWith(d); })) {
+        continue;
+      }
+      copyDirRecursive(srcPath, destPath, protectedFiles, protectedDirs);
+    } else {
+      // Skip protected files
+      if (protectedFiles.indexOf(relativePath) !== -1) {
+        console.log('  Skipped (project-specific): ' + relativePath);
+        continue;
+      }
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function main() {
+  console.log('');
+  console.log('  AIDevelopmentFramework — Update');
+  console.log('');
+
+  if (!fs.existsSync('.claude')) {
+    console.error('No .claude/ directory found. Run "npx ai-framework init" first.');
+    process.exit(1);
+  }
+
+  var tmpDir = path.join(require('os').tmpdir(), 'ai-framework-update-' + Date.now());
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  console.log('Downloading latest framework from GitHub...');
+
+  try {
+    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']);
+
+    var sourceClaudeDir = path.join(tmpDir, '.claude');
+    var targetClaudeDir = path.join(process.cwd(), '.claude');
+
+    if (fs.existsSync(sourceClaudeDir)) {
+      console.log('Updating .claude/ (preserving project-specific files)...');
+      copyDirRecursive(sourceClaudeDir, targetClaudeDir, PROTECTED_FILES, PROTECTED_DIRS);
+    }
+
+    // Update docs (but not docs/plans/ which contains project plans)
+    var sourceDocsDir = path.join(tmpDir, 'docs');
+    var targetDocsDir = path.join(process.cwd(), 'docs');
+    if (fs.existsSync(sourceDocsDir)) {
+      console.log('Updating docs/...');
+      var docEntries = fs.readdirSync(sourceDocsDir, { withFileTypes: true });
+      for (var i = 0; i < docEntries.length; i++) {
+        var entry = docEntries[i];
+        if (entry.isFile()) {
+          fs.copyFileSync(
+            path.join(sourceDocsDir, entry.name),
+            path.join(targetDocsDir, entry.name)
+          );
+        }
+        // Skip docs/plans/ and docs/superpowers/ — project-specific
+      }
+    }
+
+    console.log('');
+    console.log('Update complete!');
+    console.log('');
+    console.log('Updated: commands, agent protocols, rules templates, hooks, skills, docs');
+    console.log('Preserved: agent knowledge bases, test patterns, auth state, code patterns, settings, plans');
+    console.log('');
+    console.log('Run /setup to check if new plugins are required.');
+    console.log('');
+  } catch (err) {
+    console.error('Update failed: ' + err.message);
+    process.exit(1);
+  } finally {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch (e) {
+      // ignore cleanup errors
+    }
+  }
+}
+
+main();

package/docs/command-reference.md

@@ -0,0 +1,41 @@
+# Command Reference
+
+## /start — Smart Router
+**Phase:** Router | **Arguments:** None
+Detects scope level and routes to the correct pipeline.
+
+## /prime — Context Loader
+**Phase:** Plan | **Arguments:** None
+Loads codebase context. Run at session start or after context reset.
+
+## /create-prd — PRD Generator
+**Phase:** Plan (L0) | **Arguments:** Optional idea description
+Brainstorms and generates a Product Requirements Document. Output: `docs/plans/PRD.md`
+
+## /plan-project — PRD Decomposer
+**Phase:** Plan (L0) | **Arguments:** Optional PRD path (default: `docs/plans/PRD.md`)
+Breaks PRD into GitHub milestones and issues. Output: GitHub issues + `docs/plans/roadmap.md`
+
+## /plan-feature — Feature Planner
+**Phase:** Plan (L1/L2) | **Arguments:** Feature description or issue number (e.g., `#42`)
+5-phase analysis producing a detailed implementation plan. Output: `docs/plans/<feature>.md`
+
+## /execute — Plan Executor
+**Phase:** Implement | **Arguments:** Optional plan path (auto-detected if omitted)
+Executes plan task-by-task with TDD. Reads mandatory files, runs validation commands.
+
+## /validate — Verification Orchestrator
+**Phase:** Validate | **Arguments:** None
+Runs lint, tests, type-check, visual testing (tester agents), and code review.
+
+## /ship — Commit + Push + PR
+**Phase:** Validate | **Arguments:** None
+Stages, commits (conventional), pushes, creates PR linked to issue.
+
+## /evolve — Self-Improvement
+**Phase:** Evolve | **Arguments:** None
+Updates CLAUDE.md, architect knowledge base, rules, code patterns, test patterns.
+
+## /setup — Health Check
+**Phase:** Utility | **Arguments:** None
+Checks installed plugins, skills, MCP servers. Reports health and install commands.

package/docs/customization.md

@@ -0,0 +1,33 @@
+# Customization Guide
+
+## Adding Custom Rules
+
+1. Copy `.claude/rules/_template.md` to `.claude/rules/your-domain.md`
+2. Set the `globs` pattern to match your file paths
+3. Add your conventions and skill chains
+4. Rules auto-load when editing matching files
+
+## Adding Custom Agents
+
+1. Copy `.claude/agents/_template/AGENT.md` to `.claude/agents/your-agent/AGENT.md`
+2. Define query types, tools, and response format
+3. Add knowledge base files as needed
+4. Reference the agent from your commands or rules
+
+## Customizing Commands
+
+Commands are markdown files in `.claude/commands/`. Edit existing commands or add new ones. Commands are invoked as `/command-name` in Claude Code.
+
+## Customizing Hooks
+
+Hooks are shell scripts in `.claude/hooks/`. Edit existing hooks or add new ones. Make sure hooks are executable (`chmod +x`).
+
+## Overriding Rules per Project
+
+Each project gets its own `.claude/` folder. Customize CLAUDE.md, rules, and agent knowledge bases per project. The framework's commands stay the same.
+
+## Contributing
+
+1. Fork the repository
+2. Add your contribution
+3. Submit a PR with description, usage, and testing notes

package/docs/getting-started.md

@@ -0,0 +1,68 @@
+# Getting Started
+
+## Quick Start (Existing Project)
+
+1. Copy the `.claude/` folder into your project root
+2. Run `/setup` to check what plugins/skills you need
+3. Install missing dependencies (commands provided by /setup)
+4. Run `/prime` to load your codebase context
+5. Run `/start` to begin your first task
+
+## Quick Start (New Project)
+
+1. Copy the `.claude/` folder into your project root
+2. Run `/setup` to check dependencies
+3. Run `/start` — it will detect a new project and guide you through:
+   - `/create-prd` — brainstorm and define what you're building
+   - `/plan-project` — create GitHub issues from the PRD
+   - Per-issue implementation via the PIV+E loop
+
+## Your First Feature (Walkthrough)
+
+### 1. Start
+```
+/start
+> What are you working on? -> 3. Working on a specific GitHub issue
+> Issue number? -> #1
+```
+
+### 2. Plan
+```
+/plan-feature #1
+```
+Review the plan. Adjust if needed.
+
+### 3. Implement
+```
+/execute docs/plans/my-feature.md
+```
+
+### 4. Validate
+```
+/validate
+```
+
+### 5. Ship
+```
+/ship
+```
+
+### 6. Evolve (after merge)
+```
+/evolve
+```
+
+## Commands Quick Reference
+
+| Command | When to Use |
+|---------|------------|
+| `/start` | Beginning of any work session |
+| `/prime` | Load/reload codebase context |
+| `/create-prd` | Planning a new project from scratch |
+| `/plan-project` | Breaking a PRD into GitHub issues |
+| `/plan-feature` | Planning a specific feature |
+| `/execute` | Implementing a plan |
+| `/validate` | Verifying work before shipping |
+| `/ship` | Committing, pushing, creating PR |
+| `/evolve` | Updating the system after completing work |
+| `/setup` | Checking framework health |

package/docs/methodology.md

@@ -0,0 +1,78 @@
+# PIV+E Methodology
+
+A tool-agnostic methodology for reliable AI-assisted software development.
+
+## The Problem
+
+AI coding assistants are powerful but unpredictable. They write code that looks right but subtly isn't. They lose context. They make the same mistakes repeatedly. The solution isn't a better AI — it's a better system around the AI.
+
+## The PIV+E Loop
+
+```
+PLAN -> IMPLEMENT -> VALIDATE -> EVOLVE
+  ^                               |
+  +-------------------------------+
+        System gets smarter
+```
+
+### Plan (Human decides, AI structures)
+
+The human owns what gets built. The AI helps structure the thinking.
+
+- **Brainstorm** the idea — explore alternatives, constraints, tradeoffs
+- **Write a spec** (PRD for projects, plan for features)
+- **Decompose** into implementable units (GitHub issues)
+
+The key output is a plan document that passes the "no prior knowledge test."
+
+### Implement (AI executes, guided by plan)
+
+The AI does the heavy lifting, constrained by the plan.
+
+- **Test-Driven Development** — write the test first, then make it pass
+- **Follow the plan** — don't improvise, don't add features, don't refactor unrelated code
+- **Use specialists** — architecture agents, design skills, framework-specific tools
+- **Commit frequently** — small, atomic commits after each task
+
+### Validate (Human + AI verify together)
+
+Both human and AI verify the work.
+
+- **Automated checks** — lint, type-check, test suite (AI runs these)
+- **Visual verification** — browser/mobile testing agents (AI runs these)
+- **Code review** — review agents flag issues (AI runs, human decides)
+- **Human review** — the final authority (human approves the PR)
+
+### Evolve (System learns from each cycle)
+
+The system improves after every cycle.
+
+- **Update rules** — new patterns become rules, mistakes become warnings
+- **Update knowledge base** — architecture agent learns new modules/endpoints
+- **Update test patterns** — new pages/screens get added to test inventories
+- **Record decisions** — why things were done this way
+
+## Context Management
+
+- **Plans are artifacts** — they survive session boundaries
+- **Context resets are a feature** — start fresh for implementation after heavy planning
+- **Progressive disclosure** — load information as needed, not all at once
+- **Knowledge bases** — structured information that agents can query
+
+## Discipline Scaling
+
+| Complexity | Ceremony Level |
+|-----------|---------------|
+| XL (new module) | Full PIV+E with brainstorming, PRD, parallel agents |
+| L (new feature) | Plan + TDD + testing agents |
+| M (single task) | Quick plan + implement + verify |
+| S (tweak) | Just do it + verify |
+| Bug | Debug + fix + verify |
+
+## Principles
+
+1. Context is precious — manage it deliberately
+2. Plans are artifacts — they survive session boundaries
+3. Discipline scales with complexity
+4. The system self-improves — every mistake becomes a rule
+5. Human stays in control — AI assists, human decides