gabbe-kit 1.1.0 → 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 (72) hide show
  1. package/agents/AGENTS.md +3 -2
  2. package/agents/guides/00-index.md +4 -4
  3. package/agents/guides/ai/agent-only-cognition.md +10 -2
  4. package/agents/guides/ai/agent-only-swarms.md +4 -4
  5. package/agents/guides/ai/agent-operating-ergonomics.md +1 -1
  6. package/agents/guides/ai/beyond-llms.md +12 -2
  7. package/agents/guides/architecture/api-standards.md +9 -7
  8. package/agents/guides/architecture/critical-systems-arch.md +10 -4
  9. package/agents/guides/architecture/microservices.md +2 -2
  10. package/agents/guides/architecture/orchestration.md +3 -3
  11. package/agents/guides/architecture/systems-architecture.md +6 -0
  12. package/agents/guides/ops/cost-optimization.md +1 -1
  13. package/agents/guides/patterns/agentic-patterns.md +12 -40
  14. package/agents/guides/patterns/ai-native-scenarios.md +2 -2
  15. package/agents/guides/patterns/design-patterns.md +11 -65
  16. package/agents/guides/patterns/software-design-patterns.md +4 -2
  17. package/agents/guides/principles/clean-code-standards.md +1 -1
  18. package/agents/guides/principles/evaluation-strategy.md +18 -13
  19. package/agents/guides/principles/future-tech.md +1 -1
  20. package/agents/guides/principles/human-agent-collaboration.md +4 -3
  21. package/agents/guides/principles/legacy-tech.md +7 -3
  22. package/agents/guides/principles/testing-strategy.md +5 -3
  23. package/agents/guides/processes/loki-sdlc-phases.md +1 -1
  24. package/agents/guides/security/api-security.md +1 -1
  25. package/agents/guides/security/cryptography-standards.md +8 -2
  26. package/agents/guides/security/privacy-data-protection.md +2 -2
  27. package/agents/guides/security/secure-architecture.md +1 -1
  28. package/agents/skills/00-index.md +16 -16
  29. package/agents/skills/brain/active-inference.skill.md +1 -1
  30. package/agents/skills/brain/brain-mode.skill.md +9 -2
  31. package/agents/skills/brain/cost-benefit-router.skill.md +20 -8
  32. package/agents/skills/brain/loki-mode.skill.md +13 -10
  33. package/agents/skills/brain/sequential-thinking.skill.md +1 -1
  34. package/agents/skills/coding/mobile-dev.skill.md +1 -0
  35. package/agents/skills/coding/tdd-cycle.skill.md +1 -1
  36. package/agents/skills/coding/testing-strategy.skill.md +1 -1
  37. package/agents/skills/coding/visual-design.skill.md +1 -0
  38. package/agents/skills/coordination/agent-interop.skill.md +5 -4
  39. package/agents/skills/coordination/meta-optimize.skill.md +2 -2
  40. package/agents/skills/coordination/multi-agent-orch.skill.md +1 -1
  41. package/agents/skills/coordination/persona-selector.skill.md +1 -1
  42. package/agents/skills/coordination/self-optimize.skill.md +1 -1
  43. package/agents/skills/coordination/swarm-consensus.skill.md +10 -0
  44. package/agents/skills/core/audit-trail.skill.md +1 -1
  45. package/agents/skills/core/emerging-tech.skill.md +1 -1
  46. package/agents/skills/core/integrity-check.skill.md +1 -1
  47. package/agents/skills/core/knowledge-connect.skill.md +1 -0
  48. package/agents/skills/core/preflight.skill.md +8 -0
  49. package/agents/skills/core/sdlc-checkpoint.skill.md +7 -2
  50. package/agents/skills/core/self-heal.skill.md +17 -4
  51. package/agents/skills/core/session-resume.skill.md +8 -3
  52. package/agents/skills/core/state-portability.skill.md +3 -2
  53. package/agents/skills/ops/incident-response.skill.md +1 -0
  54. package/agents/skills/ops/production-health.skill.md +1 -0
  55. package/agents/skills/ops/release-management.skill.md +1 -0
  56. package/agents/skills/ops/system-benchmark.skill.md +1 -0
  57. package/agents/skills/product/spec-writer.skill.md +6 -3
  58. package/agents/skills/security/ai-safety-guardrails.skill.md +12 -3
  59. package/agents/skills/security/legal-review.skill.md +1 -0
  60. package/agents/skills/security/reliability-engineering.skill.md +4 -3
  61. package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +1 -1
  62. package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +7 -0
  63. package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +1 -1
  64. package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +2 -2
  65. package/agents/templates/coordination/AGENTS_TEMPLATE.md +108 -15
  66. package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +3 -3
  67. package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +1 -1
  68. package/agents/templates/product/PRD_TEMPLATE.md +8 -2
  69. package/agents/templates/product/SPEC_TEMPLATE.md +9 -3
  70. package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +1 -1
  71. package/docs/adr/0002-brain-active-inference-runtime.md +29 -8
  72. package/package.json +1 -1
