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 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 SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/).
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
- - The first published open-source project world-wide that features a complete agentic coding kit/framework with cognitive brain loop, skills, SDLC workflow, etc.
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
- *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)*
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`**. The installed command is `gabbe` either way. After installing, run `gabbe doctor` for an environment + install report. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
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
- └── docs/ # Whitepapers & research
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` *(generated by `init.py`)*
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, Voting Log |
640
+ | **Coordination** | 5+ | Agent Profile, Swarm Config, Handshake, Swarm Architecture |
597
641
  | **Brain** | 5+ | Active Inference Loop, Episodic Memory, OODA Trace |
598
- | **Data** | 5+ | Data Pipeline, Database Schema, OWL Ontology |
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` *(generated by `init.py`)*
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, **Zero-Dependency CLI** (`gabbe`) 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.
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.8+
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 (Requires API Key). |
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.0*
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
  ---
@@ -184,5 +184,5 @@
184
184
  *Amended by: [team member name]*
185
185
  *Reason for amendment: [brief explanation]*
186
186
 
187
- *GABBE Kit version: 1.1.0*
187
+ *GABBE Kit version: 1.1.3*
188
188
  *This file is maintained by the team and updated when project conventions change.*
@@ -240,7 +240,7 @@ GOOD (EARS — testable):
240
240
  ```json
241
241
  {
242
242
  "mcpServers": {
243
- "context7": { "command": "npx", "args": ["@context7/mcp-server"] },
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 (`gabbe budget` / `route` / `forecast`).
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 "gabbe verify" in cmd and process.returncode != 0:
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.0*
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/mcp-server"
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](link) or [EMPATHY_MAP.md](link) or [None]
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 = { command: null, agents: [], yes: false, wizard: false, help: false, force: false };
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;