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 |