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.
@@ -32,8 +32,8 @@ AI coding agents suffer from three compounding problems:
32
32
  ## 5-Minute Setup Checklist
33
33
 
34
34
  ```bash
35
- # 1. Download & Run the Installer
36
- curl -sL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/scripts/init.py | python3 -
35
+ # 1. Download & Run the Installer (uses npx gabbe-kit init when Node is present)
36
+ curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh | sh
37
37
 
38
38
  # OR if you have the repo cloned:
39
39
  python3 GABBE/scripts/init.py
@@ -62,7 +62,7 @@ python3 GABBE/scripts/init.py
62
62
  - Open `agents/AGENTS.md`: Check `Tech Stack` section.
63
63
  - Verify `test_cmd` and `lint_cmd` match your project.
64
64
  - Open `agents/CONSTITUTION.md`: Review project laws.
65
- - Adjust Article I (Directives) if needed.
65
+ - Adjust Article I (Test-First Mandate) if needed.
66
66
 
67
67
  ## 6. Git Tracking (Important)
68
68
  - To keep the initial structure of `agents/memory/` and `project/` in your repository but prevent Git from tracking the continuous autonomous modifications your agents will make to them locally, run:
@@ -74,10 +74,10 @@ python3 GABBE/scripts/init.py
74
74
 
75
75
  ## 🚀 GABBE CLI (Experimental)
76
76
 
77
- GABBE contains a **Zero-Dependency CLI** (`gabbe`) CLI which powers the "Hybrid Mode". It bridges the gap between flexible Markdown files and a robust SQLite database. It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.
77
+ GABBE contains a **lightweight CLI** (`gabbe`; three runtime dependencies: `requests`, `PyYAML`, `jsonschema`) which powers the "Hybrid Mode". It bridges the gap between flexible Markdown files and a robust SQLite database. It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.
78
78
 
79
79
  ### Prerequisites
80
- - Python 3.8+
80
+ - Python 3.9+
81
81
  - **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
82
82
 
83
83
  **Environment Variables** (full reference in [CLI_REFERENCE.md](CLI_REFERENCE.md#environment-variables)):
@@ -129,10 +129,10 @@ python scripts/fill_placeholders.py
129
129
  | `gabbe verify --chaos` | **Resilience**: fault-injection self-checks (fail-closed tool, hard-stop, escalation). |
130
130
  | `gabbe eval` | **Skill evals**: deterministic self-check; `--live` scores via the model. |
131
131
  | `gabbe doctor` | **Autodetect**: OS/runtimes/agents + post-install MCP next-steps. |
132
- | `gabbe update` / `gabbe uninstall` | Additive refresh / manifest-backed removal (for `gabbe`-CLI-managed kits; npx/curl/wizard installs aren't manifest-tracked). |
132
+ | `gabbe update` / `gabbe uninstall` | Additive refresh / manifest-backed removal (for `gabbe`-CLI-managed kits and wizard installs; npx/curl installs aren't manifest-tracked). |
133
133
  | `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
134
134
  | `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
135
- | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key). |
135
+ | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (prompts of 100+ characters or with code blocks are rated by the LLM and need `GABBE_API_KEY`; without a key a fallback heuristic is used). |
136
136
  | `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
137
137
  | `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
138
138
  | `gabbe runs` | **Run History**: List recent agent runs with status, cost, and timestamps. |
@@ -297,7 +297,7 @@ Uses Active Inference to plan, route between local/remote models, and learn from
297
297
  ### Activate Loki Mode (Large Projects)
298
298
 
299
299
  **Using the CLI:**
300
- > `gabbe brain activate` (Loki may be triggered autonomously)
300
+ > `gabbe brain activate` prints the model's recommended next action; it does not start Loki.
301
301
  Or activate the swarm skill explicitly:
302
302
  > Activate `agents/skills/brain/loki-mode.skill.md` with your goal.
303
303
 
@@ -316,20 +316,20 @@ Multi-agent swarm with 30+ specialized personas for projects >5 features or >20
316
316
  ```
317
317
  GABBE/
318
318
  scripts/init.py <- Installer Wizard (Run this first)
319
- README_FULL.md <- Complete step-by-step guide
320
- QUICK_GUIDE.md <- This file
319
+ docs/README_FULL.md <- Complete step-by-step guide
320
+ docs/QUICK_GUIDE.md <- This file
321
321
  agents/ <- The actual kit payload
322
322
  AGENTS.md <- Universal config template
323
323
  CONSTITUTION.md <- Immutable project law
324
324
  scripts/setup-context.sh <- Internal wiring script (wrapped by scripts/init.py)
325
325
  skills/ <- 214 agent capability packages (💯)
326
- core/ <- (tdd, refactor, debug, git...)
326
+ coding/ <- (tdd, refactor, debug, git...)
327
327
  security/ <- (audit, threat-model...)
328
- arch/ <- (design, review, patterns...)
328
+ architecture/ <- (design, review, patterns...)
329
329
  templates/ <- 100 fill-in-the-blank documents
330
330
  guides/ <- 86 domain & process guides
