gabbe-kit 1.0.3 → 1.1.1

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.
Files changed (82) hide show
  1. package/README.md +21 -0
  2. package/agents/AGENTS.md +36 -3
  3. package/agents/CONSTITUTION.md +1 -1
  4. package/agents/guides/00-index.md +4 -4
  5. package/agents/guides/ai/agent-only-cognition.md +10 -2
  6. package/agents/guides/ai/agent-only-swarms.md +4 -4
  7. package/agents/guides/ai/agent-operating-ergonomics.md +1 -1
  8. package/agents/guides/ai/ai-agentic.md +2 -4
  9. package/agents/guides/ai/beyond-llms.md +12 -2
  10. package/agents/guides/ai/multi-agent-systems.md +1 -1
  11. package/agents/guides/architecture/api-standards.md +9 -7
  12. package/agents/guides/architecture/critical-systems-arch.md +10 -4
  13. package/agents/guides/architecture/microservices.md +2 -2
  14. package/agents/guides/architecture/orchestration.md +3 -3
  15. package/agents/guides/architecture/systems-architecture.md +6 -0
  16. package/agents/guides/ops/cost-optimization.md +1 -1
  17. package/agents/guides/patterns/agentic-patterns.md +12 -40
  18. package/agents/guides/patterns/ai-native-scenarios.md +4 -4
  19. package/agents/guides/patterns/design-patterns.md +11 -65
  20. package/agents/guides/patterns/software-design-patterns.md +4 -2
  21. package/agents/guides/principles/clean-code-standards.md +1 -1
  22. package/agents/guides/principles/evaluation-strategy.md +18 -13
  23. package/agents/guides/principles/future-tech.md +1 -1
  24. package/agents/guides/principles/human-agent-collaboration.md +4 -3
  25. package/agents/guides/principles/legacy-tech.md +7 -3
  26. package/agents/guides/principles/testing-strategy.md +5 -3
  27. package/agents/guides/processes/loki-sdlc-phases.md +1 -1
  28. package/agents/guides/security/api-security.md +1 -1
  29. package/agents/guides/security/cryptography-standards.md +8 -2
  30. package/agents/guides/security/privacy-data-protection.md +2 -2
  31. package/agents/guides/security/secure-architecture.md +1 -1
  32. package/agents/skills/00-index.md +16 -16
  33. package/agents/skills/brain/active-inference.skill.md +1 -1
  34. package/agents/skills/brain/brain-mode.skill.md +9 -2
  35. package/agents/skills/brain/cost-benefit-router.skill.md +20 -8
  36. package/agents/skills/brain/loki-mode.skill.md +13 -10
  37. package/agents/skills/brain/sequential-thinking.skill.md +1 -1
  38. package/agents/skills/coding/mobile-dev.skill.md +1 -0
  39. package/agents/skills/coding/secure-coding.skill.md +1 -1
  40. package/agents/skills/coding/tdd-cycle.skill.md +1 -1
  41. package/agents/skills/coding/testing-strategy.skill.md +1 -1
  42. package/agents/skills/coding/visual-design.skill.md +1 -0
  43. package/agents/skills/coordination/agent-interop.skill.md +5 -4
  44. package/agents/skills/coordination/meta-optimize.skill.md +2 -2
  45. package/agents/skills/coordination/multi-agent-orch.skill.md +1 -1
  46. package/agents/skills/coordination/persona-selector.skill.md +1 -1
  47. package/agents/skills/coordination/self-optimize.skill.md +1 -1
  48. package/agents/skills/coordination/swarm-consensus.skill.md +10 -0
  49. package/agents/skills/core/audit-trail.skill.md +1 -1
  50. package/agents/skills/core/emerging-tech.skill.md +1 -1
  51. package/agents/skills/core/integrity-check.skill.md +1 -1
  52. package/agents/skills/core/knowledge-connect.skill.md +1 -0
  53. package/agents/skills/core/preflight.skill.md +8 -0
  54. package/agents/skills/core/sdlc-checkpoint.skill.md +7 -2
  55. package/agents/skills/core/self-heal.skill.md +17 -4
  56. package/agents/skills/core/session-resume.skill.md +8 -3
  57. package/agents/skills/core/state-portability.skill.md +3 -2
  58. package/agents/skills/ops/incident-response.skill.md +1 -0
  59. package/agents/skills/ops/production-health.skill.md +1 -0
  60. package/agents/skills/ops/release-management.skill.md +1 -0
  61. package/agents/skills/ops/system-benchmark.skill.md +1 -0
  62. package/agents/skills/product/spec-writer.skill.md +6 -3
  63. package/agents/skills/security/ai-safety-guardrails.skill.md +15 -6
  64. package/agents/skills/security/legal-review.skill.md +1 -0
  65. package/agents/skills/security/reliability-engineering.skill.md +4 -3
  66. package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +1 -1
  67. package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +7 -0
  68. package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +1 -1
  69. package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +2 -2
  70. package/agents/templates/coordination/AGENTS_TEMPLATE.md +133 -16
  71. package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +1 -1
  72. package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +3 -3
  73. package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +1 -1
  74. package/agents/templates/product/PRD_TEMPLATE.md +8 -2
  75. package/agents/templates/product/SPEC_TEMPLATE.md +9 -3
  76. package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +1 -1
  77. package/bin/install.js +36 -6
  78. package/docs/CLI_REFERENCE.md +43 -5
  79. package/docs/INSTALL.md +23 -10
  80. package/docs/adr/0002-brain-active-inference-runtime.md +29 -8
  81. package/package.json +2 -2
  82. 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