@@ -8,6 +8,7 @@ context_cost: high
8
8
  # Incident Response Skill
9
9
 
10
10
  ## Goal
11
+ Coordinate the response to a production incident — drive communication, containment, mitigation, and resolution in the correct order — rather than fixing the bug single-handedly.
11
12
 
12
13
  ## Role
13
14
  You are an **Incident Commander**. Your goal is NOT to fix the bug yourself, but to coordinate the response, ensuring communication, containment, and resolution happen in order.
@@ -8,6 +8,7 @@ context_cost: medium
8
8
  # Production Health Skill
9
9
 
10
10
  ## Goal
11
+ Assess and maintain the operational health of an agentic system in production — checking vitals (latency, error rates, saturation), reliability signals, and cost/FinOps posture, and flagging anomalies before they become incidents.
11
12
 
12
13
  ## Role
13
14
  You are a Site Reliability Engineer (SRE) and FinOps specialist focused on the operational health of agentic systems.
@@ -8,6 +8,7 @@ context_cost: low
8
8
  # Release Management Skill
9
9
 
10
10
  ## Goal
11
+ Manage software releases so they are traceable, documented, and correctly versioned — produce changelogs, apply Semantic Versioning, and tag releases for clean rollback and audit.
11
12
 
12
13
  ## Role
13
14
  You are a **Release Manager**. You ensure software releases are traceable, documented, and versioned correctly (Semantic Versioning).
@@ -8,6 +8,7 @@ context_cost: medium
8
8
  # System Benchmark Skill
9
9
 
10
10
  ## Goal
11
+ Benchmark a system under realistic and adversarial load — design and run load/stress tests, measure throughput, latency, and saturation points, and report bottlenecks against capacity targets.
11
12
 
12
13
  ## Role
13
14
  You are a Performance Engineer specializing in load testing, stress testing, and system analysis.
@@ -11,6 +11,8 @@ context_cost: medium
11
11
  ## Goal
12
12
  Transform a user goal or feature request into a structured PRD using EARS syntax. Before generating requirements, invoke the ambiguity layer to clarify unclear aspects. Human approval required before proceeding to implementation.
13
13
 
14
+ > **Boundary vs `product/req-elicitation.skill`:** `req-elicitation` is the heavyweight IEEE 29148 / IREB elicitation pass (stakeholder interviews, use cases → full `EARS_REQUIREMENTS.md`). `spec-writer` is the fast feature-to-PRD path that reuses the **same EARS forms** (defined canonically in `req-elicitation`). For large or regulated requirement sets, run `req-elicitation`; use `spec-writer` for a single feature's PRD. Both must use the identical EARS patterns.
15
+
14
16
  ## Steps
15
17
 
16
18
  1. **Receive and understand the goal**
@@ -59,11 +61,12 @@ Transform a user goal or feature request into a structured PRD using EARS syntax
59
61
  THE SYSTEM SHALL require a TOTP code on each login attempt.
