guardian-framework 0.1.14 → 0.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -68
- package/dist/cli.js +1 -1
- package/dist/exports.js +1 -1
- package/package.json +1 -1
- package/templates/pi/preflight_report.json +1 -1
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<picture>
|
|
3
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Guardian-
|
|
4
|
-
<img alt="Guardian" src="https://img.shields.io/badge/Guardian-
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Guardian-SDLC%20Orchestrator-00bcd4?style=for-the-badge&labelColor=222">
|
|
4
|
+
<img alt="Guardian" src="https://img.shields.io/badge/Guardian-SDLC%20Orchestrator-00bcd4?style=for-the-badge&labelColor=fff">
|
|
5
5
|
</picture>
|
|
6
6
|
|
|
7
|
-
<h3>
|
|
7
|
+
<h3>Business intent → enforced architecture → production code.<br/>One flow, no drift.</h3>
|
|
8
8
|
|
|
9
9
|
<br/>
|
|
10
10
|
|
|
@@ -12,36 +12,65 @@
|
|
|
12
12
|
<a href="https://github.com/arman-jalili/guardian-framework/actions"><img src="https://img.shields.io/github/actions/workflow/status/arman-jalili/guardian-framework/ci.yml?style=flat&colorA=222&colorB=00bcd4" alt="CI"/></a>
|
|
13
13
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/arman-jalili/guardian-framework?style=flat&colorA=222&colorB=00bcd4" alt="license"/></a>
|
|
14
14
|
<br/>
|
|
15
|
-
<a href="https://github.com/arman-jalili/rigorix-oss"><img src="https://img.shields.io/badge/
|
|
15
|
+
<a href="https://github.com/arman-jalili/rigorix-oss"><img src="https://img.shields.io/badge/Proven%20on-Rigorix%20(146K%20LOC)%2000bcd4?style=flat&colorA=222" alt="Rigorix"/></a>
|
|
16
16
|
</div>
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
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.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
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.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## The Full SDLC
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
```
|
|
29
|
+
Business Intent
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
Domain Exploration ─── discovers bounded contexts, entities, ubiquitous language
|
|
33
|
+
│
|
|
34
|
+
▼
|
|
35
|
+
Architecture Modules ─── components, dependencies, contracts per context
|
|
36
|
+
│
|
|
37
|
+
▼
|
|
38
|
+
ADRs & Review ─── every decision captured, cross-referenced, versioned
|
|
39
|
+
│
|
|
40
|
+
▼
|
|
41
|
+
Roadmap ─── phases with dependencies, migrations, acceptance criteria
|
|
42
|
+
│
|
|
43
|
+
▼
|
|
44
|
+
Epic Execution ─── issues generated per component, agents implement in pipelines
|
|
45
|
+
│
|
|
46
|
+
▼
|
|
47
|
+
Enforcement ─── CI validates structure, dependencies, DDD layers, every merge
|
|
48
|
+
```
|
|
27
49
|
|
|
28
50
|
---
|
|
29
51
|
|
|
30
|
-
##
|
|
52
|
+
## Walkthrough: From Intent to Enforcement
|
|
31
53
|
|
|
32
|
-
|
|
54
|
+
### 1. You Have a Business Intent
|
|
33
55
|
|
|
34
|
-
|
|
35
|
-
|
|
56
|
+
*"I need to build a system that collects audit records from CI/CD pipelines, verifies their integrity, stores them, and lets customers query them."*
|
|
57
|
+
|
|
58
|
+
### 2. Explore the Domain
|
|
36
59
|
|
|
37
60
|
```
|
|
38
61
|
/domain --explore "Audit logging for regulated financial transactions"
|
|
39
62
|
```
|
|
40
63
|
|
|
41
|
-
|
|
64
|
+
Guardian analyzes the intent and produces a structured domain model:
|
|
65
|
+
- **Bounded contexts:** Audit Ingestion, Audit Query, Compliance Engine, Policy Engine
|
|
66
|
+
- **Entities:** AuditRecord, Policy, ComplianceReport
|
|
67
|
+
- **Ubiquitous language:** signed records, evidence, compliance score
|
|
68
|
+
|
|
69
|
+
This isn't a brainstorming session. It's the first artifact in a chain that ends with enforced CI.
|
|
42
70
|
|
|
43
|
-
###
|
|
44
|
-
|
|
71
|
+
### 3. Define Architecture Modules
|
|
72
|
+
|
|
73
|
+
From the exploration, Guardian scaffolds one module per bounded context:
|
|
45
74
|
|
|
46
75
|
```markdown
|
|
47
76
|
# Audit Ingestion
|
|
@@ -50,62 +79,81 @@ From the exploration, Guardian scaffolds architecture modules. Each module descr
|
|
|
50
79
|
status: planned
|
|
51
80
|
description: Verifies HMAC-SHA256 signatures on incoming audit records.
|
|
52
81
|
depends: none
|
|
82
|
+
|
|
83
|
+
## Idempotency Handler
|
|
84
|
+
status: planned
|
|
85
|
+
description: Deduplicates records using Idempotency-Key header.
|
|
86
|
+
depends: HMAC Signature Verifier
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Each module defines components, their dependencies, and their contract interfaces. The structure is simple markdown — no DSL, no config language.
|
|
90
|
+
|
|
91
|
+
### 4. Capture Decisions with ADRs
|
|
92
|
+
|
|
93
|
+
Every architectural choice gets an Architecture Decision Record — not as documentation, as a constraint.
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
ADR-004: Use HMAC-SHA256 with JCS canonicalization
|
|
97
|
+
ADR-005: Idempotency via Idempotency-Key header (not dedup table)
|
|
98
|
+
ADR-006: Cursor-based pagination for audit listing
|
|
53
99
|
```
|
|
54
100
|
|
|
55
|
-
|
|
56
|
-
Architecture Decision Records (ADRs) capture every meaningful choice — why this approach, not that one. They're version-controlled, cross-referenced, and enforced.
|
|
101
|
+
ADRs are cross-referenced. Change an ADR? The modules that depend on it need updating. The canonical validator catches the gap.
|
|
57
102
|
|
|
58
|
-
|
|
59
|
-
> Status: Accepted. Depends on: ADR-003 (JSON Canonicalization Scheme).
|
|
103
|
+
### 5. Plan the Roadmap
|
|
60
104
|
|
|
61
|
-
|
|
62
|
-
Group modules into delivery phases with dependencies, migrations, and acceptance criteria.
|
|
105
|
+
Group modules into delivery phases. Each phase has dependencies, database migrations, and acceptance criteria.
|
|
63
106
|
|
|
64
107
|
```
|
|
65
108
|
/architect --roadmap
|
|
66
109
|
```
|
|
67
110
|
|
|
68
|
-
>
|
|
111
|
+
> Phase 0: Foundation — Scaffold & Shared Infrastructure (Days 1–5)
|
|
112
|
+
> Modules: Operations, Auth, Team Management, Rate Limiting, API Versioning
|
|
113
|
+
> Phase 1: Core Ingestion Pipeline (Days 6–12)
|
|
114
|
+
> Modules: Audit Ingestion, Audit Query, Usage Metering
|
|
115
|
+
> Depends on: Phase 0
|
|
69
116
|
|
|
70
|
-
###
|
|
71
|
-
Guardian generates issue files from your architecture — one issue per component, with full context, acceptance criteria, and auto-generated file changes.
|
|
117
|
+
### 6. Execute
|
|
72
118
|
|
|
73
119
|
```
|
|
74
120
|
/architect --phase "Phase 0"
|
|
75
121
|
```
|
|
76
122
|
|
|
77
|
-
|
|
78
|
-
|
|
123
|
+
Guardian generates one epic per module, one issue per component. Each issue carries:
|
|
124
|
+
- The component's architecture context and dependencies
|
|
125
|
+
- A language-specific codegen skill reference (e.g., `Follow: .pi/skills/agents/rust-codegen.md`)
|
|
126
|
+
- Auto-generated file changes with the correct DDD layer structure
|
|
127
|
+
- Acceptance criteria
|
|
128
|
+
|
|
129
|
+
The implementing agent reads the skill, loads the relevant DDD patterns on-demand, and builds the component. When done, it calls `pipeline_advance`. Guardian auto-advances through:
|
|
79
130
|
|
|
80
|
-
The agent implements each component. When done, it calls `pipeline_advance`. Guardian auto-advances through:
|
|
81
131
|
```
|
|
82
132
|
implement → validate → create-mr → merge
|
|
83
133
|
```
|
|
84
134
|
|
|
85
|
-
|
|
135
|
+
### 7. Enforce
|
|
86
136
|
|
|
87
|
-
|
|
137
|
+
This is where the loop closes. Guardian generates CI scripts from the architecture:
|
|
88
138
|
|
|
89
|
-
|
|
139
|
+
| Script | What it enforces |
|
|
140
|
+
|--------|-----------------|
|
|
141
|
+
| `check_ddd_structure.sh` | Every module has `domain/ application/ infrastructure/ interfaces/` — no `contracts/` wrapper |
|
|
142
|
+
| `check_architecture_conformance.sh` | Domain doesn't import infrastructure. Application doesn't import interfaces. Per-module 4-layer structure. |
|
|
143
|
+
| `check_{module}_contracts.sh` | Every frozen interface has a concrete implementation |
|
|
144
|
+
| `validate-canonical.sh` | Every code file references its architecture source |
|
|
90
145
|
|
|
91
|
-
|
|
92
|
-
|---------------|-------------------|
|
|
93
|
-
| Drawing diagrams that go stale | Generates CI scripts that check structure on every commit |
|
|
94
|
-
| Writing "domain must not depend on infrastructure" in a doc | Creates a `check_ddd_structure.sh` that literally greps for illegal imports and fails if found |
|
|
95
|
-
| Trusting code review to catch drift | Blocks merges when architecture is violated — no human oversight needed |
|
|
96
|
-
| Onboarding new devs with 30-page docs | Every issue carries its full context: architecture reference, codegen patterns, acceptance criteria |
|
|
97
|
-
| One-size-fits-all prompts | Generates language-specific codegen skills (Rust, Go, Python, TypeScript, Java/Spring Boot) with DDD + Clean Architecture patterns |
|
|
146
|
+
If a developer (or AI agent) adds a dependency from the domain layer to infrastructure, `check_ddd_structure.sh` catches it and CI fails. The merge is blocked.
|
|
98
147
|
|
|
99
148
|
---
|
|
100
149
|
|
|
101
|
-
##
|
|
150
|
+
## What This Means
|
|
151
|
+
|
|
152
|
+
**Architecture drift becomes a compile-time error.**
|
|
153
|
+
|
|
154
|
+
Not a documentation comment. Not a code review note that gets lost. A CI failure that blocks the merge until fixed.
|
|
102
155
|
|
|
103
|
-
|
|
104
|
-
- 146,312 lines of Rust
|
|
105
|
-
- 30 modules across 3 crates
|
|
106
|
-
- 18 ADRs, 38 module specs, 44 issue drafts
|
|
107
|
-
- 580 commits over 11 active days
|
|
108
|
-
- Built by a single developer — Guardian handled orchestration and enforcement
|
|
156
|
+
Guardian was proven on [Rigorix](https://github.com/arman-jalili/rigorix-oss): 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.
|
|
109
157
|
|
|
110
158
|
---
|
|
111
159
|
|
|
@@ -115,41 +163,21 @@ If CI fails (architecture violation, security issue, broken test), the pipeline
|
|
|
115
163
|
npx guardian-framework init
|
|
116
164
|
```
|
|
117
165
|
|
|
118
|
-
Answer 4 prompts (project name, language, AI tools, validators). You get:
|
|
119
|
-
- A `.pi/` directory with full architecture scaffolding
|
|
120
|
-
- 20 TypeScript extensions (orchestration, pipeline, kanban, validation, etc.)
|
|
121
|
-
- 21 workflow prompt templates
|
|
122
|
-
- 74 CI scripts with language-specific validators
|
|
123
|
-
- Agent export files for Claude Code, pi, Copilot, Cursor, and more
|
|
124
|
-
|
|
125
166
|
Then:
|
|
126
|
-
```
|
|
167
|
+
```bash
|
|
127
168
|
cd your-project && pi
|
|
128
|
-
/domain --explore "your business
|
|
169
|
+
/domain --explore "your business intent"
|
|
129
170
|
/architect --roadmap
|
|
130
171
|
/architect --phase "Phase 0"
|
|
131
172
|
```
|
|
132
173
|
|
|
133
174
|
---
|
|
134
175
|
|
|
135
|
-
## One File, One Constraint
|
|
136
|
-
|
|
137
|
-
At the heart of every file is a canonical reference:
|
|
138
|
-
|
|
139
|
-
```typescript
|
|
140
|
-
//! @canonical .pi/architecture/modules/auth-system.md#token-validation
|
|
141
|
-
//! Issue: #42
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
When code and architecture diverge, the reference breaks. CI catches it. The merge is blocked. Architecture drift becomes a compile-time error, not a documentation comment.
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
176
|
## Links
|
|
149
177
|
|
|
150
178
|
| | |
|
|
151
179
|
|---|---|
|
|
152
|
-
| **
|
|
153
|
-
| **
|
|
180
|
+
| **User Manual** | [docs/USER_MANUAL.md](docs/USER_MANUAL.md) — every workflow, command, and extension |
|
|
181
|
+
| **Proven on** | [Rigorix](https://github.com/arman-jalili/rigorix-oss) — 146K LOC Rust, 30 modules |
|
|
154
182
|
| **Source** | [github.com/arman-jalili/guardian-framework](https://github.com/arman-jalili/guardian-framework) |
|
|
155
183
|
| **License** | MIT |
|
package/dist/cli.js
CHANGED
|
@@ -1335,7 +1335,7 @@ __export(exports_package, {
|
|
|
1335
1335
|
bin: () => bin,
|
|
1336
1336
|
author: () => author
|
|
1337
1337
|
});
|
|
1338
|
-
var name = "guardian-framework", version = "0.1.
|
|
1338
|
+
var name = "guardian-framework", version = "0.1.16", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
|
|
1339
1339
|
var init_package = __esm(() => {
|
|
1340
1340
|
exports = {
|
|
1341
1341
|
".": {
|
package/dist/exports.js
CHANGED
|
@@ -995,7 +995,7 @@ __export(exports_package, {
|
|
|
995
995
|
bin: () => bin,
|
|
996
996
|
author: () => author
|
|
997
997
|
});
|
|
998
|
-
var name = "guardian-framework", version = "0.1.
|
|
998
|
+
var name = "guardian-framework", version = "0.1.16", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
|
|
999
999
|
var init_package = __esm(() => {
|
|
1000
1000
|
exports = {
|
|
1001
1001
|
".": {
|
package/package.json
CHANGED