@@ -123,12 +124,13 @@ every task (episodic, semantic, AUDIT_LOG, CONTINUITY, PROJECT_STATE, RESUME_POI
123
124
  **CRITICAL MANDATES (always apply):**
124
125
 
125
126
  - **Optimal skill/guide/MCP selection** — analyze the task and select (or ask the user to confirm) the best skills/guides/templates; never default to generic execution when a specialized one exists. Recommend enabling any MCP server that would materially help.
126
- - **Cost & budget by default** — minimize tokens/context/API cost; never use swarms or SOTA models for simple work, and **ask the human before any expensive/SOTA/high-cost approach** (with a one-line cost-benefit). Four levers (`guides/ops/cost-optimization.md`): prompt caching (stable context first), context budgeting (load minimum, prefer `context_cost: low`), model tiering (`gabbe route`), batching. Never weaken the gates, the 10-phase SDLC, or HITL to save cost.
127
+ - **Cost & budget by default** — minimize tokens/context/API cost; never use swarms or SOTA models for simple work, and **ask the human before any expensive/SOTA/high-cost approach** (with a one-line cost-benefit). Four levers (`guides/ops/cost-optimization.md`): prompt caching (stable context first), context budgeting (load minimum, prefer `context_cost: low`), model tiering (`gabbe route`), batching. Never weaken the gates, the SDLC lifecycle, or HITL to save cost.
127
128
  - **Spec-driven (first-class)** — `spec → evals → test → code`, never code-first. Non-trivial features start from an **EARS** spec (`product/spec-writer.skill`, `templates/product/SPEC_TEMPLATE.md`, `guides/planning/product-requirements.md`); keep a **golden thread** (requirement → spec → test → code → audit). No requirement without a test (Article I); resolve ambiguity in the spec via `clarify.skill`.
128
129
  - **Observability (first-class)** — every run/decision/model+tool call is traced with token usage + **per-step cost attribution** (`core/audit-trail.skill`, `core/agent-analytics.skill`; OTel GenAI conventions `gen_ai.usage.*`; span tree root→plan→discover→execute→retrieve). Redact content by default (Article IV); `AUDIT_LOG.md` is authoritative without the CLI.
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
  ---
@@ -527,7 +559,8 @@ restating them here, to prevent drift):
527
559
  - **🧠 Brain Mode** (`brain/brain-mode.skill.md`) — the Strategist (System 2): meta-cognitive
528
560
  planner/router/optimizer (Active Inference + dynamic cost routing). Trigger: `gabbe brain activate`, `supermode`.
529
561
  - **⚡ Loki Mode** (`brain/loki-mode.skill.md`) — the Executor (System 1): the deterministic
530
- 10-phase SDLC (S01→S10) with human-in-the-loop gates. Trigger: `loki`, `orchestrate`.
562
+ SDLC state machine — a 14-phase lifecycle (10-phase core build loop S01–S10, plus
563
+ Day-0 S00 and Day-2 S11–S13) with human-in-the-loop gates (S00/S01/S02/S07/S08). Trigger: `loki`, `orchestrate`.
531
564
 
