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
@@ -160,9 +160,38 @@ Import style:
160
160
 
161
161
  ## 5. Workflow for Agents — Review-Driven Development
162
162
 
163
- Agents MUST follow this order. Skipping steps is forbidden.
163
+ Agents MUST follow this order; skipping steps is forbidden. Keep `agents/memory/` current at
164
+ every task (episodic, semantic, AUDIT_LOG, CONTINUITY, PROJECT_STATE, RESUME_POINTER), and consult
165
+ `agents/{skills,guides,templates}/` for relevant capabilities at each step.
166
+
167
+ **CRITICAL MANDATES (always apply):**
168
+
169
+ - **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.
170
+ - **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 phases, or HITL to save cost.
171
+ - **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`.
172
+ - **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.
173
+ - **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`).
174
+
175
+ ### Step 0 — Preflight & Clarify (before anything else)
176
+
177
+ ```
178
+ Run preflight.skill as the FIRST action of every session and every major task:
179
+ 1. Auto-checks: integrity-check (fast) → confirm memory + working tree are coherent.
180
+ 2. Load index SUMMARIES (not bodies): agents/{skills,guides,templates,personas}/00-index.md
181
+ → know what capabilities exist before choosing generically.
182
+ 3. Load memory headers with decay-aware priming (PROJECT_STATE, CONTINUITY, latest snapshot).
183
+ 4. Surface cost posture: GABBE_AUTONOMY (ask|auto|hybrid, default hybrid) + remaining budget.
184
+ 5. Recommend the OPTIMAL set for the task (skills/guides/persona/MCP), ranked by
185
+ relevance × (1/context_cost); pick a reasoning pattern proportionate to task + budget.
186
+ 6. Flag new/changed capabilities since last preflight (defer adoption to update-scan.skill).
187
+ 7. End by invoking clarify.skill → ask the focused batch of clarifying questions
188
+ (and "questions you should ask me") before proceeding.
189
+ Do not begin implementation until blocking questions are answered, unless the autonomy
190
+ posture is `auto` AND the task is cheap AND reversible.
191
+ ```
164
192
 
165
193
  ### Step 1 — Load Context (every session start)
194
+
166
195
  ```
167
196
  1. Read this AGENTS.md completely
168
197
  2. Read CONSTITUTION.md if it exists
@@ -172,6 +201,7 @@ Agents MUST follow this order. Skipping steps is forbidden.
172
201
  ```
173
202
 
174
203
  ### Step 2 — Plan Before Coding
204
+
175
205
  ```
176
206
  Before touching any file, write a brief implementation plan:
177
207
  - What files will you create or modify?
@@ -184,6 +214,7 @@ For complex tasks: write plan.md or use PLAN_TEMPLATE.md
184
214
  ```
185
215
 
186
216
  ### Step 3 — Test First (TDD Red Phase)
217
+
187
218
  ```
188
219
  Write the failing test BEFORE writing implementation code.
189
220
  Run the test -- it MUST fail (Red).
@@ -191,12 +222,14 @@ If the test passes immediately with no implementation: the test is WRONG. Fix it
191
222
  ```
192
223
 
193
224
  ### Step 4 — Implement (TDD Green Phase)
225
+
194
226
  ```
195
227
  Write the minimal code to make the failing test pass.
196
228
  Do not add features not covered by a failing test.
197
229
  ```
198
230
 
199
231
  ### Step 5 — Verify (must all pass before marking done)
232
+
200
233
  ```
201
234
  Run: [test command] -> must pass
202
235
  Run: [typecheck command] -> must pass
@@ -205,23 +238,36 @@ Run: agentic-linter check -> no boundary violations
205
238
  ```
206
239
 
207
240
  ### Step 6 — Refactor
241
+
208
242
  ```
209
243
  Improve code quality while keeping all tests green.
210
244
  Check: Cyclomatic complexity < 10, no code duplication > 3 occurrences, no dead code.
211
245
  ```
212
246
 
213
247
  ### Step 7 — Log & Complete