60
62
  ```
61
63
 
62
- **Unwanted Behavior** (negative requirements):
64
+ **Unwanted Behavior** (defensive requirements — canonical `IF…THEN` form):
63
65
  ```
64
- THE SYSTEM SHALL NOT store plaintext passwords in any medium.
65
- THE SYSTEM SHALL NOT expose internal stack traces in HTTP responses.
66
+ IF a password is submitted for storage THEN THE SYSTEM SHALL hash it and SHALL NOT store the plaintext in any medium.
67
+ IF an unhandled error occurs THEN THE SYSTEM SHALL return a generic error and SHALL NOT expose internal stack traces in HTTP responses.
66
68
  ```
69
+ (Matches the `IF [unwanted condition] THEN the [system] shall [protective response]` form in `req-elicitation.skill` / `req-review.skill`.)
67
70
 
68
71
  5. **Write acceptance criteria**
69
72
  Each requirement needs 1+ verifiable acceptance criteria:
@@ -13,14 +13,23 @@ This skill protects the system from its own AI.
13
13
 
14
14
  ## Steps
15
15
  ## 1. Input Guardrails (Defense)
16
+
17
+ > **KNOWN-WEAK, necessary-not-sufficient layers.** Delimiters/"Sandwich Defense" and
18
+ > pattern-matching jailbreak filters are *trivially bypassed* and must never be the sole or
19
+ > authoritative defense — treat them as cheap pre-filters only. The authoritative controls are
20
+ > structural (instruction hierarchy, dual-LLM quarantine, least-privilege tokens, egress
21
+ > filtering, HITL on trifecta-complete actions). See `prompt-injection-defense.skill` (which
22
+ > states: "Pattern-matching filters and 'ask the LLM to detect the injection' are known-weak and
23
+ > trivially bypassed") for the layered defense these rails must enforce.
24
+
16
25
  - **Prompt Injection**: "Ignore previous instructions".
17
- - *Defense*: Delimiters (XML tags), "Sandwich Defense" (System Prompt + User Input + System Reminder).
26
+ - *Defense (weak pre-filter only)*: Delimiters (XML tags), "Sandwich Defense" (System Prompt + User Input + System Reminder). Bypassable — back it with the structural controls above.
18
27
  - **Jailbreaks**: "Do this in 'DAN' mode".
19
- - *Defense*: Pattern matching for known jailbreak signatures.
28
+ - *Defense (weak pre-filter only)*: Pattern matching for known jailbreak signatures. Catches only known strings; never rely on it alone.
20
29
  - **PII Scrubbing**: Regex scan input for SSN, Credit Cards, Emails *before* sending to LLM.
21
30
 
22
31
  ## 2. Output Guardrails (Verification)
23
- - **Hallucination Check**: "Self-Consistency" (Ask 3 times, take majority).
32
+ - **Reasoning-variance reduction (NOT a factual-hallucination check)**: "Self-Consistency" (sample N times, take the majority answer) reduces *reasoning variance* on tasks with a single correct answer. It does **not** detect factual hallucination — if the model is confidently wrong, all N samples agree and the majority is still wrong. For factual grounding, use retrieval/citation checks and external verification, not self-consistency.
24
33
  - **Tone Policing**: Sentiment analysis on output. (Block Toxic/Aggressive responses).
25
34
  - **Format Validation**: Ensure JSON is valid JSON.
26
35
 
@@ -8,6 +8,7 @@ context_cost: "medium"
8
8
  # Legal Review Skill
9
9
 
10
10
  ## Goal
11
+ Perform a preliminary engineering legal-risk review — scan dependencies and code for license incompatibilities, IP/attribution issues, and other legal red flags, and surface them for human (legal) sign-off.
11
12
 
12
13
  ## Role
13
14
  You are a **Legal Compliance Bot**. You scan dependencies and code for legal risks. *Disclaimer: You are not a lawyer. This is a preliminary engineering check.*
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: reliability-engineering
3
- description: Designing failover patterns (Hot Standby, TMR), redundancy, and MTTF calculations.
3
+ description: Designing failover patterns (Hot Standby, TMR), redundancy, and MTBF/availability calculations.
4
4
  triggers: [reliability engineering]
5
5
  tags: [security]
6
- role: prod-safety-engineer, eng-arch
6
+ role: prod-safety-engineer, prod-architect
7
7
  context_cost: low
8
8
  ---
9
9
  # reliability-engineering Skill
@@ -23,7 +23,8 @@ This skill designs systems that continue to function in the presence of faults.
23
23
  - **N-Version Programming**: 3 teams write the same software in 3 languages (Python, Rust, Ada) to avoid common bugs.
24
24
 
25
25
  ## 3. Calculations
26
- - **MTBF (Mean Time Between Failures)**: Total Time / Number of Failures.
26
+ - **MTBF (Mean Time Between Failures)**: Total Time / Number of Failures. Use for **repairable** systems (the model used throughout this skill).
27
+ - **MTTF (Mean Time To Failure)**: the analogous metric for **non-repairable** components (you replace, not repair); MTBF ≈ MTTF + MTTR.
27
28
  - **Availability**: MTBF / (MTBF + MTTR). Goal: 99.999% ("Five Nines" = 5 mins downtime/year).
28
29
  - **Failure Rate ($\lambda$)**: 1 / MTBF.
29
30
 
@@ -24,7 +24,7 @@ Use this checklist during code reviews to ensure high quality.
24
24
  - [ ] **Testable**: Dependencies are injected (DI), not hardcoded.
25
25
  - [ ] **Boundary Checks**: Inputs are validated.
26
26
 
27
- ## 5. Modern Best Practices (2025)
27
+ ## 5. Modern Best Practices
28
28
  - [ ] **Immutable Default**: Prefer `const`/`final` over mutable variables.
29
29
  - [ ] **Async/Await**: properly used; no blocking main threads.
30
30
  - [ ] **Type Safety**: No `any` or loose types unless strictly necessary.
@@ -21,6 +21,13 @@ with anchored definitions so the judge (and humans during calibration) score con
21
21
 
22
22
  Weights must sum to 1.0. Weighted score = Σ(criterion_score × weight).
23
23
 
24
+ **Score normalization (canonical rule — state once, reuse everywhere):** criteria are
25
+ scored on a **1–5** scale; the **normalized** score used by automated gates is
26
+ `normalized = weighted_score / 5` (range 0–1). So a rubric threshold of `>= 4.0/5` is the
27
+ **same gate** as a harness `threshold: 0.8` (4.0 ÷ 5 = 0.8). Pick one representation per
28
+ config and note the equivalence; e.g. `coding/GOLDEN_DATASET_TEMPLATE.md` expresses the
29
+ same bar as `threshold: 0.8`.
30
+
24
31
  ## Scoring Mode
25
32
 
26
33
  - **Mode**: [pairwise — compare candidate A vs B and pick a winner | pointwise — score one output in isolation against the anchors].
@@ -62,7 +62,7 @@ tests:
62
62
  value: >
63
63
  Score the summary 1-5. It must: (a) state the customer's core problem,
64
64
  (b) omit PII, (c) be under 3 sentences. Pass only if score >= 4.
65
- threshold: 0.8 # normalized judge score required to pass
65
+ threshold: 0.8 # normalized judge score required to pass (= 4.0/5; see EVAL_RUBRIC_TEMPLATE.md normalization rule)
66
66
  ```
