Roo-Code/ARCHITECTURE_NOTES.md

Roo Code Hook Architecture Notes

Entry Points

• execute_command: Handles all tool execution requests from the agent.
• write_file: Performs all codebase mutations initiated by the agent.
• These are the primary points where the hook engine intercepts and enforces governance.

Hook Engine

• preHook(intentId):
  • Validates the selected intent against active_intents.yaml.
  • Injects intent-specific constraints and owned scope into the agent context.
  • Blocks execution if no valid intent is selected.
• postHook(intentId, filePath, content):
  • Computes SHA-256 hash of the modified code to ensure spatial independence.
  • Appends a structured entry to .orchestration/agent_trace.jsonl, linking the change back to the business intent.
  • Supports multiple intents and can track simultaneous agent actions.

Orchestration Folder

• active_intents.yaml: Stores all high-level business intents, their status, constraints, and acceptance criteria.
• agent_trace.jsonl: Append-only ledger capturing all mutating actions, with intent mapping and content hashes.
• intent_map.md: Maps business intents to physical files and AST nodes for traceability and future planning.

Demo Flow

1. User selects INT-001 (e.g., JWT Authentication Migration).
2. preHook injects constraints and scope for the selected intent.
3. Agent executes write_file to modify code (e.g., src/auth/jwt.ts).
4. postHook records the file content hash and updates agent_trace.jsonl.
5. Repeat for other intents (e.g., INT-002 Billing Refactor, INT-003 Logging Middleware) to demonstrate parallel intent handling.

Key Features Demonstrated:

• Traceability: Every code change is linked to a specific intent.
• Governance: Hooks enforce scope and constraints before code is written.
• Scalability: Multiple intents can be managed concurrently with consistent context injection and trace logging.