ai-development-framework 0.1.0 → 0.1.2

package/cli/update.js

@@ -1,58 +1,123 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const readline = require('readline');
+const { PROTECTED_FILES, PROTECTED_DIRS, CUSTOMIZABLE_FILES, toProjectRelative } = require('./protected-files');
 
 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) {
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(question) {
+  return new Promise(function (resolve) {
+    rl.question(question, resolve);
+  });
+}
+
+function isTemplateContent(filePath) {
+  try {
+    var content = fs.readFileSync(filePath, 'utf-8');
+    if (content.includes('> Populated by /create-rules')) return true;
+    if (content.includes('> Populated when /create-rules')) return true;
+    if (content.includes('> No decisions recorded yet')) return true;
+    if (content.includes('Run `/create-rules` to populate')) return true;
+    if (content.includes('> This section is populated as the project grows')) return true;
+    return false;
+  } catch (e) {
+    return false;
+  }
+}
+
+function copyDirWithProtection(src, dest, projectRoot, customizedAction) {
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
   }
   var entries = fs.readdirSync(src, { withFileTypes: true });
+  var stats = { updated: 0, skipped: 0, backedUp: 0 };
   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);
+    var projectRelPath = toProjectRelative(destPath, projectRoot);
 
     if (entry.isDirectory()) {
-      // Skip protected directories entirely
-      if (protectedDirs.some(function (d) { return relativePath.startsWith(d); })) {
+      var isProtectedDir = PROTECTED_DIRS.some(function (d) {
+        return projectRelPath === d || projectRelPath.startsWith(d + '/');
+      });
+      if (isProtectedDir && fs.existsSync(destPath)) {
+        console.log('  Skipped (project-specific): ' + projectRelPath + '/');
+        try {
+          var dirFiles = fs.readdirSync(destPath, { recursive: true });
+          stats.skipped += dirFiles.length || 1;
+        } catch (e) {
+          stats.skipped++;
+        }
         continue;
       }
-      copyDirRecursive(srcPath, destPath, protectedFiles, protectedDirs);
+      var sub = copyDirWithProtection(srcPath, destPath, projectRoot, customizedAction);
+      stats.updated += sub.updated;
+      stats.skipped += sub.skipped;
+      stats.backedUp += sub.backedUp;
     } else {
-      // Skip protected files
-      if (protectedFiles.indexOf(relativePath) !== -1) {
-        console.log('  Skipped (project-specific): ' + relativePath);
+      if (!fs.existsSync(destPath)) {
+        // New file — always install
+        var destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir)) {
+          fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(srcPath, destPath);
+        stats.updated++;
         continue;
       }
+
+      // Protected file — skip if it has real content, update if still template
+      if (PROTECTED_FILES.indexOf(projectRelPath) !== -1) {
+        if (!isTemplateContent(destPath)) {
+          console.log('  Skipped (project-specific): ' + projectRelPath);
+          stats.skipped++;
+        } else {
+          fs.copyFileSync(srcPath, destPath);
+          stats.updated++;
+        }
+        continue;
+      }
+
+      // Customizable file — apply chosen action
+      if (CUSTOMIZABLE_FILES.indexOf(projectRelPath) !== -1) {
+        var srcContent = fs.readFileSync(srcPath, 'utf-8');
+        var destContent = fs.readFileSync(destPath, 'utf-8');
+        if (srcContent !== destContent) {
+          if (customizedAction === 'keep') {
+            console.log('  Skipped (customized): ' + projectRelPath);
+            stats.skipped++;
+            continue;
+          } else if (customizedAction === 'backup') {
+            var timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            var backupPath = destPath + '.' + timestamp + '.backup';
+            fs.copyFileSync(destPath, backupPath);
+            console.log('  Backed up: ' + projectRelPath);
+            fs.copyFileSync(srcPath, destPath);
+            stats.backedUp++;
+            stats.updated++;
+            continue;
+          }
+          // 'overwrite' falls through
+        }
+      }
+
       fs.copyFileSync(srcPath, destPath);
+      stats.updated++;
     }
   }
+  return stats;
 }
 
