Sruja Architecture

Sruja Architecture Skill

Deterministic, evidence-first workflow for generating and maintaining repo.sruja (or architecture.sruja). The skill guides the AI to write valid architecture from real code evidence; no DSL expertise required.

Quick Start

1. Evidence — If .sruja/context.json exists and is recent (e.g. updated_at within last hour), use it. Else run sruja sync -r . (do not ask the user to run it).
2. Questions — Ask 2–5 targeted questions only when evidence is ambiguous (boundaries, externals, datastores, deployment, data flows).
3. Generate — Produce minimal repo.sruja from evidence (C4 context + containers; components only when justified).
4. Validate — Run sruja lint repo.sruja and fix all errors before considering complete.
5. Refine — Optionally run sruja drift -r . and update DSL from drift results.
6. Impact (Optional) — Before refactoring code, run sruja impact <target> -r . --depth 3 to quickly see upstream dependents and downstream dependencies.

Workflow checklist: [ ] Evidence gathered → [ ] Questions (if needed) → [ ] repo.sruja generated → [ ] sruja lint passed → [ ] Open questions listed (no guessing)

Core Principles

• Evidence-first — Gather evidence before modeling.
• No guessing — Surface open questions instead of fabricating answers.
• Minimal DSL — Generate only what evidence supports.
• Validation — Always lint and fix errors before considering complete.

Evidence and Discovery

Discovery is backed by a static analysis graph (Tree-sitter): modules, imports, and dependencies from supported languages (TypeScript, Python, Go, Rust, Java, C#, Ruby, etc.). Use this graph as the single source of truth; prefer it over guessing.

Progressive loading (large or multi-repo):

If context is missing or stale, run sruja sync -r . or sruja discover --context -r . --format json yourself. After generating, suggest Sruja: Refresh repo context or sruja sync -r . for next time.

Evidence provides: repository structure, detected technologies, module boundaries, entry points, external dependencies, scan scope.

Workflow (Detail)

1. Collect Evidence

Prefer .sruja/context.json when present and recent (updated_at, truth_status, baseline_path, git_commit). If missing or stale, run:

sruja sync -r .

Or JSON only: sruja discover --context -r . --format json

2. Ask Targeted Questions

Only when evidence is ambiguous:

• Main system boundaries? External services? Datastores? Deployment? Main data flows?

Do not ask about information already clear from evidence.

3. Generate Minimal DSL

Minimal repo.sruja from evidence. C4 context and container levels first; component level only when evidence justifies it.

import { * } from 'sruja.ai/stdlib'

Person = person "Person"
ExternalAPI = system "External API" { description "Third-party or backend service" }

System = system "System" {
  Container = container "Container" {
    technology "Technology"
    description "Description"
  }
}

Person -> System.Container "Protocol"
System.Container -> ExternalAPI "HTTPS"

Component knowledge (opt-in): Ask the user if they want per-component markdown under .sruja/knowledge/. If yes: one file per component (e.g. .sruja/knowledge/PaymentService.md), add doc ".sruja/knowledge/<Id>.md" on the element, use references/KNOWLEDGE_TEMPLATE.md. Scope: containers and key systems; quality over coverage.

Doc references — markdown only: In .sruja files, doc must point to markdown (e.g. .sruja/knowledge/Component.md, docs/README.md, or a generated knowledge base). Do not set doc to source code paths (e.g. .rs, .ts, crates/...). The markdown itself may link to or reference code; the separation is: Sruja DSL elements reference markdown via doc, and that markdown can refer to files.

Sources (specs and infra artifacts): Use source <kind> "<path>" inside an element body to bind code-adjacent artifacts (OpenAPI specs, Kubernetes manifests, Terraform modules, docs) to the architecture element they describe. This keeps architecture grounded in real, reviewable files without requiring the user to write DSL.

Payments = container "Payments API" {
  technology "Go"
  description "Handles payment processing"

  source openapi "./specs/payments.yaml"
  source kubernetes "./k8s/payments/"
  source terraform "./infra/payments/"
  source docs "./docs/payments.md"
}

Supported kinds include: openapi, asyncapi, kubernetes (k8s), dockerfile (docker), terraform (tf), docs (doc), readme, proto (protobuf), config, graphql (gql), helm, and custom.

4. Validate and Repair

sruja lint repo.sruja

Fix all errors. Common: E201 (invalid kind), E204 (circular deps), E205 (orphans), E206 (invalid refs).

5. Refine (Optional)

sruja drift -r .

Use drift results to refine repo.sruja. Use -a path to specify a different architecture file.

Operating Modes

1. Local authoring — Create/update repo.sruja from evidence + questions; generate minimal DSL; run sruja lint.
2. System context — Use discover output or .sruja/context.json for the slice relevant to the task; prefer canonical IDs from evidence.
3. Drift refinement — After code/intent changes, use sruja drift -r . (and optionally sruja intent propose) to turn deltas into DSL updates or open questions; do not invent without evidence.
4. Multi-repo — When system.index.json exists (from sruja compose), load only the impacted slice; use canonical IDs repo_id::local_id; check conflicts and ownership. See docs/FEDERATION.md.

When to Apply

• Discovering architecture from a new codebase
• Generating initial repo.sruja from requirements
• Refactoring or updating existing architecture
• Validating architecture against code
• Maintaining architecture documentation

What NOT to Do

• Do not guess missing information — list open questions.
• Do not add framework/domain/security narratives without evidence.
• Do not create components for completeness only.
• Do not add relationships unsupported by evidence.
• Do not skip linting.
• Do not set doc on elements to source code paths (e.g. crates/foo/src/lib.rs, extension/src/bar.ts). Use markdown only; the markdown can reference code.

Open Questions

Surface missing or unclear information explicitly in comments:

// OPEN QUESTIONS:
// - How is authentication implemented?
// - What message queue is used for async operations?
// - External API integrations not detected?

Multi-repo (Publish and Compose)

Setup: See FEDERATION_SETUP_GUIDE.md for step-by-step instructions.

Workflow:

1. Per-repo: Generate repo.sruja in each repository (same as single-repo workflow)
2. Publish: In each repo: sruja publish -r . -o repo.bundle.json
3. Collect: Copy bundles to shared location (rename to avoid collisions: api.repo.bundle.json)
4. Compose: sruja compose -i <dir> -o system.index.json builds unified graph with canonical IDs
5. Resolve conflicts: Check conflicts array for duplicate kind+label across repos

When working across repos:

• Use canonical IDs: repo_id::local_id (e.g., api-service::PaymentAPI)
• Load only impacted slice from system.index.json, not full graph
• Check ownership before modifying cross-repo relationships

Prompt for multi-repo setup:

Use sruja-architecture. Help me set up federation across multiple repos.
Guide me through: 1) generating repo.sruja in each repo, 2) publishing bundles,
3) composing system.index.json. Reference docs/FEDERATION_SETUP_GUIDE.md for steps.

