gabbe-kit 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
 
@@ -1220,7 +1226,7 @@ See [MCP_CONFIGURATIONS.md](MCP_CONFIGURATIONS.md) for comprehensive per-server
1220
1226
  ## Instructions
1221
1227
  [Detailed steps for the agent to follow]
1222
1228
  ```
1223
- 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.
1224
1230
 
1225
1231
  ### Adding Custom MCP Servers
1226
1232
 
@@ -1321,7 +1327,7 @@ Copy and paste these exact prompts into your AI chat window to kick off standard
1321
1327
  ### Activate Loki Mode (Large Projects)
1322
1328
 
1323
1329
  **Using the CLI:**
1324
- > `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.
1325
1331
  Or activate the swarm skill explicitly:
1326
1332
  > Activate `agents/skills/brain/loki-mode.skill.md` with your goal.
1327
1333
 
@@ -1336,7 +1342,7 @@ Or activate the swarm skill explicitly:
1336
1342
 
1337
1343
  | Guide | Stack | Key Topics |
1338
1344
  |---|---|---|
1339
- | `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 |
1340
1346
  | `guides/architecture/system-qualities.md` | Architecture/Ops | Reliability, SRE, Scalability |
1341
1347
  | `guides/ops/production-health.md` | Ops/SRE | Health Checks & Monitoring |
1342
1348
  | `guides/principles/future-tech.md` | Future/2030 | 6G, IoT Matter, Vector DBs, WASM |
@@ -1353,7 +1359,7 @@ Or activate the swarm skill explicitly:
1353
1359
  | `guides/patterns/ai-native-scenarios.md` | AI/Agentic | Vibe-to-Code, Auto-Patching, DB Refactor |
1354
1360
  | `guides/patterns/enterprise-migration-scenario.md` | Enterprise | Strangler Fig, Migration paths |
1355
1361
 
1356
- | `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 |
1357
1363
  | `guides/ai/self-healing-summary.md` | AI/Agentic | Self-healing architecture & loops |
1358
1364
  | `guides/languages/js-ts-nodejs.md` | Python/Node/React | Swarms, Orchestration, A2A Protocol |
1359
1365
  | `guides/patterns/autonomous-swarm-patterns.md` | AI/Agentic | Self-organizing Swarm Patterns |
@@ -1374,7 +1380,7 @@ Or activate the swarm skill explicitly:
1374
1380
 
1375
1381
  | `guides/ops/compliance-audit.md` | Compliance & Audit | GDPR, SOC2 logging, Privacy Engineering |
1376
1382
  | `guides/ops/troubleshooting-guide.md` | Ops | Debugging, Root Cause, Recovery |
1377
- | `guides/ops/self-healing-summary.md` | Ops | Automated recovery patterns |
1383
+ | `guides/ai/self-healing-summary.md` | Ops | Automated recovery patterns |
1378
1384
 
1379
1385
  | `guides/ai/ai-agentic.md` | AI/Agentic | RARV, SDD lifecycle, Memory Architecture, MCP config |
1380
1386
  | `guides/architecture/microservices.md` | Microservices | Bounded contexts, event-driven, contract testing |
@@ -1396,12 +1402,12 @@ Or activate the swarm skill explicitly:
1396
1402
  ### Subject-Specific Guides
1397
1403
  | Topic | Guide |
1398
1404
  |---|---|
