devforgeai 1.0.8 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devforgeai",
-  "version": "1.0.8",
+  "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/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/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.).

package/devforgeai/specs/context/architecture-constraints.md

@@ -1,323 +0,0 @@
-# Architecture Constraints - DevForgeAI Framework
-
-**Status**: LOCKED
-**Last Updated**: 2025-10-30
-**Version**: 1.0
-
-## Framework Architecture Patterns
-
-### Three-Layer Architecture (LOCKED)
-
-```
-Layer 1: Skills (Framework Implementation)
-   ↓ invokes
-Layer 2: Subagents (Parallel Execution)
-   ↓ uses
-Layer 3: Slash Commands (User Workflows)
-```
-
-**Dependency Rules**:
-- ✅ Commands can invoke Skills
-- ✅ Commands can invoke Subagents via Task tool
-- ✅ Skills can invoke other Skills
-- ✅ Skills can invoke Subagents via Task tool
-- ❌ Skills CANNOT invoke Commands
-- ❌ Subagents CANNOT invoke Skills or Commands
-- ❌ Circular dependencies forbidden (Skill A → Skill B → Skill A)
-
-### Skill Design Constraints (LOCKED)
-
-**Single Responsibility Principle**:
-- Each skill handles ONE phase of development lifecycle
-- ✅ implementing-stories: TDD implementation only (ADR-017 naming)
-- ✅ validating-quality: Quality validation only (ADR-017 naming)
-- ✅ designing-systems: Architecture and context file creation only (ADR-017 naming)
-- ✅ discovering-requirements: Requirements discovery and elicitation only (ADR-017 naming)
-- ❌ implementing-and-validating: Multiple responsibilities
-
-**Context Isolation**:
-- Each skill invocation has separate context window
-- Skills MUST NOT assume state from previous invocations
-- Skills MUST read context files explicitly
-
-**Progressive Disclosure**:
-- Main SKILL.md: Core instructions (<1000 lines)
-- references/: Deep documentation (loaded on demand)
-- MUST use "see references/[file].md" pattern
-
-### Subagent Design Constraints (LOCKED)
-
-**Domain Specialization**:
-- Each subagent specialized in single domain
-- ✅ test-automator: Test generation only
-- ✅ backend-architect: Backend implementation only
-- ❌ full-stack-developer: Too broad
-
-**Tool Restrictions**:
-- Principle of least privilege
-- Only grant tools needed for subagent's domain
-- Example: test-automator gets Read, Write, Edit, Bash (for running tests)
-- Example: code-reviewer gets Read, Grep, Glob only (read-only)
-
-**Parallel Execution Support**:
-- Subagents MUST be designed for parallel invocation
-- No shared state between subagents
-- No dependencies between parallel subagents
-
-### Command Design Constraints (LOCKED)
-
-**User-Facing Workflows**:
-- Commands orchestrate skills and subagents
-- Commands provide user-friendly parameters
-- Commands handle user ambiguity via AskUserQuestion
-
-**Size Constraints**:
-- Keep under 500 lines (<20K characters)
-- If exceeding 500 lines → extract to skill
-
-**Parameter Handling**:
-- Use $ARGUMENTS for user input
-- Provide argument-hint in frontmatter
-- Validate parameters before processing
-
-### Context File Enforcement (LOCKED)
-
-**Immutability Principle**:
-- Context files are THE LAW
-- Development skill MUST read ALL 6 context files
-- AI agents MUST follow constraints or HALT
-
-**Validation Pattern**:
-```markdown
-## Phase 1: Context Validation
-Read context files in PARALLEL:
-- Read(file_path="devforgeai/context/tech-stack.md")
-- Read(file_path="devforgeai/context/source-tree.md")
-- Read(file_path="devforgeai/context/dependencies.md")
-- Read(file_path="devforgeai/context/coding-standards.md")
-- Read(file_path="devforgeai/context/architecture-constraints.md")
-- Read(file_path="devforgeai/context/anti-patterns.md")
-
-HALT if ANY file missing: "Context incomplete. Run /create-context"
-```
-
-### Quality Gate Pattern (LOCKED)
-
-**Gate Enforcement**:
-- Quality gates MUST block progression on violations
-- Gates validated in sequence (no skipping)
-- HALT pattern for gate failures
-
-**Example**:
-```markdown
-HALT if tests fail: "Tests must pass before proceeding"
-HALT if coverage < threshold: "Coverage below 95%/85%/80%"
-HALT if CRITICAL violations: "Fix critical issues before release"
-```
-
-### Error Handling Pattern (LOCKED)
-
-**AskUserQuestion for Ambiguity**:
-```markdown
-IF ambiguity detected:
-  Use AskUserQuestion with specific options
-  Document decision in context file or ADR
-  Proceed with chosen option
-```
-
-**HALT for Constraint Violations**:
-```markdown
-IF constraint violated:
-  HALT with clear error message
-  Provide resolution steps
-  Request user confirmation before retry
-```
-
-### Token Efficiency Pattern (LOCKED)
-
-**Parallel Tool Invocation**:
-```markdown
-✅ CORRECT: Parallel reads
-Read(file_path="file1.md")
-Read(file_path="file2.md")
-Read(file_path="file3.md")
-
-❌ WRONG: Sequential narrative
-First read file1, then read file2, then read file3...
-```
-
-**Native Tools Over Bash**:
-- 40-73% token savings documented
-- MUST use Read/Write/Edit/Glob/Grep instead of Bash equivalents
-
----
-
-### Parallel Execution Rules (LOCKED)
-
-**Three Parallel Patterns Available:**
-
-| Pattern | Use Case | Max Concurrent | Time Savings |
-|---------|----------|----------------|--------------|
-| Parallel Subagents | Multiple Task() calls | 4-6 (10 max) | 30-40% |
-| Background Tasks | Long-running Bash | 3-4 | 50-80% |
-| Parallel Tools | Multiple Read/Grep | Automatic | 15-25% |
-
-**Task Count Limits (LOCKED):**
-- **Recommended**: 4-6 parallel subagents per batch
-- **Maximum**: 10 concurrent tasks (framework limit)
-- **Beyond 10**: Implement explicit batching with synchronization points
-
-**Dependency Rules (LOCKED):**
-- ✅ Parallel tasks MUST be independent (no cross-task dependencies)
-- ✅ If task B uses output of task A: execute sequentially
-- ✅ Synchronization points required between dependent batches
-- ❌ Never parallelize dependent operations
-
-**Background Task Rules:**
-- Timeout required for all background tasks (60-600 seconds)
-- Results MUST be retrieved before next phase
-- Cleanup on error or deferral
-
-**Failure Recovery (LOCKED):**
-- Primary: Attempt parallel execution
-- Fallback: Silently retry as sequential if parallel fails
-- Threshold: Continue if >= 50% success rate (configurable)
-
-**Reference:** See `docs/guides/parallel-orchestration-guide.md` for full patterns
-
----
-
-## Installer Architecture Patterns (EPIC-012, EPIC-013, EPIC-014)
-
-### Installation State Machine (LOCKED)
-
-**States**:
-```
-┌─────────────┐
-│   Fresh     │ ← No previous installation detected
-└──────┬──────┘
-       │ detect existing
-       ▼
-┌─────────────┐
-│   Upgrade   │ ← Previous version detected, upgrade path valid
-└──────┬──────┘
-       │ upgrade fails
-       ▼
-┌─────────────┐
-│  Rollback   │ ← Restore previous version from backup
-└──────┬──────┘
-       │ success
-       ▼
-┌─────────────┐
-│  Validated  │ ← Installation verified complete
-└─────────────┘
-```
-
-**State Transitions**:
-- ✅ Fresh → Validated (successful fresh install)
-- ✅ Upgrade → Validated (successful upgrade)
-- ✅ Upgrade → Rollback → Validated (failed upgrade, rollback succeeded)
-- ✅ Fix → Validated (repair completed)
-- ❌ Validated → Fresh (no overwriting valid installation without user consent)
-- ❌ Rollback → Rollback (no recursive rollback)
-
-### Validation Pipeline Pattern (LOCKED)
-
-**Chain of Responsibility** for pre-flight checks:
-
-```
-PreFlightValidation
-  ├── PythonVersionCheck     → WARN if Python < 3.10
-  ├── DiskSpaceCheck         → ERROR if < 100MB available
-  ├── PermissionCheck        → ERROR if target not writable
-  ├── ExistingInstallCheck   → INFO prompts for upgrade/fresh choice
-  ├── GitStatusCheck         → WARN if uncommitted changes (optional)
-  └── ConflictCheck          → WARN lists files that would be overwritten
-```
-
-**Rules**:
-- ✅ Checks run in sequence (each check passes before next)
-- ✅ ERROR checks block installation (must fix before proceeding)
-- ✅ WARN checks allow continuation with --force flag
-- ✅ INFO checks are informational only (don't block)
-- ❌ No skipping ERROR checks (even with --force)
-- ❌ No partial validation (all checks must run)
-
-### Atomic Installation Pattern (LOCKED)
-
-**All-or-Nothing Principle**:
-
-```
-1. Create backup of existing files (if any)
-2. Create transaction log
-3. Execute installation steps
-   - If any step fails → Rollback to backup
-   - If all steps succeed → Commit (delete backup marker)
-4. Validate installation
-   - If validation fails → Rollback
-5. Update version metadata
-```
-
-**Rules**:
-- ✅ Backup MUST be created before ANY modifications
-- ✅ Transaction log tracks all file operations
-- ✅ Rollback restores EXACTLY to pre-installation state
-- ✅ No partial installations allowed
-- ❌ No modifications without backup
-- ❌ No deleting backup until validation passes
-
-### CLAUDE.md Merge Strategy (LOCKED)
-
-**4 Merge Strategies**:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  AUTO-MERGE (default)                                        │
-│  - Parse user sections vs DevForgeAI sections                │
-│  - Preserve user content, update DevForgeAI content          │
-│  - Merge result = User + Updated Framework                   │
-├─────────────────────────────────────────────────────────────┤
-│  REPLACE                                                     │
-│  - Backup existing CLAUDE.md                                 │
-│  - Overwrite with DevForgeAI template                        │
-│  - User must manually re-add custom content                  │
-├─────────────────────────────────────────────────────────────┤
-│  SKIP                                                        │
-│  - Don't modify CLAUDE.md                                    │
-│  - User manually integrates DevForgeAI instructions          │
-├─────────────────────────────────────────────────────────────┤
-│  MANUAL                                                      │
-│  - Create CLAUDE.mddevforgeai (new content)                 │
-│  - User merges manually with existing CLAUDE.md              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Rules**:
-- ✅ Always backup before merge (regardless of strategy)
-- ✅ Auto-merge uses section markers to identify boundaries
-- ✅ Conflict detection prompts user for resolution
-- ✅ Merge result validated for syntax errors
-- ❌ No silent overwrites (always inform user)
-- ❌ No merge without user consent on conflict
-
-### Version Compatibility Matrix (LOCKED)
-
-**Upgrade Paths**:
-
-| From Version | To Version | Allowed? | Migration Required? |
-|--------------|------------|----------|---------------------|
-| v1.x.x       | v1.y.z (y>x) | ✅ Yes | Minor migration |
-| v1.x.x       | v2.0.0     | ⚠️ With warning | Major migration |
-| v2.x.x       | v1.x.x     | ❌ No (downgrade) | N/A |
-| None         | Any        | ✅ Yes (fresh) | None |
-
-**Rules**:
-- ✅ Minor version upgrades always allowed (1.0 → 1.1)
-- ✅ Patch version upgrades always allowed (1.0.0 → 1.0.1)
-- ⚠️ Major version upgrades require user confirmation (1.x → 2.x)
-- ❌ Downgrades blocked by default (require --force)
-- ❌ Skip-version upgrades require sequential migrations (1.0 → 1.1 → 1.2, not 1.0 → 1.2)
-
----
-
-**REMEMBER**: Projects using DevForgeAI will have their own architecture-constraints.md defining layer boundaries, patterns, and design rules specific to their architecture (Clean Architecture, N-Tier, etc.).