devforgeai 1.0.7 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devforgeai",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "DevForgeAI is a spec-driven development framework designed to enable AI-assisted software development with zero technical debt through automated validation, architectural constraints enforcement, and test-driven development workflows.",
   "keywords": [
     "ai",
@@ -38,7 +38,7 @@
     "src/claude/skills/",
     "src/scripts/*.sh",
     "src/scripts/*.json",
-    "devforgeai/specs/context/"
+    "docs/"
   ],
   "repository": {
     "type": "git",

package/src/cli/commands/install.js

@@ -204,9 +204,14 @@ async function action(directory, opts) {
       ide: ['claude-code'],
     });
 
-    // IDE setup
+    // IDE setup (merge settings on update, overwrite on reinstall)
     const claudeCode = new ClaudeCodeIDE();
-    await claudeCode.setup(installDir, copier);
+    const ideResult = await claudeCode.setup(installDir, copier, {
+      reinstall: !opts._updateMode,
+    });
+    if (!opts.quiet && ideResult.message) {
+      formatter.info(ideResult.message);
+    }
 
     // Phase 9: Summary
     if (!opts.quiet) {

package/src/cli/lib/components.js

@@ -11,7 +11,6 @@ const COMPONENTS = [
       { from: 'CLAUDE.md', to: 'CLAUDE.md', template: true },
       { from: 'src/claude/rules/', to: '.claude/rules/', template: false },
       { from: 'src/claude/memory/', to: '.claude/memory/', template: false },
-      { from: 'devforgeai/specs/context/', to: 'devforgeai/specs/context/', template: true },
     ],
   },
   {
@@ -71,15 +70,12 @@ const COMPONENTS = [
     required: false,
     defaultSelected: true,
     directories: [
-      'src/',
-      'tests/',
-      'docs/',
       'devforgeai/',
-      'devforgeai/specs/',
-      'devforgeai/specs/adrs/',
-      'devforgeai/specs/Stories/',
-      'devforgeai/specs/Epics/',
-      'tmp/',
+    ],
+    sources: [
+      { from: 'docs/api/', to: 'docs/api/', template: false },
+      { from: 'docs/architecture/', to: 'docs/architecture/', template: false },
+      { from: 'docs/guides/', to: 'docs/guides/', template: false },
     ],
   },
 ];

package/src/cli/lib/ide/claude-code.js

@@ -1,23 +1,38 @@
+const path = require('path');
+const fs = require('fs');
+const fsp = fs.promises;
 const { BaseIDE } = require('./base');
