izanagi-ai 2.0.0

package/core/decision-engine.md

@@ -0,0 +1,377 @@
+# Core: Decision Engine
+
+> Version 1.0.0
+> Priority: Critical
+> Dependencies: Context Engine, Skill Registry
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Decision Engine is the entry point of every interaction. It classifies the incoming task, determines urgency and complexity, selects the appropriate skill chain (DAG), and validates that all dependencies are satisfied before execution.
+
+---
+
+## Goals
+
+- Classify any input into a task type with confidence ≥ 90%.
+- Route to the correct skill chain with zero ambiguity.
+- Detect missing dependencies before execution.
+- Respect token budget at routing time.
+- Log every decision for reflection and evolution.
+
+---
+
+## Classification Schema
+
+Every task is classified into exactly one category:
+
+| Category | Examples |
+|----------|----------|
+| `new_project` | "Create a blog", "Start a SaaS app" |
+| `new_feature` | "Add payment gateway", "Add search" |
+| `bug` | "Login is broken", "500 error on checkout" |
+| `refactor` | "Clean up this controller", "Extract service" |
+| `review` | "Review my PR", "Is this code good?" |
+| `question` | "How do I use Enum in PHP?", "What is CQRS?" |
+| `explain` | "Explain this code", "Why is this slow?" |
+| `security_audit` | "Audit my API", "Check for vulnerabilities" |
+| `optimize` | "This query is slow", "Reduce memory usage" |
+| `debug` | "Stack trace here", "Why is this null?" |
+| `test` | "Write tests for this", "Coverage report" |
+| `devops` | "Deploy to production", "Set up CI/CD" |
+| `teach` | "Teach me Laravel", "What is dependency injection?" |
+| `plan` | "Plan the next sprint", "Break down this feature" |
+| `document` | "Document this API", "Generate README" |
+
+---
+
+## Skill Chain Matrix
+
+```yaml
+new_project:
+  chain:
+    - core/planning-engine
+    - skills/software-architect
+    - skills/requirement-analyzer
+    - skills/risk-analyzer
+    - skills/software-architect
+  budget: 3000
+  quality_gates: [security, style, completeness]
+
+new_feature:
+  chain:
+    - skills/software-architect
+    - skills/requirement-analyzer
+    - coding/backend-engineer
+    - testing/unit-test-engineer
+  budget: 2500
+  quality_gates: [security, style, completeness]
+
+bug:
+  chain:
+    - skills/debug-specialist
+    - skills/root-cause-analyzer
+    - skills/bug-hunter
+    - testing/integration-test-engineer
+    - teaching/professor-mode
+  budget: 2000
+  quality_gates: [security, completeness]
+
+refactor:
+  chain:
+    - skills/software-architect
+    - skills/complexity-analyzer
+    - skills/refactoring-specialist
+    - testing/unit-test-engineer
+    - skills/solid-validator
+  budget: 2000
+  quality_gates: [style, completeness]
+
+review:
+  chain:
+    - skills/senior-code-reviewer
+    - security/security-engineer
+    - skills/performance-optimizer
+    - skills/clean-code-validator
+    - skills/solid-validator
+  budget: 1500
+  quality_gates: [security, style, clarity]
+
+question:
+  chain:
+    - teaching/professor-mode
+    - teaching/code-explainer
+    - teaching/interactive-teaching
+  budget: 1000
+  quality_gates: [clarity, completeness]
+
+teach:
+  chain:
+    - teaching/professor-mode
+    - teaching/mentor-mode
+    - teaching/adaptive-teaching
+    - teaching/learning-tracker
+  budget: 1500
+  quality_gates: [clarity, completeness]
+
+security_audit:
+  chain:
+    - security/security-engineer
+    - security/owasp-auditor
+    - security/pentest-reviewer
+    - skills/bug-prevention
+    - skills/documentation-writer
+  budget: 3000
+  quality_gates: [security, completeness]
+
+optimize:
+  chain:
+    - skills/performance-optimizer
+    - skills/complexity-analyzer
+    - skills/dependency-analyzer
+    - database/sql-optimizer
+  budget: 2000
+  quality_gates: [style, completeness]
+
+devops:
+  chain:
+    - devops/devops-engineer
+    - devops/docker-expert
+    - devops/ci-cd-specialist
+    - security/security-engineer
+  budget: 2500
+
+debug:
+  chain:
+    - skills/debug-specialist
+    - skills/root-cause-analyzer
+    - skills/logging-expert
+  budget: 2000
+  quality_gates: [completeness]
+
+test:
+  chain:
+    - testing/unit-test-engineer
+    - testing/integration-test-engineer
+    - testing/e2e-test-engineer
+  budget: 2000
+  quality_gates: [completeness]
+
+explain:
+  chain:
+    - teaching/code-explainer
+    - teaching/professor-mode
+    - skills/documentation-writer
+  budget: 1200
+  quality_gates: [clarity, completeness]
+
+
+  quality_gates: [security, completeness]
+
+plan:
+  chain:
+    - core/planning-engine
+    - skills/requirement-analyzer
+    - skills/risk-analyzer
+    - skills/task-planner
+  budget: 2000
+  quality_gates: [completeness]
+
+document:
+  chain:
+    - skills/documentation-writer
+    - skills/technical-writer
+    - skills/readme-generator
+  budget: 1500
+  quality_gates: [clarity, completeness]
+
+unknown:
+  chain:
+    - skills/requirement-analyzer
+    - core/planning-engine
+    - skills/software-architect
+    - teaching/professor-mode
+  budget: 2000
+  quality_gates: [clarity, completeness]
+```
+
+---
+
+## Decision Algorithm
+
+```
+function classify(input):
+    input = normalize(input.lower())
+    
+    if keywords("create|new|start|build|init") AND keywords("project|app|system"):
+        return "new_project"
+    
+    if keywords("bug|error|broken|fail|crash|exception|wrong|issue"):
+        return "bug"
+    
+    if keywords("refactor|clean|extract|improve|restructure|rewrite"):
+        return "refactor"
+    
+    if keywords("review|check|approve|validate|audit|pr|merge"):
+        if keywords("security|vulnerability|owasp"):
+            return "security_audit"
+        return "review"
+    
+    if keywords("how|what|why|when|where|explain|mean|difference"):
+        return "question"
+    
+    if keywords("teach|learn|train|understand|concept|mentor"):
+        return "teach"
+    
+    if keywords("deploy|ci|cd|pipeline|infra|server|container|docker|kubernetes"):
+        return "devops"
+    
+    if keywords("slow|fast|performance|optimize|benchmark|bottleneck|memory|cpu"):
+        return "optimize"
+    
+    if keywords("test|coverage|spec|assert|mock|phpunit|pest|jest|pytest"):
+        return "test"
+    
+    if keywords("plan|sprint|task|story|backlog|milestone|roadmap"):
+        return "plan"
+    
+    if keywords("document|readme|docs|wiki|manual|guide"):
+        return "document"
+    
+    if keywords("add|implement|feature|module|functionality|custom"):
+        return "new_feature"
+    
+    if keywords("debug|stack|trace|null|undefined|ddd|var_dump|dd"):
+        return "debug"
+    
+    return "unknown"
+```
+
+---
+
+## Routing Protocol
+
+```
+1. Receive input
+2. Normalize and tokenize
+3. Run classification algorithm
+4. If confidence < 70%:
+    4a. Flag as "uncertain"
+    4b. Append Context Engine clarification
+    4c. Ask user for clarification
+    4d. Re-classify with new input
+5. Look up skill chain from matrix
+6. Validate all chain dependencies are available
+7. Check token budget (sum of all skills ≤ max)
+8. If budget exceeded:
+    8a. Activate Token Manager
+    8b. Compress lower-priority skills in chain
+9. Execute chain in order
+10. Pass output to Quality Gates
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Classify before acting.
+- ✅ Validate dependencies before execution.
+- ✅ Log every decision (input, classification, chain, confidence).
+- ✅ If uncertain, ask for clarification.
+- ✅ Respect token budget.
+
+### Never
+
+- ❌ Execute without classification.
+- ❌ Skip dependency validation.
+- ❌ Execute a chain that exceeds the token budget.
+- ❌ Assume classification with confidence < 70%.
+- ❌ Modify the chain matrix without reflection.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Classification accuracy | ≥ 90% | Compare classification vs user feedback |
+| Chain execution success | 100% | Count failed executions |
+| Clarification rate | ≤ 10% | Percent of inputs needing clarification |
+| Budget compliance | 100% | Check no chain exceeds budget |
+| Routing latency | < 100ms | Time from input to chain start |
+
+---
+
+## Quality Gates (Pre-Routing)
+
+1. ✅ Input is not empty
+2. ✅ Input language is supported
+3. ✅ Classification returns a valid category
+4. ✅ Chain exists for category
+5. ✅ All dependencies in chain exist
+6. ✅ Token budget sufficient
+
+---
+
+## Memory Hooks
+
+```yaml
+on_classify:
+  - load: user_task_history (last 5)
+  - load: project_context
+
+on_route:
+  - save: last_classification
+  - save: chain_used
+
+on_error:
+  - save: classification_error
+  - notify: Reflection Engine
+```
+
+---
+
+## Token Budget
+
+| Operation | Tokens |
+|-----------|--------|
+| Normalization | 20 |
+| Classification | 100 |
+| Chain lookup | 30 |
+| Dependency validation | 40 |
+| **Total per routing** | **190** |
+
+---
+
+## Reflection
+
+### Pre-delivery
+
+- [ ] Is the classification correct?
+- [ ] Could this input match multiple categories?
+- [ ] Is the chain optimal for this task?
+- [ ] Is budget sufficient?
+
+### Post-delivery
+
+- [ ] Did the chain produce the expected output?
+- [ ] Was any skill in the chain unnecessary?
+- [ ] Should a new category be added?
+- [ ] Should the chain matrix be updated?
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 15 task categories
+- Keyword-based classification algorithm
+- Skill chain matrix for all categories
+- Confidence threshold at 70%
+- Token budget enforcement

package/core/evolution-engine.md

@@ -0,0 +1,169 @@
+# Core: Evolution Engine
+
+> Version 1.0.0
+> Priority: High
+> Dependencies: Reflection Engine, Memory Manager, Skill Registry
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Evolution Engine is the self-improvement mechanism of Nexus AI. It receives structured feedback from the Reflection Engine, detects recurring patterns, and automatically updates skill files, rules, and configurations to prevent repeated mistakes and improve over time.
+
+---
+
+## Goals
+
+- Update skills automatically based on reflection data.
+- Eliminate recurring mistakes within 3 occurrences.
+- Track skill evolution history per version.
+- Never introduce breaking changes without user approval.
+
+---
+
+## Workflow
+
+```
+Reflection Engine
+    ↓
+Evolution Trigger (pattern detected ≥ threshold)
+    ↓
+Load current skill file
+    ↓
+Generate diff (proposed change)
+    ↓
+Validate change (no breaking, no regression)
+    ↓
+Flag for user approval (if major) OR auto-apply (if minor)
+    ↓
+Update skill file
+    ↓
+Update changelog
+    ↓
+Log evolution event
+```
+
+---
+
+## Change Types
+
+| Type | Auto-apply | User Approval | Example |
+|------|-----------|---------------|---------|
+| **Patch** | ✅ Yes | ❌ No | Fix typo, update budget estimate |
+| **Minor** | ❌ No | ✅ Yes | Add new rule, extend workflow |
+| **Major** | ❌ No | ✅ Yes | Restructure skill, change dependencies |
+| **Deprecation** | ❌ No | ✅ Yes | Remove obsolete skill or rule |
+
+---
+
+## Pattern → Action Mapping
+
+```yaml
+patterns:
+  token_waste:
+    threshold: 5 occurrences
+    action: "Reduce token budget for skill by 10%"
+    auto_apply: true
+    
+  misclassification:
+    threshold: 3 occurrences
+    action: "Update Decision Engine classification keywords"
+    auto_apply: false
+    
+  security_gap:
+    threshold: 1 occurrence
+    action: "Immediate skill update — add security rule"
+    auto_apply: false
+    
+  user_confusion:
+    threshold: 3 occurrences
+    action: "Add Professor Mode activation to skill chain"
+    auto_apply: true
+    
+  missing_dependency:
+    threshold: 2 occurrences
+    action: "Add missing dependency to skill declaration"
+    auto_apply: true
+    
+  budget_exceeded:
+    threshold: 3 occurrences
+    action: "Increase budget or compress skill output"
+    auto_apply: true
+```
+
+---
+
+## Evolution Log Format
+
+```yaml
+evolution:
+  id: "evo-20260717-001"
+  timestamp: "2026-07-17T12:00:00Z"
+  
+  source:
+    reflection_ids: ["ref-001", "ref-005", "ref-012"]
+    pattern: "token_waste"
+    occurrences: 5
+    
+  change:
+    type: "patch"
+    target: "skills/backend-engineer.md"
+    field: "token_budget"
+    old_value: 800
+    new_value: 720
+    reason: "Recurring token waste in code examples"
+    
+  status: "auto_applied"
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Log every evolution event with full traceability.
+- ✅ Require user approval for minor and major changes.
+- ✅ Validate changes before applying (no regressions).
+- ✅ Update CHANGELOG.md for every evolution.
+- ✅ Track which reflection triggered the change.
+
+### Never
+
+- ❌ Auto-apply changes that affect skill structure.
+- ❌ Apply changes that break backward compatibility without user approval.
+- ❌ Delete skill files without user confirmation.
+- ❌ Ignore pattern thresholds (always act at threshold).
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Auto-apply accuracy | ≥ 95% | No user reverts of auto-applied changes |
+| Recurring mistake elimination | ≤ 1 recurrence after fix | Track mistake IDs |
+| Evolution events per week | ≥ 2 | Count logged events |
+| User approval rate | ≥ 80% | Approved / requested changes |
+
+---
+
+## Quality Gates (Pre-Apply)
+
+1. ✅ Change improves the system (not neutral or worse).
+2. ✅ Change does not break existing dependencies.
+3. ✅ Change is compatible with SYSTEM.md version.
+4. ✅ Change is documented in CHANGELOG.md.
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 6 pattern → action mappings
+- 4 change types with auto-apply rules
+- Full traceability from reflection to change
+- Validation gate before any change