gabbe-kit 1.0.2 → 1.1.0
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 +21 -0
- package/agents/AGENTS.md +33 -1
- package/agents/CONSTITUTION.md +1 -1
- package/agents/guides/ai/ai-agentic.md +2 -4
- package/agents/guides/ai/multi-agent-systems.md +1 -1
- package/agents/guides/patterns/ai-native-scenarios.md +2 -2
- package/agents/skills/coding/secure-coding.skill.md +1 -1
- package/agents/skills/core/audit-trail.skill.md +1 -1
- package/agents/skills/security/ai-safety-guardrails.skill.md +3 -3
- package/agents/templates/coordination/AGENTS_TEMPLATE.md +25 -1
- package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +1 -1
- package/bin/install.js +36 -6
- package/docs/CLI_REFERENCE.md +43 -5
- package/docs/INSTALL.md +23 -10
- package/package.json +2 -2
- package/scripts/init.py +488 -8
package/README.md
CHANGED
|
@@ -63,10 +63,18 @@ It contains:
|
|
|
63
63
|
```bash
|
|
64
64
|
npx gabbe-kit init # Node installer — bundles the kit, wires every agent
|
|
65
65
|
npx gabbe-kit init --agents claude,cursor,antigravity,opencode --yes # non-interactive
|
|
66
|
+
npx gabbe-kit init --force # re-template even preserved files (each is backed up first)
|
|
66
67
|
# or, without npm:
|
|
67
68
|
curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh | sh
|
|
68
69
|
```
|
|
69
70
|
|
|
71
|
+
> **Never-clobber.** Both installers — the Node installer (`npx gabbe-kit init`) and
|
|
72
|
+
> the Python wizard (`gabbe setup` / `python scripts/init.py`) — back up ANY differing
|
|
73
|
+
> pre-existing file to `<name>.gabbe-bak` before refreshing it; nothing you already had
|
|
74
|
+
> is silently overwritten. The preserve-set (`AGENTS.md`, `CONSTITUTION.md`, `TASKS.md`,
|
|
75
|
+
> `policies.yml`, `config.json`) is left untouched unless you pass `--force`, which
|
|
76
|
+
> opts into re-templating them too (still backing each up first).
|
|
77
|
+
|
|
70
78
|
**Python / PyPI:**
|
|
71
79
|
```bash
|
|
72
80
|
pipx install gabbe # installs the `gabbe` CLI (doctor / brain / route / gateway)
|
|
@@ -84,10 +92,19 @@ The installer is a **Universal Skill Compiler** — it generates the correct for
|
|
|
84
92
|
- **Zed / Continue / Roo Code / Kilo Code**: root `AGENTS.md` (agents.md standard) + each tool's rules file
|
|
85
93
|
- Every install also writes a root `AGENTS.md` (the agents.md open standard).
|
|
86
94
|
|
|
95
|
+
**Greenfield vs. brownfield (autodetect).** In an empty directory the wizard runs the
|
|
96
|
+
greenfield flow unchanged. In an **existing codebase** (detected via `package.json`,
|
|
97
|
+
`pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`, `pom.xml`, `Gemfile`, a `.git`
|
|
98
|
+
repo, etc.) it adds a **Mode** question — greenfield build vs **Upgrade / Refactor
|
|
99
|
+
existing** — prefills the detected language / framework / package-manager / project-name
|
|
100
|
+
as defaults, and in refactor mode scaffolds a `BROWNFIELD_ONBOARDING.md` discovery brief
|
|
101
|
+
(map → assess → baseline → backlog) instead of greenfield mission docs.
|
|
102
|
+
|
|
87
103
|
Steps after running the wizard:
|
|
88
104
|
|
|
89
105
|
1. **Verify Context**
|
|
90
106
|
- Open `agents/AGENTS.md` and check the `Tech Stack` section and other [PLACEHOLDER] or Optional sections.
|
|
107
|
+
- The wizard auto-fills derivable `[PLACEHOLDER:]` fields — dev/test/lint/format/typecheck/coverage commands (by package manager), `repo_url` (from the git remote), and `ci_cd` / `deployment_target` (from detected files). Fields it can't derive are kept and tagged `<!-- OPTIONAL: fill this in yourself -->`, and the installer prints an end-of-install warning listing them so blank fields are never shipped silently. Fill them in or re-run `gabbe setup`.
|
|
91
108
|
- Open `agents/CONSTITUTION.md` and review project laws.
|
|
92
109
|
|
|
93
110
|
2. **Feed the Mission**
|
|
@@ -526,6 +543,10 @@ Config in AGENTS.md: test_cmd="pytest", lint_cmd="ruff check ."
|
|
|
526
543
|
|
|
527
544
|
## 📋 SDLC Phases (10 Gates)
|
|
528
545
|
|
|
546
|
+
The table below enumerates the **10 SDLC gates (S01–S10)**. These are bracketed by
|
|
547
|
+
the Day-0 phase **S00 (Strategy & Discovery)** and the Day-2 phases **S11–S13
|
|
548
|
+
(Operate / Evolve / Decommission)** that complete the cradle-to-grave ADLC (S00–S13).
|
|
549
|
+
|
|
529
550
|
| Phase | Gate | Key Artifact |
|
|
530
551
|
|---|---|---|
|
|
531
552
|
| S01 | Requirements | `PRD_TEMPLATE.md` (EARS syntax) |
|
package/agents/AGENTS.md
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## 1. Project Identity (REQUIRED VARIABLES)
|
|
10
|
+
>
|
|
10
11
|
> **ACTION REQUIRED**: Replace all `[PLACEHOLDER: ...]` values below with your specific stack.
|
|
11
12
|
|
|
12
13
|
```yaml
|
|
@@ -129,6 +130,7 @@ every task (episodic, semantic, AUDIT_LOG, CONTINUITY, PROJECT_STATE, RESUME_POI
|
|
|
129
130
|
- **Human–agent collaboration (manager, not operator)** — the human delegates → observes → intervenes on exceptions. Keep three questions always answerable: **Purpose** (scope/non-goals via spec), **Transparency** (legible reasoning/tools/cost via observability), **Control** (pause/correct/approve via HITL). Prefer an async, observable surface; "done" only when all three hold (`guides/principles/human-agent-collaboration.md`).
|
|
130
131
|
|
|
131
132
|
### Step 0 — Preflight & Clarify (before anything else)
|
|
133
|
+
|
|
132
134
|
```
|
|
133
135
|
Run preflight.skill as the FIRST action of every session and every major task:
|
|
134
136
|
1. Auto-checks: integrity-check (fast) → confirm memory + working tree are coherent.
|
|
@@ -146,6 +148,7 @@ posture is `auto` AND the task is cheap AND reversible.
|
|
|
146
148
|
```
|
|
147
149
|
|
|
148
150
|
### Step 1 — Load Context (every session start)
|
|
151
|
+
|
|
149
152
|
```
|
|
150
153
|
1. Read this AGENTS.md completely
|
|
151
154
|
2. Read CONSTITUTION.md if it exists
|
|
@@ -155,6 +158,7 @@ posture is `auto` AND the task is cheap AND reversible.
|
|
|
155
158
|
```
|
|
156
159
|
|
|
157
160
|
### Step 2 — Plan Before Coding
|
|
161
|
+
|
|
158
162
|
```
|
|
159
163
|
Before touching any file, write a brief implementation plan.
|
|
160
164
|
|
|
@@ -168,18 +172,21 @@ For complex tasks: write PLAN.md or use PLAN_TEMPLATE.md
|
|
|
168
172
|
```
|
|
169
173
|
|
|
170
174
|
### Step 3 — Test First (TDD Red Phase)
|
|
175
|
+
|
|
171
176
|
```
|
|
172
177
|
Write the failing test BEFORE writing implementation code.
|
|
173
178
|
<!-- OPTIONAL: Detailed TDD Red -> The test MUST fail (Red). Do not implement features not covered by a test -->
|
|
174
179
|
```
|
|
175
180
|
|
|
176
181
|
### Step 4 — Implement (TDD Green Phase)
|
|
182
|
+
|
|
177
183
|
```
|
|
178
184
|
Write the minimal code to make the failing test pass.
|
|
179
185
|
<!-- OPTIONAL: Detailed TDD Green -> Do not add features not covered by a failing test -->
|
|
180
186
|
```
|
|
181
187
|
|
|
182
188
|
### Step 5 — Verify (must all pass before marking done)
|
|
189
|
+
|
|
183
190
|
```
|
|
184
191
|
Run: [test command] -> must pass
|
|
185
192
|
Run: [typecheck command] -> must pass
|
|
@@ -188,12 +195,14 @@ Run: [lint command] -> must pass
|
|
|
188
195
|
```
|
|
189
196
|
|
|
190
197
|
### Step 6 — Refactor
|
|
198
|
+
|
|
191
199
|
```
|
|
192
200
|
Improve code quality while keeping all tests green.
|
|
193
201
|
<!-- OPTIONAL: Refactoring Metrics -> E.g. Complexity < 10, no duplication > 3 -->
|
|
194
202
|
```
|
|
195
203
|
|
|
196
204
|
### Step 7 — Log & Complete
|
|
205
|
+
|
|
197
206
|
```
|
|
198
207
|
Write entry to agents/memory/AUDIT_LOG.md
|
|
199
208
|
Update task status in project/TASKS.md to DONE
|
|
@@ -211,9 +220,11 @@ Refresh agents/memory/RESUME_POINTER.md (state-preserve.skill) — keep the
|
|
|
211
220
|
## 6. Governance & Security
|
|
212
221
|
|
|
213
222
|
### 🛡️ Mandatory Security & Guardrails
|
|
223
|
+
|
|
214
224
|
Agents MUST adhere to the **Security & Guardrails** section appended to the bottom of whatever skill they are currently executing. Bypassing these skill-specific guardrails is strictly forbidden.
|
|
215
225
|
|
|
216
226
|
### Forbidden Actions (agents must never do these without explicit human approval)
|
|
227
|
+
|
|
217
228
|
```
|
|
218
229
|
- Commit .env files or any file containing secrets
|
|
219
230
|
- Push directly to main/master branch
|
|
@@ -228,6 +239,7 @@ Agents MUST adhere to the **Security & Guardrails** section appended to the bott
|
|
|
228
239
|
```
|
|
229
240
|
|
|
230
241
|
### Secrets Policy
|
|
242
|
+
|
|
231
243
|
```
|
|
232
244
|
All secrets MUST be in environment variables.
|
|
233
245
|
Local dev: .env file (always in .gitignore)
|
|
@@ -237,6 +249,7 @@ Use: [PLACEHOLDER: dotenv | .env.vault | AWS Secrets Manager | HashiCorp Vault]
|
|
|
237
249
|
```
|
|
238
250
|
|
|
239
251
|
### PR Format (Conventional Commits)
|
|
252
|
+
|
|
240
253
|
```
|
|
241
254
|
Format: <type>(<scope>): <subject>
|
|
242
255
|
|
|
@@ -253,6 +266,7 @@ PR body must include:
|
|
|
253
266
|
```
|
|
254
267
|
|
|
255
268
|
### Quality Gates (all must pass before PR merges)
|
|
269
|
+
|
|
256
270
|
```
|
|
257
271
|
<!-- OPTIONAL: Quality Gates Specifics -> Document testing, linting, code coverage >99%, CI integration gates -->
|
|
258
272
|
```
|
|
@@ -264,11 +278,13 @@ PR body must include:
|
|
|
264
278
|
Agents must use authoritative sources. Never guess or hallucinate.
|
|
265
279
|
|
|
266
280
|
### Source Tiers (in order of trust)
|
|
281
|
+
|
|
267
282
|
```
|
|
268
283
|
<!-- OPTIONAL: Source Tiers -> Tier 1: Official docs/Specs. Tier 2: Academic. Tier 3: Verified blogs. Avoid: Reddit/SO. -->
|
|
269
284
|
```
|
|
270
285
|
|
|
271
286
|
### Research Gate -- mandatory before:
|
|
287
|
+
|
|
272
288
|
```
|
|
273
289
|
- Using any library not in existing package.json / composer.json
|
|
274
290
|
- Calling any API method not confirmed in official docs
|
|
@@ -277,6 +293,7 @@ Agents must use authoritative sources. Never guess or hallucinate.
|
|
|
277
293
|
```
|
|
278
294
|
|
|
279
295
|
### When to invoke research.skill
|
|
296
|
+
|
|
280
297
|
```
|
|
281
298
|
"I'm not sure about X" -> knowledge-gap.skill -> research.skill -> confirm before coding
|
|
282
299
|
If library version not found in official docs -> do NOT assume behavior -> report to human
|
|
@@ -290,6 +307,7 @@ Use Context-7 MCP for library docs (prevents hallucinated deprecated API usage)
|
|
|
290
307
|
Agents may autonomously fix failures up to 5 attempts.
|
|
291
308
|
|
|
292
309
|
### What agents may self-heal (no human approval needed):
|
|
310
|
+
|
|
293
311
|
```
|
|
294
312
|
- Type errors and lint errors
|
|
295
313
|
- Test assertion updates when spec changed
|
|
@@ -300,6 +318,7 @@ Agents may autonomously fix failures up to 5 attempts.
|
|
|
300
318
|
```
|
|
301
319
|
|
|
302
320
|
### What requires human decision:
|
|
321
|
+
|
|
303
322
|
```
|
|
304
323
|
- Architecture or library changes
|
|
305
324
|
- Breaking API changes (any consumer affected)
|
|
@@ -311,7 +330,9 @@ Agents may autonomously fix failures up to 5 attempts.
|
|
|
311
330
|
```
|
|
312
331
|
|
|
313
332
|
### Self-Heal Escalation Protocol
|
|
333
|
+
|
|
314
334
|
After 5 failed attempts, agent MUST:
|
|
335
|
+
|
|
315
336
|
```
|
|
316
337
|
|
|
317
338
|
1. STOP all autonomous action
|
|
@@ -326,8 +347,10 @@ After 5 failed attempts, agent MUST:
|
|
|
326
347
|
```
|
|
327
348
|
|
|
328
349
|
### Self-Evolving Policy (within cost + permission bounds)
|
|
350
|
+
|
|
329
351
|
The system may keep itself current and improve (new/better skills, tools, MCPs, models) via
|
|
330
352
|
`update-scan.skill` — but only inside hard bounds (full detail in that skill):
|
|
353
|
+
|
|
331
354
|
- **Allowed** (gated by `GABBE_AUTONOMY` + budget): adopt a cheaper/better reversible+validated tool/model; import a vetted external skill (validated first); refine prompts/personas from **successful** trajectories only.
|
|
332
355
|
- **Always needs human approval** (even under `auto`): anything expensive/SOTA/irreversible, externally-sourced runnable code, or any change to protected files.
|
|
333
356
|
- **Guardrails:** misaligned-replay guard (never learn from failed runs); protected files (never auto-edit build/IaC/CI/dependency manifests outside the self-heal allowlist); policy-as-code self-enforcement with every adoption/rejection logged to `AUDIT_LOG.md`; prefer canary + rollback, version evolved components.
|
|
@@ -368,6 +391,7 @@ Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed,
|
|
|
368
391
|
## 10. Tool-Specific Overrides
|
|
369
392
|
|
|
370
393
|
### Claude Code (claude.ai/code, Claude Code CLI)
|
|
394
|
+
|
|
371
395
|
```
|
|
372
396
|
- Skills: Use slash commands matching skill names (e.g., /tdd-cycle, /code-review)
|
|
373
397
|
- Memory: Use TodoWrite tool for task tracking
|
|
@@ -376,6 +400,7 @@ Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed,
|
|
|
376
400
|
```
|
|
377
401
|
|
|
378
402
|
### Cursor
|
|
403
|
+
|
|
379
404
|
```
|
|
380
405
|
- Context: This AGENTS.md is symlinked to .cursorrules
|
|
381
406
|
- Skills: Reference skill files directly in conversation
|
|
@@ -383,12 +408,14 @@ Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed,
|
|
|
383
408
|
```
|
|
384
409
|
|
|
385
410
|
### GitHub Copilot
|
|
411
|
+
|
|
386
412
|
```
|
|
387
413
|
- Context: Instructions from .github/copilot-instructions.md (symlinked)
|
|
388
414
|
- Skills: Reference skills/ directory files in comments or conversation
|
|
389
415
|
```
|
|
390
416
|
|
|
391
417
|
### Gemini CLI
|
|
418
|
+
|
|
392
419
|
```
|
|
393
420
|
- Context: This AGENTS.md is symlinked to .gemini/settings.json (instructions field) + GEMINI.md
|
|
394
421
|
- Skills: Symlinked to .agent/skills/ -- invoke by trigger keywords
|
|
@@ -396,6 +423,7 @@ Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed,
|
|
|
396
423
|
```
|
|
397
424
|
|
|
398
425
|
### Google Antigravity
|
|
426
|
+
|
|
399
427
|
```
|
|
400
428
|
- Context: Reads the root AGENTS.md (priority AGENTS.md → GEMINI.md → defaults, v1.20.3+)
|
|
401
429
|
- Skills: Emitted to .agents/skills/<slug>/SKILL.md (agentskills.io standard)
|
|
@@ -403,12 +431,14 @@ Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed,
|
|
|
403
431
|
```
|
|
404
432
|
|
|
405
433
|
### OpenCode (local-first)
|
|
434
|
+
|
|
406
435
|
```
|
|
407
436
|
- Context: Reads the root AGENTS.md + an opencode.json `instructions` array
|
|
408
437
|
- Skills: Emitted to .agents/skills/<slug>/SKILL.md (agentskills.io standard)
|
|
409
438
|
```
|
|
410
439
|
|
|
411
440
|
### Zed / Continue / Roo Code / Kilo Code
|
|
441
|
+
|
|
412
442
|
```
|
|
413
443
|
- Context: Read the root AGENTS.md (agents.md standard); Zed also via .rules,
|
|
414
444
|
Continue via .continue/rules/, Roo via .roo/rules/, Kilo via .kilocode/rules/
|
|
@@ -496,6 +526,7 @@ END of session:
|
|
|
496
526
|
```
|
|
497
527
|
|
|
498
528
|
### Per-project policy: `project/gabbe.config.json` (optional)
|
|
529
|
+
|
|
499
530
|
A runtime-agnostic policy file the agent reads to tune itself to this project —
|
|
500
531
|
autonomy posture, budgets, model tiers, enabled MCPs, skill registries, and
|
|
501
532
|
protected files. Copy `docs/gabbe.config.example.json` to
|
|
@@ -514,6 +545,7 @@ See `docs/SCHEMA.md` → *Project policy config*.
|
|
|
514
545
|
> **This section is optional.** The GABBE CLI provides platform controls (budget, audit, replay, escalation) but is NOT required. Agents can fully operate via markdown inference without it.
|
|
515
546
|
|
|
516
547
|
### Core CLI Integration
|
|
548
|
+
|
|
517
549
|
See `agents/guides/ops/gabbe-cli-workflows.md` for standard CLI workflows: Init, Sync, Verify, Status, Route, Forecast, and Brain execution controls. (Note: The GABBE CLI is an optional experimental tool; agents can fully rely on markdown inference execution otherwise).
|
|
518
550
|
|
|
519
551
|
---
|
|
@@ -536,7 +568,7 @@ the same operating spine in §5/§13 (preflight → clarify → act → state-pr
|
|
|
536
568
|
---
|
|
537
569
|
|
|
538
570
|
*Last updated: [DATE]*
|
|
539
|
-
*GABBE Kit version: 1.0
|
|
571
|
+
*GABBE Kit version: 1.1.0*
|
|
540
572
|
*This file is maintained by the team and updated when project conventions change.*
|
|
541
573
|
|
|
542
574
|
---
|
package/agents/CONSTITUTION.md
CHANGED
|
@@ -8,8 +8,7 @@
|
|
|
8
8
|
```
|
|
9
9
|
┌─────────────────────────────────────────────────────┐
|
|
10
10
|
│ AGENTS.md (Agent Context Layer) │
|
|
11
|
-
│ - Project
|
|
12
|
-
| `architecture-governance`, `error-handling-strategy`, `event-governance` | archunit, error handling, schema registry |identity, commands, architecture rules │
|
|
11
|
+
│ - Project identity, commands, architecture rules │
|
|
13
12
|
│ - Workflow policies, research rules, self-heal limits│
|
|
14
13
|
├─────────────────────────────────────────────────────┤
|
|
15
14
|
│ Skills (Capability Layer) │
|
|
@@ -103,8 +102,7 @@ Process:
|
|
|
103
102
|
1. Identify architecture impact — which layers change?
|
|
104
103
|
2. Create ADR for each significant technology decision
|
|
105
104
|
3. Create C4 Level 1-3 diagrams
|
|
106
|
-
4. Invoke `
|
|
107
|
-
| `access-control`, `data-governance`, `backup-recovery`, `queue-management` | rbac, lineage, backup, dlq |threat-model.skill for security features
|
|
105
|
+
4. Invoke `threat-model.skill` for security features
|
|
108
106
|
5. Write PLAN.md with ordered implementation phases
|
|
109
107
|
Output: PLAN.md + ADRs + threat model — human reviews and approves
|
|
110
108
|
```
|
|
@@ -76,7 +76,7 @@ Standard sequential chains are slow. Loki optimizes S05 via "Task Batching":
|
|
|
76
76
|
|
|
77
77
|
### C. Hybrid Swarms (A2A)
|
|
78
78
|
Loki allows delegation to external specialized swarms:
|
|
79
|
-
- **Internal**: "Build the API" (Loki Persona `backend
|
|
79
|
+
- **Internal**: "Build the API" (Loki Persona `eng-backend`)
|
|
80
80
|
- **External**: "Audit for vulnerabilities" -> Delegates to `Sec-Swarm-1` via `agent-interop.skill`.
|
|
81
81
|
|
|
82
82
|
### D. Cognitive Architectures (Global Workspace)
|
|
@@ -8,7 +8,7 @@ This guide explores advanced "in the wild" use cases where GABBE 2.0 excels, lev
|
|
|
8
8
|
|
|
9
9
|
### Workflow:
|
|
10
10
|
1. **Prompt:**
|
|
11
|
-
> "Use the vibe-coding skill to analyze my existing prototype in `src/vibe`. Now, use the clean-coder and
|
|
11
|
+
> "Use the vibe-coding skill to analyze my existing prototype in `src/vibe`. Now, use the clean-coder and arch-design skills to refactor it into a Clean Architecture (Domain, Application, Adapters) with 100% test coverage using Vitest."
|
|
12
12
|
2. **Key Steps:**
|
|
13
13
|
- **Extract Logic:** The agent separates UI-only "vibe" code from business logic.
|
|
14
14
|
- **Apply Types:** Moving from `any` or loose JS to strict TypeScript.
|
|
@@ -50,7 +50,7 @@ This guide explores advanced "in the wild" use cases where GABBE 2.0 excels, lev
|
|
|
50
50
|
|
|
51
51
|
### Workflow:
|
|
52
52
|
1. **Prompt:**
|
|
53
|
-
> "Activate Brain Mode. Goal: Decide between GraphQL and REST for our mobile backend. Run a competitive simulation between `
|
|
53
|
+
> "Activate Brain Mode. Goal: Decide between GraphQL and REST for our mobile backend. Run a competitive simulation between `prod-architect` (GraphQL proponent) and `ops-sre` (REST proponent). Present a weighted decision matrix in `ARCHITECTURE_DECISION_MATRIX.md`."
|
|
54
54
|
2. **Key Steps:**
|
|
55
55
|
- **Debate:** The orchestrator runs 2-3 passes of debate, synthesizing the pros/cons.
|
|
56
56
|
- **Simulation:** Agent creates minimal benchmarks for both approaches.
|
|
@@ -18,7 +18,7 @@ This skill guides the implementation of security controls *during* development (
|
|
|
18
18
|
|
|
19
19
|
- **Syntactic Validation**: Is it an email? Is it a number? (Use Zod/Pydantic).
|
|
20
20
|
- **Semantic Validation**: Is `start_date` before `end_date`? Is `transfer_amount` > 0?
|
|
21
|
-
- **Allow-list**: Only accept known
|
|
21
|
+
- **Allow-list**: Only accept known good characters (e.g., `[a-zA-Z0-9]`). Block everything else.
|
|
22
22
|
|
|
23
23
|
## 2. Output Encoding (Defense)
|
|
24
24
|
> "Context matters."
|
|
@@ -69,7 +69,7 @@ HUMAN_APPROVED - Human provided approval for a phase or decision
|
|
|
69
69
|
| 2025-03-15T16:45:00Z | S05-001 | eng-backend | SELF_HEAL_ATTEMPT | Type error on UserDto.email field — attempt 1/5 | FAIL | src/application/create-user.use-case.ts:42 |
|
|
70
70
|
| 2025-03-15T16:50:00Z | S05-001 | eng-backend | TASK_DONE | Fixed type error via research (strict null check) | SUCCESS | src/application/create-user.use-case.ts |
|
|
71
71
|
| 2025-03-15T17:00:00Z | S05-001 | ops-security | SECURITY_FINDING | HIGH: Missing rate limit on /auth/login | OPEN | src/adapters/http/auth.controller.ts:23 |
|
|
72
|
-
| 2025-03-15T17:30:00Z | S06-001 | orch-judge | QUALITY_GATE | Gate 3 Tests: 247 pass, 0 fail,
|
|
72
|
+
| 2025-03-15T17:30:00Z | S06-001 | orch-judge | QUALITY_GATE | Gate 3 Tests: 247 pass, 0 fail, 99% coverage | PASS | — |
|
|
73
73
|
```
|
|
74
74
|
|
|
75
75
|
3. **APPEND ONLY — never modify existing entries**
|
|
@@ -27,7 +27,7 @@ This skill protects the system from its own AI.
|
|
|
27
27
|
## 3. Libraries & Tools
|
|
28
28
|
- **NeMo Guardrails (NVIDIA)**
|
|
29
29
|
- **Guardrails AI (Python)**
|
|
30
|
-
- **
|
|
30
|
+
- **Presidio (PII)**
|
|
31
31
|
|
|
32
32
|
## 4. System Design
|
|
33
33
|
- **Human in the Loop (HITL)**: For high-stakes actions (Transfer Money), AI *proposes*, Human *approves*.
|
|
@@ -48,12 +48,12 @@ For how these controls map onto named AI-risk standards (OWASP LLM Top 10, NIST
|
|
|
48
48
|
## Security & Guardrails
|
|
49
49
|
|
|
50
50
|
### 1. Skill Security (AI Safety Guardrails)
|
|
51
|
-
- **Guardrail Circumvention Prevention**: The infrastructure running the `NeMo Guardrails` or `
|
|
51
|
+
- **Guardrail Circumvention Prevention**: The infrastructure running the `NeMo Guardrails` or `Presidio` PII scrubbing must be physically and logically separated from the primary LLM execution environment. If the primary LLM is successfully jailbroken, it must not possess the system-level permissions required to disable its own outgoing telemetry or content filters.
|
|
52
52
|
- **Filter Evasion Monitoring**: The agent must continuously audit the logs of the Input Guardrails. A sudden spike in rejected prompts or specific keywords (e.g., "DAN", "Ignore previous") must trigger an automated escalation to the Security Operations Center (SOC), indicating an active, coordinated prompt injection attack.
|
|
53
53
|
|
|
54
54
|
### 2. System Integration Security
|
|
55
55
|
- **Fail-Closed Architecture**: If the Output Guardrail service (e.g., the JSON format validator or sentiment analyzer) crashes or times out, the primary application must default to a "Fail-Closed" state. The system is strictly prohibited from bypassing the offline guardrail to deliver unchecked LLM output directly to the end-user.
|
|
56
|
-
- **PII Scrubbing Reversibility**: When `
|
|
56
|
+
- **PII Scrubbing Reversibility**: When `Presidio` or similar tools redact PII from a user prompt before sending it to an external LLM, the mapping mechanism (e.g., swapping `John Doe` for `[USER_1]`) must utilize cryptographically secure, high-entropy tokens. Attackers must not be able to infer the original PII by reverse-engineering the redaction dictionary.
|
|
57
57
|
|
|
58
58
|
### 3. LLM & Agent Guardrails
|
|
59
59
|
- **Meta-Jailbreak Detection**: Aggressive attackers may attempt to jailbreak the primary LLM by using the guardrail system itself as an attack vector (e.g., embedding a prompt injection payload inside a legitimate string of PII to bypass the initial filter). The agent must apply recursive, multi-layered inspection to all structured inputs.
|
|
@@ -163,6 +163,7 @@ Import style:
|
|
|
163
163
|
Agents MUST follow this order. Skipping steps is forbidden.
|
|
164
164
|
|
|
165
165
|
### Step 1 — Load Context (every session start)
|
|
166
|
+
|
|
166
167
|
```
|
|
167
168
|
1. Read this AGENTS.md completely
|
|
168
169
|
2. Read CONSTITUTION.md if it exists
|
|
@@ -172,6 +173,7 @@ Agents MUST follow this order. Skipping steps is forbidden.
|
|
|
172
173
|
```
|
|
173
174
|
|
|
174
175
|
### Step 2 — Plan Before Coding
|
|
176
|
+
|
|
175
177
|
```
|
|
176
178
|
Before touching any file, write a brief implementation plan:
|
|
177
179
|
- What files will you create or modify?
|
|
@@ -184,6 +186,7 @@ For complex tasks: write plan.md or use PLAN_TEMPLATE.md
|
|
|
184
186
|
```
|
|
185
187
|
|
|
186
188
|
### Step 3 — Test First (TDD Red Phase)
|
|
189
|
+
|
|
187
190
|
```
|
|
188
191
|
Write the failing test BEFORE writing implementation code.
|
|
189
192
|
Run the test -- it MUST fail (Red).
|
|
@@ -191,12 +194,14 @@ If the test passes immediately with no implementation: the test is WRONG. Fix it
|
|
|
191
194
|
```
|
|
192
195
|
|
|
193
196
|
### Step 4 — Implement (TDD Green Phase)
|
|
197
|
+
|
|
194
198
|
```
|
|
195
199
|
Write the minimal code to make the failing test pass.
|
|
196
200
|
Do not add features not covered by a failing test.
|
|
197
201
|
```
|
|
198
202
|
|
|
199
203
|
### Step 5 — Verify (must all pass before marking done)
|
|
204
|
+
|
|
200
205
|
```
|
|
201
206
|
Run: [test command] -> must pass
|
|
202
207
|
Run: [typecheck command] -> must pass
|
|
@@ -205,12 +210,14 @@ Run: agentic-linter check -> no boundary violations
|
|
|
205
210
|
```
|
|
206
211
|
|
|
207
212
|
### Step 6 — Refactor
|
|
213
|
+
|
|
208
214
|
```
|
|
209
215
|
Improve code quality while keeping all tests green.
|
|
210
216
|
Check: Cyclomatic complexity < 10, no code duplication > 3 occurrences, no dead code.
|
|
211
217
|
```
|
|
212
218
|
|
|
213
219
|
### Step 7 — Log & Complete
|
|
220
|
+
|
|
214
221
|
```
|
|
215
222
|
Write entry to agents/memory/AUDIT_LOG.md
|
|
216
223
|
Update task status in project/TASKS.md to DONE
|
|
@@ -222,6 +229,7 @@ If this completes a SDLC phase: invoke sdlc-checkpoint.skill
|
|
|
222
229
|
## 6. Governance & Security
|
|
223
230
|
|
|
224
231
|
### Forbidden Actions (agents must never do these without explicit human approval)
|
|
232
|
+
|
|
225
233
|
```
|
|
226
234
|
- Commit .env files or any file containing secrets
|
|
227
235
|
- Push directly to main/master branch
|
|
@@ -236,6 +244,7 @@ If this completes a SDLC phase: invoke sdlc-checkpoint.skill
|
|
|
236
244
|
```
|
|
237
245
|
|
|
238
246
|
### Secrets Policy
|
|
247
|
+
|
|
239
248
|
```
|
|
240
249
|
All secrets MUST be in environment variables.
|
|
241
250
|
Local dev: .env file (always in .gitignore)
|
|
@@ -245,6 +254,7 @@ Use: [PLACEHOLDER: dotenv | .env.vault | AWS Secrets Manager | HashiCorp Vault]
|
|
|
245
254
|
```
|
|
246
255
|
|
|
247
256
|
### PR Format (Conventional Commits)
|
|
257
|
+
|
|
248
258
|
```
|
|
249
259
|
Format: <type>(<scope>): <subject>
|
|
250
260
|
|
|
@@ -266,6 +276,7 @@ PR body must include:
|
|
|
266
276
|
```
|
|
267
277
|
|
|
268
278
|
### Quality Gates (all must pass before PR merges)
|
|
279
|
+
|
|
269
280
|
```
|
|
270
281
|
Gate 1 -- Syntax/Linting: ESLint / PHP-CS-Fixer / Prettier / Ruff -- zero errors
|
|
271
282
|
Gate 2 -- Type Safety: tsc --noEmit / PHPStan L9 / mypy -- zero errors
|
|
@@ -283,6 +294,7 @@ Gate 7 -- EARS Compliance: (for new features) All requirements have tests
|
|
|
283
294
|
Agents must use authoritative sources. Never guess or hallucinate.
|
|
284
295
|
|
|
285
296
|
### Source Tiers (in order of trust)
|
|
297
|
+
|
|
286
298
|
```
|
|
287
299
|
Tier 1 (Primary -- always prefer):
|
|
288
300
|
- Official language/framework docs (MDN, nodejs.org, laravel.com, docs.python.org)
|
|
@@ -303,6 +315,7 @@ NOT acceptable (never cite as authoritative):
|
|
|
303
315
|
```
|
|
304
316
|
|
|
305
317
|
### Research Gate -- mandatory before:
|
|
318
|
+
|
|
306
319
|
```
|
|
307
320
|
- Using any library not in existing package.json / composer.json
|
|
308
321
|
- Calling any API method not confirmed in official docs
|
|
@@ -311,6 +324,7 @@ NOT acceptable (never cite as authoritative):
|
|
|
311
324
|
```
|
|
312
325
|
|
|
313
326
|
### When to invoke research.skill
|
|
327
|
+
|
|
314
328
|
```
|
|
315
329
|
"I'm not sure about X" -> knowledge-gap.skill -> research.skill -> confirm before coding
|
|
316
330
|
If library version not found in official docs -> do NOT assume behavior -> report to human
|
|
@@ -324,6 +338,7 @@ Use Context-7 MCP for library docs (prevents hallucinated deprecated API usage)
|
|
|
324
338
|
Agents may autonomously fix failures up to 5 attempts.
|
|
325
339
|
|
|
326
340
|
### What agents may self-heal (no human approval needed):
|
|
341
|
+
|
|
327
342
|
```
|
|
328
343
|
- Type errors and lint errors
|
|
329
344
|
- Test assertion updates when spec changed
|
|
@@ -334,6 +349,7 @@ Agents may autonomously fix failures up to 5 attempts.
|
|
|
334
349
|
```
|
|
335
350
|
|
|
336
351
|
### What requires human decision:
|
|
352
|
+
|
|
337
353
|
```
|
|
338
354
|
- Architecture or library changes
|
|
339
355
|
- Breaking API changes (any consumer affected)
|
|
@@ -345,7 +361,9 @@ Agents may autonomously fix failures up to 5 attempts.
|
|
|
345
361
|
```
|
|
346
362
|
|
|
347
363
|
### Self-Heal Escalation Protocol
|
|
364
|
+
|
|
348
365
|
After 5 failed attempts, agent MUST:
|
|
366
|
+
|
|
349
367
|
```
|
|
350
368
|
1. STOP all autonomous action
|
|
351
369
|
2. Create structured escalation report:
|
|
@@ -390,6 +408,7 @@ Format for human escalation:
|
|
|
390
408
|
## 10. Tool-Specific Overrides
|
|
391
409
|
|
|
392
410
|
### Claude Code (claude.ai/code, Claude Code CLI)
|
|
411
|
+
|
|
393
412
|
```
|
|
394
413
|
- Skills: Use slash commands matching skill names (e.g., /tdd-cycle, /code-review)
|
|
395
414
|
- Memory: Use TodoWrite tool for task tracking
|
|
@@ -398,6 +417,7 @@ Format for human escalation:
|
|
|
398
417
|
```
|
|
399
418
|
|
|
400
419
|
### Cursor
|
|
420
|
+
|
|
401
421
|
```
|
|
402
422
|
- Context: This AGENTS.md is symlinked to .cursorrules
|
|
403
423
|
- Skills: Reference skill files directly in conversation
|
|
@@ -405,12 +425,14 @@ Format for human escalation:
|
|
|
405
425
|
```
|
|
406
426
|
|
|
407
427
|
### GitHub Copilot
|
|
428
|
+
|
|
408
429
|
```
|
|
409
430
|
- Context: Instructions from .github/copilot-instructions.md (symlinked)
|
|
410
431
|
- Skills: Reference skills/ directory files in comments or conversation
|
|
411
432
|
```
|
|
412
433
|
|
|
413
434
|
### Antigravity / Gemini CLI
|
|
435
|
+
|
|
414
436
|
```
|
|
415
437
|
- Context: This AGENTS.md is symlinked to .gemini/settings.json (instructions field)
|
|
416
438
|
- Skills: Symlinked to .agent/skills/ -- invoke by trigger keywords
|
|
@@ -443,6 +465,7 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
|
|
|
443
465
|
## 12. References
|
|
444
466
|
|
|
445
467
|
### 3. Skill Access
|
|
468
|
+
|
|
446
469
|
- **Search First**: Before coding, search for relevant skills:
|
|
447
470
|
- **Cursor**: Check `.cursor/rules/` for `.mdc` files.
|
|
448
471
|
- **VS Code / Copilot**: Check `.github/skills/` or invoke via slash command.
|
|
@@ -462,6 +485,7 @@ Project memory: agents/memory/PROJECT_STATE.md
|
|
|
462
485
|
Past failures: agents/memory/CONTINUITY.md
|
|
463
486
|
Decision log: agents/memory/AUDIT_LOG.md
|
|
464
487
|
```
|
|
488
|
+
|
|
465
489
|
- **Skills**: `agents/skills/` (Master) → `.cursor/rules/` (*.mdc) | `.github/skills/` | `.claude/skills/`
|
|
466
490
|
- **Memory**: `agents/memory/`
|
|
467
491
|
|
|
@@ -536,5 +560,5 @@ Examples:
|
|
|
536
560
|
---
|
|
537
561
|
|
|
538
562
|
*Last updated: [DATE]*
|
|
539
|
-
*GABBE Kit version: 1.0
|
|
563
|
+
*GABBE Kit version: 1.1.0*
|
|
540
564
|
*This file is maintained by the team and updated when project conventions change.*
|
|
@@ -65,7 +65,7 @@ EXAMPLE ENTRIES (remove this comment block when using):
|
|
|
65
65
|
| 2025-03-15T16:00:00Z | S05-001 | eng-backend | TASK_BLOCKED | T-020: Cannot implement payment integration — unclear if Stripe or Paddle | OPEN | project/TASKS.md |
|
|
66
66
|
| 2025-03-15T16:01:00Z | S05-001 | eng-backend | HUMAN_ESCALATION | T-020 blocked: Payment provider not decided. Options: Stripe (fees: 2.9%) vs Paddle (fees: 5%). Recommend Stripe (direct settlement). | ESCALATED | project/TASKS.md |
|
|
67
67
|
| 2025-03-15T16:45:00Z | S05-001 | human:bob | DECISION | Use Stripe for payment processing — direct settlement preferred | APPROVED | — |
|
|
68
|
-
| 2025-03-15T17:00:00Z | S06-001 | orch-judge | QUALITY_GATE | Gate 3 Tests: 247 pass, 0 fail, 0 skip,
|
|
68
|
+
| 2025-03-15T17:00:00Z | S06-001 | orch-judge | QUALITY_GATE | Gate 3 Tests: 247 pass, 0 fail, 0 skip, 99% coverage | PASS | — |
|
|
69
69
|
| 2025-03-15T17:05:00Z | S07-001 | ops-security | SECURITY_FINDING | HIGH: No rate limit on /auth/login endpoint — brute force possible | OPEN | src/adapters/http/auth.controller.ts:23 |
|
|
70
70
|
| 2025-03-15T17:30:00Z | S07-001 | eng-backend | TASK_DONE | Added rate limiting to /auth/login: 5 req/min per IP | SUCCESS | src/adapters/http/auth.controller.ts |
|
|
71
71
|
| 2025-03-15T17:31:00Z | S07-001 | ops-security | SECURITY_FINDING | HIGH: No rate limit on /auth/login — RESOLVED | RESOLVED | src/adapters/http/auth.controller.ts |
|
package/bin/install.js
CHANGED
|
@@ -172,17 +172,45 @@ function shouldPreserve(relPath, fileName) {
|
|
|
172
172
|
return false;
|
|
173
173
|
}
|
|
174
174
|
|
|
175
|
-
//
|
|
176
|
-
|
|
175
|
+
// Back up an existing target file to <name>.gabbe-bak before it is overwritten.
|
|
176
|
+
// The first backup wins (never overwrite an existing .gabbe-bak), so re-running
|
|
177
|
+
// install preserves the user's ORIGINAL, not a kit copy from a prior run.
|
|
178
|
+
function backupBeforeOverwrite(dst) {
|
|
179
|
+
const backup = dst + '.gabbe-bak';
|
|
180
|
+
if (!fs.existsSync(backup)) {
|
|
181
|
+
try {
|
|
182
|
+
fs.copyFileSync(dst, backup);
|
|
183
|
+
log(` ${yellow('!')} Backed up existing ${path.basename(dst)} -> ${path.basename(backup)}`);
|
|
184
|
+
} catch (e) {
|
|
185
|
+
/* best-effort backup */
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// Copy a directory tree without ever losing user data. Preserved files are left
|
|
191
|
+
// untouched; any other differing pre-existing file is backed up to .gabbe-bak
|
|
192
|
+
// before being refreshed. With force=true, even preserved files are re-templated
|
|
193
|
+
// (still backed up first). Mirrors init.py safe_merge_directory.
|
|
194
|
+
function safeCopyTree(srcRoot, dstRoot, force) {
|
|
177
195
|
if (!fs.existsSync(srcRoot)) return 0;
|
|
178
196
|
let copied = 0;
|
|
179
197
|
for (const src of walk(srcRoot)) {
|
|
180
198
|
const rel = path.relative(srcRoot, src);
|
|
181
199
|
const dst = path.join(dstRoot, rel);
|
|
182
200
|
const fileName = path.basename(src);
|
|
183
|
-
|
|
201
|
+
const exists = fs.existsSync(dst);
|
|
202
|
+
if (exists && !force && shouldPreserve(rel, fileName)) {
|
|
184
203
|
continue;
|
|
185
204
|
}
|
|
205
|
+
if (exists) {
|
|
206
|
+
let differs = true;
|
|
207
|
+
try {
|
|
208
|
+
differs = !fs.readFileSync(src).equals(fs.readFileSync(dst));
|
|
209
|
+
} catch (e) {
|
|
210
|
+
differs = true;
|
|
211
|
+
}
|
|
212
|
+
if (differs) backupBeforeOverwrite(dst);
|
|
213
|
+
}
|
|
186
214
|
fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
187
215
|
fs.copyFileSync(src, dst);
|
|
188
216
|
copied += 1;
|
|
@@ -411,7 +439,7 @@ Examples:
|
|
|
411
439
|
`;
|
|
412
440
|
|
|
413
441
|
function parseArgs(argv) {
|
|
414
|
-
const opts = { command: null, agents: [], yes: false, wizard: false, help: false };
|
|
442
|
+
const opts = { command: null, agents: [], yes: false, wizard: false, help: false, force: false };
|
|
415
443
|
for (let i = 0; i < argv.length; i++) {
|
|
416
444
|
const a = argv[i];
|
|
417
445
|
if (a === 'init') {
|
|
@@ -420,6 +448,8 @@ function parseArgs(argv) {
|
|
|
420
448
|
opts.help = true;
|
|
421
449
|
} else if (a === '--yes' || a === '-y') {
|
|
422
450
|
opts.yes = true;
|
|
451
|
+
} else if (a === '--force') {
|
|
452
|
+
opts.force = true;
|
|
423
453
|
} else if (a === '--wizard') {
|
|
424
454
|
opts.wizard = true;
|
|
425
455
|
} else if (a === '--agents') {
|
|
@@ -496,13 +526,13 @@ function runInit(opts) {
|
|
|
496
526
|
if (path.resolve(targetAgents) === path.resolve(SOURCE_AGENTS_DIR)) {
|
|
497
527
|
log(` ${blue('→')} Target agents/ is the source; skipping copy.`);
|
|
498
528
|
} else {
|
|
499
|
-
const n = safeCopyTree(SOURCE_AGENTS_DIR, targetAgents);
|
|
529
|
+
const n = safeCopyTree(SOURCE_AGENTS_DIR, targetAgents, opts.force);
|
|
500
530
|
log(` ${green('✓')} Copied agents/ (${n} files, user content preserved)`);
|
|
501
531
|
}
|
|
502
532
|
if (fs.existsSync(SOURCE_DOCS_DIR)) {
|
|
503
533
|
const targetDocs = path.join(PROJECT_ROOT, 'docs');
|
|
504
534
|
if (path.resolve(targetDocs) !== path.resolve(SOURCE_DOCS_DIR)) {
|
|
505
|
-
const n = safeCopyTree(SOURCE_DOCS_DIR, targetDocs);
|
|
535
|
+
const n = safeCopyTree(SOURCE_DOCS_DIR, targetDocs, opts.force);
|
|
506
536
|
log(` ${green('✓')} Copied docs/ (${n} files)`);
|
|
507
537
|
}
|
|
508
538
|
}
|