gabbe-kit 1.0.3 → 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 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.3*
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
  ---
@@ -184,5 +184,5 @@
184
184
  *Amended by: [team member name]*
185
185
  *Reason for amendment: [brief explanation]*
186
186
 
187
- *GABBE Kit version: 1.0.3*
187
+ *GABBE Kit version: 1.1.0*
188
188
  *This file is maintained by the team and updated when project conventions change.*
@@ -8,8 +8,7 @@
8
8
  ```
9
9
  ┌─────────────────────────────────────────────────────┐
10
10
  │ AGENTS.md (Agent Context Layer) │
11
- │ - Project `diagramming`, `domain-model`, `adaptive-architecture`, `compatibility-design` | diagram, domain, local-first, compatibility |
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 `security-audit`, `threat-model`, `privacy-audit`, `compliance-review`, `legal-review` | security, threat, privacy, SOC2, legal |
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-coder`)
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 architecture-design skills to refactor it into a Clean Architecture (Domain, Application, Adapters) with 100% test coverage using Vitest."
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 `arch-architect` (GraphQL proponent) and `ops-sre` (REST proponent). Present a weighted decision matrix in `ARCHITECTURE_DECISION_MATRIX.md`."
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 bad characters (e.g., `[a-zA-Z0-9]`). Block everything else.
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, 84% coverage | PASS | — |
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
- - **Rebertha (PII)**
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 `Rebertha` 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.
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 `Rebertha` 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.
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.3*
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, 84% coverage | PASS | — |
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
- // Copy a directory tree without overwriting preserved user files.
176
- function safeCopyTree(srcRoot, dstRoot) {
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
- if (fs.existsSync(dst) && shouldPreserve(rel, fileName)) {
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
  }