sruja: Instructions file for Codex

This guide helps AI agents work effectively with the Sruja codebase.

Procedural workflow instructions belong in .sruja/loop.toml [pipeline], not in natural language. See [PipelineConfig] for the explicit stage model that drives the agent loop. This file contains knowledge and context, not step-by-step procedures.

Table of Contents

• Quick Reference
• Architecture Setup
• Before Coding: Shared Understanding
• AI Agent Workflow
• Code-Embedded Architecture Metadata
• Build, Lint, and Test Commands
• Code Style Guidelines
• Editor-Specific Configs
• Troubleshooting

⚡ Quick Reference (Top 5 Commands)

Command	Purpose
make setup / just setup	First-run setup (install deps, hooks, build)
make check / just check	Pre-commit check (fmt + lint + test)
make daily / just daily	Sync context + check diagnostic drift
sruja focus	Task briefing (blast radius, decisions, AI info)
sruja mcp -r .	Start MCP server for deep context queries

Architecture Setup (AI Agent Workflow)

Use this workflow to set up architecture enforcement for any repository. No separate API key needed — the AI agent provides the intelligence, sruja provides the tools.

Step 1: Understand the codebase

sruja_list_architecture_index  → get structure
sruja_get_topology             → get dependencies
sruja_get_repomap              → get file overview

Step 2: Classify the architecture

Call sruja_classify with a classification JSON that you (the AI agent) have determined:

{
  "schema_version": "classification/v1",
  "project_type": "rust-workspace",
  "summary": { "crates": 14, "source_files": 500 },
  "layers": [
    { "name": "Core Engine", "members": ["sruja-language", "sruja-engine"] },
    { "name": "Delivery", "members": ["sruja-cli", "sruja-wasm"] }
  ],
  "boundaries": [
    { "from": "sruja-language", "to": "sruja-cli", "allowed": false, "reason": "Core should not depend on CLI" }
  ],
  "forbidden_patterns": [
    "Lower-tier crates must not depend on higher-tier crates"
  ]
}