gabbe-kit 1.1.2 → 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`).
@@ -7,7 +7,7 @@
7
7
  > Windsurf, Cline, Aider) into a **governed software-engineering team**, with an optional
8
8
  > Python control plane for budgets, policy, audit, and MCP tooling.
9
9
  >
10
- > **At a glance (v1.1.1):** 214 skills · 86 guides · 100 templates · 36 personas · 24 runtime
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
11
  > modules · 14 supported agents · install via `npx gabbe-kit init` / `pip install gabbe` /
12
12
  > `curl …/install.sh | sh` / git checkout.
13
13
  >
@@ -29,8 +29,8 @@ Each line is a feature → the concrete value it delivers.
29
29
  `.github/skills/…`, `.gemini/…`, universal `.agents/skills/…`). *Value:* a single, consistent
30
30
  engineering standard across a mixed-tool team instead of per-tool rule drift.
31
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
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
34
  agent is driven by an actual engineering process, not ad-hoc "vibe coding".
35
35
  - **Human-in-the-loop gates** at `S00/S01/S02/S07/S08`. *Value:* humans stay managers, not
36
36
  spectators — approval is required at the expensive/irreversible decision points.
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
 
@@ -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
 
@@ -74,7 +74,7 @@ gabbe uninstall --dry-run # preview the exact removal (manifest-backed installs
74
74
  ```
75
75
 
76
76
  `update`/`uninstall` are manifest-backed for kits managed by the Python `gabbe`
77
- 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`
78
78
  from a checkout first, or remove the kit directories manually. See
79
79
  `docs/INSTALL.md` for scopes (project / `--global` / `--dir`), channels, and the
80
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. |
@@ -32,8 +32,8 @@ AI coding agents suffer from three compounding problems:
32
32
  ## 5-Minute Setup Checklist
33
33
 
34
34
  ```bash
35
- # 1. Download & Run the Installer
36
- curl -sL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/scripts/init.py | python3 -
35
+ # 1. Download & Run the Installer (uses npx gabbe-kit init when Node is present)
36
+ curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh | sh
37
37
 
38
38
  # OR if you have the repo cloned:
39
39
  python3 GABBE/scripts/init.py
@@ -62,7 +62,7 @@ python3 GABBE/scripts/init.py
62
62
  - Open `agents/AGENTS.md`: Check `Tech Stack` section.
63
63
  - Verify `test_cmd` and `lint_cmd` match your project.
64
64
  - Open `agents/CONSTITUTION.md`: Review project laws.
65
- - Adjust Article I (Directives) if needed.
65
+ - Adjust Article I (Test-First Mandate) if needed.
66
66
 
67
67
  ## 6. Git Tracking (Important)
68
68
  - To keep the initial structure of `agents/memory/` and `project/` in your repository but prevent Git from tracking the continuous autonomous modifications your agents will make to them locally, run:
@@ -74,10 +74,10 @@ python3 GABBE/scripts/init.py
74
74
 
75
75
  ## 🚀 GABBE CLI (Experimental)
76
76
 
77
- GABBE contains a **Zero-Dependency CLI** (`gabbe`) CLI which powers the "Hybrid Mode". It bridges the gap between flexible Markdown files and a robust SQLite database. It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.
77
+ GABBE contains a **lightweight CLI** (`gabbe`; three runtime dependencies: `requests`, `PyYAML`, `jsonschema`) which powers the "Hybrid Mode". It bridges the gap between flexible Markdown files and a robust SQLite database. It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.
78
78
 
79
79
  ### Prerequisites
80
- - Python 3.8+
80
+ - Python 3.9+
81
81
  - **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
82
82
 