See docs/FEDERATION.md for artifact schemas and retrieval behavior.

Progressive Discovery — What to Load When

Do not load references/AGENTS.md, references/REFERENCE.md, or entire rules/ at once. Load only what the task needs:

Related References

• Discovery and refinement: references/REFERENCE.md
• Modeling rules: rules/ (per-task; see table above)
• Prompts: references/PROMPTS.md; references/AGENTS.md only for full design/refactor
• Multi-repo setup: docs/FEDERATION_SETUP_GUIDE.md (step-by-step)
• Multi-repo reference: docs/FEDERATION.md (schemas, commands)

Prerequisites and Installation

CLI: Workflow uses sruja sync, sruja discover, sruja lint, sruja drift, and (optionally) sruja impact. Install a CLI that includes sync and discover:

curl -fsSL https://sruja.ai/install.sh | bash

Or from repo: cargo install --path crates/sruja-cli. Verify with sruja --help (must list sync and discover). If the CLI lacks these, the skill falls back to repo structure and codebase only; upgrade via the install script or repo build.

Extension (optional): Sruja extension — syntax, diagnostics, Sruja: Run validation, diagram preview, export to Markdown, Sruja: Refresh repo context. When installed, run Refresh once (or after big changes); the skill prefers .sruja/context.json.

Install skill:

npx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture

Retrieval Order (Architecture-Aware Codegen/Review)

1. Local repo truth — repo.sruja (or architecture.sruja)
2. Fresh evidence — .sruja/context.json (Tree-sitter); if missing/stale, run sruja sync -r . or suggest Sruja: Refresh repo context. For deep semantic context, check/generate index.scip (SCIP) first.
3. Slice from system index — If system.index.json exists, load only impacted slice; use canonical IDs repo_id::local_id
4. Intent and contract refs — ADRs, intent files from repo or bundle
5. Truth/drift — .sruja/context.json or sruja status -r . --format json

Prefer canonical IDs; do not invent when context is missing — ask or mark unknown.

Quick Start Prompt

Single repo:

Use sruja-architecture skill. If .sruja/context.json exists and is recent, use it for evidence; otherwise run `sruja sync -r .` or `sruja discover --context -r . --format json`. Gather evidence, ask targeted questions only if scope or externals are unclear, generate a minimal repo.sruja with evidence-based components and relationships, then run `sruja lint` and fix all errors until it passes. Do not guess; list open questions instead.

Multi-repo:

Use sruja-architecture skill. Help me set up federation across multiple repos.
1) First, help me generate repo.sruja in each repository.
2) Then guide me through publishing bundles and composing system.index.json.
Reference docs/FEDERATION_SETUP_GUIDE.md for detailed steps.

Optional Cursor rule: "For architecture tasks, use .sruja/context.json when present and recent; else run sruja sync -r . or sruja discover --context -r . --format json. For multi-repo, use impacted slice from system.index.json when available; see docs/FEDERATION_SETUP_GUIDE.md."