331
- loki/
332
- docs/
331
+ personas/ <- 36 specialized roles (Loki Mode)
332
+ memory/ <- project state, continuity, audit log
333
333
  ```
334
334
 
335
335
  ---
@@ -399,7 +399,7 @@ The script detects your selected agents and generates the correct format for eac
399
399
  |---|---|---|
400
400
  | **Cursor** | `.mdc` rules | `.cursor/rules/*.mdc` |
401
401
  | **VS Code / Copilot** | Folders + Config | `.github/skills/<slug>/` |
402
- | **Claude Code** | Symlink | `.claude/skills` → `agents/skills` |
402
+ | **Claude Code** | `SKILL.md` folders | `.claude/skills/<slug>/SKILL.md` (one per skill) |
403
403
  | **Gemini / Antigravity** | Settings | `.gemini/settings.json` points to `agents/skills` |
404
404
 
405
405
  This means you write a skill once in `agents/skills/` and it runs everywhere.
@@ -657,7 +657,7 @@ Goal: Mandate SDD for all new features
657
657
  Rule: No code without an approved PRD.md
658
658
  Actions:
659
659
  - Make spec-writer.skill the entry point for all feature requests
660
- - Enforce 7-gate quality system in CI/CD
660
+ - Enforce 10-gate quality system in CI/CD
661
661
  - Track and repay tech debt with tech-debt.skill
662
662
  - Measure: specification-to-code ratio, coverage, architectural violations
663
663
  ```
@@ -678,14 +678,15 @@ Actions:
678
678
 
679
679
  | Server | Install | Why |
680
680
  |---|---|---|
681
- | **Context-7** | `npx @context7/mcp-server` | Up-to-date SDK docs (prevents API hallucination) |
681
+ | **Context-7** | `npx @upstash/context7-mcp` | Up-to-date SDK docs (prevents API hallucination) |
682
682
  | **Sequential Thinking** | `npx @modelcontextprotocol/server-sequential-thinking` | Chain-of-thought before acting |
683
683
  | **GitHub MCP** | `npx @modelcontextprotocol/server-github` | PR review, issues, code search |
684
+ | **GitHits** | `npx githits@latest init` | Navigate open-source dependency source/docs (no clone, no key) |
684
685
  | **PostgreSQL MCP** | `npx @modelcontextprotocol/server-postgres` | Live schema introspection |
685
686
  | **Semgrep MCP** | `pip install semgrep-mcp` | In-agent SAST security scanning |
686
687
  | **Brave Search MCP** | `npx @modelcontextprotocol/server-brave-search` | Authoritative web research |
687
688
  | **Playwright MCP** | `npx @playwright/mcp` | Browser automation for visual TDD |
688
- | **Sentry MCP** | `npx @sentry/mcp` | Error tracking and bug context |
689
+ | **Sentry MCP** | `npx @sentry/mcp-server` | Error tracking and bug context |
689
690
  | **Qdrant MCP** | `docker run qdrant/qdrant` + MCP server | Long-term semantic memory |
690
691
 
691
692
  See `templates/core/MCP_CONFIG_TEMPLATE.json` for the full catalog with security configuration.
@@ -745,7 +746,7 @@ If the self-healing loop frequently fails or a specific skill repeatedly produce
745
746
  ```
746
747
 
747
748
  **Using Pure Agent Mode (No CLI):**
748
- > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/react-components.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
749
+ > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/ui-gen.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
749
750
 
750
751
  ### Human-in-the-Loop — When to Pause and Ask
751
752
  ```
@@ -837,7 +838,7 @@ No human needed for:
837
838
 
838
839
  | Category | Templates |
839
840
  |---|---|
840
- | **Core** | `AGENTS`, `MCP_CONFIG`, `DEVCONTAINER`, `DEV_SPACE`, `PLAN`, `TASKS`, `AUDIT_LOG`, `SDLC_TRACKER`, `SESSION_SNAPSHOT`, `SWARM_CONFIG`, `AGENT_HANDSHAKE`, `SYSTEM_ANALYSIS`, `PROJECT_STATE`, `CONTINUITY`, `VOTING_LOG` |
841
+ | **Core** | `AGENTS`, `MCP_CONFIG`, `DEVCONTAINER`, `DEV_SPACE`, `PLAN`, `TASKS`, `AUDIT_LOG`, `SDLC_TRACKER`, `SESSION_SNAPSHOT`, `SWARM_CONFIG`, `AGENT_HANDSHAKE`, `SYSTEM_ANALYSIS` (project state, continuity and the voting log live in `agents/memory/`: `PROJECT_STATE.md`, `CONTINUITY.md`, `episodic/VOTING_LOG.md` (created at run time)) |
841
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` |
842
843
  | **Reqs** | `PRD`, `SPEC`, `BUSINESS_CASE`, `CAPABILITY_MAP`, `EMPATHY_MAP`, `NFR`, `QUALITY_ATTRIBUTES`, `REQUIREMENTS_REVIEW`, `STAKEHOLDER_REGISTER`, `TRACEABILITY_MATRIX`, `ETHICAL_IMPACT_ASSESSMENT` |
843
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` |
@@ -896,7 +897,7 @@ python3 GABBE/scripts/init.py
896
897
  *See README.md for quick reference.*
897
898
  *See README_FULL.md for full workflow guides with Mermaid diagrams.*
898
899
  *See skills/00-index.md for complete skills registry with installation instructions.*
899
- *See agents/skills/brain/README_ORCHESTRATORS.md for Loki Mode multi-agent orchestration.*
900
+ *See agents/skills/brain/loki-mode.skill.md for Loki Mode multi-agent orchestration.*
900
901
  *See agents/skills/brain/README.md for complete brain documentation.*
901
902
 
902
903
  ## 🛡️ Security & Guardrails
@@ -19,7 +19,7 @@ It contains:
19
19
  - **100 Templates** (standardized documents)
20
20
  - **86 Guides** (language & domain expertise)
21
21
  - **36 Personas** (specialized roles)
22
- - **65 MCP servers** (configuration and guides for AI tools)
22
+ - **66 MCP servers** (configuration and guides for AI tools)
23
23
  - **Brain Mode** (meta-cognitive orchestration)
24
24
  - **Loki Mode** (multi-agent swarm engineering personas team for large projects)
25
25
 
@@ -34,26 +34,28 @@ It contains:
34
34
  3. [Quick Start (5 min)](#3-quick-start-5-min)
35
35
  4. [Kit Structure Map](#4-kit-structure-map)
36
36
  5. [Workflow 1: New Project from Scratch](#5-workflow-1-new-project-from-scratch)
37
- 6. [Workflow 2: Refactoring & Bugfixing Existing Project](#6-workflow-2-refactoring-bugfixing-existing-project)
38
- 7. [Self-Healing + Research Loop](#7-self-healing-research-loop)
37
+ 6. [Workflow 2: Refactoring & Bugfixing Existing Project](#6-workflow-2-refactoring--bugfixing-existing-project)
38
+ 7. [Self-Healing + Research Loop](#7-self-healing--research-loop)
39
+ 8. [Cognitive Architecture Integration (Evolution & Healing)](#8-cognitive-architecture-integration-evolution--healing)
39
40
  9. [Multi-Agent Systems (MAS)](#9-multi-agent-systems-mas)
40
- 10. [Architecture & Design Patterns](#10-architecture-design-patterns)
41
+ 10. [Architecture & Design Patterns](#10-architecture--design-patterns)
41
42
  11. [Agentic Patterns (Advanced AI)](#11-agentic-patterns-advanced-ai)
42
43
  12. [Testing Strategy](#12-testing-strategy)
43
44
  13. [Enterprise Domains (Infra, Data, Integration)](#13-enterprise-domains-infra-data-integration)
44
- 14. [Environment & Deployment (Local/Remote/Cloud)](#14-environment-deployment-localremotecloud)
45
+ 14. [Environment & Deployment (Local/Remote/Cloud)](#14-environment--deployment-localremotecloud)
45
46
  15. [Legacy Systems (COBOL, Mainframe)](#15-legacy-systems-cobol-mainframe)
46
- 16. [Future Tech & Adaptive Skills (2026-2030)](#16-future-tech-adaptive-skills-2026-2030)
47
- 17. [System Quality & Evolution (SRE, Performance)](#17-system-quality-evolution-sre-performance)
48
- 18. [System Lifecycle & Traceability](#18-system-lifecycle-traceability)
47
+ 16. [Future Tech & Adaptive Skills (2026-2030)](#16-future-tech--adaptive-skills-2026-2030)
48
+ 17. [System Quality & Evolution (SRE, Performance)](#17-system-quality--evolution-sre-performance)
49
+ 18. [System Lifecycle & Traceability](#18-system-lifecycle--traceability)
49
50
  19. [Skills Reference](#19-skills-reference)
50
51
  20. [Templates Reference](#20-templates-reference)
51
52
  21. [MCP Configuration](#21-mcp-configuration)
52
53
  22. [Extending the Kit](#22-extending-the-kit)
53
54
  23. [Loki Mode (Large Projects)](#23-loki-mode-large-projects)
54
- 24. [Guides by Technology Stack](#24-guides-by-technology-stack)
55
- 25. [Testing & Verification](#25-testing--verification)
56
- 26. [Troubleshooting](#26-troubleshooting)
55
+ 24. [What's Inside?](#24-whats-inside)
56
+ 25. [Common Actions (Copy-Paste Prompts)](#25--common-actions-copy-paste-prompts)
57
+ 26. [Guides by Technology Stack](#26-guides-by-technology-stack)
58
+ 27. [Troubleshooting](#27-troubleshooting)
57
59
 
58
60
  ---
59
61
 
@@ -93,14 +95,18 @@ The system features a **Brain Mode** that supersedes standard execution. It uses
93
95
 
94
96
  ```bash
95
97
  # Activate Brain Mode
96
- /brain activate "Build a SaaS platform"
98
+ gabbe brain activate
97
99
  ```
98
100
 
101
+ Or ask your agent in chat: "Activate Brain Mode. Goal: Build a SaaS platform."
102
+
99
103
  ### Key Capabilities
100
104
  - **Active Inference Loop**: Continuously compares "Expected State" vs "Actual State".
101
105
  - **Dynamic Cost Routing**: Routes simple tasks to **Local LLMs** and complex ones to **Remote SOTA Models**.
102
106
  - **Episodic Memory**: Learns from past failures and successes across projects.
103
107
 
108
+ 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](adr/0002-brain-active-inference-runtime.md)).
109
+
104
110
  Read more in [AGENTS.md](../agents/AGENTS.md).
105
111
 
106
112
  ---
@@ -131,11 +137,11 @@ python3 scripts/init.py
131
137
 
132
138
  ## 3.1. GABBE CLI (experimental)
133
139
 
134
- GABBE has a **Zero-Dependency CLI** (`gabbe`) CLI which powers the "Hybrid Mode". It bridges the gap between flexible Markdown files and a robust SQLite database.
140
+ GABBE has 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.
135
141
  It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.
136
142
 
137
143
  ### Prerequisites
138
- - Python 3.8+
144
+ - Python 3.9+
139
145
  - **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
140
146
 
141
147
  **Environment Variables** (full reference in [CLI_REFERENCE.md](CLI_REFERENCE.md#environment-variables)):
@@ -160,7 +166,7 @@ It's an experimental work-in-progress and you can do without the whole package o
160
166
  | `GABBE_POLICY_FILE` | `project/policies.yml` | Path to YAML policy file for tool access control |
161
167
  | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli` (interactive), `file` (pause), `silent` (auto-reject) |
162
168
  | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout for verify shell commands (seconds) |
163
- | `GABBE_MCP_TOKEN` | *(unset)* | If set, MCP clients must provide this token to authenticate |
169
+ | `GABBE_MCP_TOKEN` | *(unset)* | MCP clients must provide this token to authenticate. While it is unset (and `GABBE_MCP_INSECURE` is off) the server refuses tool calls |
164
170
  | `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | Comma-separated list of executables permitted via MCP `run_command` |
165
171
  | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
166
172
 
@@ -187,7 +193,7 @@ gabbe --help
187
193
  | `gabbe update` / `gabbe uninstall` | **Reversible install**: additive refresh / manifest-backed removal (`--dry-run`, `--purge`, `--global`, `--dir`). |
188
194
  | `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
189
195
  | `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
190
- | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key). |
196
+ | `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). |
191
197
  | `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
192
198
  | `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
193
199
  | `gabbe runs [--status STATUS] [--limit N]` | **Run History**: List recent agent runs with status, cost, and timestamps. |
@@ -202,7 +208,7 @@ gabbe --help
202
208
  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`](PLATFORM_CONTROLS.md).
203
209
 
204
210
  ### Architecture
205
- GABBE 2.0 uses a **Hybrid Architecture** where agents and humans interact via Markdown, but the system of record is SQLite.
211
+ GABBE uses a **Hybrid Architecture** where agents and humans interact via Markdown, but the system of record is SQLite.
206
212
 
207
213
  ```mermaid
208
214
  graph TD
@@ -352,7 +358,7 @@ Uses Active Inference to plan, route between local/remote models, and learn from
352
358
  ### Activate Loki Mode (Large Projects)
353
359
 
354
360
  **Using the CLI:**
355
- > `gabbe brain activate` (Loki may be triggered autonomously by the Brain based on context cost).
361
+ > `gabbe brain activate` prints the model's recommended next action; it does not start Loki. Start Loki with the skill below.
356
362
  Or activate the swarm skill explicitly:
357
363
  > Activate `agents/skills/brain/loki-mode.skill.md` with your goal.
358
364
 
@@ -406,7 +412,7 @@ graph TB
406
412
  L --> M1
407
413
  end
408
414
  subgraph "Templates Layer"
409
- T[templates/<br/>60+ fill-in-the-blank docs]
415
+ T[templates/<br/>100 fill-in-the-blank docs]
410
416
  end
411
417
  ```
412
418
 
@@ -552,7 +558,7 @@ flowchart TD
552
558
  B1 -->|Yes — resuming| C[Load all memory + project state]
553
559
  B1 -->|No — first time| D[Initialize kit]
554
560
 
555
- D --> D1[setup-context.sh]
561
+ D --> D1[agents/scripts/setup-context.sh]
556
562
  D1 --> D2[Adapt AGENTS.md]
557
563
  D2 --> D3[Run audit skills]
558
564
 
@@ -612,7 +618,7 @@ flowchart TD
612
618
  cp -r ~/agents/ ./
613
619
 
614
620
  # 2. Wire up context
615
- agents/setup-context.sh
621
+ agents/scripts/setup-context.sh
616
622
 
617
623
  # 3. Adapt AGENTS.md
618
624
  # - Set tech stack, test commands, lint commands
@@ -682,7 +688,7 @@ GABBE's true power lies in its **Meta-Cognitive triad**: Active Inference (`acti
682
688
 
683
689
  ### 8.1. Sensory MCPs to Working Memory
684
690
  When an agent uses a sensory tool (like `visual-specs` or `excalidraw`), the parsed visual context is directly committed to the `WORKING_MEMORY.md`.
685
- When `gabbe route` or `gabbe brain activate` runs, the **Cost-Benefit Router** actively reads this memory. If the visual data is highly complex, the router will automatically escalate the task to a **REMOTE** LLM to preserve reasoning quality, overriding local restrictions.
691
+ The `gabbe` CLI does not read `WORKING_MEMORY.md`; routing by `gabbe route` uses the prompt text only.
686
692
 
687
693
  ### 8.2. Enforcing Brain Mode (`activate`)
688
694
  Brain Mode should be integrated into your development loop after significant milestones:
@@ -709,13 +715,13 @@ gabbe brain evolve --skill code-review
709
715
  ```
710
716
 
711
717
  **Using Pure Agent Mode (No CLI):**
712
- > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/react-components.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
718
+ > "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`."
713
719
 
714
720
  ### 8.4. Self-Healing Enforcement (`heal`)
715
721
  The healing protocol acts as an infrastructure watchdog to recover from failures.
716
722
 
717
723
  **Using the CLI:**
718
- Checks for missing files (`AGENTS.md`, `CONSTITUTION.md`), corrupted SQLite databases, and network reachability. Run this in your CI/CD pipeline.
724
+ Checks that the database is reachable and that `agents/AGENTS.md`, `agents/CONSTITUTION.md` and `project/TASKS.md` exist. Run this in your CI/CD pipeline.
719
725
  ```bash
720
726
  gabbe brain heal
721
727
  ```
@@ -728,7 +734,7 @@ gabbe brain heal
728
734
  This kit includes specialized tools for building orchestrator-worker swarms and complex agent topologies.
729
735
 
730
736
  **Key Resources:**
731
- - **Guide**: `guides/multi-agent-systems.md` — Full development patterns & stack integration.
737
+ - **Guide**: `guides/ai/multi-agent-systems.md` — Full development patterns & stack integration.
732
738
  - **Skill**: `multi-agent-orch` — Plan and orchestrate agent swarms.
733
739
  - **Skill**: `agent-protocol` — Define inter-agent communication schemas.
734
740
  - **Template**: `AGENT_PROFILE_TEMPLATE.md` — Define roles and personalities.
@@ -752,7 +758,7 @@ Embeds 2025-standard patterns into your workflow.
752
758
  - **Template**: `ARCH_DECISION_FRAMEWORK.md` — Matrix for Architectural decision making.
753
759
  - **Template**: `DESIGN_PATTERN_USAGE.md` — Justify complex pattern choices.
754
760
  - **Template**: `CLEAN_CODE_CHECKLIST.md` — Quality gate for PRs.
755
- - **Guide**: `guides/design-patterns.md` — Catalog of modern patterns.
761
+ - **Guide**: `guides/patterns/design-patterns.md` — Catalog of modern patterns.
756
762
 
757
763
  ---
758
764
 
@@ -763,7 +769,7 @@ Tools for building self-correcting, planning, and memory-augmented agents.
763
769
  **Key Resources:**
764
770
  - **Skill**: `agentic-patterns` — Implements Reflection, ReAct, and Planning loops.
765
771
  - **Template**: `ETHICAL_IMPACT_ASSESSMENT.md` — AI Safety & Bias check.
766
- - **Guide**: `guides/agentic-patterns.md` — Deep dive into cognitive architectures.
772
+ - **Guide**: `guides/patterns/agentic-patterns.md` — Deep dive into cognitive architectures.
767
773
 
768
774
  ---
769
775
 
@@ -773,7 +779,7 @@ Comprehensive testing resources using Pyramid or Trophy models.
773
779
 
774
780
  **Key Resources:**
775
781
  - **Skill**: `testing-strategy` — Orchestrate Unit, Integration, E2E, and Contract testing.
776
- - **Guide**: `guides/testing-strategy.md` — Complete guide to modern testing patterns.
782
+ - **Guide**: `guides/principles/testing-strategy.md` — Complete guide to modern testing patterns.
777
783
  - **Template**: `TEST_PLAN_TEMPLATE.md` — Master test plan document.
778
784
  - **Template**: `TEST_CASE_TEMPLATE.md` — Detailed test case definition.
779
785
  - **Template**: `E2E_TEST_SUITE_TEMPLATE.md` — High-level E2E scenarios.
@@ -794,7 +800,7 @@ Specialized resources for specialized domains.
794
800
 
795
801
  ### Enterprise Integration
796
802
  - **Skill**: `enterprise-integration` (ERP, CRM, Legacy patterns).
797
- - **Guide**: `guides/enterprise-patterns.md` (Strangler Fig, ACL).
803
+ - **Guide**: `guides/patterns/enterprise-patterns.md` (Strangler Fig, ACL).
798
804
  - **Template**: `INTEGRATION_SPEC_TEMPLATE.md`.
799
805
 
800
806
  ---
@@ -814,7 +820,7 @@ Tools for the full lifecycle: from localhost to production.
814
820
  ### Cloud Deployment (Outer Loop)
815
821
  - **Skill**: `cloud-deploy` (Vercel, Railway, AWS SST).
816
822
  - **Template**: `DEPLOY_CONFIG_TEMPLATE.md`.
817
- - **Guide**: `guides/dev-environments.md`.
823
+ - **Guide**: `guides/ops/dev-environments.md`.
818
824
 
819
825
  ---
820
826
 
@@ -825,7 +831,7 @@ Tools for the full lifecycle: from localhost to production.
825
831
  ### Modernization
826
832
  - **Skill**: `legacy-modernization` (COBOL analysis, Strangler Fig).
827
833
  - **Template**: `LEGACY_AUDIT_TEMPLATE.md` (Risk & Knowledge audit).
828
- - **Guide**: `guides/legacy-tech.md` (Mainframe DevOps, COBOL basics).
834
+ - **Guide**: `guides/principles/legacy-tech.md` (Mainframe DevOps, COBOL basics).
829
835
 
830
836
  ---
831
837
 
@@ -837,7 +843,7 @@ Preparing for the next wave: 6G, Agentic IoT, and Evolutionary Architecture.
837
843
  - **Skill**: `emerging-tech` (6G, Matter, Vector Databases).
838
844
  - **Skill**: `adaptive-architecture` (Local-First, WASM, CRDTs).
839
845
  - **Template**: `ADAPTIVE_SYSTEM_TEMPLATE.md` (Evolutionary design).
840
- - **Guide**: `guides/future-tech.md` (The 2030 Horizon).
846
+ - **Guide**: `guides/principles/future-tech.md` (The 2030 Horizon).
841
847
 
842
848
  ---
843
849
 
@@ -855,7 +861,7 @@ Resources for ensuring your software is reliable, fast, and adaptable.
855
861
  - **Template**: `SAFETY_CASE.md` (Critical system assurance).
856
862
  - **Template**: `COST_OPTIMIZATION_REPORT_TEMPLATE.md` (FinOps).
857
863
  - **Template**: `INCIDENT_POSTMORTEM_TEMPLATE.md` (Blameless analysis).
858
- - **Guide**: `guides/system-qualities.md` (The "Ilities").
864
+ - **Guide**: `guides/architecture/system-qualities.md` (The "Ilities").
859
865
 
860
866
  ---
861
867
 
@@ -868,7 +874,7 @@ Resources for binding Requirements to Code and Tests (The Golden Thread).
868
874
 
869
875
  ### Documentation
870
876
  - **Template**: `TRACEABILITY_MATRIX_TEMPLATE.md` (Live status of requirements).
871
- - **Guide**: `guides/full-system-lifecycle.md` (Definition of Done).
877
+ - **Guide**: `guides/processes/full-system-lifecycle.md` (Definition of Done).
872
878
 
873
879
  ---
874
880
 
@@ -1100,8 +1106,8 @@ All templates now live in categorized subdirectories under `agents/templates/`.
1100
1106
  | `core/SESSION_SNAPSHOT_TEMPLATE.md` | Complete project state |
1101
1107
  | `core/TRACEABILITY_MATRIX_TEMPLATE.md` | Traceability Matrix | Req -> Code -> Test trace |
1102
1108
  | `core/BUG_REPORT_TEMPLATE.md` | Bug Report | Structured bug reporting |
1103
- | `core/PROJECT_STATE_TEMPLATE.md` | Project State | Current SDLC phase & status |
1104
- | `core/CONTINUITY_TEMPLATE.md` | Continuity Log | Past failure prevention log |
1109
+ | `agents/memory/PROJECT_STATE.md` | Project State | Current SDLC phase & status |
1110
+ | `agents/memory/CONTINUITY.md` | Continuity Log | Past failure prevention log |
1105
1111
 
1106
1112
  ### Coordination & Brain (`templates/coordination/`, `templates/brain/`)
1107
1113
  | Template | Purpose |
@@ -1110,7 +1116,7 @@ All templates now live in categorized subdirectories under `agents/templates/`.
1110
1116
  | `coordination/SWARM_CONFIG_TEMPLATE.json` | Multi-agent configuration |
1111
1117
  | `coordination/AGENT_PROFILE_TEMPLATE.md` | Agent Profile | Persona definition |
1112
1118
  | `coordination/AGENT_HANDSHAKE_TEMPLATE.json` | Agent Handshake | Protocol negotiation |
1113
- | `coordination/VOTING_LOG_TEMPLATE.md` | Agent Consensus Voting Record |
1119
+ | `agents/memory/episodic/VOTING_LOG.md` (created by `swarm-consensus`; no template file) | Agent Consensus Voting Record |
1114
1120
  | `coordination/SWARM_ARCHITECTURE_TEMPLATE.md` | Swarm Architecture | Multi-agent topology |
1115
1121
  | `brain/ACTIVE_INFERENCE_LOOP_TEMPLATE.md` | Cognitive loop structure |
1116
1122
  | `brain/GLOBAL_WORKSPACE_CONFIG_TEMPLATE.md` | GWT Blackboard config |
@@ -1140,7 +1146,7 @@ All templates now live in categorized subdirectories under `agents/templates/`.
1140
1146
  | `architecture/SCALABILITY_ANALYSIS_TEMPLATE.md` | Architecture | Scalability bottleneck analysis |
1141
1147
  | `architecture/SMART_CONTRACT_TEMPLATE.md` | Blockchain | Smart contract logic & security |
1142
1148
  | `architecture/ARCHITECTURE_DECISION_MATRIX.md` | Architecture | Scoring matrix for trade-offs |
1143
- | `core/PROJECT_CONTEXT_TEMPLATE.md` | Core | Holistic project context for agents |
1149
+ | `brain/PROJECT_CONTEXT_TEMPLATE.md` | Core | Holistic project context for agents |
1144
1150
  | `product/PROBLEM_STATEMENT_TEMPLATE.md` | Product | Problem definition (EARS subset) |
1145
1151
  | `product/IDEATION_LOG_TEMPLATE.md` | Product | Brainstorming & outcome log |
1146
1152
 
@@ -1158,6 +1164,7 @@ MCP (Model Context Protocol) servers extend agent capabilities. Configure them i
1158
1164
  | **Docs** | Context-7 MCP | Up-to-date SDK docs (prevents API hallucination) |
1159
1165
  | **Reasoning** | Sequential Thinking | Chain-of-thought before acting |
1160
1166
  | **Code Search** | GitHub MCP | PR review, code search, issue management |
1167
+ | **Dependencies** | GitHits MCP | Navigate open-source dependency source/docs (no clone, no key) |
1161
1168
  | **Database** | PostgreSQL MCP | Live schema introspection |
1162
1169
  | **Security** | Semgrep MCP | SAST scanning from within the agent |
1163
1170
  | **Web Search** | Brave Search / Tavily | Authoritative source research |
@@ -1170,7 +1177,7 @@ MCP (Model Context Protocol) servers extend agent capabilities. Configure them i
1170
1177
  | **Canvas** | tldraw MCP | Persistent visual canvas for wireframing |
1171
1178
  | **Filesystem** | Filesystem MCP | Local file access for internal RAG |
1172
1179
 
1173
- **Full coverage matrix** (65 MCP servers in `MCP_CONFIG_TEMPLATE.json`):
1180
+ **Full coverage matrix** (66 MCP servers in `MCP_CONFIG_TEMPLATE.json`):
1174
1181
 
1175
1182
  | Integration Domain | Servers Available |
1176
1183
  |---|---|
@@ -1182,6 +1189,7 @@ MCP (Model Context Protocol) servers extend agent capabilities. Configure them i
1182
1189
  | **Observability** | Sentry, Datadog, Grafana |
1183
1190
  | **Code Quality** | Semgrep, Snyk, SonarQube, Gitleaks, Time Complexity |
1184
1191
  | **Project Mgmt** | GitHub, GitLab, Jira, Linear, Notion, Confluence, Slack |
1192
+ | **Dependencies** | GitHits (navigate open-source dependency source, docs, issues, changelogs) |
1185
1193
  | **Cloud/Infra** | AWS Core, Kubernetes, Figma |
1186
1194
 
1187
1195
  **Security rules:**
@@ -1218,7 +1226,7 @@ See [MCP_CONFIGURATIONS.md](MCP_CONFIGURATIONS.md) for comprehensive per-server
1218
1226
  ## Instructions
1219
1227
  [Detailed steps for the agent to follow]
1220
1228
  ```
1221
- 3. **Register:** Run `scripts/init.py` (or `agents/setup-context.sh`) to symlink changes.
1229
+ 3. **Register:** Run `scripts/init.py` (or `agents/scripts/setup-context.sh`) to symlink changes.
1222
1230
 
1223
1231
  ### Adding Custom MCP Servers
1224
1232
 
@@ -1319,7 +1327,7 @@ Copy and paste these exact prompts into your AI chat window to kick off standard
1319
1327
  ### Activate Loki Mode (Large Projects)
1320
1328
 
1321
1329
  **Using the CLI:**
1322
- > `gabbe brain activate` (Loki may be triggered autonomously by the Brain based on context cost).
1330
+ > `gabbe brain activate` prints the model's recommended next action; it does not start Loki. Start Loki with the skill below.
1323
1331
  Or activate the swarm skill explicitly:
1324
1332
  > Activate `agents/skills/brain/loki-mode.skill.md` with your goal.
1325
1333
 
@@ -1334,7 +1342,7 @@ Or activate the swarm skill explicitly:
1334
1342
 
1335
1343
  | Guide | Stack | Key Topics |
1336
1344
  |---|---|---|
1337
- | `guides/principles/full-system-lifecycle.md` | Process/SDLC | Traceability, Golden Thread, DoD |
1345
+ | `guides/processes/full-system-lifecycle.md` | Process/SDLC | Traceability, Golden Thread, DoD |
1338
1346
  | `guides/architecture/system-qualities.md` | Architecture/Ops | Reliability, SRE, Scalability |
1339
1347
  | `guides/ops/production-health.md` | Ops/SRE | Health Checks & Monitoring |
1340
1348
  | `guides/principles/future-tech.md` | Future/2030 | 6G, IoT Matter, Vector DBs, WASM |
@@ -1351,7 +1359,7 @@ Or activate the swarm skill explicitly:
1351
1359
  | `guides/patterns/ai-native-scenarios.md` | AI/Agentic | Vibe-to-Code, Auto-Patching, DB Refactor |
1352
1360
  | `guides/patterns/enterprise-migration-scenario.md` | Enterprise | Strangler Fig, Migration paths |
1353
1361
 
1354
- | `guides/principles/RARV_CYCLE.md` | AI/Agentic | Reason-Act-Reflect-Verify loop |
1362
+ | `guides/processes/RARV_CYCLE.md` | AI/Agentic | Reason-Act-Reflect-Verify loop |
1355
1363
  | `guides/ai/self-healing-summary.md` | AI/Agentic | Self-healing architecture & loops |
1356
1364
  | `guides/languages/js-ts-nodejs.md` | Python/Node/React | Swarms, Orchestration, A2A Protocol |
1357
1365
  | `guides/patterns/autonomous-swarm-patterns.md` | AI/Agentic | Self-organizing Swarm Patterns |
@@ -1372,7 +1380,7 @@ Or activate the swarm skill explicitly:
1372
1380
 
1373
1381
  | `guides/ops/compliance-audit.md` | Compliance & Audit | GDPR, SOC2 logging, Privacy Engineering |
1374
1382
  | `guides/ops/troubleshooting-guide.md` | Ops | Debugging, Root Cause, Recovery |
1375
- | `guides/ops/self-healing-summary.md` | Ops | Automated recovery patterns |
1383
+ | `guides/ai/self-healing-summary.md` | Ops | Automated recovery patterns |
1376
1384
 
1377
1385
  | `guides/ai/ai-agentic.md` | AI/Agentic | RARV, SDD lifecycle, Memory Architecture, MCP config |
1378
1386
  | `guides/architecture/microservices.md` | Microservices | Bounded contexts, event-driven, contract testing |
@@ -1394,12 +1402,12 @@ Or activate the swarm skill explicitly:
1394
1402
  ### Subject-Specific Guides
1395
1403
  | Topic | Guide |
1396
1404
  |---|---|
1397
- | **Product** | `guides/product-requirements.md` (PRD/Spec), `guides/strategic-analysis.md` (Strategy) |
1398
- | **Architecture** | `guides/critical-systems-arch.md`, `guides/event-driven-architecture.md` |
1399
- | **Integration** | `guides/knowledge-integration.md`, `guides/no-code-integration.md`, `guides/api-standards.md` |
1400
- | **Agents** | `guides/actor-agent-frameworks.md`, `guides/autonomous-swarm-patterns.md`, `guides/agent-communication.md` |
1401
- | **UI/UX** | `guides/visual-design-system.md`, `guides/a2ui-protocols.md`, `guides/agent-ui.md` |
1402
- | **Lifecycle** | `guides/production-health.md`, `guides/beyond-llms.md` |
1405
+ | **Product** | `guides/planning/product-requirements.md` (PRD/Spec), `guides/planning/strategic-analysis.md` (Strategy) |
1406
+ | **Architecture** | `guides/architecture/critical-systems-arch.md`, `guides/architecture/event-driven-architecture.md` |
1407
+ | **Integration** | `guides/processes/knowledge-integration.md`, `guides/principles/no-code-integration.md`, `guides/architecture/api-standards.md` |
1408
+ | **Agents** | `guides/ai/actor-agent-frameworks.md`, `guides/patterns/autonomous-swarm-patterns.md`, `guides/ai/agent-communication.md` |
1409
+ | **UI/UX** | `guides/principles/visual-design-system.md`, `guides/ai/a2ui-protocols.md`, `guides/ai/agent-ui.md` |
1410
+ | **Lifecycle** | `guides/ops/production-health.md`, `guides/ai/beyond-llms.md` |
1403
1411
  | **Industry** | `guides/industry/engineering-standards.md`, `guides/industry/global-standards.md`, `guides/industry/telecom-networks.md` |
1404
1412
 
1405
1413
  ---
@@ -1407,7 +1415,7 @@ Or activate the swarm skill explicitly:
1407
1415
  ## 27. Troubleshooting
1408
1416
 
1409
1417
  **Agent ignores AGENTS.md:**
1410
- - Run `setup-context.sh` to create tool-specific symlinks
1418
+ - Run `agents/scripts/setup-context.sh` to create tool-specific symlinks
1411
1419
  - For Cursor: verify `.cursorrules` file exists (symlink created by setup script)
1412
1420
  - For Claude Code: verify `.claude/CLAUDE.md` exists
1413
1421
 
@@ -1429,7 +1437,7 @@ Or activate the swarm skill explicitly:
1429
1437
 
1430
1438
  **Agent makes architecture decisions without asking:**
1431
1439
  - Add to AGENTS.md Human-in-the-Loop section: "Architecture changes require human approval"
1432
- - Check `CONSTITUTION.md` — Article VII should cover this
1440
+ - Check `CONSTITUTION.md` — Article VIII should cover this
1433
1441
 
1434
1442
  **Context window too large / slow responses:**
1435
1443
  - Use `context_cost: low` skills for routine tasks
@@ -1442,8 +1450,8 @@ Or activate the swarm skill explicitly:
1442
1450
 
1443
1451
  *See README.md for quick reference.*
1444
1452
  *See skills/00-index.md for complete skills registry with installation instructions.*
1445
- *See agents/skills/brain/README_ORCHESTRATORS.md for Loki Mode multi-agent orchestration.*
1446
- *See agents/skills/brain/README.md and README_ORCHESTRATORS.md for complete brain documentation.*
1453
+ *See agents/skills/brain/loki-mode.skill.md for Loki Mode multi-agent orchestration.*
1454
+ *See agents/skills/brain/README.md for complete brain documentation.*
1447
1455
 
1448
1456
 
1449
1457
  ---