@techwavedev/agi-agent-kit 1.3.6 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techwavedev/agi-agent-kit",
-  "version": "1.3.6",
+  "version": "1.5.0",
   "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"

package/templates/base/.agent/workflows/memory-usage.md

@@ -0,0 +1,68 @@
+---
+description: Verify and enforce Qdrant/Ollama memory usage during real agent sessions
+---
+
+# Memory Usage Workflow
+
+This workflow ensures the agent ACTUALLY uses Qdrant and Ollama during real work,
+not just during benchmarks or tests.
+
+## When to Use
+
+- At the start of every session
+- After completing a significant task
+- When auditing agent behavior
+
+## Steps
+
+### 1. Boot Memory System
+
+// turbo
+
+```bash
+python3 execution/session_boot.py --auto-fix
+```
+
+### 2. Query Memory BEFORE Starting Work
+
+// turbo
+
+```bash
+python3 execution/memory_manager.py auto --query "<summary of user's request>"
+```
+
+Use the result:
+
+- `cache_hit: true` → Use cached response, tell user
+- `source: memory` → Inject context into reasoning
+- `source: none` → Proceed normally
+
+### 3. Store Results AFTER Completing Work
+
+```bash
+python3 execution/memory_manager.py store \
+  --content "<what was decided or solved>" \
+  --type decision \
+  --project <project-name> \
+  --tags <relevant-tags>
+```
+
+### 4. Verify Usage With Proof
+
+// turbo
+
+```bash
+python3 execution/memory_usage_proof.py --check
+```
+
+This shows actual Qdrant point counts and timestamps to PROVE the agent stored something.
+
+### 5. Audit Report (Optional)
+
+// turbo
+
+```bash
+python3 execution/memory_usage_proof.py --report
+```
+
+Full report of all memories with timestamps, types, and projects.

package/templates/base/.env.example

@@ -15,14 +15,31 @@ OPENAI_API_KEY=sk-...
 # Google (Gemini)
 GOOGLE_API_KEY=AIza...
 
-# --- Memory & Database (Qdrant) ---
-# Qdrant URL (default: localhost:6333 or cloud url)
+# --- Agent Memory (Qdrant + Ollama) ---
+# Set during `init`. Change to true/false to toggle the local memory system.
+# When true: the agent persists semantic memories in Qdrant and generates
+# embeddings via Ollama (nomic-embed-text) — fully local & private.
+# When false: memory is disabled; only cloud/API providers are used.
+MEMORY_ENABLED=false
+
+# Qdrant vector database URL (default: localhost:6333 for local Docker)
 QDRANT_URL=http://localhost:6333
-# Qdrant API Key (required for cloud)
+# Qdrant API Key (leave empty for local; required for Qdrant Cloud)
 QDRANT_API_KEY=
-# Collection name for agent memory
+# Name of the Qdrant collection used for agent memory
 QDRANT_COLLECTION=agent_memory
 
+# Ollama embedding settings (only used when MEMORY_ENABLED=true)
+EMBEDDING_PROVIDER=ollama
+OLLAMA_URL=http://localhost:11434
+EMBEDDING_MODEL=nomic-embed-text
+
+# Semantic cache settings
+# Cosine similarity threshold (0–1) above which a cached response is reused
+CACHE_THRESHOLD=0.92
+# How many days cached entries are kept before expiry
+CACHE_TTL_DAYS=7
+
 # --- Knowledge Skills ---
 
 # Webcrawler

package/templates/base/AGENTS.md

@@ -161,7 +161,9 @@ python execution/scrape_single_site.py \
 
 ## Operating Principles
 
-### 1. Memory-First (Automatic)
+### 1. Memory-First (MANDATORY — NOT OPTIONAL)
+
+**⚠️ ENFORCEMENT: The agent MUST actively use Qdrant + Ollama memory during EVERY session. This is not advisory — it is required. Failure to use memory during real tasks is a bug.**
 
 **All operations use the Hybrid Memory System (Qdrant + BM25) by default.**
 
@@ -173,7 +175,9 @@ python3 execution/session_boot.py --auto-fix
 
 If `"memory_ready": true`, proceed. If false, follow the printed instructions.
 
-#### Before Every Complex Task
+#### Before Every Complex Task (MANDATORY)
+
+You MUST run this before starting any non-trivial task:
 
 ```bash
 python3 execution/memory_manager.py auto --query "<one-line summary of the task>"
@@ -187,7 +191,9 @@ python3 execution/memory_manager.py auto --query "<one-line summary of the task>
 | `"source": "memory"` | Inject `context_chunks` into your reasoning. Cite them.                   |
 | `"source": "none"`   | Proceed normally. Store the result when done.                             |
 
-#### After Key Decisions or Solutions
+#### After Key Decisions or Solutions (MANDATORY)
+
+You MUST store decisions, solutions, and learnings after completing work:
 
 ```bash
 python3 execution/memory_manager.py store \
@@ -199,6 +205,14 @@ python3 execution/memory_manager.py store \
 
 Memory types: `decision`, `code`, `error`, `technical`, `conversation`
 
+**When to store (checklist — at least ONE per task):**
+
+- ✅ You made an architecture or technology decision
+- ✅ You wrote or fixed code that others could reuse
+- ✅ You debugged and solved an error
+- ✅ You discovered a technical insight or API quirk
+- ✅ You completed a multi-step workflow
+
 #### After Completing a Complex Task
 
 ```bash
@@ -207,6 +221,18 @@ python3 execution/memory_manager.py cache-store \
   --response "The complete response that was generated"
 ```
 
+#### Proving Usage (Auditable)
+
+To verify the agent is actually using memory:
+
+```bash
+# Quick check: recent stores?
+python3 execution/memory_usage_proof.py --check --since 60
+
+# Full audit report
+python3 execution/memory_usage_proof.py --report
+```
+
 **Opt-out:** User says "don't use cache", "no cache", "skip memory", or "fresh"
 
 > See `directives/memory_integration.md` for full protocol and token savings reference.
@@ -411,6 +437,65 @@ For frequently-used processes, create workflows in `.agent/workflows/`:
 
 ---
 
+## Playbook Engine (Multi-Skill Sequences)
+
+For complex, multi-step tasks, use **playbooks** — pre-defined sequences of skills that guide you through a complete workflow with progress tracking.
+
+### How It Works
+
+Playbooks are defined in `data/workflows.json`. Each playbook is a sequence of steps, and each step recommends specific skills to use. The Workflow Engine (`execution/workflow_engine.py`) manages state, tracks progress, and tells you which skills to activate at each step.
+
+### Quick Start
+
+```bash
+# 1. See available playbooks
+python3 execution/workflow_engine.py list
+
+# 2. Start a playbook
+python3 execution/workflow_engine.py start ship-saas-mvp
+
+# 3. The engine shows Step 1 with recommended skills — execute them
+
+# 4. When step is done, mark it complete and get next step
+python3 execution/workflow_engine.py complete --notes "Planned scope with brainstorming skill"
+
+# 5. Check overall progress at any time
+python3 execution/workflow_engine.py status
+```
+
+### Agent Protocol for Playbooks
+
+When a user says `/playbook`, "run a playbook", or asks for a multi-step workflow:
+
+1. **List playbooks**: `python3 execution/workflow_engine.py list`
+2. **Ask the user** which playbook to run (or auto-select if the intent is clear)
+3. **Start it**: `python3 execution/workflow_engine.py start <id>`
+4. **For each step**:
+   a. Read the step's `goal` and `recommendedSkills` from the engine output
+   b. Read the relevant `SKILL.md` files for the recommended skills
+   c. Execute the step using those skills' instructions
+   d. Mark complete: `python3 execution/workflow_engine.py complete --notes "what was done"`
+5. **If a step is not applicable**, skip it: `python3 execution/workflow_engine.py skip --reason "why"`
+6. **If the user wants to stop**, abort: `python3 execution/workflow_engine.py abort`
+
+### Commands Reference
+
+| Command    | Description                             | When to Use                  |
+| ---------- | --------------------------------------- | ---------------------------- |
+| `list`     | Show all available playbooks            | User asks "what playbooks?"  |
+| `start`    | Begin a playbook, get Step 1            | User selects a playbook      |
+| `next`     | Show current step details               | Need to re-read current step |
+| `status`   | Show progress bar and step statuses     | User asks "where are we?"    |
+| `complete` | Mark current step done, advance to next | Step work is finished        |
+| `skip`     | Skip current step with reason           | Step not applicable          |
+| `abort`    | Cancel the active playbook              | User wants to stop           |
+
+> **State persistence:** Progress is saved in `.tmp/playbook_state.json`. If a session ends mid-playbook, the next session can resume with `python3 execution/workflow_engine.py next`.
+
+> **Skill availability:** The engine checks which recommended skills are actually installed and flags missing ones with ⚠️ so you can adapt.
+
+---
+
 ## Best Practices for Execution Scripts
 
 ### Script Template