248
+
214
249
  ```
215
250
  Write entry to agents/memory/AUDIT_LOG.md
216
251
  Update task status in project/TASKS.md to DONE
252
+ Refresh agents/memory/RESUME_POINTER.md (state-preserve.skill) — keep the
253
+ "next action" current so any future session resumes losslessly
217
254
  If this completes a SDLC phase: invoke sdlc-checkpoint.skill
218
255
  ```
219
256
 
257
+ > **State preservation is continuous, not just at Step 7.** Per `state-preserve.skill`
258
+ > and §13, save incrementally after every meaningful step and flush a full snapshot
259
+ > before budget/time runs out — assume a cutoff can happen at any moment.
260
+
220
261
  ---
221
262
 
222
263
  ## 6. Governance & Security
223
264
 
265
+ ### 🛡️ Mandatory Security & Guardrails
266
+
267
+ 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.
268
+
224
269
  ### Forbidden Actions (agents must never do these without explicit human approval)
270
+
225
271
  ```
226
272
  - Commit .env files or any file containing secrets
227
273
  - Push directly to main/master branch
@@ -236,6 +282,7 @@ If this completes a SDLC phase: invoke sdlc-checkpoint.skill
236
282
  ```
237
283
 
238
284
  ### Secrets Policy
285
+
239
286
  ```
240
287
  All secrets MUST be in environment variables.
241
288
  Local dev: .env file (always in .gitignore)
@@ -245,6 +292,7 @@ Use: [PLACEHOLDER: dotenv | .env.vault | AWS Secrets Manager | HashiCorp Vault]
245
292
  ```
246
293
 
247
294
  ### PR Format (Conventional Commits)
295
+
248
296
  ```
249
297
  Format: <type>(<scope>): <subject>
250
298
 
@@ -266,10 +314,11 @@ PR body must include:
266
314
  ```
267
315
 
268
316
  ### Quality Gates (all must pass before PR merges)
317
+
269
318
  ```
270
319
  Gate 1 -- Syntax/Linting: ESLint / PHP-CS-Fixer / Prettier / Ruff -- zero errors
271
320
  Gate 2 -- Type Safety: tsc --noEmit / PHPStan L9 / mypy -- zero errors
272
- Gate 3 -- Test Coverage: >99% coverage, all tests passing, no skipped tests
321
+ Gate 3 -- Test Coverage: >= 99% coverage, all tests passing, no skipped tests
273
322
  Gate 4 -- Integration: Docker Compose up, API contract validation
274
323
  Gate 5 -- Security scan: npm audit / composer audit -- no critical or high CVEs
275
324
  Gate 6 -- Complexity: Cyclomatic complexity < 10 on modified files
@@ -283,6 +332,7 @@ Gate 7 -- EARS Compliance: (for new features) All requirements have tests
283
332
  Agents must use authoritative sources. Never guess or hallucinate.
284
333
 
285
334
  ### Source Tiers (in order of trust)
335
+
286
336
  ```
287
337
  Tier 1 (Primary -- always prefer):
288
338
  - Official language/framework docs (MDN, nodejs.org, laravel.com, docs.python.org)
@@ -303,6 +353,7 @@ NOT acceptable (never cite as authoritative):
303
353
  ```
304
354
 
305
355
  ### Research Gate -- mandatory before:
356
+
306
357
  ```
307
358
  - Using any library not in existing package.json / composer.json
308
359
  - Calling any API method not confirmed in official docs
@@ -311,6 +362,7 @@ NOT acceptable (never cite as authoritative):
311
362
  ```
312
363
 
313
364
  ### When to invoke research.skill
365
+
314
366
  ```
315
367
  "I'm not sure about X" -> knowledge-gap.skill -> research.skill -> confirm before coding
316
368
  If library version not found in official docs -> do NOT assume behavior -> report to human
@@ -324,6 +376,7 @@ Use Context-7 MCP for library docs (prevents hallucinated deprecated API usage)
324
376
  Agents may autonomously fix failures up to 5 attempts.
325
377
 
326
378
  ### What agents may self-heal (no human approval needed):
