# Technology Stack - DevForgeAI Framework

**Status**: LOCKED
**Last Updated**: 2026-01-31
**Version**: 1.4 (Added: Treelint as approved AST-aware code search tool - STORY-350)

## CRITICAL RULE: Framework-Agnostic Design

**LOCKED PRINCIPLE**: DevForgeAI is a **meta-framework** that works with ANY technology stack. This file documents the framework's own implementation constraints, NOT the constraints of projects using the framework.

---

## Framework Implementation Technologies

### Core Platform

**Platform**: Claude Code Terminal
- **Version**: 1.0+
- **Constraint**: Framework MUST work within Claude Code Terminal capabilities
- **Documentation**: https://docs.claude.com/en/docs/claude-code/

**CRITICAL**: Framework components are implemented as:
- **Skills** (`.claude/skills/[skill-name]/SKILL.md`) - Markdown with YAML frontmatter
- **Subagents** (`.claude/agents/[agent-name].md`) - Markdown with YAML frontmatter
- **Slash Commands** (`.claude/commands/[command-name].md`) - Markdown with YAML frontmatter

### Documentation Format

**Primary Format**: Markdown
- **ALL** skills, subagents, commands, context files, ADRs use Markdown
- **YAML frontmatter** for metadata only
- **JSON** only for structured data exchange (NOT documentation)

**PROHIBITED**:
❌ HTML files for framework documentation
❌ JSON/YAML files for instructions (Markdown only)
❌ Language-specific code in framework docs (must be framework-agnostic)

**Exception - Workflow Hook Scripts (EPIC-048):**
✅ `.claude/hooks/*.sh` - Shell scripts for workflow event hooks
- **Rationale:** Hooks require executable logic for exit codes and workflow control
- **Naming convention:** `post-{workflow}-{action}.sh` (e.g., `post-qa-debt-detection.sh`)
- **Registration:** Must be registered in `devforgeai/config/hooks.yaml`
- **Exit codes:** 0=proceed, 1=warn, 2=halt

**Rationale**: Claude interprets natural language (Markdown) better than structured formats. Research shows 60-80% token savings with progressive disclosure in Markdown.

### Version Control

**System**: Git
- **Required**: All framework components version controlled
- **Branching**: Feature branches for development
- **Commits**: Conventional commit format

### Framework Validation Tools (EPIC-015)

**Epic Coverage Validation System**:
- **Language**: Bash scripting (Claude Code native)
- **Parsing**: Grep patterns for YAML frontmatter and markdown headers
- **Matching**: Exact `epic:` field matching via `grep "^epic: EPIC-XXX"`
- **Data Model**: JSON files or Bash associative arrays
- **Reporting**: Write tool for JSON/markdown generation
- **CLI**: Slash command `/validate-epic-coverage` in `.claude/commands/`

**Rationale** (ADR-005): Uses only Claude Code native tools (Grep, Read, Write, Bash) to achieve 95% coverage without external dependencies. Evidence: 60/63 stories (95%) have `epic:` field.

**PROHIBITED for framework validation**:
❌ External Python libraries (RapidFuzz, PyYAML, mistune)
❌ npm packages for framework tooling
❌ Any dependencies requiring `pip install` or `npm install`

---

## Static Analysis Tools (Code Quality & Security)

### REMOVED: ast-grep (ADR-007)

**Status**: ❌ REMOVED (2025-12-21)
**Decision**: ADR-007 - Remove ast-grep and Evaluate Tree-sitter

**Reason for Removal**: After comprehensive evaluation (EPIC-018, STORY-115-118), ast-grep was found to have fundamental limitations:

1. **Multi-line Pattern Matching Fails** - Patterns with comments/type annotations between statements don't match
2. **Cannot Count/Accumulate** - "Detect classes with >20 methods" impossible with pattern matching
3. **Whitespace Sensitivity** - Python indentation breaks pattern matching
4. **No Semantic Analysis** - Cannot detect duplicate code, unused variables, or cross-file issues
5. **C# AST Issues** - Access modifiers and catch blocks don't match expected patterns

**Evidence**: 52/59 tests passing (88.1%) despite comprehensive remediation - 6 tests failed due to tool limitations, NOT implementation issues.

**PROHIBITED**:
❌ ast-grep for static analysis (REMOVED)
❌ Pattern-based tools that cannot handle real-world code
❌ Tools without proper Python/C# AST support

---

## AST-Aware Code Search Tools

This section documents AST-aware code analysis tools approved for DevForgeAI subagents. These tools provide semantic understanding of code structure beyond simple text matching.

---

### APPROVED: Treelint (ADR-013)

**Status**: ✅ APPROVED
**Decision**: ADR-013 - Treelint Integration for AST-Aware Code Search
**Version**: v0.12.0+ (LOCKED)

