GitHub - arman-jalili/guardian-framework: Architecture Enforcement Framework for AI-Assisted Development

Guardian is an SDLC orchestrator for AI-assisted development. It takes you from a business intent — "I need to build audit logging for regulated financial transactions" — to an enforcement pipeline that blocks merges if the implementation violates the architecture. The entire lifecycle lives in a single .pi/ directory. Every artifact (modules, ADRs, roadmap, issues, CI scripts, agent skills) is generated from that directory. Nothing is handwritten twice. Nothing drifts.

The Full SDLC You have a business intent │ ▼ Domain Exploration ←─ you and the agent explore, iterate, refine │ ▼ Architecture Modules ←─ you review, adjust, approve │ ▼ Enrich Module Docs ←─ agent fills DDD content from exploration │ ▼ ADRs, Diagrams, Specs ←─ you challenge decisions, finalize │ ▼ Roadmap Plan ←─ you adopt phases, set priorities │ ▼ Epic Execution ─── agents implement, you review PRs │ ▼ Enforcement Pipeline ─── CI blocks merges on violation

Walkthrough: From Intent to Enforcement 1. You Have a Business Intent "I need to build a system that collects audit records from CI/CD pipelines, verifies their integrity, stores them, and lets customers query them." 2. Explore the Domain (Human + Agent, Iterative) /domain --explore "Audit logging for regulated financial transactions"

Guardian analyzes your intent and produces a structured domain model. But this isn't a one-shot output — it's the start of a conversation. You review, challenge, and refine:

"These aren't the right bounded contexts. Merge Ingestion and Query into one." "Add a Compliance Engine context. Regulated finance needs it." "The ubiquitous language is wrong — we call them 'evidence records', not 'audit records'."

You go back and forth until the model reflects your actual business.

Only then do you proceed. 3. Scaffold Architecture Modules /domain --architect-scaffold <session-id>

Guardian generates one architecture module per bounded context, with architecture layers, aggregates, repository contracts, and domain events: # Audit Ingestion

## Architecture | Layer | Responsibility | |-------|--------------| | **Domain** | Aggregates, entities, repository interfaces | src/audit-ingestion/domain/ | | **Application** | Use cases, DTOs | src/audit-ingestion/application/ |

## Aggregates ### AuditRecord **Repository Interface:** ```rust pub trait AuditRecordRepository: Send + Sync { async fn find_by_id(&self, id: &AuditRecordId) -> Result<Option<AuditRecord>, DomainError>; async fn save(&self, entity: &AuditRecord) -> Result<(), DomainError>; async fn delete(&self, id: &AuditRecordId) -> Result<(), DomainError>; } Domain Events

Event Description Trigger

AuditRecordIngested ... ...

### 3.5 Enrich with Full DDD Content

/domain --enrich

The agent reads the domain exploration and enhances each module stub with: - Mermaid data flow diagrams - Real Rust struct stubs - API endpoint tables - Ubiquitous Language per context - Cross-context dependencies - Security considerations

This produces production-quality architecture docs (5–20 KB each) that an implementer can build from directly.

## Idempotency Handler status: planned description: Deduplicates records using Idempotency-Key header. depends: HMAC Signature Verifier

4. Review Architecture (Human in the Loop) Now you review the generated architecture. This is where the real design happens:

"The Idempotency Handler shouldn't depend on Signature Verifier — they're parallel." "We need an ADR explaining why we chose HMAC-SHA256 over ECDSA." "Add a system-overview diagram showing how records flow from ingestion to query."

You tell the agent to add ADRs, update module docs, generate diagrams.

You challenge decisions until the architecture is solid. Every ADR captures a decision: ADR-004: Use HMAC-SHA256 with JCS canonicalization ADR-005: Idempotency via Idempotency-Key header (not dedup table) ADR-006: Cursor-based pagination for audit listing

5. Adopt the Roadmap When the architecture is finalized, you lock it in with a roadmap. Each phase has dependencies, migrations, and acceptance criteria. /architect --roadmap /architect --adopt-roadmap

Phase 0: Foundation (5 modules, Days 1–5) Phase 1: Core Ingestion Pipeline (3 modules, Days 6–12, depends on Phase 0)

6. Execute via Phases /architect --phase "Phase 0"

Guardian generates one epic per module, one issue per component. Each issue carries the component's architecture context, language-specific DDD patterns, and acceptance criteria. The agent implements. You review PRs. Guardian auto-advances through the pipeline: implement → validate → create-mr → merge

Optional: TDD Mode Pass --tdd to /architect --epic to generate deterministically failing test files from architecture contracts before the agent sees any implementation issue. Tests use expect(false).toBe(true) (or language equivalent) — the agent follows Red→Green→Refactor to make them pass. No LLM is involved in test generation. Every test is derived from structured component data (name, description, dependencies, affected layers). /architect --epic "Auth Module" --tdd

7. Enforcement Closes the Loop Every change is validated against the architecture:

Script What it enforces

check_ddd_structure.sh Every module has domain/ application/ infrastructure/ interfaces/ — no contracts/ wrapper

check_architecture_conformance.sh Domain doesn't import infrastructure. Per-module 4-layer structure.

validate-canonical.sh Every code file references its architecture source

If someone (or an AI) adds a dependency from the domain layer to infrastructure, check_ddd_structure.sh catches it. CI fails. The merge is blocked.

Quick Start # 1. Scaffold cd your-project npx guardian-framework init

# 2.

Explore (iterative — review, refine, repeat) /domain --explore "your business intent"

# 3. Generate architecture from exploration /domain --architect-scaffold <session-id>

# 4. Enrich module docs with full DDD content /domain --enrich <session-id>

# 5. Review and refine (ADRs, diagrams, modules — human-in-the-loop)

# 6. Adopt the roadmap /architect --roadmap /architect --adopt-roadmap

# 6. Execute /architect --phase "Phase 0"

What This Means Architecture drift becomes a compile-time error. Not a documentation comment. Not a code review note that gets lost. A CI failure that blocks the merge until fixed. Guardian was proven on Rigorix: 146,312 lines of Rust, 30 modules, 580 commits, built by a single developer over 11 active days. The architecture defined in .pi/ was continuously validated against implementation. When drift happened, it was caught before reaching main.

Links

User Manual docs/USER_MANUAL.md — every workflow, command, and extension

Proven on Rigorix — 146K LOC Rust, 30 modules

Source github.com/arman-jalili/guardian-framework

License MIT