379
+
327
380
  ```
328
381
  - Type errors and lint errors
329
382
  - Test assertion updates when spec changed
@@ -334,6 +387,7 @@ Agents may autonomously fix failures up to 5 attempts.
334
387
  ```
335
388
 
336
389
  ### What requires human decision:
390
+
337
391
  ```
338
392
  - Architecture or library changes
339
393
  - Breaking API changes (any consumer affected)
@@ -345,7 +399,9 @@ Agents may autonomously fix failures up to 5 attempts.
345
399
  ```
346
400
 
347
401
  ### Self-Heal Escalation Protocol
402
+
348
403
  After 5 failed attempts, agent MUST:
404
+
349
405
  ```
350
406
  1. STOP all autonomous action
351
407
  2. Create structured escalation report:
@@ -357,6 +413,15 @@ After 5 failed attempts, agent MUST:
357
413
  4. Wait for human response before continuing
358
414
  ```
359
415
 
416
+ ### Self-Evolving Policy (within cost + permission bounds)
417
+
418
+ The system may keep itself current and improve (new/better skills, tools, MCPs, models) via
419
+ `update-scan.skill` — but only inside hard bounds (full detail in that skill):
420
+
421
+ - **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.
422
+ - **Always needs human approval** (even under `auto`): anything expensive/SOTA/irreversible, externally-sourced runnable code, or any change to protected files.
423
+ - **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.
424
+
360
425
  ---
361
426
 
362
427
  ## 9. Human-in-the-Loop Triggers
@@ -373,6 +438,8 @@ ALWAYS pause and ask:
373
438
  - Architectural change (new service, new database, library switch)
374
439
  - Any discovered vulnerability that requires feature disablement
375
440
  - "I've tried 5 times and cannot fix this" (see Self-Healing Policy)
441
+ - Any expensive / SOTA-model / irreversible action — even under GABBE_AUTONOMY=auto
442
+ - Adopting a new tool, model, or externally-sourced skill (see update-scan / skills-registry)
376
443
  - [PLACEHOLDER: add project-specific escalation triggers]
377
444
 
378
445
  Format for human escalation:
@@ -385,11 +452,20 @@ Format for human escalation:
385
452
  Awaiting: [specific decision needed]
386
453
  ```
387
454
 
455
+ **Clarify at every major step (not just at session start).** Per `clarify.skill`, the agent
456
+ estimates its own uncertainty before each major step and asks a focused batch of clarifying
457
+ questions (≈3–6, highest-impact first) whenever interpretation is ambiguous, a decision input is
458
+ missing, retrieval/verification failed, or the action is expensive/irreversible. The amount of
459
+ questioning scales with the `GABBE_AUTONOMY` posture (ask → clarify freely; hybrid → clarify on
460
+ real ambiguity; auto → silent for cheap/reversible work but always pause for the cases above).
461
+ Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed, not a guess.
462
+
388
463
  ---
389
464
 
390
465
  ## 10. Tool-Specific Overrides
391
466
 
392
467
  ### Claude Code (claude.ai/code, Claude Code CLI)
468
+
393
469
  ```
394
470
  - Skills: Use slash commands matching skill names (e.g., /tdd-cycle, /code-review)
395
471
  - Memory: Use TodoWrite tool for task tracking
@@ -398,6 +474,7 @@ Format for human escalation:
398
474
  ```
399
475
 
400
476
  ### Cursor
477
+
401
478
  ```
402
479
  - Context: This AGENTS.md is symlinked to .cursorrules
403
480
  - Skills: Reference skill files directly in conversation
@@ -405,12 +482,14 @@ Format for human escalation:
405
482
  ```
406
483
 
407
484
  ### GitHub Copilot
485
+
408
486
  ```
409
487
  - Context: Instructions from .github/copilot-instructions.md (symlinked)
410
488
  - Skills: Reference skills/ directory files in comments or conversation
411
489
  ```
412
490
 
413
491
  ### Antigravity / Gemini CLI
492
+
414
493
  ```
415
494
  - Context: This AGENTS.md is symlinked to .gemini/settings.json (instructions field)