**Why v0.12.0+ Required** (minimum version rationale):
- v0.12 introduces daemon mode support for improved performance
- v0.12 stabilizes JSON output format for AI consumption
- v0.12 adds full language support for Python, TypeScript, JavaScript, Rust, Markdown
- Required minimum 0.12 for subagent integration via `--format json` flag

**Purpose**: AST-aware code search for DevForgeAI subagents, replacing text-based Grep for semantic code navigation.

**Installation**:
```bash
# Via pip (recommended)
pip install treelint>=0.12.0

# Via cargo
cargo install treelint
```

**Subagent Usage Examples** (all require `--format json` for AI consumption):
```bash
# Search for functions by name or type
treelint search --type function --name "validate*" --format json

# Generate ranked file importance map
treelint map --ranked --format json

# Analyze function call dependencies
treelint deps --calls --format json
```

**Language Support Table**:

| Language | File Extensions | Status |
|----------|-----------------|--------|
| Python | `.py` | ✅ Supported |
| TypeScript | `.ts`, `.tsx` | ✅ Supported |
| JavaScript | `.js`, `.jsx` | ✅ Supported |
| Rust | `.rs` | ✅ Supported |
| Markdown | `.md` | ✅ Supported |

**Fallback Behavior**:
When Treelint is unavailable or file type is unsupported:
- Use `Grep(pattern="...")` as fallback for text-based search
- Grep provides text matching without AST awareness
- Subagents SHOULD attempt Treelint first, fallback to Grep on error

**Integration Pattern**:
```markdown
# Subagent should use Bash for Treelint invocation
Bash(command="treelint search --type function --format json")

# Fallback if Treelint fails
IF treelint command fails:
    Grep(pattern="def |function |class ", glob="**/*.py")
```

**Reference**: [ADR-013](../adrs/ADR-013-treelint-integration.md)

---

## Project Technology Stack Pattern

When creating context files for **projects using DevForgeAI**, the architecture skill MUST use AskUserQuestion to determine:

### Backend Technology Options

Framework supports (but does not mandate) any of:
- C# with .NET 6.0+
- Python 3.9+ with FastAPI/Django/Flask
- Node.js 18+ with Express/Nest.js
- Java 11+ with Spring Boot
- Go 1.20+ with Gin/Echo
- Rust 1.70+ with Actix/Rocket

**Pattern**: spec-driven-architecture skill asks user to select backend technology, then LOCKS it in project's tech-stack.md.

### Frontend Framework Options

Framework supports (but does not mandate) any of:
- React 18+ with TypeScript
- Vue.js 3+ with TypeScript
- Angular 15+
- Svelte 4+
- Solid.js
- Next.js 14+ (React meta-framework)

**Pattern**: spec-driven-architecture skill asks user to select frontend framework, then LOCKS it in project's tech-stack.md.

### Database Options

Framework supports (but does not mandate) any of:
- PostgreSQL 13+
- MySQL 8+
- Microsoft SQL Server 2019+
- MongoDB 6+
- SQLite 3+
- Oracle Database 19c+

**Pattern**: spec-driven-architecture skill asks user to select database, then LOCKS it in project's tech-stack.md.

### Testing Framework Options

Framework supports (but does not mandate) any of:

**For .NET**:
- xUnit
- NUnit
- MSTest

**For Node.js/TypeScript**:
- Jest
- Vitest
- Mocha + Chai

**For Python**:
- pytest
- unittest
- nose2

**For Java**:
- JUnit 5
- TestNG

**For Go**:
- testing (standard library)
- Testify

**Pattern**: spec-driven-architecture skill asks user to select testing framework for their language, then LOCKS it in project's tech-stack.md.

---

## Framework Constraint Enforcement

### LOCKED: Claude Code Terminal Tools

Framework skills and subagents MUST use Claude Code native tools:

**File Operations**:
- ✅ `Read(file_path="...")` - Reading files
- ✅ `Write(file_path="...")` - Creating files
- ✅ `Edit(file_path="...", old_string="...", new_string="...")` - Modifying files
- ✅ `Glob(pattern="...")` - Finding files by pattern
- ✅ `Grep(pattern="...")` - Searching file contents

**PROHIBITED**:
❌ `Bash(command="cat file.txt")` - Use Read() instead
❌ `Bash(command="echo 'content' > file.txt")` - Use Write() instead
❌ `Bash(command="find . -name *.md")` - Use Glob() instead
❌ `Bash(command="grep 'pattern' file.txt")` - Use Grep() instead
❌ `Bash(command="sed -i 's/old/new/' file.txt")` - Use Edit() instead

**Rationale**: Native tools are 40-73% more token-efficient than Bash commands.