67
67
 
68
68
  Notes:
@@ -15,8 +15,8 @@
15
15
  | Level | Goal | Tools | Coverage Goal |
16
16
  |---|---|---|---|
17
17
  | **Static** | Catch typos & type errors | ESLint, TypeScript | 100% (Strict) |
18
- | **Unit** | Verify isolated logic | Vitest | > 99% |
19
- | **Integration** | Verify component interactions | Vitest / Supertest | Critical Paths |
18
+ | **Unit** | Verify isolated logic | Vitest | >= 99% |
19
+ | **Integration** | Verify component interactions | Vitest / Supertest | Critical Paths (~70–80%) |
20
20
  | **Contract** | Verify API consumers | Pact | All Microservices |
21
21
  | **E2E** | Verify user journeys | Playwright | Smoke Tests Only |
22
22
 
@@ -160,7 +160,35 @@ 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)
166
194
 
@@ -221,13 +249,23 @@ Check: Cyclomatic complexity < 10, no code duplication > 3 occurrences, no dead
221
249
  ```
222
250
  Write entry to agents/memory/AUDIT_LOG.md
223
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
224
254
  If this completes a SDLC phase: invoke sdlc-checkpoint.skill
225
255
  ```
226
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
+
227
261
  ---
228
262
 
229
263
  ## 6. Governance & Security
230
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
+
231
269
  ### Forbidden Actions (agents must never do these without explicit human approval)
232
270
 
233
271
  ```
@@ -280,7 +318,7 @@ PR body must include:
280
318
  ```
281
319
  Gate 1 -- Syntax/Linting: ESLint / PHP-CS-Fixer / Prettier / Ruff -- zero errors
282
320
  Gate 2 -- Type Safety: tsc --noEmit / PHPStan L9 / mypy -- zero errors
283
- 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
284
322
  Gate 4 -- Integration: Docker Compose up, API contract validation
285
323
  Gate 5 -- Security scan: npm audit / composer audit -- no critical or high CVEs
286
324
  Gate 6 -- Complexity: Cyclomatic complexity < 10 on modified files
@@ -375,6 +413,15 @@ After 5 failed attempts, agent MUST:
375
413
  4. Wait for human response before continuing
376
414
  ```
377
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
+
378
425
  ---
379
426
 
380
427
  ## 9. Human-in-the-Loop Triggers
@@ -391,6 +438,8 @@ ALWAYS pause and ask:
391
438
  - Architectural change (new service, new database, library switch)
392
439
  - Any discovered vulnerability that requires feature disablement
393
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)
394
443
  - [PLACEHOLDER: add project-specific escalation triggers]
395
444
 
396
445
  Format for human escalation:
@@ -403,6 +452,14 @@ Format for human escalation:
403
452
  Awaiting: [specific decision needed]
404
453
  ```
405
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
+
406
463
  ---
407
464
 
408
465
  ## 10. Tool-Specific Overrides
@@ -464,7 +521,11 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
464
521
 
465
522
  ## 12. References
466
523
 
467
- ### 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):**
468
529
 
469
530
  - **Search First**: Before coding, search for relevant skills:
470
531
  - **Cursor**: Check `.cursor/rules/` for `.mdc` files.
@@ -475,12 +536,12 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
475
536
 
476
537
  ```
477
538
  Project law: agents/CONSTITUTION.md
478
- Skills registry: agents/skills/00-index.md
479
- Language guides: agents/guides/
480
- Orchestrators: agents/skills/brain/README.md
481
- 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
482
541
  Templates: agents/templates/00-index.md
483
- 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
484
545
  Project memory: agents/memory/PROJECT_STATE.md
485
546
  Past failures: agents/memory/CONTINUITY.md
486
547
  Decision log: agents/memory/AUDIT_LOG.md
@@ -498,19 +559,33 @@ Every session, agents MUST:
498
559
  ```
499
560
  START of session:
500
561
  1. Read this AGENTS.md
501
- 2. Read agents/memory/PROJECT_STATE.md (if exists) -> understand current state
502
- 3. Read agents/memory/CONTINUITY.md (if exists) -> understand past failures
503
- 4. Load latest agents/memory/episodic/SESSION_SNAPSHOT/ (if exists)
504
- 5. If resuming: use session-resume.skill for full recovery
505
- 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.
506
580
 
507
581
  END of session:
508
582
  1. Update project/TASKS.md with current status of all in-progress tasks
509
583
  2. Write session summary to agents/memory/episodic/ (DECISION_LOG_TEMPLATE.md)
510
584
  3. Update agents/memory/PROJECT_STATE.md with current SDLC phase