1399
- | **Product** | `guides/product-requirements.md` (PRD/Spec), `guides/strategic-analysis.md` (Strategy) |
1400
- | **Architecture** | `guides/critical-systems-arch.md`, `guides/event-driven-architecture.md` |
1401
- | **Integration** | `guides/knowledge-integration.md`, `guides/no-code-integration.md`, `guides/api-standards.md` |
1402
- | **Agents** | `guides/actor-agent-frameworks.md`, `guides/autonomous-swarm-patterns.md`, `guides/agent-communication.md` |
1403
- | **UI/UX** | `guides/visual-design-system.md`, `guides/a2ui-protocols.md`, `guides/agent-ui.md` |
1404
- | **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` |
1405
1411
  | **Industry** | `guides/industry/engineering-standards.md`, `guides/industry/global-standards.md`, `guides/industry/telecom-networks.md` |
1406
1412
 
1407
1413
  ---
@@ -1409,7 +1415,7 @@ Or activate the swarm skill explicitly:
1409
1415
  ## 27. Troubleshooting
1410
1416
 
1411
1417
  **Agent ignores AGENTS.md:**
1412
- - Run `setup-context.sh` to create tool-specific symlinks
1418
+ - Run `agents/scripts/setup-context.sh` to create tool-specific symlinks
1413
1419
  - For Cursor: verify `.cursorrules` file exists (symlink created by setup script)
1414
1420
  - For Claude Code: verify `.claude/CLAUDE.md` exists
1415
1421
 
@@ -1431,7 +1437,7 @@ Or activate the swarm skill explicitly:
1431
1437
 
1432
1438
  **Agent makes architecture decisions without asking:**
1433
1439
  - Add to AGENTS.md Human-in-the-Loop section: "Architecture changes require human approval"
1434
- - Check `CONSTITUTION.md` — Article VII should cover this
1440
+ - Check `CONSTITUTION.md` — Article VIII should cover this
1435
1441
 
1436
1442
  **Context window too large / slow responses:**
1437
1443
  - Use `context_cost: low` skills for routine tasks
@@ -1444,8 +1450,8 @@ Or activate the swarm skill explicitly:
1444
1450
 
1445
1451
  *See README.md for quick reference.*
1446
1452
  *See skills/00-index.md for complete skills registry with installation instructions.*
1447
- *See agents/skills/brain/README_ORCHESTRATORS.md for Loki Mode multi-agent orchestration.*
1448
- *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.*
1449
1455
 
1450
1456
 
1451
1457
  ---
package/docs/ROADMAP.md CHANGED
@@ -14,7 +14,7 @@ Today almost every gate and rule in the kit is enforced only by the agent readin
14
14
 
15
15
  | Rule | Enforced today by | A hook can add |
16
16
  |---|---|---|
17
- | The agent never commits, pushes, tags, publishes or deploys unless told to in that request | prose (AGENTS.md, CONSTITUTION Article XIII) | a block on the git and publish commands before they run |
17
+ | The agent never commits, pushes, tags, publishes or deploys unless told to in that request | nothing yet: not stated in AGENTS.md or CONSTITUTION.md | a block on the git and publish commands before they run |
18
18
  | Protected files (the constitution, AGENTS.md, golden baselines, lockfiles, CI) are not edited | prose; `protected_files` in `project/gabbe.config.json` is read by no code | a block on edits to the configured globs |
19
19
  | Checks run on the final tree before work is reported as done | prose (Step 7 of the operating spine) | a refusal to end the turn when files changed after the last green run |
20
20
  | The session is recorded in memory before it ends | prose (AGENTS.md section 13) | a refusal to end the turn after edits when no memory file was updated; the resume pointer injected at session start |
@@ -96,3 +96,5 @@ The forge stays the final layer for every agent: a required CI check on the defa
96
96
  ## 2. `gabbe verify` exit code
97
97
 
98
98
  `gabbe verify` prints "Verification FAILED" and still exits 0 (`gabbe/main.py` ignores the result of `run_verification()`; only `--chaos` exits 1). Anyone who runs it in CI, as the full guide suggests, gets a green job on a failed check. Fix: exit 1 when the verification fails, with a test. This is independent of the hooks and comes first.
99
+
100
+ Done in 1.1.2: `gabbe verify` now exits 1 when verification fails (see the [CHANGELOG](../CHANGELOG.md)).
@@ -1,8 +1,10 @@
1
1
  <!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
2
2
  # GABBE v1.0 Release Checklist
3
3
 
4
+ Historical: the acceptance gate used for v1.0.0 (released 2026-06-17). The current release procedure is in [CONTRIBUTING.md](../CONTRIBUTING.md#releasing).
5
+
4
6
  A human-runnable release gate that mirrors the v1.0 acceptance matrix in
5
- `GABBE-v1.0-MASTER-PLAN.md`. Tag `v1.0.0` only when **every** box below is
7
+ `GABBE-v1.0-MASTER-PLAN.md` (the maintainer's plan, kept outside the repository). Tag `v1.0.0` only when **every** box below is
6
8
  ticked on a clean checkout and in CI. No item may be waived.
7
9
 
8
10
  Run all commands from the repository root. Each section maps to one acceptance
@@ -81,8 +83,8 @@ gabbe verify --chaos # all fault-injection self-
81
83
  ## 5. Compatibility & emission proven (works standalone, every target agent)
82
84
 
83
85
  ```bash
