@techwavedev/agi-agent-kit 1.3.4 → 1.3.6

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@techwavedev/agi-agent-kit",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "Enterprise-Grade Agentic Framework - Modular skill-based AI assistant toolkit with deterministic execution, semantic memory, and platform-adaptive orchestration.",
   "bin": {
     "agi-agent-kit": "./bin/init.js"
   },
+  "scripts": {
+    "prepublishOnly": "python3 .agent/scripts/release_gate.py"
+  },
   "files": [
     "bin/",
     "templates/",

package/templates/base/.agent/scripts/release_gate.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Script: release_gate.py
+Purpose: Enforce strict quality checks before release (npm publish or public merge).
+Checks:
+1. Documentation (README/CHANGELOG updated?)
+2. Security (Secret scanning)
+3. Code Integrity (Syntax check)
+4. Version Consistency (package.json)
+"""
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# Configuration
+ROOT_DIR = Path(__file__).resolve().parent.parent.parent
+SENSITIVE_PATTERNS = [
+    r"(?i)aws_access_key_id\s*=\s*['\"](AKIA[0-9A-Z]{16})['\"]",
+    r"(?i)api_key\s*=\s*['\"](sk-[a-zA-Z0-9]{32,})['\"]",
+    r"(?i)private_key\s*=\s*['\"](-----BEGIN PRIVATE KEY-----)['\"]",
+]
+REQUIRED_DOCS = ["README.md", "CHANGELOG.md"]
+
+def run_command(cmd, cwd=ROOT_DIR):
+    """Run a shell command and return output."""
+    try:
+        result = subprocess.run(
+            cmd, shell=True, check=True, capture_output=True, text=True, cwd=cwd
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Command failed: {cmd}")
+        print(e.stderr)
+        return None
+
+def check_git_status():
+    """Ensure working directory is clean."""
+    print("🔍 Checking Git status...")
+    status = run_command("git status --porcelain")
+    if status:
+        print("⚠️  Uncommitted changes detected:")
+        print(status)
+        response = input("Continue anyway? (y/N): ")
+        if response.lower() != 'y':
+            sys.exit(1)
+    else:
+        print("✅ Git working directory clean.")
+
+def check_documentation():
+    """Verify documentation updates."""
+    print("🔍 Verifying documentation...")
+    for doc in REQUIRED_DOCS:
+        if not (ROOT_DIR / doc).exists():
+            print(f"❌ Missing required document: {doc}")
+            sys.exit(1)
+        
+        # Check if modified in last commit (optional but good practice)
+        # diff = run_command(f"git diff head --name-only | grep {doc}")
+        # if diff:
+        #     print(f"✅ {doc} updated in staged/recent changes.")
+        
+    print("✅ Documentation present.")
+
+def scan_secrets():
+    """Scan for hardcoded secrets."""
+    print("🔍 Scanning for secrets...")
+    issues = []
+    # Scan python, js, md files
+    for ext in ["py", "js", "md", "json"]:
+        for path in ROOT_DIR.rglob(f"*.{ext}"):
+            if "node_modules" in str(path) or ".git" in str(path):
+                continue
+            try:
+                content = path.read_text(errors="ignore")
+                for pattern in SENSITIVE_PATTERNS:
+                    match = re.search(pattern, content)
+                    if match:
+                        issues.append(f"{path}: Potential secret found via regex")
+            except Exception:
+                pass
+
+    if issues:
+        print("❌ Security issues found:")
+        for issue in issues:
+            print(f"   - {issue}")
+        sys.exit(1)
+    print("✅ No hardcoded secrets found.")
+
+def check_versions():
+    """Check package.json version matches changelog."""
+    print("🔍 Checking version consistency...")
+    pkg_json = ROOT_DIR / "package.json"
+    changelog = ROOT_DIR / "CHANGELOG.md"
+    
+    if pkg_json.exists():
+        data = json.loads(pkg_json.read_text())
+        version = data.get("version")
+        print(f"ℹ️  Package version: {version}")
+        
+        if changelog.exists():
+            content = changelog.read_text()
+            if version not in content:
+                print(f"⚠️  Version {version} not found in CHANGELOG.md!")
+                response = input("Continue anyway? (y/N): ")
+                if response.lower() != 'y':
+                    sys.exit(1)
+            else:
+                print("✅ Version present in CHANGELOG.")
+
+def syntax_check():
+    """Run basic syntax check."""
+    print("🔍 verifying Python syntax...")
+    # Find all python files
+    py_files = list(ROOT_DIR.rglob("*.py"))
+    failed = False
+    for py in py_files:
+        if "node_modules" in str(py) or ".venv" in str(py):
+            continue
+        try:
+            subprocess.run(["python3", "-m", "py_compile", str(py)], check=True, capture_output=True)
+        except subprocess.CalledProcessError:
+            print(f"❌ Syntax error in {py}")
+            failed = True
+    
+    if failed:
+        sys.exit(1)
+    print("✅ Python syntax valid.")
+
+def main():
+    print("🚀 Starting Release Gate Protocol...")
+    print("-----------------------------------")
+    
+    check_git_status()
+    check_documentation()
+    scan_secrets()
+    check_versions()
+    syntax_check()
+    
+    print("-----------------------------------")
+    print("✅ All checks passed. Ready for release.")
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/templates/base/.agent/workflows/release-protocol.md

@@ -0,0 +1,43 @@
+---
+description: Comprehensive Release Protocol for Agi Agent Kit. Enforces documentation reviews, security scans, and version checks before any publish or public merge.
+---
+
+## Release Governance Protocol (MANDATORY)
+
+Before merging to `public` branch or running `npm publish`, execute this protocol.
+
+### 1. Preparation
+
+- [ ] Ensure `CHANGELOG.md` is updated with all features/fixes.
+- [ ] Ensure `package.json` version is bumped correctly (semver).
+- [ ] Review `README.md` for any API changes.
+
+### 2. Automated Gate
+
+Run the Release Gate script to enforce checks:
+
+```bash
+python3 .agent/scripts/release_gate.py
+```
+
+This script will verify:
+
+- Git status (clean working tree)
+- Documentation presence
+- Secret scanning (no API keys)
+- Version consistency
+- Python syntax validity
+
+### 3. Manual Review
+
+- [ ] Check if `AGENTS.md` reflects new capabilities.
+- [ ] Verify `memory_integration.md` if memory system changed.
+- [ ] Ensure no temporary files in `execution/` or `skills/` unless intended.
+
+### 4. Publish
+
+Only proceed if Step 2 passes.
+
+```bash
+npm publish --access public
+```

package/templates/base/AGENTS.md

@@ -1,6 +1,6 @@
 # Agent Instructions
 
-> `CLAUDE.md`, `GEMINI.md`, and `OPENCODE.md` are symlinks to this file, so the same instructions load in any AI environment.
+> `CLAUDE.md`, `GEMINI.md`, `OPENCODE.md`, `COPILOT.md`, and `OPENCLAW.md` are symlinks to this file, so the same instructions load in any AI environment.
 
 ---
 
@@ -163,7 +163,7 @@ python execution/scrape_single_site.py \
 
 ### 1. Memory-First (Automatic)
 
-**All operations use the Qdrant-powered memory system by default.**
+**All operations use the Hybrid Memory System (Qdrant + BM25) by default.**
 
 #### Session Start (MANDATORY — run once per session)
 
@@ -270,6 +270,33 @@ Before marking a task complete:
 - Spot-check data quality where possible
 - Confirm deliverables are in the expected location (cloud service, output file, etc.)
 
+### 6. Release Governance Protocol (MANDATORY)
+
+**Before merging to `public` branch or publishing to NPM, YOU MUST:**
+
+1.  **Execute the Release Gate**:
+
+    ```bash
+    python3 .agent/scripts/release_gate.py
+    ```
+
+    This validates:
+    - Documentation (README/CHANGELOG) presence & updates
+    - Security (Secret scanning)
+    - Code Syntax (Python/JS)
+    - Version Consistency (package.json vs CHANGELOG)
+    - Git Status (Clean working tree)
+
+2.  **Verify Workflow**:
+    - Review `.agent/workflows/release-protocol.md` for manual steps.
+    - Ensure `AGENTS.md` and `memory_integration.md` are up-to-date with code.
+
+3.  **Publish via Script**:
+    - Do NOT run `npm publish` manually.
+    - Run `npm run prepublishOnly` (or relying on the lifecycle hook) to enforce the gate.
+
+**ZERO TOLERANCE:** Never bypass the Release Gate. If it fails, FIX the issue. Do not force push.
+
 ---
 
 ## File Organization

package/templates/base/README.md

@@ -1,13 +1,37 @@
-# AGI Agent Kit
+# 🚀 AGI Agent Kit
 
-**Enterprise-Grade Agentic Framework & Scaffolding Tool**
+> **Stop hallucinating. Start executing.**
 
 [![npm version](https://img.shields.io/npm/v/@techwavedev/agi-agent-kit.svg)](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)
+[![npm downloads](https://img.shields.io/npm/dw/@techwavedev/agi-agent-kit.svg)](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai)
+[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Google-blue)](https://github.com/google-gemini/gemini-cli)
+[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-OpenAI-green)](https://github.com/openai/codex)
+[![Cursor](https://img.shields.io/badge/Cursor-AI%20IDE-orange)](https://cursor.sh)
+[![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-VSCode-lightblue)](https://github.com/features/copilot)
+[![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode)
+[![Antigravity IDE](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/techwavedev/agi-agent-kit)
+[![AdaL CLI](https://img.shields.io/badge/AdaL%20CLI-SylphAI-pink)](https://sylph.ai/)
+[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a-coffee-d13610?logo=buymeacoffee&logoColor=white)](https://www.buymeacoffee.com/eltonmachado)
 
-`@techwavedev/agi-agent-kit` is a modular, deterministic framework designed to bridge the gap between LLM reasoning and reliable production execution. It scaffolds a "3-Layer Architecture" (Intent → Orchestration → Execution) that forces agents to use tested scripts rather than hallucinating code.
+**AGI Agent Kit** is the enterprise-grade scaffolding that turns any AI coding assistant into a **deterministic production machine**. While LLMs are probabilistic (90% accuracy per step = 59% over 5 steps), this framework forces them through a **3-Layer Architecture** — Intent → Orchestration → Execution — where business logic lives in tested scripts, not hallucinated code.
 
-**v1.3.4** — Now with **861 curated skills** (including 782 community skills from [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)), **8-platform support** (Claude Code, Gemini CLI, Codex CLI, Cursor, Copilot, OpenCode, AdaL CLI, Antigravity IDE), structured plan execution, TDD enforcement, verification gates (adapted from [obra/superpowers](https://github.com/obra/superpowers)), and semantic memory.
+### Why this exists
+
+Most AI coding setups give you a prompt and hope for the best. AGI Agent Kit gives you:
+
+- 🧠 **Semantic Memory** — Qdrant-powered caching that eliminates redundant LLM calls (90-100% token savings)
+- 🎯 **19 Specialist Agents** — Domain-bounded experts (Frontend, Backend, Security, Mobile, Game Dev...) with enforced file ownership
+- ⚡ **861 Curated Skills** — 4 core + 75 professional + 782 community skills across 16 domain categories
+- 🔒 **Verification Gates** — No task completes without evidence. TDD enforcement. Two-stage code review.
+- 🌐 **8 Platforms, One Config** — Write once, run on Claude Code, Gemini CLI, Codex CLI, Cursor, Copilot, OpenCode, AdaL CLI, Antigravity IDE
+
+```bash
+npx @techwavedev/agi-agent-kit init
+```
+
+If this project helps you, consider [supporting it here](https://www.buymeacoffee.com/eltonmachado) or simply ⭐ the repo.
 
 ---
 
@@ -154,81 +178,6 @@ python3 execution/memory_manager.py auto \
 # → {"source": "cache", "cache_hit": true, "tokens_saved_estimate": 12}
 ```
 
----
-
-## 🧪 Real Benchmark: Subagents vs Agent Teams
-
-The framework supports two orchestration modes. Here are **real test results** from `execution/benchmark_modes.py` running on local infrastructure (Qdrant + Ollama `nomic-embed-text`, zero cloud API calls):
-
-```
-MODE A: SUBAGENTS — Independent, fire-and-forget
-  📤 Explore Auth Patterns    → ✅ stored in cache + memory (127ms)
-  📤 Query Performance        → ❌ FAILED (timeout — fault tolerant)
-  📤 Scan CVEs                → ✅ stored in cache + memory (14ms)
-  Summary: 2/3 completed, 1 failed, 0 cross-references
-
-MODE B: AGENT TEAMS — Shared context, coordinated
-  👤 Backend Specialist       → ✅ stored in shared memory (14ms)
-  👤 Database Specialist      → ✅ stored in shared memory (13ms)
-  👤 Frontend Specialist      → 🔗 Read Backend + Database output first
-     ✅ Got context from team-backend: "API contract: POST /api/messages..."
-     ✅ Got context from team-database: "Schema: users(id UUID PK, name..."
-     → ✅ stored in shared memory (14ms)
-  Summary: 3/3 completed, 0 failed, 2 cross-references
-```
-
-**2nd run (cache warm):** All queries hit cache at **score 1.000**, reducing total time from 314ms → 76ms (Subagents) and 292ms → 130ms (Agent Teams).
-
-| Metric               | Subagents                            | Agent Teams                          |
-| -------------------- | ------------------------------------ | ------------------------------------ |
-| Execution model      | Fire-and-forget (isolated)           | Shared context (coordinated)         |
-| Tasks completed      | 2/3 (fault tolerant)                 | 3/3                                  |
-| Cross-references     | 0 (not supported)                    | 2 (peers read each other's work)     |
-| Context sharing      | ❌ Each agent isolated               | ✅ Peer-to-peer via Qdrant           |
-| Two-stage review     | ❌                                   | ✅ Spec + Quality                    |
-| Cache hits (2nd run) | 5/5                                  | 5/5                                  |
-| Embedding provider   | Ollama local (nomic-embed-text 137M) | Ollama local (nomic-embed-text 137M) |
-
-**Try it yourself:**
-
-```bash
-# 1. Start infrastructure
-docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
-ollama serve & ollama pull nomic-embed-text
-
-# 2. Boot memory system
-python3 execution/session_boot.py --auto-fix
-# ✅ Memory system ready — 5 memories, 1 cached responses
-
-# 3. Run the full benchmark (both modes)
-python3 execution/benchmark_modes.py --verbose
-
-# 4. Or test individual operations:
-
-# Store a decision (embedding generated locally via Ollama)
-python3 execution/memory_manager.py store \
-  --content "Chose PostgreSQL for relational data" \
-  --type decision --project myapp
-# → {"status": "stored", "point_id": "...", "token_count": 5}
-
-# Auto-query: checks cache first, then retrieves context
-python3 execution/memory_manager.py auto \
-  --query "what database did we choose?"
-# → {"source": "memory", "cache_hit": false, "context_chunks": [...]}
-
-# Cache an LLM response for future reuse
-python3 execution/memory_manager.py cache-store \
-  --query "how to set up auth?" \
-  --response "Use JWT with 24h expiry, refresh tokens in httpOnly cookies"
-
-# Re-query → instant cache hit (score 1.000, zero re-computation)
-python3 execution/memory_manager.py auto \
-  --query "how to set up auth?"
-# → {"source": "cache", "cache_hit": true, "tokens_saved_estimate": 12}
-```
-
----
-
 ## 🌐 Platform Support
 
 The framework automatically detects your AI coding environment and activates the best available features.

package/templates/base/directives/memory_integration.md

@@ -2,7 +2,12 @@
 
 ## Goal
 
-Ensure all AI agents use the Qdrant-powered memory system by default to save tokens and preserve context across sessions. Embedding is handled locally via Ollama (`nomic-embed-text`, 768 dimensions) at zero cost.
+Ensure all AI agents use the **Hybrid Memory System (Qdrant + BM25)** by default to save tokens, preserve context, and avoid redundant work.
+
+- **Semantic Memory (Qdrant)**: Concept matching (e.g., "how do I fix econnrefused")
+- **Keyword Memory (BM25)**: Exact matching (e.g., "error 503", "sg-018f20ea", "API_KEY")
+
+Using memory provides **90-100% token savings** on repeated tasks.
 
 ## Inputs
 
@@ -10,24 +15,15 @@ Ensure all AI agents use the Qdrant-powered memory system by default to save tok
 - Project name (optional, for scoped retrieval)
 - Memory type classification (auto-detected or explicit)
 
-## Prerequisites
-
-| Component          | Required | Check Command                                       |
-| ------------------ | -------- | --------------------------------------------------- |
-| Qdrant (Docker)    | Yes      | `curl http://localhost:6333/collections`             |
-| Ollama             | Yes      | `curl http://localhost:11434/api/tags`               |
-| nomic-embed-text   | Yes      | `ollama pull nomic-embed-text`                       |
-| Collections setup  | Yes      | `python3 execution/session_init.py`                  |
-
 ## Execution Protocol
 
 ### 1. Session Start (Run Once)
 
 ```bash
-python3 execution/session_init.py
+python3 execution/session_boot.py --auto-fix
 ```
 
-This verifies Qdrant, Ollama, and creates `agent_memory` (768d) and `semantic_cache` (768d) collections if they don't exist.
+Checks Qdrant, Ollama, collections, and BM25 index. Auto-heals if broken.
 
 ### 2. Before Every Complex Task
 
@@ -37,13 +33,15 @@ python3 execution/memory_manager.py auto --query "<user request summary>"
 
 **Decision tree based on result:**
 
-| Result             | Action                                                   |
-| ------------------ | -------------------------------------------------------- |
-| `cache_hit: true`  | Use cached response directly. Inform user of cache hit.  |
-| `source: memory`   | Inject retrieved context chunks into your reasoning.     |
-| `source: none`     | Proceed normally. Store the result when done.            |
+| Result            | Action                                                  |
+| ----------------- | ------------------------------------------------------- |
+| `cache_hit: true` | Use cached response directly. Inform user of cache hit. |
+| `source: memory`  | Inject retrieved context chunks into your reasoning.    |
+| `source: none`    | Proceed normally. Store the result when done.           |
 
-### 3. After Key Decisions or Solutions
+### 3. Storing Knowledge (Auto-Indexed)
+
+Whenever you solve a problem or make a decision:
 
 ```bash
 python3 execution/memory_manager.py store \
@@ -53,7 +51,11 @@ python3 execution/memory_manager.py store \
   --tags relevant-tag1 relevant-tag2
 ```
 
-### 4. After Completing a Complex Task (Cache the Response)
+> **Note:** This automatically updates both Qdrant (vectors) and BM25 (keywords).
+
+### 4. Cache the Response
+
+After completing a complex task:
 
 ```bash
 python3 execution/memory_manager.py cache-store \
@@ -61,35 +63,34 @@ python3 execution/memory_manager.py cache-store \
   --response "The complete response that was generated"
 ```
 
-## Memory Type Guide
+## Hybrid Search Modes
 
-| Type           | When to Store                                    | Retention |
-| -------------- | ------------------------------------------------ | --------- |
-| `decision`     | Architecture choice, tech selection, trade-off   | Permanent |
-| `code`         | Reusable pattern, snippet, config                | Permanent |
-| `error`        | Bug fix with root cause and solution             | 90 days   |
-| `technical`    | API docs, library quirks, config patterns        | Permanent |
-| `conversation` | User preference, constraint, project context     | 30 days   |
+If you need specific lookup behavior, use `hybrid_search.py` directly:
 
-## Token Savings Reference
+```bash
+# True Hybrid (Default) - Best for general refactoring
+python3 scripts/hybrid_search.py --query "fix auth error" --mode hybrid
+
+# Vector Only - Best for conceptual research
+python3 scripts/hybrid_search.py --query "authentication patterns" --mode vector
+
+# Keyword Only - Best for error codes/IDs
+python3 scripts/hybrid_search.py --query "sg-018f20ea63e82eeb5" --mode keyword
+```
 
-| Scenario              | Without Memory | With Memory | Savings |
-| --------------------- | -------------- | ----------- | ------- |
-| Repeated question     | ~2000 tokens   | 0 tokens    | 100%    |
-| Similar architecture  | ~5000 tokens   | ~500 tokens | 90%     |
-| Past error resolution | ~3000 tokens   | ~300 tokens | 90%     |
-| Context from history  | ~10000 tokens  | ~1000 tokens| 90%     |
+## Memory Type Guide
+
+| Type           | When to Store                                  | Retention |
+| -------------- | ---------------------------------------------- | --------- |
+| `decision`     | Architecture choice, tech selection, trade-off | Permanent |
+| `code`         | Reusable pattern, snippet, config              | Permanent |
+| `error`        | Bug fix with root cause and solution           | 90 days   |
+| `technical`    | API docs, library quirks, config patterns      | Permanent |
+| `conversation` | User preference, constraint, project context   | 30 days   |
 
 ## Edge Cases
 
 - **Qdrant not running:** Log warning, proceed without memory. Never block user workflow.
-- **Ollama not running:** Same as above. Memory is optional, never mandatory for task completion.
-- **Stale cache:** Cache entries older than 7 days are auto-cleared. Run `python3 execution/memory_manager.py cache-clear --older-than 7` manually if needed.
-- **Dimension mismatch:** If switching providers (e.g., OpenAI→Ollama), run `python3 execution/session_init.py --force` to recreate collections with correct dimensions.
+- **BM25 missing:** Run `python3 execution/memory_manager.py bm25-sync` to rebuild.
+- **Stale cache:** Cache entries older than 7 days are auto-cleared. Run `python3 execution/memory_manager.py cache-clear --older-than 7`.
 - **User opt-out:** Respect "no cache", "fresh", "skip memory" keywords.
-
-## Outputs
-
-- Cached responses (in Qdrant `semantic_cache` collection)
-- Stored memories (in Qdrant `agent_memory` collection)
-- Session health report (JSON from `session_init.py`)

package/templates/base/directives/release_process.md

@@ -0,0 +1,40 @@
+# Release Process Directive
+
+## Goal
+
+Safely release a new version of the Agi Agent Kit to NPM and the public repository, ensuring all quality gates are passed.
+
+## Inputs
+
+- `package.json` (version to be released)
+- `CHANGELOG.md` (release notes)
+- Codebase state (must be clean)
+
+## Execution Protocol (MANDATORY)
+
+1. **Pre-Flight Check**:
+   - Run `python3 .agent/scripts/release_gate.py`
+   - If it fails, STOP. Fix issues. Do not bypass.
+
+2. **Version Bump**:
+   - Update `package.json` version.
+   - Run `npm install` to update lockfile if needed.
+
+3. **Changelog Update**:
+   - Add new version header to `CHANGELOG.md`.
+   - List all features, fixes, and breaking changes.
+
+4. **Trigger Release**:
+   - Push changes: `git push origin main`
+   - Create a Release on GitHub matching `package.json` version (e.g., `v1.3.8`).
+   - This triggers the `.github/workflows/publish.yml` action.
+   - The action will run `release_gate.py` and publish to NPM automatically.
+
+5. **Verify**:
+   - Check Actions tab for success.
+   - Check NPM for new version.
+
+## Edge Cases
+
+- **Gate Failure**: If `release_gate.py` finds secrets or syntax errors, they MUST be resolved.
+- **Docs Missing**: If README is stale, update it before release.