511
585
  4. Write all decisions/outcomes to agents/memory/AUDIT_LOG.md
512
- 5. Create SDLC checkpoint if a phase was completed
513
- 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)
514
589
  ```
515
590
 
516
591
  ---
@@ -559,6 +634,24 @@ Examples:
559
634
 
560
635
  ---
561
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
+
562
655
  *Last updated: [DATE]*
563
656
  *GABBE Kit version: 1.1.0*
564
657
  *This file is maintained by the team and updated when project conventions change.*
@@ -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
@@ -12,16 +12,37 @@ not capture cost/benefit trade-offs or episodic memory.
12
12
 
13
13
  ## Decision
14
14
 
15
- Brain Mode (`gabbe/brain.py`) implements an Active-Inference / OODA control loop:
16
- Observe (read PROJECT_STATE, audit log, recent outputs) → Orient → Decide (route
17
- local vs remote via a cost-benefit router) → Act, with evolutionary prompt
18
- optimization ("genes" persisted in SQLite) and episodic memory recall. This is an
19
- **experimental** runtime: it is documented as such and gated behind explicit
20
- `gabbe brain` subcommands, never on by default.
15
+ Brain Mode (`gabbe/brain.py`) is framed conceptually as an Active-Inference / OODA
16
+ control loop, but its actual mechanism is deliberately small. Each activation:
17
+
18
+ 1. **Reads project state** — a single `GROUP BY status` count of tasks in SQLite
19
+ (the "observation"; not a read of PROJECT_STATE.md, the audit log, or recent outputs).
20
+ 2. **Selects a prompt gene** via **epsilon-greedy** (≈20% explore the newest generation,
21
+ else exploit the highest `success_rate`); genes are persisted in SQLite.
22
+ 3. **Calls the LLM** once (through the gateway, under budget/hardstop controls) to emit
23
+ a high-level action description.
24
+ 4. **Bumps `success_rate`** for the chosen gene by a fixed delta on success — a
25
+ **monotonic** increment capped at 1.0. There is no free-energy computation, no
26
+ prediction-error update, and no episodic-memory recall in this loop.
27
+
28
+ Active Inference and OODA are therefore **framing, not math**: they name the intent
29
+ (observe → choose → act → reinforce), not a literal variational free-energy implementation.
30
+ **Cost/complexity routing is a separate concern** handled by `gabbe route` (and described
31
+ conceptually in `agents/guides/ai/self-evolving-skills.md`), not inside this loop. This is
32
+ an **experimental** runtime: documented as such and gated behind explicit `gabbe brain`
33
+ subcommands, never on by default.
21
34
 
22
35
  ## Consequences
23
36
 
24
- - The cost router and budget/hardstop controls are first-class, not bolt-ons.
37
+ - The budget/hardstop controls are first-class, not bolt-ons; routing (`gabbe route`) is a
38
+ distinct, separately-invoked capability rather than a step inside the Brain loop.
25
39
  - Because it is experimental, claims in the README are marked Experimental and
26
40
  link to reproducible examples rather than implying production guarantees.
27
- - The loop is deterministic enough to be replayed (`gabbe replay`) for audit.
41
+ - **Replay is deterministic because `gabbe replay` re-emits RECORDED outputs from
42
+ checkpoints** — the live loop itself is stochastic (epsilon-greedy gene selection plus
43
+ a non-deterministic LLM call), so a fresh live run is not bit-for-bit reproducible.
44
+
45
+ > **Honesty note:** the Active-Inference / OODA description is conceptual framing for how
46
+ > the loop is organized, not a claim that `brain.py` minimizes free energy. The production
47
+ > engine is epsilon-greedy gene selection over a monotonic `success_rate` — see the same
48
+ > caveat in `agents/skills/brain/cognitive-testing.skill.md` and the brain README.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gabbe-kit",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "GABBE - Generative Architectural Brain Base Engine. A Markdown agentic engineering kit installer (Python-independent). Wires AGENTS.md, skills, and per-agent rule files into any project.",
5
5
  "keywords": [
6
6
  "agentic",