gabbe-kit 1.1.1 → 1.1.3

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.
@@ -0,0 +1,165 @@
1
+ # GABBE architecture
2
+
3
+ > **Audience:** contributors and maintainers. **Scope:** the parts of this repository, what
4
+ > each one reads and writes, and how they connect. The reasons behind the larger decisions
5
+ > are in [`docs/adr/`](adr/); the emitted file formats are in [SCHEMA.md](SCHEMA.md).
6
+
7
+ GABBE has two layers. The **kit** (`agents/`) is Markdown that a coding agent reads; it works
8
+ with no code running. Installers copy the kit into a project and compile its skills into
9
+ each agent's native format. The optional **CLI** (`gabbe/`, Python) adds enforced budgets,
10
+ policy, audit, an MCP server and replay on top of a project's SQLite state.
11
+
12
+ ## Context
13
+
14
+ ```mermaid
15
+ flowchart LR
16
+ dev["Developer"]
17
+ agent["AI coding agent<br/>(Claude Code, Cursor, Copilot, Gemini, Codex, …)"]
18
+ mcpc["MCP client"]
19
+ llm["OpenAI-compatible LLM API<br/>(GABBE_API_URL)"]
20
+ reg["npm · PyPI · GitHub Packages<br/>GitHub Releases"]
21
+ subgraph gabbe["This repository"]
22
+ kit["Markdown kit<br/>agents/"]
23
+ inst["Installers<br/>bin/install.js · install.sh · scripts/init.py"]
24
+ cli["Optional CLI<br/>gabbe/"]
25
+ end
26
+ proj[("User project<br/>agents/ · AGENTS.md · .claude/ · .cursor/ …<br/>project/state.db")]
27
+
28
+ dev -->|npx gabbe-kit init / curl install.sh / init.py| inst
29
+ inst -->|copies kit, emits per-agent files| proj
30
+ kit --> inst
31
+ agent -->|reads AGENTS.md, skills| proj
32
+ dev -->|gabbe …| cli
33
+ cli -->|reads and writes| proj
34
+ cli -->|HTTPS| llm
35
+ mcpc -->|JSON-RPC over stdio| cli
36
+ gabbe -->|v* tag workflows| reg
37
+ ```
38
+
39
+ ## Parts of the repository
40
+
41
+ ```mermaid
42
+ flowchart TB
43
+ subgraph content["Kit content (agents/)"]
44
+ skills["skills/ · templates/ · guides/<br/>personas/ · memory/"]
45
+ aMd["AGENTS.md · CONSTITUTION.md"]
46
+ ascripts["scripts/<br/>compile_skills.py · setup-context.sh/.ps1<br/>state_export.sh · state_import.sh · validators"]
47
+ end
48
+ node["bin/install.js<br/>(Node installer, npm gabbe-kit)"]
49
+ boot["install.sh · install.ps1<br/>(bootstrap: npx, else init.py)"]
50
+ wizard["scripts/init.py<br/>(interactive wizard)"]
51
+ plugin["scripts/build_claude_plugin.py"]
52
+ regx["scripts/registry_export.py<br/>scripts/registry_import.py"]
53
+ cliPkg["gabbe/ (PyPI gabbe)"]
54
+ gates["scripts/verify_all.sh · scripts/gates/run_gates.sh<br/>gabbe/tests · scripts/tests"]
55
+ out1[("project: agents/, docs/,<br/>AGENTS.md, .agents/skills/")]
56
+ out2[("project: per-agent formats,<br/>.gabbe/manifest.json")]
57
+ out3[("plugins/ ·<br/>.claude-plugin/marketplace.json")]
58
+
59
+ boot --> node
60
+ boot --> wizard
61
+ content --> node --> out1
62
+ content --> wizard
63
+ wizard -->|runs| ascripts
64
+ wizard --> out2
65
+ wizard -.->|uses when importable| cliPkg
66
+ content --> plugin --> out3
67
+ cliPkg -->|gabbe registry publish / add| regx
68
+ gates -.->|checks| content
69
+ gates -.->|checks| cliPkg
70
+ ```
71
+
72
+ - `bin/install.js` copies `agents/` and `docs/`, writes a root `AGENTS.md`, emits the universal
73
+ `.agents/skills/<slug>/SKILL.md` tree and wires the agents named with `--agents`. It writes no
74
+ manifest ([INSTALL.md](INSTALL.md)).
75
+ - `scripts/init.py` asks questions, copies the kit, calls `agents/scripts/compile_skills.py` for
76
+ each selected agent's format, and records what it created in `.gabbe/manifest.json` so
77
+ `gabbe uninstall` can reverse it. It uses `gabbe/detect.py` for brownfield detection when the
78
+ `gabbe` package is importable.
79
+ - `scripts/build_claude_plugin.py` turns every `agents/skills/**/*.skill.md` into the Claude Code
80
+ plugins under `plugins/` (generated; never edit by hand).
81
+ - The emitter golden vault (`scripts/tests/golden/baseline_v0.8.0`) hashes every file the wizard
82
+ writes, which includes every file under `agents/`. Any change there needs a recapture; see
83
+ [TESTING.md](../TESTING.md).
84
+
85
+ ## The CLI (`gabbe/`)
86
+
87
+ Each `gabbe` command runs in the project found by walking up from the current directory to the
88
+ first folder with `project/`, `.git` or `pyproject.toml` (`gabbe/config.py`). State lives in
89
+ that project's `project/state.db` (SQLite, schema v3), span logs in `project/logs/`, policy in
90
+ `project/policies.yml`. The arrows are the imports inside the package.
91
+
92
+ ```mermaid
93
+ flowchart TB
94
+ main["main.py<br/>(argparse, 19 commands)"]
95
+ subgraph cmds["Command modules"]
96
+ sync["sync.py"]
97
+ verify["verify.py"]
98
+ status["status.py"]
99
+ route["route.py"]
100
+ brain["brain.py"]
101
+ forecast["forecast.py"]
102
+ mcp["mcp_server.py"]
103
+ evals["evals.py"]
104
+ doctor["doctor.py"]
105
+ installer["installer.py"]
106
+ end
107
+ subgraph controls["Platform controls"]
108
+ context["context.py<br/>(RunContext)"]
109
+ budget["budget.py"]
110
+ hardstop["hardstop.py"]
111
+ policy["policy.py"]
112
+ gateway["gateway.py"]
113
+ audit["audit.py"]
114
+ escalation["escalation.py"]
115
+ replay["replay.py"]
116
+ end
117
+ llm["llm.py"]
118
+ cache["cache.py"]
119
+ database["database.py"]
120
+ config["config.py"]
121
+ detect["detect.py<br/>(used by scripts/init.py)"]
122
+
123
+ main --> cmds
124
+ main --> audit
125
+ main --> escalation
126
+ main --> replay
127
+ main --> database
128
+ brain --> context
129
+ brain --> gateway
130
+ brain --> llm
131
+ brain --> audit
132
+ brain --> escalation
133
+ brain --> database
134
+ mcp --> context
135
+ mcp --> gateway
136
+ verify --> mcp
137
+ verify --> route
138
+ verify --> hardstop
139
+ verify --> escalation
140
+ route --> llm
141
+ llm --> cache
142
+ llm --> audit
143
+ context --> budget
144
+ context --> hardstop
145
+ context --> policy
146
+ context --> gateway
147
+ context --> audit
148
+ context --> escalation
149
+ context --> replay
150
+ context --> database
151
+ budget --> database
152
+ audit --> database
153
+ escalation --> database
154
+ replay --> database
155
+ sync --> database
156
+ status --> database
157
+ forecast --> database
158
+ database --> config
159
+ ```
160
+
161
+ `config.py` (environment variables and paths) is imported by most modules; those arrows are
162
+ left out. `evals.py` runs `agents/scripts/eval_skills.py`; `doctor.py`, `installer.py` and
163
+ `detect.py` import nothing else from the package. What each control does, with its Python
164
+ API, is in [PLATFORM_CONTROLS.md](PLATFORM_CONTROLS.md); every command and variable is in
165
+ [CLI_REFERENCE.md](CLI_REFERENCE.md).
@@ -34,12 +34,12 @@ Entry point: `gabbe` (defined in `pyproject.toml → [project.scripts]`)
34
34
  | `GABBE_MAX_RECURSION_DEPTH` | `5` | Maximum agent recursion depth |