532
565
  Brain Mode **wraps** Loki: it receives the request, routes by complexity/budget, runs Loki for
533
566
  the SDLC, and monitors — intervening if cost spikes, errors loop, or requirements drift. Both use
@@ -536,7 +569,7 @@ the same operating spine in §5/§13 (preflight → clarify → act → state-pr
536
569
  ---
537
570
 
538
571
  *Last updated: [DATE]*
539
- *GABBE Kit version: 1.0.3*
572
+ *GABBE Kit version: 1.1.0*
540
573
  *This file is maintained by the team and updated when project conventions change.*
541
574
 
542
575
  ---
@@ -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.*
@@ -87,12 +87,12 @@
87
87
  ### 6. Implementation Patterns (`patterns/`)
88
88
  | Guide | File | Purpose |
89
89
  |---|---|---|
90
- | Agentic Patterns| `patterns/agentic-patterns.md` | Implementation paths for swarms |
91
- | Agentic Design Patterns | `patterns/agentic-design-patterns.md` | Full pattern catalog: reasoning/planning/workflow/multi-agent/memory/safety |
92
- | Software Design Patterns | `patterns/software-design-patterns.md` | Classical catalog: GoF + architectural + DDD + enterprise/distributed |
90
+ | Agentic Design Patterns | `patterns/agentic-design-patterns.md` | **Canonical** agentic catalog: reasoning/planning/workflow/multi-agent/memory/safety |
91
+ | Agentic Patterns| `patterns/agentic-patterns.md` | Pointer → `agentic-design-patterns.md` |
92
+ | Software Design Patterns | `patterns/software-design-patterns.md` | **Canonical** classical catalog: GoF + architectural + DDD + enterprise/distributed |
93
+ | Design Patterns | `patterns/design-patterns.md` | Pointer → `software-design-patterns.md` |
93
94
  | AI Scenarios | `patterns/ai-native-scenarios.md` | Real-world AI integrations |
94
95
  | Autonomous Swarm| `patterns/autonomous-swarm-patterns.md` | Inter-agent negotiation |
95
- | Design Patterns | `patterns/design-patterns.md` | GoF and modern code patterns |
96
96
  | Ent. Migration | `patterns/enterprise-migration-scenario.md` | Legacy to modern code paths |
97
97
  | Ent. Patterns | `patterns/enterprise-patterns.md` | CQRS, Saga, and bounded contexts |
98
98
  | Time Complexity | `patterns/time-complexity-analysis.md` | Big-O detection and remediation |
@@ -17,7 +17,11 @@ This guide explains how to manually trigger:
17
17
 
18
18
  ## 1. Manual Brain Mode (Active Inference)
19
19
 
20
- If you have a massive feature to build and want the agent to use "System 2" Free Energy logic (thinking before typing), you can explicitly ask it to load the `brain-mode` skill.
20
+ If you have a massive feature to build and want the agent to use "System 2" deliberation (thinking before typing), you can explicitly ask it to load the `brain-mode` skill.
21
+
22
+ > **Framing vs. implementation.** "Active Inference" and "Free Energy" are *framing words* for
23
+ > the observe → decide → act loop in the brain prompt — no variational free-energy math is
24
+ > computed. See `ai/self-evolving-skills.md` for the honest accounting.
21
25
 
22
26
  ### The Agent Prompt
23
27
  > "Activate Brain Mode for this session by reading `agents/skills/brain/brain-mode.skill.md`. Your goal is to [build X feature]. Follow the Observe -> Orient -> Decide -> Act loop in that document before you write any code."
@@ -34,6 +38,10 @@ Because `brain-mode.skill.md` contains strict procedural logic, the LLM will:
34
38
 
35
39
  If your agent is consistently failing at a specific task (e.g., repeatedly generating outdated React components), you don't need the CLI to fix it. You can order the agent to "evolve" its own rulebook.
36
40
 
41
+ > **Framing vs. implementation.** "Genetic Evolution" is a metaphor. GABBE's real mechanism is a
42
+ > single-parent **LLM-driven rewrite** of a skill selected by an **epsilon-greedy bandit** — there
43
+ > is no crossover and no population culling. See `ai/self-evolving-skills.md`.
44
+
37
45
  ### The Agent Prompt
38
46
  > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/ui-gen.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
39
47
 
@@ -61,7 +69,7 @@ Agents often fail silently or give up when a test breaks. You can manually force
61
69
 
62
70
  ## 4. Manual Cost-Benefit Routing
63
71
 
64
- If you are using a local LLM or a cheaper model on Copilot and encounter a hyper-complex visual diagram or massive refactor, you can prompt the agent to "route" the task context to you, the human, to paste into a frontier model (like Claude 3.5 Sonnet or OpenAI o1).
72
+ If you are using a local LLM or a cheaper model on Copilot and encounter a hyper-complex visual diagram or massive refactor, you can prompt the agent to "route" the task context to you, the human, to paste into a frontier model.
65
73
 
66
74
  ### The Agent Prompt
67
75
  > "Evaluate my request to [refactor the legacy COBOL module] using `cost-benefit-router.skill.md`. Provide a Complexity Score. If the score is > 50, do not attempt to solve it. Instead, generate a `REMOTE_PAYLOAD.md` containing exactly the context I need to copy-paste into an external AI interface."
@@ -10,7 +10,7 @@ However, **all GABBE swarm coordination protocols are defined in Markdown.** Thi
10
10
 
11
11
  There are two primary ways to operate Swarms in "Agent-Only" mode:
12
12
  1. **In-Context Simulation**: The LLM adopts multiple personas sequentially within the same chat thread.
13
- 2. **True Subagent Delegation (A2A)**: You act as the "Router," taking instructions from the Master Orchestrator and spinning up true, parallel LLM instances (like Gemini 1.5 Pro or Claude 3.5 Sonnet) to do isolated work.
13
+ 2. **True Subagent Delegation (A2A)**: You act as the "Router," taking instructions from the Master Orchestrator and spinning up true, parallel LLM instances (each running a frontier model) to do isolated work.
14
14
 
15
15
  ---
16
16
 
@@ -49,13 +49,13 @@ Use this for simple projects where context window limits are not a concern. The
49
49
  > "Execute the next 3 tasks using **In-Context Simulation**. Act as the `eng-backend` persona to write the code, then immediately adopt the `eng-qa` persona in the next paragraph to test it."
50
50
 
51
51
  ### Tactic B: True Subagent Delegation A2A (For Massive Scale)
52
- Use this when you need true isolation, zero context-pollution, or want to utilize different frontier models for different tasks (e.g., Cursor for coding, OpenAI o1 for Architecture review).
52
+ Use this when you need true isolation, zero context-pollution, or want to utilize different frontier models for different tasks (e.g., one tool for coding, another frontier model for architecture review).
53
53
 
54
54
  > "For the next task, use **True Subagent Delegation**. Do not write the code yourself. Instead, generate a `delegation-payload.md` file. Include the specific `persona` file to load, the exact task context, and the expected output format. I will copy-paste this file into a separate AI model and return the result to you here."
55
55
 
56
56
  **Your Workflow:**
57
57
  1. The Orchestrator generates `delegation-payload.md`.
58
- 2. You open a new browser tab for an advanced model (e.g., Gemini Advanced).
58
+ 2. You open a new browser tab for a frontier model.
59
59
  3. You paste the payload: *"You are now adopting the GABBE `eng-qa` persona based on the following payload..."*
60
60
  4. The Subagent works in isolation and gives you the final test suite.
61
61
  5. You paste the test suite back to the Orchestrator in Cursor: *"Here is the output from the `eng-qa` subagent. Proceed to S06."*
@@ -64,7 +64,7 @@ Use this when you need true isolation, zero context-pollution, or want to utiliz
64
64
 
65
65
  ## 4. Ad-Hoc Swarm Debate (No SDLC)
66
66
 
67
- You don't need the 10 phases to use Swarms. You can invoke a specific matrix of personas to debate a complex architecture decision.
67
+ You don't need the full 14-phase lifecycle (the 10-phase core build loop S01–S10, plus Day-0 S00 and Day-2 S11–S13) to use Swarms. You can invoke a specific matrix of personas to debate a complex architecture decision.
68
68
 
69
69
  ### The Agent Prompt
70
70
  > "Invoke `agents/skills/coordination/multi-agent-orch.skill.md`. I need to decide between PostgreSQL and MongoDB. Load the `prod-architect`, `eng-database`, and `ops-cost` personas. Facilitate a sequential debate simulating their perspectives. Synthesize their arguments into a final recommendation."
@@ -12,7 +12,7 @@
12
12
  | **Context efficiency** | The context window is finite; every token spent on irrelevant text is a token not spent on the task. | `00-index.md` summaries + `context_cost` tags + `preflight.skill` (load summaries, then bodies on demand — progressive disclosure). |
13
13
  | **A clear operating loop** | Ambiguity about "what do I do next" wastes turns and invites drift. | `AGENTS.md` §5 Step 0–7 (preflight → plan → test → implement → verify → refactor → log). |
14
14
  | **Durable memory** | A token/time cutoff or an agent switch must not lose progress. | `state-preserve.skill` (continuous + pre-cutoff checkpoint) + `RESUME_POINTER.md` + `state-portability.skill` (move to any agent). |
15
- | **Knowing when to ask vs act** | Acting on a wrong interpretation is expensive; asking on the obvious is annoying. | `clarify.skill` (uncertainty-aware) + `GABBE_AUTONOMY` levels (L0–L3). |
15
+ | **Knowing when to ask vs act** | Acting on a wrong interpretation is expensive; asking on the obvious is annoying. | `clarify.skill` (uncertainty-aware) + the autonomy posture `GABBE_AUTONOMY = ask \| auto \| hybrid` (default **hybrid**). |
16
16
  | **Fast feedback** | Verifying late means debugging a big surface; verifying early localizes the error. | Test-first mandate + run the test/lint/gate now, not at the end + `verify_all.sh`. |
17
17
  | **Self-correction** | The first attempt is often wrong; a bounded recovery loop beats giving up or thrashing. | `self-heal.skill` (≤5 attempts, cost-gated) + `final-review.skill`. |
18
18
  | **Cost awareness** | Cheap and expensive paths often produce the same result; defaulting to expensive burns budget. | Cost levers (cache/context-budget/model-tier/batch) + `budget.reserve()` + `cost-benefit-router`. |
@@ -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
  ```
@@ -9,7 +9,7 @@ This guide explores paradigms that extend beyond pure Large Language Models, off
9
9
  ## 1. Neuro-Symbolic AI (Hybrid)
10
10
  **The Best of Both Worlds:**
11
11
  * **Neural (System 1):** Fast, intuitive, handles fuzzy data (Images, Text).
12
- * **Symbolic (System 2):** Slow, logical, guarantees correctness (Logic, Math, Rules).
12
+ * **Symbolic (System 2):** Slow, logical, can establish correctness within its formal model (Logic, Math, Rules).
13
13
 
14
14
  ### Application in Engineering
15
15
  * **Formal Verification:** LLM translates code to Formal Logic (TLA+ / Coq). Symbolic Prover verifies it.
@@ -29,6 +29,11 @@ Instead of "one-shot" generation, use "Population-based" improvement.
29
29
  4. **Crossover/Mutation:** Ask LLM to "Mix strategy A and B" or "Mutate parameter X".
30
30
  5. **Repeat:** Until optimal.
31
31
 
32
+ > **Framing vs. implementation.** This is the *evolutionary metaphor*, not what GABBE
33
+ > actually runs. GABBE's real mechanism is a single-parent **LLM-driven rewrite** of a
34
+ > skill steered by an **epsilon-greedy multi-armed bandit** — there is **no crossover and
35
+ > no population culling**. See `ai/self-evolving-skills.md` for the honest accounting.
36
+
32
37
  *See `brain/learning-adaptation.skill.md` and `brain/self-improvement.skill.md`.*
33
38
 
34
39
  ---
@@ -38,9 +43,14 @@ Instead of "one-shot" generation, use "Population-based" improvement.
38
43
  Based on Karl Friston's work. Agents act to confirm their predictions about the world.
39
44
  *See `brain/active-inference.skill.md`.*
40
45
 
46
+ > **Framing vs. implementation.** In GABBE, "Active Inference" and "minimize free energy/surprise"
47
+ > are *framing words* placed in the brain's system prompt to bias the observe → decide → act loop —
48
+ > there is no variational free energy or generative-model math being computed. See
49
+ > `ai/self-evolving-skills.md` for the honest accounting.
50
+
41
51
  * **Generative Model:** The Agent maintains a belief state of the Project.
42
52
  * **Prediction Error:** The difference between "Expected State" (All tests pass) and "Sensed State" (Build failed).
43
- * **Action:** The Agent codes *solely* to minimize this Prediction Error.
53
+ * **Action:** The Agent codes to *reduce* this Prediction Error (as a goal, not a computed objective).
44
54
  * **Epistemic Exploration:** Agent acts not just to fix, but to *learn* ("I will add a log to see what's happening").
45
55
 
46
56
  ---
@@ -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)
@@ -38,14 +38,16 @@ Consistency allows shared client libraries.
38
38
  }
39
39
  ```
40
40
 
41
- ### Error (RFC 7807)
41
+ ### Error (RFC 9457 Problem Details)
42
+ Use the standardized **Problem Details** media type `application/problem+json` (RFC 9457, which obsoletes RFC 7807) for HTTP error responses:
42
43
  ```json
43
44
  {
44
- "error": {
45
- "code": "resource_not_found",
46
- "message": "User 123 not found",
47
- "traceId": "abc-123"
48
- }
45
+ "type": "https://example.com/probs/resource-not-found",
46
+ "title": "Resource not found",
47
+ "status": 404,
48
+ "detail": "User 123 not found",
49
+ "instance": "/users/123",
50
+ "traceId": "abc-123"
49
51
  }
50
52
  ```
51
53
 
@@ -53,7 +55,7 @@ Consistency allows shared client libraries.
53
55
  - **Authentication**: Bearer Token (JWT) in Header.
54
56
  - **Rate Limiting**: Return `429 Too Many Requests` with `Retry-After` header.
55
57
  - **Idempotency**: `POST` requests should accept `Idempotency-Key` header to prevent double-billing on network retry.
56
- - **Documentation**: OpenAPI 3.0+ required for ALL APIs.
58
+ - **Documentation**: OpenAPI 3.1+ required for ALL APIs (3.1 aligns with JSON Schema 2020-12).
57
59
 
58
60
  ## 6. Deprecation Policy
59
61
  1. Mark endpoint `Deprecated: true` in OpenAPI.
@@ -22,7 +22,7 @@ This guide details how to apply **Agentic Engineering** to domains governed by s
22
22
  You cannot trust an AI Agent to control a plane directly ("The Black Box Problem").
23
23
  **Solution:** **Runtime Assurance (RTA)** arch.
24
24
  * **Complex Channel (AI):** Optimizes flight path (High Performance, Low Trust).
25
- * **Safety Monitor (Deterministic):** Checks limits ($$ G < 4.0 $$, $$ Alt > 500 $$).
25
+ * **Safety Monitor (Deterministic):** Checks limits (`G < 4.0`, `Alt > 500`).
26
26
  * **Switch:** If Monitor triggers, revert to distinct "Safe Core" code.
27
27
 
28
28
  ### 2.2 Integration with Domain-Driven Design (DDD)
@@ -47,17 +47,23 @@ In a regulated environment, the Agent's primary job is **Evidence Generation**.
47
47
  2. **Segregation Verification:**
48
48
  * Agent analyzes import graphs.
49
49
  * Alerts if "Class C" (Critical) code imports "Class A" (UI) code.
50
- 3. **Hazard Analysis (FMEA/STPA):**
51
- * Agent brainstorms "What if?" scenarios ("What if the GPS sensor sends NaN?").
50
+ 3. **Hazard Analysis (STPA / FTA):**
51
+ * For *hazard* analysis use system-theoretic methods — **STPA** (Systems-Theoretic Process Analysis) and **FTA** (Fault Tree Analysis) — to reason top-down from unsafe control actions and hazards.
52
+ * **FMEA** (Failure Mode and Effects Analysis) is a *failure-mode* analysis, not a hazard analysis: it works bottom-up from component failure modes to their effects. Use it alongside, not as a substitute for, STPA/FTA.
53
+ * Agent brainstorms "What if?" scenarios ("What if the GPS sensor sends NaN?") to seed both.
52
54
 
53
55
  ---
54
56
 
55
- ## 4. The "Lethal Trifecta" in Critical Ops
57
+ ## 4. Forbidden Constructs in Hard-Real-Time Code
56
58
  Avoid these three at all costs:
57
59
  1. **Unbounded Loops:** Control loops must be deterministic.
58
60
  2. **Dynamic Memory Allocation:** Critical C/C++ often forbids `malloc` after init.
59
61
  3. **Deadlocks:** Actors/Agents must have proven liveness.
60
62
 
63
+ > Note: "Lethal Trifecta" is a term of art for the *prompt-injection* risk
64
+ > (private data + untrusted content + exfiltration channel in one agent) — see the
65
+ > security guides; it does not refer to the real-time constructs above.
66
+
61
67
  ---
62
68
 
63
69
  ## 5. References
@@ -12,11 +12,11 @@
12
12
  - Organization is large enough to support operational overhead
13
13
 
14
14
  **Do NOT use microservices when:**
15
- - Team < 10 engineers (start with modular monolith)
15
+ - Team is below ~50 engineers and you have not hit a concrete scaling-pain trigger (start with a modular monolith)
16
16
  - Domain is not well understood yet (boundaries will be wrong)
17
17
  - Operational maturity is not there (monitoring, tracing, CI/CD)
18
18
 
19
- **Start with a modular monolith. Extract services when boundaries are proven.**
19
+ **Start with a modular monolith. Extract services when boundaries are proven** — the rule of thumb is ~50 engineers or a clear scaling-pain trigger (independent deploy cadence, divergent scaling needs), matching `architecture/monolith.md`.
20
20
 
21
21
  ---
22
22
 
@@ -9,7 +9,7 @@ This directory contains the **High-Level Orchestrators** for the Agentic Enginee
9
9
 
10
10
  - **Role**: Meta-Cognitive Orchestrator.
11
11
  - **Function**: Plans, Routes, and Optimizes.
12
- - **Logic**: Active Inference (Free Energy Principle).
12
+ - **Logic**: Active Inference (Free Energy Principle) — used here as conceptual *framing* for the observe → decide → act loop, not implemented variational math. See `ai/self-evolving-skills.md` for the honest accounting.
13
13
  - **Use Case**: Complex, ambiguous, or high-stakes projects.
14
14
  - **Key Feature**: **Dynamic Cost Routing** (Local vs Remote).
15
15
 
@@ -21,8 +21,8 @@ This directory contains the **High-Level Orchestrators** for the Agentic Enginee
21
21
  > **The Executor (System 1)**
22
22
 
23
23
  - **Role**: SDLC Orchestrator.
24
- - **Function**: Executes the 10-Phase Engineering Lifecycle.
25
- - **Logic**: Deterministic Workflow (S01 -> S10).
24
+ - **Function**: Executes the 14-phase lifecycle (10-phase core build loop S01–S10, plus Day-0 S00 and Day-2 S11–S13).
25
+ - **Logic**: Deterministic Workflow (core build loop S01 -> S10).
26
26
  - **Use Case**: Building software with strict process requirements.
27
27
  - **Key Feature**: **Human-in-the-Loop Gates**.
28
28
 
@@ -46,6 +46,12 @@ If you don't know the quality priorities → you cannot make good architecture d
46
46
 
47
47
  ### ISO 25010 Quality Attributes
48
48
 
49
+ > **Authoritative model:** the canonical, complete characteristic set is the
50
+ > **ISO/IEC 25010:2023 (Ed. 2)** nine-characteristic model in
51
+ > [`system-qualities.md`](system-qualities.md) (which adds Functional Suitability,
52
+ > Compatibility, and the new **Safety** characteristic). The list below is an
53
+ > illustrative subset of the sub-characteristics, not the full model.
54
+
49
55
  ```
50
56
  Performance Efficiency
51
57
  Time behavior: How fast (response time, throughput)
@@ -47,7 +47,7 @@ Match model power to task difficulty. `gabbe route` decides LOCAL (free/cheap lo
47
47
  For non-latency-sensitive bulk work, async batch APIs run at **−50%** (e.g. Anthropic Message Batches). Schedule large non-interactive runs (audits, migrations, regen) as batches.
48
48
 
49
49
  ### Hard guardrails (never disabled)
50
- `GABBE_MAX_COST_USD`, token/iteration/wall-time budgets, and hard stops bound a runaway loop regardless of the optimizations above — cost control must never weaken the quality gates, the 10-phase SDLC, or human-in-the-loop escalation.
50
+ `GABBE_MAX_COST_USD`, token/iteration/wall-time budgets, and hard stops bound a runaway loop regardless of the optimizations above — cost control must never weaken the quality gates, the 10-phase core SDLC (S01–S10), or human-in-the-loop escalation.
51
51
 
52
52
  ## Automation & Agentic Checks
53
53
  Use the `cost-optimization.skill.md` to autonomously: