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.
- package/LICENSE +1 -1
- package/README.md +25 -16
- package/agents/AGENTS.md +1 -1
- package/agents/CONSTITUTION.md +1 -1
- package/agents/guides/ai/ai-agentic.md +3 -1
- package/agents/guides/ops/cost-optimization.md +1 -1
- package/agents/guides/ops/troubleshooting-guide.md +2 -2
- package/agents/scripts/verify_e2e_init_flows.py +1 -1
- package/agents/skills/00-index.md +2 -2
- package/agents/skills/architecture/visual-whiteboarding.skill.md +17 -0
- package/agents/skills/coding/performant-php.skill.md +17 -0
- package/agents/templates/coordination/AGENTS_TEMPLATE.md +1 -1
- package/agents/templates/core/MCP_CONFIG_TEMPLATE.json +21 -2
- package/agents/templates/product/PRD_TEMPLATE.md +1 -1
- package/bin/install.js +24 -1
- package/docs/ARCHITECTURE.md +165 -0
- package/docs/CLI_REFERENCE.md +10 -7
- package/docs/FEATURES_AND_INNOVATIONS.md +3 -3
- package/docs/INSTALL.md +4 -1
- package/docs/MCP_CONFIGURATIONS.md +12 -3
- package/docs/PLATFORM_CONTROLS.md +1 -1
- package/docs/POST_INSTALL.md +3 -3
- package/docs/QUICK_COMMANDS.md +3 -3
- package/docs/QUICK_GUIDE.md +21 -21
- package/docs/README_FULL.md +58 -52
- package/docs/ROADMAP.md +3 -1
- package/docs/V1_RELEASE_CHECKLIST.md +5 -3
- package/docs/VERIFICATION_GUIDE.md +8 -7
- package/docs/reports/duplication-report.md +6 -6
- package/package.json +2 -2
- package/scripts/init.py +13 -25
|
@@ -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).
|
package/docs/CLI_REFERENCE.md
CHANGED
|
@@ -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: `
|
|
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)* |
|
|
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
|
|
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
|
|
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
|
|
565
|
-
|
|
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 →
|
|
33
|
-
|
|
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`
|
|
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.
|
|
30
|
-
>
|
|
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)* |
|
|
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
|
---
|
package/docs/POST_INSTALL.md
CHANGED
|
@@ -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`**
|
|
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`
|
|
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.
|
package/docs/QUICK_COMMANDS.md
CHANGED
|
@@ -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 (
|
|
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. |
|
package/docs/QUICK_GUIDE.md
CHANGED
|
@@ -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 -
|
|
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 (
|
|
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 **
|
|
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.
|
|
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
|
|
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 (
|
|
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`
|
|
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
|
|
320
|
-
QUICK_GUIDE.md
|
|
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
|
-
|
|
326
|
+
coding/ <- (tdd, refactor, debug, git...)
|
|
327
327
|
security/ <- (audit, threat-model...)
|
|
328
|
-
|
|
328
|
+
architecture/ <- (design, review, patterns...)
|
|
329
329
|
templates/ <- 100 fill-in-the-blank documents
|
|
330
330
|
guides/ <- 86 domain & process guides
|
|
331
|
-
|
|
332
|
-
|
|
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** |
|
|
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
|
|
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
|
|
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/
|
|
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
|
|
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/
|
|
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
|