**Exception**: Bash MUST be used for:
- Running tests: `Bash(command="npm test")`, `Bash(command="dotnet test")`
- Running builds: `Bash(command="npm run build")`, `Bash(command="dotnet build")`
- Git operations: `Bash(command="git status")`, `Bash(command="git commit")`
- Package managers: `Bash(command="npm install")`, `Bash(command="pip install")`

### LOCKED: Skill Invocation Pattern

**Skills invoke other skills**:
```markdown
Skill(command="validating-quality --mode=light --story=STORY-001")
```

**Skills invoke subagents**:
```markdown
Task(subagent_type="test-automator",
     prompt="Generate tests for acceptance criteria in STORY-001.md")
```

**PROHIBITED**:
❌ Skills directly calling Bash to invoke other skills
❌ Circular skill dependencies (Skill A calls Skill B calls Skill A)

### LOCKED: Context File Format

All project context files MUST follow this structure:

```markdown
# [Context File Title]

**Status**: LOCKED
**Last Updated**: YYYY-MM-DD
**Version**: X.Y

## [Section 1]
Content with ✅ CORRECT and ❌ FORBIDDEN examples

## [Section 2]
...

## Ambiguity Resolution Protocol
When ambiguity is encountered, AI agents MUST use AskUserQuestion...
```

**PROHIBITED**:
❌ Context files in JSON format
❌ Context files in YAML format (except frontmatter)
❌ Context files without "LOCKED" status marker
❌ Context files without version and date

---

## Technical Debt Threshold Configuration

**Status**: LOCKED (as of 2026-01-21, STORY-289)

**Purpose**: The threshold alerting system enforces technical debt limits during `/dev` workflow pre-flight validation.

### Configuration Location

Thresholds are configured in `devforgeai/technical-debt-register.md` YAML frontmatter:

```yaml
---
thresholds:
  warning_count: 5    # Display warning at 5-9 open items
  critical_count: 10  # Display CRITICAL warning at 10-14 open items
  blocking_count: 15  # Block /dev workflow at 15+ open items
---
```

### Threshold Behavior

| Level | Count Range | Behavior |
|-------|-------------|----------|
| **Normal** | 0-4 items | No alert, workflow proceeds |
| **Warning** | 5-9 items | Display warning, workflow proceeds |
| **Critical** | 10-14 items | Display CRITICAL warning, workflow proceeds |
| **Blocking** | 15+ items | HALT workflow, require override or debt reduction |

### Customization

Projects can customize thresholds by editing the YAML frontmatter in `technical-debt-register.md`:

```yaml
thresholds:
  warning_count: 3    # More aggressive warning (default: 5)
  critical_count: 7   # More aggressive critical (default: 10)
  blocking_count: 12  # More aggressive blocking (default: 15)
```

**Validation Rules:**
- `warning_count < critical_count < blocking_count` (must be in ascending order)
- All values must be positive integers
- If thresholds section is missing or invalid, defaults (5/10/15) are used

### Override Mechanism

When blocked (15+ items), users can override with `--ignore-debt-threshold` flag:
- Triggers `AskUserQuestion` consent prompt
- Override is logged to `devforgeai/workflows/{STORY-ID}-phase-state.json`
- Persistent warning banner displayed throughout workflow

**Reference:** STORY-289 (Threshold Alerting System), `src/claude/skills/spec-driven-dev/phases/phase-01-preflight.md` Step 10

---

## Token Budget Constraints

### LOCKED: Component Size Limits

These limits enforce Claude Code Terminal's character budget constraint:

**Skills**:
- Target: 500-800 lines (~20,000-30,000 characters)
- Maximum: 1,000 lines (~40,000 characters)
- Rationale: Skills have separate context windows

**Slash Commands**:
- Target: 200-400 lines (~8,000-15,000 characters)
- Maximum: 500 lines (~20,000 characters)
- Rationale: 15,000 character budget for command context

**Subagents**:
- Target: 100-300 lines (~4,000-12,000 characters)
- Maximum: 500 lines (~20,000 characters)
- Rationale: Separate context window per subagent

**Context Files**:
- Target: 200-400 lines (~8,000-15,000 characters)
- Maximum: 600 lines (~24,000 characters)
- Rationale: Read into development skill context

**ENFORCEMENT**:
When components exceed targets:
1. Extract reference documentation to separate files
2. Use progressive disclosure (load references on demand)
3. Split into sub-components if necessary

---

## Framework Extension Pattern

### Adding New Skills

**Process**:
1. Create `.claude/skills/[skill-name]/` directory
2. Create `SKILL.md` with YAML frontmatter
3. Add `references/` subdirectory for deep documentation
4. Update CLAUDE.md with skill description
5. Test skill invocation