416
495
  - Skills: Symlinked to .agent/skills/ -- invoke by trigger keywords
@@ -442,7 +521,12 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
442
521
 
443
522
  ## 12. References
444
523
 
445
- ### 3. Skill Access
524
+ **Discover skills via the index — `agents/skills/00-index.md` is the canonical catalog**: native
525
+ skill menus (e.g. Claude Code) may truncate large collections by token budget, so always consult
526
+ the index to find any skill, then read its full file before use. Per-tool skill locations: see §10.
527
+
528
+ **Skill access (search first, read before use):**
529
+
446
530
  - **Search First**: Before coding, search for relevant skills:
447
531
  - **Cursor**: Check `.cursor/rules/` for `.mdc` files.
448
532
  - **VS Code / Copilot**: Check `.github/skills/` or invoke via slash command.
@@ -452,16 +536,17 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
452
536
 
453
537
  ```
454
538
  Project law: agents/CONSTITUTION.md
455
- Skills registry: agents/skills/00-index.md
456
- Language guides: agents/guides/
457
- Orchestrators: agents/skills/brain/README.md
458
- Brain Patterns: agents/skills/brain/README.md
539
+ Skills (canonical): agents/skills/00-index.md (master: agents/skills/**)
540
+ Guides: agents/guides/00-index.md
459
541
  Templates: agents/templates/00-index.md
460
- Quick reference: QUICK_GUIDE.md
542
+ Personas (Loki): agents/personas/00-index.md
543
+ Brain patterns: agents/skills/brain/README.md
544
+ Quick reference: docs/QUICK_GUIDE.md
461
545
  Project memory: agents/memory/PROJECT_STATE.md
462
546
  Past failures: agents/memory/CONTINUITY.md
463
547
  Decision log: agents/memory/AUDIT_LOG.md
464
548
  ```
549
+
465
550
  - **Skills**: `agents/skills/` (Master) → `.cursor/rules/` (*.mdc) | `.github/skills/` | `.claude/skills/`
466
551
  - **Memory**: `agents/memory/`
467
552
 
@@ -474,19 +559,33 @@ Every session, agents MUST:
474
559
  ```
475
560
  START of session:
476
561
  1. Read this AGENTS.md
477
- 2. Read agents/memory/PROJECT_STATE.md (if exists) -> understand current state
478
- 3. Read agents/memory/CONTINUITY.md (if exists) -> understand past failures
479
- 4. Load latest agents/memory/episodic/SESSION_SNAPSHOT/ (if exists)
480
- 5. If resuming: use session-resume.skill for full recovery
481
- 6. Run integrity-check.skill before starting new work on existing code
562
+ 2. Read agents/memory/RESUME_POINTER.md (the lifeline — current task + NEXT ACTION)
563
+ 3. Read agents/memory/PROJECT_STATE.md (if exists) -> understand current state
564
+ 4. Read agents/memory/CONTINUITY.md (if exists) -> understand past failures
565
+ 5. Load latest agents/memory/episodic/SESSION_SNAPSHOT/ (if exists)
566
+ 6. If resuming: use session-resume.skill for full recovery
567
+ 7. Run integrity-check.skill before starting new work on existing code
568
+
569
+ CONTINUOUSLY — never lose progress (state-preserve.skill; assume a cutoff at any moment):
570
+ - After each meaningful step: refresh RESUME_POINTER.md (current task + precise NEXT ACTION)
571
+ and append the outcome to AUDIT_LOG.md.
572
+ - Pre-exhaustion flush: when budget/tokens/turns run low or before a long/irreversible action,
573
+ write a FULL snapshot FIRST (RESUME_POINTER, then snapshot/PROJECT_STATE/CONTINUITY).
574
+ - On-disk Markdown memory must always suffice for a fresh agent to resume losslessly.
575
+
576
+ PORTABLE — switch coding agent or LLM anytime (state-portability.skill):
577
+ DEHYDRATE (state_export.sh → STATE_HANDOFF.md + a lossless bundle) and HYDRATE in the
578
+ destination agent (state_import.sh), then run session-resume + preflight. Memory + instructions
579
+ + state are a fully compatible export/import. Never export secrets; merge (don't clobber) on import.
482
580
 
483
581
  END of session:
484
582
  1. Update project/TASKS.md with current status of all in-progress tasks
485
583
  2. Write session summary to agents/memory/episodic/ (DECISION_LOG_TEMPLATE.md)
486
584
  3. Update agents/memory/PROJECT_STATE.md with current SDLC phase
487
585
  4. Write all decisions/outcomes to agents/memory/AUDIT_LOG.md
488
- 5. Create SDLC checkpoint if a phase was completed
489
- 6. If stopping mid-task: note exactly where you stopped and why
586
+ 5. Update agents/memory/CONTINUITY.md with lessons learned
587
+ 6. Create SDLC checkpoint if a phase was completed
588
+ 7. If stopping mid-task: note exactly where you stopped and why (RESUME_POINTER)
490
589
  ```
