Skip to content

README_FULL.md

Latest commit

 

History

History
1453 lines (1166 loc) · 69.3 KB

README_FULL.md

File metadata and controls

1453 lines (1166 loc) · 69.3 KB
Raw

GABBE (Generative Architectural Brain Base Engine) - Agentic Software R&D Engineering Kit

Audience: users & agents adopting the full GABBE kit. Scope: complete reference — skills, templates, guides, modes, setup per language, troubleshooting.

Complete Guide

What is this?

  • Universal kit for Software and AI coding agents: Claude Code, Cursor, GitHub Copilot, Antigravity/Gemini, Codex.
  • Drop-in context kit that turns any AI coding agent into a governed engineering team for developing software.
  • Based on Software Engineering & Architecture Practices and Procedures.
  • Works for any project type, new or existing, any language, any team size.
  • Write Once, Run Everywhere: Skills work on Cursor (.mdc), VS Code (folder/skill), Claude (.skill.md), Gemini.
  • The system features an experimental Meta-Cognitive Orchestrator "Brain" (Neurocognitive based architecture derived from Neuroscience, Cognitive Psychology, Epistemology, treating the Software System not as a machine, but as a Cognitive Entity), using Active Inference to plan, route, and optimize work.
  • The system features a Multi-Agent Swarm "Loki" Engineering Team (30+ specialized agent roles for large projects), providing episodic and semantic memory, project history auditing and checkpoints.

It contains:

  • 214 Skills (specialized capabilities)
  • 100 Templates (standardized documents)
  • 86 Guides (language & domain expertise)
  • 36 Personas (specialized roles)
  • 66 MCP servers (configuration and guides for AI tools)
  • Brain Mode (meta-cognitive orchestration)
  • Loki Mode (multi-agent swarm engineering personas team for large projects)

214 Skills · 100 Templates · 86 Guides · 36 Personas · 50+ MCPs · Loki / Brain Mode CLI

Table of Contents

  1. What Is This Kit?
  2. Brain Mode
  3. Quick Start (5 min)
  4. Kit Structure Map
  5. Workflow 1: New Project from Scratch
  6. Workflow 2: Refactoring & Bugfixing Existing Project
  7. Self-Healing + Research Loop
  8. Multi-Agent Systems (MAS)
  9. Architecture & Design Patterns
  10. Agentic Patterns (Advanced AI)
  11. Testing Strategy
  12. Enterprise Domains (Infra, Data, Integration)
  13. Environment & Deployment (Local/Remote/Cloud)
  14. Legacy Systems (COBOL, Mainframe)
  15. Future Tech & Adaptive Skills (2026-2030)
  16. System Quality & Evolution (SRE, Performance)
  17. System Lifecycle & Traceability
  18. Skills Reference
  19. Templates Reference
  20. MCP Configuration
  21. Extending the Kit
  22. Loki Mode (Large Projects)
  23. Guides by Technology Stack
  24. Testing & Verification
  25. Troubleshooting

1. What Is This Kit?

This kit gives AI coding agents the context, skills, memory, and workflows to act as a reliable software engineering team. It solves Another Lethal Trifecta of agentic AI:

  • Velocity mismatch — agents code faster than humans can review, skipping critical steps
  • Non-determinism — same prompt, different output every time without guardrails
  • Cost asymmetry ("context rot") — wrong architectural decisions compound and become exponentially expensive to fix
  • Self-Evolution: Agents rewrite their own prompts (meta-optimize) to fix recurring errors.
  • Adaptive Orchestration: Loki Mode dynamically injects research/safety phases based on complexity.
  • Vibe Coding: Translates high-level aesthetic intents ("Make it pop") into concrete CSS/JS.
  • Optimal Execution Mandates: Built-in rules forcing agents to prioritize the best specialized skills, proactively recommend missing MCP servers, and aggressively default to cost & budget optimization unless authorized by a human.

The kit enforces Spec-Driven Development (SDD), Test-Driven Development (TDD), Architecture-Driven Development (ADD), and structured human-in-the-loop checkpoints — so agents build correct, secure, maintainable software the first time.