-function main() {
+async function main() {
   console.log('');
   console.log('  AIDevelopmentFramework — Update');
   console.log('');
@@ -62,6 +127,7 @@ function main() {
     process.exit(1);
   }
 
+  var projectRoot = process.cwd();
   var tmpDir = path.join(require('os').tmpdir(), 'ai-framework-update-' + Date.now());
   fs.mkdirSync(tmpDir, { recursive: true });
 
@@ -71,40 +137,63 @@ function main() {
     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']);
 
+    // Ask about customized files
+    var customizedAction = 'keep';
+    console.log('');
+    var choice = await ask(
+      '  How should customized rules/hooks be handled?\n' +
+      '    1. Keep mine     — preserve your customizations (default)\n' +
+      '    2. Use framework — overwrite with latest framework versions\n' +
+      '    3. Backup + update — save yours as .backup, install new versions\n' +
+      '  Choice (1/2/3): '
+    );
+
+    if (choice === '2') customizedAction = 'overwrite';
+    else if (choice === '3') customizedAction = 'backup';
+
     var sourceClaudeDir = path.join(tmpDir, '.claude');
-    var targetClaudeDir = path.join(process.cwd(), '.claude');
+    var targetClaudeDir = path.join(projectRoot, '.claude');
 
     if (fs.existsSync(sourceClaudeDir)) {
-      console.log('Updating .claude/ (preserving project-specific files)...');
-      copyDirRecursive(sourceClaudeDir, targetClaudeDir, PROTECTED_FILES, PROTECTED_DIRS);
-    }
+      console.log('');
+      console.log('Updating .claude/ ...');
+      console.log('');
+      var stats = copyDirWithProtection(sourceClaudeDir, targetClaudeDir, projectRoot, customizedAction);
 
-    // 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)
-          );
+      // Update docs (but not docs/plans/ or docs/superpowers/)
+      var sourceDocsDir = path.join(tmpDir, 'docs');
+      var targetDocsDir = path.join(projectRoot, 'docs');
+      if (fs.existsSync(sourceDocsDir)) {
+        console.log('');
+        console.log('Updating docs/...');
+        if (!fs.existsSync(targetDocsDir)) {
+          fs.mkdirSync(targetDocsDir, { recursive: true });
+        }
+        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)
+            );
+            stats.updated++;
+          }
         }
-        // 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('');
+      console.log('');
+      console.log('Update complete!');
+      console.log('');
+      console.log('  Updated:   ' + stats.updated + ' files');
+      console.log('  Skipped:   ' + stats.skipped + ' files (preserved your customizations)');
+      if (stats.backedUp > 0) {
+        console.log('  Backed up: ' + stats.backedUp + ' files (saved as .backup)');
+      }
+      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);
@@ -112,8 +201,9 @@ function main() {
     try {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     } catch (e) {
-      // ignore cleanup errors
+      // ignore
     }
+    rl.close();
   }
 }
 

package/docs/customization.md

@@ -26,6 +26,62 @@ Hooks are shell scripts in `.claude/hooks/`. Edit existing hooks or add new ones
 
 Each project gets its own `.claude/` folder. Customize CLAUDE.md, rules, and agent knowledge bases per project. The framework's commands stay the same.
 