491
590
 
492
591
  ---
@@ -535,6 +634,24 @@ Examples:
535
634
 
536
635
  ---
537
636
 
637
+ ## Loki & Brain — Agentic Orchestration
638
+
639
+ Two optional orchestration modes (both run purely via Markdown inference; the `gabbe`
640
+ CLI is optional). Full definitions live in the skills — this is only a pointer (avoid
641
+ restating them here, to prevent drift):
642
+
643
+ - **🧠 Brain Mode** (`brain/brain-mode.skill.md`) — the Strategist (System 2): meta-cognitive
644
+ planner/router/optimizer (Active Inference framing + dynamic cost routing). Trigger: `gabbe brain activate`, `supermode`.
645
+ - **⚡ Loki Mode** (`brain/loki-mode.skill.md`) — the Executor (System 1): the deterministic
646
+ SDLC lifecycle (S00→S13, 14 phases) with human-in-the-loop hard gates at S00 (GO/NO-GO),
647
+ S01, S02, S07, S08. Trigger: `loki`, `orchestrate`.
648
+
649
+ Brain Mode **wraps** Loki: it receives the request, routes by complexity/budget, runs Loki for
650
+ the SDLC, and monitors — intervening if cost spikes, errors loop, or requirements drift. Both use
651
+ the same operating spine in §5/§13 (preflight → clarify → act → state-preserve → final-review).
652
+
653
+ ---
654
+
538
655
  *Last updated: [DATE]*
539
- *GABBE Kit version: 1.0.3*
656
+ *GABBE Kit version: 1.1.0*
540
657
  *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 |
@@ -1,5 +1,5 @@
1
1
  # Session Snapshot — S[XX]_[PHASE_NAME]
2
- <!-- Created by: sdlc-checkpoint.skill -->
2
+ <!-- Created by: sdlc-checkpoint.skill (the SESSION_SNAPSHOT/ directory is created on first checkpoint) -->
3
3
  <!-- Store in: agents/memory/episodic/SESSION_SNAPSHOT/S[XX]_[phase].md -->
4
4
  <!-- IMMUTABLE after creation — never overwrite, create new snapshot for revisions -->
5
5
 
@@ -7,7 +7,7 @@
7
7
 
8
8
  **Snapshot ID:** S[XX]-[YYYYMMDD]-[HH]
9
9
  **Timestamp:** [ISO 8601: 2025-03-15T14:30:00Z]
10
- **SDLC Phase:** S[XX] — [Phase Name: REQUIREMENTS/DESIGN/SPEC/TASKS/IMPLEMENTATION/TESTING/SECURITY/REVIEW/STAGING/PRODUCTION]
10
+ **SDLC Phase:** S[XX] — [Phase Name: DISCOVERY(S00)/REQUIREMENTS(S01)/DESIGN(S02)/SPEC(S03)/TASKS(S04)/IMPLEMENTATION(S05)/TESTING(S06)/SECURITY(S07)/REVIEW(S08)/STAGING(S09)/PRODUCTION(S10)/OPERATE(S11)/EVOLVE(S12)/DECOMMISSION(S13)]
11
11
  **Created by:** [agent persona name or "human"]