35
35
  | `GABBE_MAX_RETRIES_PER_TOOL` | `3` | Maximum retries per tool call |
36
36
  | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout for verify shell commands (seconds) |
37
- | `GABBE_AUTONOMY` | `hybrid` | Autonomy mode: `manual`, `hybrid`, or `autonomous` (env > project config > default; invalid values warn and fall back to `hybrid`) |
37
+ | `GABBE_AUTONOMY` | `hybrid` | Autonomy mode: `ask`, `auto`, or `hybrid` (env > project config > default; invalid values warn and fall back to `hybrid`) |
38
38
  | `GABBE_POLICY_FILE` | `project/policies.yml` | Path to YAML policy file for tool access control |
39
39
  | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli` (interactive), `file` (pause), `silent` (auto-reject) |
40
40
  | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
41
41
  | `GABBE_OTEL_CAPTURE_CONTENT` | `false` | Opt-in: capture prompt/response content on GenAI spans (off by default — content may contain PII/secrets) |
42
- | `GABBE_MCP_TOKEN` | *(unset)* | If set, MCP clients must send this token in `initialize` params (constant-time compared). Leave unset to disable authentication. |
42
+ | `GABBE_MCP_TOKEN` | *(unset)* | MCP clients must send this token in `initialize` params (constant-time compared). While it is unset (and `GABBE_MCP_INSECURE` is off) the server starts but refuses every tool call. |
43
43
  | `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | Comma-separated list of allowed executables for `run_command` via MCP, matched by exact command or basename (a directory entry is **not** a wildcard). When unset, all commands are blocked. Example: `pytest,ruff,bandit` |
44
44
  | `GABBE_MCP_INSECURE` | *(unset)* | Set to `1`/`true` to restore legacy permissive MCP mode (no auth, all commands allowed). Trusted, isolated hosts only. |
45
45
  | `GABBE_MCP_COMMAND_TIMEOUT` | `300` | Timeout (seconds) for a command executed via the MCP `run_command` tool |
@@ -274,6 +274,7 @@ Located at `project/state.db` (SQLite 3).
274
274
  | `reasoning_token_price` | REAL | Cost per reasoning token |
275
275
  | `cache_creation_price` | REAL | Cost per cache token |
276
276
  | `cache_read_price` | REAL | Cost per cache read token |
277
+ | `updated_at` | DATETIME | Last modification timestamp |
277
278
 
278
279
  ### `runs` (v3 updates)
279
280
  | Column | Type | Description |
@@ -438,15 +439,16 @@ gabbe registry add ./bundle --namespace ext # dry run
438
439
  gabbe registry add https://example/skill.skill.md --apply
439
440
  ```
440
441
 
441
- ### `gabbe setup [--force]`
442
+ ### `gabbe setup`
442
443
 
443
444
  Run the interactive install wizard (`scripts/init.py`) to wire the kit into your
444
445
  coding agents. (For a Python-independent install, use `npx gabbe-kit init` or
445
- `curl -fsSL .../install.sh | sh`.)
446
+ `curl -fsSL .../install.sh | sh`.) `gabbe setup --force` passes `--force` to the
447
+ wizard.
446
448
 
447
449
  ```bash
448
450
  gabbe setup
