Roo-Code/Architecture.md

1. Project Overview

Goal: Develop an Intent-Code Traceability system for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified.

Core Features:

• Two-stage Reasoning Loop (State Machine):

  • Stage 1: Capture client intent, map to AI code action.
  • Stage 2: Validate AI-generated code, detect misalignment, log corrections.

• Hook System Integration:

  • Identify injection points in Roo Code for tracking.
  • Pre-commit, post-commit, and runtime hooks for tracing execution.

• .orchestration/ directory:

  • Stores intent metadata, execution logs, and reasoning states.

• Intent-Code Mapping:

  • Links user intent → AI agent decisions → generated code → execution results.

• Auditability:

  • Every code change is traceable to its originating intent.

---

2. Architecture Layers

A. Input Layer (Intent Capture)

• Source: User commands in the IDE, chat prompts, or code requests.

• Components:

  • Intent Parser (NLP model / regex-based)
  • Preprocessing Engine (normalize ambiguous input)

• Output: Structured intent objects (JSON/YAML).

B. Hook System Layer

• Integration Points: Roo Code Extension

  • Pre-commit hook: Captures intent vs proposed AI code.
  • Post-commit hook: Logs executed code and execution result.
  • Custom Reasoning hooks: Intercepts AI agent output for validation.

• Responsibilities:

  • Validate AI output before commit.
  • Trigger state updates in Reasoning Loop.
  • Maintain orchestration logs.

C. Orchestration & Reasoning Layer

• State Machine (Two-Stage Loop):

  • Stage 1: Intent → Proposed Code

    • AI agent generates code based on captured intent.
    • Hook system verifies structure and alignment.

  • Stage 2: Code Validation

    • Execute test cases or lint checks.
    • Detect mismatches and suggest corrections.

• Data Storage: .orchestration/ directory

  • Stores:

    • Intent metadata
    • AI decisions and reasoning traces
    • Validation results
    • Hook system logs

D. Storage & Traceability Layer

• File System: .orchestration/ for local tracking

• Optional DB: Lightweight database (SQLite/PostgreSQL) for:

  • Intent history
  • AI agent output logs
  • Validation state

• Purpose: Allows historical analysis and auditability.

E. Output & Feedback Layer

• Developer Feedback:

  • Misalignment alerts
  • Suggested corrections
  • Intent-Code mapping visualizations

• Metrics & Analysis:

  • Traceability coverage
  • Reasoning loop success rate
  • Hook system performance

---

3. Development Plan / Workflow

1. Phase 0: Prep

   • Review ARCHITECTURE-NOTES.md for Roo Code injection points.
   • Map the cognitive and trust debt decisions → reasoning logic.
   • Setup Git repo with Git Speck Kit.

2. Phase 1: Hook System Implementation

   • Identify Roo Code extension points for:

     • pre-commit
     • post-commit
     • runtime reasoning interception

   • Build hook scripts.

   • Unit test hooks independently.

3. Phase 2: Reasoning Loop

   • Implement two-stage state machine.
   • Connect hooks to Reasoning Loop states.
   • Implement intent validation logic.

4. Phase 3: Orchestration Directory

   • .orchestration/ for:

     • intent.json
     • reasoning_state.json
     • validation_results.json

   • Implement read/write APIs for traceability.

5. Phase 4: Logging & Traceability

   • Implement audit logs for every hook event.
   • Integrate with Git Speck Kit for code snapshots.
   • Enable metrics collection for AI alignment tracking.

6. Phase 5: Testing & Validation

   • Create sample AI-generated code scenarios.
   • Test traceability pipeline end-to-end.
   • Measure coverage of intent-code alignment.

7. Phase 6: Documentation

   • Maintain ARCHITECTURE_NOTES.md and README.md.
   • Document hook usage, state machine, and orchestration structure.

---

4. Tech Stack / Tools

• Git & Git Speck Kit: Source control, snapshots, hooks.
• Python / Node.js: For hooks and orchestration logic.
• JSON/YAML: Intent and traceability storage.
• Roo Code Extension: Injection points for hook system.
• Lightweight DB (Optional): SQLite or PostgreSQL for logs.
• NLP / Parsing: Optional intent parsing models.
• Testing Frameworks: pytest / Jest for automated validation.

---

5. Key Architectural Decisions (From Cognitive & Trust Debt)

• Track only AI-generated code relevant to intent instead of all outputs.
• Enforce two-stage validation loop to prevent drift between intent and code.
• Maintain self-contained orchestration directory to simplify tracing and rollback.
• Use hooks as checkpoints rather than full code reviews to scale traceability.
• Metrics-driven design: Log reasoning steps to improve future AI alignment.