guardian-framework 0.1.13 → 0.1.15
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 +86 -400
- 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,471 +1,157 @@
|
|
|
1
1
|
<div align="center">
|
|
2
|
-
<
|
|
3
|
-
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Guardian-Architecture%20Enforcement-00bcd4?style=for-the-badge&labelColor=222">
|
|
4
|
+
<img alt="Guardian" src="https://img.shields.io/badge/Guardian-Architecture%20Enforcement-00bcd4?style=for-the-badge&labelColor=fff">
|
|
5
|
+
</picture>
|
|
6
|
+
|
|
7
|
+
<h3>From idea to production code — with architecture that's actually enforced.</h3>
|
|
8
|
+
|
|
9
|
+
<br/>
|
|
4
10
|
|
|
5
11
|
<a href="https://github.com/arman-jalili/guardian-framework/blob/main/package.json"><img src="https://img.shields.io/github/package-json/v/arman-jalili/guardian-framework?style=flat&colorA=222&colorB=00bcd4" alt="version"/></a>
|
|
6
|
-
<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
|
|
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>
|
|
7
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>
|
|
8
|
-
<a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat&colorA=222" alt="Bun"/></a>
|
|
9
14
|
<br/>
|
|
10
|
-
<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/Built%20with%20Guardian-Rigorix%20(146K%20LOC%20Rust)-00bcd4?style=flat&colorA=222" alt="Rigorix"/></a>
|
|
11
16
|
</div>
|
|
12
17
|
|
|
13
18
|
---
|
|
14
19
|
|
|
15
|
-
|
|
20
|
+
### What if your architecture was more than a document?
|
|
16
21
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
For example, if the architecture specifies that the Payment context may not depend on Authentication, Guardian detects the dependency during CI and blocks the change before merge.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
+
Most projects start with great architecture ideas, then drift. Implementation strays. Dependencies sneak in the wrong direction. By the time anyone notices, the codebase is fighting the original design.
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
**Guardian is the tool that prevents that drift — not by documentation, but by enforcement.**
|
|
24
25
|
|
|
25
|
-
|
|
26
|
+
It works with **pi** — the AI coding agent. You define your architecture once in simple markdown files. Guardian turns those files into executable constraints: CI scripts that validate every change, prompt templates that guide every implementation, and a verification pipeline that blocks merges when code violates architecture.
|
|
26
27
|
|
|
27
|
-
|
|
28
|
-
|----------|-------------------|
|
|
29
|
-
| Architecture specifications | Module boundaries, component breakdowns, dependency rules, interface contracts |
|
|
30
|
-
| Architecture Decision Records | Structured ADR documents with status tracking and cross-references |
|
|
31
|
-
| Implementation epics | Component-level issues sliced from architecture modules, ordered by dependency |
|
|
32
|
-
| CI enforcement policies | Validator scripts, hardening stages, and merge gates that block violations |
|
|
33
|
-
| Agent workflows | 21 prompt templates covering feature development, bug fixes, hotfixes, refactoring, and issue lifecycle |
|
|
34
|
-
| Tool-specific exports | `.claude/`, `.github/`, `.opencode/`, `.agents/` directories generated from the same `.pi/` source |
|
|
35
|
-
|
|
36
|
-
The `.pi/` model also supports domain modeling with concepts like bounded contexts, entities, and domain events for teams that use those techniques. For everyone else, it works directly from architecture modules and ADRs — no DDD background required.
|
|
28
|
+
Guardian also **scaffolds agent configurations** for Claude Code, Copilot, Cursor, and OpenCode — exporting skills, context files, and workflow definitions to their respective directories (`.claude/`, `.github/`, `.opencode/`).
|
|
37
29
|
|
|
38
30
|
---
|
|
39
31
|
|
|
40
|
-
##
|
|
41
|
-
|
|
42
|
-
Guardian enforces architecture through 7 categories of validator scripts, automatically selected based on change scope:
|
|
43
|
-
|
|
44
|
-
| Scope | Files | Lines | Validators Triggered |
|
|
45
|
-
|-------|-------|-------|---------------------|
|
|
46
|
-
| Simple | 1-2 | <= 50 | CI + canonical |
|
|
47
|
-
| Moderate | 3-5 | 51-200 | CI + architecture + canonical |
|
|
48
|
-
| Complex | 6-15 | 201-500 | CI + architecture + security + tests + integration + canonical |
|
|
49
|
-
| Critical | 16+ | 501+ | All 7 + human approval |
|
|
32
|
+
## How It Works — A Complete Walkthrough
|
|
50
33
|
|
|
51
|
-
|
|
34
|
+
**The process is a flow, not a one-time setup. Here's the full loop:**
|
|
52
35
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
| CI | Build, test, lint, format, audit | All changes |
|
|
56
|
-
| Architecture | Module boundaries, dependency direction, ADR compliance | Moderate+ |
|
|
57
|
-
| Canonical | Every code file references its architecture source; docs match code | All changes |
|
|
58
|
-
| Security | Secrets, injection, path traversal, auth bypass | Complex+ |
|
|
59
|
-
| Tests | Unit, integration, coverage thresholds | Complex+ |
|
|
60
|
-
| Integration | Component wiring, interface contracts | Complex+ |
|
|
61
|
-
| Operations | Tracing, cancellation, atomic writes, error handling | Critical |
|
|
36
|
+
### 1. Explore the Domain
|
|
37
|
+
Start by understanding the problem space. Guardian guides you through domain exploration — identifying bounded contexts, entities, and the language your business speaks.
|
|
62
38
|
|
|
63
|
-
The canonical validator is the linchpin: every implementation file carries a header tracing it to a specific architecture section. When code and architecture diverge, the reference breaks and CI fails.
|
|
64
|
-
|
|
65
|
-
```typescript
|
|
66
|
-
/**
|
|
67
|
-
* Canonical Reference: .pi/architecture/modules/auth-system.md#token-validation
|
|
68
|
-
* Implements: AC-1, AC-2
|
|
69
|
-
* Issue: #42
|
|
70
|
-
* Last Sync: 2026-06-28
|
|
71
|
-
*/
|
|
72
39
|
```
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## Proven in Practice
|
|
77
|
-
|
|
78
|
-
Guardian was used to build **[Rigorix](https://github.com/arman-jalili/rigorix-oss)** — a deterministic coding-agent runtime comprising 146,312 lines of Rust across 30 modules, 3 crates, and 580 commits — written by a single developer over 11 active days.
|
|
79
|
-
|
|
80
|
-
During that build:
|
|
81
|
-
|
|
82
|
-
- 18 ADRs defined the architecture
|
|
83
|
-
- 38 module specs described component contracts
|
|
84
|
-
- 44 issue drafts drove implementation across 120+ feature branches
|
|
85
|
-
- 7 validator scripts ran on every merge
|
|
86
|
-
- Architecture violations were detected in CI, reducing reliance on manual code review
|
|
87
|
-
|
|
88
|
-
[Rigorix](https://github.com/arman-jalili/rigorix-oss) serves as the public reference implementation demonstrating Guardian's workflow in practice. The architecture defined in `.pi/` was continuously validated against implementation — divergence was detected automatically before it reached the main branch.
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## Installation
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
# CLI tool — scaffold in any project
|
|
96
|
-
npx guardian-framework init
|
|
97
|
-
npm install -g guardian-framework
|
|
40
|
+
/domain --explore "Audit logging for regulated financial transactions"
|
|
98
41
|
```
|
|
99
42
|
|
|
43
|
+
> Output: structured domain analysis with contexts, entities, and a shared glossary.
|
|
100
44
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## Quick Start
|
|
106
|
-
|
|
107
|
-
### 1. Scaffold the framework
|
|
108
|
-
|
|
109
|
-
```bash
|
|
110
|
-
cd your-project
|
|
111
|
-
npx guardian-framework init
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
Interactive prompts for project name, language, AI tools, validators, and workflows.
|
|
115
|
-
|
|
116
|
-
### 2. Define your architecture
|
|
117
|
-
|
|
118
|
-
Architecture modules in `.pi/architecture/modules/` define components, dependencies, and status:
|
|
45
|
+
### 2. Define the Architecture
|
|
46
|
+
From the exploration, Guardian scaffolds architecture modules. Each module describes one bounded context: its components, dependencies, and contract interfaces.
|
|
119
47
|
|
|
120
48
|
```markdown
|
|
121
|
-
#
|
|
49
|
+
# Audit Ingestion
|
|
122
50
|
|
|
123
|
-
##
|
|
51
|
+
## HMAC Signature Verifier
|
|
124
52
|
status: planned
|
|
125
|
-
description:
|
|
53
|
+
description: Verifies HMAC-SHA256 signatures on incoming audit records.
|
|
126
54
|
depends: none
|
|
127
|
-
|
|
128
|
-
## OAuth2 Provider Integration
|
|
129
|
-
status: planned
|
|
130
|
-
description: Google, GitHub OAuth2 for SSO.
|
|
131
|
-
depends: JWT Token Validation
|
|
132
55
|
```
|
|
133
56
|
|
|
134
|
-
### 3.
|
|
57
|
+
### 3. Review & Decide
|
|
58
|
+
Architecture Decision Records (ADRs) capture every meaningful choice — why this approach, not that one. They're version-controlled, cross-referenced, and enforced.
|
|
135
59
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Generates source tree, build config, and CI pipeline with enforcement pre-wired.
|
|
60
|
+
> **ADR-004:** "Use HMAC-SHA256 with JCS canonicalization for audit signatures."
|
|
61
|
+
> Status: Accepted. Depends on: ADR-003 (JSON Canonicalization Scheme).
|
|
141
62
|
|
|
142
|
-
### 4. Plan
|
|
63
|
+
### 4. Plan the Roadmap
|
|
64
|
+
Group modules into delivery phases with dependencies, migrations, and acceptance criteria.
|
|
143
65
|
|
|
144
66
|
```
|
|
145
|
-
/architect --
|
|
146
|
-
/epic-plan --module auth docs/auth.md # Module-specific slice
|
|
67
|
+
/architect --roadmap
|
|
147
68
|
```
|
|
148
69
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
```bash
|
|
152
|
-
bash .pi/scripts/validate-ci.sh
|
|
153
|
-
bash .pi/scripts/validate-canonical.sh
|
|
154
|
-
guardian validate # TOML-based declarative validators
|
|
155
|
-
```
|
|
70
|
+
> Shows: Phase 0: Foundation (5 modules, Days 1–5), Phase 1: Core Pipeline (3 modules, Days 6–12)...
|
|
156
71
|
|
|
157
|
-
###
|
|
72
|
+
### 5. Execute Phases or Epics
|
|
73
|
+
Guardian generates issue files from your architecture — one issue per component, with full context, acceptance criteria, and auto-generated file changes.
|
|
158
74
|
|
|
159
|
-
```bash
|
|
160
|
-
guardian update --dryRun # Preview framework changes
|
|
161
|
-
guardian generate # Export to .claude/, .github/, .opencode/
|
|
162
75
|
```
|
|
163
|
-
|
|
164
|
-
---
|
|
165
|
-
|
|
166
|
-
## CLI Commands
|
|
167
|
-
|
|
168
|
-
| Command | Purpose |
|
|
169
|
-
|---------|---------|
|
|
170
|
-
| `init` | Scaffold `.pi/` framework and exports interactively |
|
|
171
|
-
| `generate` | Regenerate exports from `.pi/` source |
|
|
172
|
-
| `update` | Smart merge new templates, preserving user edits |
|
|
173
|
-
| `upgrade` | Migrate to new framework version |
|
|
174
|
-
| `uninstall` | Remove Guardian-managed files |
|
|
175
|
-
| `info` | Display manifest status, token stats, export sync |
|
|
176
|
-
| `stats` | Token savings analytics and USD estimation |
|
|
177
|
-
| `validate` | Run TOML-based declarative validators |
|
|
178
|
-
| `verify` | SHA-256 file integrity check |
|
|
179
|
-
| `trust` | Trust-gated config management |
|
|
180
|
-
| `domain` | Domain exploration — explore, scaffold, answer, list |
|
|
181
|
-
| `project create` | Generate source tree, build config, CI from architecture |
|
|
182
|
-
|
|
183
|
-
### `update` — Smart Merge
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
guardian update --dryRun # Preview changes
|
|
187
|
-
guardian update # Apply with confirmation
|
|
188
|
-
guardian update --force # Override user-modified files
|
|
189
|
-
guardian update --regenerate # Update and regenerate exports
|
|
76
|
+
/architect --phase "Phase 0"
|
|
190
77
|
```
|
|
191
78
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
| New template file | Add to project |
|
|
195
|
-
| Unchanged framework file | Update to new version |
|
|
196
|
-
| User file with YAML front matter | Merge — keep user config, replace body |
|
|
197
|
-
| User file without front matter | Preserve — keep as-is |
|
|
198
|
-
| Generated export | Mark for regeneration |
|
|
199
|
-
| Removed from templates | Orphan — noted, not deleted |
|
|
200
|
-
|
|
201
|
-
---
|
|
202
|
-
|
|
203
|
-
## Architecture
|
|
204
|
-
|
|
205
|
-
### Directory Structure
|
|
79
|
+
> Creates 5 epics × N component issues each, organized in a pipeline.
|
|
80
|
+
> Each issue includes: `Follow: .pi/skills/agents/rust-codegen.md` — the implementing agent gets the right DDD patterns automatically.
|
|
206
81
|
|
|
82
|
+
The agent implements each component. When done, it calls `pipeline_advance`. Guardian auto-advances through:
|
|
207
83
|
```
|
|
208
|
-
|
|
209
|
-
agent/AGENTS.md Project instructions + YAML runtime config
|
|
210
|
-
architecture/
|
|
211
|
-
modules/ Module architecture docs
|
|
212
|
-
decisions/ ADRs (Architecture Decision Records)
|
|
213
|
-
diagrams/ System overview, data flow diagrams
|
|
214
|
-
context/ Shared knowledge loaded once per session
|
|
215
|
-
domain/ Domain exploration artifacts
|
|
216
|
-
extensions/ 20 TypeScript extensions
|
|
217
|
-
prompts/ 21 workflow prompt templates
|
|
218
|
-
scripts/ 74 validator and utility shell scripts
|
|
219
|
-
ci/ 17 CI stage scripts
|
|
220
|
-
git/ 5 Git management scripts
|
|
221
|
-
languages/ Language-specific validators (Go=7, Java=9, Python=7, Rust=7, TypeScript=7)
|
|
222
|
-
skills/
|
|
223
|
-
agents/ 27 agent definitions
|
|
224
|
-
validators/ 10 validator skill definitions
|
|
225
|
-
validators/ TOML declarative validation configs
|
|
84
|
+
implement → validate → create-mr → merge
|
|
226
85
|
```
|
|
227
86
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
| Tool | Directory | Contents |
|
|
231
|
-
|------|-----------|----------|
|
|
232
|
-
| Claude Code | `.claude/` | Context, agents, workflows, scripts, architecture |
|
|
233
|
-
| OpenCode | `.opencode/` | Context, prompts, workflows, scripts |
|
|
234
|
-
| Agents (Antigravity) | `.agents/` | Agents, context, workflows, scripts |
|
|
235
|
-
| GitHub Copilot | `.github/` | Instructions, agents, copilot configs, workflows |
|
|
236
|
-
| oh-my-pi | `.omp/` | Agents, extensions |
|
|
237
|
-
| pi | `.pi/skills/` | SKILL.md packages |
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
## Extensions
|
|
242
|
-
|
|
243
|
-
20 TypeScript extensions for pi (`.pi/extensions/`), zero external npm dependencies:
|
|
244
|
-
|
|
245
|
-
| Extension | Purpose |
|
|
246
|
-
|-----------|---------|
|
|
247
|
-
| `architect.ts` | Epic orchestration — discover, implement, validate, merge, close |
|
|
248
|
-
| `pipeline.ts` | Multi-step workflow engine with per-step acceptance gates |
|
|
249
|
-
| `goal-loop.ts` | Standing goals with validator judge — auto-iterates until validated |
|
|
250
|
-
| `kanban.ts` | Durable task board with state machine, dependencies, comments |
|
|
251
|
-
| `domain-explorer.ts` | Domain exploration — explore, answer, scaffold, validate |
|
|
252
|
-
| `project-scaffolder.ts` | Project scaffolding from architecture decisions (Epic 0) |
|
|
253
|
-
| `coordinator.ts` | Scope classification + validation orchestration |
|
|
254
|
-
| `curator.ts` | Skill lifecycle — usage tracking, stale detection, archival |
|
|
255
|
-
| `bash-guard.ts` | Destructive command blocking with risk analysis |
|
|
256
|
-
| `filechanges.ts` | File change tracking with accept/decline review |
|
|
257
|
-
| `plan-mode.ts` | Queued edits for batch review |
|
|
258
|
-
| `snippets.ts` | `#handle` token expansion |
|
|
259
|
-
| `session-persistence.ts` | Structured session lifecycle with auto-titling |
|
|
260
|
-
| `redaction.ts` | Automatic secret redaction |
|
|
261
|
-
| `hooks.ts` | Declarative shell hooks for lifecycle events |
|
|
262
|
-
| `config-reload.ts` | Hot config reload |
|
|
263
|
-
| `read-only-mode.ts` | Safe codebase exploration |
|
|
264
|
-
| `ask-user-question.ts` | Structured user prompts (text, single-select, multi-select) |
|
|
265
|
-
| `slash-commands.ts` | `/init`, `/validate`, `/scope`, `/snippet` commands |
|
|
266
|
-
| `validation-runner.ts` | `/validate` command for running validators |
|
|
87
|
+
If CI fails (architecture violation, security issue, broken test), the pipeline blocks until fixed.
|
|
267
88
|
|
|
268
89
|
---
|
|
269
90
|
|
|
270
|
-
##
|
|
271
|
-
|
|
272
|
-
21 workflow prompt templates in `.pi/prompts/`:
|
|
273
|
-
|
|
274
|
-
### Implementation Workflows
|
|
275
|
-
| Workflow | File | Use When |
|
|
276
|
-
|----------|------|----------|
|
|
277
|
-
| Feature Development | `feature-development.md` | New features (Moderate+ scope) |
|
|
278
|
-
| Bug Fix | `bug-fix.md` | Bug fixes (Simple/Moderate) |
|
|
279
|
-
| Emergency Hotfix | `hotfix.md` | Production issues (skip planning) |
|
|
280
|
-
| Refactoring | `refactoring.md` | Code improvement (behavior unchanged) |
|
|
281
|
-
| Issue Implementation Series | `issue-implementation-series.md` | Batch implementation via pipeline |
|
|
282
|
-
|
|
283
|
-
### Epic and Issue Management
|
|
284
|
-
| Workflow | File | Purpose |
|
|
285
|
-
|----------|------|---------|
|
|
286
|
-
| Epic Plan | `epic-plan.md` | Cross-module, module-slice, or free-form epic planning |
|
|
287
|
-
| Epic Template | `epic-template.md` | Epic definition template |
|
|
288
|
-
| Issue Template | `issue-template.md` | Single issue template |
|
|
289
|
-
| Issue Template Set | `issue-template-set.md` | Full template set for all issue types |
|
|
290
|
-
| Issue Draft | `issue-draft.md` | Create draft issues from approved epic |
|
|
291
|
-
| Git Issues | `git-issues.md` | Create epics/issues on GitHub/GitLab |
|
|
292
|
-
| Issue Closeout | `issue-closeout.md` | Verify AC, validators, canonical, MR |
|
|
293
|
-
| Issue Merge | `issue-merge.md` | Merge MR, close issue, update epic |
|
|
294
|
-
| Plan to Issues | `plan-to-issues.md` | Convert plan documents to GitHub/GitLab issues |
|
|
295
|
-
|
|
296
|
-
### Blueprint and Maintenance
|
|
297
|
-
| Workflow | File | Purpose |
|
|
298
|
-
|----------|------|---------|
|
|
299
|
-
| Blueprint Validate | `blueprint-validate.md` | Validate `.pi/` structure and integrity |
|
|
300
|
-
| CI Blueprint | `ci-blueprint.md` | CI pipeline configuration blueprint |
|
|
301
|
-
| Sync Check | `sync-check.md` | Verify exports match blueprint source |
|
|
302
|
-
| Context Refresh | `context-refresh.md` | Update context from codebase |
|
|
303
|
-
| Scope Analyzer | `scope-analyzer.md` | Auto-determine change scope + validators |
|
|
304
|
-
| Pattern Extract | `pattern-extract.md` | Extract patterns to `patterns.md` |
|
|
305
|
-
| Blueprint Update | `blueprint-update.md` | Reverse-sync implementation to blueprint |
|
|
306
|
-
|
|
307
|
-
---
|
|
91
|
+
## What Makes Guardian Different
|
|
308
92
|
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
|
312
|
-
|
|
313
|
-
|
|
|
314
|
-
|
|
|
315
|
-
|
|
|
316
|
-
| `/architect abort` | Cancel epic |
|
|
317
|
-
| `/architect --roadmap` | Show all roadmap phases with status |
|
|
318
|
-
| `/architect --phase "Phase 1"` | Start a roadmap phase — creates epics for all modules |
|
|
319
|
-
| `/architect --phase-status` | Show current/next pending phase |
|
|
320
|
-
| `/architect --phase-done <N>` | Mark a phase complete |
|
|
321
|
-
| `/architect --phase-module-done <N> "Module"` | Mark a module done within a phase |
|
|
322
|
-
| `/domain --explore "..."` | Start domain exploration |
|
|
323
|
-
| `/domain --validate <id>` | Validate against domain files |
|
|
324
|
-
| `/domain --architect-scaffold <id>` | Generate module docs from exploration |
|
|
325
|
-
| `/project create --lang java ...` | Scaffold project |
|
|
326
|
-
| `/project status` | Check scaffold status |
|
|
327
|
-
| `/pipeline "Name" --items "A,B" --steps "x,y"` | Start multi-step pipeline |
|
|
328
|
-
| `/pipeline status | pause | resume | abort` | Manage pipeline |
|
|
329
|
-
| `/goal "objective" --validators=ci,tests` | Set persistent goal |
|
|
330
|
-
| `/goal status | pause | resume | clear` | Manage goal |
|
|
331
|
-
| `/subgoal "..." | list | remove | clear` | Manage subgoals |
|
|
332
|
-
| `/kanban create | list | status` | Task board |
|
|
333
|
-
| `/curator review | pin | unpin` | Skill lifecycle |
|
|
334
|
-
| `/snippet list | add | remove | edit` | Token expansion snippets |
|
|
335
|
-
| `/plan` / `/plan-apply` | Queue edits for batch review |
|
|
336
|
-
| `/validate` | Run validators |
|
|
93
|
+
| Instead of... | Guardian does this |
|
|
94
|
+
|---------------|-------------------|
|
|
95
|
+
| Drawing diagrams that go stale | Generates CI scripts that check structure on every commit |
|
|
96
|
+
| 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 |
|
|
97
|
+
| Trusting code review to catch drift | Blocks merges when architecture is violated — no human oversight needed |
|
|
98
|
+
| Onboarding new devs with 30-page docs | Every issue carries its full context: architecture reference, codegen patterns, acceptance criteria |
|
|
99
|
+
| One-size-fits-all prompts | Generates language-specific codegen skills (Rust, Go, Python, TypeScript, Java/Spring Boot) with DDD + Clean Architecture patterns |
|
|
337
100
|
|
|
338
101
|
---
|
|
339
102
|
|
|
340
|
-
##
|
|
341
|
-
|
|
342
|
-
Tools callable programmatically by the agent during a session:
|
|
343
|
-
|
|
344
|
-
| Tool | Purpose |
|
|
345
|
-
|------|---------|
|
|
346
|
-
| `guardian_scope` | Classify change scope (Simple to Critical) |
|
|
347
|
-
| `guardian_validate` | Run validation scripts by category |
|
|
348
|
-
| `guardian_coordinate` | Orchestrate scope + validation workflow |
|
|
349
|
-
| `guardian_goal_evaluate` | Evaluate goal progress (validator + LLM judge) |
|
|
350
|
-
| `architect_status` | Show epic state |
|
|
351
|
-
| `architect_discover` | Find modules + next slice |
|
|
352
|
-
| `architect_roadmap` | Show roadmap phases and status |
|
|
353
|
-
| `pipeline_status` | Pipeline progress |
|
|
354
|
-
| `pipeline_advance` | Mark step passed |
|
|
355
|
-
| `pipeline_fail` | Mark step failed |
|
|
356
|
-
| `pipeline_start` | Start pipeline programmatically |
|
|
357
|
-
| `pipeline_next_task` | Get current item + step context |
|
|
358
|
-
| `pipeline_run_acceptance` | Run step acceptance gates |
|
|
359
|
-
| `kanban_create` | Create task |
|
|
360
|
-
| `kanban_list` | List tasks |
|
|
361
|
-
| `kanban_show` | Show task details |
|
|
362
|
-
| `kanban_complete` | Mark done |
|
|
363
|
-
| `kanban_block` | Block with reason |
|
|
364
|
-
| `kanban_comment` | Add comment |
|
|
365
|
-
| `domain_explore` | Create exploration prompt |
|
|
366
|
-
| `domain_save_result` | Save analysis session |
|
|
367
|
-
| `domain_validate` | Validate against glossary |
|
|
368
|
-
| `curator_review` | Detect stale skills |
|
|
369
|
-
| `curator_pin` | Protect from archival |
|
|
370
|
-
| `curator_unpin` | Allow archival |
|
|
371
|
-
| `ask_user_question` | Ask user structured questions |
|
|
372
|
-
|
|
373
|
-
---
|
|
374
|
-
|
|
375
|
-
## Token Optimization
|
|
376
|
-
|
|
377
|
-
Guardian includes several mechanisms to reduce token consumption when working with LLM-based coding agents:
|
|
378
|
-
|
|
379
|
-
| Mechanism | How It Works |
|
|
380
|
-
|-----------|-------------|
|
|
381
|
-
| DRY Context | Shared templates loaded once per session rather than per-turn |
|
|
382
|
-
| Snippet Expansion | `#handle` tokens expand to full content on demand |
|
|
383
|
-
| TOML Filters | 8-stage filter pipeline compresses command output before sending to LLM |
|
|
384
|
-
| Validator Scripts | Shell scripts replace LLM-based checks for mechanical validations |
|
|
385
|
-
| Context Compaction | Budget-aware truncation prioritizing structurally important lines |
|
|
103
|
+
## Built with Guardian
|
|
386
104
|
|
|
387
|
-
|
|
105
|
+
**[Rigorix](https://github.com/arman-jalili/rigorix-oss)** — a deterministic coding-agent runtime built using Guardian's own workflow:
|
|
106
|
+
- 146,312 lines of Rust
|
|
107
|
+
- 30 modules across 3 crates
|
|
108
|
+
- 18 ADRs, 38 module specs, 44 issue drafts
|
|
109
|
+
- 580 commits over 11 active days
|
|
110
|
+
- Built by a single developer — Guardian handled orchestration and enforcement
|
|
388
111
|
|
|
389
112
|
---
|
|
390
113
|
|
|
391
|
-
##
|
|
392
|
-
|
|
393
|
-
| Language | Build | Test | Lint | Format | Validators |
|
|
394
|
-
|----------|-------|------|------|--------|------------|
|
|
395
|
-
| TypeScript | `bun build` | `bun test` | `biome check` | `biome format` | 7 |
|
|
396
|
-
| Rust | `cargo build` | `cargo test` | `cargo clippy` | `cargo fmt` | 7 |
|
|
397
|
-
| Python | `python -m build` | `pytest` | `ruff check` | `ruff format` | 7 |
|
|
398
|
-
| Go | `go build ./...` | `go test ./...` | `golangci-lint` | `gofmt` | 7 |
|
|
399
|
-
| Java / Spring Boot | `mvn` / `gradle` | JUnit + Mockito | Checkstyle / Spotless | Spotless | 9 |
|
|
400
|
-
|
|
401
|
-
---
|
|
402
|
-
|
|
403
|
-
## Workflow Configuration
|
|
404
|
-
|
|
405
|
-
`.pi/agent/AGENTS.md` carries YAML front matter defining runtime settings:
|
|
406
|
-
|
|
407
|
-
```yaml
|
|
408
|
-
agent:
|
|
409
|
-
max_turns: 20
|
|
410
|
-
max_retry_backoff_ms: 300000
|
|
411
|
-
stall_timeout_ms: 300000
|
|
412
|
-
|
|
413
|
-
generate:
|
|
414
|
-
on_conflict: warn
|
|
415
|
-
atomic_writes: true
|
|
416
|
-
|
|
417
|
-
validate:
|
|
418
|
-
fail_fast: false
|
|
419
|
-
timeout_ms: 300000
|
|
420
|
-
|
|
421
|
-
goal:
|
|
422
|
-
enabled: true
|
|
423
|
-
max_turns: 20
|
|
424
|
-
judge_validator: true
|
|
425
|
-
|
|
426
|
-
kanban:
|
|
427
|
-
enabled: true
|
|
428
|
-
auto_create_tasks: true
|
|
114
|
+
## Quick Start
|
|
429
115
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
stale_after_days: 30
|
|
433
|
-
archive_after_days: 90
|
|
434
|
-
auto_review: true
|
|
116
|
+
```bash
|
|
117
|
+
npx guardian-framework init
|
|
435
118
|
```
|
|
436
119
|
|
|
437
|
-
|
|
120
|
+
Answer 4 prompts (project name, language, AI tools, validators). You get:
|
|
121
|
+
- A `.pi/` directory with full architecture scaffolding
|
|
122
|
+
- 20 TypeScript extensions (orchestration, pipeline, kanban, validation, etc.)
|
|
123
|
+
- 21 workflow prompt templates
|
|
124
|
+
- 74 CI scripts with language-specific validators
|
|
125
|
+
- Agent export files for Claude Code, pi, Copilot, Cursor, and more
|
|
438
126
|
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
bun run lint # biome check .
|
|
446
|
-
bun run format # biome format . --write
|
|
447
|
-
bun run typecheck # tsc --noEmit
|
|
127
|
+
Then:
|
|
128
|
+
```
|
|
129
|
+
cd your-project && pi
|
|
130
|
+
/domain --explore "your business domain"
|
|
131
|
+
/architect --roadmap
|
|
132
|
+
/architect --phase "Phase 0"
|
|
448
133
|
```
|
|
449
134
|
|
|
450
135
|
---
|
|
451
136
|
|
|
452
|
-
##
|
|
137
|
+
## One File, One Constraint
|
|
453
138
|
|
|
454
|
-
|
|
455
|
-
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
456
|
-
- **Security:** [SECURITY.md](SECURITY.md)
|
|
457
|
-
- **Changelog:** [CHANGELOG.md](CHANGELOG.md)
|
|
458
|
-
- **Code of Conduct:** [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
|
|
459
|
-
- **Architecture:** See `.pi/architecture/decisions/` for all ADRs
|
|
139
|
+
At the heart of every file is a canonical reference:
|
|
460
140
|
|
|
461
|
-
|
|
141
|
+
```typescript
|
|
142
|
+
//! @canonical .pi/architecture/modules/auth-system.md#token-validation
|
|
143
|
+
//! Issue: #42
|
|
144
|
+
```
|
|
462
145
|
|
|
463
|
-
|
|
146
|
+
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.
|
|
464
147
|
|
|
465
|
-
|
|
148
|
+
---
|
|
466
149
|
|
|
467
150
|
## Links
|
|
468
151
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
152
|
+
| | |
|
|
153
|
+
|---|---|
|
|
154
|
+
| **Full User Manual** | [docs/USER_MANUAL.md](docs/USER_MANUAL.md) — every workflow, every command, validated against source |
|
|
155
|
+
| **Reference Implementation** | [Rigorix](https://github.com/arman-jalili/rigorix-oss) — 146K LOC Rust, 30 modules, built with Guardian |
|
|
156
|
+
| **Source** | [github.com/arman-jalili/guardian-framework](https://github.com/arman-jalili/guardian-framework) |
|
|
157
|
+
| **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.15", 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.15", 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