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.
- package/agents/AGENTS.md +3 -2
- package/agents/guides/00-index.md +4 -4
- package/agents/guides/ai/agent-only-cognition.md +10 -2
- package/agents/guides/ai/agent-only-swarms.md +4 -4
- package/agents/guides/ai/agent-operating-ergonomics.md +1 -1
- package/agents/guides/ai/beyond-llms.md +12 -2
- package/agents/guides/architecture/api-standards.md +9 -7
- package/agents/guides/architecture/critical-systems-arch.md +10 -4
- package/agents/guides/architecture/microservices.md +2 -2
- package/agents/guides/architecture/orchestration.md +3 -3
- package/agents/guides/architecture/systems-architecture.md +6 -0
- package/agents/guides/ops/cost-optimization.md +1 -1
- package/agents/guides/patterns/agentic-patterns.md +12 -40
- package/agents/guides/patterns/ai-native-scenarios.md +2 -2
- package/agents/guides/patterns/design-patterns.md +11 -65
- package/agents/guides/patterns/software-design-patterns.md +4 -2
- package/agents/guides/principles/clean-code-standards.md +1 -1
- package/agents/guides/principles/evaluation-strategy.md +18 -13
- package/agents/guides/principles/future-tech.md +1 -1
- package/agents/guides/principles/human-agent-collaboration.md +4 -3
- package/agents/guides/principles/legacy-tech.md +7 -3
- package/agents/guides/principles/testing-strategy.md +5 -3
- package/agents/guides/processes/loki-sdlc-phases.md +1 -1
- package/agents/guides/security/api-security.md +1 -1
- package/agents/guides/security/cryptography-standards.md +8 -2
- package/agents/guides/security/privacy-data-protection.md +2 -2
- package/agents/guides/security/secure-architecture.md +1 -1
- package/agents/skills/00-index.md +16 -16
- package/agents/skills/brain/active-inference.skill.md +1 -1
- package/agents/skills/brain/brain-mode.skill.md +9 -2
- package/agents/skills/brain/cost-benefit-router.skill.md +20 -8
- package/agents/skills/brain/loki-mode.skill.md +13 -10
- package/agents/skills/brain/sequential-thinking.skill.md +1 -1
- package/agents/skills/coding/mobile-dev.skill.md +1 -0
- package/agents/skills/coding/tdd-cycle.skill.md +1 -1
- package/agents/skills/coding/testing-strategy.skill.md +1 -1
- package/agents/skills/coding/visual-design.skill.md +1 -0
- package/agents/skills/coordination/agent-interop.skill.md +5 -4
- package/agents/skills/coordination/meta-optimize.skill.md +2 -2
- package/agents/skills/coordination/multi-agent-orch.skill.md +1 -1
- package/agents/skills/coordination/persona-selector.skill.md +1 -1
- package/agents/skills/coordination/self-optimize.skill.md +1 -1
- package/agents/skills/coordination/swarm-consensus.skill.md +10 -0
- package/agents/skills/core/audit-trail.skill.md +1 -1
- package/agents/skills/core/emerging-tech.skill.md +1 -1
- package/agents/skills/core/integrity-check.skill.md +1 -1
- package/agents/skills/core/knowledge-connect.skill.md +1 -0
- package/agents/skills/core/preflight.skill.md +8 -0
- package/agents/skills/core/sdlc-checkpoint.skill.md +7 -2
- package/agents/skills/core/self-heal.skill.md +17 -4
- package/agents/skills/core/session-resume.skill.md +8 -3
- package/agents/skills/core/state-portability.skill.md +3 -2
- package/agents/skills/ops/incident-response.skill.md +1 -0
- package/agents/skills/ops/production-health.skill.md +1 -0
- package/agents/skills/ops/release-management.skill.md +1 -0
- package/agents/skills/ops/system-benchmark.skill.md +1 -0
- package/agents/skills/product/spec-writer.skill.md +6 -3
- package/agents/skills/security/ai-safety-guardrails.skill.md +12 -3
- package/agents/skills/security/legal-review.skill.md +1 -0
- package/agents/skills/security/reliability-engineering.skill.md +4 -3
- package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +1 -1
- package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +7 -0
- package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +1 -1
- package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +2 -2
- package/agents/templates/coordination/AGENTS_TEMPLATE.md +108 -15
- package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +3 -3
- package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +1 -1
- package/agents/templates/product/PRD_TEMPLATE.md +8 -2
- package/agents/templates/product/SPEC_TEMPLATE.md +9 -3
- package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +1 -1
- package/docs/adr/0002-brain-active-inference-runtime.md +29 -8
- 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** (
|
|
64
|
+
**Unwanted Behavior** (defensive requirements — canonical `IF…THEN` form):
|
|
63
65
|
```
|
|
64
|
-
THE SYSTEM SHALL NOT store plaintext
|
|
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
|
-
- **
|
|
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
|
|
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,
|
|
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
|
|
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 |
|
|
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
|
|
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:
|
|
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
|
-
|
|
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
|
|
479
|
-
|
|
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
|
-
|
|
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/
|
|
502
|
-
3. Read agents/memory/
|
|
503
|
-
4.
|
|
504
|
-
5.
|
|
505
|
-
6.
|
|
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.
|
|
513
|
-
6.
|
|
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]/
|
|
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]% |
|
|
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
|
-
|
|
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
|
-
|
|
227
|
-
-
|
|
228
|
-
-
|
|
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
|
|
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`)
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
|
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
|
-
-
|
|
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.
|
|
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",
|