84
- # For each supported client (claude, cursor, copilot, gemini, codex, + new additive ones):
85
- python3 agents/scripts/compile_skills.py --platform <client> --skills-dir agents/skills --target-dir /tmp/gabbe-<client>
86
+ # For each platform: Cursor, "VS Code", "GitHub Copilot", "Claude Code", Antigravity, OpenCode, Universal (or All):
87
+ python3 agents/scripts/compile_skills.py --platform "<platform>" --skills-dir agents/skills --target-dir /tmp/gabbe-out --project-root /tmp/gabbe-proj
86
88
  python3 scripts/init.py # (or: npx gabbe-kit init) — clean init succeeds end-to-end with new content
87
89
  ```
88
90
 
@@ -11,7 +11,7 @@
11
11
  Before running tests or launching verifiers, ensure the project development environment is correctly bootstrapped.
12
12
 
13
13
  ### Prerequisites:
14
- - **Python:** versions 3.8 to 3.12 support the GABBE framework and test runners.
14
+ - **Python:** versions 3.9 to 3.13 support the GABBE framework and test runners.
15
15
  - **Node.js**: Expected by specific NPM-based tools or workflows, though Python is the framework root.
16
16
 
17
17
  ### Installation:
@@ -25,7 +25,7 @@ pip install -e ".[dev]"
25
25
 
26
26
  *Optionally*, establish environment secrets to verify API-driven paths (Required for executing the `gabbe brain`, `gabbe route`, and specific integration scenarios):
27
27
  ```bash
28
- cp .env.example .env
28
+ # Either export the key, or put the same line (without `export`) in a gitignored .env
29
29
  export GABBE_API_KEY="sk-..." # Add remote LLM keys for deep integration
30
30
  ```
31
31
 
@@ -35,7 +35,7 @@ export GABBE_API_KEY="sk-..." # Add remote LLM keys for deep integration
35
35
 
36
36
  The heart of the GABBE orchestration, database integration, memory access, and MCP translation occurs in the `gabbe/` module. The core tests target its routing (`route.py`), budget control (`budget.py`), orchestration logic (`brain.py`), and subprocess checking logic (`verify.py`).
37
37
 
38
- **Run the Full Suite (570+ tests):**
38
+ **Run the Full Suite (860+ tests):**
39
39
  ```bash
40
40
  # Discovers all tests in gabbe/tests and scripts/tests
41
41
  pytest
@@ -152,7 +152,7 @@ A series of purpose-built Python compilation scripts ensure that your modificati
152
152
 
153
153
  **Check Structural Integrity:**
154
154
  ```bash
155
- # Checks if skills, templates, guides are valid and that `agents/AGENTS.md` matches `AGENTS_TEMPLATE.md` structures.
155
+ # Checks that the required kit files and folders exist, that the Python scripts compile, and that the template folders are present.
156
156
  python3 agents/scripts/validate_integrity.py
157
157
  ```
158
158
 
@@ -186,8 +186,9 @@ python3 agents/scripts/verify_setup_simulation.py
186
186
 
187
187
  **Run Everything in One Pass:**