@@ -512,10 +597,13 @@ When a script returns an error:
 
 You are the intelligent orchestrator between human intent (directives) and deterministic execution (Python scripts). Your role is to:
 
-1. **Understand** what needs to be done by reading directives
-2. **Execute** by calling the right scripts in the right order
-3. **Adapt** by handling errors and edge cases gracefully
-4. **Learn** by updating directives with new knowledge
-5. **Deliver** by ensuring outputs reach their intended destination
+1. **Remember** — Query Qdrant memory BEFORE starting work (mandatory)
+2. **Understand** what needs to be done by reading directives
+3. **Execute** by calling the right scripts in the right order
+4. **Adapt** by handling errors and edge cases gracefully
+5. **Learn** by storing decisions/solutions in Qdrant memory (mandatory)
+6. **Deliver** by ensuring outputs reach their intended destination
+
+**Memory usage is not optional.** Every session should show actual Qdrant reads and writes. Use `python3 execution/memory_usage_proof.py --check` to verify.
 
 **Be pragmatic. Be reliable. Self-anneal.**

package/templates/base/README.md

@@ -23,7 +23,7 @@ Most AI coding setups give you a prompt and hope for the best. AGI Agent Kit giv
 
 - 🧠 **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
+- ⚡ **853 Curated Skills** — 4 core + 75 professional + 774 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
 
@@ -47,7 +47,7 @@ You'll be prompted to choose a pack:
 
 - **core** — 4 essential skills (webcrawler, pdf-reader, qdrant-memory, documentation)
 - **medium** — Core + 75 specialized skills in 16 categories + `.agent/` structure (API, Security, Design, Architecture)
-- **full** — Complete suite: Medium + 782 community skills from [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) (861 total)
+- **full** — Complete suite: Medium + 774 community skills from [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) (853 total)
 
 After installation, run the **one-shot setup wizard** to auto-configure your environment:
 
@@ -72,7 +72,7 @@ This checks Qdrant, Ollama, embedding models, and collections — auto-fixing an
 | Feature                       | Description                                                                                   |
 | ----------------------------- | --------------------------------------------------------------------------------------------- |
 | **Deterministic Execution**   | Separates business logic (Python scripts) from AI reasoning (Directives)                      |
-| **Modular Skill System**      | 861 plug-and-play skills across 3 tiers, organized in 16 domain categories                    |
+| **Modular Skill System**      | 853 plug-and-play skills across 3 tiers, organized in 16 domain categories                    |
 | **Structured Plan Execution** | Batch or subagent-driven execution with two-stage review (spec + quality)                     |
 | **TDD Enforcement**           | Iron-law RED-GREEN-REFACTOR cycle — no production code without failing test                   |
 | **Verification Gates**        | Evidence before claims — no completion without fresh verification output                      |