12
12
  **Project:** [Project name from AGENTS.md]
13
13
 
@@ -19,7 +19,7 @@
19
19
  SDLC Phase: S[XX] — [Phase Name]
20
20
  Phase status: COMPLETED / IN_PROGRESS
21
21
  Gate criteria met: YES / NO (if NO, explain)
22
- Overall progress: [X]/10 phases complete
22
+ Overall progress: [X]/14 phases complete (S00–S13)
23
23
  Confidence: HIGH / MEDIUM / LOW
24
24
  ```
25
25
 
@@ -80,7 +80,7 @@ Example:
80
80
  | Metric | Current | Target | Trend |
81
81
  |---|---|---|---|
82
82
  | Cyclomatic complexity (max) | [X] | < 10 | [improving/stable/worsening] |
83
- | Test coverage | [X]% | > 99% | [improving/stable/worsening] |
83
+ | Test coverage | [X]% | >= 99% | [improving/stable/worsening] |
84
84
  | Code duplication | [X]% | < 3% | [improving/stable/worsening] |
85
85
  | TODO/FIXME count | [X] | 0 untracked | [improving/stable/worsening] |
86
86
  | Outdated major deps | [X] | 0 | [improving/stable/worsening] |
@@ -157,9 +157,15 @@ DELETE /api/v1/[resource]/{id} Delete
157
157
 
158
158
  ---
159
159
 
160
- ## 9. Non-Functional Requirements
160
+ ## 9. Non-Functional Requirements (Summary)
161
161
 
162
- | Category | Requirement |
162
+ <!-- This is a SUMMARY only. The authoritative, full NFR definition (RTO/RPO, latency
163
+ percentiles, throughput, encryption, observability, compatibility) lives in
164
+ NFR_TEMPLATE.md — link it here and do not duplicate detail. -->
165
+
166
+ **Full NFR definition:** [Link to NFR.md (from NFR_TEMPLATE.md)]
167
+
168
+ | Category | Headline target (full detail in NFR.md) |
163
169
  |---|---|
164
170
  | **Performance** | API responses < [X]ms at p99 under [Y] concurrent users |
165
171
  | **Availability** | [X]% uptime SLO |
@@ -223,9 +223,15 @@ tests/integration/api/[resource].test.ts
223
223
  ```
224
224
 
225
225
  ### Coverage Target
226
- - Domain layer: > 99%
227
- - Application layer: > 85%
228
- - Adapters layer: > 99% (integration tests)
226
+
227
+ <!-- Respect the test pyramid: unit-heavy domain layer carries the highest coverage;
228
+ integration-level adapter coverage targets critical paths, not every branch.
229
+ Keep these in sync with coding/TEST_PLAN_TEMPLATE.md §2. -->
230
+
231
+ - Domain layer (unit): >= 99%
232
+ - Application layer (unit): > 90%
233
+ - Adapters layer (integration): critical paths covered (~70–80% — integration tests
234
+ exercise wiring, not every branch)
229
235
 
230
236
  ---
231
237
 
@@ -177,7 +177,7 @@ sequenceDiagram
177
177
 
178
178
  ## 7. Design Readiness Checklist
179
179
 
180
- **All required items must pass before proceeding to S02 Architecture / S03 Implementation.**
180
+ **All required items must pass before proceeding to S02 Architecture / S03 Specification.**
181
181
 
182
182
  ### Required
183
183
  - [ ] System architecture diagram (C4 Context minimum) — present and human-verified
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
  }
@@ -438,7 +438,7 @@ gabbe registry add ./bundle --namespace ext # dry run
438
438
  gabbe registry add https://example/skill.skill.md --apply
439
439
  ```
440
440
 
441
- ### `gabbe setup`
441
+ ### `gabbe setup [--force]`
442
442
 
443
443
  Run the interactive install wizard (`scripts/init.py`) to wire the kit into your
444
444
  coding agents. (For a Python-independent install, use `npx gabbe-kit init` or
@@ -446,6 +446,42 @@ coding agents. (For a Python-independent install, use `npx gabbe-kit init` or
446
446
 
447
447
  ```bash
