guardian-framework 0.1.61 → 0.1.62
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 +10 -0
- package/dist/cli.js +1 -1
- package/dist/exports.js +1 -1
- package/package.json +1 -1
- package/templates/pi/INDEX.md +1 -0
- package/templates/pi/preflight_report.json +1 -1
- package/templates/pi/skills/tdd-practice.md +124 -0
package/README.md
CHANGED
|
@@ -172,6 +172,16 @@ The agent implements. You review PRs. Guardian auto-advances through the pipelin
|
|
|
172
172
|
implement → validate → create-mr → merge
|
|
173
173
|
```
|
|
174
174
|
|
|
175
|
+
#### Optional: TDD Mode
|
|
176
|
+
|
|
177
|
+
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.
|
|
178
|
+
|
|
179
|
+
No LLM is involved in test generation. Every test is derived from structured component data (name, description, dependencies, affected layers).
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
/architect --epic "Auth Module" --tdd
|
|
183
|
+
```
|
|
184
|
+
|
|
175
185
|
### 7. Enforcement Closes the Loop
|
|
176
186
|
|
|
177
187
|
Every change is validated against the architecture:
|
package/dist/cli.js
CHANGED
|
@@ -3178,7 +3178,7 @@ __export(exports_package, {
|
|
|
3178
3178
|
bin: () => bin,
|
|
3179
3179
|
author: () => author
|
|
3180
3180
|
});
|
|
3181
|
-
var name = "guardian-framework", version = "0.1.
|
|
3181
|
+
var name = "guardian-framework", version = "0.1.62", 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;
|
|
3182
3182
|
var init_package = __esm(() => {
|
|
3183
3183
|
exports = {
|
|
3184
3184
|
".": {
|
package/dist/exports.js
CHANGED
|
@@ -1963,7 +1963,7 @@ __export(exports_package, {
|
|
|
1963
1963
|
bin: () => bin,
|
|
1964
1964
|
author: () => author
|
|
1965
1965
|
});
|
|
1966
|
-
var name = "guardian-framework", version = "0.1.
|
|
1966
|
+
var name = "guardian-framework", version = "0.1.62", 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;
|
|
1967
1967
|
var init_package = __esm(() => {
|
|
1968
1968
|
exports = {
|
|
1969
1969
|
".": {
|
package/package.json
CHANGED
package/templates/pi/INDEX.md
CHANGED
|
@@ -417,6 +417,7 @@ When running `guardian-framework generate`, `.pi/` files are transformed:
|
|
|
417
417
|
| `architecture/modules/*.md` | `.claude/architecture/*.md` | Direct copy + canonical header |
|
|
418
418
|
| `architecture/CHANGELOG.md` | `.claude/architecture/CHANGELOG.md` | Direct copy |
|
|
419
419
|
| `skills/rust-enterprise-codegen.md` | `.pi/skills/rust-enterprise-codegen.md` | Direct copy — full reference patterns |
|
|
420
|
+
| `skills/tdd-practice.md` | `.pi/skills/tdd-practice.md` | Direct copy — TDD practice guidance for agents |
|
|
420
421
|
| `skills/agents/*.md` | `.claude/agents/*.md`, `.github/agents/*.agent.md` | Direct copy + YAML frontmatter |
|
|
421
422
|
| `skills/validators/*.md` | `.opencode/prompts/*.txt` | Convert to .txt, compress |
|
|
422
423
|
| `context/*.md` | `.claude/context/*.md`, `.opencode/context/*.md` | Direct copy + canonical header |
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tdd-practice
|
|
3
|
+
description: TDD practice guide for Guardian implementation agents. Use when TDD mode is enabled on an epic — follows Red→Green→Refactor with pre-generated failing tests from architecture contracts.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# TDD Practice — Red → Green → Refactor
|
|
7
|
+
|
|
8
|
+
> This skill applies when TDD mode is enabled on the current epic (`--tdd`).
|
|
9
|
+
> Pre-generated failing test files exist in `tests/unit/<module>/<component>/`.
|
|
10
|
+
> These tests were generated deterministically from architecture contracts — no LLM involvement.
|
|
11
|
+
|
|
12
|
+
## Core Principle
|
|
13
|
+
|
|
14
|
+
Tests are **living artifacts**. They evolve with the code:
|
|
15
|
+
|
|
16
|
+
1. They start as minimal failing tests generated from architecture contracts
|
|
17
|
+
2. As you implement, you expand them to cover real behavior
|
|
18
|
+
3. When you refactor, you update both code and tests
|
|
19
|
+
4. They remain as regression protection for the lifetime of the component
|
|
20
|
+
|
|
21
|
+
Do NOT treat the generated tests as rigid specs you must match exactly. Treat them as a starting point. If the implementation reveals a better API than the generated test assumes, update the test.
|
|
22
|
+
|
|
23
|
+
## Workflow
|
|
24
|
+
|
|
25
|
+
### 1. Red — See the test fail
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
bun test tests/unit/<module>/<component>/<component>.test.ts
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Confirm the test fails before writing any implementation code. This validates that:
|
|
32
|
+
- The test infrastructure works
|
|
33
|
+
- The test is actually testing something (not a false positive)
|
|
34
|
+
- You understand what "not implemented" looks like
|
|
35
|
+
|
|
36
|
+
### 2. Green — Make the test pass
|
|
37
|
+
|
|
38
|
+
Write the minimal implementation to make the failing test pass.
|
|
39
|
+
|
|
40
|
+
**Guidelines:**
|
|
41
|
+
- Write only enough code to pass the test
|
|
42
|
+
- Do not over-engineer — YAGNI
|
|
43
|
+
- Use the test's TODO comments as a guide for what the API should look like
|
|
44
|
+
- The test file is in `tests/unit/`, implementation files go in `src/`
|
|
45
|
+
- Import the implementation module into the test file
|
|
46
|
+
|
|
47
|
+
If the generated test assumes an API shape that doesn't fit, **update the test first**, then implement.
|
|
48
|
+
|
|
49
|
+
Example — given a generated test:
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
it("should be defined", () => {
|
|
53
|
+
// TODO: uncomment when MyComponent is implemented
|
|
54
|
+
// const instance = new MyComponent();
|
|
55
|
+
// expect(instance).toBeDefined();
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**Step 1:** Uncomment and update to match the actual API:
|
|
60
|
+
|
|
61
|
+
```typescript
|
|
62
|
+
import { MyComponent } from "../../../src/module/my-component";
|
|
63
|
+
|
|
64
|
+
it("should be defined", () => {
|
|
65
|
+
const instance = new MyComponent();
|
|
66
|
+
expect(instance).toBeDefined();
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Step 2:** Create the minimal implementation:
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
export class MyComponent {
|
|
74
|
+
// Minimal implementation — add methods as tests require them
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Step 3:** Run the test — it should pass.
|
|
79
|
+
|
|
80
|
+
### 3. Refactor — Improve without breaking tests
|
|
81
|
+
|
|
82
|
+
Once the test passes, improve the code quality:
|
|
83
|
+
|
|
84
|
+
- Extract duplication
|
|
85
|
+
- Add error handling
|
|
86
|
+
- Follow Clean Architecture / DDD patterns
|
|
87
|
+
- Run tests again to confirm nothing broke
|
|
88
|
+
|
|
89
|
+
## Handling Generated Tests
|
|
90
|
+
|
|
91
|
+
The generated tests are **suggestions, not constraints**. You should modify them when:
|
|
92
|
+
|
|
93
|
+
- **API mismatch**: The real component has a different constructor signature or method name — update the test
|
|
94
|
+
- **Missing edge cases**: Add new `it()` blocks for edge cases the generator didn't anticipate
|
|
95
|
+
- **Wrong test type**: The generator created an instantiation test but what you need is a behavior test — rewrite it
|
|
96
|
+
- **Layer evolution**: The generator guessed a domain test but the component only needs application-layer behavior — adjust
|
|
97
|
+
|
|
98
|
+
**Do NOT** delete test files. If a test is genuinely wrong, fix it. If a component doesn't need tests (rare), leave the file with a comment explaining why.
|
|
99
|
+
|
|
100
|
+
## Test Structure Conventions
|
|
101
|
+
|
|
102
|
+
- One `describe` block per component: `describe("ComponentName", () => { ... })`
|
|
103
|
+
- Descriptive `it` names explaining the behavior: `it("should reject invalid input")`
|
|
104
|
+
- Use `beforeEach` for shared setup
|
|
105
|
+
- No test interdependencies — each `it` runs independently
|
|
106
|
+
- Mock external dependencies (APIs, databases) at boundaries
|
|
107
|
+
|
|
108
|
+
## File Locations
|
|
109
|
+
|
|
110
|
+
| Artifact | Path |
|
|
111
|
+
|----------|------|
|
|
112
|
+
| Tests | `tests/unit/<module>/<component>/<component>.test.ts` |
|
|
113
|
+
| Implementation | `src/<module>/<component>.ts` (or appropriate layer) |
|
|
114
|
+
| TDD guide | `.pi/skills/tdd-practice.md` |
|
|
115
|
+
|
|
116
|
+
## Anti-Patterns
|
|
117
|
+
|
|
118
|
+
- ❌ Writing all tests upfront before any implementation code (only the generated skeleton exists)
|
|
119
|
+
- ❌ Making tests pass without understanding what they test
|
|
120
|
+
- ❌ Deleting generated tests because they "look hard to implement"
|
|
121
|
+
- ❌ Adding production code that has no corresponding test
|
|
122
|
+
- ❌ Skipping the "Red" step — you need to see the test fail to know it can pass
|
|
123
|
+
- ❌ Over-mocking — prefer real objects when feasible
|
|
124
|
+
- ❌ Treating generated tests as immutable contracts
|