**PROHIBITED**:
❌ Adding skills without SKILL.md file
❌ Hardcoding logic in skills (use AskUserQuestion for decisions)
❌ Skills that work only for specific languages

### Adding New Subagents

**Process**:
1. Create `.claude/agents/[agent-name].md`
2. Add YAML frontmatter with name, description, tools, model
3. Write system prompt focused on single responsibility
4. Test subagent in isolation and with skills
5. Update documentation

**PROHIBITED**:
❌ Subagents with multiple responsibilities
❌ Subagents that overlap with existing agents
❌ Subagents without tool restrictions (use principle of least privilege)

### Adding New Slash Commands

**Process**:
1. Create `.claude/commands/[command-name].md`
2. Add YAML frontmatter with description, argument-hint
3. Write command instructions with $ARGUMENTS placeholder
4. Keep under 500 lines (<20K characters)
5. Test with real arguments

**PROHIBITED**:
❌ Commands exceeding 500 lines (extract to skills)
❌ Commands without argument hints
❌ Commands that duplicate skill functionality

---

## Ambiguity Resolution Protocol

**CRITICAL**: When framework implementation encounters ambiguity:

1. **Check this file** for LOCKED decisions
2. **Check other context files** for related constraints
3. **If still ambiguous** → STOP and use AskUserQuestion
4. **After resolution** → Update context file or create ADR

**Example Ambiguity**:
"Should the development skill invoke QA skill automatically or wait for user command?"

**Resolution**:
```
Question: "Should development skill invoke QA skill automatically after implementation?"
Header: "QA invocation"
Options:
  - "Automatic - Always invoke light QA after each phase"
  - "Manual - Wait for user to run /qa command"
  - "Configurable - Allow user to set preference"
multiSelect: false
```

After resolution → Document decision in this file or create ADR.

---

## Migration and Versioning

### Framework Version Upgrades

**Semantic Versioning**: MAJOR.MINOR.PATCH

**MAJOR** (Breaking changes):
- Context file format changes
- Skill/subagent interface changes
- Tool usage pattern changes
- Requires project migration

**MINOR** (New features):
- New skills added
- New subagents added
- New slash commands added
- Backward compatible

**PATCH** (Bug fixes):
- Documentation corrections
- Reference file updates
- Minor optimizations
- Fully compatible

### Project Migration Strategy

When upgrading projects to new framework version:
1. Check CHANGELOG for breaking changes
2. Update context files if format changed
3. Regenerate context files with new architecture skill
4. Test with sample story before full migration

---

## Installer/Distribution Technologies

### NPM Package Distribution (EPIC-012)

**Status**: LOCKED (as of 2025-11-25)

**Purpose**: DevForgeAI installer is distributed as an NPM package for easy installation.

**Package Distribution**:
- **Registry**: NPM (public)
- **Package Name**: `devforgeai` (or `@devforgeai/installer` if scoped)
- **Installation**: `npm install -g devforgeai`
- **Entry Point**: `devforgeai` command available globally

**CLI Framework (Node.js wrapper)**:
- **Commander.js 11+** OR **Yargs 17+** - LOCKED (command-line argument parsing)
- **Inquirer.js 9+** - LOCKED (interactive wizard prompts)
- **Ora 7+** - LOCKED (spinner/progress indicators)
- **Chalk 5+** - LOCKED (terminal colors/formatting)
- **Semver 7+** - LOCKED (semantic version parsing/comparison)
- **Boxen 7+** - LOCKED (bordered message boxes)

**Core Installer (Python - existing)**:
- Reuses existing `installer/install.py` and related modules
- Node.js CLI wrapper invokes Python subprocess
- Python 3.10+ required for CLI tools (devforgeai validators)

**Integration Points**:
- **NPM Registry**: Package publishing via `npm publish` with provenance
- **GitHub API**: Version checking, release notes (optional, online mode)
- **PyPI**: devforgeai CLI installed via pip (optional dependency)

**PROHIBITED**:
❌ Replacing Python installer with pure Node.js (reuse existing code)
❌ Bundling alternative CLI frameworks (one choice only)
❌ External network calls during installation (offline mode required)

**Rationale**: NPM provides widest reach for Node.js developers (primary target audience). Python installer core already exists and is well-tested.

---

## References

- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/)
- [Native Tools Best Practices](.claude/skills/spec-driven-cc-guide/references/best-practices.md) - Token efficiency guidelines
- [Spec-Driven CC Guide Skill](.claude/skills/spec-driven-cc-guide/SKILL.md) - Complete terminal feature reference with 4-phase EVG enforcement
- [Framework Design Rationale](README.md)

---

**REMEMBER**: This tech-stack.md defines the **framework's own constraints**. Projects using DevForgeAI will have their own tech-stack.md files created by the spec-driven-architecture skill based on user technology choices.