+const { SettingsMerger } = require('../settings-merger');
 
 class ClaudeCodeIDE extends BaseIDE {
   constructor() {
     super({ name: 'claude-code', displayName: 'Claude Code' });
   }
 
-  async setup(targetRoot, copier) {
-    // Claude Code uses .claude/ directory which is already handled
-    // by the core-framework, agents, skills, commands, hooks components.
-    // This integration ensures the directory structure is correct
-    // and any Claude Code-specific config is in place.
+  async setup(targetRoot, copier, options = {}) {
+    const merger = new SettingsMerger(targetRoot);
 
-    // No additional steps needed - all .claude/ content
-    // is handled by component copier
-    return { success: true, message: 'Claude Code integration ready' };
+    // Load template settings from the package source
+    const templatePath = path.join(copier.sourceRoot, 'src', 'claude', 'settings.json');
+    let templateSettings;
+    try {
+      const raw = await fsp.readFile(templatePath, 'utf8');
+      templateSettings = JSON.parse(raw);
+    } catch (err) {
+      return { success: false, message: `Could not read template settings: ${err.message}` };
+    }
+
+    const mode = options.reinstall ? 'overwrite' : 'merge';
+    const result = await merger.install(templateSettings, { mode });
+
+    return {
+      success: true,
+      message: `Claude Code settings ${result.action}${result.backupCreated ? ' (backup created)' : ''}`,
+    };
   }
 
   describe() {
-    return 'Claude Code — .claude/ directory with agents, skills, commands, rules, hooks';
+    return 'Claude Code — .claude/ directory with agents, skills, commands, rules, hooks, settings';
   }
 }
 

package/src/cli/lib/settings-merger.js

@@ -0,0 +1,160 @@
+'use strict';
+
+const fs = require('fs');
+const fsp = fs.promises;
+const path = require('path');
+
+class SettingsMerger {
+  constructor(targetRoot) {
+    if (!targetRoot) {
+      throw new Error('SettingsMerger requires targetRoot');
+    }
+    this.targetRoot = path.resolve(targetRoot);
+    this.settingsPath = path.join(this.targetRoot, '.claude', 'settings.json');
+    this.backupPath = path.join(this.targetRoot, '.claude', 'settings.json.bak');
+  }
+
+  /**
+   * Install settings.json into target project.
+   * @param {object} templateSettings - The DevForgeAI template settings object
+   * @param {object} options - { mode: 'merge' | 'overwrite' }
+   * @returns {object} { action: string, backupCreated: boolean }
+   */
+  async install(templateSettings, options = {}) {
+    const mode = options.mode || 'merge';
+
+    await fsp.mkdir(path.dirname(this.settingsPath), { recursive: true });
+
+    let existing = null;
+    try {
+      const raw = await fsp.readFile(this.settingsPath, 'utf8');
+      existing = JSON.parse(raw);
+    } catch {
+      // No existing file or invalid JSON — treat as fresh install
+    }
+
+    if (!existing || mode === 'overwrite') {
+      await fsp.writeFile(this.settingsPath, JSON.stringify(templateSettings, null, 2) + '\n', 'utf8');
+      return { action: existing ? 'overwritten' : 'created', backupCreated: false };
+    }
+
+    // Merge mode: backup first, then deep merge
+    await this.backup(existing);
+    const merged = this.merge(existing, templateSettings);
+    await fsp.writeFile(this.settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    return { action: 'merged', backupCreated: true };
+  }
+
+  /**
+   * Deep merge template into existing settings.
+   * Existing values are preserved; template fills gaps.
+   */
+  merge(existing, template) {
+    const result = JSON.parse(JSON.stringify(existing));
+
+    // Merge permissions
+    if (template.permissions) {
+      result.permissions = this.mergePermissions(
+        result.permissions || {},
+        template.permissions
+      );
+    }
+
+    // Merge hooks
+    if (template.hooks) {
+      result.hooks = this.mergeHooks(
+        result.hooks || {},
+        template.hooks
+      );
+    }
+
+    // Set statusLine if missing
+    if (template.statusLine && !result.statusLine) {
+      result.statusLine = template.statusLine;
+    }
+
+    // Set includeCoAuthoredBy if missing
+    if ('includeCoAuthoredBy' in template && !('includeCoAuthoredBy' in result)) {
+      result.includeCoAuthoredBy = template.includeCoAuthoredBy;
+    }
+
+    return result;
+  }
+
+  /**
+   * Merge permission arrays: union of allow/ask/deny with deduplication.
+   */
+  mergePermissions(existing, incoming) {
+    const result = JSON.parse(JSON.stringify(existing));
+
+    if (incoming.defaultMode && !result.defaultMode) {
+      result.defaultMode = incoming.defaultMode;
+    }
+
+    for (const key of ['allow', 'ask', 'deny']) {
+      if (incoming[key]) {
+        const existingSet = new Set(result[key] || []);
+        for (const item of incoming[key]) {
+          existingSet.add(item);
+        }
+        result[key] = [...existingSet];
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Merge hooks by event name. Within each event, deduplicate by command path.
+   */
+  mergeHooks(existing, incoming) {
+    const result = JSON.parse(JSON.stringify(existing));
+
+    for (const [eventName, incomingEntries] of Object.entries(incoming)) {
+      if (!result[eventName]) {
+        // Event doesn't exist — add all entries
+        result[eventName] = incomingEntries;
+        continue;
+      }
+
+      // Event exists — deduplicate by command path
+      for (const incomingEntry of incomingEntries) {
+        const isDuplicate = result[eventName].some(existingEntry =>
+          this._hookEntriesMatch(existingEntry, incomingEntry)
+        );
+        if (!isDuplicate) {
+          result[eventName].push(incomingEntry);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check if two hook entries match (same matcher + same command paths).
+   */
+  _hookEntriesMatch(a, b) {
+    // Different matchers = different entries
+    const matcherA = a.matcher || '';
+    const matcherB = b.matcher || '';
+    if (matcherA !== matcherB) return false;
+
+    // Compare hook commands
+    const cmdsA = (a.hooks || []).map(h => h.command).sort();
+    const cmdsB = (b.hooks || []).map(h => h.command).sort();
+
+    if (cmdsA.length !== cmdsB.length) return false;
+    return cmdsA.every((cmd, i) => cmd === cmdsB[i]);
+  }
+
+  /**
+   * Backup existing settings.json.
+   */
+  async backup(existingObj) {
+    const content = JSON.stringify(existingObj, null, 2) + '\n';
+    await fsp.writeFile(this.backupPath, content, 'utf8');
+  }
+}
+
+module.exports = { SettingsMerger };

package/devforgeai/specs/context/anti-patterns.md

@@ -1,285 +0,0 @@
-# Anti-Patterns - DevForgeAI Framework
-
-**Status**: LOCKED
-**Last Updated**: 2026-02-05
-**Version**: 1.1
-
-## Framework Anti-Patterns
-
-### Category 1: Tool Usage Violations (SEVERITY: CRITICAL)
-
-❌ **FORBIDDEN: Using Bash for File Operations**
-
-**Wrong**:
-```markdown
-Bash(command="cat story.md")
-Bash(command="echo 'content' > file.md")
-Bash(command="find . -name '*.md'")
-```
-
-**Correct**:
-```markdown
-Read(file_path="story.md")
-Write(file_path="file.md", content="content")
-Glob(pattern="**/*.md")
-```
-
-**Rationale**: 40-73% token efficiency gain with native tools.
-
-### Category 2: Monolithic Components (SEVERITY: HIGH)
-
-❌ **FORBIDDEN: All-in-One Skill**
-
-**Wrong**:
-```
-.claude/skills/devforgeai-everything/
-└── SKILL.md (5,000 lines doing ideation + architecture + dev + qa + release)
-```
-
-**Correct**:
-```
-.claude/skills/
-├── discovering-requirements/
-├── designing-architecture/
-├── implementing-stories/
-├── validating-quality/
-└── releasing-stories/
-```
-
-**Rationale**: Modularity enables independent updates and token efficiency.
-
-### Category 3: Making Assumptions (SEVERITY: CRITICAL)
-
-❌ **FORBIDDEN: Assuming Technology Choices**
-
-**Wrong**:
-```markdown
-# AI sees "need caching" and adds Redis without asking
-Install Redis for caching layer
-```
-
-**Correct**:
-```markdown
-Question: "Spec requires caching. Which technology?"
-Header: "Caching"
-Options:
-  - "Redis (in-memory, distributed)"
-  - "Memcached (simple, fast)"
-  - "In-memory (no external service)"
-multiSelect: false
-```
-
-**Rationale**: Assumptions cause technical debt.
-
-### Category 4: Size Violations (SEVERITY: HIGH)
-
-❌ **FORBIDDEN: Exceeding Component Size Limits**
-
-**Wrong**:
-```markdown
-# SKILL.md with 2,000 lines of inline documentation
-```
-
-**Correct**:
-```markdown
-# SKILL.md with 500 lines + references/ for deep docs
-For detailed scoring rubric, see references/complexity-assessment-matrix.md
-```
-
-**Rationale**: Character budget constraints (15K for commands).
-
-### Category 5: Language-Specific Framework Code (SEVERITY: CRITICAL)
-
-❌ **FORBIDDEN: Python/C#/JavaScript in Framework**
-
-**Wrong**:
-```
-.claude/skills/implementing-stories/
-├── SKILL.md
-└── scripts/
-    └── implement.py    # Python implementation
-```
-
-**Correct**:
-```
-.claude/skills/implementing-stories/
-├── SKILL.md
-└── references/
-    └── tdd-workflow-guide.md    # Documentation only
-```
-
-**Rationale**: Framework must be language-agnostic.
-
-### Category 6: Context File Violations (SEVERITY: CRITICAL)
-
-❌ **FORBIDDEN: Proceeding Without Context Files**
-
-**Wrong**:
-```markdown
-# Development skill starts implementation without reading context
-Implement feature X using EF Core
-```
-
-**Correct**:
-```markdown
-## Phase 1: Context Validation
-Read all 6 context files
-HALT if missing: "Run /create-context first"
-Check tech-stack.md for ORM choice
-```
-
-**Rationale**: Context files prevent architectural violations.
-
-### Category 7: Circular Dependencies (SEVERITY: HIGH)
-
-❌ **FORBIDDEN: Skills Calling Each Other in Loops**
-
-**Wrong**:
-```
-implementing-stories calls validating-quality
-  ↓
-validating-quality calls implementing-stories
-  ↓
-Infinite loop
-```
-
-**Correct**:
-```
-implementing-stories calls validating-quality (one-way)
-validating-quality returns results
-implementing-stories continues
-```
-
-**Rationale**: Prevents infinite loops and context overflow.
-
-### Category 8: Narrative Documentation (SEVERITY: MEDIUM)
-
-❌ **FORBIDDEN: Prose Instead of Instructions**
-
-**Wrong**:
-```markdown
-The system should first analyze the codebase, and then it might want to consider generating tests...
-```
-
-**Correct**:
-```markdown
-1. Analyze codebase:
-   - Grep(pattern="class.*Test", glob="**/*.cs")
-2. Generate tests:
-   - Use test-automator subagent
-```
-
-**Rationale**: Direct instructions are clearer for Claude.
-
-### Category 9: Missing Frontmatter (SEVERITY: HIGH)
-
-❌ **FORBIDDEN: Skills/Subagents/Commands Without Frontmatter**
-
-**Wrong**:
-```markdown
-# My Skill
-Instructions go here...
-```
-
-**Correct**:
-```markdown
----
-name: my-skill
-description: Brief description of when to use
-tools: Read, Write
----
-
-# My Skill
-Instructions go here...
-```
-
-**Rationale**: Frontmatter required for discovery.
-
-### Category 10: Hardcoded Paths (SEVERITY: MEDIUM)
-
-❌ **FORBIDDEN: Hardcoded File Paths**
-
-**Wrong**:
-```markdown
-Read(file_path="/home/user/project/story.md")
-```
-
-**Correct**:
-```markdown
-Read(file_path="devforgeai/specs/Stories/$STORY_ID.md")
-```
-
-**Rationale**: Relative paths work across environments.
-
-### Category 11: Code Search Tool Selection (SEVERITY: MEDIUM)
-
-**Treelint-Supported Languages:** Python (`.py`), TypeScript (`.ts`, `.tsx`), JavaScript (`.js`, `.jsx`), Rust (`.rs`), Markdown (`.md`)
-
-**Grep is Correct for:** Unsupported languages, simple text-pattern searches (TODOs, string literals), fallback when Treelint is unavailable.
-
-❌ **FORBIDDEN: Using Treelint for Unsupported File Types**
-
-**Wrong**:
-```markdown
-# Treelint does not support C#, Java, Go, SQL - returns errors
-Bash(command="treelint search --type function myfile.cs")
-Bash(command="treelint search --type class MyClass.java")
-Bash(command="treelint deps --calls project.go")
-```
-
-**Correct**:
-```markdown
-# Use Grep for unsupported languages
-Grep(pattern="class\\s+\\w+", glob="**/*.cs")
-Grep(pattern="public\\s+void", glob="**/*.java")
-Grep(pattern="func\\s+\\w+", glob="**/*.go")
-```
-
-**Rationale**: Treelint returns errors for unsupported file types, wasting tokens on error responses instead of useful results.
-
-❌ **FORBIDDEN: Using Grep When Treelint Available for Supported Languages**
-
-**Wrong**:
-```markdown
-# Using Grep for semantic code search in Treelint-supported languages
-Grep(pattern="def\\s+validate", glob="**/*.py")
-Grep(pattern="function\\s+handle", glob="**/*.ts")
-Grep(pattern="class\\s+Service", glob="**/*.js")
-```
-
-**Correct**:
-```markdown
-# Use Treelint for semantic AST-aware search
-Bash(command="treelint search --type function --name 'validate*' --format json")
-Bash(command="treelint search --type class --name 'Service*' --format json")
-Bash(command="treelint deps --calls --format json")
-```
-
-**Rationale**: Treelint provides 99.93% token reduction vs Grep for semantic code search (Source: ADR-013, RESEARCH-007). AST-aware search eliminates false positives from comments, strings, and partial matches. Grep remains valid for simple text patterns (TODOs, string literals) even in supported languages, and as fallback when Treelint is unavailable.
-
-## Anti-Pattern Detection Protocol
-
-When framework components detect anti-patterns:
-
-1. **HALT immediately**
-2. **Report specific violation** with file:line reference
-3. **Provide correction example**
-4. **Request user confirmation** before proceeding
-
-## Enforcement Checklist
-
-Before committing framework changes:
-- [ ] No Bash for file operations (use Read/Write/Edit/Glob/Grep)
-- [ ] Components within size limits (skills <1000, commands <500)
-- [ ] No language-specific code in framework
-- [ ] All ambiguities use AskUserQuestion
-- [ ] Context files read before development
-- [ ] No circular dependencies
-- [ ] Direct instructions, not narrative prose
-- [ ] All components have frontmatter
-- [ ] No hardcoded absolute paths
-- [ ] Code search tool selection correct (Treelint for supported languages, Grep for unsupported)
-
----
-
-**REMEMBER**: Projects using DevForgeAI will have their own anti-patterns.md with project-specific forbidden patterns (SQL injection, N+1 queries, God objects, etc.).