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.
- package/LICENSE +1 -1
- package/README.md +65 -17
- 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 +33 -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 +208 -0
- package/docs/INSTALL.md +4 -1
- package/docs/MCP_CONFIGURATIONS.md +56 -4
- package/docs/PLATFORM_CONTROLS.md +1 -1
- package/docs/POST_INSTALL.md +5 -4
- package/docs/QUICK_COMMANDS.md +3 -3
- package/docs/QUICK_GUIDE.md +22 -21
- package/docs/README_FULL.md +62 -54
- package/docs/ROADMAP.md +100 -0
- package/docs/V1_RELEASE_CHECKLIST.md +5 -3
- package/docs/VERIFICATION_GUIDE.md +8 -7
- package/docs/assets/GABBE.png +0 -0
- package/docs/reports/duplication-report.md +6 -6
- package/package.json +3 -2
- package/scripts/init.py +13 -25
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
## License
|
|
2
2
|
|
|
3
|
-
This documentation is licensed under the [Creative Commons Attribution 4.0 International License (CC BY
|
|
3
|
+
This documentation is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/).
|
|
4
4
|
|
|
5
5
|
You are free to:
|
|
6
6
|
|
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
## What is this?
|
|
9
9
|
|
|
10
10
|
- Agentic code development and governance via capability layers and software development cycle gates verifications and alignment (including best practices for security and human-in-the-loop, complete framework).
|
|
11
|
-
-
|
|
11
|
+
- An open-source project that features a complete agentic coding kit/framework with cognitive brain loop, skills, SDLC workflow, etc.
|
|
12
12
|
- Universal kit for Software and AI coding agents: Claude Code, Cursor, Windsurf, Cline, Aider, Devin, Gemini, **Antigravity**, **OpenCode**, **Zed**, **Continue**, **Roo Code**, **Kilo Code**, OpenAI/Codex, GitHub Copilot, VS Code.
|
|
13
13
|
- Drop-in context kit that turns any AI coding agent into a governed engineering team for developing software.
|
|
14
14
|
- Based on Software Engineering & Architecture Practices and Procedures.
|
|
@@ -34,7 +34,11 @@ It contains:
|
|
|
34
34
|
|
|
35
35
|
---
|
|
36
36
|
|
|
37
|
-
*
|
|
37
|
+
*Website: [andreibesleaga.github.io/GABBE](https://andreibesleaga.github.io/GABBE/)*
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
*Full documentation: [README_FULL.md](docs/README_FULL.md) · Full quick guide: [QUICK_GUIDE.md](docs/QUICK_GUIDE.md) · Quick commands: [QUICK_COMMANDS.md](docs/QUICK_COMMANDS.md) · CLI reference: [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) · MCP servers: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md) · Platform Controls: [PLATFORM_CONTROLS.md](docs/PLATFORM_CONTROLS.md) · Verification Guide: [VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md) · Architecture: [ARCHITECTURE.md](docs/ARCHITECTURE.md) · Roadmap: [ROADMAP.md](docs/ROADMAP.md)*
|
|
38
42
|
|
|
39
43
|
---
|
|
40
44
|
|
|
@@ -57,7 +61,7 @@ It contains:
|
|
|
57
61
|
| **Shell bootstrap** | `curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh \| sh` | picks the best available installer |
|
|
58
62
|
| **Git checkout** | `git clone https://github.com/andreibesleaga/GABBE && cd GABBE && python3 scripts/init.py` | the interactive wizard |
|
|
59
63
|
|
|
60
|
-
> On npm the package is **`gabbe-kit`** (npm refuses the unscoped `gabbe`); on PyPI it is **`gabbe
|
|
64
|
+
> On npm the package is **`gabbe-kit`** (npm refuses the unscoped `gabbe`); on PyPI it is **`gabbe`**; the npm package is additionally mirrored on GitHub Packages as `@andreibesleaga/gabbe-kit` (npmjs stays canonical). Both packages install a command named `gabbe`, but not the same one: on npm it is the kit installer (`gabbe init` only), on PyPI it is the CLI. After installing the PyPI CLI, run `gabbe doctor` for an environment + install report. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
|
|
61
65
|
|
|
62
66
|
**Universal, Python-independent (one command):**
|
|
63
67
|
```bash
|
|
@@ -121,9 +125,47 @@ Steps after running the wizard:
|
|
|
121
125
|
**Manual Setup:**
|
|
122
126
|
```bash
|
|
123
127
|
cp -r GABBE/agents .
|
|
124
|
-
chmod +x agents/setup-context.sh && agents/setup-context.sh
|
|
128
|
+
chmod +x agents/scripts/setup-context.sh && agents/scripts/setup-context.sh
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Install as a Claude Code plugin
|
|
132
|
+
|
|
133
|
+
The skills also ship as Claude Code plugins in one marketplace, so Claude Code can use
|
|
134
|
+
them without installing the kit into the project:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
claude plugin marketplace add andreibesleaga/GABBE
|
|
138
|
+
claude plugin install gabbe@gabbe
|
|
125
139
|
```
|
|
126
140
|
|
|
141
|
+
`gabbe` holds the core skills (every skill in `agents/skills/core/` and every skill
|
|
142
|
+
marked `core: true`). The other skills come as topic plugins from the same marketplace:
|
|
143
|
+
`gabbe-ai`, `gabbe-architecture`, `gabbe-brain`, `gabbe-coding`, `gabbe-coordination`,
|
|
144
|
+
`gabbe-data`, `gabbe-industry`, `gabbe-ops`, `gabbe-product` and `gabbe-security`
|
|
145
|
+
(for example `claude plugin install gabbe-security@gabbe`). Claude Code keeps every
|
|
146
|
+
installed skill's name and description in context, within about 1% of the context
|
|
147
|
+
window. All 214 skills would need far more than that; the core plugin alone costs about
|
|
148
|
+
2,700 tokens per session (`claude plugin details gabbe`), a little over the ~2,000-token
|
|
149
|
+
budget of a 200k context and well within that of a 1M context. Over budget, Claude Code
|
|
150
|
+
drops the descriptions of the least-used skills; nothing fails. Install only the topics
|
|
151
|
+
you use.
|
|
152
|
+
|
|
153
|
+
The same skills install one by one with the skills CLI ([skills.sh](https://skills.sh)):
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
npx skills add andreibesleaga/GABBE -a claude-code
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Plugin skills are namespaced (`/gabbe:code-review`, `/gabbe:debug`). The skills CLI
|
|
160
|
+
instead writes them to `.claude/skills/` in the project, where GABBE's `code-review` and
|
|
161
|
+
`debug` take the place of Claude Code's built-in `/code-review` and `/debug` in that
|
|
162
|
+
project; skip those two there if you want the built-ins.
|
|
163
|
+
|
|
164
|
+
The plugins are content only (Markdown skills and the templates they name: no hooks,
|
|
165
|
+
no MCP servers, no executables). They are generated from `agents/skills/`; after
|
|
166
|
+
editing a skill run `python scripts/build_claude_plugin.py` (CI checks the tree is in
|
|
167
|
+
sync).
|
|
168
|
+
|
|
127
169
|
### 🌍 Cross-Platform Support
|
|
128
170
|
- **Linux / macOS / WSL:** Native support.
|
|
129
171
|
- **Windows (Native):**
|
|
@@ -482,7 +524,7 @@ agents/
|
|
|
482
524
|
├── guides/ # 86 language & domain guides
|
|
483
525
|
├── personas/ # 36 specialized agent roles
|
|
484
526
|
├── memory/ # Episodic + semantic + project state
|
|
485
|
-
└──
|
|
527
|
+
└── scripts/ # setup-context, validators, state export/import
|
|
486
528
|
```
|
|
487
529
|
|
|
488
530
|
---
|
|
@@ -507,34 +549,36 @@ Sits **above** Loki. Decides *how* to execute, not just *what* to execute.
|
|
|
507
549
|
| **Episodic Memory** | Recalls past project outcomes to avoid repeated mistakes |
|
|
508
550
|
| **System 2 Thinking** | Strategic planning before execution |
|
|
509
551
|
|
|
552
|
+
These are the agent-mode behaviours of `brain-mode.skill`. The `gabbe brain` CLI is smaller: it reads task counts, picks a prompt gene (epsilon-greedy), makes one LLM call and rewards the gene; routing is `gabbe route`, and it does no episodic recall (see [ADR-0002](docs/adr/0002-brain-active-inference-runtime.md)).
|
|
553
|
+
|
|
510
554
|
---
|
|
511
555
|
|
|
512
556
|
## 🔧 Setup by Project Type
|
|
513
557
|
|
|
514
558
|
### JavaScript / TypeScript / Node.js
|
|
515
559
|
```
|
|
516
|
-
Guide: guides/js-ts-nodejs.md
|
|
560
|
+
Guide: guides/languages/js-ts-nodejs.md
|
|
517
561
|
Stack: Vitest, Zod, Prisma, Playwright, Hono
|
|
518
562
|
Config in AGENTS.md: test_cmd="npx vitest", lint_cmd="npx eslint ."
|
|
519
563
|
```
|
|
520
564
|
|
|
521
565
|
### Go (Golang)
|
|
522
566
|
```
|
|
523
|
-
Guide: guides/go-lang.md
|
|
567
|
+
Guide: guides/languages/go-lang.md
|
|
524
568
|
Stack: Echo/Gin, Ent, Testify, Testcontainers
|
|
525
569
|
Config in AGENTS.md: test_cmd="go test ./...", lint_cmd="golangci-lint run"
|
|
526
570
|
```
|
|
527
571
|
|
|
528
572
|
### PHP / Laravel
|
|
529
573
|
```
|
|
530
|
-
Guide: guides/php-laravel.md
|
|
574
|
+
Guide: guides/languages/php-laravel.md
|
|
531
575
|
Stack: DDD, Actions, Pest PHP, PHPStan L9, Enlightn
|
|
532
576
|
Config in AGENTS.md: test_cmd="vendor/bin/pest", lint_cmd="vendor/bin/pint"
|
|
533
577
|
```
|
|
534
578
|
|
|
535
579
|
### Python / FastAPI
|
|
536
580
|
```
|
|
537
|
-
Guide: guides/python-fastapi-ai.md
|
|
581
|
+
Guide: guides/languages/python-fastapi-ai.md
|
|
538
582
|
Stack: Pydantic, Pytest, Ruff, FastAPI
|
|
539
583
|
Config in AGENTS.md: test_cmd="pytest", lint_cmd="ruff check ."
|
|
540
584
|
```
|
|
@@ -579,7 +623,7 @@ the Day-0 phase **S00 (Strategy & Discovery)** and the Day-2 phases **S11–S13
|
|
|
579
623
|
| **Industry** | 5+ | `healthcare-fhir`, `telecom-networks`, `industrial-iot`, `global-standards`, `engineering-standards` |
|
|
580
624
|
| **Loki Modes** | 2+ | `brain-mode`, `loki-mode` |
|
|
581
625
|
|
|
582
|
-
Full catalog: `agents/skills/00-index.md`
|
|
626
|
+
Full catalog: `agents/skills/00-index.md`
|
|
583
627
|
|
|
584
628
|
---
|
|
585
629
|
|
|
@@ -593,12 +637,12 @@ Full catalog: `agents/skills/00-index.md` *(generated by `init.py`)*
|
|
|
593
637
|
| **Security** | 5+ | Threat Model, Safety Case, Ethical Impact |
|
|
594
638
|
| **Product** | 10+ | PRD, Spec, User Story Map, Visual Spec, Green Software |
|
|
595
639
|
| **Core** | 5+ | Plan, Tasks, Audit Log, Project State, Continuity |
|
|
596
|
-
| **Coordination** | 5+ | Agent Profile, Swarm Config, Handshake,
|
|
640
|
+
| **Coordination** | 5+ | Agent Profile, Swarm Config, Handshake, Swarm Architecture |
|
|
597
641
|
| **Brain** | 5+ | Active Inference Loop, Episodic Memory, OODA Trace |
|
|
598
|
-
| **Data** |
|
|
642
|
+
| **Data** | 3 | Data Pipeline, Database Schema, OWL Ontology |
|
|
599
643
|
| **Industry** | 5+ | FHIR Interop, IoT Telemetry, Telecom API, Global SDLC Audit |
|
|
600
644
|
|
|
601
|
-
Full catalog: `agents/templates/00-index.md`
|
|
645
|
+
Full catalog: `agents/templates/00-index.md`
|
|
602
646
|
|
|
603
647
|
---
|
|
604
648
|
|
|
@@ -609,6 +653,7 @@ Full catalog: `agents/templates/00-index.md` *(generated by `init.py`)*
|
|
|
609
653
|
| **Context-7** | Up-to-date SDK docs (prevents hallucination) |
|
|
610
654
|
| **Sequential Thinking** | Chain-of-thought reasoning |
|
|
611
655
|
| **GitHub MCP** | PR review, code search |
|
|
656
|
+
| **GitHits** | Navigate open-source dependency source/docs (no clone, no key) |
|
|
612
657
|
| **PostgreSQL MCP** | Live schema introspection |
|
|
613
658
|
| **Playwright MCP** | Browser automation / visual TDD |
|
|
614
659
|
| **Brave Search** | Authoritative web research |
|
|
@@ -647,7 +692,7 @@ Task → Knowledge gap? → research.skill → Execute → Verify
|
|
|
647
692
|
|
|
648
693
|
| Problem | Fix |
|
|
649
694
|
|---|---|
|
|
650
|
-
| Agent ignores AGENTS.md | Run `setup-context.sh` to create symlinks |
|
|
695
|
+
| Agent ignores AGENTS.md | Run `agents/scripts/setup-context.sh` to create symlinks |
|
|
651
696
|
| Agent repeats mistakes | Check `CONTINUITY.md` — tell agent to read it |
|
|
652
697
|
| Tests pass immediately | False positive — test is broken, fix it first |
|
|
653
698
|
| Uses deprecated APIs | Activate Context-7 MCP |
|
|
@@ -705,10 +750,10 @@ Agents are explicitly configured to **Fail-Closed**—they must wait for human a
|
|
|
705
750
|
|
|
706
751
|
## 🚀 GABBE CLI (Experimental)
|
|
707
752
|
|
|
708
|
-
GABBE has also an experimental helper, **
|
|
753
|
+
GABBE has also an experimental helper, **lightweight CLI** (`gabbe`; three runtime dependencies: `requests`, `PyYAML`, `jsonschema`) for a "Hybrid Mode" (Markdown files and a SQLite database) and launching different commands. It is a work-in-progress and you can do without it, only with the rest of the kit.
|
|
709
754
|
|
|
710
755
|
### Prerequisites
|
|
711
|
-
- Python 3.
|
|
756
|
+
- Python 3.9+
|
|
712
757
|
- **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
|
|
713
758
|
|
|
714
759
|
**Environment Variables** (full reference in [CLI_REFERENCE.md](docs/CLI_REFERENCE.md)):
|
|
@@ -758,7 +803,7 @@ gabbe --help
|
|
|
758
803
|
| `gabbe verify`| **Enforcer**: programmable integrity check (files, tests, lint). |
|
|
759
804
|
| `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
|
|
760
805
|
| `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
|
|
761
|
-
| `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (
|
|
806
|
+
| `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). |
|
|
762
807
|
| `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
|
|
763
808
|
| `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
|
|
764
809
|
| `gabbe runs` | **Run History**: List recent agent runs with status, cost, and timestamps. |
|
|
@@ -768,6 +813,9 @@ gabbe --help
|
|
|
768
813
|
| `gabbe registry publish` | **Publish Skills**: Export the kit's skills as a publish-ready agentskills.io bundle (manifest + agent-card) for universal registries. |
|
|
769
814
|
| `gabbe registry add <source>` | **Import Skills**: Draw an external skill/bundle (path, `.tar.gz`, or URL) — validated + security-scanned + landed namespaced for review. |
|
|
770
815
|
| `gabbe setup` | **Install Wizard**: Run the interactive installer to wire the kit into your coding agents (see also `npx gabbe-kit init`). |
|
|
816
|
+
| `gabbe doctor` | **Autodetect**: OS/arch, runtimes, installed agents + post-install MCP next-steps. |
|
|
817
|
+
| `gabbe eval` | **Skill evals**: deterministic self-check; `--live` scores skill outputs via the model. |
|
|
818
|
+
| `gabbe update` / `gabbe uninstall` | **Reversible install**: additive refresh / manifest-backed removal (`--dry-run`, `--purge`, `--global`, `--dir`). |
|
|
771
819
|
|
|
772
820
|
### Platform Control Layer
|
|
773
821
|
The experimental `gabbe` CLI supports a **platform control layer**. It covers budget enforcement, cost and token controls, hard stops, policy rules, the tool gateway, audit tracing, human escalation, and deterministic replay. Detailed documentation is available in [`PLATFORM_CONTROLS.md`](docs/PLATFORM_CONTROLS.md).
|
package/agents/AGENTS.md
CHANGED
|
@@ -569,7 +569,7 @@ the same operating spine in §5/§13 (preflight → clarify → act → state-pr
|
|
|
569
569
|
---
|
|
570
570
|
|
|
571
571
|
*Last updated: [DATE]*
|
|
572
|
-
*GABBE Kit version: 1.1.
|
|
572
|
+
*GABBE Kit version: 1.1.3*
|
|
573
573
|
*This file is maintained by the team and updated when project conventions change.*
|
|
574
574
|
|
|
575
575
|
---
|
package/agents/CONSTITUTION.md
CHANGED
|
@@ -240,7 +240,7 @@ GOOD (EARS — testable):
|
|
|
240
240
|
```json
|
|
241
241
|
{
|
|
242
242
|
"mcpServers": {
|
|
243
|
-
"context7": { "command": "npx", "args": ["@context7
|
|
243
|
+
"context7": { "command": "npx", "args": ["@upstash/context7-mcp"] },
|
|
244
244
|
"sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] },
|
|
245
245
|
"github": {
|
|
246
246
|
"command": "npx",
|
|
@@ -256,6 +256,8 @@ GOOD (EARS — testable):
|
|
|
256
256
|
}
|
|
257
257
|
```
|
|
258
258
|
|
|
259
|
+
> The `server-github` and `server-postgres` packages above are deprecated: npm marks them "no longer supported" (checked 2026-10-30), though they still install. See `docs/MCP_CONFIGURATIONS.md` for current alternatives.
|
|
260
|
+
|
|
259
261
|
**Key MCP servers for agentic engineering:**
|
|
260
262
|
- **Context-7**: Up-to-date library docs (prevents hallucinated API usage)
|
|
261
263
|
- **Sequential Thinking**: Forces structured reasoning before acting
|
|
@@ -27,7 +27,7 @@ Financial Operations (FinOps) is the operating model for the cloud, bringing fin
|
|
|
27
27
|
|
|
28
28
|
## LLM & Agentic Cost Control (the agent's own spend)
|
|
29
29
|
|
|
30
|
-
The largest variable cost of an agentic system is LLM tokens. GABBE controls this with four levers, all enforceable through the platform-control layer (`
|
|
30
|
+
The largest variable cost of an agentic system is LLM tokens. GABBE controls this with four levers, all enforceable through the platform-control layer (the `GABBE_MAX_COST_USD` budget, `gabbe route` and `gabbe forecast`).
|
|
31
31
|
|
|
32
32
|
### 1. Prompt caching — the highest-leverage lever
|
|
33
33
|
Reusing a stable prompt prefix avoids re-billing it on every call. Sources verified 2026-06-10.
|
|
@@ -21,7 +21,7 @@ This guide provides solutions to common issues encountered when initializing, co
|
|
|
21
21
|
**Cause:** Windows requires Administrator privileges to create symlinks by default.
|
|
22
22
|
**Solution:**
|
|
23
23
|
1. Open PowerShell **as Administrator**.
|
|
24
|
-
2. Run `.\agents\setup-context.ps1`.
|
|
24
|
+
2. Run `.\agents\scripts\setup-context.ps1`.
|
|
25
25
|
3. Alternatively, enable Developer Mode in Windows Settings (which allows standard users to create symlinks).
|
|
26
26
|
|
|
27
27
|
## 2. Agent Configuration Issues
|
|
@@ -30,7 +30,7 @@ This guide provides solutions to common issues encountered when initializing, co
|
|
|
30
30
|
**Symptoms:** The agent generates code in the wrong framework or ignores layer boundaries.
|
|
31
31
|
**Cause:** The symlink from `.cursorrules` or `.claude/CLAUDE.md` to `AGENTS.md` is broken, or the file lacks rules.
|
|
32
32
|
**Solution:**
|
|
33
|
-
1. Re-run `./agents/setup-context.sh`.
|
|
33
|
+
1. Re-run `./agents/scripts/setup-context.sh`.
|
|
34
34
|
2. Check `AGENTS.md` to ensure `[PLACEHOLDER]` fields are filled correctly.
|
|
35
35
|
|
|
36
36
|
### Skills not triggering
|
|
@@ -30,7 +30,7 @@ def run_gabbe_command(cmd, env, cwd):
|
|
|
30
30
|
process = subprocess.run(cmd, text=True, env=env, cwd=str(cwd), capture_output=True, shell=True)
|
|
31
31
|
# gabbe verify is expected to fail with exit code 1 due to [PLACEHOLDER] variables inside a freshly initialized setup.
|
|
32
32
|
# The success state is it finding the placeholders instead of crashing.
|
|
33
|
-
if "
|
|
33
|
+
if cmd.endswith(" verify") and process.returncode != 0:
|
|
34
34
|
if (
|
|
35
35
|
"Verification FAILED" in process.stdout
|
|
36
36
|
or "Placeholder" in process.stdout
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
### Method 1: This Kit (built-in — no install needed)
|
|
12
12
|
All 214 skills in this directory are ready to use immediately.
|
|
13
|
-
Run `setup-context.sh` to wire them to your AI tool's skill directory.
|
|
13
|
+
Run `agents/scripts/setup-context.sh` to wire them to your AI tool's skill directory.
|
|
14
14
|
|
|
15
15
|
### Method 2: Skill Marketplaces & Registries
|
|
16
16
|
```bash
|
|
@@ -35,7 +35,7 @@ namnam install --platform claude-code
|
|
|
35
35
|
### Global vs Workspace Scope
|
|
36
36
|
```bash
|
|
37
37
|
# Workspace scope (this project only):
|
|
38
|
-
# .claude/skills/ -> agents/skills/*/*.skill.md (done by setup-context.sh)
|
|
38
|
+
# .claude/skills/ -> agents/skills/*/*.skill.md (done by agents/scripts/setup-context.sh)
|
|
39
39
|
|
|
40
40
|
# Global scope (all projects on this machine):
|
|
41
41
|
ln -sf /path/to/agents/skills/*/*.skill.md ~/.claude/skills/
|
|
@@ -31,3 +31,20 @@ To be used when the user requests generating diagrams onto a physical board, can
|
|
|
31
31
|
## 4. Avoiding Hallucinations
|
|
32
32
|
* **Spatial Overlap**: Agents must calculate X/Y coordinates carefully to avoid stacking nodes on top of each other. Add an arbitrary offset (e.g., +200px) per new node in a sequence.
|
|
33
33
|
* **Secret Leakage**: NEVER write API keys, database credentials, or real user data onto shared visual canvases like Miro or Figma. Redact all tokens.
|
|
34
|
+
|
|
35
|
+
## Security & Guardrails
|
|
36
|
+
|
|
37
|
+
### 1. Skill Security
|
|
38
|
+
|
|
39
|
+
* **No secrets on canvases**: Boards and design files are shared with everyone who has the link. Never place API keys, credentials, internal hostnames or real user data on them; use labelled placeholders.
|
|
40
|
+
* **Sanitize labels**: Treat user-provided node names as untrusted text. Escape them before writing `.drawio` XML or board items, so a label cannot break the file or inject markup.
|
|
41
|
+
|
|
42
|
+
### 2. System Integration Security
|
|
43
|
+
|
|
44
|
+
* **Least-privilege MCP tokens**: Give the Miro, Draw.io or Figma MCP server a token scoped to the one board or file it needs, read-only where the task only reads (Figma extraction).
|
|
45
|
+
* **Respect board permissions**: Do not change sharing settings or invite users; ask the human to do it.
|
|
46
|
+
|
|
47
|
+
### 3. LLM & Agent Guardrails
|
|
48
|
+
|
|
49
|
+
* **Draw only what exists**: Render the verified architecture from the plan or the code. Do not add components (WAF, KMS, queues) that the system does not have.
|
|
50
|
+
* **Human review before sharing**: Present the generated diagram for approval before it is posted to a shared board.
|
|
@@ -46,6 +46,23 @@ Build fast, type-safe, maintainable PHP services using the current ecosystem (ve
|
|
|
46
46
|
4. **Raise the static-analysis level** (PHPStan/Psalm) and let it fail CI; apply Rector for safe upgrades.
|
|
47
47
|
5. **Re-profile** and record the before/after numbers.
|
|
48
48
|
|
|
49
|
+
## Security & Guardrails
|
|
50
|
+
|
|
51
|
+
### 1. Skill Security
|
|
52
|
+
|
|
53
|
+
- **Parameterized queries only**: Use PDO prepared statements or the ORM's bindings; never interpolate user input into SQL, shell commands (`exec`, `shell_exec`) or `unserialize()`.
|
|
54
|
+
- **Dependency hygiene**: Run `composer audit` in CI and keep `roave/security-advisories` installed so a vulnerable package fails the install.
|
|
55
|
+
|
|
56
|
+
### 2. System Integration Security
|
|
57
|
+
|
|
58
|
+
- **Worker-mode state**: In FrankenPHP worker mode, RoadRunner or Swoole the process outlives the request. Reset per-request state (auth, tenant, static caches) so data cannot leak between users.
|
|
59
|
+
- **Production settings**: Keep `display_errors=Off` and `expose_php=Off`; load secrets from the environment, never from committed files.
|
|
60
|
+
|
|
61
|
+
### 3. LLM & Agent Guardrails
|
|
62
|
+
|
|
63
|
+
- **Measure before optimizing**: Do not enable JIT, preloading or worker mode without a before/after profile; record both numbers.
|
|
64
|
+
- **Version claims**: Check the PHP and framework versions in `composer.json` before using 8.4/8.5-only syntax.
|
|
65
|
+
|
|
49
66
|
## Sources (verified 2026-06-10)
|
|
50
67
|
- PHP 8.5 / 8.4 features: <https://www.php.net/releases/8.5/en.php> · <https://php.watch/versions>
|
|
51
68
|
- Laravel 12: <https://laravel.com/docs/12.x/releases>
|
|
@@ -653,5 +653,5 @@ the same operating spine in §5/§13 (preflight → clarify → act → state-pr
|
|
|
653
653
|
---
|
|
654
654
|
|
|
655
655
|
*Last updated: [DATE]*
|
|
656
|
-
*GABBE Kit version: 1.1.
|
|
656
|
+
*GABBE Kit version: 1.1.3*
|
|
657
657
|
*This file is maintained by the team and updated when project conventions change.*
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"_description": "Up-to-date SDK docs \u2014 prevents API hallucination. HIGHLY RECOMMENDED.",
|
|
9
9
|
"command": "npx",
|
|
10
10
|
"args": [
|
|
11
|
-
"@context7
|
|
11
|
+
"@upstash/context7-mcp"
|
|
12
12
|
],
|
|
13
13
|
"env": {}
|
|
14
14
|
},
|
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
},
|
|
24
24
|
"brave-search": {
|
|
25
25
|
"_description": "Authoritative web research with source filtering.",
|
|
26
|
+
"_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
|
|
26
27
|
"command": "npx",
|
|
27
28
|
"args": [
|
|
28
29
|
"-y",
|
|
@@ -45,6 +46,7 @@
|
|
|
45
46
|
"_section_version_control": "=== VERSION CONTROL & PROJECT MANAGEMENT ===",
|
|
46
47
|
"github": {
|
|
47
48
|
"_description": "PR review, code search, issue management, git history.",
|
|
49
|
+
"_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
|
|
48
50
|
"command": "npx",
|
|
49
51
|
"args": [
|
|
50
52
|
"-y",
|
|
@@ -54,9 +56,22 @@
|
|
|
54
56
|
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
|
|
55
57
|
}
|
|
56
58
|
},
|
|
59
|
+
"githits": {
|
|
60
|
+
"_description": "Lets the agent navigate the open-source code your app depends on — search/grep/read dependency source, docs, issues, PRs and changelogs without cloning. Prevents dependency-API hallucination. No API key.",
|
|
61
|
+
"command": "npx",
|
|
62
|
+
"args": [
|
|
63
|
+
"-y",
|
|
64
|
+
"githits@latest",
|
|
65
|
+
"mcp",
|
|
66
|
+
"start"
|
|
67
|
+
],
|
|
68
|
+
"env": {},
|
|
69
|
+
"_install": "Auto-config: `npx githits@latest init` detects your tool and wires this in. Docs: https://docs.githits.com/installation/automatic-setup (manual: /installation/manual-setup)."
|
|
70
|
+
},
|
|
57
71
|
"_section_database": "=== DATABASES ===",
|
|
58
72
|
"postgres-dev": {
|
|
59
73
|
"_description": "PostgreSQL for development \u2014 READ-WRITE allowed.",
|
|
74
|
+
"_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
|
|
60
75
|
"_security": "DEVELOPMENT ONLY \u2014 never use read-write in production",
|
|
61
76
|
"command": "npx",
|
|
62
77
|
"args": [
|
|
@@ -96,6 +111,7 @@
|
|
|
96
111
|
},
|
|
97
112
|
"postgres-prod": {
|
|
98
113
|
"_description": "PostgreSQL for production \u2014 READ-ONLY. Schema introspection only.",
|
|
114
|
+
"_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
|
|
99
115
|
"_security": "PRODUCTION \u2014 read-only access enforced by database user permissions",
|
|
100
116
|
"_enable_only_when_needed": true,
|
|
101
117
|
"command": "npx",
|
|
@@ -136,7 +152,7 @@
|
|
|
136
152
|
"command": "npx",
|
|
137
153
|
"args": [
|
|
138
154
|
"-y",
|
|
139
|
-
"@sentry/mcp"
|
|
155
|
+
"@sentry/mcp-server"
|
|
140
156
|
],
|
|
141
157
|
"env": {
|
|
142
158
|
"SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}",
|
|
@@ -180,6 +196,8 @@
|
|
|
180
196
|
"_section_infrastructure": "=== CLOUD & INFRASTRUCTURE ===",
|
|
181
197
|
"terraform": {
|
|
182
198
|
"_description": "Agentic Infrastructure as Code (IaC) via HashiCorp Terraform.",
|
|
199
|
+
"_note": "No npm package (E404 checked 2026-10-30). HashiCorp ships terraform-mcp-server as a Go binary and Docker image.",
|
|
200
|
+
"_enabled": false,
|
|
183
201
|
"command": "npx",
|
|
184
202
|
"args": [
|
|
185
203
|
"-y",
|
|
@@ -193,6 +211,7 @@
|
|
|
193
211
|
"docker": {
|
|
194
212
|
"_enabled": false,
|
|
195
213
|
"_description": "Docker daemon integration \u2014 manage containers, images, and read local logs.",
|
|
214
|
+
"_note": "No npm package (E404 checked 2026-10-30). Desktop server: use the MCP Toolkit in Docker Desktop.",
|
|
196
215
|
"command": "npx",
|
|
197
216
|
"args": [
|
|
198
217
|
"-y",
|
|
@@ -203,6 +222,7 @@
|
|
|
203
222
|
"google-cloud": {
|
|
204
223
|
"_enabled": false,
|
|
205
224
|
"_description": "Google Cloud Platform access \u2014 manage Firebase, Cloud Run, GKE, BigQuery.",
|
|
225
|
+
"_note": "No npm package (E404 checked 2026-10-30). Use Google Cloud's own MCP documentation instead of npx.",
|
|
206
226
|
"command": "npx",
|
|
207
227
|
"args": [
|
|
208
228
|
"-y",
|
|
@@ -229,6 +249,7 @@
|
|
|
229
249
|
"vercel": {
|
|
230
250
|
"_enabled": false,
|
|
231
251
|
"_description": "Vercel deployments, aliases, and serverless log integration.",
|
|
252
|
+
"_note": "No npm package (E404 checked 2026-10-30). Hosted server: use Vercel's hosted MCP; @vercel/mcp-adapter builds your own.",
|
|
232
253
|
"command": "npx",
|
|
233
254
|
"args": [
|
|
234
255
|
"-y",
|
|
@@ -241,6 +262,7 @@
|
|
|
241
262
|
"gitlab": {
|
|
242
263
|
"_enabled": false,
|
|
243
264
|
"_description": "GitLab alternative to GitHub MCP.",
|
|
265
|
+
"_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
|
|
244
266
|
"command": "npx",
|
|
245
267
|
"args": [
|
|
246
268
|
"-y",
|
|
@@ -294,6 +316,7 @@
|
|
|
294
316
|
"datadog": {
|
|
295
317
|
"_enabled": false,
|
|
296
318
|
"_description": "Monitoring, alerts, observability queries.",
|
|
319
|
+
"_note": "No npm package (E404 checked 2026-10-30). Hosted server: connect to Datadog's hosted MCP.",
|
|
297
320
|
"command": "npx",
|
|
298
321
|
"args": [
|
|
299
322
|
"-y",
|
|
@@ -307,6 +330,7 @@
|
|
|
307
330
|
"grafana": {
|
|
308
331
|
"_enabled": false,
|
|
309
332
|
"_description": "Dashboard search, datasource queries, incident management.",
|
|
333
|
+
"_note": "No npm package (E404 checked 2026-10-30). Grafana ships the Go mcp-grafana server.",
|
|
310
334
|
"command": "npx",
|
|
311
335
|
"args": [
|
|
312
336
|
"-y",
|
|
@@ -320,6 +344,7 @@
|
|
|
320
344
|
"aws-core": {
|
|
321
345
|
"_enabled": false,
|
|
322
346
|
"_description": "AWS core services \u2014 documentation, CDK, Lambda.",
|
|
347
|
+
"_note": "No npm package (E404 checked 2026-10-30). AWS ships awslabs.* servers on PyPI (run with uvx).",
|
|
323
348
|
"command": "npx",
|
|
324
349
|
"args": [
|
|
325
350
|
"-y",
|
|
@@ -361,6 +386,7 @@
|
|
|
361
386
|
"figma": {
|
|
362
387
|
"_enabled": false,
|
|
363
388
|
"_description": "UI/UX semantic understanding, component specs, and design-to-code.",
|
|
389
|
+
"_note": "No npm package (E404 checked 2026-10-30). Desktop server: enable the Dev Mode MCP server in the Figma desktop app.",
|
|
364
390
|
"command": "npx",
|
|
365
391
|
"args": [
|
|
366
392
|
"-y",
|
|
@@ -405,6 +431,7 @@
|
|
|
405
431
|
"miro": {
|
|
406
432
|
"_enabled": false,
|
|
407
433
|
"_description": "Read context from virtual whiteboards and continuously sync architecture PRDs.",
|
|
434
|
+
"_note": "No npm package (E404 checked 2026-10-30). Connect through Miro's own MCP documentation instead of npx.",
|
|
408
435
|
"command": "npx",
|
|
409
436
|
"args": [
|
|
410
437
|
"-y",
|
|
@@ -449,6 +476,7 @@
|
|
|
449
476
|
"redis": {
|
|
450
477
|
"_enabled": false,
|
|
451
478
|
"_description": "Redis interaction and key management.",
|
|
479
|
+
"_note": "Deprecated: npm marks this package 'no longer supported' (checked 2026-10-30); it still installs. Prefer an actively maintained alternative.",
|
|
452
480
|
"command": "npx",
|
|
453
481
|
"args": [
|
|
454
482
|
"-y",
|
|
@@ -508,6 +536,7 @@
|
|
|
508
536
|
"confluence": {
|
|
509
537
|
"_enabled": false,
|
|
510
538
|
"_description": "Confluence pages and spaces.",
|
|
539
|
+
"_note": "No npm package (E404 checked 2026-10-30). Use a community Atlassian server such as mcp-atlassian.",
|
|
511
540
|
"command": "npx",
|
|
512
541
|
"args": [
|
|
513
542
|
"-y",
|
|
@@ -601,6 +630,7 @@
|
|
|
601
630
|
"zapier": {
|
|
602
631
|
"_enabled": false,
|
|
603
632
|
"_description": "Connect to 6,000+ apps via Zapier.",
|
|
633
|
+
"_note": "No npm package (E404 checked 2026-10-30). Hosted server: connect to your per-user URL at mcp.zapier.com.",
|
|
604
634
|
"command": "npx",
|
|
605
635
|
"args": [
|
|
606
636
|
"-y",
|
|
@@ -653,6 +683,7 @@
|
|
|
653
683
|
"_enabled": false,
|
|
654
684
|
"_security": "DEVELOPMENT ONLY \u2014 restrict to project directory. Never enable in production.",
|
|
655
685
|
"_description": "Execute shell commands for local build, test, and system introspection (internal RAG).",
|
|
686
|
+
"_note": "No npm package (E404 checked 2026-10-30). Do not use; run shell commands through your agent's own tools.",
|
|
656
687
|
"command": "npx",
|
|
657
688
|
"args": [
|
|
658
689
|
"-y",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
**Success metric:** [How will we know this feature succeeds? e.g., "Checkout abandonment drops 15%"]
|
|
13
13
|
|
|
14
14
|
**Strategic Context (Step 0 Reference):**
|
|
15
|
-
- [BUSINESS_CASE.md
|
|
15
|
+
- [Path to BUSINESS_CASE.md or EMPATHY_MAP.md, or None]
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
package/bin/install.js
CHANGED
|
@@ -423,6 +423,8 @@ Options:
|
|
|
423
423
|
gemini, antigravity, opencode, zed, continue, roo, kilo,
|
|
424
424
|
codex, copilot, vscode.
|
|
425
425
|
--yes, -y Non-interactive: accept defaults, do not prompt.
|
|
426
|
+
--force Also refresh preserved files such as AGENTS.md and
|
|
427
|
+
CONSTITUTION.md (the old copy is backed up to .gabbe-bak).
|
|
426
428
|
--wizard Delegate to the full Python wizard (scripts/init.py) if
|
|
427
429
|
python3 is available (interactive, richer configuration).
|
|
428
430
|
--help, -h Show this help.
|
|
@@ -439,7 +441,15 @@ Examples:
|
|
|
439
441
|
`;
|
|
440
442
|
|
|
441
443
|
function parseArgs(argv) {
|
|
442
|
-
const opts = {
|
|
444
|
+
const opts = {
|
|
445
|
+
command: null,
|
|
446
|
+
agents: [],
|
|
447
|
+
yes: false,
|
|
448
|
+
wizard: false,
|
|
449
|
+
help: false,
|
|
450
|
+
force: false,
|
|
451
|
+
unknown: [],
|
|
452
|
+
};
|
|
443
453
|
for (let i = 0; i < argv.length; i++) {
|
|
444
454
|
const a = argv[i];
|
|
445
455
|
if (a === 'init') {
|
|
@@ -459,6 +469,10 @@ function parseArgs(argv) {
|
|
|
459
469
|
} else if (a.startsWith('-')) {
|
|
460
470
|
log(red(`Unknown option: ${a}`));
|
|
461
471
|
opts.help = true;
|
|
472
|
+
} else {
|
|
473
|
+
// An unknown word (e.g. `gabbe doctor`, a command of the PyPI CLI) must
|
|
474
|
+
// not fall through to the default `init` and copy the kit.
|
|
475
|
+
opts.unknown.push(a);
|
|
462
476
|
}
|
|
463
477
|
}
|
|
464
478
|
return opts;
|
|
@@ -586,6 +600,15 @@ function runInit(opts) {
|
|
|
586
600
|
|
|
587
601
|
function main() {
|
|
588
602
|
const opts = parseArgs(process.argv.slice(2));
|
|
603
|
+
if (opts.unknown.length) {
|
|
604
|
+
process.stderr.write(red(`Unknown command: ${opts.unknown.join(' ')}`) + '\n');
|
|
605
|
+
process.stderr.write(
|
|
606
|
+
'The npm package only installs the kit; `gabbe doctor` and the other CLI\n' +
|
|
607
|
+
'commands come from the PyPI package (pipx install gabbe).\n\n'
|
|
608
|
+
);
|
|
609
|
+
process.stderr.write(USAGE);
|
|
610
|
+
return 1;
|
|
611
|
+
}
|
|
589
612
|
if (opts.help) {
|
|
590
613
|
process.stdout.write(USAGE);
|
|
591
614
|
return 0;
|