188
188
  ```bash
189
- # Umbrella runner aggregating logs across all structural checkers
190
- bash agents/scripts/setup-context.sh
189
+ # One-stop runner: lint + type-check, the test suite, the gates, the kit validators,
190
+ # the registry round-trip and the install smoke tests (see TESTING.md)
191
+ bash scripts/verify_all.sh
191
192
  ```
192
193
 
193
194
  ---
@@ -271,7 +272,7 @@ Upon passing all elements in this guide, the framework is confirmed 100% operati
271
272
 
272
273
  | Check | Command | Expected Result |
273
274
  |---|---|---|
274
- | Full test suite | `pytest` | All pass, 0 failures (570+ tests) |
275
+ | Full test suite | `pytest` | All pass, 0 failures (860+ tests) |
275
276
  | Structural integrity | `python3 agents/scripts/validate_integrity.py` | Project integrity check passed |
276
277
  | Link validation | `python3 agents/scripts/validate_links.py` | All links valid |
277
278
  | Skills validation | `python3 agents/scripts/validate_skills.py` | All 214 skills passed |
@@ -1,19 +1,18 @@
1
1
  # GABBE Duplication Report
2
2
 
3
- Generated by `agents/scripts/report_duplicates.py` over 353 corpus files (skills, templates, guides, personas).
3
+ Generated by `agents/scripts/report_duplicates.py` over 431 corpus files (skills, templates, guides, personas).
4
4
  Method: normalized 3-line shingle Jaccard similarity. Report-only — no files were modified.
5
5
 
6
6
  **0 pair(s)** at or above the consolidation threshold (0.6). The corpus is largely non-duplicative; the top 20 most-similar pairs are listed below for review.
7
7
 
8
8
  | Similarity | File A | File B |
9
9
  |---|---|---|
10
- | 0.05 | `agents/guides/architecture/system-qualities.md` | `agents/guides/architecture/system-scalability.md` |
11
- | 0.02 | `agents/guides/languages/c-sharp.md` | `agents/guides/languages/rust.md` |
12
- | 0.02 | `agents/guides/languages/java.md` | `agents/guides/languages/rust.md` |
13
- | 0.02 | `agents/guides/languages/c-sharp.md` | `agents/guides/languages/java.md` |
10
+ | 0.04 | `agents/guides/architecture/system-qualities.md` | `agents/guides/architecture/system-scalability.md` |
14
11
  | 0.01 | `agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md` | `agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md` |
12
+ | 0.01 | `agents/templates/coding/PROPERTY_TEST_CHECKLIST.md` | `agents/templates/core/DEPENDENCY_GRAPH_TEMPLATE.md` |
15
13
  | 0.01 | `agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md` | `agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md` |
16
14
  | 0.01 | `agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md` | `agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md` |
15
+ | 0.01 | `agents/templates/security/MODEL_CARD_TEMPLATE.md` | `agents/templates/security/SYSTEM_CARD_TEMPLATE.md` |
17
16
  | 0.01 | `agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md` | `agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md` |
18
17
  | 0.01 | `agents/skills/architecture/api-design.skill.md` | `agents/skills/architecture/error-handling-strategy.skill.md` |
19
18
  | 0.01 | `agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md` | `agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md` |
@@ -22,9 +21,10 @@ Method: normalized 3-line shingle Jaccard similarity. Report-only — no files w
22
21
  | 0.01 | `agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md` | `agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md` |
23
22
  | 0.01 | `agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md` | `agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md` |
24
23
  | 0.01 | `agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md` | `agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md` |
25
- | 0.01 | `agents/templates/product/PRD_TEMPLATE.md` | `agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md` |
26
24
  | 0.01 | `agents/skills/coding/excalidraw.skill.md` | `agents/skills/coding/tldraw-canvas.skill.md` |
25
+ | 0.01 | `agents/templates/product/PRD_TEMPLATE.md` | `agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md` |
27
26
  | 0.01 | `agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md` | `agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md` |
28
27
  | 0.01 | `agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md` | `agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md` |
29
28
  | 0.00 | `agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md` | `agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md` |