+## Configuring the Knowledge Base
+
+The framework includes an optional project knowledge base (Obsidian-compatible) that gives the agent persistent project understanding across sessions.
+
+### Enable
+
+Add to your project's `CLAUDE.md`:
+
+```markdown
+## Knowledge Base
+
+Path: .obsidian/
+```
+
+### Custom Path
+
+Use any folder name:
+
+```markdown
+## Knowledge Base
+
+Path: knowledge/
+```
+
+**Note:** The framework's `.gitignore` only covers Obsidian config files under `.obsidian/`. If you use a custom path and open it as an Obsidian vault, add these entries to your `.gitignore` (replacing `knowledge/` with your path):
+
+```
+knowledge/app.json
+knowledge/appearance.json
+knowledge/core-plugins.json
+knowledge/core-plugins-migration.json
+knowledge/workspace.json
+knowledge/workspace-mobile.json
+knowledge/hotkeys.json
+knowledge/plugins/
+knowledge/themes/
+```
+
+### Disable
+
+Remove the `## Knowledge Base` section from CLAUDE.md. All knowledge operations are skipped — commands work exactly as before.
+
+### What It Does
+
+Pipeline commands automatically read from and write to the knowledge base:
+- `/start` creates the structure when starting a new project
+- `/prime` loads relevant notes for context before work
+- `/create-prd` seeds the knowledge base from the PRD
+- `/plan-project` creates feature notes alongside GitHub issues
+- `/execute` reads related feature notes before implementing
+- `/ship` updates feature notes after completing work
+
+### Obsidian
+
+If you have [Obsidian](https://obsidian.md/) installed, open your project folder as a vault. The `.obsidian/` directory makes it a valid vault. Notes are navigable, linkable, and searchable through Obsidian's UI. Obsidian is not required — the notes are plain markdown.
+
 ## Contributing
 
 1. Fork the repository

package/docs/plans/2026-04-04-knowledge-base-integration-design.md

@@ -0,0 +1,209 @@
+# Knowledge Base Integration Design
+
+**Date:** 2026-04-04
+**Status:** Approved
+
+## Problem
+
+The agent starts each session with no project-level context beyond what it can read from code and git history. It doesn't know what features are planned, why decisions were made, or how features relate to each other. This leads to:
+
+- Agent trying to implement entire projects in one shot instead of following the issue-based pipeline
+- No persistent project understanding across sessions
+- Brainstorming insights lost after the session ends
+- No automatic check for related features/decisions before starting work
+
+## Solution
+
+Add an optional, Obsidian-compatible knowledge base (`.obsidian/` by default) that pipeline commands read from and write to at natural checkpoints. The knowledge base complements the existing architect-agent (code-level knowledge) with project-level understanding.
+
+## Design
+
+### Knowledge Base Structure
+
+Default path: `.obsidian/` (configurable via `Knowledge Base: <path>` in project CLAUDE.md).
+
+```
+.obsidian/
+├── app.json                     # Obsidian config (gitignored)
+├── appearance.json              # Obsidian config (gitignored)
+├── core-plugins.json            # Obsidian config (gitignored)
+├── workspace.json               # Obsidian config (gitignored)
+├── overview.md                  # Project vision, goals, tech stack, target users
+├── architecture/
+│   └── system-design.md         # High-level architecture, component diagram
+├── features/
+│   ├── feature-name.md          # One per feature area, links to GitHub issues
+│   └── ...
+├── decisions/
+│   └── NNN-title.md             # ADR format: context, decision, consequences
+├── config/
+│   └── integrations.md          # Third-party services, env var names (never store actual secrets)
+└── research/
+    └── ...                      # Brainstorming notes, tech comparisons
+```
+
+### Gitignore Rules
+
+Obsidian config files are gitignored (machine-specific). Notes are committed.
+
+```
+.obsidian/app.json
+.obsidian/appearance.json
+.obsidian/core-plugins.json
+.obsidian/core-plugins-migration.json
+.obsidian/workspace.json
+.obsidian/hotkeys.json
+.obsidian/plugins/
+.obsidian/themes/
+```
+
+### Feature Note Template
+
+```markdown
+# Feature: [Name]
+
+## Summary
+[1-2 sentences: what this feature does and why]
+
+## GitHub Issues
+- #N — [title] (status)
+- #N — [title] (status)
+
+## Key Decisions
+- [Decision and why]
+
+## Implementation Notes
+[Updated after work is completed — endpoints created, components built, patterns used]
+```
+
+### Decision Record Template
+
+```markdown
+# NNN: [Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+
+## Context
+[What situation led to this decision]
+
+## Decision
+[What we chose and why]
+
+## Consequences
+[What this means for future work — both positive and negative]
+```
+
+## Command Integration
+
+### `/start` — New L0 Behavior
+
+Detects empty project → routes to new flow:
+1. Brainstorm functionalities (interactive)
+2. Create `.obsidian/` structure with `overview.md`
+3. Create feature notes in `.obsidian/features/`
+4. Create GitHub issues linked to feature notes
+5. STOP — ask user which issue to work on
+
+### `/prime` — Smart Knowledge Loading
+
+Add to existing context loading:
+1. Read `.obsidian/overview.md` (always)
+2. If working on a specific issue → read the linked feature note
+3. Scan other feature note filenames + summaries → pull in related ones
+4. Include knowledge context in session summary output
+
+### `/create-prd` — Knowledge Base Seeding
+
+Add after saving PRD:
+1. Create `.obsidian/overview.md` extracted from PRD (vision, goals, tech stack, users)
+2. Create `.obsidian/architecture/system-design.md` from PRD's architecture section
+
+### `/plan-project` — Feature Notes Alongside Issues
+
+Add after creating each GitHub issue:
+1. Create `.obsidian/features/<feature-name>.md` with the feature template
+2. Link the GitHub issue numbers in the note
+3. If architectural decisions were made during brainstorming, create `.obsidian/decisions/NNN-title.md`
+
+### `/ship` — Knowledge Update Checkpoint
+
+Add before committing:
+1. Read the feature note for the issue being completed
+2. Update `## Implementation Notes` with what was built
+3. Update `## GitHub Issues` status if issue is being closed
+4. If a significant decision was made, create a decision record
+5. Commit knowledge updates alongside code
+
+### `/execute` — Knowledge-Aware Context
+
+Add to mandatory file reading step:
+1. Check `.obsidian/` for the feature note linked to the current issue
+2. Read related feature notes (smart/targeted scan)
+3. Check `.obsidian/decisions/` for relevant past decisions
+
+## Read-Before-Work Flow (Smart/Targeted)
+
+When the agent starts work on an issue:
+
+1. **Always read:** `overview.md` + directly linked feature note
+2. **Scan for related:** list `.obsidian/features/`, read first 5 lines of each, pull in notes with clear dependency/overlap
+3. **Check decisions:** scan `.obsidian/decisions/` titles, read relevant ones
+4. **Check codebase:** existing `/prime` behavior (code structure, git history, architect-agent)
+
+### Issue-to-Feature Linking
+
+- Feature notes list issue numbers in `## GitHub Issues`
+- Agent greps `.obsidian/features/*.md` for the current issue number
+- Fallback: keyword matching between issue title and feature note filenames/summaries
+
+## Write-After-Work Flow (End of Issue)
+
+Triggered by `/ship`:
+
+### Updated:
+- **Feature note:** `## Implementation Notes`, `## GitHub Issues` status, `## Key Decisions`
+- **Decision records:** only when a technology/approach was chosen over alternatives, a pattern was established, or something was intentionally excluded
+
+### Updated only when significant:
+- **Overview:** only when new integration added or scope changed
+
+### Not updated:
+- Bug fixes (L3) unless they reveal a design decision
+- Unrelated feature notes
+- No full rewrites — only append/update relevant sections
+
+## Configuration & Optionality
+
+### CLAUDE.md Configuration
+
+```markdown
+## Knowledge Base
+
+Path: .obsidian/
+```
+
+When path is set → commands read/write from it.
+When absent → knowledge operations skipped entirely. Zero impact.
+
+### `/init-claude-md` Integration
+
+During setup, ask:
+1. Yes, use `.obsidian/` (default)
+2. Yes, custom path
+3. No — skip knowledge base
+
+### Guard Behavior
+
+Every command that touches the knowledge base:
+1. Read project CLAUDE.md → look for `Knowledge Base` path
+2. If not found → skip all knowledge operations
+3. If found → check folder exists
+4. If folder doesn't exist → create it with initial structure
+
+## Relationship to Existing Systems
+
+- **architect-agent:** Keeps code-level knowledge (modules, endpoints, patterns). Knowledge base holds project-level understanding. Agent reads both.
+- **docs/plans/:** Untouched. Superpowers skills write here. Knowledge base is additive.
+- **docs/superpowers/plans/:** Untouched. Same reason.
+- **Obsidian:** Optional. The `.obsidian/` folder works as plain markdown without Obsidian installed. Obsidian users get a navigable vault for free.