gabbe-kit 1.1.0 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -3
- 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/MCP_CONFIG_TEMPLATE.json +12 -0
- 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/FEATURES_AND_INNOVATIONS.md +208 -0
- package/docs/MCP_CONFIGURATIONS.md +44 -1
- package/docs/POST_INSTALL.md +2 -1
- package/docs/QUICK_GUIDE.md +1 -0
- package/docs/README_FULL.md +4 -2
- package/docs/ROADMAP.md +98 -0
- package/docs/adr/0002-brain-active-inference-runtime.md +29 -8
- package/docs/assets/GABBE.png +0 -0
- package/package.json +2 -1
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
|
|
2
|
+
# GABBE — Features, Value & Innovations (v1.1.1)
|
|
3
|
+
|
|
4
|
+
> **GABBE** = *Generative Architectural Brain Base Engine* — a universal, runtime-agnostic
|
|
5
|
+
> Markdown "agentic engineering kit" that turns any AI coding agent (Claude Code, Cursor,
|
|
6
|
+
> GitHub Copilot, Gemini/Antigravity, Codex, OpenCode, Zed, Continue, Roo Code, Kilo Code,
|
|
7
|
+
> Windsurf, Cline, Aider) into a **governed software-engineering team**, with an optional
|
|
8
|
+
> Python control plane for budgets, policy, audit, and MCP tooling.
|
|
9
|
+
>
|
|
10
|
+
> **At a glance (v1.1.1):** 214 skills · 86 guides · 100 templates · 36 personas · 24 runtime
|
|
11
|
+
> modules · 14 supported agents · install via `npx gabbe-kit init` / `pip install gabbe` /
|
|
12
|
+
> `curl …/install.sh | sh` / git checkout.
|
|
13
|
+
>
|
|
14
|
+
> **Honesty note (by design):** this document follows GABBE's own anti-overclaim doctrine
|
|
15
|
+
> (`agents/guides/ai/gabbe-innovations.md`). Where a capability is *framing on top of a simpler
|
|
16
|
+
> reality*, it says so. No "guaranteed", "mathematically proven", or "best-in-class" claims.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 1. What it is and why it delivers real value (short summaries)
|
|
21
|
+
|
|
22
|
+
Each line is a feature → the concrete value it delivers.
|
|
23
|
+
|
|
24
|
+
- **Runtime-agnostic Markdown kit** — the whole methodology is plain structured Markdown an
|
|
25
|
+
agent reads and follows; **no runtime lock-in**. *Value:* adopt it in whatever coding agent
|
|
26
|
+
your team already uses; nothing to host, no SDK to learn, no migration cost.
|
|
27
|
+
- **Universal "write-once, run-everywhere" skill compiler** — one source kit emits the *native*
|
|
28
|
+
format for each agent (`.cursor/rules/*.mdc`, `.claude/skills/<slug>/SKILL.md`,
|
|
29
|
+
`.github/skills/…`, `.gemini/…`, universal `.agents/skills/…`). *Value:* a single, consistent
|
|
30
|
+
engineering standard across a mixed-tool team instead of per-tool rule drift.
|
|
31
|
+
- **Cradle-to-grave ADLC** — a 14-phase lifecycle (Day-0 strategy `S00`; core build loop
|
|
32
|
+
`S01–S10`: requirements → architecture → spec → design → implement → test → review →
|
|
33
|
+
integrate → release → production; Day-2 `S11–S13`: operate → evolve → sunset). *Value:* the
|
|
34
|
+
agent is driven by an actual engineering process, not ad-hoc "vibe coding".
|
|
35
|
+
- **Human-in-the-loop gates** at `S00/S01/S02/S07/S08`. *Value:* humans stay managers, not
|
|
36
|
+
spectators — approval is required at the expensive/irreversible decision points.
|
|
37
|
+
- **Loki Mode — multi-persona "swarm"** — 36 specialized roles (architect, backend, QA,
|
|
38
|
+
security, SRE, …), each with explicit Role / Does-NOT / scope / outputs. *Value:* role
|
|
39
|
+
separation and review discipline that a single undifferentiated prompt doesn't give you.
|
|
40
|
+
- **Brain Mode — meta-cognitive planner/router** — a System-2 layer that picks the next
|
|
41
|
+
strategic action and routes work by complexity/budget, wrapping the System-1 SDLC. *Value:*
|
|
42
|
+
cheaper, more deliberate execution (don't use a frontier model or a swarm for trivial work).
|
|
43
|
+
- **Four-layer durable memory** — project state, continuity-of-failures, episodic session
|
|
44
|
+
snapshots, and an authoritative audit log, all as files on disk. *Value:* real cross-session
|
|
45
|
+
continuity; the agent stops repeating past mistakes and survives a context/crash cutoff.
|
|
46
|
+
- **Portable state export/import** — checkpoint and resume the *same* task in a *different*
|
|
47
|
+
agent/LLM. *Value:* no vendor lock-in mid-project; move work between tools freely.
|
|
48
|
+
- **Optional Python control plane (`gabbe` CLI)** — budget enforcement, fail-closed policy,
|
|
49
|
+
an MCP tool gateway, audit tracing, human escalation, and deterministic replay. *Value:* when
|
|
50
|
+
you need *enforced* (not just requested) cost/safety controls, you bolt them on without
|
|
51
|
+
changing the methodology.
|
|
52
|
+
- **Spec-driven & test-first** — EARS requirements → evals → tests → code. *Value:* specs become
|
|
53
|
+
executable contracts; less architectural drift, fewer hallucinated requirements.
|
|
54
|
+
- **Standards-grounded guardrails** — prompt-injection defense, output validation, an OWASP
|
|
55
|
+
LLM-Top-10 coverage map, and an AI-risk standards map. *Value:* security posture grounded in
|
|
56
|
+
recognized standards rather than ad-hoc rules.
|
|
57
|
+
- **Reversible, isolated install** — manifest-backed install/update/uninstall that restores the
|
|
58
|
+
pre-install state byte-for-byte (Python CLI path). *Value:* safe to try and safe to remove.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 2. What's new since `v0.8.0-beta` (the shipped delta → `v1.1.1`)
|
|
63
|
+
|
|
64
|
+
`v0.8.0-beta` was an experimental, largely single-target Markdown kit. The line below is now a
|
|
65
|
+
**published, multi-agent engineering platform** with a typed runtime, hardened security defaults,
|
|
66
|
+
universal install, release automation, and CI that catches its own drift.
|
|
67
|
+
|
|
68
|
+
**`0.9.x` — audit hardening + the operating spine**
|
|
69
|
+
- Re-scored the project on an 8-pillar audit rubric (**18/40 → ~36/40**).
|
|
70
|
+
- **Dual license** done right: Apache-2.0 (code) + CC-BY-SA-4.0 (content), SPDX headers.
|
|
71
|
+
- **MCP server made fail-closed by default** (was unauthenticated/allow-all): token + allowlist
|
|
72
|
+
required, subprocess timeout, protocol version.
|
|
73
|
+
- **Policy engine fail-closed**; **gateway fail-closed tool-argument validation** (`jsonschema`
|
|
74
|
+
now a hard dependency); audit-log redaction closure (emails/keys/tokens, incl. OTel attrs).
|
|
75
|
+
- **Operating spine** as runtime-agnostic Markdown: mandated `preflight` (Step 0), `clarify`,
|
|
76
|
+
`final-review`, continuous + pre-cutoff `state-preserve`, portable state export/import.
|
|
77
|
+
- **`gabbe/` core fully typed** (`mypy --strict` clean on core modules).
|
|
78
|
+
- Universal, Python-independent install (`npx`, `install.sh/ps1`), kit shipped in the sdist,
|
|
79
|
+
CI matrix 3.9–3.13, dependabot, **CycloneDX SBOM on release**, OpenSSF Scorecard.
|
|
80
|
+
|
|
81
|
+
**`1.0.x` — v1.0 release + registry publishing**
|
|
82
|
+
- **v1.0.0**: cradle-to-grave ADLC, evals + standards-grounded guardrails, advanced testing,
|
|
83
|
+
one-command multi-OS install with autodetect + `gabbe doctor`.
|
|
84
|
+
- **Registry publishing went live**: **npm `gabbe-kit`** (`npx gabbe-kit init`) and **PyPI
|
|
85
|
+
`gabbe`** (`pip install gabbe`); a `vX.Y.Z` tag drives `release.yml` → npm + PyPI + GitHub
|
|
86
|
+
Release (wheel, sdist, npm tgz, kit tarball, SBOM) + a multi-OS post-publish verify.
|
|
87
|
+
- Install-doc accuracy + a bootstrap-script fix so `curl …/install.sh | sh` works end-to-end.
|
|
88
|
+
- MCP `serverInfo` version now tracks the package (no drift); kit-version stamps refreshed.
|
|
89
|
+
|
|
90
|
+
**`1.1.x` — install safety, brownfield mode, and a content audit**
|
|
91
|
+
- **Never-clobber install**: both install paths back up any differing pre-existing file before
|
|
92
|
+
refreshing it; a `--force` flag opts into re-templating preserve-set files.
|
|
93
|
+
- **Reversible wizard installs**: everything created is recorded in `.gabbe/manifest.json`, so
|
|
94
|
+
`gabbe uninstall` fully reverses an install and restores backed-up files.
|
|
95
|
+
- **Brownfield autodetect + refactor mode**: sniffs an existing codebase
|
|
96
|
+
(language/framework/package-manager/git) and offers greenfield-vs-refactor.
|
|
97
|
+
- **Fuller population**: the wizard fills more `AGENTS.md` fields, tags OPTIONAL, warns on
|
|
98
|
+
unfilled placeholders. Broader test coverage (MCP stdio e2e, wheel-install sandbox, wizard
|
|
99
|
+
snapshot, mermaid validation).
|
|
100
|
+
- **v1.1.1 — capability-layer content audit**: a deep semantic/structural pass unified the SDLC
|
|
101
|
+
phase model and HITL gate set across the whole kit, re-synced `AGENTS_TEMPLATE.md` to the live
|
|
102
|
+
spine, de-duplicated overlapping guides, corrected the Brain/Active-Inference docs to match the
|
|
103
|
+
*actual* code (and removed overclaim superlatives), and fixed security/crypto accuracy items.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 3. What's distinctive — "world-first / unlike what else exists"
|
|
108
|
+
|
|
109
|
+
Framed honestly against the 2026 landscape. These are **distinctive combinations** where we are
|
|
110
|
+
not aware of a direct equivalent — *not* bald "world-first" claims. Where the broader market
|
|
111
|
+
already does something, it's noted.
|
|
112
|
+
|
|
113
|
+
1. **A universal *skill compiler* across 14 agents, not a single-agent rule set.** The market has
|
|
114
|
+
plenty of per-agent rule files (`CLAUDE.md`, `.cursor/rules`, Copilot instructions) and curated
|
|
115
|
+
rule packs; **AGENTS.md** itself is now a Linux-Foundation standard. GABBE is unusual in
|
|
116
|
+
*compiling one source kit into each agent's native format* — so a mixed-tool team shares one
|
|
117
|
+
engineering standard. *Distinctive: the breadth (14 targets) + an `agentskills.io` registry
|
|
118
|
+
import/export for sharing skills.*
|
|
119
|
+
|
|
120
|
+
2. **A methodology kit, not a runtime framework.** MetaGPT, CrewAI, AutoGen, LangGraph, OpenHands
|
|
121
|
+
are Python frameworks you *build agents with*. GABBE is a portable Markdown methodology that
|
|
122
|
+
*drops into the agent you already use* — zero hosting, zero SDK. The role-based "software
|
|
123
|
+
company" idea overlaps with MetaGPT/CrewAI, but those require their runtime; GABBE's 36-persona
|
|
124
|
+
swarm is followed by whatever agent reads the kit.
|
|
125
|
+
|
|
126
|
+
3. **Whole-lifecycle, not just spec→code.** Spec-driven tools (GitHub Spec Kit, Kiro, BMAD,
|
|
127
|
+
OpenSpec) center on spec → plan → tasks → implement. GABBE includes that (EARS, spec→evals→
|
|
128
|
+
test→code) **but extends to Day-0 strategy and Day-2 operate/evolve/sunset**, plus memory,
|
|
129
|
+
governance, and self-improvement in one kit. Most competitors solve a single slice.
|
|
130
|
+
|
|
131
|
+
4. **Methodology *and* an optional enforcement runtime, cleanly separated.** Tools are usually
|
|
132
|
+
either a methodology (docs/specs) *or* a runtime (a framework). GABBE ships both: the Markdown
|
|
133
|
+
works alone, and the optional `gabbe` CLI turns "asked-to" conventions (budget, policy,
|
|
134
|
+
tool-allowlist, hard stops) into *fail-closed enforced* controls via an MCP gateway with audit
|
|
135
|
+
tracing and deterministic replay.
|
|
136
|
+
|
|
137
|
+
5. **A real (if modest) self-improving prompt loop, described honestly.** `gabbe/brain.py` runs
|
|
138
|
+
an **epsilon-greedy bandit over prompt "genes" with LLM-driven mutation and a success-rate
|
|
139
|
+
reward** (Evolutionary Prompt Optimization). What's distinctive isn't the algorithm (it's
|
|
140
|
+
simple) but the **discipline of shipping it with an explicit honesty doc** that separates the
|
|
141
|
+
working loop from the "Active Inference / free energy" *framing* (which is wording, not computed
|
|
142
|
+
math). Truth-in-advertising as a design value is itself rare in this space.
|
|
143
|
+
|
|
144
|
+
> **Caveat (read with §1).** "Works in any agent" and "swarm" depend on the host agent honoring
|
|
145
|
+
> the Markdown; in a pure-Markdown runtime the gates/budgets are strong instructions, not
|
|
146
|
+
> environment-imposed guarantees — that's exactly when the optional `gabbe` CLI is worth adding.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## 4. Full feature catalog (everything else)
|
|
151
|
+
|
|
152
|
+
**Methodology & content layer**
|
|
153
|
+
- 214 skills (packaged workflows w/ triggers + constraints), 86 guides (language/domain/principles
|
|
154
|
+
expertise), 100 templates (PRD, SPEC, NFR, ADR, C4, test/eval plans, runbooks, …), 36 personas.
|
|
155
|
+
- Operating spine: `preflight` (Step 0) → `clarify` → plan → TDD (red/green) → `verify` →
|
|
156
|
+
refactor → log/complete, with a mandated final review.
|
|
157
|
+
- Index + frontmatter conventions make skills discoverable and auto-selectable by keyword.
|
|
158
|
+
|
|
159
|
+
**Cognition & orchestration**
|
|
160
|
+
- **Brain Mode** (System 2): meta-cognitive planning, complexity/budget routing (`gabbe route`,
|
|
161
|
+
LOCAL vs REMOTE), epsilon-greedy prompt optimization, self-optimization (autonomy L0–L3 via
|
|
162
|
+
`GABBE_AUTONOMY = ask|auto|hybrid`).
|
|
163
|
+
- **Loki Mode** (System 1): the 14-phase SDLC state machine with persona handoffs, per-phase
|
|
164
|
+
checkpoints, quality gates, and human-approval gates.
|
|
165
|
+
- Dynamic capability loading (load-or-ask), persona selector, swarm consensus/voting.
|
|
166
|
+
|
|
167
|
+
**Memory & continuity**
|
|
168
|
+
- Four layers: `PROJECT_STATE.md`, `CONTINUITY.md`, episodic `SESSION_SNAPSHOT`s, `AUDIT_LOG.md`.
|
|
169
|
+
- `RESUME_POINTER` continuous + pre-cutoff checkpointing; portable state export/import across
|
|
170
|
+
agents/LLMs; recency/relevance retrieval policy.
|
|
171
|
+
|
|
172
|
+
**Platform / control plane (optional `gabbe` CLI, 24 modules)**
|
|
173
|
+
- Budget enforcement (`can_afford()` / `reserve()` pre-step reservation); fail-closed policy
|
|
174
|
+
engine; MCP tool gateway (token + allowlist + arg-schema validation + subprocess timeout);
|
|
175
|
+
audit tracing (OpenTelemetry GenAI semantic conventions, redact-by-default); human escalation;
|
|
176
|
+
deterministic replay; run history; `gabbe doctor` environment report; `gabbe verify --chaos`
|
|
177
|
+
fault-injection self-checks.
|
|
178
|
+
- Registry interop: `registry_export`/`registry_import` (agentskills.io), `gabbe registry
|
|
179
|
+
publish|add`, `gabbe setup`.
|
|
180
|
+
|
|
181
|
+
**Quality, security & release engineering**
|
|
182
|
+
- Self-* demonstrated by tests: self-evolving (gene generations), self-adaptive (PII→LOCAL /
|
|
183
|
+
complexity routing), self-healing (chaos escalation/hard-stop).
|
|
184
|
+
- Guardrails: prompt-injection defense, output validation, OWASP LLM01–LLM10 coverage map,
|
|
185
|
+
AI-risk standards map; secrets policy; redaction.
|
|
186
|
+
- Six backward-compat gates (API surface, CLI `--help` byte-equal, config schema, DB schema,
|
|
187
|
+
emitter golden vault, CVE delta) + golden emitter vault per agent; eval harness
|
|
188
|
+
(assertions-only per-commit; live LLM-as-judge nightly).
|
|
189
|
+
- Supply chain: CycloneDX 1.6 SBOM on release, OpenSSF Scorecard, OSV/Trivy/pip-audit, dependabot,
|
|
190
|
+
`requirements-lock.txt`, CI matrix Python 3.9–3.13 on {Linux, macOS, Windows}.
|
|
191
|
+
|
|
192
|
+
**Install & distribution**
|
|
193
|
+
- Channels: `npx gabbe-kit init` (Python-independent), `pip install gabbe` / `pipx` / `uvx`,
|
|
194
|
+
`curl …/install.sh | sh`, `git clone` + `python3 scripts/init.py`.
|
|
195
|
+
- Scopes: project / `--global` / `--dir`; never-clobber with `.gabbe-bak` backups + `--force`;
|
|
196
|
+
manifest-backed reversible `update` / `uninstall`; multi-OS post-publish verify.
|
|
197
|
+
- 14 target agents incl. universal `.agents/skills/` for any agentskills.io-compatible tool.
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Sources (competitive landscape)
|
|
202
|
+
|
|
203
|
+
- AGENTS.md as an open/Linux-Foundation standard — [deployhq guide](https://www.deployhq.com/blog/ai-coding-config-files-guide), [AGENTS.md vs CLAUDE.md vs Cursor Rules (2026)](https://codersera.com/blog/agents-md-vs-claude-md-vs-cursor-rules-comparison-2026/)
|
|
204
|
+
- Multi-agent SWE frameworks — [MetaGPT](https://github.com/FoundationAgents/MetaGPT), [framework comparison 2026](https://openagents.org/blog/posts/2026-02-23-open-source-ai-agent-frameworks-compared)
|
|
205
|
+
- Spec-driven development — [GitHub Spec Kit](https://github.github.com/spec-kit/), [Kiro](https://kiro.dev/), [Martin Fowler: SDD tools](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
|
|
206
|
+
- GABBE internal honesty inventory — `agents/guides/ai/gabbe-innovations.md`, `agents/guides/ai/self-evolving-skills.md`
|
|
207
|
+
|
|
208
|
+
_Compiled 2026-06-19 for GABBE v1.1.1. Feature counts verified against the repo; novelty framed honestly per GABBE's own anti-overclaim doctrine._
|
|
@@ -216,6 +216,49 @@ PR review, code search, issue management, and git history.
|
|
|
216
216
|
|
|
217
217
|
---
|
|
218
218
|
|
|
219
|
+
### GitHits
|
|
220
|
+
|
|
221
|
+
Lets the agent **navigate the open-source code your app depends on**. Your agent can already read your local codebase; GitHits extends that reach to your dependencies — searching, grepping, and reading source, docs, issues, PRs, and changelogs of packages **without cloning them locally**. Acts like Context7 for dependency *source code* (not just SDK docs), preventing the agent from hallucinating a dependency's API or upgrade behaviour.
|
|
222
|
+
|
|
223
|
+
| Property | Value |
|
|
224
|
+
|---|---|
|
|
225
|
+
| **Package** | `githits` (npm) |
|
|
226
|
+
| **Website** | [githits.com](https://githits.com) · [docs.githits.com](https://docs.githits.com/) |
|
|
227
|
+
| **API Key** | None required |
|
|
228
|
+
| **GABBE Skill** | `research.skill`, `coding/code-review.skill`, `security/dependency-security.skill` |
|
|
229
|
+
|
|
230
|
+
**Capabilities:** code examples (real implementation patterns from repos/issues/discussions/PRs of your deps), code navigation (dependency search, source grep, package-path resolution, line-range reads), documentation access (hosted + repo-backed package docs), and package inspection (metadata, vulnerabilities, changelogs, upgrade context).
|
|
231
|
+
|
|
232
|
+
**Install (automatic — recommended):**
|
|
233
|
+
```bash
|
|
234
|
+
# Detects your tool (Claude Code, Cursor, VS Code/Copilot, Windsurf, Cline,
|
|
235
|
+
# Claude Desktop, Codex CLI, Gemini CLI, OpenCode, …) and wires up the MCP server.
|
|
236
|
+
npx githits@latest init
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
**Config (manual — universal stdio entry):**
|
|
240
|
+
```json
|
|
241
|
+
{
|
|
242
|
+
"githits": {
|
|
243
|
+
"command": "npx",
|
|
244
|
+
"args": ["-y", "githits@latest", "mcp", "start"],
|
|
245
|
+
"env": {}
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
> [!NOTE]
|
|
251
|
+
> The server runs as a local stdio subprocess — no background service, global install, env vars, or remote HTTP URL required. For tools not auto-detected, add the manual config above and restart, then confirm `githits` shows as a connected server. See [docs.githits.com/installation/manual-setup](https://docs.githits.com/installation/manual-setup).
|
|
252
|
+
|
|
253
|
+
**Usage:**
|
|
254
|
+
```
|
|
255
|
+
> "Use GitHits to find how `fastapi` implements dependency injection in its source."
|
|
256
|
+
> "Read the changelog and breaking changes for the `pydantic` v1 → v2 upgrade."
|
|
257
|
+
> "Grep the `react` dependency source for how `useEffect` cleanup is scheduled."
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
219
262
|
### GitLab
|
|
220
263
|
|
|
221
264
|
GitLab alternative to the GitHub MCP. Same capabilities for GitLab-hosted repos.
|
|
@@ -1753,7 +1796,7 @@ credentials never leave the host. Servers marked **(new in v1.0)** were added to
|
|
|
1753
1796
|
| SWEBOK area | Priority MCP servers | GABBE tie-in |
|
|
1754
1797
|
|---|---|---|
|
|
1755
1798
|
| **Requirements & Design** | `figma`, `notion`, `obsidian` (new), `knowledge-graph-memory` (new) | S00–S03; `knowledge-connect.skill`, ADR/spec search; persistent semantic memory prevents architectural-decision drift |
|
|
1756
|
-
| **Construction & Architecture** | `github`, `supabase` (new), `postgres-dev`/`postgres-prod`, `mongodb`, `aws-core`, `azure`, `kubernetes`, `docker` | S05; direct schema/query execution instead of guessed SQL |
|
|
1799
|
+
| **Construction & Architecture** | `github`, `githits` (new), `supabase` (new), `postgres-dev`/`postgres-prod`, `mongodb`, `aws-core`, `azure`, `kubernetes`, `docker` | S05; direct schema/query execution instead of guessed SQL; `githits` reads dependency source/docs so the agent doesn't guess third-party APIs |
|
|
1757
1800
|
| **Testing & Quality** | `sentry`, `snyk`, `semgrep`, `mcp-evals` (new), `mcp-chaos-rig` (new) | S06–S07; `mcp-evals` ↔ `eval-driven-development.skill`; `mcp-chaos-rig` ↔ `chaos-fault-injection.skill` + `gabbe verify --chaos` |
|
|
1758
1801
|
| **Maintenance & Config Mgmt** | `pagerduty` (new), `cloudflare` (new), `vercel`, `gitlab` | S11–S13 Day-2; on-call automation, edge deploy logs |
|
|
1759
1802
|
| **Eng. Management & Economics** | `linear`, `jira`, `confluence`, `slack`, `discord` (new), `stripe` | management + software economics; comms triage, billing/churn |
|
package/docs/POST_INSTALL.md
CHANGED
|
@@ -14,7 +14,7 @@ All agent clients GABBE detected are already wired. Anything missing is reported
|
|
|
14
14
|
|
|
15
15
|
## 2. Enable MCP servers (the main post-install task)
|
|
16
16
|
|
|
17
|
-
GABBE ships a catalog of **
|
|
17
|
+
GABBE ships a catalog of **66 MCP servers** in
|
|
18
18
|
`agents/templates/core/MCP_CONFIG_TEMPLATE.json`. Most are opt-in (`"_enabled": false`).
|
|
19
19
|
To enable one: set `"_enabled": true`, fill the listed env vars, and point your agent
|
|
20
20
|
at the config (e.g. `.mcp.json`, `.cursor/mcp.json`, or your client's MCP settings).
|
|
@@ -27,6 +27,7 @@ at the config (e.g. `.mcp.json`, `.cursor/mcp.json`, or your client's MCP settin
|
|
|
27
27
|
| `filesystem` | Read-only project file access (internal RAG) | npx; set root path |
|
|
28
28
|
| `sequential-thinking` | Chain-of-thought reasoning | npx; no key |
|
|
29
29
|
| `github` | PR review, code search, issue mgmt | npx; `GITHUB_TOKEN` |
|
|
30
|
+
| `githits` | Navigate open-source dependency source/docs (no clone) | npx; no key (`npx githits@latest init`) |
|
|
30
31
|
| `brave-search` or `tavily` | Authoritative web research | npx; API key |
|
|
31
32
|
|
|
32
33
|
### Locally-installed servers (clone/build/binary, not a plain npx one-liner)
|
package/docs/QUICK_GUIDE.md
CHANGED
|
@@ -681,6 +681,7 @@ Actions:
|
|
|
681
681
|
| **Context-7** | `npx @context7/mcp-server` | Up-to-date SDK docs (prevents API hallucination) |
|
|
682
682
|
| **Sequential Thinking** | `npx @modelcontextprotocol/server-sequential-thinking` | Chain-of-thought before acting |
|
|
683
683
|
| **GitHub MCP** | `npx @modelcontextprotocol/server-github` | PR review, issues, code search |
|
|
684
|
+
| **GitHits** | `npx githits@latest init` | Navigate open-source dependency source/docs (no clone, no key) |
|
|
684
685
|
| **PostgreSQL MCP** | `npx @modelcontextprotocol/server-postgres` | Live schema introspection |
|
|
685
686
|
| **Semgrep MCP** | `pip install semgrep-mcp` | In-agent SAST security scanning |
|
|
686
687
|
| **Brave Search MCP** | `npx @modelcontextprotocol/server-brave-search` | Authoritative web research |
|
package/docs/README_FULL.md
CHANGED
|
@@ -19,7 +19,7 @@ It contains:
|
|
|
19
19
|
- **100 Templates** (standardized documents)
|
|
20
20
|
- **86 Guides** (language & domain expertise)
|
|
21
21
|
- **36 Personas** (specialized roles)
|
|
22
|
-
- **
|
|
22
|
+
- **66 MCP servers** (configuration and guides for AI tools)
|
|
23
23
|
- **Brain Mode** (meta-cognitive orchestration)
|
|
24
24
|
- **Loki Mode** (multi-agent swarm engineering personas team for large projects)
|
|
25
25
|
|
|
@@ -1158,6 +1158,7 @@ MCP (Model Context Protocol) servers extend agent capabilities. Configure them i
|
|
|
1158
1158
|
| **Docs** | Context-7 MCP | Up-to-date SDK docs (prevents API hallucination) |
|
|
1159
1159
|
| **Reasoning** | Sequential Thinking | Chain-of-thought before acting |
|
|
1160
1160
|
| **Code Search** | GitHub MCP | PR review, code search, issue management |
|
|
1161
|
+
| **Dependencies** | GitHits MCP | Navigate open-source dependency source/docs (no clone, no key) |
|
|
1161
1162
|
| **Database** | PostgreSQL MCP | Live schema introspection |
|
|
1162
1163
|
| **Security** | Semgrep MCP | SAST scanning from within the agent |
|
|
1163
1164
|
| **Web Search** | Brave Search / Tavily | Authoritative source research |
|
|
@@ -1170,7 +1171,7 @@ MCP (Model Context Protocol) servers extend agent capabilities. Configure them i
|
|
|
1170
1171
|
| **Canvas** | tldraw MCP | Persistent visual canvas for wireframing |
|
|
1171
1172
|
| **Filesystem** | Filesystem MCP | Local file access for internal RAG |
|
|
1172
1173
|
|
|
1173
|
-
**Full coverage matrix** (
|
|
1174
|
+
**Full coverage matrix** (66 MCP servers in `MCP_CONFIG_TEMPLATE.json`):
|
|
1174
1175
|
|
|
1175
1176
|
| Integration Domain | Servers Available |
|
|
1176
1177
|
|---|---|
|
|
@@ -1182,6 +1183,7 @@ MCP (Model Context Protocol) servers extend agent capabilities. Configure them i
|
|
|
1182
1183
|
| **Observability** | Sentry, Datadog, Grafana |
|
|
1183
1184
|
| **Code Quality** | Semgrep, Snyk, SonarQube, Gitleaks, Time Complexity |
|
|
1184
1185
|
| **Project Mgmt** | GitHub, GitLab, Jira, Linear, Notion, Confluence, Slack |
|
|
1186
|
+
| **Dependencies** | GitHits (navigate open-source dependency source, docs, issues, changelogs) |
|
|
1185
1187
|
| **Cloud/Infra** | AWS Core, Kubernetes, Figma |
|
|
1186
1188
|
|
|
1187
1189
|
**Security rules:**
|
package/docs/ROADMAP.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# GABBE roadmap
|
|
2
|
+
|
|
3
|
+
What is planned after 1.1.1, in the order it should be built. Nothing here ships until it is written, tested and released; the [CHANGELOG](../CHANGELOG.md) records what did.
|
|
4
|
+
|
|
5
|
+
## 1. Agent hooks
|
|
6
|
+
|
|
7
|
+
### The decision
|
|
8
|
+
|
|
9
|
+
GABBE stays a context kit that works with any agent, so hooks are **not required** to use it. It will ship one small, **off-by-default** hook set for the agents that support hooks, because four of its rules are broken in practice when they rest on the agent's reading alone, and a hook can enforce each of those four at the tool-call boundary.
|
|
10
|
+
|
|
11
|
+
### What enforces each rule today, and what a hook could add
|
|
12
|
+
|
|
13
|
+
Today almost every gate and rule in the kit is enforced only by the agent reading Markdown. The Python CLI's controls (budget, hard stop, policy, tool gateway, escalation) wrap `gabbe brain activate` and `gabbe serve-mcp`, so they never see a coding agent's file edits, git commands or phase changes.
|
|
14
|
+
|
|
15
|
+
| Rule | Enforced today by | A hook can add |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| The agent never commits, pushes, tags, publishes or deploys unless told to in that request | prose (AGENTS.md, CONSTITUTION Article XIII) | a block on the git and publish commands before they run |
|
|
18
|
+
| Protected files (the constitution, AGENTS.md, golden baselines, lockfiles, CI) are not edited | prose; `protected_files` in `project/gabbe.config.json` is read by no code | a block on edits to the configured globs |
|
|
19
|
+
| Checks run on the final tree before work is reported as done | prose (Step 7 of the operating spine) | a refusal to end the turn when files changed after the last green run |
|
|
20
|
+
| The session is recorded in memory before it ends | prose (AGENTS.md section 13) | a refusal to end the turn after edits when no memory file was updated; the resume pointer injected at session start |
|
|
21
|
+
| S00–S13 gates, human approvals, the orch-judge veto | prose; `gabbe status` reads a phase that no command writes | nothing reliable: a hook sees tool calls, not whether a gate was earned |
|
|
22
|
+
| Ask before deciding, additive edits to authored prose, research before claims, numbers re-run before quoting | prose | nothing: these are judgements, not tool calls |
|
|
23
|
+
| The project's tests, lint and security scan pass | the project's CI and `gabbe verify` (human-run) | the Stop check above runs the same commands |
|
|
24
|
+
|
|
25
|
+
### The planned hook set
|
|
26
|
+
|
|
27
|
+
One zero-dependency Node script, `agents/hooks/gabbe-hooks.js`, with templates the installer merges into a project when asked with `npx gabbe-kit init --hooks`. Without that flag nothing is written. Node is used because the installer already needs it and hooks must also run on Windows.
|
|
28
|
+
|
|
29
|
+
| Event | Matcher | Command | Purpose | When it fails or is absent |
|
|
30
|
+
|---|---|---|---|---|
|
|
31
|
+
| `PreToolUse` | `Bash` | `node agents/hooks/gabbe-hooks.js guard-bash` | denies git writes (`commit`, `push`, `tag`, `merge`, `rebase`, `reset --hard`, `clean -f`, `--no-verify`, `config core.hooksPath`), `gh pr merge`/`release`/`repo create`, package publishes and deploy commands, including `git -C <dir>` and `cd x && git …` forms; denies shell writes that name a protected path | fails closed on unreadable input; a timeout is treated by the host as non-blocking |
|
|
32
|
+
| `PreToolUse` | `Edit\|Write\|MultiEdit\|NotebookEdit` | `… guard-edit` | denies edits to `protected_files` (or the kit defaults) and to the hook files and their state | fails closed |
|
|
33
|
+
| `PostToolUse` | `Edit\|Write\|MultiEdit\|NotebookEdit\|Bash` | `… ledger` | records that this session changed files, so read-only sessions never meet the Stop check | never blocks |
|
|
34
|
+
| `Stop` | every stop | `… stop` | after edits, refuses to end the turn when the tree differs from the tree the last green `gate` run saw, or when no memory file was updated since the first edit; tells the agent what to run | fails open; at most three refusals per session, then a warning, so a session whose tests cannot pass is never trapped |
|
|
35
|
+
| `SessionStart` | `startup\|resume\|clear` | `… session-start` | prints the first lines of the resume pointer and the date of the last green gate into the session | cannot block |
|
|
36
|
+
| (a command) | — | `… gate` | the only writer of the green stamp: runs `hooks.gate_command`, or the test, lint and security-scan commands of the AGENTS.md Commands section, and records the tree hash on success | exit 1 and no stamp when a command fails |
|
|
37
|
+
|
|
38
|
+
Escape hatches live where the agent's shell cannot reach them: environment variables of the host process (`GABBE_HOOKS_OFF=1`, `GABBE_ALLOW_GIT_WRITE=1`, `GABBE_UNLOCK=<globs>`), and a one-shot written authorization of one exact command line, consumed when used.
|
|
39
|
+
|
|
40
|
+
A second, script-free layer ships in the same Claude Code template: `permissions.deny` entries for `Bash(git commit *)`, `Bash(git push *)` and edits of the constitution, which Claude Code enforces without running any hook.
|
|
41
|
+
|
|
42
|
+
**Claude Code** (`.claude/settings.json`, merged, never overwritten):
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"permissions": { "deny": ["Bash(git commit *)", "Bash(git push *)", "Bash(git tag *)", "Edit(agents/CONSTITUTION.md)"] },
|
|
47
|
+
"hooks": {
|
|
48
|
+
"PreToolUse": [
|
|
49
|
+
{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "node agents/hooks/gabbe-hooks.js guard-bash", "timeout": 10 }] },
|
|
50
|
+
{ "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [{ "type": "command", "command": "node agents/hooks/gabbe-hooks.js guard-edit", "timeout": 10 }] }
|
|
51
|
+
],
|
|
52
|
+
"PostToolUse": [
|
|
53
|
+
{ "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash", "hooks": [{ "type": "command", "command": "node agents/hooks/gabbe-hooks.js ledger", "timeout": 10 }] }
|
|
54
|
+
],
|
|
55
|
+
"Stop": [{ "hooks": [{ "type": "command", "command": "node agents/hooks/gabbe-hooks.js stop", "timeout": 30 }] }],
|
|
56
|
+
"SessionStart": [{ "matcher": "startup|resume|clear", "hooks": [{ "type": "command", "command": "node agents/hooks/gabbe-hooks.js session-start", "timeout": 10 }] }]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**Other agents.** Check each against its current documentation when the work starts, because these surfaces change often.
|
|
62
|
+
|
|
63
|
+
| Agent | What it gets |
|
|
64
|
+
|---|---|
|
|
65
|
+
| Cursor | `.cursor/hooks.json`: `beforeShellExecution` runs the shell guard; `afterFileEdit` records edits and reports a protected-file edit after the fact. Cursor has no pre-edit block and no blocking stop, so the last two rules are warnings there. |
|
|
66
|
+
| Gemini CLI, GitHub Copilot (CLI and coding agent), OpenCode, Windsurf | each has a hook or plugin surface; the installer prints a note naming it, and wiring follows once verified |
|
|
67
|
+
| Codex, Aider, Cline, Roo Code, Kilo Code, Zed, Continue, Devin, Antigravity | prose, plus the git-side guard below; for Aider the installer also sets `auto-commits: false` |
|
|
68
|
+
| every agent | `.githooks/pre-commit` and `pre-push` (POSIX sh), copied but not activated: a commit or push passes only from a shell that carries `GABBE_HUMAN_COMMIT=1`, staged protected files are refused, and the staged tree must match the green stamp when one exists. Activating them (`git config core.hooksPath .githooks`) is the project owner's choice. |
|
|
69
|
+
|
|
70
|
+
The forge stays the final layer for every agent: a required CI check on the default branch blocks an unchecked change whichever agent produced it.
|
|
71
|
+
|
|
72
|
+
### Honest limits
|
|
73
|
+
|
|
74
|
+
- A hook sees tool calls, not intent. Gates earned, judgements, claims and additive editing stay prose.
|
|
75
|
+
- A determined agent can write a script and run it. The set closes the mistakes agents actually make, such as misreading an authorization, skipping a re-run of the checks or forgetting the memory update, and leaves every evasion visible in the transcript and the hook log.
|
|
76
|
+
- The Stop check also fires after a clarifying question that follows edits; the three-refusal cap keeps that from trapping a session.
|
|
77
|
+
|
|
78
|
+
### Files and changes
|
|
79
|
+
|
|
80
|
+
- Add `agents/hooks/gabbe-hooks.js`, `agents/hooks/claude-settings.template.json`, `agents/hooks/cursor-hooks.template.json`, `agents/hooks/githooks/pre-commit`, `agents/hooks/githooks/pre-push` and `agents/hooks/README.md` (one table: rule, hook, enforced, still prose).
|
|
81
|
+
- `bin/install.js`: a `--hooks` flag that merges the templates (union of `permissions.deny`; a hook group added per event only when its command is not already there).
|
|
82
|
+
- `scripts/init.py`: a wizard question, default No, so the emitter vault of Gate 4 is unchanged.
|
|
83
|
+
- `project/gabbe.config.json` schema: `hooks.gate_command`, `hooks.memory_files`, `hooks.resume_lines` (documented in `docs/SCHEMA.md`, additive only, Gate 3).
|
|
84
|
+
- Correct the two lines that promise enforcement that does not exist today: AGENTS.md section 10 ("Hooks: Check .claude/settings.json…") and the git-workflow skill ("The workflow script MUST intercept…"). Both become true only with `--hooks`; say so. Editing AGENTS.md needs a golden-baseline recapture for Gate 4.
|
|
85
|
+
|
|
86
|
+
### Tests
|
|
87
|
+
|
|
88
|
+
- `scripts/tests/test_hooks.js` (zero dependencies, throwaway git repositories): read-only git allowed; every denied write and publish form denied; protected and hook-state writes denied while reads pass; the one-shot authorization consumed; the environment escape hatches; fail-closed on empty and malformed input; the Stop sequence (silent without edits, blocks, `gate`, blocks on memory, passes, blocks again after a later edit, stops blocking after three); `gate` refuses a failing command and placeholders; `session-start` resets the ledger; a kit installed under a subfolder.
|
|
89
|
+
- Three installer tests for `--hooks` in `scripts/tests/test_node_install.js`, run on all three operating systems in CI.
|
|
90
|
+
|
|
91
|
+
### Considered and not chosen
|
|
92
|
+
|
|
93
|
+
- **No hooks at all.** One enforcement story for every agent and nothing to maintain against changing hook formats, but the four rules above would stay unenforced inside the session and be caught only afterwards by CI, if at all. It also leaves the two lines that promise enforcement untrue.
|
|
94
|
+
- **A full hook layer.** Every S00–S13 gate and every policy enforced through hooks and the Python gateway, with a phase ledger. It cannot enforce what matters most in a gate, which is whether the work earned it, and it would bind the kit to the hook formats of many agents. The cost in size and portability is out of proportion to what it adds over the planned set.
|
|
95
|
+
|
|
96
|
+
## 2. `gabbe verify` exit code
|
|
97
|
+
|
|
98
|
+
`gabbe verify` prints "Verification FAILED" and still exits 0 (`gabbe/main.py` ignores the result of `run_verification()`; only `--chaos` exits 1). Anyone who runs it in CI, as the full guide suggests, gets a green job on a failed check. Fix: exit 1 when the verification fails, with a test. This is independent of the hooks and comes first.
|
|
@@ -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/docs/assets/GABBE.png
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gabbe-kit",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.2",
|
|
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",
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"bin/",
|
|
37
37
|
"agents/",
|
|
38
38
|
"docs/",
|
|
39
|
+
"!docs/assets/claude-plugin-icon.png",
|
|
39
40
|
"scripts/init.py",
|
|
40
41
|
"install.sh",
|
|
41
42
|
"install.ps1",
|