29
+ | 0.00 | `agents/guides/languages/js-ts-nodejs.md` | `agents/guides/languages/php-laravel.md` |
30
30
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gabbe-kit",
3
- "version": "1.1.2",
3
+ "version": "1.1.3",
4
4
  "description": "GABBE - Generative Architectural Brain Base Engine. A Markdown agentic engineering kit installer (Python-independent). Wires AGENTS.md, skills, and per-agent rule files into any project.",
5
5
  "keywords": [
6
6
  "agentic",
@@ -14,7 +14,7 @@
14
14
  "cursor",
15
15
  "copilot"
16
16
  ],
17
- "homepage": "https://github.com/andreibesleaga/GABBE#readme",
17
+ "homepage": "https://andreibesleaga.github.io/GABBE/",
18
18
  "bugs": {
19
19
  "url": "https://github.com/andreibesleaga/GABBE/issues"
20
20
  },
package/scripts/init.py CHANGED
@@ -1142,30 +1142,18 @@ def main():
1142
1142
  print(f" {GREEN}✓ Initialized Loki Memory{NC}")
1143
1143
 
1144
1144
  _is_windows = sys.platform == "win32"
1145
- _is_unix = not _is_windows
1146
-
1147
- # Copy setup-context.sh (Linux / macOS)
1148
- if _is_unix:
1149
- setup_src = AGENTS_DIR / "scripts/setup-context.sh"
1150
- setup_dest = PROJECT_ROOT / "setup-context.sh"
1151
- if setup_src.exists():
1152
- shutil.copy2(setup_src, setup_dest)
1153
- setup_dest.chmod(0o755)
1154
- print(f" {GREEN}✓ Installed setup-context.sh{NC}")
1155
- else:
1156
- print(f" {YELLOW}! Could not find {setup_src}, skipping setup-context.sh install{NC}")
1157
-
1158
- # Copy setup-context.ps1 (Windows)
1159
- if _is_windows:
1160
- setup_ps1_src = AGENTS_DIR / "scripts/setup-context.ps1"
1161
- setup_ps1_dest = PROJECT_ROOT / "setup-context.ps1"
1162
- if setup_ps1_src.exists():
1163
- shutil.copy2(setup_ps1_src, setup_ps1_dest)
1164
- print(f" {GREEN}✓ Installed setup-context.ps1 (Windows Support){NC}")
1165
- else:
1166
- print(
1167
- f" {YELLOW}! Could not find {setup_ps1_src}, skipping setup-context.ps1 install{NC}"
1168
- )
1145
+
1146
+ # setup-context.sh/.ps1 stay in agents/scripts/: the script derives the project
1147
+ # root from its own location (scripts/../..), so a copy at the project root
1148
+ # would write .claude/, .cursorrules, memory/ ... into the folder above it.
1149
+ _setup_name = "setup-context.ps1" if _is_windows else "setup-context.sh"
1150
+ _setup_path = AGENTS_DIR / "scripts" / _setup_name
1151
+ if _setup_path.exists():
1152
+ try:
1153
+ _setup_shown = _setup_path.relative_to(PROJECT_ROOT)
1154
+ except ValueError:
1155
+ _setup_shown = _setup_path
1156
+ print(f" {GREEN}✓ Context script: {_setup_shown} (run it from there){NC}")
1169
1157
 
1170
1158
  # Symlinks
1171
1159
  skills_src = AGENTS_DIR / "skills"
@@ -1383,7 +1371,7 @@ You MUST NOT write implementation code until these artifacts are approved:
1383
1371
  - [ ] CI/CD Pipeline configured
1384
1372
  - [ ] Compliance Audit passed (if regulated)
1385
1373
 
1386
- Start by running: `setup-context.sh` to confirm your environment.
1374
+ Start by running: `agents/scripts/setup-context.sh` to confirm your environment.
1387
1375
  """
1388
1376
  mission_file = PROJECT_ROOT / "BOOTSTRAP_MISSION.md"
1389
1377
  mission_file.write_text(mission)