448
448
  gabbe setup
449
+ gabbe setup --force # re-template even preserved files (each backed up first)
450
+ ```
451
+
452
+ **Behavior:**
453
+ - **Never-clobber.** Any differing pre-existing file is backed up to `<name>.gabbe-bak`
454
+ before being refreshed; nothing you already had is silently overwritten. The
455
+ preserve-set (`AGENTS.md`, `CONSTITUTION.md`, `TASKS.md`, `policies.yml`, `config.json`)
456
+ is left untouched unless you pass `--force`, which re-templates them too (still backing
457
+ each up first).
458
+ - **Reversible.** The wizard writes `.gabbe/manifest.json` recording everything it created
459
+ (copied kit files, wiring symlinks, generated skill trees, config files), so
460
+ `gabbe uninstall` fully reverses a wizard install.
461
+ - **Brownfield autodetect.** In an existing codebase (detects `package.json`,
462
+ `pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`, `pom.xml`, `Gemfile`, a `.git`
463
+ repo, etc.) the wizard adds a Mode question — greenfield vs **Upgrade / Refactor
464
+ existing** — prefills detected language / framework / package-manager / project-name as
465
+ defaults, and in refactor mode scaffolds a `BROWNFIELD_ONBOARDING.md` discovery brief
466
+ instead of greenfield mission docs. The greenfield flow is unchanged in an empty dir.
467
+ - **Placeholder population.** Derivable `[PLACEHOLDER:]` fields in `AGENTS.md`
468
+ (dev/test/lint/format/typecheck/coverage commands, `repo_url`, `ci_cd`,
469
+ `deployment_target`) are auto-filled; the rest are kept, tagged
470
+ `<!-- OPTIONAL: fill this in yourself -->`, and listed in an end-of-install warning so
471
+ blank fields are never shipped silently.
472
+
473
+ **Node installer (`npx gabbe-kit init`) flags** — the Python-independent equivalent
474
+ supports the same never-clobber/`--force` behavior plus non-interactive install:
475
+
476
+ | Flag | Description |
477
+ |---|---|
478
+ | `--yes` | Non-interactive; accept defaults without prompting |
479
+ | `--agents <list>` | Comma-separated agents to wire (e.g. `--agents claude,cursor`) |
480
+ | `--force` | Re-template even preserve-set files (each backed up to `<name>.gabbe-bak` first) |
481
+
482
+ ```bash
483
+ npx gabbe-kit init --yes --agents claude,cursor
484
+ npx gabbe-kit init --force
449
485
  ```
450
486
 
451
487
  ---
@@ -498,10 +534,12 @@ gabbe update
498
534
  ### `gabbe uninstall [--agents LIST] [--dry-run] [--purge] [--global] [--dir PATH]`
499
535
 
500
536
  Reverse a GABBE install using its `.gabbe/manifest.json`: removes exactly what was
501
- installed, restores any `.bak` backups, prunes now-empty dirs, and never touches
502
- unrelated files. `--agents` deselects specific agents only; `--dry-run` prints the
503
- plan without changing anything; `--purge` also removes the `agents/` kit and
504
- `.gabbe/`. Idempotent and isolated (never writes outside the target).
537
+ installed, restores any `.gabbe-bak`/`.bak` backups, preserves any file you edited after
538
+ install as `<name>.gabbe-bak` (rather than deleting it), prunes now-empty wiring dirs, and
539
+ never touches unrelated files. Wizard installs (`gabbe setup`) are manifest-tracked and so
540
+ fully reversible. `--agents` deselects specific agents only; `--dry-run` prints the plan
541
+ without changing anything; `--purge` also removes the `agents/` kit and `.gabbe/`.
542
+ Idempotent and isolated (never writes outside the target).
505
543
 
506
544
  ```bash
507
545
  gabbe uninstall --dry-run