Universal Skill Compiler: npx gabbe-kit init (Python-independent), curl -fsSL …/install.sh | sh, or scripts/init.py automatically configures skills for your specific tool:

  • VS Code / Copilot: .github/skills/<slug>/SKILL.md (slash commands e.g. /code-review).
  • Cursor: optimized .cursor/rules/*.mdc.
  • Claude Code: .claude/skills/<slug>/SKILL.md (native skill discovery).
  • Gemini: .gemini/settings.json + GEMINI.md.
  • Antigravity / OpenCode: the universal .agents/skills/<slug>/SKILL.md tree (+ opencode.json).
  • Zed / Continue / Roo Code / Kilo Code: root AGENTS.md + each tool's rules file.

Compatible with: Claude Code, Cursor, Windsurf, Cline, Aider, Devin, Gemini, Antigravity, OpenCode, Zed, Continue, Roo Code, Kilo Code, OpenAI/Codex, GitHub Copilot, VS Code — and any tool reading the AGENTS.md / agentskills.io standards.

Repositories using this kit should see reduction in agent runtime and token usage through explicit context, cached decisions, and SDLC memory.

2. Brain Mode

"Meta-Cognitive Orchestrator"

The system features a Brain Mode that supersedes standard execution. It uses Active Inference to minimize project risk and intelligently routes tasks to local and remote models.

# Activate Brain Mode
/brain activate "Build a SaaS platform"

Key Capabilities

  • Active Inference Loop: Continuously compares "Expected State" vs "Actual State".
  • Dynamic Cost Routing: Routes simple tasks to Local LLMs and complex ones to Remote SOTA Models.
  • Episodic Memory: Learns from past failures and successes across projects.

Read more in AGENTS.md.

3. Quick Start (5 min)

# 1. Run the Interactive Setup Wizard
python3 scripts/init.py

2. Feed the Mission

  • The script generates BOOTSTRAP_MISSION.md (or SETUP_MISSION.md if dynamic setup is disabled) in your root.
  • Copy its content and paste it into your AI Agent's chat window.
  • This aligns the agent with your project context immediately.

3. Verify Context

  • Open agents/AGENTS.md and check the Tech Stack section.
  • Open agents/CONSTITUTION.md and review project rules.

4. Git Tracking (Important)

  • 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: 
    git ls-files agents/memory/ project/ | xargs git update-index --skip-worktree

3.1. GABBE CLI (experimental)

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. It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.

Prerequisites

  • Python 3.8+
  • LLM API Key: For Brain/Route features, set GABBE_API_KEY (OpenAI-compatible).

Environment Variables (full reference in CLI_REFERENCE.md):

Variable Default Description
GABBE_API_URL https://api.openai.com/v1/chat/completions OpenAI-compatible endpoint
GABBE_API_KEY (required for LLM features) Bearer token for the LLM API
GABBE_API_MODEL gpt-4o Model name sent in API requests
GABBE_LLM_TEMPERATURE 0.7 Sampling temperature (0.0–1.0)
GABBE_LLM_TIMEOUT 30 HTTP timeout in seconds
GABBE_ROUTE_THRESHOLD 50 Complexity score above which prompts route REMOTE
GABBE_MAX_COST_USD 5.0 Maximum cost (USD) budget per run
GABBE_MAX_TOKENS_PER_RUN 100000 Maximum token limit per run
GABBE_MAX_TOOL_CALLS_PER_RUN 50 Maximum tool calls per run
GABBE_MAX_ITERATIONS 25 Maximum brain loop iterations per run
GABBE_MAX_WALL_TIME 300 Maximum wall-clock time per run (seconds)
GABBE_MAX_RECURSION_DEPTH 5 Maximum agent recursion depth
GABBE_MAX_RETRIES_PER_TOOL 3 Maximum retries per tool call
GABBE_LLM_MAX_RETRIES 3 Number of retry attempts for LLM HTTP calls
GABBE_LOG_LEVEL INFO Logging level (DEBUG, INFO, WARNING, ERROR)
GABBE_POLICY_FILE project/policies.yml Path to YAML policy file for tool access control
GABBE_ESCALATION_MODE cli Escalation mode: cli (interactive), file (pause), silent (auto-reject)
GABBE_SUBPROCESS_TIMEOUT 300 Timeout for verify shell commands (seconds)
GABBE_MCP_TOKEN (unset) If set, MCP clients must provide this token to authenticate
GABBE_MCP_ALLOWED_COMMANDS (unset) Comma-separated list of executables permitted via MCP run_command
GABBE_OTEL_ENABLED false Enable OpenTelemetry tracing

Installation

The CLI is a Python package.

# 1. Install locally (Recommended)
pip install -e .

# 2. Verify installation
gabbe --help

Core Commands

Command Description
gabbe init Initialize the SQLite Database (Run this after python scripts/init.py).
gabbe sync Hybrid Sync: Bidirectional sync between project/TASKS.md and SQLite DB.
gabbe verify Enforcer: programmable integrity check (files, tests, lint).
gabbe verify --chaos Resilience: fault-injection self-checks (fail-closed tool, hard-stop, PII routing, escalation).
gabbe eval Skill evals: deterministic self-check; --live scores skill outputs via the model.
gabbe doctor Autodetect: OS/arch, runtimes, installed agents + post-install MCP next-steps.
gabbe update / gabbe uninstall Reversible install: additive refresh / manifest-backed removal (--dry-run, --purge, --global, --dir).
gabbe status Dashboard: Visualizes project phase and task progress.
gabbe brain Meta-Cognition: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key).
gabbe route Cost Router: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key).
gabbe forecast Strategic Forecast: Projects remaining work cost and tokens based on historical run data.
gabbe serve-mcp MCP Gateway: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely.
gabbe runs [--status STATUS] [--limit N] Run History: List recent agent runs with status, cost, and timestamps.
gabbe audit <run-id> [--format json|table] Audit Trace: Display structured span-level audit trace for a past run.
gabbe replay <run-id> [--from-step N] Deterministic Replay: Replay a past run from its checkpoints.
gabbe resume <run-id> Escalation Resume: Approve or reject pending escalations for a paused run.
gabbe registry publish [--out DIR] Publish Skills: Export skills as a publish-ready agentskills.io bundle (manifest + agent-card) for universal registries.
gabbe registry add <source> Import Skills: Draw an external skill/bundle (validated + security-scanned + namespaced).
gabbe setup Install Wizard: Wire the kit into your coding agents (also npx gabbe-kit init).

Platform Control Layer

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.

Architecture

GABBE 2.0 uses a Hybrid Architecture where agents and humans interact via Markdown, but the system of record is SQLite.

graph TD
    subgraph User["User (Legacy Flow)"]
        Edit[Edit project/TASKS.md]
    end

    subgraph CLI["GABBE CLI (pip installed)"]
        Sync[gabbe sync]
        Verify[gabbe verify]
        Brain[gabbe brain]
        Router[gabbe route]
        Forecast[gabbe forecast]
        MCP[gabbe serve-mcp]
    end

    subgraph Storage["Hybrid Memory"]
        MD[Markdown Files]
        DB[(SQLite state.db)]
    end

    User -->|Manual Edits| MD
    MD <-->|Bi-Directional| Sync
    Sync <--> DB
    Brain -->|Read/Write| DB
    Verify -->|Check| MD
    Verify -->|Check| DB
    Forecast -->|Analyze| DB
    MCP -->|Write Telemetry| DB
Loading

Text Overview (ASCII)

[User] --(Manual Edits)--> [Markdown Files] <--(Bi-Directional)--> [gabbe sync] <--> [(SQLite state.db)]
                                                                                       ^      ^
[gabbe brain] --(Read/Write)-----------------------------------------------------------+      |
[gabbe verify] --(Check)--> [Markdown Files]                                                  |
[gabbe verify] --(Check)----------------------------------------------------------------------+
[gabbe forecast] --(Analyze)------------------------------------------------------------------+
[gabbe serve-mcp] --(Write Telemetry)---------------------------------------------------------+

How to Use

Setup

# 1. Generate Context Configs
python3 scripts/init.py

# 2. Initialize Database
gabbe init

Daily Workflow

# Check status
gabbe status

# Sync tasks (manual edits)
gabbe sync

# Optimize a skill (Requires GABBE_API_KEY)
gabbe brain evolve --skill tdd-cycle

Verification

gabbe verify

🚀 Common Actions (Copy-Paste Prompts)

Strategy & Ideation (Step 0)

"Use business-case/strategy skills to validate exactly why we are building [description] and who it is for."

New Project from Scratch

"Read AGENTS.md. I want to build [description]. Start with spec-writer skill."

Flow: Strategy → Spec → Design → Tasks → TDD Implementation → Security → Deploy

Resume Existing Project

"Read AGENTS.md and agents/memory/PROJECT_STATE.md. Resume the project."

Fix a Bug

"Read AGENTS.md. Bug: [description]. Use debug skill with TDD."

Flow: Reproduce → Root Cause → Failing Test → Fix → Green → Regression Check

Refactor / Pay Tech Debt

"Use tech-debt skill on [directory]. Then refactor the top-priority item."

Security Audit

"Run security-audit skill on the entire codebase."

Architecture Review

"Run arch-review skill. Check for SOLID violations and coupling."

"Use the performant-nodejs skill to audit the current Node.js architecture for scalability bottlenecks and propose optimizations."

"Use the performant-laravel skill to audit the current Laravel architecture for scalability bottlenecks and propose optimizations."

"Use the performant-python skill to audit the current Python architecture for scalability bottlenecks and propose optimizations."

"Use the performant-go skill to audit the current Go architecture for scalability bottlenecks and propose optimizations."

"Use the performant-ai skill to audit the current AI/LLM architecture for latency and cost bottlenecks."

Software Engineering & System Architecture

"Act as a Principal Staff Engineer. Review the codebase in [directory] and generate a C4 system architecture diagram (Context and Container levels). Identify any bottlenecks and propose scaling strategies."

"Use the design-patterns and domain-model skills. We are building a [feature segment]. Propose the optimum architecture pattern (e.g. Event-driven, CQRS, Hexagonal) and define the core domain entities."

Vibe-Coding (Creative Frontend)

"Use the vibe-coding skill. Build a [component/page] using [framework]. I want it to feel [aesthetic, e.g. glassmorphism, cyberpunk, sleek corporate]. Include micro-animations and smooth transitions. Prioritize visual WOW over generic utility."

Activate Brain Mode (Complex Goals)

"Activate Brain Mode. Goal: [build X / migrate Y / solve Z]."

Uses Active Inference to plan, route between local/remote models, and learn from past outcomes.

Activate Loki Mode (Large Projects)

Using the CLI:

gabbe brain activate (Loki may be triggered autonomously by the Brain based on context cost). Or activate the swarm skill explicitly: Activate agents/skills/brain/loki-mode.skill.md with your goal.

Using Pure Agent Mode (No CLI):

"Activate agents/skills/brain/loki-mode.skill.md. Goal: [build X]. Do not ask me for permission unless you hit a mandatory Human Approval Gate or a task requires True A2A Delegation."

Multi-agent swarm with 30+ specialized personas for projects >5 features or >20 files.

After Setup - Common Triggers:

New Project:

"Read AGENTS.md. I want to build [description]. Start with spec-writer skill."

Resuming:

"Read AGENTS.md and agents/memory/PROJECT_STATE.md. Resume the project."

Fixing a Bug:

"Read AGENTS.md. There's a bug: [description]. Use debug skill and fix it with TDD." VS Code users: Type /debug

4. Kit Structure Map

graph TB
    subgraph "Agent Context Layer"
        A[AGENTS.md<br/>Universal config template] --> B[CONSTITUTION.md<br/>Immutable project law]
        A --> C[skills/00-index.md<br/>Skills registry]
        A --> D[guides/<br/>Language-specific guides]
    end
    subgraph "Agent Capability Layer"
        C --> S1[Core Skills<br/>code-review, tdd, refactor, debug]
        C --> S2[Security Skills<br/>security-audit, threat-model, privacy]
        C --> S3[Research + Self-Heal<br/>research, self-heal, knowledge-gap]
        C --> S4[SDLC Skills<br/>session-resume, sdlc-checkpoint, integrity-check]
    end
    subgraph "Memory Layer"
        M1[agents/memory/PROJECT_STATE.md<br/>Current SDLC phase] --> M2[agents/memory/AUDIT_LOG.md<br/>Append-only decision history]
        M2 --> M3[agents/memory/episodic/<br/>Per-session decision logs]
        M3 --> M4[agents/memory/episodic/SESSION_SNAPSHOT/<br/>Per-milestone snapshots]
        M5[agents/memory/CONTINUITY.md<br/>Past failures - checked every session] --> M6[agents/memory/semantic/<br/>Crystallized project knowledge]
    end
    subgraph "Orchestration Layer — Large Projects"
        L[agents/skills/brain/loki-mode.skill.md<br/>Master orchestration] --> P[agents/personas/<br/>30+ role-based agent personas]
        L --> M1
    end
    subgraph "Templates Layer"
        T[templates/<br/>60+ fill-in-the-blank docs]
    end
Loading

5. Workflow 1: New Project from Scratch

Required Minimum

SDLC Gate Required Optional
S01 Requirements PRD.md with EARS syntax, human approval User stories, wireframes, CONSTITUTION.md articles
S02 Design Architecture decision + AGENTS.md update C4 model, formal ADR, threat model (required for security features)
S03 Specification SPEC_TEMPLATE.md, API contracts Feature flags, rollout plan
S04 Tasks TASKS_TEMPLATE.md, 15-min decomposition Epic planning, story points
S05 Implementation TDD (test first), RARV cycle, audit log Browser-TDD (frontend only), pair-agent review
S06 Testing Unit tests >99% coverage, integration tests E2E tests, load tests, visual regression
S07 Security SECURITY_CHECKLIST.md, npm audit clean, compliance-review DAST, penetration test, formal compliance review
S08 Review Human code review orch-judge EARS compliance check
S09 Staging Smoke tests Performance benchmarks, accessibility audit
S10 Production Rollback plan, monitoring Canary deployment, feature flags

Full SDLC Flow

flowchart TD
    A([Start: User Goal]) --> B[Read AGENTS.md + CONSTITUTION.md]
    B --> C{Project size?}
    C -->|Small/Medium| D[Single Agent Mode]
    C -->|Large/Complex| E[Loki Swarm Mode]

    D --> F[spec-writer.skill → PRD.md + EARS]
    E --> F

    F --> G{Human approves spec?}
    G -->|No| F
    G -->|Yes| H[sdlc-checkpoint S01]

    H --> I[adr-writer.skill + threat-model.skill]
    I --> J[C4 Architecture + PLAN.md]
    J --> K{Human approves design?}
    K -->|No| I
    K -->|Yes| L[sdlc-checkpoint S02]

    L --> M[project/TASKS.md decomposition — 15-min rule]
    M --> N[sdlc-checkpoint S03/S04]

    N --> O[Implementation Loop]
    O --> O1[RARV Cycle per task]
    O1 --> O2{Tests pass?}
    O2 -->|No| O3[self-heal.skill max 5×]
    O3 --> O2
    O2 -->|Yes| O4[audit-trail.skill log]
    O4 --> O5{All tasks done?}
    O5 -->|No| O1
    O5 -->|Yes| P[sdlc-checkpoint S05]

    P --> Q[integrity-check.skill — 8 dimensions]
    Q --> R[sdlc-checkpoint S06]
    R --> S[security-audit.skill + compliance-review.skill + SECURITY_CHECKLIST]
    S --> T[sdlc-checkpoint S07]
    T --> U{Human review}
    U -->|Changes needed| O
    U -->|Approved| V[sdlc-checkpoint S08]
    V --> W[deployment.skill → Staging]
    W --> X[sdlc-checkpoint S09]
    X --> Y[Production Deploy]
    Y --> Z([sdlc-checkpoint S10 — COMPLETE])

    style A fill:#4CAF50,color:#fff
    style Z fill:#4CAF50,color:#fff
    style G fill:#FF9800,color:#fff
    style K fill:#FF9800,color:#fff
    style U fill:#FF9800,color:#fff
Loading

Step-by-Step Instructions

Step 0 — Strategy (Optional)

Tell agent: "Use business-case/strategy skills to validate the goals."
Agent produces: BUSINESS_CASE.md or EMPATHY_MAP.md or similar strategy docs
You review: The 'Why' and the 'Who' before moving to 'What'
Approve: "Approved. Move to Step 1 Requirements."

Step 1 — Requirements (S01)

Tell agent: "Use spec-writer skill. Build [your goal]."
Agent produces: PRD.md using EARS syntax (templates/product/PRD_TEMPLATE.md)
(Optional) Tell agent: "Use visual-specs skill to process these whiteboard photos."
Agent produces: VISUAL_SPEC_PACKAGE_TEMPLATE.md + diagrams
You review: Check that all requirements are verifiable predicates and visual specs match intent.
Approve: "Approved. Create SDLC checkpoint S01."

Step 2 — Design (S02)

Agent produces: PLAN.md + C4 architecture diagram + ADRs for major decisions
Agent runs: threat-model.skill for any auth/data storage features
You review: Architecture decisions, data flow, security mitigations
Approve: "Approved. Create SDLC checkpoint S02."

Step 3 — Specification & Tasks (S03/S04)

Agent produces: SPEC_TEMPLATE.md with API contracts + TASKS_TEMPLATE.md
Each task must: Be achievable in ~15 minutes, have testable acceptance criteria
You review: Coverage of all PRD requirements in tasks
Approve: "Approved. Create SDLC checkpoints S03 and S04."

Step 4 — Implementation Loop (S05)

For each task, agent:
  1. Reads task + AGENTS.md + CONTINUITY.md (past failures)
  2. Detects knowledge gaps → invokes research.skill if needed
  3. Writes failing test FIRST (TDD Red)
  4. Implements minimal code to pass test (TDD Green)
  5. Refactors while keeping tests green (TDD Refactor)
  6. Runs: tests + lint + typecheck + agentic-linter boundary check
  7. Logs to AUDIT_LOG.md
  8. Marks task DONE in project/TASKS.md

Steps 5-10 — Quality, Security, Deploy

Tell agent: "Run integrity-check skill" → 8-dimension verification
Tell agent: "Run security-audit and compliance-review skills" → OWASP checks + compliance checks
You review code → Human approval → Staging deploy → Production

6. Workflow 2: Refactoring & Bugfixing Existing Project

Full Flow

flowchart TD
    A([Start: Existing Project]) --> B[session-resume.skill]
    B --> B1{Has agents/memory?}
    B1 -->|Yes — resuming| C[Load all memory + project state]
    B1 -->|No — first time| D[Initialize kit]

    D --> D1[setup-context.sh]
    D1 --> D2[Adapt AGENTS.md]
    D2 --> D3[Run audit skills]

    C --> E[integrity-check.skill]
    D3 --> E

    E --> F{What type of work?}

    F -->|Bug Fix| G[BUG_REPORT_TEMPLATE + debug.skill]
    G --> G1[Reproduce → Root cause → TDD Red]
    G1 --> G2[tdd-cycle.skill — write test FIRST]
    G2 --> G3[Fix → Green → Refactor]
    G3 --> G4[self-heal if stuck]
    G4 --> G5[audit-trail.skill]

    F -->|Tech Debt| H[tech-debt.skill]
    H --> H1[TECH_DEBT_TEMPLATE prioritized backlog]
    H1 --> H2[refactor.skill per item]
    H2 --> H3[agentic-linter check after each]

    F -->|Architecture Debt| I[arch-debt.skill]
    I --> I1[Coupling analysis + violations]
    I1 --> I2[ADR for migration approach]
    I2 --> I3[Strangler Fig or modularization]
    I3 --> I4[agentic-linter gates each PR]

    F -->|Security| J[security-audit.skill + compliance-review.skill + threat-model]
    J --> J1[SECURITY_CHECKLIST.md]
    J1 --> J2[privacy-audit.skill if PII involved]
    J2 --> J3[legal-review.skill if regulated]

    F -->|Performance| K[performance-audit.skill]
    K --> K1[Profile → bottlenecks → N+1 check]
    K1 --> K2[Fix with test guard — no regressions]

    G5 --> L[sdlc-checkpoint]
    H3 --> L
    I4 --> L
    J3 --> L
    K2 --> L

    L --> M[integrity-check.skill — final verify]
    M --> N{All green?}
    N -->|No| F
    N -->|Yes| O[git-workflow.skill → PR]
    O --> P([Human review + merge])

    style A fill:#2196F3,color:#fff
    style P fill:#4CAF50,color:#fff
    style F fill:#FF9800,color:#fff
Loading

First-Time Setup on Existing Project

# 1. Copy kit to project root
cp -r ~/agents/ ./

# 2. Wire up context
agents/setup-context.sh

# 3. Adapt AGENTS.md
#    - Set tech stack, test commands, lint commands
#    - Add existing architecture constraints
#    - Document known tech debt areas

# 4. Initialize memory
#    Agent: "Initialize project memory. Run integrity-check skill on current codebase."

Bug Fix Flow (step-by-step)

1. Fill templates/core/BUG_REPORT_TEMPLATE.md with reproduction steps
2. Tell agent: "Use debug skill. Bug: [description]. BUG_REPORT_TEMPLATE.md is filled."
3. Agent: reproduces → root cause → writes FAILING TEST first
4. Agent: implements fix → verifies test is now GREEN
5. Agent: runs full test suite (no regressions), lint, typecheck
6. Agent: logs to AUDIT_LOG.md, creates git-workflow PR
7. You: review PR

Tech Debt Flow (step-by-step)

1. Tell agent: "Use tech-debt skill on [directory or whole project]."
2. Agent: scans for TODOs, complexity > 10, duplication, stale deps
3. Agent: fills TECH_DEBT_TEMPLATE.md with Impact×Effort matrix
4. You: review and prioritize the backlog
5. Tell agent: "Refactor [debt item] using refactor skill. Keep all tests green."
6. Agent: runs agentic-linter after each refactor to verify boundaries

7. Self-Healing + Research Loop

flowchart LR
    A[Task assigned] --> B{Knowledge gap?}
    B -->|Yes| C[knowledge-gap.skill]
    C --> D[research.skill]
    D --> E{Authoritative source found?}
    E -->|Yes| F[Store in semantic memory]
    E -->|No| G[Escalate to human]
    F --> H[Proceed with task]
    B -->|No| H
    H --> I{Verification passes?}
    I -->|Yes| J[audit-trail log → Done]
    I -->|No| K[self-heal.skill]
    K --> L{Attempt < 5?}
    L -->|Yes| M[Diagnose + re-research if needed]
    M --> H
    L -->|No| N[Human escalation report]
    N --> O[orch-coordinator ticket]
    O --> P([Human decision])
    P --> H
Loading

8. Cognitive Architecture Integration (Evolution & Healing)

GABBE's true power lies in its Meta-Cognitive triad: Active Inference (activate), Genetic Evolution (evolve), and Autonomous Recovery (heal). These tools run in the background or at specific SDLC gates to continuously optimize the team's performance.

8.1. Sensory MCPs to Working Memory

When an agent uses a sensory tool (like visual-specs or excalidraw), the parsed visual context is directly committed to the WORKING_MEMORY.md. 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.

8.2. Enforcing Brain Mode (activate)

Brain Mode should be integrated into your development loop after significant milestones:

  • After Requirements (S01): To predict architectural bottlenecks before they are written.
  • Before Testing (S06): To foresee edge cases the standard developer agent missed.

Using the CLI: Map gabbe brain activate as a Git pre-commit hook or explicitly call it:

gabbe brain activate

Using Pure Agent Mode (No CLI):

"Activate Brain Mode for this session by reading agents/skills/brain/brain-mode.skill.md. Your goal is to [build X feature]. Follow the Observe -> Orient -> Decide -> Act loop in that document before you write any code."

8.3. Genetic Evolution (Meta-Optimization)

Whenever a specific skill yields repeatedly poor code or requires manual human correction, you should trigger Evolutionary Prompt Optimization (EPO).

Using the CLI: Run this after completing a sprint or resolving a major bug. The system reads the failing context and rewrites the skill's system prompt in the SQLite genes table.

gabbe brain evolve --skill tdd-cycle
gabbe brain evolve --skill code-review

Using Pure Agent Mode (No CLI):

"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."

8.4. Self-Healing Enforcement (heal)

The healing protocol acts as an infrastructure watchdog to recover from failures.

Using the CLI: Checks for missing files (AGENTS.md, CONSTITUTION.md), corrupted SQLite databases, and network reachability. Run this in your CI/CD pipeline.

gabbe brain heal

Using Pure Agent Mode (No CLI):

"The build is failing. Invoke agents/skills/core/self-heal.skill.md. Do not ask me for permission between steps. Diagnose the error, hypothesize a fix, write the code, and run the tests. If it fails again, loop back to step 1. You have a maximum of 5 attempts before you must escalate to me."

9. Multi-Agent Systems (MAS)

This kit includes specialized tools for building orchestrator-worker swarms and complex agent topologies.

Key Resources:

  • Guide: guides/multi-agent-systems.md — Full development patterns & stack integration.
  • Skill: multi-agent-orch — Plan and orchestrate agent swarms.
  • Skill: agent-protocol — Define inter-agent communication schemas.
  • Template: AGENT_PROFILE_TEMPLATE.md — Define roles and personalities.
  • Template: SWARM_ARCHITECTURE_TEMPLATE.md — Map topologies and data flow.

When to use MAS:

  • Complex tasks requiring different "personas" (e.g., Coder + Reviewer + Security).
  • Tasks exceeding a single context window.
  • Parallel execution of sub-tasks.

10. Architecture & Design Patterns

Embeds 2025-standard patterns into your workflow.

Key Resources:

  • Skill: arch-patterns — Selects Microservices vs Monolith vs Serverless.
  • Skill: design-patterns — Implements GoF patterns (Strategy, Factory, etc.).
  • Skill: clean-coder — Enforces SOLID, DRY, and no "code smells".
  • Template: ARCH_DECISION_FRAMEWORK.md — Matrix for Architectural decision making.
  • Template: DESIGN_PATTERN_USAGE.md — Justify complex pattern choices.
  • Template: CLEAN_CODE_CHECKLIST.md — Quality gate for PRs.
  • Guide: guides/design-patterns.md — Catalog of modern patterns.

11. Agentic Patterns (Advanced AI)

Tools for building self-correcting, planning, and memory-augmented agents.

Key Resources:

  • Skill: agentic-patterns — Implements Reflection, ReAct, and Planning loops.
  • Template: ETHICAL_IMPACT_ASSESSMENT.md — AI Safety & Bias check.
  • Guide: guides/agentic-patterns.md — Deep dive into cognitive architectures.

12. Testing Strategy

Comprehensive testing resources using Pyramid or Trophy models.

Key Resources:

  • Skill: testing-strategy — Orchestrate Unit, Integration, E2E, and Contract testing.
  • Guide: guides/testing-strategy.md — Complete guide to modern testing patterns.
  • Template: TEST_PLAN_TEMPLATE.md — Master test plan document.
  • Template: TEST_CASE_TEMPLATE.md — Detailed test case definition.
  • Template: E2E_TEST_SUITE_TEMPLATE.md — High-level E2E scenarios.

13. Enterprise Domains (Infra, Data, Integration)

Specialized resources for specialized domains.

Infrastructure & DevOps

  • Skill: infra-devops (Terraform, K8s, CI/CD).
  • Template: INFRA_PLAN_TEMPLATE.md.

Data Engineering

  • Skill: data-engineering (ETL/ELT, Spark, dbt).
  • Template: DATA_PIPELINE_TEMPLATE.md.

Enterprise Integration

  • Skill: enterprise-integration (ERP, CRM, Legacy patterns).
  • Guide: guides/enterprise-patterns.md (Strangler Fig, ACL).
  • Template: INTEGRATION_SPEC_TEMPLATE.md.

14. Environment & Deployment (Local/Remote/Cloud)

Tools for the full lifecycle: from localhost to production.

Local Development (Inner Loop)

  • Skill: docker-dev (Compose Watch, DevContainers).
  • Template: DEVCONTAINER_TEMPLATE.json.

Remote Kubernetes Dev (Hybrid Loop)

  • Skill: k8s-dev (Telepresence, Okteto, DevSpace).
  • Template: DEV_SPACE_TEMPLATE.yaml.

Cloud Deployment (Outer Loop)

  • Skill: cloud-deploy (Vercel, Railway, AWS SST).
  • Template: DEPLOY_CONFIG_TEMPLATE.md.
  • Guide: guides/dev-environments.md.

15. Legacy Systems (COBOL, Mainframe)

"Old" code runs the world economy. Treat it with respect.

Modernization

  • Skill: legacy-modernization (COBOL analysis, Strangler Fig).
  • Template: LEGACY_AUDIT_TEMPLATE.md (Risk & Knowledge audit).
  • Guide: guides/legacy-tech.md (Mainframe DevOps, COBOL basics).

16. Future Tech & Adaptive Skills (2026-2030)

Preparing for the next wave: 6G, Agentic IoT, and Evolutionary Architecture.

Emerging Technologies

  • Skill: emerging-tech (6G, Matter, Vector Databases).
  • Skill: adaptive-architecture (Local-First, WASM, CRDTs).
  • Template: ADAPTIVE_SYSTEM_TEMPLATE.md (Evolutionary design).
  • Guide: guides/future-tech.md (The 2030 Horizon).

17. System Quality & Evolution (SRE, Performance)

Resources for ensuring your software is reliable, fast, and adaptable.

Skills

  • SRE: reliability-sre (SLOs, Error Budgets, Chaos).
  • Performance: performance-optimization (Caching, Sharding).
  • Design: compatibility-design (API Versioning, Migrations).

Documentation

  • Template: NFR_TEMPLATE.md (Reliability targets).
  • Template: SAFETY_CASE.md (Critical system assurance).
  • Template: COST_OPTIMIZATION_REPORT_TEMPLATE.md (FinOps).
  • Template: INCIDENT_POSTMORTEM_TEMPLATE.md (Blameless analysis).
  • Guide: guides/system-qualities.md (The "Ilities").

18. System Lifecycle & Traceability

Resources for binding Requirements to Code and Tests (The Golden Thread).

Skills

  • Traceability: system-lifecycle (Link REQ -> Code -> Test).

Documentation

  • Template: TRACEABILITY_MATRIX_TEMPLATE.md (Live status of requirements).
  • Guide: guides/full-system-lifecycle.md (Definition of Done).

19. Skills Reference

All 214 skills live in skills/ subdirectories. Invoke by mentioning the trigger keyword or using slash commands in VS Code.

1. Coding & Development (coding/)

Skill Slash Command (VS Code) Triggers Purpose
coding/code-review.skill.md /code-review review, PR, audit Security, perf, style check
coding/tdd-cycle.skill.md /tdd-cycle test, TDD, red-green Red-Green-Refactor loop
coding/browser-tdd.skill.md /browser-tdd visual, browser Visual TDD with Playwright
coding/refactor.skill.md /refactor refactor, cleanup Safe code restructuring
coding/debug.skill.md /debug fix, debug, bug Root Cause Analysis
coding/git-workflow.skill.md /git-workflow commit, PR, branch Conventional commits
coding/documentation.skill.md /documentation docs, README Doc generation
coding/clean-coder.skill.md clean code, solid Enforce SOLID/DRY
coding/mobile-dev.skill.md mobile, ios Mobile development
coding/visual-design.skill.md design, ui, tokens UI Design System
coding/vibe-coding.skill.md vibe, aesthetic Creative Frontend
coding/ci-autofix.skill.md ci fix, autofix Auto-fix CI failures
coding/tool-construction.skill.md build tool, mcp Tool building
coding/ui-gen.skill.md ui, dashboard Generative UI
coding/secure-coding.skill.md secure code, owasp Security-first coding
coding/file-processing.skill.md file, parse File manipulation
coding/artisan-commands.skill.md artisan, scripts Custom task automation
coding/performant-nodejs.skill.md nodejs, performance High-performance Node.js
coding/performant-laravel.skill.md laravel, performance High-performance Laravel
coding/performant-python.skill.md python, performance High-performance Python
coding/performant-go.skill.md go, performance High-performance Go
coding/performant-ai.skill.md ai, llm, performance High-performance AI/LLM
coding/time-complexity.skill.md complexity, big-o, hotspot Big-O static analysis via MCP
coding/excalidraw.skill.md excalidraw, whiteboard, visual Excalidraw diagram creation via MCP
coding/sketch-to-diagram.skill.md sketch, hand-drawn, recognize Hand-drawn sketch → formal diagram
coding/tldraw-canvas.skill.md tldraw, canvas, wireframe, UI sketch Visual canvas for wireframing and design

2. Architecture (architecture/)

Skill Triggers Purpose
architecture/arch-design.skill.md design architecture Create new architecture
architecture/arch-review.skill.md review architecture ATAM audit
architecture/arch-patterns.skill.md microservices Select patterns
architecture/design-patterns.skill.md factory, strategy GoF patterns
architecture/diagramming.skill.md diagram, mermaid Technical diagrams
architecture/domain-model.skill.md domain, ddd Context mapping
architecture/visual-whiteboarding.skill.md drawio, miro, figma Map spatial architecture
architecture/api-design.skill.md api, openapi API contract design
architecture/legacy-modernization.skill.md cobol, legacy Modernization
architecture/middleware-design.skill.md middleware, pipeline Middleware patterns
architecture/state-management.skill.md state, redux, store State strategy
architecture/realtime-comm.skill.md socket, realtime Websockets/Events
architecture/graphql-schema.skill.md graphql, schema Schema design
architecture/architecture-governance.skill.md governance, drift Policy enforcement
architecture/error-handling-strategy.skill.md error, retry Resiliency design
architecture/enterprise-migration-scenario.skill.md migration, legacy Enterprise migrations
architecture/event-governance.skill.md event, kafka Event schema registry

3. Operations & SRE (ops/)

Skill Triggers Purpose
ops/reliability-sre.skill.md sre, slo Reliability Engineering
ops/performance-optimization.skill.md performance System optimization
ops/incident-response.skill.md incident, outage Incident management
ops/docker-dev.skill.md docker, compose Local containers
ops/k8s-dev.skill.md k8s, telepresence Remote K8s dev
ops/cloud-deploy.skill.md deploy, aws Cloud deployment
ops/infra-devops.skill.md terraform, iac Infrastructure as Code
ops/cost-optimization.skill.md cost, finops Cost reduction
ops/caching-strategy.skill.md cache, redis Caching patterns
ops/release-management.skill.md release, semver Release coordination
ops/memory-optimization.skill.md memory, leak Memory profiling
ops/queue-management.skill.md queue, dead letter Job queue handling
ops/production-verifier.skill.md verify prod, smoke Post-deploy check
ops/system-benchmark.skill.md benchmark, load Performance testing
ops/capacity-planning.skill.md capacity, scale Resource planning
ops/release-validation.skill.md validation, gate Compliance gates
ops/troubleshooting-guide.skill.md debug, fix System recovery

4. Security (security/)

Skill Triggers Purpose
security/security-audit.skill.md audit, owasp Security review
security/threat-model.skill.md threat, stride Threat modeling
security/privacy-audit.skill.md privacy, gdpr Privacy impact
security/compliance-review.skill.md compliance, soc2 Compliance check
security/access-control.skill.md rbac, iam Identity/Access
security/secrets-management.skill.md secrets, vault Secrets handling
security/ai-ethics-compliance.skill.md ethics, bias AI Safety check
security/ai-safety-guardrails.skill.md guardrails, jailbreak Runtime AI Safety
security/legal-review.skill.md legal, ip, license IP & License check
security/traceability-audit.skill.md trace, reqs V-Model Traceability
security/safety-scan.skill.md safety scan Pre-commit safety
security/reliability-engineering.skill.md reliability, mtbf System reliability
security/dependency-security.skill.md dep check, snyk Supply chain security
security/backup-recovery.skill.md backup, restore Disaster recovery
security/cryptography-standards.skill.md crypto, encrypt Encryption audits
security/log-analysis.skill.md log audit, splunk Security log review

| security/network-security.skill.md | firewall, netsec | Network hardening | | security/hazard-analysis.skill.md | hazard, fmea | Safety hazard analysis |

5. Product, Data & Core (product/, data/, core/, coordination/)

Skill Triggers Purpose
product/req-elicitation.skill.md gather reqs Elicit requirements
product/req-elicitation.skill.md gather reqs Elicit requirements
product/spec-writer.skill.md spec, PRD Write verification specs
product/accessibility.skill.md a11y, wcag Accessibility Audit
product/user-story-mapping.skill.md story map, journey User journey mapping
product/stakeholder-management.skill.md stakeholder, raci RACI & Interest map
product/design-thinking.skill.md empathize, ideate Design thinking loop
product/spec-analyze.skill.md analyze spec, gap Spec gap analysis
product/market-analysis.skill.md market, competitor Market research
product/decompose.skill.md decompose, break Task decomposition
product/systems-thinking.skill.md systems, loops Systems dynamics
product/req-review.skill.md review reqs, audit Requirements audit

| data/data-engineering.skill.md | etl, spark | Data pipelines | | data/db-migration.skill.md | migration, sql | DB Schema changes | | data/data-governance.skill.md | lineage, catalog | Data governance | | data/sql-optimization.skill.md | sql opt, index | Query performance | | coding/testing-strategy.skill.md | test strategy, pyramid | Testing Pyramid Strategy | | product/green-software.skill.md | green, carbon | Sustainable Software | | ops/enterprise-integration.skill.md | erp, legacy | Enterprise Patterns | | coordination/multi-agent-orch.skill.md | swarm, delegate | Agent coordination | | coordination/swarm-consensus.skill.md | vote, consensus | Swarm decision making | | coordination/agentic-linter.skill.md | arch lint, boundaries | Architecture enforcement | | coordination/meta-prompting.skill.md | meta prompt, improve | Prompt engineering | | coordination/agent-interop.skill.md | interop, connect | Cross-agent comms | | core/research.skill.md | research, find | Deep research | | core/self-heal.skill.md | fix error, heal | Auto-recovery | | core/system-lifecycle.skill.md | traceability | Trace Req->Code | | core/agent-analytics.skill.md | analytics, stats | Agent performance | | core/knowledge-connect.skill.md | connection, link | Cross-repo knowledge |

6. Neuro-Architecture (brain/)

Skill Triggers Purpose
brain/active-inference.skill.md active inference, surprise Minimizing prediction error loop
brain/global-workspace.skill.md global workspace, consciousness Central blackboard for swarms
brain/sensory-motor.skill.md senses, motor Embodied cognition & feedback control
brain/consciousness-loop.skill.md ooda, self Recursive self-reference (System 2)
brain/self-improvement.skill.md evolve, mutate Evolutionary prompt rewriting
brain/learning-adaptation.skill.md learn, plasticity Reinforcement learning & memory
brain/episodic-consolidation.skill.md consolidate, sleep Memory consolidation
brain/neuroscience-foundations.skill.md neuro, theory Cognitive theory base
brain/epistemology-knowledge.skill.md truth, justify Knowledge validation
brain/cognitive-architectures.skill.md cognitive arch Cognitive patterns
brain/sequential-thinking.skill.md reasoning, step Chain-of-thought
brain/working-memory.skill.md context, memory RAM management

See agents/skills/00-index.md for full details including context costs.

20. Templates Reference

All templates now live in categorized subdirectories under agents/templates/.

Coding & Architecture (templates/coding/, templates/architecture/)

Template Purpose
coding/CLEAN_CODE_CHECKLIST.md Pre-merge code review (SOLID/DRY)
coding/TEST_PLAN_TEMPLATE.md Master Test Plan strategy
coding/TEST_CASE_TEMPLATE.md Manual Test Case documentation
coding/E2E_TEST_SUITE_TEMPLATE.md End-to-End Test Suite
coding/DEVCONTAINER_TEMPLATE.json Dev Container Config
coding/DEV_SPACE_TEMPLATE.yaml DevSpace Config
coding/DESIGN_TOKENS_TEMPLATE.json Design Tokens
architecture/ADR_TEMPLATE.md Architecture Decision Record
architecture/ARCH_DECISION_FRAMEWORK.md Critical decision matrix
architecture/ARCHITECTURE_REVIEW_TEMPLATE.md Structured architecture audit
architecture/ARCHITECTURE_VIEWS_TEMPLATE.md C4/UML View documentation
architecture/DOMAIN_MODEL_TEMPLATE.md DDD Entity & Relationship map
architecture/DESIGN_PATTERN_USAGE.md Pattern Justification
architecture/C4_ARCHITECTURE_TEMPLATE.md C4 Model
core/WHITEBOARD_DESIGN_TEMPLATE.md Canvas Blueprint
architecture/CONTEXT_MAP_TEMPLATE.md Context Map
architecture/SYSTEM_CONTEXT_TEMPLATE.md System Context
architecture/INTEGRATION_SPEC_TEMPLATE.md Integration Spec
architecture/CAPABILITY_MAP_TEMPLATE.md Capability Map
architecture/LEGACY_AUDIT_TEMPLATE.md Legacy Audit
architecture/QUALITY_ATTRIBUTES_TEMPLATE.md Quality Attributes
architecture/CONTEXT_MAP_TEMPLATE.md Context Map
architecture/CAPABILITY_MAP_TEMPLATE.md Capability Map
architecture/SYSTEM_CONTEXT_TEMPLATE.md System Context
architecture/LEGACY_AUDIT_TEMPLATE.md Legacy Audit

Ops & Security (templates/ops/, templates/security/)

Template Purpose
ops/INCIDENT_POSTMORTEM_TEMPLATE.md Incident Root Cause Analysis
ops/CAPACITY_PLAN_TEMPLATE.md Scaling & Load planning
ops/COST_OPTIMIZATION_REPORT_TEMPLATE.md FinOps analysis
ops/BENCHMARK_REPORT_TEMPLATE.md System Benchmark
ops/DEPLOY_CONFIG_TEMPLATE.md Deployment Config
ops/INFRA_PLAN_TEMPLATE.md Infrastructure Plan
ops/RELEASE_READINESS_REPORT.md Release Readiness
ops/TECH_DEBT_TEMPLATE.md Tech Debt Log
security/THREAT_MODEL_TEMPLATE.md STRIDE threat model
security/SECURITY_CHECKLIST.md Pre-release security gate
security/ETHICAL_IMPACT_ASSESSMENT.md AI Ethics check
security/HAZARD_LOG.md Hazard Log
security/SAFETY_POLICY.md Safety Policy
security/SAFETY_CASE.md Safety Case

Product & Core (templates/product/, templates/core/)

Template Purpose
product/PRD_TEMPLATE.md Product Requirements (EARS)
product/SPEC_TEMPLATE.md Technical Specification
product/USER_STORY_MAP_TEMPLATE.md User Journey Mapping
product/BUSINESS_CASE_TEMPLATE.md Business Case
product/EMPATHY_MAP_TEMPLATE.md Empathy Map
product/REQUIREMENTS_REVIEW_TEMPLATE.md Requirements Review
product/STAKEHOLDER_REGISTER_TEMPLATE.md Stakeholder Register
product/NFR_TEMPLATE.md NFR Definition
core/PLAN_TEMPLATE.md Implementation Plan
core/TASKS_TEMPLATE.md Atomic Task breakdown
core/AUDIT_LOG_TEMPLATE.md Project Audit Trail
core/SDLC_TRACKER.md Phase progress board
core/SYSTEM_ANALYSIS_TEMPLATE.md System Analysis
core/SESSION_SNAPSHOT_TEMPLATE.md Complete project state
core/TRACEABILITY_MATRIX_TEMPLATE.md Traceability Matrix
core/BUG_REPORT_TEMPLATE.md Bug Report
core/PROJECT_STATE_TEMPLATE.md Project State
core/CONTINUITY_TEMPLATE.md Continuity Log

Coordination & Brain (templates/coordination/, templates/brain/)

Template Purpose
coordination/AGENTS_TEMPLATE.md Agent Swarm Definition
coordination/SWARM_CONFIG_TEMPLATE.json Multi-agent configuration
coordination/AGENT_PROFILE_TEMPLATE.md Agent Profile
coordination/AGENT_HANDSHAKE_TEMPLATE.json Agent Handshake
coordination/VOTING_LOG_TEMPLATE.md Agent Consensus Voting Record
coordination/SWARM_ARCHITECTURE_TEMPLATE.md Swarm Architecture
brain/ACTIVE_INFERENCE_LOOP_TEMPLATE.md Cognitive loop structure
brain/GLOBAL_WORKSPACE_CONFIG_TEMPLATE.md GWT Blackboard config
brain/SELF_IMPROVEMENT_LOG_TEMPLATE.md Self-Improvement Log
brain/KNOWLEDGE_MAP_TEMPLATE.md Knowledge Map
brain/OODA_LOOP_TRACE_TEMPLATE.md OODA Loop Trace
brain/WORKING_MEMORY_TEMPLATE.md Working Memory
brain/EPISODIC_MEMORY_LOG_TEMPLATE.md Episodic Memory
brain/PREDICTION_ERROR_LOG_TEMPLATE.md Prediction Error

Data (templates/data/)

Template Purpose
data/DATA_PIPELINE_TEMPLATE.md Data Pipeline
data/DATABASE_SCHEMA_TEMPLATE.md Database Schema
data/ONTOLOGY_TEMPLATE.md Meta-Data

Industry & Specialized (templates/industry/, templates/product/)

Template Purpose
industry/FHIR_INTEGRATION_TEMPLATE.md Healthcare
industry/IOT_TELEMETRY_TEMPLATE.md IIoT
industry/TELECOM_API_TEMPLATE.md Telecom
industry/GLOBAL_STANDARDS_AUDIT_TEMPLATE.md compliance
industry/ENGINEERING_STANDARDS_REVIEW_TEMPLATE.md Engineering
product/GREEN_SOFTWARE_REPORT_TEMPLATE.md Sustainability
architecture/SCALABILITY_ANALYSIS_TEMPLATE.md Architecture
architecture/SMART_CONTRACT_TEMPLATE.md Blockchain
architecture/ARCHITECTURE_DECISION_MATRIX.md Architecture
core/PROJECT_CONTEXT_TEMPLATE.md Core
product/PROBLEM_STATEMENT_TEMPLATE.md Product
product/IDEATION_LOG_TEMPLATE.md Product

21. MCP Configuration

MCP (Model Context Protocol) servers extend agent capabilities. Configure them in templates/core/MCP_CONFIG_TEMPLATE.json. For detailed installation and setup guides for each server, see MCP_CONFIGURATIONS.md.

Essential MCP servers:

Category Server Purpose
Docs Context-7 MCP Up-to-date SDK docs (prevents API hallucination)
Reasoning Sequential Thinking Chain-of-thought before acting
Code Search GitHub MCP PR review, code search, issue management
Dependencies GitHits MCP Navigate open-source dependency source/docs (no clone, no key)
Database PostgreSQL MCP Live schema introspection
Security Semgrep MCP SAST scanning from within the agent
Web Search Brave Search / Tavily Authoritative source research
Memory Qdrant MCP Semantic long-term memory retrieval
Browser Playwright MCP Browser automation for visual TDD
Monitoring Sentry MCP Error tracking and incident context
Complexity Time Complexity MCP Big-O static analysis via tree-sitter
Diagramming Excalidraw MCP Programmatic Excalidraw diagram creation
Vision Image Recognition MCP Sketch recognition via vision APIs
Canvas tldraw MCP Persistent visual canvas for wireframing
Filesystem Filesystem MCP Local file access for internal RAG

Full coverage matrix (66 MCP servers in MCP_CONFIG_TEMPLATE.json):

Integration Domain Servers Available
External APIs GraphQL, OpenAPI, Stripe, Zapier
Databases PostgreSQL, MongoDB, Redis, SQLite, DBHub (universal)
Knowledge Bases Qdrant, Pinecone, Chroma, Weaviate, Elasticsearch
Web Scraping Firecrawl, Brave Search, Tavily, DuckDuckGo
Internal RAG Filesystem, Shell, Jupyter, Context-7
Observability Sentry, Datadog, Grafana
Code Quality Semgrep, Snyk, SonarQube, Gitleaks, Time Complexity
Project Mgmt GitHub, GitLab, Jira, Linear, Notion, Confluence, Slack
Dependencies GitHits (navigate open-source dependency source, docs, issues, changelogs)
Cloud/Infra AWS Core, Kubernetes, Figma

Security rules:

  • Production databases: read-only access only
  • Dev databases: read-write allowed
  • Secrets/credentials: never passed as MCP config, use env vars

See templates/core/MCP_CONFIG_TEMPLATE.json for the full catalog with install commands. See MCP_CONFIGURATIONS.md for comprehensive per-server installation, API key setup, and usage guides.

22. Extending the Kit

Adding Custom Skills

  1. Create File: Add a new .skill.md file in agents/skills/.
    • Naming convention: your-skill-name.skill.md.
  2. Format: Use the standard YAML header + Markdown body: 
    ---
name: [Skill Name]
description: [What it does]
context_cost: [low/medium/high]
---
# [Skill Name]

## Triggers
- [trigger word 1]
- [trigger word 2]

## Instructions
[Detailed steps for the agent to follow]
  3. Register: Run scripts/init.py (or agents/setup-context.sh) to symlink changes.

Adding Custom MCP Servers

  1. Edit Config Template: Open agents/templates/core/MCP_CONFIG_TEMPLATE.json.
  2. Add Server: Insert your MCP server configuration into the mcpServers object.
  3. Apply to Tool:
    • Claude Desktop: Copy the content to ~/Library/Application Support/Claude/claude_desktop_config.json.
    • VS Code / Cursor: Add to your workspace settings or extension configuration.
  4. Restart: Restart your AI tool to load the new server.

Where to Find More

Skill Registries:

MCP Registries:

23. Loki Mode (Large Projects)

Loki Mode activates a multi-agent swarm for large projects (new product builds, major refactors, system migrations) where a single agent would hit context limits or require sustained multi-day work.

When to use Loki Mode:

  • Building a new product from scratch (> 5 features)
  • Major refactors touching > 20 files
  • Multi-service architecture
  • Projects running over multiple sessions/days

Invoke:

"Activate Loki Mode. Goal: [build X / migrate Y / refactor Z]"

24. What's Inside?

Stats: 214 Skills · 100 Templates · 36 Personas · 86 Guides

Category Count Skills Included
Coding 10+ tdd-cycle, debug, refactor, code-review, git-workflow
Architecture 15+ arch-design, microservices, systems-architecture, system-scalability, blockchain-dlt
Operations 15+ reliability-sre, production-health, dev-environments, cost-optimization
Security 15+ security-audit, secure-architecture, privacy-data-protection, api-security
Product 10+ spec-writer, req-elicitation, green-software, sustainability-checks
Core 10+ research, self-heal, knowledge-gap, meta-optimize
Data 5+ data-engineering, db-migration, semantic-web
Coordination 5+ multi-agent-orch, agent-protocol
Brain 10+ active-inference, consciousness-loop, cost-benefit-router
AI/Swarm 5+ multi-agent-systems, agent-communication, beyond-llms
Industry 5+ healthcare-fhir, telecom-networks, industrial-iot, global-standards, engineering-standards
Loki Modes 2+ brain-mode, loki-mode

25. 🚀 Common Actions (Copy-Paste Prompts)

Copy and paste these exact prompts into your AI chat window to kick off standard workflows.

New Project from Scratch

"Read AGENTS.md. I want to build [description]. Start with spec-writer skill."

Flow: Spec → Design → Tasks → TDD Implementation → Security → Deploy

Resume Existing Project

"Read AGENTS.md and agents/memory/PROJECT_STATE.md. Resume the project."

Fix a Bug

"Read AGENTS.md. Bug: [description]. Use debug skill with TDD."

Flow: Reproduce → Root Cause → Failing Test → Fix → Green → Regression Check

Refactor / Pay Tech Debt

"Use tech-debt skill on [directory]. Then refactor the top-priority item."

Security Audit

"Run security-audit skill on the entire codebase."

Architecture Review

"Run arch-review skill. Check for SOLID violations and coupling."

Software Engineering & System Architecture

"Act as a Principal Staff Engineer. Review the codebase in [directory] and generate a C4 system architecture diagram (Context and Container levels). Identify any bottlenecks and propose scaling strategies."

"Use the design-patterns and domain-model skills. We are building a [feature segment]. Propose the optimum architecture pattern (e.g. Event-driven, CQRS, Hexagonal) and define the core domain entities."

Vibe-Coding (Creative Frontend)

"Use the vibe-coding skill. Build a [component/page] using [framework]. I want it to feel [aesthetic, e.g. glassmorphism, cyberpunk, sleek corporate]. Include micro-animations and smooth transitions. Prioritize visual WOW over generic utility."

Activate Brain Mode (Complex Goals)

"Activate Brain Mode. Goal: [build X / migrate Y / solve Z]."

Activate Loki Mode (Large Projects)

Using the CLI:

gabbe brain activate (Loki may be triggered autonomously by the Brain based on context cost). Or activate the swarm skill explicitly: Activate agents/skills/brain/loki-mode.skill.md with your goal.

Using Pure Agent Mode (No CLI):

"Activate agents/skills/brain/loki-mode.skill.md. Goal: [build X]. Do not ask me for permission unless you hit a mandatory Human Approval Gate or a task requires True A2A Delegation."

26. Guides by Technology Stack

Guide Stack Key Topics
guides/principles/full-system-lifecycle.md Process/SDLC Traceability, Golden Thread, DoD
guides/architecture/system-qualities.md Architecture/Ops Reliability, SRE, Scalability
guides/ops/production-health.md Ops/SRE Health Checks & Monitoring
guides/principles/future-tech.md Future/2030 6G, IoT Matter, Vector DBs, WASM
guides/principles/legacy-tech.md Legacy/Mainframe COBOL, Fortran, Modernization
guides/ops/dev-environments.md Dev Environment Local vs Remote vs Cloud, Docker Watch
guides/ops/dev-workflow.md Ops/Workflow Diátaxis Docs, GitHub CLI, Commit Standards
guides/patterns/enterprise-patterns.md Enterprise Strangler Fig, ACL, CDC, Legacy Migration
guides/architecture/api-standards.md API Design REST, GraphQL, Versioning, Governance
guides/principles/testing-strategy.md Testing Pyramid, Trophy, Contract Testing
guides/architecture/event-driven-architecture.md Architecture EDA, Async, Event Sourcing
guides/patterns/design-patterns.md Design Patterns Strategy, Factory, Observer, Adapter
guides/principles/clean-code-standards.md Clean Code SOLID, DRY, KISS, Refactoring
guides/patterns/agentic-patterns.md AI/Agentic Reflection, Memory, Planning, Tools
guides/patterns/ai-native-scenarios.md AI/Agentic Vibe-to-Code, Auto-Patching, DB Refactor
guides/patterns/enterprise-migration-scenario.md Enterprise Strangler Fig, Migration paths

| guides/principles/RARV_CYCLE.md | AI/Agentic | Reason-Act-Reflect-Verify loop | | guides/ai/self-healing-summary.md | AI/Agentic | Self-healing architecture & loops | | guides/languages/js-ts-nodejs.md | Python/Node/React | Swarms, Orchestration, A2A Protocol | | guides/patterns/autonomous-swarm-patterns.md | AI/Agentic | Self-organizing Swarm Patterns | | guides/ai/agent-communication.md | All Stacks | MCP, A2A, ACP, Handshake Protocols | | guides/languages/js-ts-nodejs.md | JS/TS/Node.js | Clean Architecture, Vitest, Zod, Prisma, Playwright | | guides/languages/nodejs-advanced.md | Node.js Advanced | Fastify Architecture, Internals, Zero-Any TS | | guides/languages/go-lang.md | Go (Golang) | Echo/Gin, Ent, Testify, Clean Arch | | guides/languages/php-laravel.md | PHP/Laravel | DDD, Actions, Pest PHP, PHPStan L9, Enlightn | | guides/languages/python-fastapi-ai.md | Python/FastAPI/AI | Clean Architecture, Pydantic, Agents | | guides/security/cryptography-standards.md | Security | Encryption, Hashing, PQC Readiness | | guides/security/threat-modeling.md | Security | STRIDE, Attack Trees, Risk Assessment |

| guides/data/sql-nosql.md | SQL/NoSQL | Migration-first, PostgreSQL patterns, Redis, MongoDB | | guides/languages/rust.md | Rust | Cargo, Ownership, Actix, SQLx, Agents | | guides/languages/java.md | Java | Spring Boot, Quarkus, Maven/Gradle, ArchUnit | | guides/languages/c-sharp.md | C# / .NET | ASP.NET Core, Entity Framework, Dapr |

| guides/ops/compliance-audit.md | Compliance & Audit | GDPR, SOC2 logging, Privacy Engineering | | guides/ops/troubleshooting-guide.md | Ops | Debugging, Root Cause, Recovery | | guides/ops/self-healing-summary.md | Ops | Automated recovery patterns |

| guides/ai/ai-agentic.md | AI/Agentic | RARV, SDD lifecycle, Memory Architecture, MCP config | | guides/architecture/microservices.md | Microservices | Bounded contexts, event-driven, contract testing | | guides/architecture/systems-architecture.md | Architecture | C4 models, quality attributes, decision records | | guides/planning/product-requirements.md | Product | EARS syntax, user stories, prioritization | | guides/planning/strategic-analysis.md | Strategy | Business case, design thinking, systems loops | | guides/principles/diagramming-standards.md | Diagrams | Mermaid.js class, sequence, state diagrams | | guides/ai/visual-mcp-integration.md | Diagrams | Rules for Visual vs Text diagramming rendering | | guides/principles/visual-design-system.md | Design | Design Tokens & UI Architecture | | guides/ai/agent-ui.md | UI/UX | Generative UI, HTMX, TUI, ShadCN | | guides/principles/no-code-integration.md | No-Code | n8n, Make, Zapier, Hybrid Workflows | | guides/ai/actor-agent-frameworks.md | Architecture | Akka, Erlang, LangGraph comparison (actor-agent-frameworks.skill) | | guides/ai/a2ui-protocols.md | UI/UX | A2UI, GenUI, AG-UI standards (a2ui-protocols.skill) | | guides/architecture/critical-systems-arch.md | Safety | DO-178C, IEC 62304, DDD, Hexagonal (critical-systems-arch.skill) | | guides/ai/beyond-llms.md | AI Theory | Neuro-symbolic, Genetic Algos, Active Inference (beyond-llms.skill) | | agents/skills/brain/ | Neuro-Arch | The Brain Metaphor: Cognitive Software Patterns | | guides/architecture/monolith.md | Monolith | Vertical slices, modular monolith, Strangler Fig (monolith.skill) |

Subject-Specific Guides

Topic Guide
Product guides/product-requirements.md (PRD/Spec), guides/strategic-analysis.md (Strategy)
Architecture guides/critical-systems-arch.md, guides/event-driven-architecture.md
Integration guides/knowledge-integration.md, guides/no-code-integration.md, guides/api-standards.md
Agents guides/actor-agent-frameworks.md, guides/autonomous-swarm-patterns.md, guides/agent-communication.md
UI/UX guides/visual-design-system.md, guides/a2ui-protocols.md, guides/agent-ui.md
Lifecycle guides/production-health.md, guides/beyond-llms.md
Industry guides/industry/engineering-standards.md, guides/industry/global-standards.md, guides/industry/telecom-networks.md

27. Troubleshooting

Agent ignores AGENTS.md:

  • Run setup-context.sh to create tool-specific symlinks
  • For Cursor: verify .cursorrules file exists (symlink created by setup script)
  • For Claude Code: verify .claude/CLAUDE.md exists

Agent repeats past mistakes:

  • Check agents/memory/CONTINUITY.md — past failures should be logged here
  • Tell agent: "Read CONTINUITY.md before starting. What past mistakes are recorded?"

Tests always pass immediately (false positive):

  • tdd-cycle.skill includes a false-positive check: if test passes with no implementation, the test is wrong
  • Tell agent: "The test passed immediately — that means the test is broken. Fix the test to actually fail first."

Agent uses deprecated APIs:

  • Activate Context-7 MCP: it provides up-to-date SDK docs to prevent this
  • Add to AGENTS.md Research Policy: "Always use Context-7 MCP before calling any library method"

Session lost after interruption:

  • Tell agent: "Use session-resume skill to load all memory and continue."
  • All memory is stored in agents/memory/ — it persists across sessions

Agent makes architecture decisions without asking:

  • Add to AGENTS.md Human-in-the-Loop section: "Architecture changes require human approval"
  • Check CONSTITUTION.md — Article VII should cover this

Context window too large / slow responses:

  • Use context_cost: low skills for routine tasks
  • Activate Loki Mode: specialized personas have smaller, focused context scopes

This kit is maintained in agents/. Research is documented in docs/. For team adoption, see QUICK_GUIDE.md for the 4-phase adoption roadmap.

See README.md for quick reference. See skills/00-index.md for complete skills registry with installation instructions. See agents/skills/brain/README_ORCHESTRATORS.md for Loki Mode multi-agent orchestration. See agents/skills/brain/README.md and README_ORCHESTRATORS.md for complete brain documentation.

© 2026 Andrei Nicolae Besleaga. This work is licensed CC BY-SA 4.0