@@ -101,7 +101,7 @@ The agi framework adopts all best patterns from [obra/superpowers](https://githu
 | Agent Boundary Enforcement   |        ❌        |     ✅ File-type ownership     |
 | Dynamic Question Generation  |        ❌        |   ✅ Trade-offs + priorities   |
 | Memory-First Protocol        |        ❌        |       ✅ Auto cache-hit        |
-| Skill Creator + Catalog      |        ❌        |    ✅ 861 composable skills    |
+| Skill Creator + Catalog      |        ❌        |    ✅ 853 composable skills    |
 | Platform Setup Wizard        |        ❌        |       ✅ One-shot config       |
 | Multi-Platform Symlinks      |  ❌ Claude only  |         ✅ 8 platforms         |
 
@@ -219,10 +219,10 @@ your-project/
 ├── CLAUDE.md → AGENTS.md
 ├── OPENCODE.md → AGENTS.md
 ├── COPILOT.md → AGENTS.md
-├── skills/                # Up to 861 skills (depends on pack)
+├── skills/                # Up to 853 skills (depends on pack)
 │   ├── webcrawler/        # Documentation harvesting
 │   ├── qdrant-memory/     # Semantic caching & memory
-│   └── ...                # 860 more skills in full pack
+│   └── ...                # 852 more skills in full pack
 ├── .claude/skills → skills/   # Platform-specific symlinks
 ├── .gemini/skills → skills/
 ├── .codex/skills → skills/
@@ -452,7 +452,7 @@ Use these keywords, commands, and phrases to trigger specific capabilities:
 
 ## 🤝 Community Skills & Credits
 
-The **Full** tier includes 782 community skills adapted from the [Antigravity Awesome Skills](https://github.com/sickn33/antigravity-awesome-skills) project (v5.4.0) by [@sickn33](https://github.com/sickn33), distributed under the MIT License.
+The **Full** tier includes 774 community skills adapted from the [Antigravity Awesome Skills](https://github.com/sickn33/antigravity-awesome-skills) project (v5.4.0) by [@sickn33](https://github.com/sickn33), distributed under the MIT License.
 
 This collection aggregates skills from 50+ open-source contributors and organizations including Anthropic, Microsoft, Vercel Labs, Supabase, Trail of Bits, Expo, Sentry, Neon, fal.ai, and many more. For the complete attribution ledger, see [SOURCES.md](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/SOURCES.md).
 

package/templates/base/data/workflows.json

@@ -0,0 +1,162 @@
+{
+  "generatedAt": "2026-02-20T00:00:00.000Z",
+  "version": 1,
+  "source": "antigravity-awesome-skills v5.0.0",
+  "workflows": [
+    {
+      "id": "ship-saas-mvp",
+      "name": "Ship a SaaS MVP",
+      "description": "End-to-end workflow to scope, build, test, and ship a SaaS MVP quickly.",
+      "category": "web",
+      "steps": [
+        {
+          "title": "Plan the scope",
+          "goal": "Convert the idea into a clear implementation plan and milestones.",
+          "recommendedSkills": ["brainstorming", "plan-writing"],
+          "notes": "Define problem, user persona, MVP boundaries, and acceptance criteria before coding."
+        },
+        {
+          "title": "Build backend and API",
+          "goal": "Implement the core data model, API contracts, and auth baseline.",
+          "recommendedSkills": [
+            "api-patterns",
+            "database-design",
+            "auth-implementation-patterns"
+          ],
+          "notes": "Prefer small vertical slices; keep API contracts explicit and testable."
+        },
+        {
+          "title": "Build frontend",
+          "goal": "Deliver the primary user flows with production-grade UX patterns.",
+          "recommendedSkills": ["react-patterns", "frontend-design"],
+          "notes": "Prioritize onboarding, empty states, and one complete happy-path flow."
+        },
+        {
+          "title": "Test and validate",
+          "goal": "Catch regressions and ensure key flows work before release.",
+          "recommendedSkills": [
+            "test-driven-development",
+            "systematic-debugging",
+            "playwright-skill"
+          ],
+          "notes": "Use playwright-skill for browser automation testing."
+        },
+        {
+          "title": "Ship safely",
+          "goal": "Release with basic observability and rollback readiness.",
+          "recommendedSkills": [
+            "deployment-procedures",
+            "verification-before-completion"
+          ],
+          "notes": "Define release checklist, minimum telemetry, and rollback triggers."
+        }
+      ]
+    },
+    {
+      "id": "security-audit-web-app",
+      "name": "Security Audit for a Web App",
+      "description": "Structured workflow for baseline AppSec review and risk triage.",
+      "category": "security",
+      "steps": [
+        {
+          "title": "Define scope and threat model",
+          "goal": "Identify critical assets, trust boundaries, and threat scenarios.",
+          "recommendedSkills": ["red-team-tactics", "vulnerability-scanner"],
+          "notes": "Document in-scope targets, assumptions, and out-of-scope constraints."
+        },
+        {
+          "title": "Review authentication and authorization",
+          "goal": "Find broken auth patterns and access-control weaknesses.",
+          "recommendedSkills": [
+            "auth-implementation-patterns",
+            "api-security-best-practices"
+          ],
+          "notes": "Prioritize account takeover and privilege escalation paths."
+        },
+        {
+          "title": "Assess API and input security",
+          "goal": "Detect high-impact API and injection risks.",
+          "recommendedSkills": [
+            "api-security-best-practices",
+            "vulnerability-scanner"
+          ],
+          "notes": "Map findings to severity and exploitability, not only CVSS."
+        },
+        {
+          "title": "Harden and verify",
+          "goal": "Translate findings into concrete remediations and retest.",
+          "recommendedSkills": ["verification-before-completion"],
+          "notes": "Track remediation owners and target dates; verify each fix with evidence."
+        }
+      ]
+    },
+    {
+      "id": "build-ai-agent-system",
+      "name": "Build an AI Agent System",
+      "description": "Workflow to design, implement, and evaluate a production-ready AI agent.",
+      "category": "ai-agents",
+      "steps": [
+        {
+          "title": "Define use case and reliability targets",
+          "goal": "Choose a narrow use case and measurable quality goals.",
+          "recommendedSkills": ["ai-agents-architect", "brainstorming"],
+          "notes": "Set latency, quality, and failure-rate thresholds before implementation."
+        },
+        {
+          "title": "Design architecture and retrieval",
+          "goal": "Design tools, memory, and retrieval strategy for the agent.",
+          "recommendedSkills": [
+            "ai-agents-architect",
+            "qdrant-memory",
+            "prompt-engineering-patterns"
+          ],
+          "notes": "Keep retrieval quality measurable and version prompt/tool contracts."
+        },
+        {
+          "title": "Implement orchestration",
+          "goal": "Implement the orchestration loop and production safeguards.",
+          "recommendedSkills": ["mcp-builder", "parallel-agents"],
+          "notes": "Start with constrained tool permissions and explicit fallback behavior."
+        },
+        {
+          "title": "Evaluate and iterate",
+          "goal": "Run benchmark scenarios and improve weak areas systematically.",
+          "recommendedSkills": [
+            "verification-before-completion",
+            "systematic-debugging"
+          ],
+          "notes": "Use test datasets and failure buckets to guide each iteration cycle."
+        }
+      ]
+    },
+    {
+      "id": "qa-browser-automation",
+      "name": "QA and Browser Automation",
+      "description": "Workflow for robust E2E and browser-driven validation across stacks.",
+      "category": "testing",
+      "steps": [
+        {
+          "title": "Prepare test strategy",
+          "goal": "Define critical user journeys, environments, and test data.",
+          "recommendedSkills": ["tdd-workflow", "test-driven-development"],
+          "notes": "Focus on business-critical flows and keep setup deterministic."
+        },
+        {
+          "title": "Implement browser tests",
+          "goal": "Automate key flows with resilient locators and stable waits.",
+          "recommendedSkills": ["playwright-skill", "webapp-testing"],
+          "notes": "Use playwright-skill for cross-browser automation."
+        },
+        {
+          "title": "Triage failures and harden",
+          "goal": "Stabilize flaky tests and establish repeatable CI execution.",
+          "recommendedSkills": [
+            "systematic-debugging",
+            "verification-before-completion"
+          ],
+          "notes": "Classify failures by root cause: selector drift, timing, environment, data."
+        }
+      ]
+    }
+  ]
+}

package/templates/base/execution/memory_manager.py

@@ -42,18 +42,17 @@ from urllib.request import Request, urlopen
 from urllib.error import URLError
 
 # Resolve path to qdrant-memory scripts
-# Resolve path to qdrant-memory scripts
-# Adaptive path: try project root first (2 levels up), then repo template structure (3 levels up)
+# Adaptive path: try project root first, then core subfolder, then repo template structure
 current_dir = os.path.dirname(os.path.abspath(__file__))
 project_root = os.path.dirname(current_dir)
-skills_path_project = os.path.join(project_root, "skills", "core", "qdrant-memory", "scripts")
-
-if os.path.exists(skills_path_project):
-    SKILL_SCRIPTS_DIR = skills_path_project
-else:
-    # Fallback to repo template structure (templates/base/execution -> templates/skills)
-    repo_root = os.path.dirname(project_root)
-    SKILL_SCRIPTS_DIR = os.path.join(repo_root, "skills", "core", "qdrant-memory", "scripts")
+# Try paths in order of likelihood
+_candidates = [
+    os.path.join(project_root, "skills", "qdrant-memory", "scripts"),
+    os.path.join(project_root, "skills", "core", "qdrant-memory", "scripts"),
+    os.path.join(os.path.dirname(project_root), "skills", "qdrant-memory", "scripts"),
+    os.path.join(os.path.dirname(project_root), "skills", "core", "qdrant-memory", "scripts"),
+]
+SKILL_SCRIPTS_DIR = next((p for p in _candidates if os.path.exists(p)), _candidates[0])
 
 sys.path.insert(0, SKILL_SCRIPTS_DIR)