83
83
  **Environment Variables** (full reference in [CLI_REFERENCE.md](CLI_REFERENCE.md#environment-variables)):
@@ -129,10 +129,10 @@ python scripts/fill_placeholders.py
129
129
  | `gabbe verify --chaos` | **Resilience**: fault-injection self-checks (fail-closed tool, hard-stop, escalation). |
130
130
  | `gabbe eval` | **Skill evals**: deterministic self-check; `--live` scores via the model. |
131
131
  | `gabbe doctor` | **Autodetect**: OS/runtimes/agents + post-install MCP next-steps. |
132
- | `gabbe update` / `gabbe uninstall` | Additive refresh / manifest-backed removal (for `gabbe`-CLI-managed kits; npx/curl/wizard installs aren't manifest-tracked). |
132
+ | `gabbe update` / `gabbe uninstall` | Additive refresh / manifest-backed removal (for `gabbe`-CLI-managed kits and wizard installs; npx/curl installs aren't manifest-tracked). |
133
133
  | `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
134
134
  | `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
135
- | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key). |
135
+ | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (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). |
136
136
  | `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
137
137
  | `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
138
138
  | `gabbe runs` | **Run History**: List recent agent runs with status, cost, and timestamps. |
@@ -297,7 +297,7 @@ Uses Active Inference to plan, route between local/remote models, and learn from
297
297
  ### Activate Loki Mode (Large Projects)
298
298
 
299
299
  **Using the CLI:**
300
- > `gabbe brain activate` (Loki may be triggered autonomously)
300
+ > `gabbe brain activate` prints the model's recommended next action; it does not start Loki.
301
301
  Or activate the swarm skill explicitly:
302
302
  > Activate `agents/skills/brain/loki-mode.skill.md` with your goal.
303
303
 
@@ -316,20 +316,20 @@ Multi-agent swarm with 30+ specialized personas for projects >5 features or >20
316
316
  ```
317
317
  GABBE/
318
318
  scripts/init.py <- Installer Wizard (Run this first)
319
- README_FULL.md <- Complete step-by-step guide
320
- QUICK_GUIDE.md <- This file
319
+ docs/README_FULL.md <- Complete step-by-step guide
320
+ docs/QUICK_GUIDE.md <- This file
321
321
  agents/ <- The actual kit payload
322
322
  AGENTS.md <- Universal config template
323
323
  CONSTITUTION.md <- Immutable project law
324
324
  scripts/setup-context.sh <- Internal wiring script (wrapped by scripts/init.py)
325
325
  skills/ <- 214 agent capability packages (💯)
326
- core/ <- (tdd, refactor, debug, git...)
326
+ coding/ <- (tdd, refactor, debug, git...)
327
327
  security/ <- (audit, threat-model...)
328
- arch/ <- (design, review, patterns...)
328
+ architecture/ <- (design, review, patterns...)
329
329
  templates/ <- 100 fill-in-the-blank documents
330
330
  guides/ <- 86 domain & process guides
331
- loki/
332
- docs/
331
+ personas/ <- 36 specialized roles (Loki Mode)
332
+ memory/ <- project state, continuity, audit log
333
333
  ```
334
334
 
335
335
  ---
@@ -399,7 +399,7 @@ The script detects your selected agents and generates the correct format for eac
399
399
  |---|---|---|
400
400
  | **Cursor** | `.mdc` rules | `.cursor/rules/*.mdc` |
401
401
  | **VS Code / Copilot** | Folders + Config | `.github/skills/<slug>/` |
402
- | **Claude Code** | Symlink | `.claude/skills` → `agents/skills` |
402
+ | **Claude Code** | `SKILL.md` folders | `.claude/skills/<slug>/SKILL.md` (one per skill) |
403
403
  | **Gemini / Antigravity** | Settings | `.gemini/settings.json` points to `agents/skills` |
404
404
 
405
405
  This means you write a skill once in `agents/skills/` and it runs everywhere.
@@ -657,7 +657,7 @@ Goal: Mandate SDD for all new features
657
657
  Rule: No code without an approved PRD.md
658
658
  Actions:
659
659
  - Make spec-writer.skill the entry point for all feature requests
660
- - Enforce 7-gate quality system in CI/CD
660
+ - Enforce 10-gate quality system in CI/CD
661
661
  - Track and repay tech debt with tech-debt.skill
662
662
  - Measure: specification-to-code ratio, coverage, architectural violations
663
663
  ```
@@ -678,7 +678,7 @@ Actions:
678
678
 
679
679
  | Server | Install | Why |
680
680
  |---|---|---|
681
- | **Context-7** | `npx @context7/mcp-server` | Up-to-date SDK docs (prevents API hallucination) |
681
+ | **Context-7** | `npx @upstash/context7-mcp` | 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
684
  | **GitHits** | `npx githits@latest init` | Navigate open-source dependency source/docs (no clone, no key) |
@@ -686,7 +686,7 @@ Actions:
686
686
  | **Semgrep MCP** | `pip install semgrep-mcp` | In-agent SAST security scanning |
687
687
  | **Brave Search MCP** | `npx @modelcontextprotocol/server-brave-search` | Authoritative web research |
688
688
  | **Playwright MCP** | `npx @playwright/mcp` | Browser automation for visual TDD |
689
- | **Sentry MCP** | `npx @sentry/mcp` | Error tracking and bug context |
689
+ | **Sentry MCP** | `npx @sentry/mcp-server` | Error tracking and bug context |
690
690
  | **Qdrant MCP** | `docker run qdrant/qdrant` + MCP server | Long-term semantic memory |
691
691
 
692
692
  See `templates/core/MCP_CONFIG_TEMPLATE.json` for the full catalog with security configuration.
@@ -746,7 +746,7 @@ If the self-healing loop frequently fails or a specific skill repeatedly produce
746
746
  ```
747
747
 
748
748
  **Using Pure Agent Mode (No CLI):**
749
- > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/react-components.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
749
+ > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/ui-gen.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
750
750
 
751
751
  ### Human-in-the-Loop — When to Pause and Ask
752
752
  ```
@@ -838,7 +838,7 @@ No human needed for:
838
838
 
839
839
  | Category | Templates |
840
840
  |---|---|
841
- | **Core** | `AGENTS`, `MCP_CONFIG`, `DEVCONTAINER`, `DEV_SPACE`, `PLAN`, `TASKS`, `AUDIT_LOG`, `SDLC_TRACKER`, `SESSION_SNAPSHOT`, `SWARM_CONFIG`, `AGENT_HANDSHAKE`, `SYSTEM_ANALYSIS`, `PROJECT_STATE`, `CONTINUITY`, `VOTING_LOG` |
841
+ | **Core** | `AGENTS`, `MCP_CONFIG`, `DEVCONTAINER`, `DEV_SPACE`, `PLAN`, `TASKS`, `AUDIT_LOG`, `SDLC_TRACKER`, `SESSION_SNAPSHOT`, `SWARM_CONFIG`, `AGENT_HANDSHAKE`, `SYSTEM_ANALYSIS` (project state, continuity and the voting log live in `agents/memory/`: `PROJECT_STATE.md`, `CONTINUITY.md`, `episodic/VOTING_LOG.md` (created at run time)) |
842
842
  | **Arch** | `ADR`, `ARCH_DECISION_FRAMEWORK`, `ARCHITECTURE_DECISION_MATRIX`, `ARCHITECTURE_REVIEW`, `ARCHITECTURE_VIEWS`, `C4_ARCHITECTURE`, `CONTEXT_MAP`, `DOMAIN_MODEL`, `SYSTEM_CONTEXT`, `SWARM_ARCHITECTURE`, `DESIGN_PATTERN_USAGE`, `CAPABILITY_MAP`, `LEGACY_AUDIT` |
843
843
  | **Reqs** | `PRD`, `SPEC`, `BUSINESS_CASE`, `CAPABILITY_MAP`, `EMPATHY_MAP`, `NFR`, `QUALITY_ATTRIBUTES`, `REQUIREMENTS_REVIEW`, `STAKEHOLDER_REGISTER`, `TRACEABILITY_MATRIX`, `ETHICAL_IMPACT_ASSESSMENT` |
844
844
  | **Eng** | `CLEAN_CODE_CHECKLIST`, `SECURITY_CHECKLIST`, `THREAT_MODEL`, `TECH_DEBT`, `TEST_PLAN`, `TEST_CASE`, `INTEGRATION_SPEC`, `DATA_PIPELINE`, `DATABASE_SCHEMA`, `DESIGN_TOKENS`, `E2E_TEST_SUITE`, `SAFETY_POLICY` |
@@ -897,7 +897,7 @@ python3 GABBE/scripts/init.py
897
897
  *See README.md for quick reference.*
898
898
  *See README_FULL.md for full workflow guides with Mermaid diagrams.*
899
899
  *See skills/00-index.md for complete skills registry with installation instructions.*
900
- *See agents/skills/brain/README_ORCHESTRATORS.md for Loki Mode multi-agent orchestration.*
900
+ *See agents/skills/brain/loki-mode.skill.md for Loki Mode multi-agent orchestration.*
901
901
  *See agents/skills/brain/README.md for complete brain documentation.*
902
902
 
903
903
  ## 🛡️ Security & Guardrails