package/docs/INSTALL.md CHANGED
@@ -4,11 +4,13 @@ GABBE installs are **isolated**: nothing is ever written outside the chosen targ
4
4
  unless you pass `--global`.
5
5
 
6
6
  > **Reversibility — scope.** Manifest-backed, precise `update`/`uninstall` (recorded
7
- > in `.gabbe/manifest.json`) covers kits managed by the Python `gabbe` CLI — i.e.
8
- > after a `gabbe update` from a checkout / editable install, which writes the
9
- > manifest. The Python-independent installers (`npx gabbe-kit init`, `curl … | sh`,
10
- > and the `scripts/init.py` wizard) copy the kit but do **not** write a manifest, so
11
- > `gabbe uninstall` cannot auto-reverse them — remove those manually (delete the
7
+ > in `.gabbe/manifest.json`) covers kits managed by the Python `gabbe` CLI **and**
8
+ > the Python wizard (`gabbe setup` / `python scripts/init.py`), which now writes a
9
+ > manifest recording everything it created under the project (copied kit files,
10
+ > wiring symlinks, generated skill trees, config files). So `gabbe uninstall` fully
11
+ > reverses a wizard install too. The remaining Python-independent installers
12
+ > (`npx gabbe-kit init`, `curl … | sh`) copy the kit but do **not** write a manifest,
13
+ > so `gabbe uninstall` cannot auto-reverse them — remove those manually (delete the
12
14
  > created `agents/`, `.agents/`, per-agent dirs, and root `AGENTS.md`), or run
13
15
  > `gabbe update` from a checkout to begin manifest tracking.
14
16
 
@@ -21,6 +23,14 @@ unless you pass `--global`.
21
23
  | Shell bootstrap | `curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh \| sh` | picks the best available installer |
22
24
  | Git checkout | `git clone … && python3 scripts/init.py` | the interactive wizard |
23
25
 
26
+ **Never-clobber + `--force`.** Both installers — the Node installer
27
+ (`npx gabbe-kit init`) and the Python wizard (`gabbe setup` / `python scripts/init.py`)
28
+ — back up ANY differing pre-existing file to `<name>.gabbe-bak` before refreshing it, so
29
+ nothing you already had is silently overwritten. The preserve-set (`AGENTS.md`,
30
+ `CONSTITUTION.md`, `TASKS.md`, `policies.yml`, `config.json`) is left as-is unless you
31
+ pass `--force` (e.g. `npx gabbe-kit init --force`), which opts into re-templating those
32
+ too — and still backs each one up first.
33
+
24
34
  After installing, run `gabbe doctor` to print an environment + install report
25
35
  (detected OS/arch, runtimes, agent clients, and per-check PASS/WARN). It also prints
26
36
  **post-install next steps** — which MCP servers to enable and how. For the full
@@ -62,11 +72,14 @@ pwsh ./uninstall.ps1 -DryRun # Windows / PowerShell
62
72
  ```
63
73
 
64
74
  Uninstall reads `.gabbe/manifest.json`, removes **exactly** what was installed,
65
- restores any shadowed user files from their `.bak`, prunes now-empty directories,
66
- and is idempotent (safe to run twice). When a manifest is present the result is
67
- byte-identical to the pre-install state. **Note:** `npx` / `curl` / wizard installs
68
- are not manifest-tracked (see the scope note at the top); for those, delete the kit
69
- directories manually or run `gabbe update` from a checkout first.
75
+ restores any shadowed user files from their `.gabbe-bak`/`.bak` backup, preserves any
76
+ file you edited after install as `<name>.gabbe-bak` instead of deleting it, prunes
77
+ now-empty wiring directories, and is idempotent (safe to run twice). When a manifest is
78
+ present the result is byte-identical to the pre-install state. The wizard
79
+ (`gabbe setup` / `python scripts/init.py`) now writes a manifest, so its installs are
80
+ fully reversible too. **Note:** only `npx` / `curl` installs remain non-manifest-tracked
81
+ (see the scope note at the top); for those, delete the kit directories manually or run
82
+ `gabbe update` from a checkout first.
70
83
 
71
84
  ## Verification
72
85