449
- gabbe setup --force # re-template even preserved files (each backed up first)
451
+ gabbe setup --force # re-template even preserved files (each backed up first)
450
452
  ```
451
453
 
452
454
  **Behavior:**
@@ -478,6 +480,7 @@ supports the same never-clobber/`--force` behavior plus non-interactive install:
478
480
  | `--yes` | Non-interactive; accept defaults without prompting |
479
481
  | `--agents <list>` | Comma-separated agents to wire (e.g. `--agents claude,cursor`) |
480
482
  | `--force` | Re-template even preserve-set files (each backed up to `<name>.gabbe-bak` first) |
483
+ | `--wizard` | Delegate to the full Python wizard (`scripts/init.py`) when `python3` is available (interactive) |
481
484
 
482
485
  ```bash
483
486
  npx gabbe-kit init --yes --agents claude,cursor
@@ -561,5 +564,5 @@ Check that `updated_at` is being written correctly to the DB.
561
564
  The DB timestamp (from `MAX(updated_at) FROM tasks`) must be ≥ the file mtime after an import.
562
565
 
563
566
  **CI: `validate_skills.py` not found**
564
- The `agents/scripts/` directory contains project-specific validators generated by `scripts/init.py`.
565
- Run `python3 scripts/init.py` once to generate them before CI runs.
567
+ The validators ship in the kit's `agents/scripts/` directory and are copied into your project
568
+ with the kit. If they are missing, re-run the installer (`npx gabbe-kit init` or `python3 scripts/init.py`).
@@ -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 (written for v1.1.1; counts re-checked 2026-10-29 on v1.1.2):** 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 → tech spec → task decomposition → implement → test →
33
+ security review → human review → staging → 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._
package/docs/INSTALL.md CHANGED
@@ -31,7 +31,8 @@ nothing you already had is silently overwritten. The preserve-set (`AGENTS.md`,
31
31
  pass `--force` (e.g. `npx gabbe-kit init --force`), which opts into re-templating those
32
32
  too — and still backs each one up first.
33
33
 
34
- After installing, run `gabbe doctor` to print an environment + install report
34
+ After installing, run `gabbe doctor` (a command of the PyPI CLI; the npm package's
35
+ `gabbe` command is the kit installer and has no `doctor`) to print an environment + install report
35
36
  (detected OS/arch, runtimes, agent clients, and per-check PASS/WARN). It also prints
36
37
  **post-install next steps** — which MCP servers to enable and how. For the full
37
38
  environment-setup walkthrough (MCP servers, local-GitHub servers, policy/budgets,
@@ -45,6 +46,8 @@ validation), see `docs/POST_INSTALL.md`.
45
46
 
46
47
  Resolution order for `update` / `uninstall`: `--dir` > `--global` > project (cwd).
47
48
 
49
+ The wizard's own "Global" choice installs to `~/agents` and is not manifest-tracked; `--global` of `update`/`uninstall` targets `$XDG_DATA_HOME/gabbe` only.
50
+
48
51
  ## Updating
49
52
 
50
53
  ```bash
@@ -1,6 +1,6 @@
1
1
  # MCP Server Configurations Guide
2
2
 
3
- > **Audience:** users wiring MCP servers. **Scope:** install/config/usage for every supported MCP server (package names verified 2026-06-10).
3
+ > **Audience:** users wiring MCP servers. **Scope:** install/config/usage for every supported MCP server (package names verified 2026-06-10, re-checked 2026-10-29: see the note below).
4
4
 
5
5
  Comprehensive installation, configuration, and usage guide for every MCP (Model Context Protocol) server supported by the GABBE kit.
6
6
 
@@ -26,8 +26,17 @@ Comprehensive installation, configuration, and usage guide for every MCP (Model
26
26
  > Docker/Go `terraform-mcp-server`; **Confluence/Jira** use community Atlassian
27
27
  > servers (e.g. `mcp-atlassian`, `@aashari/mcp-server-atlassian-*`). The
28
28
  > `@anthropic/mcp-server-shell` entry has no published package and should not be
29
- > used. See `OpenSourceAudit/projects/GABBE/mcp-verification-2026-06.md` for the
30
- > full per-server status.
29
+ > used.
30
+ >
31
+ > **Re-check 2026-10-29.** The npm registry returns 404 for
32
+ > `@anthropic/mcp-server-shell`, `@zapier/mcp-server`, `@vercel/mcp-server`,
33
+ > `@modelcontextprotocol/server-confluence`, `@mirohq/miro-mcp-server`,
34
+ > `@hashicorp/terraform-mcp-server`, `@grafana/mcp-server`,
35
+ > `@googlecloud/mcp-server`, `@figma/mcp-server`, `@docker/mcp-server`,
36
+ > `@datadog/mcp-server` and `@aws/mcp-server-core`: use the hosted or
37
+ > vendor-specific route above for those. npm marks
38
+ > `@modelcontextprotocol/server-github`, `-postgres`, `-brave-search`,
39
+ > `-redis` and `-gitlab` as deprecated (no longer supported).
31
40
 
32
41
  ---
33
42
 
@@ -216,6 +225,49 @@ PR review, code search, issue management, and git history.
216
225
 
217
226
  ---
218
227
 
228
+ ### GitHits
229
+
230
+ 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.
231
+
232
+ | Property | Value |
233
+ |---|---|
234
+ | **Package** | `githits` (npm) |
235
+ | **Website** | [githits.com](https://githits.com) · [docs.githits.com](https://docs.githits.com/) |
236
+ | **API Key** | None required |
237
+ | **GABBE Skill** | `research.skill`, `coding/code-review.skill`, `security/dependency-security.skill` |
238
+
239
+ **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).
240
+
241
+ **Install (automatic — recommended):**
242
+ ```bash
243
+ # Detects your tool (Claude Code, Cursor, VS Code/Copilot, Windsurf, Cline,
244
+ # Claude Desktop, Codex CLI, Gemini CLI, OpenCode, …) and wires up the MCP server.
245
+ npx githits@latest init
246
+ ```
247
+
248
+ **Config (manual — universal stdio entry):**
249
+ ```json
250
+ {
251
+ "githits": {
252
+ "command": "npx",
253
+ "args": ["-y", "githits@latest", "mcp", "start"],
254
+ "env": {}
255
+ }
256
+ }
257
+ ```
258
+
259
+ > [!NOTE]
260
+ > 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).
261
+
262
+ **Usage:**
263
+ ```
264
+ > "Use GitHits to find how `fastapi` implements dependency injection in its source."
265
+ > "Read the changelog and breaking changes for the `pydantic` v1 → v2 upgrade."
266
+ > "Grep the `react` dependency source for how `useEffect` cleanup is scheduled."
267
+ ```
268
+
269
+ ---
270
+
219
271
  ### GitLab
220
272
 
221
273
  GitLab alternative to the GitHub MCP. Same capabilities for GitLab-hosted repos.
@@ -1753,7 +1805,7 @@ credentials never leave the host. Servers marked **(new in v1.0)** were added to
1753
1805
  | SWEBOK area | Priority MCP servers | GABBE tie-in |
1754
1806
  |---|---|---|
1755
1807
  | **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 |
1808
+ | **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
1809
  | **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
1810
  | **Maintenance & Config Mgmt** | `pagerduty` (new), `cloudflare` (new), `vercel`, `gitlab` | S11–S13 Day-2; on-call automation, edge deploy logs |
1759
1811
  | **Eng. Management & Economics** | `linear`, `jira`, `confluence`, `slack`, `discord` (new), `stripe` | management + software economics; comms triage, billing/churn |
@@ -287,7 +287,7 @@ gabbe replay <run-id> --from-step 3
287
287
  | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli`, `file`, or `silent` |
288
288
  | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
289
289
  | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout for verify shell commands |
290
- | `GABBE_MCP_TOKEN` | *(unset)* | If set, MCP clients must provide this token in `initialize` params. Leave unset to disable. |
290
+ | `GABBE_MCP_TOKEN` | *(unset)* | MCP clients must provide this token in `initialize` params. While it is unset (and `GABBE_MCP_INSECURE` is off) the server refuses tool calls. |
291
291
  | `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | Comma-separated executables permitted via `run_command` over MCP. When unset, all commands are blocked. |
292
292
 
293
293
  ---
@@ -1,8 +1,8 @@
1
1
  # Post-Install Setup — Full Environment
2
2
 
3
3
  After `npx gabbe-kit init` (or `gabbe setup` / `curl … | sh`) lands the kit and wires
4
- your detected agents, run **`gabbe doctor`** for an environment report, then follow
5
- these steps to finish a full setup. Steps are safe for a human OR an agent to execute.
4
+ your detected agents, run **`gabbe doctor`** (from the PyPI CLI: `pipx install gabbe`)
5
+ for an environment report, then follow these steps to finish a full setup. Steps are safe for a human OR an agent to execute.
6
6
 
7
7
  ## 1. Verify the install
8
8
 
@@ -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 **65 MCP servers** in
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)
@@ -73,7 +74,7 @@ gabbe uninstall --dry-run # preview the exact removal (manifest-backed installs
73
74
  ```
74
75
 
75
76
  `update`/`uninstall` are manifest-backed for kits managed by the Python `gabbe`
76
- CLI. `npx` / `curl` / wizard installs aren't manifest-tracked — run `gabbe update`
77
+ CLI and for wizard installs. `npx` / `curl` installs aren't manifest-tracked — run `gabbe update`
77
78
  from a checkout first, or remove the kit directories manually. See
78
79
  `docs/INSTALL.md` for scopes (project / `--global` / `--dir`), channels, and the
79
80
  full reversibility scope note.
@@ -9,8 +9,8 @@ This guide provides a quick reference for the most common commands, setup instru
9
9
  | Goal | Command | Description |
10
10
  |---|---|---|
11
11
  | **Initialize Kit** | `python3 scripts/init.py` | Runs the setup wizard to configure the kit, wire your AI agents (Claude, Cursor, Gemini), and generate `BOOTSTRAP_MISSION.md` (or `SETUP_MISSION.md`) |
12
- | **Manual Wiring (UNIX)** | `./agents/setup-context.sh` | Manually symlinks the skills into your IDE's agent folder. |
13
- | **Manual Wiring (Windows)** | `.\agents\setup-context.ps1` | PowerShell equivalent of the manual wiring script. |
12
+ | **Manual Wiring (UNIX)** | `./agents/scripts/setup-context.sh` | Manually symlinks the skills into your IDE's agent folder. |
13
+ | **Manual Wiring (Windows)** | `.\agents\scripts\setup-context.ps1` | PowerShell equivalent of the manual wiring script. |
14
14
  | **Install GABBE CLI (Optional)**| `pip install -e .` | Installs the GABBE CLI locally. |
15
15
 
16
16
  ---
@@ -30,7 +30,7 @@ This guide provides a quick reference for the most common commands, setup instru
30
30
  | `gabbe brain activate` | Activates Active Inference loop (requires API key). |
31
31
  | `gabbe brain evolve --skill NAME` | Evolutionary Prompt Optimization for a named skill. |
32
32
  | `gabbe brain heal` | Self-healing watchdog: checks DB and required files. |
33
- | `gabbe route <prompt>` | Arbitrates prompt between Local and Remote LLMs (requires API key). |
33
+ | `gabbe route <prompt>` | Arbitrates prompt between Local and Remote LLMs (prompts of 100+ characters or with code blocks are rated by the LLM and need `GABBE_API_KEY`; without a key a fallback heuristic is used). |
34
34
  | `gabbe forecast` | Strategic Forecast projects remaining work cost and tokens. |
35
35
  | `gabbe serve-mcp` | Zero-dependency JSON-RPC MCP server for agent integration. |
36
36
  | `gabbe runs [--status STATUS] [--limit N]` | List recent agent runs with status, cost, and timestamps. |