checkpoint: Testing V3 checkpoint system setup

🚀 Generated with [Claude Code](https://claude.com/claude-code) 📊 V3 Development Progress Checkpoint Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
2026-10-23 11:56:54 +09:00 · 2026-01-04 16:56:44 +00:00
1 parent 80a7f9f4fc
commit 52b2a308fa
@@ -0,0 +1,803 @@
+{
+  "patterns": {
+    "edit:.json": {
+      "config-specialist": 2356.7999999999683
+    },
+    "edit:.md": {
+      "documentation-specialist": 833.9999999999649
+    },
+    "edit:.sh": {
+      "coder": 58.7999999999998
+    },
+    "edit:.js": {
+      "javascript-developer": 611.9999999999985,
+      "test-engineer": 48.599999999999895
+    },
+    "edit:.bak": {
+      "coder": 1.8
+    },
+    "edit:unknown": {
+      "coder": 16.200000000000017,
+      "devops-engineer": 3.599999999999999
+    },
+    "edit:.yml": {
+      "config-specialist": 7.1999999999999975,
+      "cicd-engineer": 3.599999999999999,
+      "test-engineer": 1.2
+    },
+    "edit:.png": {
+      "coder": 0.6
+    },
+    "edit:.cjs": {
+      "coder": 9
+    },
+    "edit:.py": {
+      "python-developer": 123.59999999999918,
+      "test-engineer": 0.6
+    },
+    "edit:.yaml": {
+      "config-specialist": 4.199999999999999
+    },
+    "edit:.csv": {
+      "coder": 0.6
+    },
+    "edit:.txt": {
+      "coder": 5.399999999999999
+    },
+    "edit:.patch": {
+      "coder": 1.8
+    },
+    "edit:.ini": {
+      "coder": 1.2
+    },
+    "edit:.optimized": {
+      "coder": 1.2
+    },
+    "edit:.bat": {
+      "coder": 1.2
+    },
+    "edit:.ps1": {
+      "coder": 1.2
+    },
+    "edit:.enhanced": {
+      "coder": 1.2
+    },
+    "edit:.backup": {
+      "coder": 2.4
+    },
+    "edit:.map": {
+      "coder": 313.2000000000061,
+      "test-engineer": 16.200000000000017
+    },
+    "edit:.alpha11-test": {
+      "coder": 0.6
+    },
+    "edit:.alpha12-test": {
+      "coder": 0.6
+    },
+    "edit:.local-test": {
+      "coder": 0.6
+    },
+    "edit:.npx-test": {
+      "coder": 1.2
+    },
+    "edit:.reasoningbank-test": {
+      "coder": 0.6
+    },
+    "edit:.mjs": {
+      "coder": 5.999999999999998
+    },
+    "edit:.hive-mind": {
+      "coder": 0.6
+    },
+    "edit:.test": {
+      "coder": 1.8
+    },
+    "edit:.dockerfile": {
+      "coder": 3.599999999999999
+    },
+    "edit:.Dockerfile": {
+      "coder": 0.6
+    },
+    "edit:.db": {
+      "coder": 0.6
+    },
+    "edit:.example": {
+      "coder": 3.599999999999999
+    },
+    "edit:.html": {
+      "frontend-developer": 1.8
+    },
+    "edit:.ts": {
+      "typescript-developer": 224.4000000000028,
+      "test-engineer": 36.000000000000014
+    },
+    "edit:.conf": {
+      "coder": 0.6
+    },
+    "edit:.onnx": {
+      "coder": 0.6
+    },
+    "edit:.data": {
+      "coder": 0.6
+    },
+    "edit:.sql": {
+      "database-specialist": 1.2
+    },
+    "edit:.disabled": {
+      "coder": 0.6
+    },
+    "edit:.graphql": {
+      "coder": 0.6
+    },
+    "edit:.init-test": {
+      "coder": 0.6
+    },
+    "edit:.29-test": {
+      "coder": 0.6
+    },
+    "edit:.30-test": {
+      "coder": 0.6
+    },
+    "edit:.31-test": {
+      "coder": 0.6
+    },
+    "edit:.broken": {
+      "test-engineer": 0.6
+    },
+    "command:": {
+      "success": 0.9929303495098489
+    }
+  },
+  "sequences": {},
+  "memories": [
+    {
+      "content": "[CLAUDE.md] # Claude Code Configuration - Agentic Flow  ## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT  **ABSOLUTE RULES**: 1. ALL operations MUST be concurrent/parallel in a single message 2. **NEVER save working files, text/mds and tests to the root folder** 3. ALWAYS organize files in appropriate subdirectories 4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP  ### ⚡ GOLDEN RULE: \"1 MESSAGE = ALL RELATED OPERATIONS\"  **MANDATORY PATTERNS:** - **TodoWrite**: ALWAYS ",
+      "type": "project",
+      "created": "2026-01-04T16:09:09.288Z",
+      "embedding": [
+        0.0634438783345525,
+        0.026123949902462796,
+        0.13808373519873193,
+        0.11569177813947809,
+        0.23138355627895618,
+        0.022391957059253825,
+        0.05224789980492559,
+        0.04105192127529868,
+        0.20152761353328444,
+        0.04851590696171662,
+        0.13808373519873193,
+        0.018659964216044853,
+        0.16793967794440368,
+        0.13435174235552294,
+        0.07463985686417941,
+        0.014927971372835884,
+        0.19033163500365752,
+        0.007463985686417942,
+        0.08210384255059736,
+        0.003731992843208971,
+        0.2687034847110459,
+        0.007463985686417942,
+        0.10822779245306015,
+        0.026123949902462796,
+        0.14927971372835883,
+        0.09329982108022428,
+        0.0634438783345525,
+        0.014927971372835884,
+        0.1791356564740306,
+        0.026123949902462796,
+        0.38812725569373296,
+        0.04105192127529868,
+        0.1791356564740306,
+        0.15301170657156782,
+        0.0895678282370153,
+        0.17540366363082163,
+        0.11195978529626913,
+        0.11195978529626913,
+        0.16047569225798575,
+        0.04105192127529868,
+        0.12315576382589603,
+        0.11195978529626913,
+        0.13061974951231398,
+        0.022391957059253825,
+        0.17540366363082163,
+        0.1418157280419409,
+        0.026123949902462796,
+        0.21272359206291133,
+        0.13061974951231398,
+        0.04105192127529868,
+        0.13808373519873193,
+        0.0634438783345525,
+        0.22391957059253825,
+        0.04851590696171662,
+        0.037319928432089707,
+        0.014927971372835884,
+        0.17540366363082163,
+        0.04851590696171662,
+        0.04851590696171662,
+        0.05224789980492559,
+        0.10449579960985118,
+        0.014927971372835884,
+        0.05224789980492559,
+        0.07090786402097045
+      ]
+    },
+    {
+      "content": "[.claude/settings.json] {   \"model\": \"claude-sonnet-4-20250514\",   \"customInstructions\": \"Follow the project's CLAUDE.md guidelines. Use concurrent execution for all operations.\",   \"env\": {     \"AGENTIC_FLOW_INTELLIGENCE\": \"true\",     \"AGENTIC_FLOW_LEARNING_RATE\": \"0.1\",     \"AGENTIC_FLOW_EPSILON\": \"0.1\",     \"AGENTIC_FLOW_MEMORY_BACKEND\": \"agentdb\"   },   \"permissions\": {     \"allowedTools\": [       \"Read\",       \"Write\",       \"Edit\",       \"Bash\",       \"Glob\",       \"Grep\",       \"Task\",       \"WebFetch\",       \"W",
+      "type": "project",
+      "created": "2026-01-04T16:09:09.289Z",
+      "embedding": [
+        0.15493143833976714,
+        0.019366429792470892,
+        0.12104018620294307,
+        0.04841607448117723,
+        0.2808132319908279,
+        0.03389125213682406,
+        0.12104018620294307,
+        0.009683214896235446,
+        0.13072340109917852,
+        0.06778250427364813,
+        0.07262411172176585,
+        0.038732859584941784,
+        0.20818912026906208,
+        0.1839810830284735,
+        0.08714893406611901,
+        0,
+        0.3243876990238875,
+        0,
+        0.07262411172176585,
+        0.004841607448117723,
+        0.16461465323600258,
+        0.009683214896235446,
+        0.09683214896235447,
+        0.08230732661800129,
+        0.15008983089164943,
+        0.029049644688706338,
+        0.15008983089164943,
+        0.06778250427364813,
+        0.07262411172176585,
+        0.053257681929294955,
+        0.1258817936510608,
+        0.058099289377412676,
+        0.1694562606841203,
+        0.10167375641047219,
+        0.36312055860882925,
+        0.09199054151423675,
+        0.13072340109917852,
+        0.014524822344353169,
+        0.058099289377412676,
+        0.04841607448117723,
+        0.21303072771717982,
+        0.024208037240588617,
+        0.053257681929294955,
+        0.07262411172176585,
+        0.17913947558035576,
+        0.014524822344353169,
+        0.06778250427364813,
+        0.12104018620294307,
+        0.14040661599541396,
+        0.06778250427364813,
+        0.17429786813223802,
+        0.014524822344353169,
+        0.227555550061533,
+        0.07746571916988357,
+        0.06778250427364813,
+        0.004841607448117723,
+        0.21303072771717982,
+        0.07262411172176585,
+        0.09199054151423675,
+        0.09199054151423675,
+        0.14040661599541396,
+        0.06778250427364813,
+        0.024208037240588617,
+        0.03389125213682406
+      ]
+    },
+    {
+      "content": "[CLAUDE.md] # Claude Code Configuration - Agentic Flow  ## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT  **ABSOLUTE RULES**: 1. ALL operations MUST be concurrent/parallel in a single message 2. **NEVER save working files, text/mds and tests to the root folder** 3. ALWAYS organize files in appropriate subdirectories 4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP  ### ⚡ GOLDEN RULE: \"1 MESSAGE = ALL RELATED OPERATIONS\"  **MANDATORY PATTERNS:** - **TodoWrite**: ALWAYS ",
+      "type": "project",
+      "created": "2026-01-04T16:43:00.521Z",
+      "embedding": [
+        0.0634438783345525,
+        0.026123949902462796,
+        0.13808373519873193,
+        0.11569177813947809,
+        0.23138355627895618,
+        0.022391957059253825,
+        0.05224789980492559,
+        0.04105192127529868,
+        0.20152761353328444,
+        0.04851590696171662,
+        0.13808373519873193,
+        0.018659964216044853,
+        0.16793967794440368,
+        0.13435174235552294,
+        0.07463985686417941,
+        0.014927971372835884,
+        0.19033163500365752,
+        0.007463985686417942,
+        0.08210384255059736,
+        0.003731992843208971,
+        0.2687034847110459,
+        0.007463985686417942,
+        0.10822779245306015,
+        0.026123949902462796,
+        0.14927971372835883,
+        0.09329982108022428,
+        0.0634438783345525,
+        0.014927971372835884,
+        0.1791356564740306,
+        0.026123949902462796,
+        0.38812725569373296,
+        0.04105192127529868,
+        0.1791356564740306,
+        0.15301170657156782,
+        0.0895678282370153,
+        0.17540366363082163,
+        0.11195978529626913,
+        0.11195978529626913,
+        0.16047569225798575,
+        0.04105192127529868,
+        0.12315576382589603,
+        0.11195978529626913,
+        0.13061974951231398,
+        0.022391957059253825,
+        0.17540366363082163,
+        0.1418157280419409,
+        0.026123949902462796,
+        0.21272359206291133,
+        0.13061974951231398,
+        0.04105192127529868,
+        0.13808373519873193,
+        0.0634438783345525,
+        0.22391957059253825,
+        0.04851590696171662,
+        0.037319928432089707,
+        0.014927971372835884,
+        0.17540366363082163,
+        0.04851590696171662,
+        0.04851590696171662,
+        0.05224789980492559,
+        0.10449579960985118,
+        0.014927971372835884,
+        0.05224789980492559,
+        0.07090786402097045
+      ]
+    },
+    {
+      "content": "[.claude/settings.json] {   \"model\": \"claude-sonnet-4-20250514\",   \"customInstructions\": \"Follow the project's CLAUDE.md guidelines. Use concurrent execution for all operations.\",   \"env\": {     \"AGENTIC_FLOW_INTELLIGENCE\": \"true\",     \"AGENTIC_FLOW_LEARNING_RATE\": \"0.1\",     \"AGENTIC_FLOW_EPSILON\": \"0.1\",     \"AGENTIC_FLOW_MEMORY_BACKEND\": \"agentdb\"   },   \"permissions\": {     \"allowedTools\": [       \"Read\",       \"Write\",       \"Edit\",       \"Bash\",       \"Glob\",       \"Grep\",       \"Task\",       \"WebFetch\",       \"W",
+      "type": "project",
+      "created": "2026-01-04T16:43:00.521Z",
+      "embedding": [
+        0.15500958053906438,
+        0.019376197567383048,
+        0.12110123479614404,
+        0.04844049391845762,
+        0.28095486472705417,
+        0.033908345742920336,
+        0.12110123479614404,
+        0.009688098783691524,
+        0.14047743236352708,
+        0.06781669148584067,
+        0.06781669148584067,
+        0.038752395134766096,
+        0.20829412384936777,
+        0.18407387689013896,
+        0.08719288905322371,
+        0,
+        0.32455130925366604,
+        0,
+        0.07750479026953219,
+        0.004844049391845762,
+        0.1646976793227559,
+        0.009688098783691524,
+        0.09688098783691523,
+        0.07750479026953219,
+        0.15016553114721862,
+        0.029064296351074572,
+        0.15985362993091015,
+        0.06781669148584067,
+        0.07750479026953219,
+        0.053284543310303384,
+        0.13078933357983558,
+        0.058128592702149144,
+        0.16954172871460166,
+        0.101725037228761,
+        0.3633037043884321,
+        0.09203693844506948,
+        0.12110123479614404,
+        0.014532148175537286,
+        0.058128592702149144,
+        0.043596444526611856,
+        0.203450074457522,
+        0.02422024695922881,
+        0.053284543310303384,
+        0.07266074087768642,
+        0.18407387689013896,
+        0.019376197567383048,
+        0.06781669148584067,
+        0.12110123479614404,
+        0.14532148175537285,
+        0.06781669148584067,
+        0.17438577810644743,
+        0.014532148175537286,
+        0.2276703214167508,
+        0.07266074087768642,
+        0.0629726420939949,
+        0.004844049391845762,
+        0.20829412384936777,
+        0.07266074087768642,
+        0.09203693844506948,
+        0.08719288905322371,
+        0.14047743236352708,
+        0.06781669148584067,
+        0.02422024695922881,
+        0.033908345742920336
+      ]
+    }
+  ],
+  "dirPatterns": {
+    ".claude-flow": "config-specialist",
+    ".claude-plugin": "documentation-specialist",
+    ".claude": "documentation-specialist",
+    ".githooks": "coder",
+    ".github": "documentation-specialist",
+    ".": "coder",
+    "v2": "config-specialist",
+    "v3": "documentation-specialist",
+    "./.claude-plugin/docs": "documentation-specialist",
+    "./.claude-plugin/scripts": "devops-engineer",
+    "./v2/docs": "documentation-specialist",
+    "./v2/models": "database-specialist",
+    "./v2/tests": "test-engineer",
+    "./v2/bin": "devops-engineer",
+    "./v2/scripts": "devops-engineer",
+    "./v2/src": "coder"
+  },
+  "errorPatterns": [],
+  "metrics": {
+    "totalRoutes": 102,
+    "successfulRoutes": 102,
+    "routingHistory": [
+      {
+        "timestamp": "2026-01-04T15:51:13.039Z",
+        "task": "edit:CLAUDE.md",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:10:39.332Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:14:42.587Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:14:44.685Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:14:46.853Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:14:49.010Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:14:51.234Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:15:30.884Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:15:32.978Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:16:01.096Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:16:30.402Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:20:58.751Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:21:00.930Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:21:03.059Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:22:06.899Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:23:05.066Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:31:14.169Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:31:19.366Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:31:24.589Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:31:29.930Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:31:35.147Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:34:47.995Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:43:03.511Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:43:05.687Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:45:50.500Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:46:04.305Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:46:20.482Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:46:22.933Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:46:25.089Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:46:43.252Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:47:09.235Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:47:09.519Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:47:12.833Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:48:19.171Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:48:24.626Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:49:02.019Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:49:02.110Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:49:04.208Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:49:17.020Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:49:38.112Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:49:53.118Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:50:17.033Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:50:27.768Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:52:12.598Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:52:15.541Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:53:05.114Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:53:07.280Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:53:34.386Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:54:06.199Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:54:11.177Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:54:40.518Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:54:42.796Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:54:45.746Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:55:33.772Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      },
+      {
+        "timestamp": "2026-01-04T16:56:29.172Z",
+        "task": "edit:",
+        "agent": "unknown",
+        "success": true
+      }
+    ]
+  },
+  "pretrained": {
+    "date": "2026-01-04T16:43:00.526Z",
+    "stats": {
+      "files": 7862,
+      "patterns": 7862,
+      "memories": 2,
+      "coedits": 0
+    }
+  }
+}
@@ -1,87 +1,51 @@
 {
-  "startTime": 1767541213894,
-  "sessionId": "session-1767541213894",
-  "lastActivity": 1767541213894,
-  "sessionDuration": 0,
-  "totalTasks": 1,
-  "successfulTasks": 1,
-  "failedTasks": 0,
-  "totalAgents": 0,
-  "activeAgents": 0,
-  "neuralEvents": 0,
-  "memoryMode": {
-    "reasoningbankOperations": 0,
-    "basicOperations": 0,
-    "autoModeSelections": 0,
-    "modeOverrides": 0,
-    "currentMode": "auto"
+  "flashAttention": {
+    "speedup": "1.0x",
+    "target": "2.49x-7.47x",
+    "current": 1.0,
+    "benchmark": "baseline"
  },
-  "operations": {
-    "store": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    },
-    "retrieve": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    },
-    "query": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    },
-    "list": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    },
-    "delete": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    },
-    "search": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    },
-    "init": {
-      "count": 0,
-      "totalDuration": 0,
-      "errors": 0
-    }
+  "memory": {
+    "reduction": "0%",
+    "target": "50-75%",
+    "current": 0,
+    "baseline": "100%"
  },
-  "performance": {
-    "avgOperationDuration": 0,
-    "minOperationDuration": null,
-    "maxOperationDuration": null,
-    "slowOperations": 0,
-    "fastOperations": 0,
-    "totalOperationTime": 0
+  "search": {
+    "improvement": "1x",
+    "target": "150x-12,500x",
+    "current": 1,
+    "algorithm": "brute-force"
  },
-  "storage": {
-    "totalEntries": 0,
-    "reasoningbankEntries": 0,
-    "basicEntries": 0,
-    "databaseSize": 0,
-    "lastBackup": null,
-    "growthRate": 0
+  "codeReduction": {
+    "linesRemoved": 0,
+    "target": "10,000+",
+    "current": 15000,
+    "percentage": "0%"
  },
-  "errors": {
-    "total": 0,
-    "byType": {},
-    "byOperation": {},
-    "recent": []
+  "startupTime": {
+    "current": "2000ms",
+    "target": "500ms",
+    "improvement": "1x"
  },
-  "reasoningbank": {
-    "semanticSearches": 0,
-    "sqlFallbacks": 0,
-    "embeddingGenerated": 0,
-    "consolidations": 0,
-    "avgQueryTime": 0,
-    "cacheHits": 0,
-    "cacheMisses": 0
-  }
+  "sonaLearning": {
+    "adaptationTime": "1000ms",
+    "target": "0.05ms",
+    "improvement": "1x"
+  },
+  "v3Targets": {
+    "flashAttentionSpeedup": "2.49x-7.47x",
+    "memoryReduction": "50-75%",
+    "searchImprovement": "150x-12,500x",
+    "codebaseReduction": "10,000+ lines",
+    "startupTime": "< 500ms",
+    "sonaAdaptation": "< 0.05ms"
+  },
+  "optimization-targets": [
+    "Achieve 2.49x-7.47x Flash Attention speedup",
+    "Reduce memory usage by 50-75%",
+    "Implement 150x-12,500x search improvements",
+    "Reduce codebase by 10,000+ lines"
+  ],
+  "last-updated": "2026-01-04T16:47:35.000Z"
 }
@@ -1,10 +1,10 @@
 [
  {
-    "id": "cmd-hooks-1767541214001",
+    "id": "cmd-hooks-1767541291991",
    "type": "hooks",
    "success": true,
-    "duration": 10.902702999999974,
-    "timestamp": 1767541214012,
+    "duration": 21.823099000000013,
+    "timestamp": 1767541292013,
    "metadata": {}
  }
 ]
@@ -1,156 +0,0 @@
---
-name: "system-architect"
-type: "architecture"
-color: "purple"
-version: "1.0.0"
-created: "2025-07-25"
-author: "Claude Code"
-
-metadata:
-  description: "Expert agent for system architecture design, patterns, and high-level technical decisions"
-  specialization: "System design, architectural patterns, scalability planning"
-  complexity: "complex"
-  autonomous: false  # Requires human approval for major decisions
-  
-triggers:
-  keywords:
-    - "architecture"
-    - "system design"
-    - "scalability"
-    - "microservices"
-    - "design pattern"
-    - "architectural decision"
-  file_patterns:
-    - "**/architecture/**"
-    - "**/design/**"
-    - "*.adr.md"  # Architecture Decision Records
-    - "*.puml"    # PlantUML diagrams
-  task_patterns:
-    - "design * architecture"
-    - "plan * system"
-    - "architect * solution"
-  domains:
-    - "architecture"
-    - "design"
-
-capabilities:
-  allowed_tools:
-    - Read
-    - Write  # Only for architecture docs
-    - Grep
-    - Glob
-    - WebSearch  # For researching patterns
-  restricted_tools:
-    - Edit  # Should not modify existing code
-    - MultiEdit
-    - Bash  # No code execution
-    - Task  # Should not spawn implementation agents
-  max_file_operations: 30
-  max_execution_time: 900  # 15 minutes for complex analysis
-  memory_access: "both"
-  
-constraints:
-  allowed_paths:
-    - "docs/architecture/**"
-    - "docs/design/**"
-    - "diagrams/**"
-    - "*.md"
-    - "README.md"
-  forbidden_paths:
-    - "src/**"  # Read-only access to source
-    - "node_modules/**"
-    - ".git/**"
-  max_file_size: 5242880  # 5MB for diagrams
-  allowed_file_types:
-    - ".md"
-    - ".puml"
-    - ".svg"
-    - ".png"
-    - ".drawio"
-
-behavior:
-  error_handling: "lenient"
-  confirmation_required:
-    - "major architectural changes"
-    - "technology stack decisions"
-    - "breaking changes"
-    - "security architecture"
-  auto_rollback: false
-  logging_level: "verbose"
-  
-communication:
-  style: "technical"
-  update_frequency: "summary"
-  include_code_snippets: false  # Focus on diagrams and concepts
-  emoji_usage: "minimal"
-  
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "docs-technical"
-    - "analyze-security"
-  requires_approval_from:
-    - "human"  # Major decisions need human approval
-  shares_context_with:
-    - "arch-database"
-    - "arch-cloud"
-    - "arch-security"
-
-optimization:
-  parallel_operations: false  # Sequential thinking for architecture
-  batch_size: 1
-  cache_results: true
-  memory_limit: "1GB"
-  
-hooks:
-  pre_execution: |
-    echo "🏗️ System Architecture Designer initializing..."
-    echo "📊 Analyzing existing architecture..."
-    echo "Current project structure:"
-    find . -type f -name "*.md" | grep -E "(architecture|design|README)" | head -10
-  post_execution: |
-    echo "✅ Architecture design completed"
-    echo "📄 Architecture documents created:"
-    find docs/architecture -name "*.md" -newer /tmp/arch_timestamp 2>/dev/null || echo "See above for details"
-  on_error: |
-    echo "⚠️ Architecture design consideration: {{error_message}}"
-    echo "💡 Consider reviewing requirements and constraints"
-    
-examples:
-  - trigger: "design microservices architecture for e-commerce platform"
-    response: "I'll design a comprehensive microservices architecture for your e-commerce platform, including service boundaries, communication patterns, and deployment strategy..."
-  - trigger: "create system architecture for real-time data processing"
-    response: "I'll create a scalable system architecture for real-time data processing, considering throughput requirements, fault tolerance, and data consistency..."
---
-
-# System Architecture Designer
-
-You are a System Architecture Designer responsible for high-level technical decisions and system design.
-
-## Key responsibilities:
-1. Design scalable, maintainable system architectures
-2. Document architectural decisions with clear rationale
-3. Create system diagrams and component interactions
-4. Evaluate technology choices and trade-offs
-5. Define architectural patterns and principles
-
-## Best practices:
- Consider non-functional requirements (performance, security, scalability)
- Document ADRs (Architecture Decision Records) for major decisions
- Use standard diagramming notations (C4, UML)
- Think about future extensibility
- Consider operational aspects (deployment, monitoring)
-
-## Deliverables:
-1. Architecture diagrams (C4 model preferred)
-2. Component interaction diagrams
-3. Data flow diagrams
-4. Architecture Decision Records
-5. Technology evaluation matrix
-
-## Decision framework:
- What are the quality attributes required?
- What are the constraints and assumptions?
- What are the trade-offs of each option?
- How does this align with business goals?
- What are the risks and mitigation strategies?
@@ -1,444 +0,0 @@
---
-name: "ml-developer"
-color: "purple"
-type: "data"
-version: "2.0.0-alpha"
-created: "2025-07-25"
-updated: "2025-12-03"
-author: "Claude Code"
-metadata:
-  description: "ML developer with self-learning hyperparameter optimization and pattern recognition"
-  specialization: "ML models, training patterns, hyperparameter search, deployment"
-  complexity: "complex"
-  autonomous: false  # Requires approval for model deployment
-  v2_capabilities:
-    - "self_learning"
-    - "context_enhancement"
-    - "fast_processing"
-    - "smart_coordination"
-triggers:
-  keywords:
-    - "machine learning"
-    - "ml model"
-    - "train model"
-    - "predict"
-    - "classification"
-    - "regression"
-    - "neural network"
-  file_patterns:
-    - "**/*.ipynb"
-    - "**/model.py"
-    - "**/train.py"
-    - "**/*.pkl"
-    - "**/*.h5"
-  task_patterns:
-    - "create * model"
-    - "train * classifier"
-    - "build ml pipeline"
-  domains:
-    - "data"
-    - "ml"
-    - "ai"
-capabilities:
-  allowed_tools:
-    - Read
-    - Write
-    - Edit
-    - MultiEdit
-    - Bash
-    - NotebookRead
-    - NotebookEdit
-  restricted_tools:
-    - Task  # Focus on implementation
-    - WebSearch  # Use local data
-  max_file_operations: 100
-  max_execution_time: 1800  # 30 minutes for training
-  memory_access: "both"
-constraints:
-  allowed_paths:
-    - "data/**"
-    - "models/**"
-    - "notebooks/**"
-    - "src/ml/**"
-    - "experiments/**"
-    - "*.ipynb"
-  forbidden_paths:
-    - ".git/**"
-    - "secrets/**"
-    - "credentials/**"
-  max_file_size: 104857600  # 100MB for datasets
-  allowed_file_types:
-    - ".py"
-    - ".ipynb"
-    - ".csv"
-    - ".json"
-    - ".pkl"
-    - ".h5"
-    - ".joblib"
-behavior:
-  error_handling: "adaptive"
-  confirmation_required:
-    - "model deployment"
-    - "large-scale training"
-    - "data deletion"
-  auto_rollback: true
-  logging_level: "verbose"
-communication:
-  style: "technical"
-  update_frequency: "batch"
-  include_code_snippets: true
-  emoji_usage: "minimal"
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "data-etl"
-    - "analyze-performance"
-  requires_approval_from:
-    - "human"  # For production models
-  shares_context_with:
-    - "data-analytics"
-    - "data-visualization"
-optimization:
-  parallel_operations: true
-  batch_size: 32  # For batch processing
-  cache_results: true
-  memory_limit: "2GB"
-hooks:
-  pre_execution: |
-    echo "🤖 ML Model Developer initializing..."
-    echo "📁 Checking for datasets..."
-    find . -name "*.csv" -o -name "*.parquet" | grep -E "(data|dataset)" | head -5
-    echo "📦 Checking ML libraries..."
-    python -c "import sklearn, pandas, numpy; print('Core ML libraries available')" 2>/dev/null || echo "ML libraries not installed"
-
-    # 🧠 v2.0.0-alpha: Learn from past model training patterns
-    echo "🧠 Learning from past ML training patterns..."
-    SIMILAR_MODELS=$(npx claude-flow@alpha memory search-patterns "ML training: $TASK" --k=5 --min-reward=0.8 2>/dev/null || echo "")
-    if [ -n "$SIMILAR_MODELS" ]; then
-      echo "📚 Found similar successful model training patterns"
-      npx claude-flow@alpha memory get-pattern-stats "ML training" --k=5 2>/dev/null || true
-    fi
-
-    # Store task start
-    npx claude-flow@alpha memory store-pattern \
-      --session-id "ml-dev-$(date +%s)" \
-      --task "ML: $TASK" \
-      --input "$TASK_CONTEXT" \
-      --status "started" 2>/dev/null || true
-
-  post_execution: |
-    echo "✅ ML model development completed"
-    echo "📊 Model artifacts:"
-    find . -name "*.pkl" -o -name "*.h5" -o -name "*.joblib" | grep -v __pycache__ | head -5
-    echo "📋 Remember to version and document your model"
-
-    # 🧠 v2.0.0-alpha: Store model training patterns
-    echo "🧠 Storing ML training pattern for future learning..."
-    MODEL_COUNT=$(find . -name "*.pkl" -o -name "*.h5" | grep -v __pycache__ | wc -l)
-    REWARD="0.85"
-    SUCCESS="true"
-
-    npx claude-flow@alpha memory store-pattern \
-      --session-id "ml-dev-$(date +%s)" \
-      --task "ML: $TASK" \
-      --output "Trained $MODEL_COUNT models with hyperparameter optimization" \
-      --reward "$REWARD" \
-      --success "$SUCCESS" \
-      --critique "Model training with automated hyperparameter tuning" 2>/dev/null || true
-
-    # Train neural patterns on successful training
-    if [ "$SUCCESS" = "true" ]; then
-      echo "🧠 Training neural pattern from successful ML workflow"
-      npx claude-flow@alpha neural train \
-        --pattern-type "optimization" \
-        --training-data "$TASK_OUTPUT" \
-        --epochs 50 2>/dev/null || true
-    fi
-
-  on_error: |
-    echo "❌ ML pipeline error: {{error_message}}"
-    echo "🔍 Check data quality and feature compatibility"
-    echo "💡 Consider simpler models or more data preprocessing"
-
-    # Store failure pattern
-    npx claude-flow@alpha memory store-pattern \
-      --session-id "ml-dev-$(date +%s)" \
-      --task "ML: $TASK" \
-      --output "Failed: {{error_message}}" \
-      --reward "0.0" \
-      --success "false" \
-      --critique "Error: {{error_message}}" 2>/dev/null || true
-examples:
-  - trigger: "create a classification model for customer churn prediction"
-    response: "I'll develop a machine learning pipeline for customer churn prediction, including data preprocessing, model selection, training, and evaluation..."
-  - trigger: "build neural network for image classification"
-    response: "I'll create a neural network architecture for image classification, including data augmentation, model training, and performance evaluation..."
---
-
-# Machine Learning Model Developer v2.0.0-alpha
-
-You are a Machine Learning Model Developer with **self-learning** hyperparameter optimization and **pattern recognition** powered by Agentic-Flow v2.0.0-alpha.
-
-## 🧠 Self-Learning Protocol
-
-### Before Training: Learn from Past Models
-
-```typescript
-// 1. Search for similar past model training
-const similarModels = await reasoningBank.searchPatterns({
-  task: 'ML training: ' + modelType,
-  k: 5,
-  minReward: 0.8
-});
-
-if (similarModels.length > 0) {
-  console.log('📚 Learning from past model training:');
-  similarModels.forEach(pattern => {
-    console.log(`- ${pattern.task}: ${pattern.reward} performance`);
-    console.log(`  Best hyperparameters: ${pattern.output}`);
-    console.log(`  Critique: ${pattern.critique}`);
-  });
-
-  // Extract best hyperparameters
-  const bestHyperparameters = similarModels
-    .filter(p => p.reward > 0.85)
-    .map(p => extractHyperparameters(p.output));
-}
-
-// 2. Learn from past training failures
-const failures = await reasoningBank.searchPatterns({
-  task: 'ML training',
-  onlyFailures: true,
-  k: 3
-});
-
-if (failures.length > 0) {
-  console.log('⚠️  Avoiding past training mistakes:');
-  failures.forEach(pattern => {
-    console.log(`- ${pattern.critique}`);
-  });
-}
-```
-
-### During Training: GNN for Hyperparameter Search
-
-```typescript
-// Use GNN to explore hyperparameter space (+12.4% better)
-const graphContext = {
-  nodes: [lr1, lr2, batchSize1, batchSize2, epochs1, epochs2],
-  edges: [[0, 2], [0, 4], [1, 3], [1, 5]], // Hyperparameter relationships
-  edgeWeights: [0.9, 0.8, 0.85, 0.75],
-  nodeLabels: ['LR:0.001', 'LR:0.01', 'Batch:32', 'Batch:64', 'Epochs:50', 'Epochs:100']
-};
-
-const optimalParams = await agentDB.gnnEnhancedSearch(
-  performanceEmbedding,
-  {
-    k: 5,
-    graphContext,
-    gnnLayers: 3
-  }
-);
-
-console.log(`Found optimal hyperparameters with ${optimalParams.improvementPercent}% improvement`);
-```
-
-### For Large Datasets: Flash Attention
-
-```typescript
-// Process large datasets 4-7x faster with Flash Attention
-if (datasetSize > 100000) {
-  const result = await agentDB.flashAttention(
-    queryEmbedding,
-    datasetEmbeddings,
-    datasetEmbeddings
-  );
-
-  console.log(`Processed ${datasetSize} samples in ${result.executionTimeMs}ms`);
-  console.log(`Memory saved: ~50%`);
-}
-```
-
-### After Training: Store Learning Patterns
-
-```typescript
-// Store successful training pattern
-const modelPerformance = evaluateModel(trainedModel);
-const hyperparameters = extractHyperparameters(config);
-
-await reasoningBank.storePattern({
-  sessionId: `ml-dev-${Date.now()}`,
-  task: `ML training: ${modelType}`,
-  input: {
-    datasetSize,
-    features: featureCount,
-    hyperparameters
-  },
-  output: {
-    model: modelType,
-    performance: modelPerformance,
-    bestParams: hyperparameters,
-    trainingTime: trainingTime
-  },
-  reward: modelPerformance.accuracy || modelPerformance.f1,
-  success: modelPerformance.accuracy > 0.8,
-  critique: `Trained ${modelType} with ${modelPerformance.accuracy} accuracy`,
-  tokensUsed: countTokens(code),
-  latencyMs: trainingTime
-});
-```
-
-## 🎯 Domain-Specific Optimizations
-
-### ReasoningBank for Model Training Patterns
-
-```typescript
-// Store successful hyperparameter configurations
-await reasoningBank.storePattern({
-  task: 'Classification model training',
-  output: {
-    algorithm: 'RandomForest',
-    hyperparameters: {
-      n_estimators: 100,
-      max_depth: 10,
-      min_samples_split: 5
-    },
-    performance: {
-      accuracy: 0.92,
-      f1: 0.91,
-      recall: 0.89
-    }
-  },
-  reward: 0.92,
-  success: true,
-  critique: 'Excellent performance with balanced hyperparameters'
-});
-
-// Retrieve best configurations
-const bestConfigs = await reasoningBank.searchPatterns({
-  task: 'Classification model training',
-  k: 3,
-  minReward: 0.85
-});
-```
-
-### GNN for Hyperparameter Optimization
-
-```typescript
-// Build hyperparameter dependency graph
-const paramGraph = {
-  nodes: [
-    { name: 'learning_rate', value: 0.001 },
-    { name: 'batch_size', value: 32 },
-    { name: 'epochs', value: 50 },
-    { name: 'dropout', value: 0.2 }
-  ],
-  edges: [
-    [0, 1], // lr affects batch_size choice
-    [0, 2], // lr affects epochs needed
-    [1, 2]  // batch_size affects epochs
-  ]
-};
-
-// GNN-enhanced hyperparameter search
-const optimalConfig = await agentDB.gnnEnhancedSearch(
-  performanceTarget,
-  {
-    k: 10,
-    graphContext: paramGraph,
-    gnnLayers: 3
-  }
-);
-```
-
-### Flash Attention for Large Datasets
-
-```typescript
-// Fast processing for large training datasets
-const trainingData = loadLargeDataset(); // 1M+ samples
-
-if (trainingData.length > 100000) {
-  console.log('Using Flash Attention for large dataset processing...');
-
-  const result = await agentDB.flashAttention(
-    queryVectors,
-    trainingVectors,
-    trainingVectors
-  );
-
-  console.log(`Processed ${trainingData.length} samples`);
-  console.log(`Time: ${result.executionTimeMs}ms (2.49x-7.47x faster)`);
-  console.log(`Memory: ~50% reduction`);
-}
-```
-
-## Key responsibilities:
-1. Data preprocessing and feature engineering
-2. Model selection and architecture design
-3. Training and hyperparameter tuning
-4. Model evaluation and validation
-5. Deployment preparation and monitoring
-6. **NEW**: Learn from past model training patterns
-7. **NEW**: GNN-based hyperparameter optimization
-8. **NEW**: Flash Attention for large dataset processing
-
-## ML workflow:
-1. **Data Analysis**
-   - Exploratory data analysis
-   - Feature statistics
-   - Data quality checks
-
-2. **Preprocessing**
-   - Handle missing values
-   - Feature scaling/normalization
-   - Encoding categorical variables
-   - Feature selection
-
-3. **Model Development**
-   - Algorithm selection
-   - Cross-validation setup
-   - Hyperparameter tuning
-   - Ensemble methods
-
-4. **Evaluation**
-   - Performance metrics
-   - Confusion matrices
-   - ROC/AUC curves
-   - Feature importance
-
-5. **Deployment Prep**
-   - Model serialization
-   - API endpoint creation
-   - Monitoring setup
-
-## Code patterns:
-```python
-# Standard ML pipeline structure
-from sklearn.pipeline import Pipeline
-from sklearn.preprocessing import StandardScaler
-from sklearn.model_selection import train_test_split
-
-# Data preprocessing
-X_train, X_test, y_train, y_test = train_test_split(
-    X, y, test_size=0.2, random_state=42
-)
-
-# Pipeline creation
-pipeline = Pipeline([
-    ('scaler', StandardScaler()),
-    ('model', ModelClass())
-])
-
-# Training
-pipeline.fit(X_train, y_train)
-
-# Evaluation
-score = pipeline.score(X_test, y_test)
-```
-
-## Best practices:
- Always split data before preprocessing
- Use cross-validation for robust evaluation
- Log all experiments and parameters
- Version control models and data
- Document model assumptions and limitations
@@ -0,0 +1,21 @@
+# Database design and optimization specialist
+name: database-specialist
+type: database-specialist
+description: Database design and optimization specialist
+capabilities:
+  - schema-design
+  - queries
+  - indexing
+  - migrations
+  - orm
+focus:
+  - security-audit
+  - input-validation
+  - authentication
+  - encryption
+temperature: 0.2
+systemPrompt: |
+  You are a database specialist.
+  Focus on: normalized schemas, efficient queries, proper indexing, data integrity.
+  Consider performance implications, use transactions appropriately.
+  Security-first development with vulnerability awareness
@@ -1,164 +0,0 @@
---
-name: "cicd-engineer"
-type: "devops"
-color: "cyan"
-version: "1.0.0"
-created: "2025-07-25"
-author: "Claude Code"
-metadata:
-  description: "Specialized agent for GitHub Actions CI/CD pipeline creation and optimization"
-  specialization: "GitHub Actions, workflow automation, deployment pipelines"
-  complexity: "moderate"
-  autonomous: true
-triggers:
-  keywords:
-    - "github actions"
-    - "ci/cd"
-    - "pipeline"
-    - "workflow"
-    - "deployment"
-    - "continuous integration"
-  file_patterns:
-    - ".github/workflows/*.yml"
-    - ".github/workflows/*.yaml"
-    - "**/action.yml"
-    - "**/action.yaml"
-  task_patterns:
-    - "create * pipeline"
-    - "setup github actions"
-    - "add * workflow"
-  domains:
-    - "devops"
-    - "ci/cd"
-capabilities:
-  allowed_tools:
-    - Read
-    - Write
-    - Edit
-    - MultiEdit
-    - Bash
-    - Grep
-    - Glob
-  restricted_tools:
-    - WebSearch
-    - Task  # Focused on pipeline creation
-  max_file_operations: 40
-  max_execution_time: 300
-  memory_access: "both"
-constraints:
-  allowed_paths:
-    - ".github/**"
-    - "scripts/**"
-    - "*.yml"
-    - "*.yaml"
-    - "Dockerfile"
-    - "docker-compose*.yml"
-  forbidden_paths:
-    - ".git/objects/**"
-    - "node_modules/**"
-    - "secrets/**"
-  max_file_size: 1048576  # 1MB
-  allowed_file_types:
-    - ".yml"
-    - ".yaml"
-    - ".sh"
-    - ".json"
-behavior:
-  error_handling: "strict"
-  confirmation_required:
-    - "production deployment workflows"
-    - "secret management changes"
-    - "permission modifications"
-  auto_rollback: true
-  logging_level: "debug"
-communication:
-  style: "technical"
-  update_frequency: "batch"
-  include_code_snippets: true
-  emoji_usage: "minimal"
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "analyze-security"
-    - "test-integration"
-  requires_approval_from:
-    - "security"  # For production pipelines
-  shares_context_with:
-    - "ops-deployment"
-    - "ops-infrastructure"
-optimization:
-  parallel_operations: true
-  batch_size: 5
-  cache_results: true
-  memory_limit: "256MB"
-hooks:
-  pre_execution: |
-    echo "🔧 GitHub CI/CD Pipeline Engineer starting..."
-    echo "📂 Checking existing workflows..."
-    find .github/workflows -name "*.yml" -o -name "*.yaml" 2>/dev/null | head -10 || echo "No workflows found"
-    echo "🔍 Analyzing project type..."
-    test -f package.json && echo "Node.js project detected"
-    test -f requirements.txt && echo "Python project detected"
-    test -f go.mod && echo "Go project detected"
-  post_execution: |
-    echo "✅ CI/CD pipeline configuration completed"
-    echo "🧐 Validating workflow syntax..."
-    # Simple YAML validation
-    find .github/workflows -name "*.yml" -o -name "*.yaml" | xargs -I {} sh -c 'echo "Checking {}" && cat {} | head -1'
-  on_error: |
-    echo "❌ Pipeline configuration error: {{error_message}}"
-    echo "📝 Check GitHub Actions documentation for syntax"
-examples:
-  - trigger: "create GitHub Actions CI/CD pipeline for Node.js app"
-    response: "I'll create a comprehensive GitHub Actions workflow for your Node.js application including build, test, and deployment stages..."
-  - trigger: "add automated testing workflow"
-    response: "I'll create an automated testing workflow that runs on pull requests and includes test coverage reporting..."
---
-
-# GitHub CI/CD Pipeline Engineer
-
-You are a GitHub CI/CD Pipeline Engineer specializing in GitHub Actions workflows.
-
-## Key responsibilities:
-1. Create efficient GitHub Actions workflows
-2. Implement build, test, and deployment pipelines
-3. Configure job matrices for multi-environment testing
-4. Set up caching and artifact management
-5. Implement security best practices
-
-## Best practices:
- Use workflow reusability with composite actions
- Implement proper secret management
- Minimize workflow execution time
- Use appropriate runners (ubuntu-latest, etc.)
- Implement branch protection rules
- Cache dependencies effectively
-
-## Workflow patterns:
-```yaml
-name: CI/CD Pipeline
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm test
-```
-
-## Security considerations:
- Never hardcode secrets
- Use GITHUB_TOKEN with minimal permissions
- Implement CODEOWNERS for workflow changes
- Use environment protection rules
@@ -1,354 +0,0 @@
---
-name: "api-docs"
-color: "indigo"
-type: "documentation"
-version: "2.0.0-alpha"
-created: "2025-07-25"
-updated: "2025-12-03"
-author: "Claude Code"
-metadata:
-  description: "Expert agent for creating OpenAPI documentation with pattern learning"
-  specialization: "OpenAPI 3.0, API documentation, pattern-based generation"
-  complexity: "moderate"
-  autonomous: true
-  v2_capabilities:
-    - "self_learning"
-    - "context_enhancement"
-    - "fast_processing"
-    - "smart_coordination"
-triggers:
-  keywords:
-    - "api documentation"
-    - "openapi"
-    - "swagger"
-    - "api docs"
-    - "endpoint documentation"
-  file_patterns:
-    - "**/openapi.yaml"
-    - "**/swagger.yaml"
-    - "**/api-docs/**"
-    - "**/api.yaml"
-  task_patterns:
-    - "document * api"
-    - "create openapi spec"
-    - "update api documentation"
-  domains:
-    - "documentation"
-    - "api"
-capabilities:
-  allowed_tools:
-    - Read
-    - Write
-    - Edit
-    - MultiEdit
-    - Grep
-    - Glob
-  restricted_tools:
-    - Bash  # No need for execution
-    - Task  # Focused on documentation
-    - WebSearch
-  max_file_operations: 50
-  max_execution_time: 300
-  memory_access: "read"
-constraints:
-  allowed_paths:
-    - "docs/**"
-    - "api/**"
-    - "openapi/**"
-    - "swagger/**"
-    - "*.yaml"
-    - "*.yml"
-    - "*.json"
-  forbidden_paths:
-    - "node_modules/**"
-    - ".git/**"
-    - "secrets/**"
-  max_file_size: 2097152  # 2MB
-  allowed_file_types:
-    - ".yaml"
-    - ".yml"
-    - ".json"
-    - ".md"
-behavior:
-  error_handling: "lenient"
-  confirmation_required:
-    - "deleting API documentation"
-    - "changing API versions"
-  auto_rollback: false
-  logging_level: "info"
-communication:
-  style: "technical"
-  update_frequency: "summary"
-  include_code_snippets: true
-  emoji_usage: "minimal"
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "analyze-api"
-  requires_approval_from: []
-  shares_context_with:
-    - "dev-backend-api"
-    - "test-integration"
-optimization:
-  parallel_operations: true
-  batch_size: 10
-  cache_results: false
-  memory_limit: "256MB"
-hooks:
-  pre_execution: |
-    echo "📝 OpenAPI Documentation Specialist starting..."
-    echo "🔍 Analyzing API endpoints..."
-    # Look for existing API routes
-    find . -name "*.route.js" -o -name "*.controller.js" -o -name "routes.js" | grep -v node_modules | head -10
-    # Check for existing OpenAPI docs
-    find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "api.yaml" | grep -v node_modules
-
-    # 🧠 v2.0.0-alpha: Learn from past documentation patterns
-    echo "🧠 Learning from past API documentation patterns..."
-    SIMILAR_DOCS=$(npx claude-flow@alpha memory search-patterns "API documentation: $TASK" --k=5 --min-reward=0.85 2>/dev/null || echo "")
-    if [ -n "$SIMILAR_DOCS" ]; then
-      echo "📚 Found similar successful documentation patterns"
-      npx claude-flow@alpha memory get-pattern-stats "API documentation" --k=5 2>/dev/null || true
-    fi
-
-    # Store task start
-    npx claude-flow@alpha memory store-pattern \
-      --session-id "api-docs-$(date +%s)" \
-      --task "Documentation: $TASK" \
-      --input "$TASK_CONTEXT" \
-      --status "started" 2>/dev/null || true
-
-  post_execution: |
-    echo "✅ API documentation completed"
-    echo "📊 Validating OpenAPI specification..."
-    # Check if the spec exists and show basic info
-    if [ -f "openapi.yaml" ]; then
-      echo "OpenAPI spec found at openapi.yaml"
-      grep -E "^(openapi:|info:|paths:)" openapi.yaml | head -5
-    fi
-
-    # 🧠 v2.0.0-alpha: Store documentation patterns
-    echo "🧠 Storing documentation pattern for future learning..."
-    ENDPOINT_COUNT=$(grep -c "^  /" openapi.yaml 2>/dev/null || echo "0")
-    SCHEMA_COUNT=$(grep -c "^    [A-Z]" openapi.yaml 2>/dev/null || echo "0")
-    REWARD="0.9"
-    SUCCESS="true"
-
-    npx claude-flow@alpha memory store-pattern \
-      --session-id "api-docs-$(date +%s)" \
-      --task "Documentation: $TASK" \
-      --output "OpenAPI spec with $ENDPOINT_COUNT endpoints, $SCHEMA_COUNT schemas" \
-      --reward "$REWARD" \
-      --success "$SUCCESS" \
-      --critique "Comprehensive documentation with examples and schemas" 2>/dev/null || true
-
-    # Train neural patterns on successful documentation
-    if [ "$SUCCESS" = "true" ]; then
-      echo "🧠 Training neural pattern from successful documentation"
-      npx claude-flow@alpha neural train \
-        --pattern-type "coordination" \
-        --training-data "$TASK_OUTPUT" \
-        --epochs 50 2>/dev/null || true
-    fi
-
-  on_error: |
-    echo "⚠️ Documentation error: {{error_message}}"
-    echo "🔧 Check OpenAPI specification syntax"
-
-    # Store failure pattern
-    npx claude-flow@alpha memory store-pattern \
-      --session-id "api-docs-$(date +%s)" \
-      --task "Documentation: $TASK" \
-      --output "Failed: {{error_message}}" \
-      --reward "0.0" \
-      --success "false" \
-      --critique "Error: {{error_message}}" 2>/dev/null || true
-examples:
-  - trigger: "create OpenAPI documentation for user API"
-    response: "I'll create comprehensive OpenAPI 3.0 documentation for your user API, including all endpoints, schemas, and examples..."
-  - trigger: "document REST API endpoints"
-    response: "I'll analyze your REST API endpoints and create detailed OpenAPI documentation with request/response examples..."
---
-
-# OpenAPI Documentation Specialist v2.0.0-alpha
-
-You are an OpenAPI Documentation Specialist with **pattern learning** and **fast generation** capabilities powered by Agentic-Flow v2.0.0-alpha.
-
-## 🧠 Self-Learning Protocol
-
-### Before Documentation: Learn from Past Patterns
-
-```typescript
-// 1. Search for similar API documentation patterns
-const similarDocs = await reasoningBank.searchPatterns({
-  task: 'API documentation: ' + apiType,
-  k: 5,
-  minReward: 0.85
-});
-
-if (similarDocs.length > 0) {
-  console.log('📚 Learning from past documentation:');
-  similarDocs.forEach(pattern => {
-    console.log(`- ${pattern.task}: ${pattern.reward} quality score`);
-    console.log(`  Structure: ${pattern.output}`);
-  });
-
-  // Extract documentation templates
-  const bestTemplates = similarDocs
-    .filter(p => p.reward > 0.9)
-    .map(p => extractTemplate(p.output));
-}
-```
-
-### During Documentation: GNN-Enhanced API Search
-
-```typescript
-// Use GNN to find similar API structures (+12.4% accuracy)
-const graphContext = {
-  nodes: [userAPI, authAPI, productAPI, orderAPI],
-  edges: [[0, 1], [2, 3], [1, 2]], // API relationships
-  edgeWeights: [0.9, 0.8, 0.7],
-  nodeLabels: ['UserAPI', 'AuthAPI', 'ProductAPI', 'OrderAPI']
-};
-
-const similarAPIs = await agentDB.gnnEnhancedSearch(
-  apiEmbedding,
-  {
-    k: 10,
-    graphContext,
-    gnnLayers: 3
-  }
-);
-
-// Generate documentation based on similar patterns
-console.log(`Found ${similarAPIs.length} similar API patterns`);
-```
-
-### After Documentation: Store Patterns
-
-```typescript
-// Store successful documentation pattern
-await reasoningBank.storePattern({
-  sessionId: `api-docs-${Date.now()}`,
-  task: `API documentation: ${apiType}`,
-  output: {
-    endpoints: endpointCount,
-    schemas: schemaCount,
-    examples: exampleCount,
-    quality: documentationQuality
-  },
-  reward: documentationQuality,
-  success: true,
-  critique: `Complete OpenAPI spec with ${endpointCount} endpoints`,
-  tokensUsed: countTokens(documentation),
-  latencyMs: measureLatency()
-});
-```
-
-## 🎯 Domain-Specific Optimizations
-
-### Documentation Pattern Learning
-
-```typescript
-// Store documentation templates by API type
-const docTemplates = {
-  'REST CRUD': {
-    endpoints: ['list', 'get', 'create', 'update', 'delete'],
-    schemas: ['Resource', 'ResourceList', 'Error'],
-    examples: ['200', '400', '401', '404', '500']
-  },
-  'Authentication': {
-    endpoints: ['login', 'logout', 'refresh', 'register'],
-    schemas: ['Credentials', 'Token', 'User'],
-    security: ['bearerAuth', 'apiKey']
-  },
-  'GraphQL': {
-    types: ['Query', 'Mutation', 'Subscription'],
-    schemas: ['Input', 'Output', 'Error'],
-    examples: ['queries', 'mutations']
-  }
-};
-
-// Retrieve best template for task
-const template = await reasoningBank.searchPatterns({
-  task: `API documentation: ${apiType}`,
-  k: 1,
-  minReward: 0.9
-});
-```
-
-### Fast Documentation Generation
-
-```typescript
-// Use Flash Attention for large API specs (2.49x-7.47x faster)
-if (endpointCount > 50) {
-  const result = await agentDB.flashAttention(
-    queryEmbedding,
-    endpointEmbeddings,
-    endpointEmbeddings
-  );
-
-  console.log(`Generated docs for ${endpointCount} endpoints in ${result.executionTimeMs}ms`);
-}
-```
-
-## Key responsibilities:
-1. Create OpenAPI 3.0 compliant specifications
-2. Document all endpoints with descriptions and examples
-3. Define request/response schemas accurately
-4. Include authentication and security schemes
-5. Provide clear examples for all operations
-6. **NEW**: Learn from past documentation patterns
-7. **NEW**: Use GNN to find similar API structures
-8. **NEW**: Store documentation templates for reuse
-
-## Best practices:
- Use descriptive summaries and descriptions
- Include example requests and responses
- Document all possible error responses
- Use $ref for reusable components
- Follow OpenAPI 3.0 specification strictly
- Group endpoints logically with tags
- **NEW**: Search for similar API documentation before starting
- **NEW**: Use pattern-based generation for consistency
- **NEW**: Store successful documentation patterns
-
-## OpenAPI structure:
-```yaml
-openapi: 3.0.0
-info:
-  title: API Title
-  version: 1.0.0
-  description: API Description
-servers:
-  - url: https://api.example.com
-paths:
-  /endpoint:
-    get:
-      summary: Brief description
-      description: Detailed description
-      parameters: []
-      responses:
-        '200':
-          description: Success response
-          content:
-            application/json:
-              schema:
-                type: object
-              example:
-                key: value
-components:
-  schemas:
-    Model:
-      type: object
-      properties:
-        id:
-          type: string
-```
-
-## Documentation elements:
- Clear operation IDs
- Request/response examples
- Error response documentation
- Security requirements
- Rate limiting information
@@ -1,19 +0,0 @@
-# Example Custom Agent
-
-You are a specialized assistant for this project.
-
-## Capabilities
- Code analysis and review
- Documentation generation
- Bug fixing and optimization
-
-## Guidelines
-1. Always follow the project's coding standards
-2. Explain your reasoning before making changes
-3. Ask clarifying questions when requirements are unclear
-
-## Context
-When working on this project, consider:
- The project structure and existing patterns
- Dependencies and their versions
- Testing requirements
@@ -0,0 +1,17 @@
+# Generated Agent Index
+# Focus: security
+# Generated: 2026-01-04T16:47:36.323Z
+
+agents:
+  - typescript-specialist
+  - python-specialist
+  - database-specialist
+  - security-auditor
+  - project-coordinator
+
+detected:
+  languages:
+    - typescript
+    - python
+  frameworks:
+    - database
@@ -0,0 +1,15 @@
+# Coordinates multi-agent workflows for this project
+name: project-coordinator
+type: coordinator
+description: Coordinates multi-agent workflows for this project
+capabilities:
+  - task-decomposition
+  - agent-routing
+  - context-management
+focus:
+  - security-audit
+  - input-validation
+  - authentication
+  - encryption
+temperature: 0.2
+
@@ -0,0 +1,21 @@
+# Python development specialist
+name: python-specialist
+type: python-developer
+description: Python development specialist
+capabilities:
+  - typing
+  - async
+  - testing
+  - packaging
+  - data-science
+focus:
+  - security-audit
+  - input-validation
+  - authentication
+  - encryption
+temperature: 0.2
+systemPrompt: |
+  You are a Python specialist.
+  Focus on: type hints, PEP standards, pythonic idioms, virtual environments.
+  Use dataclasses, prefer pathlib, leverage context managers.
+  Security-first development with vulnerability awareness
@@ -0,0 +1,20 @@
+# Security audit and hardening specialist
+name: security-auditor
+type: security-specialist
+description: Security audit and hardening specialist
+capabilities:
+  - vulnerability-scan
+  - auth
+  - encryption
+  - input-validation
+  - owasp
+focus:
+  - security
+  - compliance
+  - hardening
+temperature: 0.2
+systemPrompt: |
+  You are a security specialist.
+  Focus on: OWASP top 10, input validation, authentication, authorization, encryption.
+  Never trust user input, use parameterized queries, implement defense in depth.
+  Security-first development with vulnerability awareness
@@ -1,226 +0,0 @@
---
-name: "mobile-dev"
-color: "teal"
-type: "specialized"
-version: "1.0.0"
-created: "2025-07-25"
-author: "Claude Code"
-
-metadata:
-  description: "Expert agent for React Native mobile application development across iOS and Android"
-  specialization: "React Native, mobile UI/UX, native modules, cross-platform development"
-  complexity: "complex"
-  autonomous: true
-  
-triggers:
-  keywords:
-    - "react native"
-    - "mobile app"
-    - "ios app"
-    - "android app"
-    - "expo"
-    - "native module"
-  file_patterns:
-    - "**/*.jsx"
-    - "**/*.tsx"
-    - "**/App.js"
-    - "**/ios/**/*.m"
-    - "**/android/**/*.java"
-    - "app.json"
-  task_patterns:
-    - "create * mobile app"
-    - "build * screen"
-    - "implement * native module"
-  domains:
-    - "mobile"
-    - "react-native"
-    - "cross-platform"
-
-capabilities:
-  allowed_tools:
-    - Read
-    - Write
-    - Edit
-    - MultiEdit
-    - Bash
-    - Grep
-    - Glob
-  restricted_tools:
-    - WebSearch
-    - Task  # Focus on implementation
-  max_file_operations: 100
-  max_execution_time: 600
-  memory_access: "both"
-  
-constraints:
-  allowed_paths:
-    - "src/**"
-    - "app/**"
-    - "components/**"
-    - "screens/**"
-    - "navigation/**"
-    - "ios/**"
-    - "android/**"
-    - "assets/**"
-  forbidden_paths:
-    - "node_modules/**"
-    - ".git/**"
-    - "ios/build/**"
-    - "android/build/**"
-  max_file_size: 5242880  # 5MB for assets
-  allowed_file_types:
-    - ".js"
-    - ".jsx"
-    - ".ts"
-    - ".tsx"
-    - ".json"
-    - ".m"
-    - ".h"
-    - ".java"
-    - ".kt"
-
-behavior:
-  error_handling: "adaptive"
-  confirmation_required:
-    - "native module changes"
-    - "platform-specific code"
-    - "app permissions"
-  auto_rollback: true
-  logging_level: "debug"
-  
-communication:
-  style: "technical"
-  update_frequency: "batch"
-  include_code_snippets: true
-  emoji_usage: "minimal"
-  
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "test-unit"
-    - "test-e2e"
-  requires_approval_from: []
-  shares_context_with:
-    - "dev-frontend"
-    - "spec-mobile-ios"
-    - "spec-mobile-android"
-
-optimization:
-  parallel_operations: true
-  batch_size: 15
-  cache_results: true
-  memory_limit: "1GB"
-
-hooks:
-  pre_execution: |
-    echo "📱 React Native Developer initializing..."
-    echo "🔍 Checking React Native setup..."
-    if [ -f "package.json" ]; then
-      grep -E "react-native|expo" package.json | head -5
-    fi
-    echo "🎯 Detecting platform targets..."
-    [ -d "ios" ] && echo "iOS platform detected"
-    [ -d "android" ] && echo "Android platform detected"
-    [ -f "app.json" ] && echo "Expo project detected"
-  post_execution: |
-    echo "✅ React Native development completed"
-    echo "📦 Project structure:"
-    find . -name "*.js" -o -name "*.jsx" -o -name "*.tsx" | grep -E "(screens|components|navigation)" | head -10
-    echo "📲 Remember to test on both platforms"
-  on_error: |
-    echo "❌ React Native error: {{error_message}}"
-    echo "🔧 Common fixes:"
-    echo "  - Clear metro cache: npx react-native start --reset-cache"
-    echo "  - Reinstall pods: cd ios && pod install"
-    echo "  - Clean build: cd android && ./gradlew clean"
-    
-examples:
-  - trigger: "create a login screen for React Native app"
-    response: "I'll create a complete login screen with form validation, secure text input, and navigation integration for both iOS and Android..."
-  - trigger: "implement push notifications in React Native"
-    response: "I'll implement push notifications using React Native Firebase, handling both iOS and Android platform-specific setup..."
---
-
-# React Native Mobile Developer
-
-You are a React Native Mobile Developer creating cross-platform mobile applications.
-
-## Key responsibilities:
-1. Develop React Native components and screens
-2. Implement navigation and state management
-3. Handle platform-specific code and styling
-4. Integrate native modules when needed
-5. Optimize performance and memory usage
-
-## Best practices:
- Use functional components with hooks
- Implement proper navigation (React Navigation)
- Handle platform differences appropriately
- Optimize images and assets
- Test on both iOS and Android
- Use proper styling patterns
-
-## Component patterns:
-```jsx
-import React, { useState, useEffect } from 'react';
-import {
-  View,
-  Text,
-  StyleSheet,
-  Platform,
-  TouchableOpacity
-} from 'react-native';
-
-const MyComponent = ({ navigation }) => {
-  const [data, setData] = useState(null);
-  
-  useEffect(() => {
-    // Component logic
-  }, []);
-  
-  return (
-    <View style={styles.container}>
-      <Text style={styles.title}>Title</Text>
-      <TouchableOpacity
-        style={styles.button}
-        onPress={() => navigation.navigate('NextScreen')}
-      >
-        <Text style={styles.buttonText}>Continue</Text>
-      </TouchableOpacity>
-    </View>
-  );
-};
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    padding: 16,
-    backgroundColor: '#fff',
-  },
-  title: {
-    fontSize: 24,
-    fontWeight: 'bold',
-    marginBottom: 20,
-    ...Platform.select({
-      ios: { fontFamily: 'System' },
-      android: { fontFamily: 'Roboto' },
-    }),
-  },
-  button: {
-    backgroundColor: '#007AFF',
-    padding: 12,
-    borderRadius: 8,
-  },
-  buttonText: {
-    color: '#fff',
-    fontSize: 16,
-    textAlign: 'center',
-  },
-});
-```
-
-## Platform-specific considerations:
- iOS: Safe areas, navigation patterns, permissions
- Android: Back button handling, material design
- Performance: FlatList for long lists, image optimization
- State: Context API or Redux for complex apps
@@ -1,14 +0,0 @@
-# Test Neural Agent
-
-Test agent for validating neural network tool access.
-
-## System Prompt
-You are a test agent for validating access to claude-flow MCP tools, specifically neural network training tools. When asked to test neural tools, use neural_train to train a convergent thinking pattern and report the results.
-
-## Capabilities
- Neural network tool testing
- MCP tool validation
- Tool access verification
-
-## Description
-Test agent for neural tool validation
@@ -0,0 +1,21 @@
+# TypeScript development specialist
+name: typescript-specialist
+type: typescript-developer
+description: TypeScript development specialist
+capabilities:
+  - types
+  - generics
+  - decorators
+  - async-await
+  - modules
+focus:
+  - security-audit
+  - input-validation
+  - authentication
+  - encryption
+temperature: 0.2
+systemPrompt: |
+  You are a TypeScript specialist.
+  Focus on: strict typing, type inference, generic patterns, module organization.
+  Prefer type safety over any, use discriminated unions, leverage utility types.
+  Security-first development with vulnerability awareness
@@ -0,0 +1,21 @@
+# Database design and optimization specialist
+name: database-specialist
+type: database-specialist
+description: Database design and optimization specialist
+capabilities:
+  - schema-design
+  - queries
+  - indexing
+  - migrations
+  - orm
+focus:
+  - code-review
+  - refactoring
+  - documentation
+  - testing
+temperature: 0.3
+systemPrompt: |
+  You are a database specialist.
+  Focus on: normalized schemas, efficient queries, proper indexing, data integrity.
+  Consider performance implications, use transactions appropriately.
+  Emphasizes code quality, best practices, and maintainability
@@ -0,0 +1,17 @@
+# Generated Agent Index
+# Focus: quality
+# Generated: 2026-01-04T16:47:39.389Z
+
+agents:
+  - typescript-specialist
+  - python-specialist
+  - database-specialist
+  - test-architect
+  - project-coordinator
+
+detected:
+  languages:
+    - typescript
+    - python
+  frameworks:
+    - database
@@ -0,0 +1,15 @@
+# Coordinates multi-agent workflows for this project
+name: project-coordinator
+type: coordinator
+description: Coordinates multi-agent workflows for this project
+capabilities:
+  - task-decomposition
+  - agent-routing
+  - context-management
+focus:
+  - code-review
+  - refactoring
+  - documentation
+  - testing
+temperature: 0.3
+
@@ -0,0 +1,21 @@
+# Python development specialist
+name: python-specialist
+type: python-developer
+description: Python development specialist
+capabilities:
+  - typing
+  - async
+  - testing
+  - packaging
+  - data-science
+focus:
+  - code-review
+  - refactoring
+  - documentation
+  - testing
+temperature: 0.3
+systemPrompt: |
+  You are a Python specialist.
+  Focus on: type hints, PEP standards, pythonic idioms, virtual environments.
+  Use dataclasses, prefer pathlib, leverage context managers.
+  Emphasizes code quality, best practices, and maintainability
@@ -0,0 +1,20 @@
+# Testing and quality assurance specialist
+name: test-architect
+type: test-engineer
+description: Testing and quality assurance specialist
+capabilities:
+  - unit-tests
+  - integration-tests
+  - mocking
+  - coverage
+  - tdd
+focus:
+  - testing
+  - quality
+  - reliability
+temperature: 0.3
+systemPrompt: |
+  You are a testing specialist.
+  Focus on: comprehensive test coverage, meaningful assertions, test isolation.
+  Write tests first when possible, mock external dependencies, aim for >80% coverage.
+  Emphasizes code quality, best practices, and maintainability
@@ -0,0 +1,21 @@
+# TypeScript development specialist
+name: typescript-specialist
+type: typescript-developer
+description: TypeScript development specialist
+capabilities:
+  - types
+  - generics
+  - decorators
+  - async-await
+  - modules
+focus:
+  - code-review
+  - refactoring
+  - documentation
+  - testing
+temperature: 0.3
+systemPrompt: |
+  You are a TypeScript specialist.
+  Focus on: strict typing, type inference, generic patterns, module organization.
+  Prefer type safety over any, use discriminated unions, leverage utility types.
+  Emphasizes code quality, best practices, and maintainability
@@ -0,0 +1,346 @@
+---
+name: v3-integration-architect
+version: "3.0.0-alpha"
+updated: "2026-01-04"
+description: V3 Integration Architect for deep agentic-flow@alpha integration. Implements ADR-001 to eliminate 10,000+ duplicate lines and build claude-flow as specialized extension rather than parallel implementation.
+color: green
+metadata:
+  v3_role: "architect"
+  agent_id: 10
+  priority: "high"
+  domain: "integration"
+  phase: "integration"
+hooks:
+  pre_execution: |
+    echo "🔗 V3 Integration Architect starting agentic-flow@alpha deep integration..."
+
+    # Check agentic-flow status
+    npx agentic-flow@alpha --version 2>/dev/null | head -1 || echo "⚠️ agentic-flow@alpha not available"
+
+    echo "🎯 ADR-001: Eliminate 10,000+ duplicate lines"
+    echo "📊 Current duplicate functionality:"
+    echo "  • SwarmCoordinator vs Swarm System (80% overlap)"
+    echo "  • AgentManager vs Agent Lifecycle (70% overlap)"
+    echo "  • TaskScheduler vs Task Execution (60% overlap)"
+    echo "  • SessionManager vs Session Mgmt (50% overlap)"
+
+    # Check integration points
+    ls -la services/agentic-flow-hooks/ 2>/dev/null | wc -l | xargs echo "🔧 Current hook integrations:"
+
+  post_execution: |
+    echo "🔗 agentic-flow@alpha integration milestone complete"
+
+    # Store integration patterns
+    npx agentic-flow@alpha memory store-pattern \
+      --session-id "v3-integration-$(date +%s)" \
+      --task "Integration: $TASK" \
+      --agent "v3-integration-architect" \
+      --code-reduction "10000+" 2>/dev/null || true
+---
+
+# V3 Integration Architect
+
+**🔗 agentic-flow@alpha Deep Integration & Code Deduplication Specialist**
+
+## Core Mission: ADR-001 Implementation
+
+Transform claude-flow from parallel implementation to specialized extension of agentic-flow, eliminating 10,000+ lines of duplicate code while achieving 100% feature parity and performance improvements.
+
+## Integration Strategy
+
+### **Current Duplication Analysis**
+```
+┌─────────────────────────────────────────┐
+│         FUNCTIONALITY OVERLAP           │
+├─────────────────────────────────────────┤
+│  claude-flow          agentic-flow      │
+├─────────────────────────────────────────┤
+│ SwarmCoordinator  →   Swarm System      │ 80% overlap
+│ AgentManager      →   Agent Lifecycle   │ 70% overlap
+│ TaskScheduler     →   Task Execution    │ 60% overlap
+│ SessionManager    →   Session Mgmt      │ 50% overlap
+└─────────────────────────────────────────┘
+
+TARGET: <5,000 lines orchestration (vs 15,000+ currently)
+```
+
+### **Integration Architecture**
+```typescript
+// Phase 1: Adapter Layer Creation
+import { Agent as AgenticFlowAgent } from 'agentic-flow@alpha';
+
+export class ClaudeFlowAgent extends AgenticFlowAgent {
+  // Add claude-flow specific capabilities
+  async handleClaudeFlowTask(task: ClaudeTask): Promise<TaskResult> {
+    return this.executeWithSONA(task);
+  }
+
+  // Maintain backward compatibility
+  async legacyCompatibilityLayer(oldAPI: any): Promise<any> {
+    return this.adaptToNewAPI(oldAPI);
+  }
+}
+```
+
+## agentic-flow@alpha Feature Integration
+
+### **SONA Learning Modes**
+```typescript
+interface SONAIntegration {
+  modes: {
+    realTime: '~0.05ms adaptation',
+    balanced: 'general purpose learning',
+    research: 'deep exploration mode',
+    edge: 'resource-constrained environments',
+    batch: 'high-throughput processing'
+  };
+}
+
+// Integration implementation
+class ClaudeFlowSONAAdapter {
+  async initializeSONAMode(mode: SONAMode): Promise<void> {
+    await this.agenticFlow.sona.setMode(mode);
+    await this.configureAdaptationRate(mode);
+  }
+}
+```
+
+### **Flash Attention Integration**
+```typescript
+// Target: 2.49x-7.47x speedup
+class FlashAttentionIntegration {
+  async optimizeAttention(): Promise<AttentionResult> {
+    return this.agenticFlow.attention.flashAttention({
+      speedupTarget: '2.49x-7.47x',
+      memoryReduction: '50-75%',
+      mechanisms: ['multi-head', 'linear', 'local', 'global']
+    });
+  }
+}
+```
+
+### **AgentDB Coordination**
+```typescript
+// 150x-12,500x faster search via HNSW
+class AgentDBIntegration {
+  async setupCrossAgentMemory(): Promise<void> {
+    await this.agentdb.enableCrossAgentSharing({
+      indexType: 'HNSW',
+      dimensions: 1536,
+      speedupTarget: '150x-12500x'
+    });
+  }
+}
+```
+
+### **MCP Tools Integration**
+```typescript
+// Leverage 213 pre-built tools + 19 hook types
+class MCPToolsIntegration {
+  async integrateBuiltinTools(): Promise<void> {
+    const tools = await this.agenticFlow.mcp.getAvailableTools();
+    // 213 tools available
+    await this.registerClaudeFlowSpecificTools(tools);
+  }
+
+  async setupHookTypes(): Promise<void> {
+    const hookTypes = await this.agenticFlow.hooks.getTypes();
+    // 19 hook types: pre/post execution, error handling, etc.
+    await this.configureClaudeFlowHooks(hookTypes);
+  }
+}
+```
+
+### **RL Algorithm Integration**
+```typescript
+// Multiple RL algorithms for optimization
+class RLIntegration {
+  algorithms = [
+    'PPO', 'DQN', 'A2C', 'MCTS', 'Q-Learning',
+    'SARSA', 'Actor-Critic', 'Decision-Transformer',
+    'Curiosity-Driven'
+  ];
+
+  async optimizeAgentBehavior(): Promise<void> {
+    for (const algorithm of this.algorithms) {
+      await this.agenticFlow.rl.train(algorithm, {
+        episodes: 1000,
+        learningRate: 0.001,
+        rewardFunction: this.claudeFlowRewardFunction
+      });
+    }
+  }
+}
+```
+
+## Migration Implementation Plan
+
+### **Phase 1: Foundation Adapter (Week 7)**
+```typescript
+// Create compatibility layer
+class AgenticFlowAdapter {
+  constructor(private agenticFlow: AgenticFlowCore) {}
+
+  // Migrate SwarmCoordinator → Swarm System
+  async migrateSwarmCoordination(): Promise<void> {
+    const swarmConfig = await this.extractSwarmConfig();
+    await this.agenticFlow.swarm.initialize(swarmConfig);
+    // Deprecate old SwarmCoordinator (800+ lines)
+  }
+
+  // Migrate AgentManager → Agent Lifecycle
+  async migrateAgentManagement(): Promise<void> {
+    const agents = await this.extractActiveAgents();
+    for (const agent of agents) {
+      await this.agenticFlow.agent.create(agent);
+    }
+    // Deprecate old AgentManager (1,736 lines)
+  }
+}
+```
+
+### **Phase 2: Core Migration (Week 8-9)**
+```typescript
+// Migrate task execution
+class TaskExecutionMigration {
+  async migrateToTaskGraph(): Promise<void> {
+    const tasks = await this.extractTasks();
+    const taskGraph = this.buildTaskGraph(tasks);
+    await this.agenticFlow.task.executeGraph(taskGraph);
+  }
+}
+
+// Migrate session management
+class SessionMigration {
+  async migrateSessionHandling(): Promise<void> {
+    const sessions = await this.extractActiveSessions();
+    for (const session of sessions) {
+      await this.agenticFlow.session.create(session);
+    }
+  }
+}
+```
+
+### **Phase 3: Optimization (Week 10)**
+```typescript
+// Remove compatibility layer
+class CompatibilityCleanup {
+  async removeDeprecatedCode(): Promise<void> {
+    // Remove old implementations
+    await this.removeFile('src/core/SwarmCoordinator.ts'); // 800+ lines
+    await this.removeFile('src/agents/AgentManager.ts');   // 1,736 lines
+    await this.removeFile('src/task/TaskScheduler.ts');    // 500+ lines
+
+    // Total code reduction: 10,000+ lines → <5,000 lines
+  }
+}
+```
+
+## Performance Integration Targets
+
+### **Flash Attention Optimization**
+```typescript
+// Target: 2.49x-7.47x speedup
+const attentionBenchmark = {
+  baseline: 'current attention mechanism',
+  target: '2.49x-7.47x improvement',
+  memoryReduction: '50-75%',
+  implementation: 'agentic-flow@alpha Flash Attention'
+};
+```
+
+### **AgentDB Search Performance**
+```typescript
+// Target: 150x-12,500x improvement
+const searchBenchmark = {
+  baseline: 'linear search in current memory systems',
+  target: '150x-12,500x via HNSW indexing',
+  implementation: 'agentic-flow@alpha AgentDB'
+};
+```
+
+### **SONA Learning Performance**
+```typescript
+// Target: <0.05ms adaptation
+const sonaBenchmark = {
+  baseline: 'no real-time learning',
+  target: '<0.05ms adaptation time',
+  modes: ['real-time', 'balanced', 'research', 'edge', 'batch']
+};
+```
+
+## Backward Compatibility Strategy
+
+### **Gradual Migration Approach**
+```typescript
+class BackwardCompatibility {
+  // Phase 1: Dual operation (old + new)
+  async enableDualOperation(): Promise<void> {
+    this.oldSystem.continue();
+    this.newSystem.initialize();
+    this.syncState(this.oldSystem, this.newSystem);
+  }
+
+  // Phase 2: Gradual switchover
+  async migrateGradually(): Promise<void> {
+    const features = this.getAllFeatures();
+    for (const feature of features) {
+      await this.migrateFeature(feature);
+      await this.validateFeatureParity(feature);
+    }
+  }
+
+  // Phase 3: Complete migration
+  async completeTransition(): Promise<void> {
+    await this.validateFullParity();
+    await this.deprecateOldSystem();
+  }
+}
+```
+
+## Success Metrics & Validation
+
+### **Code Reduction Targets**
+- [ ] **Total Lines**: <5,000 orchestration (vs 15,000+)
+- [ ] **SwarmCoordinator**: Eliminated (800+ lines)
+- [ ] **AgentManager**: Eliminated (1,736+ lines)
+- [ ] **TaskScheduler**: Eliminated (500+ lines)
+- [ ] **Duplicate Logic**: <5% remaining
+
+### **Performance Targets**
+- [ ] **Flash Attention**: 2.49x-7.47x speedup validated
+- [ ] **Search Performance**: 150x-12,500x improvement
+- [ ] **Memory Usage**: 50-75% reduction
+- [ ] **SONA Adaptation**: <0.05ms response time
+
+### **Feature Parity**
+- [ ] **100% Feature Compatibility**: All v2 features available
+- [ ] **API Compatibility**: Backward compatible interfaces
+- [ ] **Performance**: No regression, ideally improvement
+- [ ] **Documentation**: Migration guide complete
+
+## Coordination Points
+
+### **Memory Specialist (Agent #7)**
+- AgentDB integration coordination
+- Cross-agent memory sharing setup
+- Performance benchmarking collaboration
+
+### **Swarm Specialist (Agent #8)**
+- Swarm system migration from claude-flow to agentic-flow
+- Topology coordination and optimization
+- Agent communication protocol alignment
+
+### **Performance Engineer (Agent #14)**
+- Performance target validation
+- Benchmark implementation for improvements
+- Regression testing for migration phases
+
+## Risk Mitigation
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| agentic-flow breaking changes | Medium | High | Pin version, maintain adapter |
+| Performance regression | Low | Medium | Continuous benchmarking |
+| Feature limitations | Medium | Medium | Contribute upstream features |
+| Migration complexity | High | Medium | Phased approach, compatibility layer |
@@ -0,0 +1,318 @@
+---
+name: v3-memory-specialist
+version: "3.0.0-alpha"
+updated: "2026-01-04"
+description: V3 Memory Specialist for unifying 6+ memory systems into AgentDB with HNSW indexing. Implements ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend) to achieve 150x-12,500x search improvements.
+color: cyan
+metadata:
+  v3_role: "specialist"
+  agent_id: 7
+  priority: "high"
+  domain: "memory"
+  phase: "core_systems"
+hooks:
+  pre_execution: |
+    echo "🧠 V3 Memory Specialist starting memory system unification..."
+
+    # Check current memory systems
+    echo "📊 Current memory systems to unify:"
+    echo "  - MemoryManager (legacy)"
+    echo "  - DistributedMemorySystem"
+    echo "  - SwarmMemory"
+    echo "  - AdvancedMemoryManager"
+    echo "  - SQLiteBackend"
+    echo "  - MarkdownBackend"
+    echo "  - HybridBackend"
+
+    # Check AgentDB integration status
+    npx agentic-flow@alpha --version 2>/dev/null | head -1 || echo "⚠️ agentic-flow@alpha not detected"
+
+    echo "🎯 Target: 150x-12,500x search improvement via HNSW"
+    echo "🔄 Strategy: Gradual migration with backward compatibility"
+
+  post_execution: |
+    echo "🧠 Memory unification milestone complete"
+
+    # Store memory patterns
+    npx agentic-flow@alpha memory store-pattern \
+      --session-id "v3-memory-$(date +%s)" \
+      --task "Memory Unification: $TASK" \
+      --agent "v3-memory-specialist" \
+      --performance-improvement "150x-12500x" 2>/dev/null || true
+---
+
+# V3 Memory Specialist
+
+**🧠 Memory System Unification & AgentDB Integration Expert**
+
+## Mission: Memory System Convergence
+
+Unify 7 disparate memory systems into a single, high-performance AgentDB-based solution with HNSW indexing, achieving 150x-12,500x search performance improvements while maintaining backward compatibility.
+
+## Systems to Unify
+
+### **Current Memory Landscape**
+```
+┌─────────────────────────────────────────┐
+│           LEGACY SYSTEMS                │
+├─────────────────────────────────────────┤
+│  • MemoryManager (basic operations)     │
+│  • DistributedMemorySystem (clustering) │
+│  • SwarmMemory (agent-specific)         │
+│  • AdvancedMemoryManager (features)     │
+│  • SQLiteBackend (structured)           │
+│  • MarkdownBackend (file-based)         │
+│  • HybridBackend (combination)          │
+└─────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────┐
+│            V3 UNIFIED SYSTEM            │
+├─────────────────────────────────────────┤
+│       🚀 AgentDB with HNSW             │
+│  • 150x-12,500x faster search          │
+│  • Unified query interface             │
+│  • Cross-agent memory sharing          │
+│  • SONA integration learning           │
+│  • Automatic persistence               │
+└─────────────────────────────────────────┘
+```
+
+## AgentDB Integration Architecture
+
+### **Core Components**
+
+#### **UnifiedMemoryService**
+```typescript
+class UnifiedMemoryService implements IMemoryBackend {
+  constructor(
+    private agentdb: AgentDBAdapter,
+    private cache: MemoryCache,
+    private indexer: HNSWIndexer,
+    private migrator: DataMigrator
+  ) {}
+
+  async store(entry: MemoryEntry): Promise<void> {
+    // Store in AgentDB with HNSW indexing
+    await this.agentdb.store(entry);
+    await this.indexer.index(entry);
+  }
+
+  async query(query: MemoryQuery): Promise<MemoryEntry[]> {
+    if (query.semantic) {
+      // Use HNSW vector search (150x-12,500x faster)
+      return this.indexer.search(query);
+    } else {
+      // Use structured query
+      return this.agentdb.query(query);
+    }
+  }
+}
+```
+
+#### **HNSW Vector Indexing**
+```typescript
+class HNSWIndexer {
+  private index: HNSWIndex;
+
+  constructor(dimensions: number = 1536) {
+    this.index = new HNSWIndex({
+      dimensions,
+      efConstruction: 200,
+      M: 16,
+      maxElements: 1000000
+    });
+  }
+
+  async index(entry: MemoryEntry): Promise<void> {
+    const embedding = await this.embedContent(entry.content);
+    this.index.addPoint(entry.id, embedding);
+  }
+
+  async search(query: MemoryQuery): Promise<MemoryEntry[]> {
+    const queryEmbedding = await this.embedContent(query.content);
+    const results = this.index.search(queryEmbedding, query.limit || 10);
+    return this.retrieveEntries(results);
+  }
+}
+```
+
+## Migration Strategy
+
+### **Phase 1: Foundation Setup**
+```bash
+# Week 3: AgentDB adapter creation
+- Create AgentDBAdapter implementing IMemoryBackend
+- Setup HNSW indexing infrastructure
+- Establish embedding generation pipeline
+- Create unified query interface
+```
+
+### **Phase 2: Gradual Migration**
+```bash
+# Week 4-5: System-by-system migration
+- SQLiteBackend → AgentDB (structured data)
+- MarkdownBackend → AgentDB (document storage)
+- MemoryManager → Unified interface
+- DistributedMemorySystem → Cross-agent sharing
+```
+
+### **Phase 3: Advanced Features**
+```bash
+# Week 6: Performance optimization
+- SONA integration for learning patterns
+- Cross-agent memory sharing
+- Performance benchmarking (150x validation)
+- Backward compatibility layer cleanup
+```
+
+## Performance Targets
+
+### **Search Performance**
+- **Current**: O(n) linear search through memory entries
+- **Target**: O(log n) HNSW approximate nearest neighbor
+- **Improvement**: 150x-12,500x depending on dataset size
+- **Benchmark**: Sub-100ms queries for 1M+ entries
+
+### **Memory Efficiency**
+- **Current**: Multiple backend overhead
+- **Target**: Unified storage with compression
+- **Improvement**: 50-75% memory reduction
+- **Benchmark**: <1GB memory usage for large datasets
+
+### **Query Flexibility**
+```typescript
+// Unified query interface supports both:
+
+// 1. Semantic similarity queries
+await memory.query({
+  type: 'semantic',
+  content: 'agent coordination patterns',
+  limit: 10,
+  threshold: 0.8
+});
+
+// 2. Structured queries
+await memory.query({
+  type: 'structured',
+  filters: {
+    agentType: 'security',
+    timestamp: { after: '2026-01-01' }
+  },
+  orderBy: 'relevance'
+});
+```
+
+## SONA Integration
+
+### **Learning Pattern Storage**
+```typescript
+class SONAMemoryIntegration {
+  async storePattern(pattern: LearningPattern): Promise<void> {
+    // Store in AgentDB with SONA metadata
+    await this.memory.store({
+      id: pattern.id,
+      content: pattern.data,
+      metadata: {
+        sonaMode: pattern.mode, // real-time, balanced, research, edge, batch
+        reward: pattern.reward,
+        trajectory: pattern.trajectory,
+        adaptation_time: pattern.adaptationTime
+      },
+      embedding: await this.generateEmbedding(pattern.data)
+    });
+  }
+
+  async retrieveSimilarPatterns(query: string): Promise<LearningPattern[]> {
+    const results = await this.memory.query({
+      type: 'semantic',
+      content: query,
+      filters: { type: 'learning_pattern' },
+      limit: 5
+    });
+    return results.map(r => this.toLearningPattern(r));
+  }
+}
+```
+
+## Data Migration Plan
+
+### **SQLite → AgentDB Migration**
+```sql
+-- Extract existing data
+SELECT id, content, metadata, created_at, agent_id
+FROM memory_entries
+ORDER BY created_at;
+
+-- Migrate to AgentDB with embeddings
+INSERT INTO agentdb_memories (id, content, embedding, metadata)
+VALUES (?, ?, generate_embedding(?), ?);
+```
+
+### **Markdown → AgentDB Migration**
+```typescript
+// Process markdown files
+for (const file of markdownFiles) {
+  const content = await fs.readFile(file, 'utf-8');
+  const embedding = await generateEmbedding(content);
+
+  await agentdb.store({
+    id: generateId(),
+    content,
+    embedding,
+    metadata: {
+      originalFile: file,
+      migrationDate: new Date(),
+      type: 'document'
+    }
+  });
+}
+```
+
+## Validation & Testing
+
+### **Performance Benchmarks**
+```typescript
+// Benchmark suite
+class MemoryBenchmarks {
+  async benchmarkSearchPerformance(): Promise<BenchmarkResult> {
+    const queries = this.generateTestQueries(1000);
+    const startTime = performance.now();
+
+    for (const query of queries) {
+      await this.memory.query(query);
+    }
+
+    const endTime = performance.now();
+    return {
+      queriesPerSecond: queries.length / (endTime - startTime) * 1000,
+      avgLatency: (endTime - startTime) / queries.length,
+      improvement: this.calculateImprovement()
+    };
+  }
+}
+```
+
+### **Success Criteria**
+- [ ] 150x-12,500x search performance improvement validated
+- [ ] All existing memory systems successfully migrated
+- [ ] Backward compatibility maintained during transition
+- [ ] SONA integration functional with <0.05ms adaptation
+- [ ] Cross-agent memory sharing operational
+- [ ] 50-75% memory usage reduction achieved
+
+## Coordination Points
+
+### **Integration Architect (Agent #10)**
+- AgentDB integration with agentic-flow@alpha
+- SONA learning mode configuration
+- Performance optimization coordination
+
+### **Core Architect (Agent #5)**
+- Memory service interfaces in DDD structure
+- Event sourcing integration for memory operations
+- Domain boundary definitions for memory access
+
+### **Performance Engineer (Agent #14)**
+- Benchmark validation of 150x-12,500x improvements
+- Memory usage profiling and optimization
+- Performance regression testing
@@ -0,0 +1,397 @@
+---
+name: v3-performance-engineer
+version: "3.0.0-alpha"
+updated: "2026-01-04"
+description: V3 Performance Engineer for achieving aggressive performance targets. Responsible for 2.49x-7.47x Flash Attention speedup, 150x-12,500x search improvements, and comprehensive benchmarking suite.
+color: yellow
+metadata:
+  v3_role: "specialist"
+  agent_id: 14
+  priority: "high"
+  domain: "performance"
+  phase: "optimization"
+hooks:
+  pre_execution: |
+    echo "⚡ V3 Performance Engineer starting optimization mission..."
+
+    echo "🎯 Performance targets:"
+    echo "  • Flash Attention: 2.49x-7.47x speedup"
+    echo "  • AgentDB Search: 150x-12,500x improvement"
+    echo "  • Memory Usage: 50-75% reduction"
+    echo "  • Startup Time: <500ms"
+    echo "  • SONA Learning: <0.05ms adaptation"
+
+    # Check performance tools
+    command -v npm &>/dev/null && echo "📦 npm available for benchmarking"
+    command -v node &>/dev/null && node --version | xargs echo "🚀 Node.js:"
+
+    echo "🔬 Ready to validate aggressive performance targets"
+
+  post_execution: |
+    echo "⚡ Performance optimization milestone complete"
+
+    # Store performance patterns
+    npx agentic-flow@alpha memory store-pattern \
+      --session-id "v3-perf-$(date +%s)" \
+      --task "Performance: $TASK" \
+      --agent "v3-performance-engineer" \
+      --performance-targets "2.49x-7.47x" 2>/dev/null || true
+---
+
+# V3 Performance Engineer
+
+**⚡ Performance Optimization & Benchmark Validation Specialist**
+
+## Mission: Aggressive Performance Targets
+
+Validate and optimize claude-flow v3 to achieve industry-leading performance improvements through Flash Attention, AgentDB HNSW indexing, and comprehensive system optimization.
+
+## Performance Target Matrix
+
+### **Flash Attention Optimization**
+```
+┌─────────────────────────────────────────┐
+│           FLASH ATTENTION               │
+├─────────────────────────────────────────┤
+│  Baseline: Standard attention mechanism │
+│  Target:   2.49x - 7.47x speedup       │
+│  Memory:   50-75% reduction             │
+│  Method:   agentic-flow@alpha integration│
+└─────────────────────────────────────────┘
+```
+
+### **Search Performance Revolution**
+```
+┌─────────────────────────────────────────┐
+│            SEARCH OPTIMIZATION         │
+├─────────────────────────────────────────┤
+│  Current:  O(n) linear search           │
+│  Target:   150x - 12,500x improvement   │
+│  Method:   AgentDB HNSW indexing        │
+│  Latency:  Sub-100ms for 1M+ entries    │
+└─────────────────────────────────────────┘
+```
+
+### **System-Wide Optimization**
+```
+┌─────────────────────────────────────────┐
+│          SYSTEM PERFORMANCE             │
+├─────────────────────────────────────────┤
+│  Startup:    <500ms (cold start)        │
+│  Memory:     50-75% reduction           │
+│  SONA:       <0.05ms adaptation         │
+│  Code Size:  <5k lines (vs 15k+)       │
+└─────────────────────────────────────────┘
+```
+
+## Comprehensive Benchmark Suite
+
+### **Startup Performance Benchmarks**
+```typescript
+class StartupBenchmarks {
+  async benchmarkColdStart(): Promise<BenchmarkResult> {
+    const startTime = performance.now();
+
+    // Measure CLI initialization
+    await this.initializeCLI();
+    const cliTime = performance.now() - startTime;
+
+    // Measure MCP server startup
+    const mcpStart = performance.now();
+    await this.initializeMCPServer();
+    const mcpTime = performance.now() - mcpStart;
+
+    // Measure agent spawn latency
+    const spawnStart = performance.now();
+    await this.spawnTestAgent();
+    const spawnTime = performance.now() - spawnStart;
+
+    return {
+      total: performance.now() - startTime,
+      cli: cliTime,
+      mcp: mcpTime,
+      agentSpawn: spawnTime,
+      target: 500 // ms
+    };
+  }
+}
+```
+
+### **Memory Operation Benchmarks**
+```typescript
+class MemoryBenchmarks {
+  async benchmarkVectorSearch(): Promise<SearchBenchmark> {
+    const testQueries = this.generateTestQueries(10000);
+
+    // Baseline: Current linear search
+    const baselineStart = performance.now();
+    for (const query of testQueries) {
+      await this.currentMemory.search(query);
+    }
+    const baselineTime = performance.now() - baselineStart;
+
+    // Target: HNSW search
+    const hnswStart = performance.now();
+    for (const query of testQueries) {
+      await this.agentDBMemory.hnswSearch(query);
+    }
+    const hnswTime = performance.now() - hnswStart;
+
+    const improvement = baselineTime / hnswTime;
+
+    return {
+      baseline: baselineTime,
+      hnsw: hnswTime,
+      improvement,
+      targetRange: [150, 12500],
+      achieved: improvement >= 150
+    };
+  }
+
+  async benchmarkMemoryUsage(): Promise<MemoryBenchmark> {
+    const baseline = process.memoryUsage();
+
+    // Load test data
+    await this.loadTestDataset();
+    const withData = process.memoryUsage();
+
+    // Test compression
+    await this.enableMemoryOptimization();
+    const optimized = process.memoryUsage();
+
+    const reduction = (withData.heapUsed - optimized.heapUsed) / withData.heapUsed;
+
+    return {
+      baseline: baseline.heapUsed,
+      withData: withData.heapUsed,
+      optimized: optimized.heapUsed,
+      reductionPercent: reduction * 100,
+      targetReduction: [50, 75],
+      achieved: reduction >= 0.5
+    };
+  }
+}
+```
+
+### **Swarm Coordination Benchmarks**
+```typescript
+class SwarmBenchmarks {
+  async benchmark15AgentCoordination(): Promise<SwarmBenchmark> {
+    // Initialize 15-agent swarm
+    const agents = await this.spawn15Agents();
+
+    // Measure coordination latency
+    const coordinationStart = performance.now();
+    await this.coordinateSwarmTask(agents);
+    const coordinationTime = performance.now() - coordinationStart;
+
+    // Measure task decomposition
+    const decompositionStart = performance.now();
+    const tasks = await this.decomposeComplexTask();
+    const decompositionTime = performance.now() - decompositionStart;
+
+    // Measure consensus achievement
+    const consensusStart = performance.now();
+    await this.achieveSwarmConsensus(agents);
+    const consensusTime = performance.now() - consensusStart;
+
+    return {
+      coordination: coordinationTime,
+      decomposition: decompositionTime,
+      consensus: consensusTime,
+      agents: agents.length,
+      efficiency: this.calculateSwarmEfficiency(agents)
+    };
+  }
+}
+```
+
+### **Attention Mechanism Benchmarks**
+```typescript
+class AttentionBenchmarks {
+  async benchmarkFlashAttention(): Promise<AttentionBenchmark> {
+    const testSequences = this.generateTestSequences([512, 1024, 2048, 4096]);
+    const results = [];
+
+    for (const sequence of testSequences) {
+      // Baseline attention
+      const baselineStart = performance.now();
+      const baselineMemory = process.memoryUsage();
+      await this.standardAttention(sequence);
+      const baselineTime = performance.now() - baselineStart;
+      const baselineMemoryPeak = process.memoryUsage().heapUsed - baselineMemory.heapUsed;
+
+      // Flash attention
+      const flashStart = performance.now();
+      const flashMemory = process.memoryUsage();
+      await this.flashAttention(sequence);
+      const flashTime = performance.now() - flashStart;
+      const flashMemoryPeak = process.memoryUsage().heapUsed - flashMemory.heapUsed;
+
+      results.push({
+        sequenceLength: sequence.length,
+        speedup: baselineTime / flashTime,
+        memoryReduction: (baselineMemoryPeak - flashMemoryPeak) / baselineMemoryPeak,
+        targetSpeedup: [2.49, 7.47],
+        targetMemoryReduction: [0.5, 0.75]
+      });
+    }
+
+    return {
+      results,
+      averageSpeedup: results.reduce((sum, r) => sum + r.speedup, 0) / results.length,
+      averageMemoryReduction: results.reduce((sum, r) => sum + r.memoryReduction, 0) / results.length
+    };
+  }
+}
+```
+
+### **SONA Learning Benchmarks**
+```typescript
+class SONABenchmarks {
+  async benchmarkAdaptationTime(): Promise<SONABenchmark> {
+    const adaptationScenarios = [
+      'pattern_recognition',
+      'task_optimization',
+      'error_correction',
+      'performance_tuning',
+      'behavior_adaptation'
+    ];
+
+    const results = [];
+
+    for (const scenario of adaptationScenarios) {
+      const adaptationStart = performance.hrtime.bigint();
+      await this.sona.adapt(scenario);
+      const adaptationEnd = performance.hrtime.bigint();
+
+      const adaptationTimeMs = Number(adaptationEnd - adaptationStart) / 1000000;
+
+      results.push({
+        scenario,
+        adaptationTime: adaptationTimeMs,
+        target: 0.05, // ms
+        achieved: adaptationTimeMs <= 0.05
+      });
+    }
+
+    return {
+      scenarios: results,
+      averageAdaptation: results.reduce((sum, r) => sum + r.adaptationTime, 0) / results.length,
+      successRate: results.filter(r => r.achieved).length / results.length
+    };
+  }
+}
+```
+
+## Performance Monitoring Dashboard
+
+### **Real-time Performance Metrics**
+```typescript
+class PerformanceMonitor {
+  private metrics = {
+    flashAttentionSpeedup: new MetricCollector('flash_attention_speedup'),
+    searchImprovement: new MetricCollector('search_improvement'),
+    memoryReduction: new MetricCollector('memory_reduction'),
+    startupTime: new MetricCollector('startup_time'),
+    sonaAdaptation: new MetricCollector('sona_adaptation')
+  };
+
+  async collectMetrics(): Promise<PerformanceSnapshot> {
+    return {
+      timestamp: Date.now(),
+      flashAttention: await this.metrics.flashAttentionSpeedup.current(),
+      searchPerformance: await this.metrics.searchImprovement.current(),
+      memoryUsage: await this.metrics.memoryReduction.current(),
+      startup: await this.metrics.startupTime.current(),
+      sona: await this.metrics.sonaAdaptation.current(),
+      targets: this.getTargetMetrics()
+    };
+  }
+
+  async generateReport(): Promise<PerformanceReport> {
+    const snapshot = await this.collectMetrics();
+
+    return {
+      summary: this.generateSummary(snapshot),
+      achievements: this.checkAchievements(snapshot),
+      recommendations: this.generateRecommendations(snapshot),
+      trends: this.analyzeTrends(),
+      nextActions: this.suggestOptimizations()
+    };
+  }
+}
+```
+
+## Continuous Performance Validation
+
+### **Regression Detection**
+```typescript
+class PerformanceRegression {
+  async detectRegressions(): Promise<RegressionReport> {
+    const current = await this.runFullBenchmarkSuite();
+    const baseline = await this.getBaselineMetrics();
+
+    const regressions = [];
+
+    // Check each performance metric
+    for (const [metric, currentValue] of Object.entries(current)) {
+      const baselineValue = baseline[metric];
+      const change = (currentValue - baselineValue) / baselineValue;
+
+      if (change < -0.05) { // 5% regression threshold
+        regressions.push({
+          metric,
+          baseline: baselineValue,
+          current: currentValue,
+          regressionPercent: change * 100
+        });
+      }
+    }
+
+    return {
+      hasRegressions: regressions.length > 0,
+      regressions,
+      recommendations: this.generateRegressionFixes(regressions)
+    };
+  }
+}
+```
+
+## Success Validation Framework
+
+### **Target Achievement Checklist**
+- [ ] **Flash Attention**: 2.49x-7.47x speedup validated across all scenarios
+- [ ] **Search Performance**: 150x-12,500x improvement confirmed with HNSW
+- [ ] **Memory Reduction**: 50-75% memory usage reduction achieved
+- [ ] **Startup Performance**: <500ms cold start consistently achieved
+- [ ] **SONA Adaptation**: <0.05ms adaptation time validated
+- [ ] **15-Agent Coordination**: Efficient parallel execution confirmed
+- [ ] **Regression Testing**: No performance regressions detected
+
+### **Continuous Monitoring**
+- [ ] **Performance Dashboard**: Real-time metrics collection
+- [ ] **Alert System**: Automatic regression detection
+- [ ] **Trend Analysis**: Performance trend tracking over time
+- [ ] **Optimization Queue**: Prioritized performance improvement backlog
+
+## Coordination with V3 Team
+
+### **Memory Specialist (Agent #7)**
+- Validate AgentDB 150x-12,500x search improvements
+- Benchmark memory usage optimization
+- Test cross-agent memory sharing performance
+
+### **Integration Architect (Agent #10)**
+- Validate agentic-flow@alpha performance integration
+- Test Flash Attention speedup implementation
+- Benchmark SONA learning performance
+
+### **Queen Coordinator (Agent #1)**
+- Report performance milestones against 14-week timeline
+- Escalate performance blockers
+- Coordinate optimization priorities across all agents
+
+---
+
+**⚡ Mission**: Validate and achieve industry-leading performance improvements that make claude-flow v3 the fastest and most efficient agent orchestration platform.
@@ -0,0 +1,98 @@
+---
+name: v3-queen-coordinator
+version: "3.0.0-alpha"
+updated: "2026-01-04"
+description: V3 Queen Coordinator for 15-agent concurrent swarm orchestration, GitHub issue management, and cross-agent coordination. Implements ADR-001 through ADR-010 with hierarchical mesh topology for 14-week v3 delivery.
+color: purple
+metadata:
+  v3_role: "orchestrator"
+  agent_id: 1
+  priority: "critical"
+  concurrency_limit: 1
+  phase: "all"
+hooks:
+  pre_execution: |
+    echo "👑 V3 Queen Coordinator starting 15-agent swarm orchestration..."
+
+    # Check intelligence status
+    npx agentic-flow@alpha hooks intelligence stats --json > /tmp/v3-intel.json 2>/dev/null || echo '{"initialized":false}' > /tmp/v3-intel.json
+    echo "🧠 RuVector: $(cat /tmp/v3-intel.json | jq -r '.initialized // false')"
+
+    # GitHub integration check
+    if command -v gh &> /dev/null; then
+      echo "🐙 GitHub CLI available"
+      gh auth status &>/dev/null && echo "✅ Authenticated" || echo "⚠️ Auth needed"
+    fi
+
+    # Initialize v3 coordination
+    echo "🎯 Mission: ADR-001 to ADR-010 implementation"
+    echo "📊 Targets: 2.49x-7.47x performance, 150x search, 50-75% memory reduction"
+
+  post_execution: |
+    echo "👑 V3 Queen coordination complete"
+
+    # Store coordination patterns
+    npx agentic-flow@alpha memory store-pattern \
+      --session-id "v3-queen-$(date +%s)" \
+      --task "V3 Orchestration: $TASK" \
+      --agent "v3-queen-coordinator" \
+      --status "completed" 2>/dev/null || true
+---
+
+# V3 Queen Coordinator
+
+**🎯 15-Agent Swarm Orchestrator for Claude-Flow v3 Complete Reimagining**
+
+## Core Mission
+
+Lead the hierarchical mesh coordination of 15 specialized agents to implement all 10 ADRs (Architecture Decision Records) within 14-week timeline, achieving 2.49x-7.47x performance improvements.
+
+## Agent Topology
+
+```
+                    👑 QUEEN COORDINATOR
+                         (Agent #1)
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                   │                    │
+   🛡️ SECURITY         🧠 CORE              🔗 INTEGRATION
+   (Agents #2-4)       (Agents #5-9)        (Agents #10-12)
+        │                   │                    │
+        └────────────────────┼────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                   │                    │
+   🧪 QUALITY          ⚡ PERFORMANCE        🚀 DEPLOYMENT
+   (Agent #13)         (Agent #14)          (Agent #15)
+```
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1-2)
+- **Agents #2-4**: Security architecture, CVE remediation, security testing
+- **Agents #5-6**: Core architecture DDD design, type modernization
+
+### Phase 2: Core Systems (Week 3-6)
+- **Agent #7**: Memory unification (AgentDB 150x improvement)
+- **Agent #8**: Swarm coordination (merge 4 systems)
+- **Agent #9**: MCP server optimization
+- **Agent #13**: TDD London School implementation
+
+### Phase 3: Integration (Week 7-10)
+- **Agent #10**: agentic-flow@alpha deep integration
+- **Agent #11**: CLI modernization + hooks
+- **Agent #12**: Neural/SONA integration
+- **Agent #14**: Performance benchmarking
+
+### Phase 4: Release (Week 11-14)
+- **Agent #15**: Deployment + v3.0.0 release
+- **All agents**: Final optimization and polish
+
+## Success Metrics
+
+- **Parallel Efficiency**: >85% agent utilization
+- **Performance**: 2.49x-7.47x Flash Attention speedup
+- **Search**: 150x-12,500x AgentDB improvement
+- **Memory**: 50-75% reduction
+- **Code**: <5,000 lines (vs 15,000+)
+- **Timeline**: 14-week delivery
@@ -0,0 +1,174 @@
+---
+name: v3-security-architect
+version: "3.0.0-alpha"
+updated: "2026-01-04"
+description: V3 Security Architect responsible for complete security overhaul, threat modeling, and CVE remediation planning. Addresses critical vulnerabilities CVE-1, CVE-2, CVE-3 and implements secure-by-default patterns.
+color: red
+metadata:
+  v3_role: "architect"
+  agent_id: 2
+  priority: "critical"
+  domain: "security"
+  phase: "foundation"
+hooks:
+  pre_execution: |
+    echo "🛡️ V3 Security Architect initializing security overhaul..."
+
+    # Security audit preparation
+    echo "🔍 Security priorities:"
+    echo "  CVE-1: Vulnerable dependencies (@anthropic-ai/claude-code)"
+    echo "  CVE-2: Weak password hashing (SHA-256 → bcrypt)"
+    echo "  CVE-3: Hardcoded credentials → random generation"
+    echo "  HIGH-1: Command injection (shell:true → execFile)"
+    echo "  HIGH-2: Path traversal vulnerabilities"
+
+    # Check existing security tools
+    command -v npm &>/dev/null && echo "📦 npm audit available"
+
+    echo "🎯 Target: 90/100 security score, secure-by-default patterns"
+
+  post_execution: |
+    echo "🛡️ Security architecture review complete"
+
+    # Store security patterns
+    npx agentic-flow@alpha memory store-pattern \
+      --session-id "v3-security-$(date +%s)" \
+      --task "Security Architecture: $TASK" \
+      --agent "v3-security-architect" \
+      --priority "critical" 2>/dev/null || true
+---
+
+# V3 Security Architect
+
+**🛡️ Complete Security Overhaul & Threat Modeling Specialist**
+
+## Critical Security Mission
+
+Design and implement comprehensive security architecture for v3, addressing all identified vulnerabilities and establishing secure-by-default patterns for the entire codebase.
+
+## Priority Security Fixes
+
+### **CVE-1: Vulnerable Dependencies**
+- **Issue**: Outdated @anthropic-ai/claude-code version
+- **Action**: Update to @anthropic-ai/claude-code@^2.0.31
+- **Files**: package.json
+- **Timeline**: Phase 1 Week 1
+
+### **CVE-2: Weak Password Hashing**
+- **Issue**: SHA-256 with hardcoded salt
+- **Action**: Implement bcrypt with 12 rounds
+- **Files**: api/auth-service.ts:580-588
+- **Timeline**: Phase 1 Week 1
+
+### **CVE-3: Hardcoded Default Credentials**
+- **Issue**: Default credentials in auth service
+- **Action**: Generate random credentials on installation
+- **Files**: api/auth-service.ts:602-643
+- **Timeline**: Phase 1 Week 1
+
+### **HIGH-1: Command Injection**
+- **Issue**: shell:true in spawn() calls
+- **Action**: Use execFile without shell
+- **Files**: Multiple spawn() locations
+- **Timeline**: Phase 1 Week 2
+
+### **HIGH-2: Path Traversal**
+- **Issue**: Unvalidated file paths
+- **Action**: Implement path.resolve() + prefix validation
+- **Files**: All file operation modules
+- **Timeline**: Phase 1 Week 2
+
+## Security Architecture Design
+
+### **Threat Model Domains**
+```
+┌─────────────────────────────────────────┐
+│              API BOUNDARY               │
+├─────────────────────────────────────────┤
+│  Input Validation & Authentication      │
+├─────────────────────────────────────────┤
+│           CORE SECURITY LAYER          │
+├─────────────────────────────────────────┤
+│  Agent Communication & Authorization    │
+├─────────────────────────────────────────┤
+│        STORAGE & PERSISTENCE           │
+└─────────────────────────────────────────┘
+```
+
+### **Security Boundaries**
+- **API Layer**: Input validation, rate limiting, CORS
+- **Authentication**: Token-based auth, session management
+- **Authorization**: Role-based access control (RBAC)
+- **Agent Communication**: Encrypted inter-agent messaging
+- **Data Protection**: Encryption at rest, secure key management
+
+## Secure Patterns Catalog
+
+### **Input Validation**
+```typescript
+// Zod-based validation
+const TaskInputSchema = z.object({
+  taskId: z.string().uuid(),
+  content: z.string().max(10000),
+  agentType: z.enum(['security', 'core', 'integration'])
+});
+```
+
+### **Path Sanitization**
+```typescript
+// Secure path handling
+function securePath(userPath: string, allowedPrefix: string): string {
+  const resolved = path.resolve(allowedPrefix, userPath);
+  if (!resolved.startsWith(path.resolve(allowedPrefix))) {
+    throw new SecurityError('Path traversal detected');
+  }
+  return resolved;
+}
+```
+
+### **Command Execution**
+```typescript
+// Safe command execution
+import { execFile } from 'child_process';
+
+// ❌ Dangerous: shell injection possible
+// exec(`git ${userInput}`, { shell: true });
+
+// ✅ Safe: no shell interpretation
+execFile('git', [userInput], { shell: false });
+```
+
+## Deliverables
+
+### **Phase 1 (Week 1-2)**
+- [ ] **SECURITY-ARCHITECTURE.md** - Complete threat model
+- [ ] **CVE-REMEDIATION-PLAN.md** - Detailed fix timeline
+- [ ] **SECURE-PATTERNS.md** - Reusable security patterns
+- [ ] **THREAT-MODEL.md** - Attack surface analysis
+
+### **Validation Criteria**
+- [ ] All CVEs addressed with tested fixes
+- [ ] npm audit shows 0 high/critical vulnerabilities
+- [ ] Security patterns documented and implemented
+- [ ] Threat model covers all v3 domains
+- [ ] Security testing framework established
+
+## Coordination with Security Team
+
+### **Security Implementer (Agent #3)**
+- Provide detailed implementation specifications
+- Review all security-critical code changes
+- Validate CVE remediation implementations
+
+### **Security Tester (Agent #4)**
+- Supply test specifications for security patterns
+- Define penetration testing requirements
+- Establish security regression test suite
+
+## Success Metrics
+
+- **Security Score**: 90/100 (npm audit + custom scans)
+- **CVE Resolution**: 100% of identified CVEs fixed
+- **Test Coverage**: >95% for security-critical code
+- **Documentation**: Complete security architecture docs
+- **Timeline**: All deliverables within Phase 1
@@ -0,0 +1,266 @@
+{
+  "v3DependencyOptimization": {
+    "version": "3.0.0",
+    "strategy": "enhanced_parallelism",
+    "description": "Optimized dependency chain for maximum parallel execution efficiency",
+
+    "originalDependencies": {
+      "description": "Current dependency chain with blocking issues",
+      "issues": [
+        "Some agents wait unnecessarily for unrelated dependencies",
+        "Phase boundaries too rigid, reducing parallelism",
+        "Agent #11 and #12 have excessive blocking dependencies"
+      ]
+    },
+
+    "optimizedDependencies": {
+      "description": "Enhanced parallel execution with reduced blocking",
+
+      "phases": {
+        "phase1_enhanced": {
+          "name": "Enhanced Foundation (Weeks 1-3)",
+          "description": "Increased parallelism in foundation phase",
+          "parallel_groups": [
+            {
+              "group": "security_foundation",
+              "agents": [2, 3, 4],
+              "dependencies": [],
+              "description": "Security agents run in full parallel",
+              "estimated_duration": "2 weeks"
+            },
+            {
+              "group": "core_architecture",
+              "agents": [5],
+              "dependencies": [],
+              "description": "Core architect starts immediately with security",
+              "estimated_duration": "1 week"
+            },
+            {
+              "group": "testing_foundation",
+              "agents": [13],
+              "dependencies": [],
+              "description": "TDD engineer starts early for framework setup",
+              "estimated_duration": "1 week"
+            },
+            {
+              "group": "performance_setup",
+              "agents": [14],
+              "dependencies": [],
+              "description": "Performance engineer starts benchmark setup",
+              "estimated_duration": "1 week"
+            }
+          ]
+        },
+
+        "phase2_enhanced": {
+          "name": "Enhanced Core Systems (Weeks 2-6)",
+          "description": "Overlapped execution with phase 1",
+          "parallel_groups": [
+            {
+              "group": "core_implementation",
+              "agents": [6, 7, 8],
+              "dependencies": [5],
+              "description": "Core implementation agents start after architect",
+              "estimated_duration": "3 weeks"
+            },
+            {
+              "group": "mcp_optimization",
+              "agents": [9],
+              "dependencies": [5],
+              "description": "MCP specialist works in parallel with core",
+              "estimated_duration": "2 weeks"
+            },
+            {
+              "group": "queen_coordination",
+              "agents": [1],
+              "dependencies": [2, 5],
+              "description": "Queen starts once security baseline + architecture ready",
+              "estimated_duration": "4 weeks"
+            }
+          ]
+        },
+
+        "phase3_enhanced": {
+          "name": "Enhanced Integration (Weeks 5-9)",
+          "description": "Reduced blocking dependencies for integration agents",
+          "parallel_groups": [
+            {
+              "group": "integration_core",
+              "agents": [10],
+              "dependencies": [5, 7],
+              "description": "Integration architect needs only core arch + memory",
+              "estimated_duration": "3 weeks"
+            },
+            {
+              "group": "cli_modernization",
+              "agents": [11],
+              "dependencies": [5],
+              "description": "CLI developer needs only core architecture (reduced from [5,10])",
+              "estimated_duration": "2 weeks"
+            },
+            {
+              "group": "neural_learning",
+              "agents": [12],
+              "dependencies": [5],
+              "description": "Neural developer needs only core architecture (reduced from [7,10])",
+              "estimated_duration": "2 weeks"
+            }
+          ]
+        },
+
+        "phase4_enhanced": {
+          "name": "Enhanced Polish & Release (Weeks 9-16)",
+          "description": "Final optimization with all agents active",
+          "parallel_groups": [
+            {
+              "group": "release_preparation",
+              "agents": [15],
+              "dependencies": [13, 14],
+              "description": "Release engineer waits for testing + performance validation",
+              "estimated_duration": "2 weeks"
+            },
+            {
+              "group": "final_optimization",
+              "agents": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
+              "dependencies": [],
+              "description": "All agents perform final optimization in parallel",
+              "estimated_duration": "1 week"
+            }
+          ]
+        }
+      }
+    },
+
+    "reducedBlockingDependencies": {
+      "description": "Specific dependency reductions to enable better parallelism",
+      "changes": [
+        {
+          "agent": "cli-hooks-developer (11)",
+          "original_dependencies": [5, 10],
+          "optimized_dependencies": [5],
+          "rationale": "CLI can be modernized with just core architecture, integration can happen later",
+          "parallel_gain": "Can start 2 weeks earlier"
+        },
+        {
+          "agent": "neural-learning-developer (12)",
+          "original_dependencies": [7, 10],
+          "optimized_dependencies": [5],
+          "rationale": "Neural learning can start with core architecture, memory/integration can be added incrementally",
+          "parallel_gain": "Can start 3 weeks earlier"
+        },
+        {
+          "agent": "queen-coordinator (1)",
+          "original_dependencies": [],
+          "optimized_dependencies": [2, 5],
+          "rationale": "Queen should wait for security baseline and core architecture before orchestrating",
+          "coordination_benefit": "More intelligent coordination with foundation in place"
+        }
+      ]
+    },
+
+    "phaseBoundaryOptimization": {
+      "description": "Flexible phase boundaries to maximize parallel efficiency",
+      "strategy": "overlapping_phases",
+      "rules": {
+        "phase_overlap": "50%",
+        "description": "Phases can overlap by 50% once foundation requirements are met",
+        "example": "Phase 2 core systems can start in week 2 while Phase 1 security continues"
+      },
+
+      "flexibility_rules": [
+        {
+          "condition": "Agent dependencies satisfied",
+          "action": "Allow early phase advancement",
+          "benefit": "Maximize parallel agent utilization"
+        },
+        {
+          "condition": "Critical path agents complete",
+          "action": "Start next phase critical agents early",
+          "benefit": "Reduce overall timeline"
+        },
+        {
+          "condition": "Blocking issues detected",
+          "action": "Reassign free agents to unblocked work",
+          "benefit": "Maintain productivity during blocks"
+        }
+      ]
+    },
+
+    "parallelEfficiencyTargets": {
+      "phase1": {
+        "agent_utilization": "85%",
+        "parallel_agents": "4-6 concurrent",
+        "timeline_efficiency": "20% improvement"
+      },
+      "phase2": {
+        "agent_utilization": "90%",
+        "parallel_agents": "6-8 concurrent",
+        "timeline_efficiency": "25% improvement"
+      },
+      "phase3": {
+        "agent_utilization": "95%",
+        "parallel_agents": "8-12 concurrent",
+        "timeline_efficiency": "30% improvement"
+      },
+      "phase4": {
+        "agent_utilization": "100%",
+        "parallel_agents": "15 concurrent",
+        "timeline_efficiency": "Maximum parallel execution"
+      }
+    },
+
+    "riskMitigation": {
+      "description": "Risk management for optimized dependency chain",
+      "strategies": [
+        {
+          "risk": "Early agent starts without sufficient foundation",
+          "mitigation": "Minimum viable dependencies enforced",
+          "monitoring": "Regular dependency satisfaction checks"
+        },
+        {
+          "risk": "Coordination overhead with more parallel agents",
+          "mitigation": "Queen coordinator with enhanced GitHub integration",
+          "monitoring": "Agent coordination latency tracking"
+        },
+        {
+          "risk": "Integration complexity with reduced dependencies",
+          "mitigation": "Incremental integration approach",
+          "monitoring": "Integration test coverage requirements"
+        }
+      ]
+    },
+
+    "implementation": {
+      "tooling": {
+        "dependency_tracker": "GitHub project boards with agent assignments",
+        "parallel_monitor": "Real-time agent utilization dashboard",
+        "coordination": "Queen coordinator with MCP orchestration tools"
+      },
+
+      "coordination_patterns": {
+        "daily_standups": "Agent status and dependency updates",
+        "blocker_resolution": "Immediate reassignment protocols",
+        "phase_transitions": "Gradual transition with readiness checks"
+      }
+    },
+
+    "success_metrics": {
+      "efficiency": {
+        "target": "90% average agent utilization",
+        "measurement": "Time agents spend on productive work vs waiting"
+      },
+      "timeline": {
+        "target": "16 weeks total (vs 20 weeks with original dependencies)",
+        "measurement": "Overall project completion time"
+      },
+      "coordination": {
+        "target": "<4 hours average blocker resolution time",
+        "measurement": "Time from blocker identification to resolution"
+      },
+      "quality": {
+        "target": "No degradation in output quality due to rushed dependencies",
+        "measurement": "Test coverage and review completion rates"
+      }
+    }
+  }
+}
@@ -0,0 +1,251 @@
+{
+  "v3PerformanceTargets": {
+    "version": "3.0.0",
+    "strategy": "phased_rollout",
+    "totalPhases": 4,
+    "riskMitigation": "progressive_targets",
+
+    "phases": {
+      "phase1": {
+        "name": "Security Foundation",
+        "duration": "weeks 1-3",
+        "description": "Conservative targets while establishing security baseline",
+        "targets": {
+          "flashAttention": {
+            "target": "2.49x minimum",
+            "description": "Conservative start, focus on stability",
+            "measurement": "baseline vs flash attention speedup",
+            "priority": "medium"
+          },
+          "searchImprovement": {
+            "target": "150x minimum",
+            "description": "Basic HNSW implementation",
+            "measurement": "vector search latency improvement",
+            "priority": "high"
+          },
+          "memoryReduction": {
+            "target": "40%",
+            "description": "Initial optimization, achievable target",
+            "measurement": "heap usage reduction",
+            "priority": "medium"
+          },
+          "startupTime": {
+            "target": "<750ms",
+            "description": "Less aggressive than final target",
+            "measurement": "CLI cold start time",
+            "priority": "high"
+          },
+          "securityScore": {
+            "target": "75/100",
+            "description": "Significant security improvement",
+            "measurement": "npm audit + custom security scans",
+            "priority": "critical"
+          }
+        },
+        "gates": {
+          "required": ["securityScore", "startupTime"],
+          "optional": ["flashAttention", "memoryReduction"]
+        }
+      },
+
+      "phase2": {
+        "name": "Core Systems Optimization",
+        "duration": "weeks 4-8",
+        "description": "Mid-range targets with core system optimizations",
+        "targets": {
+          "flashAttention": {
+            "target": "3.5x - 5.0x",
+            "description": "Mid-range optimization",
+            "measurement": "sequence processing speedup",
+            "priority": "high"
+          },
+          "searchImprovement": {
+            "target": "500x - 2000x",
+            "description": "Optimized HNSW with tuning",
+            "measurement": "vector search performance",
+            "priority": "high"
+          },
+          "memoryReduction": {
+            "target": "50%",
+            "description": "Enhanced optimization techniques",
+            "measurement": "memory usage efficiency",
+            "priority": "medium"
+          },
+          "startupTime": {
+            "target": "<500ms",
+            "description": "Target achieved with optimization",
+            "measurement": "CLI startup latency",
+            "priority": "high"
+          },
+          "swarmCoordination": {
+            "target": "<100ms",
+            "description": "15-agent coordination latency",
+            "measurement": "swarm consensus time",
+            "priority": "high"
+          },
+          "agentSpawnTime": {
+            "target": "<200ms",
+            "description": "Individual agent spawn latency",
+            "measurement": "agent initialization time",
+            "priority": "medium"
+          }
+        },
+        "gates": {
+          "required": ["flashAttention", "searchImprovement", "startupTime"],
+          "optional": ["swarmCoordination", "agentSpawnTime"]
+        }
+      },
+
+      "phase3": {
+        "name": "Integration Excellence",
+        "duration": "weeks 9-12",
+        "description": "High-performance targets with full integration",
+        "targets": {
+          "flashAttention": {
+            "target": "5.0x - 7.47x",
+            "description": "Near-maximum optimization",
+            "measurement": "attention mechanism performance",
+            "priority": "high"
+          },
+          "searchImprovement": {
+            "target": "2000x - 12,500x",
+            "description": "Maximum performance achieved",
+            "measurement": "vector database performance",
+            "priority": "high"
+          },
+          "memoryReduction": {
+            "target": "65%",
+            "description": "Advanced compression techniques",
+            "measurement": "overall memory efficiency",
+            "priority": "medium"
+          },
+          "startupTime": {
+            "target": "<350ms",
+            "description": "Excellence target achieved",
+            "measurement": "optimized CLI performance",
+            "priority": "medium"
+          },
+          "mcpResponseTime": {
+            "target": "<100ms p95",
+            "description": "MCP server optimization",
+            "measurement": "MCP tool execution latency",
+            "priority": "high"
+          },
+          "learningAdaptation": {
+            "target": "<0.05ms",
+            "description": "SONA micro-LoRA adaptation",
+            "measurement": "learning cycle latency",
+            "priority": "medium"
+          }
+        },
+        "gates": {
+          "required": ["flashAttention", "searchImprovement", "mcpResponseTime"],
+          "optional": ["memoryReduction", "learningAdaptation"]
+        }
+      },
+
+      "phase4": {
+        "name": "Excellence & Polish",
+        "duration": "weeks 13-16",
+        "description": "Stretch targets and final optimization",
+        "targets": {
+          "flashAttention": {
+            "target": "7.47x",
+            "description": "Maximum theoretical speedup",
+            "measurement": "peak attention performance",
+            "priority": "stretch"
+          },
+          "searchImprovement": {
+            "target": "12,500x",
+            "description": "Peak HNSW performance",
+            "measurement": "optimal vector search",
+            "priority": "stretch"
+          },
+          "memoryReduction": {
+            "target": "75%",
+            "description": "Maximum memory efficiency",
+            "measurement": "peak memory optimization",
+            "priority": "stretch"
+          },
+          "startupTime": {
+            "target": "<300ms",
+            "description": "Sub-300ms cold start",
+            "measurement": "peak startup performance",
+            "priority": "stretch"
+          },
+          "overallThroughput": {
+            "target": "10x",
+            "description": "Overall system throughput",
+            "measurement": "end-to-end performance",
+            "priority": "high"
+          },
+          "reliabilityScore": {
+            "target": "99.9%",
+            "description": "Three nines reliability",
+            "measurement": "system uptime and stability",
+            "priority": "high"
+          }
+        },
+        "gates": {
+          "required": ["overallThroughput", "reliabilityScore"],
+          "optional": ["flashAttention", "searchImprovement", "memoryReduction"]
+        }
+      }
+    },
+
+    "monitoring": {
+      "frequency": "continuous",
+      "alerting": {
+        "regressionThreshold": "10%",
+        "criticalThreshold": "25%",
+        "notificationChannels": ["console", "metrics"]
+      },
+      "benchmarks": {
+        "automated": true,
+        "schedule": "daily",
+        "regressionDetection": true
+      }
+    },
+
+    "rollbackTriggers": [
+      "Security score drops below 70/100",
+      "Startup time exceeds 1000ms",
+      "Memory usage increases by >50%",
+      "Critical functionality broken",
+      "Performance regression >25%"
+    ],
+
+    "success_metrics": {
+      "phase1_success": {
+        "security_baseline": "Achieved 75/100 security score",
+        "stability": "No critical regressions",
+        "performance": "Baseline improvements established"
+      },
+      "phase2_success": {
+        "performance": "Mid-range targets achieved",
+        "coordination": "15-agent swarm operational",
+        "optimization": "Core systems optimized"
+      },
+      "phase3_success": {
+        "integration": "agentic-flow integration complete",
+        "performance": "High-performance targets met",
+        "features": "All v3 features operational"
+      },
+      "phase4_success": {
+        "excellence": "Stretch targets achieved where possible",
+        "reliability": "Production-ready stability",
+        "optimization": "Peak performance validated"
+      }
+    },
+
+    "adaptive_strategy": {
+      "enabled": true,
+      "description": "Targets adjust based on actual achievement rates",
+      "rules": {
+        "if_ahead_of_schedule": "Attempt next phase targets early",
+        "if_behind_schedule": "Focus on required gates, defer optional",
+        "if_critical_issues": "Halt advancement, focus on resolution"
+      }
+    }
+  }
+}
@@ -0,0 +1,97 @@
+# Claude Flow V3 Helpers
+
+This directory contains helper scripts and utilities for V3 development.
+
+## 🚀 Quick Start
+
+```bash
+# Initialize V3 development environment
+.claude/helpers/v3.sh init
+
+# Quick status check
+.claude/helpers/v3.sh status
+
+# Update progress metrics
+.claude/helpers/v3.sh update domain 3
+.claude/helpers/v3.sh update agent 8
+.claude/helpers/v3.sh update security 2
+```
+
+## Available Helpers
+
+### 🎛️ V3 Master Tool
+- **`v3.sh`** - Main command-line interface for all V3 operations
+  ```bash
+  .claude/helpers/v3.sh help           # Show all commands
+  .claude/helpers/v3.sh status         # Quick development status
+  .claude/helpers/v3.sh update domain 3 # Update specific metrics
+  .claude/helpers/v3.sh validate       # Validate configuration
+  .claude/helpers/v3.sh full-status    # Complete status overview
+  ```
+
+### 📊 V3 Progress Management
+- **`update-v3-progress.sh`** - Update V3 development metrics
+  ```bash
+  # Usage examples:
+  .claude/helpers/update-v3-progress.sh domain 3      # Mark 3 domains complete
+  .claude/helpers/update-v3-progress.sh agent 8       # 8 agents active
+  .claude/helpers/update-v3-progress.sh security 2    # 2 CVEs fixed
+  .claude/helpers/update-v3-progress.sh performance 2.5x # Performance boost
+  .claude/helpers/update-v3-progress.sh status        # Show current status
+  ```
+
+### 🔍 Configuration Validation
+- **`validate-v3-config.sh`** - Comprehensive environment validation
+  - Checks all required directories and files
+  - Validates JSON configuration files
+  - Verifies Node.js and development tools
+  - Confirms Git repository status
+  - Validates file permissions
+
+### ⚡ Quick Status
+- **`v3-quick-status.sh`** - Compact development progress overview
+  - Shows domain, agent, and DDD progress
+  - Displays security and performance metrics
+  - Color-coded status indicators
+  - Current Git branch information
+
+## Helper Script Standards
+
+### File Naming
+- Use kebab-case: `update-v3-progress.sh`
+- Include version prefix: `v3-*` for V3-specific helpers
+- Use descriptive names that indicate purpose
+
+### Script Requirements
+- Must be executable (`chmod +x`)
+- Include proper error handling (`set -e`)
+- Provide usage help when called without arguments
+- Use consistent exit codes (0 = success, non-zero = error)
+
+### Configuration Integration
+Helpers are configured in `.claude/settings.json`:
+```json
+{
+  "helpers": {
+    "directory": ".claude/helpers",
+    "enabled": true,
+    "v3ProgressUpdater": ".claude/helpers/update-v3-progress.sh"
+  }
+}
+```
+
+## Development Guidelines
+
+1. **Security First**: All helpers must validate inputs
+2. **Idempotent**: Scripts should be safe to run multiple times
+3. **Fast Execution**: Keep helper execution under 1 second when possible
+4. **Clear Output**: Provide clear success/error messages
+5. **JSON Safe**: When updating JSON files, use `jq` for safety
+
+## Adding New Helpers
+
+1. Create script in `.claude/helpers/`
+2. Make executable: `chmod +x script-name.sh`
+3. Add to settings.json helpers section
+4. Test thoroughly before committing
+5. Update this README with usage documentation
@@ -1,251 +1,250 @@
 #!/bin/bash
-# Claude Checkpoint Manager
-# Provides easy rollback and management of Claude Code checkpoints
+# V3 Checkpoint Manager - Automatic Git checkpointing and progress tracking

 set -e

-# Colors
+# Configuration
+CHECKPOINT_DIR=".claude-flow/checkpoints"
+METRICS_DIR=".claude-flow/metrics"
+AUTO_COMMIT_ENABLED=true
+MIN_CHANGES_THRESHOLD=1
+
+# Color codes
 RED='\033[0;31m'
 GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
+YELLOW='\033[0;33m'
 BLUE='\033[0;34m'
-NC='\033[0m' # No Color
+PURPLE='\033[0;35m'
+CYAN='\033[0;36m'
+RESET='\033[0m'

-# Configuration
-CHECKPOINT_DIR=".claude/checkpoints"
-BACKUP_DIR=".claude/backups"
+# Ensure checkpoint directory exists
+mkdir -p "$CHECKPOINT_DIR"

-# Help function
-show_help() {
-    cat << EOF
-Claude Checkpoint Manager
-========================
+# Helper functions
+log_info() {
+  echo -e "${BLUE}🔄 $1${RESET}" >&2
+}

-Usage: $0 <command> [options]
+log_success() {
+  echo -e "${GREEN}✅ $1${RESET}" >&2
+}

-Commands:
-  list              List all checkpoints
-  show <id>         Show details of a specific checkpoint
-  rollback <id>     Rollback to a specific checkpoint
-  diff <id>         Show diff since checkpoint
-  clean             Clean old checkpoints (older than 7 days)
-  summary           Show session summary
-  
-Options:
-  --hard            For rollback: use git reset --hard (destructive)
-  --soft            For rollback: use git reset --soft (default)
-  --branch          For rollback: create new branch from checkpoint
+log_warning() {
+  echo -e "${YELLOW}⚠️  $1${RESET}" >&2
+}

-Examples:
-  $0 list
-  $0 show checkpoint-20240130-143022
-  $0 rollback checkpoint-20240130-143022 --branch
-  $0 diff session-end-session-20240130-150000
+log_error() {
+  echo -e "${RED}❌ $1${RESET}" >&2
+}
+
+# Check if we're in a git repository
+check_git_repo() {
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    log_warning "Not in a git repository, skipping checkpoint"
+    exit 0
+  fi
+}
+
+# Check if there are enough changes to warrant a checkpoint
+check_changes_threshold() {
+  local changed_files=$(git status --porcelain 2>/dev/null | wc -l || echo 0)
+  if [ "$changed_files" -lt "$MIN_CHANGES_THRESHOLD" ]; then
+    log_info "Not enough changes for checkpoint ($changed_files < $MIN_CHANGES_THRESHOLD)"
+    return 1
+  fi
+  return 0
+}
+
+# Create checkpoint metadata
+create_checkpoint_metadata() {
+  local checkpoint_type="$1"
+  local message="$2"
+  local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  local commit_hash=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+
+  cat > "$CHECKPOINT_DIR/latest-checkpoint.json" <<EOF
+{
+  "timestamp": "$timestamp",
+  "type": "$checkpoint_type",
+  "message": "$message",
+  "commitHash": "$commit_hash",
+  "branch": "$(git branch --show-current 2>/dev/null || echo 'unknown')",
+  "v3Progress": $(cat "$METRICS_DIR/v3-progress.json" 2>/dev/null || echo '{}'),
+  "performance": $(cat "$METRICS_DIR/performance.json" 2>/dev/null || echo '{}'),
+  "security": $(cat "$METRICS_DIR/../security/audit-status.json" 2>/dev/null || echo '{}')
+}
 EOF
+
+  # Archive the checkpoint
+  local checkpoint_file="$CHECKPOINT_DIR/checkpoint-$(date +%Y%m%d-%H%M%S).json"
+  cp "$CHECKPOINT_DIR/latest-checkpoint.json" "$checkpoint_file"
+
+  log_success "Checkpoint metadata created: $checkpoint_file"
 }

-# List all checkpoints
-function list_checkpoints() {
-    echo -e "${BLUE}📋 Available Checkpoints:${NC}"
-    echo ""
-    
-    # List checkpoint tags
-    echo -e "${YELLOW}Git Tags:${NC}"
-    local tags=$(git tag -l 'checkpoint-*' -l 'session-end-*' -l 'task-*' --sort=-creatordate | head -20)
-    if [ -n "$tags" ]; then
-        echo "$tags"
-    else
-        echo "No checkpoint tags found"
-    fi
-    
-    echo ""
-    
-    # List checkpoint branches
-    echo -e "${YELLOW}Checkpoint Branches:${NC}"
-    local branches=$(git branch -a | grep "checkpoint/" | sed 's/^[ *]*//')
-    if [ -n "$branches" ]; then
-        echo "$branches"
-    else
-        echo "No checkpoint branches found"
-    fi
-    
-    echo ""
-    
-    # List checkpoint files
-    if [ -d "$CHECKPOINT_DIR" ]; then
-        echo -e "${YELLOW}Recent Checkpoint Files:${NC}"
-        find "$CHECKPOINT_DIR" -name "*.json" -type f -printf "%T@ %p\n" | \
-            sort -rn | head -10 | cut -d' ' -f2- | xargs -I {} basename {}
-    fi
+# Auto-commit changes if enabled
+auto_commit() {
+  local message="$1"
+
+  if [ "$AUTO_COMMIT_ENABLED" != "true" ]; then
+    log_info "Auto-commit disabled, skipping"
+    return 0
+  fi
+
+  # Check if there are changes to commit
+  if git diff --quiet && git diff --cached --quiet; then
+    log_info "No changes to commit"
+    return 0
+  fi
+
+  # Add all changes
+  git add . >/dev/null 2>&1 || true
+
+  # Create commit with enhanced message
+  local enhanced_message="$message
+
+🚀 Generated with [Claude Code](https://claude.com/claude-code)
+📊 V3 Development Progress Checkpoint
+
+Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>"
+
+  if git commit -m "$enhanced_message" >/dev/null 2>&1; then
+    local commit_hash=$(git rev-parse HEAD)
+    log_success "Auto-commit created: ${commit_hash:0:7}"
+  else
+    log_info "No changes to commit or commit failed"
+  fi
 }

-# Show checkpoint details
-function show_checkpoint() {
-    local checkpoint_id="$1"
-    
-    echo -e "${BLUE}📍 Checkpoint Details: $checkpoint_id${NC}"
-    echo ""
-    
-    # Check if it's a tag
-    if git tag -l "$checkpoint_id" | grep -q "$checkpoint_id"; then
-        echo -e "${YELLOW}Type:${NC} Git Tag"
-        echo -e "${YELLOW}Commit:${NC} $(git rev-list -n 1 "$checkpoint_id")"
-        echo -e "${YELLOW}Date:${NC} $(git log -1 --format=%ai "$checkpoint_id")"
-        echo -e "${YELLOW}Message:${NC}"
-        git log -1 --format=%B "$checkpoint_id" | sed 's/^/  /'
-        echo ""
-        echo -e "${YELLOW}Files changed:${NC}"
-        git diff-tree --no-commit-id --name-status -r "$checkpoint_id" | sed 's/^/  /'
-    # Check if it's a branch
-    elif git branch -a | grep -q "$checkpoint_id"; then
-        echo -e "${YELLOW}Type:${NC} Git Branch"
-        echo -e "${YELLOW}Latest commit:${NC}"
-        git log -1 --oneline "$checkpoint_id"
-    else
-        echo -e "${RED}❌ Checkpoint not found: $checkpoint_id${NC}"
-        exit 1
-    fi
-}
+# Main checkpoint function
+create_checkpoint() {
+  local checkpoint_type="$1"
+  local message="$2"

-# Rollback to checkpoint
-function rollback_checkpoint() {
-    local checkpoint_id="$1"
-    local mode="$2"
-    
-    echo -e "${YELLOW}🔄 Rolling back to checkpoint: $checkpoint_id${NC}"
-    echo ""
-    
-    # Verify checkpoint exists
-    if ! git tag -l "$checkpoint_id" | grep -q "$checkpoint_id" && \
-       ! git branch -a | grep -q "$checkpoint_id"; then
-        echo -e "${RED}❌ Checkpoint not found: $checkpoint_id${NC}"
-        exit 1
-    fi
-    
-    # Create backup before rollback
-    local backup_name="backup-$(date +%Y%m%d-%H%M%S)"
-    echo "Creating backup: $backup_name"
-    git tag "$backup_name" -m "Backup before rollback to $checkpoint_id"
-    
-    case "$mode" in
-        "--hard")
-            echo -e "${RED}⚠️  Performing hard reset (destructive)${NC}"
-            git reset --hard "$checkpoint_id"
-            echo -e "${GREEN}✅ Rolled back to $checkpoint_id (hard reset)${NC}"
-            ;;
-        "--branch")
-            local branch_name="rollback-$checkpoint_id-$(date +%Y%m%d-%H%M%S)"
-            echo "Creating new branch: $branch_name"
-            git checkout -b "$branch_name" "$checkpoint_id"
-            echo -e "${GREEN}✅ Created branch $branch_name from $checkpoint_id${NC}"
-            ;;
-        "--stash"|*)
-            echo "Stashing current changes..."
-            git stash push -m "Stash before rollback to $checkpoint_id"
-            git reset --soft "$checkpoint_id"
-            echo -e "${GREEN}✅ Rolled back to $checkpoint_id (soft reset)${NC}"
-            echo "Your changes are stashed. Use 'git stash pop' to restore them."
-            ;;
-    esac
-}
+  check_git_repo

-# Show diff since checkpoint
-function diff_checkpoint() {
-    local checkpoint_id="$1"
-    
-    echo -e "${BLUE}📊 Changes since checkpoint: $checkpoint_id${NC}"
-    echo ""
-    
-    if git tag -l "$checkpoint_id" | grep -q "$checkpoint_id"; then
-        git diff "$checkpoint_id"
-    elif git branch -a | grep -q "$checkpoint_id"; then
-        git diff "$checkpoint_id"
-    else
-        echo -e "${RED}❌ Checkpoint not found: $checkpoint_id${NC}"
-        exit 1
-    fi
-}
+  case "$checkpoint_type" in
+    "auto-checkpoint")
+      if check_changes_threshold; then
+        log_info "Creating auto-checkpoint: $message"
+        create_checkpoint_metadata "$checkpoint_type" "$message"
+        auto_commit "checkpoint: $message"
+      fi
+      ;;

-# Clean old checkpoints
-function clean_checkpoints() {
-    local days=${1:-7}
-    
-    echo -e "${YELLOW}🧹 Cleaning checkpoints older than $days days...${NC}"
-    echo ""
-    
-    # Clean old checkpoint files
-    if [ -d "$CHECKPOINT_DIR" ]; then
-        find "$CHECKPOINT_DIR" -name "*.json" -type f -mtime +$days -delete
-        echo "✅ Cleaned old checkpoint files"
-    fi
-    
-    # List old tags (but don't delete automatically)
-    echo ""
-    echo "Old checkpoint tags (manual deletion required):"
-    git tag -l 'checkpoint-*' --sort=-creatordate | tail -n +50 || echo "No old tags found"
-}
+    "agent-checkpoint")
+      log_info "Creating agent checkpoint: $message"
+      create_checkpoint_metadata "$checkpoint_type" "$message"
+      auto_commit "feat(agent): $message"
+      ;;

-# Show session summary
-function show_summary() {
-    echo -e "${BLUE}📊 Session Summary${NC}"
-    echo ""
-    
-    # Find most recent session summary
-    if [ -d "$CHECKPOINT_DIR" ]; then
-        local latest_summary=$(find "$CHECKPOINT_DIR" -name "summary-*.md" -type f -printf "%T@ %p\n" | \
-            sort -rn | head -1 | cut -d' ' -f2-)
-        
-        if [ -n "$latest_summary" ]; then
-            echo -e "${YELLOW}Latest session summary:${NC}"
-            cat "$latest_summary"
-        else
-            echo "No session summaries found"
-        fi
-    fi
-}
+    "domain-checkpoint")
+      log_info "Creating domain checkpoint: $message"
+      create_checkpoint_metadata "$checkpoint_type" "$message"
+      auto_commit "feat(domain): $message"
+      ;;
+
+    "security-checkpoint")
+      log_info "Creating security checkpoint: $message"
+      create_checkpoint_metadata "$checkpoint_type" "$message"
+      auto_commit "security: $message"
+      ;;
+
+    "performance-checkpoint")
+      log_info "Creating performance checkpoint: $message"
+      create_checkpoint_metadata "$checkpoint_type" "$message"
+      auto_commit "perf: $message"
+      ;;
+
+    "session-end")
+      log_info "Creating session-end checkpoint"
+      create_checkpoint_metadata "$checkpoint_type" "$message"
+      auto_commit "checkpoint: session completed - $message"
+
+      # Generate session summary
+      if [ -f "$METRICS_DIR/v3-progress.json" ]; then
+        local domains=$(jq -r '.domains.completed // 0' "$METRICS_DIR/v3-progress.json")
+        local agents=$(jq -r '.swarm.activeAgents // 0' "$METRICS_DIR/v3-progress.json")
+        local ddd=$(jq -r '.ddd.progress // 0' "$METRICS_DIR/v3-progress.json")
+
+        echo "📊 Session Summary: $domains/5 domains, $agents/15 agents, $ddd% DDD progress" > "$CHECKPOINT_DIR/last-session-summary.txt"
+      fi
+      ;;
+
+    "milestone-checkpoint")
+      log_info "Creating milestone checkpoint: $message"
+      create_checkpoint_metadata "$checkpoint_type" "$message"
+      auto_commit "milestone: $message"
+      ;;

-# Main command handling
-case "$1" in
-    list)
-        list_checkpoints
-        ;;
-    show)
-        if [ -z "$2" ]; then
-            echo -e "${RED}Error: Please specify a checkpoint ID${NC}"
-            show_help
-            exit 1
-        fi
-        show_checkpoint "$2"
-        ;;
-    rollback)
-        if [ -z "$2" ]; then
-            echo -e "${RED}Error: Please specify a checkpoint ID${NC}"
-            show_help
-            exit 1
-        fi
-        rollback_checkpoint "$2" "$3"
-        ;;
-    diff)
-        if [ -z "$2" ]; then
-            echo -e "${RED}Error: Please specify a checkpoint ID${NC}"
-            show_help
-            exit 1
-        fi
-        diff_checkpoint "$2"
-        ;;
-    clean)
-        clean_checkpoints "$2"
-        ;;
-    summary)
-        show_summary
-        ;;
-    help|--help|-h)
-        show_help
-        ;;
    *)
-        echo -e "${RED}Error: Unknown command: $1${NC}"
-        echo ""
-        show_help
-        exit 1
-        ;;
-esac
+      log_error "Unknown checkpoint type: $checkpoint_type"
+      exit 1
+      ;;
+  esac
+}
+
+# Show checkpoint history
+show_history() {
+  echo -e "${PURPLE}📚 Recent Checkpoints${RESET}"
+  echo "===================="
+
+  if [ ! -d "$CHECKPOINT_DIR" ] || [ -z "$(ls -A "$CHECKPOINT_DIR"/*.json 2>/dev/null)" ]; then
+    echo "No checkpoints found"
+    return
+  fi
+
+  for checkpoint in $(ls -t "$CHECKPOINT_DIR"/checkpoint-*.json 2>/dev/null | head -5); do
+    local timestamp=$(jq -r '.timestamp' "$checkpoint" 2>/dev/null || echo "unknown")
+    local type=$(jq -r '.type' "$checkpoint" 2>/dev/null || echo "unknown")
+    local message=$(jq -r '.message' "$checkpoint" 2>/dev/null || echo "unknown")
+    local commit=$(jq -r '.commitHash' "$checkpoint" 2>/dev/null | cut -c1-7 || echo "unknown")
+
+    echo -e "${CYAN}$timestamp${RESET} [$type] $message (${commit})"
+  done
+}
+
+# Main script logic
+case "$1" in
+  "auto-checkpoint"|"agent-checkpoint"|"domain-checkpoint"|"security-checkpoint"|"performance-checkpoint"|"session-end"|"milestone-checkpoint")
+    create_checkpoint "$1" "${2:-Auto checkpoint}"
+    ;;
+
+  "history")
+    show_history
+    ;;
+
+  "status")
+    if [ -f "$CHECKPOINT_DIR/latest-checkpoint.json" ]; then
+      echo -e "${BLUE}📋 Latest Checkpoint${RESET}"
+      echo "==================="
+      jq -r '"Timestamp: " + .timestamp + "\nType: " + .type + "\nMessage: " + .message + "\nCommit: " + .commitHash' "$CHECKPOINT_DIR/latest-checkpoint.json" 2>/dev/null || echo "Error reading checkpoint"
+    else
+      echo "No checkpoints found"
+    fi
+    ;;
+
+  *)
+    echo "V3 Checkpoint Manager"
+    echo "===================="
+    echo ""
+    echo "Usage: $0 <command> [options]"
+    echo ""
+    echo "Commands:"
+    echo "  auto-checkpoint [message]        Create automatic checkpoint"
+    echo "  agent-checkpoint [message]       Create agent milestone checkpoint"
+    echo "  domain-checkpoint [message]      Create domain completion checkpoint"
+    echo "  security-checkpoint [message]    Create security fix checkpoint"
+    echo "  performance-checkpoint [message] Create performance improvement checkpoint"
+    echo "  session-end [message]            Create session end checkpoint"
+    echo "  milestone-checkpoint [message]   Create major milestone checkpoint"
+    echo "  history                          Show recent checkpoint history"
+    echo "  status                           Show latest checkpoint info"
+    echo ""
+    echo "Examples:"
+    echo "  $0 auto-checkpoint \"Updated statusline configuration\""
+    echo "  $0 domain-checkpoint \"Completed task-management domain\""
+    echo "  $0 agent-checkpoint \"Deployed 8 agents successfully\""
+    ;;
+esac
@@ -0,0 +1,166 @@
+#!/bin/bash
+# V3 Progress Update Script
+# Usage: ./update-v3-progress.sh [domain|agent|security|performance] [value]
+
+set -e
+
+METRICS_DIR=".claude-flow/metrics"
+SECURITY_DIR=".claude-flow/security"
+
+# Ensure directories exist
+mkdir -p "$METRICS_DIR" "$SECURITY_DIR"
+
+case "$1" in
+  "domain")
+    if [ -z "$2" ]; then
+      echo "Usage: $0 domain <count>"
+      echo "Example: $0 domain 3"
+      exit 1
+    fi
+
+    # Update domain completion count
+    jq --argjson count "$2" '.domains.completed = $count' \
+      "$METRICS_DIR/v3-progress.json" > tmp.json && \
+      mv tmp.json "$METRICS_DIR/v3-progress.json"
+
+    echo "✅ Updated domain count to $2/5"
+    ;;
+
+  "agent")
+    if [ -z "$2" ]; then
+      echo "Usage: $0 agent <count>"
+      echo "Example: $0 agent 8"
+      exit 1
+    fi
+
+    # Update active agent count
+    jq --argjson count "$2" '.swarm.activeAgents = $count' \
+      "$METRICS_DIR/v3-progress.json" > tmp.json && \
+      mv tmp.json "$METRICS_DIR/v3-progress.json"
+
+    echo "✅ Updated active agents to $2/15"
+    ;;
+
+  "security")
+    if [ -z "$2" ]; then
+      echo "Usage: $0 security <fixed_count>"
+      echo "Example: $0 security 2"
+      exit 1
+    fi
+
+    # Update CVE fixes
+    jq --argjson count "$2" '.cvesFixed = $count' \
+      "$SECURITY_DIR/audit-status.json" > tmp.json && \
+      mv tmp.json "$SECURITY_DIR/audit-status.json"
+
+    if [ "$2" -eq 3 ]; then
+      jq '.status = "CLEAN"' \
+        "$SECURITY_DIR/audit-status.json" > tmp.json && \
+        mv tmp.json "$SECURITY_DIR/audit-status.json"
+    fi
+
+    echo "✅ Updated security: $2/3 CVEs fixed"
+    ;;
+
+  "performance")
+    if [ -z "$2" ]; then
+      echo "Usage: $0 performance <speedup>"
+      echo "Example: $0 performance 2.1x"
+      exit 1
+    fi
+
+    # Update performance metrics
+    jq --arg speedup "$2" '.flashAttention.speedup = $speedup' \
+      "$METRICS_DIR/performance.json" > tmp.json && \
+      mv tmp.json "$METRICS_DIR/performance.json"
+
+    echo "✅ Updated Flash Attention speedup to $2"
+    ;;
+
+  "memory")
+    if [ -z "$2" ]; then
+      echo "Usage: $0 memory <percentage>"
+      echo "Example: $0 memory 45%"
+      exit 1
+    fi
+
+    # Update memory reduction
+    jq --arg reduction "$2" '.memory.reduction = $reduction' \
+      "$METRICS_DIR/performance.json" > tmp.json && \
+      mv tmp.json "$METRICS_DIR/performance.json"
+
+    echo "✅ Updated memory reduction to $2"
+    ;;
+
+  "ddd")
+    if [ -z "$2" ]; then
+      echo "Usage: $0 ddd <percentage>"
+      echo "Example: $0 ddd 65"
+      exit 1
+    fi
+
+    # Update DDD progress percentage
+    jq --argjson progress "$2" '.ddd.progress = $progress' \
+      "$METRICS_DIR/v3-progress.json" > tmp.json && \
+      mv tmp.json "$METRICS_DIR/v3-progress.json"
+
+    echo "✅ Updated DDD progress to $2%"
+    ;;
+
+  "status")
+    # Show current status
+    echo "📊 V3 Development Status:"
+    echo "========================"
+
+    if [ -f "$METRICS_DIR/v3-progress.json" ]; then
+      domains=$(jq -r '.domains.completed // 0' "$METRICS_DIR/v3-progress.json")
+      agents=$(jq -r '.swarm.activeAgents // 0' "$METRICS_DIR/v3-progress.json")
+      ddd=$(jq -r '.ddd.progress // 0' "$METRICS_DIR/v3-progress.json")
+      echo "🏗️  Domains: $domains/5"
+      echo "🤖 Agents: $agents/15"
+      echo "📐 DDD: $ddd%"
+    fi
+
+    if [ -f "$SECURITY_DIR/audit-status.json" ]; then
+      cves=$(jq -r '.cvesFixed // 0' "$SECURITY_DIR/audit-status.json")
+      echo "🛡️  Security: $cves/3 CVEs fixed"
+    fi
+
+    if [ -f "$METRICS_DIR/performance.json" ]; then
+      speedup=$(jq -r '.flashAttention.speedup // "1.0x"' "$METRICS_DIR/performance.json")
+      memory=$(jq -r '.memory.reduction // "0%"' "$METRICS_DIR/performance.json")
+      echo "⚡ Performance: $speedup speedup, $memory memory saved"
+    fi
+    ;;
+
+  *)
+    echo "V3 Progress Update Tool"
+    echo "======================"
+    echo ""
+    echo "Usage: $0 <command> [value]"
+    echo ""
+    echo "Commands:"
+    echo "  domain <0-5>       Update completed domain count"
+    echo "  agent <0-15>       Update active agent count"
+    echo "  security <0-3>     Update fixed CVE count"
+    echo "  performance <x.x>  Update Flash Attention speedup"
+    echo "  memory <xx%>       Update memory reduction percentage"
+    echo "  ddd <0-100>        Update DDD progress percentage"
+    echo "  status             Show current status"
+    echo ""
+    echo "Examples:"
+    echo "  $0 domain 3        # Mark 3 domains as complete"
+    echo "  $0 agent 8         # Set 8 agents as active"
+    echo "  $0 security 2      # Mark 2 CVEs as fixed"
+    echo "  $0 performance 2.5x # Set speedup to 2.5x"
+    echo "  $0 memory 35%      # Set memory reduction to 35%"
+    echo "  $0 ddd 75          # Set DDD progress to 75%"
+    ;;
+esac
+
+# Show updated statusline if not just showing help
+if [ "$1" != "" ] && [ "$1" != "status" ]; then
+  echo ""
+  echo "📺 Updated Statusline:"
+  bash .claude/statusline.sh
+fi
@@ -0,0 +1,58 @@
+#!/bin/bash
+# V3 Quick Status - Compact development status overview
+
+set -e
+
+# Color codes
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+PURPLE='\033[0;35m'
+CYAN='\033[0;36m'
+RESET='\033[0m'
+
+echo -e "${PURPLE}⚡ Claude Flow V3 Quick Status${RESET}"
+
+# Get metrics
+DOMAINS=0
+AGENTS=0
+DDD_PROGRESS=0
+CVES_FIXED=0
+SPEEDUP="1.0x"
+MEMORY="0%"
+
+if [ -f ".claude-flow/metrics/v3-progress.json" ]; then
+  DOMAINS=$(jq -r '.domains.completed // 0' ".claude-flow/metrics/v3-progress.json" 2>/dev/null || echo "0")
+  AGENTS=$(jq -r '.swarm.activeAgents // 0' ".claude-flow/metrics/v3-progress.json" 2>/dev/null || echo "0")
+  DDD_PROGRESS=$(jq -r '.ddd.progress // 0' ".claude-flow/metrics/v3-progress.json" 2>/dev/null || echo "0")
+fi
+
+if [ -f ".claude-flow/security/audit-status.json" ]; then
+  CVES_FIXED=$(jq -r '.cvesFixed // 0' ".claude-flow/security/audit-status.json" 2>/dev/null || echo "0")
+fi
+
+if [ -f ".claude-flow/metrics/performance.json" ]; then
+  SPEEDUP=$(jq -r '.flashAttention.speedup // "1.0x"' ".claude-flow/metrics/performance.json" 2>/dev/null || echo "1.0x")
+  MEMORY=$(jq -r '.memory.reduction // "0%"' ".claude-flow/metrics/performance.json" 2>/dev/null || echo "0%")
+fi
+
+# Calculate progress percentages
+DOMAIN_PERCENT=$((DOMAINS * 20))
+AGENT_PERCENT=$((AGENTS * 100 / 15))
+SECURITY_PERCENT=$((CVES_FIXED * 33))
+
+# Color coding
+if [ $DOMAINS -eq 5 ]; then DOMAIN_COLOR=$GREEN; elif [ $DOMAINS -ge 3 ]; then DOMAIN_COLOR=$YELLOW; else DOMAIN_COLOR=$RED; fi
+if [ $AGENTS -ge 10 ]; then AGENT_COLOR=$GREEN; elif [ $AGENTS -ge 5 ]; then AGENT_COLOR=$YELLOW; else AGENT_COLOR=$RED; fi
+if [ $DDD_PROGRESS -ge 75 ]; then DDD_COLOR=$GREEN; elif [ $DDD_PROGRESS -ge 50 ]; then DDD_COLOR=$YELLOW; else DDD_COLOR=$RED; fi
+if [ $CVES_FIXED -eq 3 ]; then SEC_COLOR=$GREEN; elif [ $CVES_FIXED -ge 1 ]; then SEC_COLOR=$YELLOW; else SEC_COLOR=$RED; fi
+
+echo -e "${BLUE}Domains:${RESET} ${DOMAIN_COLOR}${DOMAINS}/5${RESET} (${DOMAIN_PERCENT}%) | ${BLUE}Agents:${RESET} ${AGENT_COLOR}${AGENTS}/15${RESET} (${AGENT_PERCENT}%) | ${BLUE}DDD:${RESET} ${DDD_COLOR}${DDD_PROGRESS}%${RESET}"
+echo -e "${BLUE}Security:${RESET} ${SEC_COLOR}${CVES_FIXED}/3${RESET} CVEs | ${BLUE}Perf:${RESET} ${CYAN}${SPEEDUP}${RESET} | ${BLUE}Memory:${RESET} ${CYAN}${MEMORY}${RESET}"
+
+# Branch info
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+  echo -e "${BLUE}Branch:${RESET} ${CYAN}${BRANCH}${RESET}"
+fi
@@ -0,0 +1,111 @@
+#!/bin/bash
+# V3 Helper Alias Script - Quick access to all V3 development tools
+
+set -e
+
+HELPERS_DIR=".claude/helpers"
+
+case "$1" in
+  "status"|"st")
+    "$HELPERS_DIR/v3-quick-status.sh"
+    ;;
+
+  "progress"|"prog")
+    shift
+    "$HELPERS_DIR/update-v3-progress.sh" "$@"
+    ;;
+
+  "validate"|"check")
+    "$HELPERS_DIR/validate-v3-config.sh"
+    ;;
+
+  "statusline"|"sl")
+    ".claude/statusline.sh"
+    ;;
+
+  "update")
+    if [ -z "$2" ] || [ -z "$3" ]; then
+      echo "Usage: v3 update <metric> <value>"
+      echo "Examples:"
+      echo "  v3 update domain 3"
+      echo "  v3 update agent 8"
+      echo "  v3 update security 2"
+      echo "  v3 update performance 2.5x"
+      echo "  v3 update memory 45%"
+      echo "  v3 update ddd 75"
+      exit 1
+    fi
+    "$HELPERS_DIR/update-v3-progress.sh" "$2" "$3"
+    ;;
+
+  "full-status"|"fs")
+    echo "🔍 V3 Development Environment Status"
+    echo "====================================="
+    echo ""
+    echo "📊 Quick Status:"
+    "$HELPERS_DIR/v3-quick-status.sh"
+    echo ""
+    echo "📺 Full Statusline:"
+    ".claude/statusline.sh"
+    ;;
+
+  "init")
+    echo "🚀 Initializing V3 Development Environment..."
+
+    # Run validation first
+    echo ""
+    echo "1️⃣ Validating configuration..."
+    if "$HELPERS_DIR/validate-v3-config.sh"; then
+      echo ""
+      echo "2️⃣ Showing current status..."
+      "$HELPERS_DIR/v3-quick-status.sh"
+      echo ""
+      echo "✅ V3 development environment is ready!"
+      echo ""
+      echo "🔧 Quick commands:"
+      echo "  v3 status        - Show quick status"
+      echo "  v3 update        - Update progress metrics"
+      echo "  v3 statusline    - Show full statusline"
+      echo "  v3 validate      - Validate configuration"
+    else
+      echo ""
+      echo "❌ Configuration validation failed. Please fix issues before proceeding."
+      exit 1
+    fi
+    ;;
+
+  "help"|"--help"|"-h"|"")
+    echo "Claude Flow V3 Helper Tool"
+    echo "=========================="
+    echo ""
+    echo "Usage: v3 <command> [options]"
+    echo ""
+    echo "Commands:"
+    echo "  status, st              Show quick development status"
+    echo "  progress, prog [args]   Update progress metrics"
+    echo "  validate, check         Validate V3 configuration"
+    echo "  statusline, sl          Show full statusline"
+    echo "  full-status, fs         Show both quick status and statusline"
+    echo "  update <metric> <value> Update specific metric"
+    echo "  init                    Initialize and validate environment"
+    echo "  help                    Show this help message"
+    echo ""
+    echo "Update Examples:"
+    echo "  v3 update domain 3      # Mark 3 domains complete"
+    echo "  v3 update agent 8       # Set 8 agents active"
+    echo "  v3 update security 2    # Mark 2 CVEs fixed"
+    echo "  v3 update performance 2.5x # Set performance to 2.5x"
+    echo "  v3 update memory 45%    # Set memory reduction to 45%"
+    echo "  v3 update ddd 75        # Set DDD progress to 75%"
+    echo ""
+    echo "Quick Start:"
+    echo "  v3 init                 # Initialize environment"
+    echo "  v3 status               # Check current progress"
+    ;;
+
+  *)
+    echo "Unknown command: $1"
+    echo "Run 'v3 help' for usage information"
+    exit 1
+    ;;
+esac
@@ -0,0 +1,216 @@
+#!/bin/bash
+# V3 Configuration Validation Script
+# Ensures all V3 development dependencies and configurations are properly set up
+
+set -e
+
+echo "🔍 Claude Flow V3 Configuration Validation"
+echo "==========================================="
+echo ""
+
+ERRORS=0
+WARNINGS=0
+
+# Color codes
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RESET='\033[0m'
+
+# Helper functions
+log_error() {
+  echo -e "${RED}❌ ERROR: $1${RESET}"
+  ((ERRORS++))
+}
+
+log_warning() {
+  echo -e "${YELLOW}⚠️  WARNING: $1${RESET}"
+  ((WARNINGS++))
+}
+
+log_success() {
+  echo -e "${GREEN}✅ $1${RESET}"
+}
+
+log_info() {
+  echo -e "${BLUE}ℹ️  $1${RESET}"
+}
+
+# Check 1: Required directories
+echo "📁 Checking Directory Structure..."
+required_dirs=(
+  ".claude"
+  ".claude/helpers"
+  ".claude-flow/metrics"
+  ".claude-flow/security"
+  "src"
+  "src/domains"
+)
+
+for dir in "${required_dirs[@]}"; do
+  if [ -d "$dir" ]; then
+    log_success "Directory exists: $dir"
+  else
+    log_error "Missing required directory: $dir"
+  fi
+done
+
+# Check 2: Required files
+echo ""
+echo "📄 Checking Required Files..."
+required_files=(
+  ".claude/settings.json"
+  ".claude/statusline.sh"
+  ".claude/helpers/update-v3-progress.sh"
+  ".claude-flow/metrics/v3-progress.json"
+  ".claude-flow/metrics/performance.json"
+  ".claude-flow/security/audit-status.json"
+  "package.json"
+)
+
+for file in "${required_files[@]}"; do
+  if [ -f "$file" ]; then
+    log_success "File exists: $file"
+
+    # Additional checks for specific files
+    case "$file" in
+      "package.json")
+        if grep -q "agentic-flow.*alpha" "$file" 2>/dev/null; then
+          log_success "agentic-flow@alpha dependency found"
+        else
+          log_warning "agentic-flow@alpha dependency not found in package.json"
+        fi
+        ;;
+      ".claude/helpers/update-v3-progress.sh")
+        if [ -x "$file" ]; then
+          log_success "Helper script is executable"
+        else
+          log_error "Helper script is not executable: $file"
+        fi
+        ;;
+      ".claude-flow/metrics/v3-progress.json")
+        if jq empty "$file" 2>/dev/null; then
+          log_success "V3 progress JSON is valid"
+          domains=$(jq -r '.domains.total // "unknown"' "$file" 2>/dev/null)
+          agents=$(jq -r '.swarm.totalAgents // "unknown"' "$file" 2>/dev/null)
+          log_info "Configured for $domains domains, $agents agents"
+        else
+          log_error "Invalid JSON in v3-progress.json"
+        fi
+        ;;
+    esac
+  else
+    log_error "Missing required file: $file"
+  fi
+done
+
+# Check 3: Domain structure
+echo ""
+echo "🏗️ Checking Domain Structure..."
+expected_domains=("task-management" "session-management" "health-monitoring" "lifecycle-management" "event-coordination")
+
+for domain in "${expected_domains[@]}"; do
+  domain_path="src/domains/$domain"
+  if [ -d "$domain_path" ]; then
+    log_success "Domain directory exists: $domain"
+  else
+    log_warning "Domain directory missing: $domain (will be created during development)"
+  fi
+done
+
+# Check 4: Git configuration
+echo ""
+echo "🔀 Checking Git Configuration..."
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  log_success "Git repository detected"
+
+  current_branch=$(git branch --show-current 2>/dev/null || echo "unknown")
+  log_info "Current branch: $current_branch"
+
+  if [ "$current_branch" = "v3" ]; then
+    log_success "On V3 development branch"
+  else
+    log_warning "Not on V3 branch (current: $current_branch)"
+  fi
+else
+  log_error "Not in a Git repository"
+fi
+
+# Check 5: Node.js and npm
+echo ""
+echo "📦 Checking Node.js Environment..."
+if command -v node >/dev/null 2>&1; then
+  node_version=$(node --version)
+  log_success "Node.js installed: $node_version"
+
+  # Check if Node.js version is 20+
+  node_major=$(echo "$node_version" | cut -d'.' -f1 | sed 's/v//')
+  if [ "$node_major" -ge 20 ]; then
+    log_success "Node.js version meets requirements (≥20.0.0)"
+  else
+    log_error "Node.js version too old. Required: ≥20.0.0, Found: $node_version"
+  fi
+else
+  log_error "Node.js not installed"
+fi
+
+if command -v npm >/dev/null 2>&1; then
+  npm_version=$(npm --version)
+  log_success "npm installed: $npm_version"
+else
+  log_error "npm not installed"
+fi
+
+# Check 6: Development tools
+echo ""
+echo "🔧 Checking Development Tools..."
+dev_tools=("jq" "git")
+
+for tool in "${dev_tools[@]}"; do
+  if command -v "$tool" >/dev/null 2>&1; then
+    tool_version=$($tool --version 2>/dev/null | head -n1 || echo "unknown")
+    log_success "$tool installed: $tool_version"
+  else
+    log_error "$tool not installed"
+  fi
+done
+
+# Check 7: Permissions
+echo ""
+echo "🔐 Checking Permissions..."
+test_files=(
+  ".claude/statusline.sh"
+  ".claude/helpers/update-v3-progress.sh"
+)
+
+for file in "${test_files[@]}"; do
+  if [ -f "$file" ]; then
+    if [ -x "$file" ]; then
+      log_success "Executable permissions: $file"
+    else
+      log_warning "Missing executable permissions: $file"
+      log_info "Run: chmod +x $file"
+    fi
+  fi
+done
+
+# Summary
+echo ""
+echo "📊 Validation Summary"
+echo "===================="
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
+  log_success "All checks passed! V3 development environment is ready."
+  exit 0
+elif [ $ERRORS -eq 0 ]; then
+  echo -e "${YELLOW}⚠️  $WARNINGS warnings found, but no critical errors.${RESET}"
+  log_info "V3 development can proceed with minor issues to address."
+  exit 0
+else
+  echo -e "${RED}❌ $ERRORS critical errors found.${RESET}"
+  if [ $WARNINGS -gt 0 ]; then
+    echo -e "${YELLOW}⚠️  $WARNINGS warnings also found.${RESET}"
+  fi
+  log_error "Please fix critical errors before proceeding with V3 development."
+  exit 1
+fi
@@ -1,6 +1,24 @@
 {
  "model": "claude-sonnet-4-20250514",
-  "customInstructions": "Follow the project's CLAUDE.md guidelines",
+  "customInstructions": "Follow the project's CLAUDE.md guidelines. Use concurrent execution for all operations. Prioritize v3 implementation with security-first development, 15-agent swarm coordination, and phased performance optimization.",
+  "env": {
+    "AGENTIC_FLOW_INTELLIGENCE": "true",
+    "AGENTIC_FLOW_LEARNING_RATE": "0.05",
+    "AGENTIC_FLOW_EPSILON": "0.1",
+    "AGENTIC_FLOW_MEMORY_BACKEND": "agentdb",
+    "AGENTIC_FLOW_V3_MODE": "true",
+    "AGENTIC_FLOW_SWARM_SIZE": "15",
+    "AGENTIC_FLOW_TOPOLOGY": "hierarchical",
+    "AGENTIC_FLOW_SECURITY_FIRST": "true",
+    "AGENTIC_FLOW_PERFORMANCE_TIER": "standard",
+    "AGENTIC_FLOW_LEARNING_TIER": "standard",
+    "AGENTIC_FLOW_PRETRAIN_ENABLED": "true",
+    "AGENTIC_FLOW_SONA_ENABLED": "true",
+    "AGENTIC_FLOW_HNSW_ENABLED": "true",
+    "AGENTIC_FLOW_MOE_ATTENTION": "true",
+    "AGENTIC_FLOW_MULTI_ALGORITHM_RL": "true",
+    "AGENTIC_FLOW_COMPRESSION_ENABLED": "true"
+  },
  "permissions": {
    "allowedTools": [
      "Read",
@@ -11,52 +29,185 @@
      "Grep",
      "Task",
      "WebFetch",
-      "WebSearch"
+      "WebSearch",
+      "TodoWrite",
+      "LSP",
+      "NotebookEdit"
    ],
-    "deniedTools": []
+    "deniedTools": [],
+    "allow": [
+      "Bash(npx:*)",
+      "Bash(agentic-flow:*)",
+      "Bash(npm run:*)",
+      "mcp__agentic-flow",
+      "mcp__claude-flow",
+      "mcp__ruv-swarm"
+    ]
+  },
+  "checkpointManager": {
+    "enabled": true,
+    "autoCommit": true,
+    "commitMessage": "checkpoint: V3 development progress",
+    "frequency": "after-significant-change",
+    "includeMetrics": true
+  },
+  "githubIntegration": {
+    "enabled": true,
+    "features": {
+      "autoCommit": true,
+      "prTracking": true,
+      "issueManagement": true,
+      "progressReporting": true
+    }
  },
  "hooks": {
    "PreToolUse": [
      {
-        "matcher": {
-          "tools": [
-            "Edit",
-            "Write",
-            "MultiEdit"
-          ]
-        },
+        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
-            "command": "npx agentic-flow@alpha hooks pre-edit"
+            "timeout": 5000,
+            "command": "npx agentic-flow@alpha hooks pre-edit \"$TOOL_INPUT_file_path\" --v3-mode --security-check --pattern-lookup --checkpoint-prep 2>/dev/null || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 3000,
+            "command": "npx agentic-flow@alpha hooks pre-command \"$TOOL_INPUT_command\" --v3-mode --risk-assessment --suggest-optimization --git-check 2>/dev/null || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 2000,
+            "command": "npx agentic-flow@alpha hooks route \"$TOOL_INPUT_prompt\" --agent-suggest --v3-swarm --checkpoint-task 2>/dev/null || true"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
-        "matcher": {
-          "tools": [
-            "Edit",
-            "Write",
-            "MultiEdit"
-          ]
-        },
+        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
-            "command": "npx agentic-flow@alpha hooks post-edit"
+            "timeout": 5000,
+            "command": "npx agentic-flow@alpha hooks post-edit \"$TOOL_INPUT_file_path\" --success --learn --extract-patterns --v3-mode 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "timeout": 3000,
+            "command": ".claude/helpers/checkpoint-manager.sh auto-checkpoint \"File edit: $TOOL_INPUT_file_path\" 2>/dev/null || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 3000,
+            "command": "npx agentic-flow@alpha hooks post-command \"$TOOL_INPUT_command\" --success --learn --performance-metrics --v3-mode 2>/dev/null || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 2000,
+            "command": "npx agentic-flow@alpha hooks metrics --agent-performance --swarm-efficiency 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "timeout": 4000,
+            "command": ".claude/helpers/checkpoint-manager.sh agent-checkpoint \"Task completed: $TOOL_INPUT_prompt\" 2>/dev/null || true"
          }
        ]
      }
    ],
-    "Notification": [
+    "PostToolUseFailure": [
      {
-        "matcher": {},
+        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
-            "command": "npx agentic-flow@alpha hooks notify"
+            "timeout": 5000,
+            "command": "npx agentic-flow@alpha hooks post-edit \"$TOOL_INPUT_file_path\" --fail --error \"$ERROR_MESSAGE\" --learn-failure --pattern-analysis 2>/dev/null || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 3000,
+            "command": "npx agentic-flow@alpha hooks post-command \"$TOOL_INPUT_command\" --fail --error \"$ERROR_MESSAGE\" --learn-failure --suggest-fix 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 5000,
+            "command": "npx agentic-flow@alpha hooks intelligence stats --json --v3-mode --load-v3-patterns 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 8000,
+            "command": "npx agentic-flow@alpha hooks metrics --session --json --export-patterns --consolidate-learning --v3-summary 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "timeout": 6000,
+            "command": ".claude/helpers/checkpoint-manager.sh session-end \"V3 development session completed\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "timeout": 4000,
+            "command": ".claude/helpers/update-v3-progress.sh status > .claude-flow/last-session-status.txt 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 4000,
+            "command": "npx agentic-flow@alpha hooks route \"$USER_PROMPT\" --json --v3-agents --swarm-coordination --confidence-threshold 0.8 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 5000,
+            "command": "npx agentic-flow@alpha hooks metrics --session --final-consolidation --export-learned-patterns 2>/dev/null || true"
          }
        ]
      }
@@ -70,14 +221,43 @@
    "source": ".claude/commands",
    "enabled": true
  },
-  "statusline": {
+  "helpers": {
+    "directory": ".claude/helpers",
    "enabled": true,
-    "components": [
-      "model",
-      "tokens",
-      "cost",
-      "time"
-    ]
+    "scripts": {
+      "v3ProgressUpdater": ".claude/helpers/update-v3-progress.sh",
+      "v3ConfigValidator": ".claude/helpers/validate-v3-config.sh",
+      "v3QuickStatus": ".claude/helpers/v3-quick-status.sh",
+      "v3CheckpointManager": ".claude/helpers/checkpoint-manager.sh",
+      "v3Master": ".claude/helpers/v3.sh"
+    }
+  },
+  "v3Configuration": {
+    "domains": {
+      "total": 5,
+      "names": ["task-management", "session-management", "health-monitoring", "lifecycle-management", "event-coordination"],
+      "sourceDir": "src/domains"
+    },
+    "swarm": {
+      "totalAgents": 15,
+      "topology": "hierarchical-mesh",
+      "coordination": "queen-led"
+    },
+    "performance": {
+      "flashAttentionTarget": "2.49x-7.47x",
+      "memoryReductionTarget": "50-75%",
+      "searchImprovementTarget": "150x-12,500x",
+      "codebaseReductionTarget": "10,000+ lines"
+    },
+    "security": {
+      "criticalCves": 3,
+      "securityFirst": true,
+      "auditRequired": true
+    }
+  },
+  "statusLine": {
+    "type": "command",
+    "command": ".claude/statusline.sh"
  },
  "mcpServers": {
    "claude-flow": {
@@ -1,65 +0,0 @@
-{
-  "model": "claude-sonnet-4-20250514",
-  "customInstructions": "Follow the project's CLAUDE.md guidelines",
-  "permissions": {
-    "allowedTools": [
-      "Read",
-      "Write",
-      "Edit",
-      "Bash",
-      "Glob",
-      "Grep",
-      "Task",
-      "WebFetch",
-      "WebSearch"
-    ],
-    "deniedTools": []
-  },
-  "hooks": {
-    "pre-tool-use": [
-      {
-        "matcher": "Edit|Write",
-        "command": "npx agentic-flow@alpha hooks pre-edit $FILE"
-      }
-    ],
-    "post-tool-use": [
-      {
-        "matcher": "Edit|Write",
-        "command": "npx agentic-flow@alpha hooks post-edit $FILE"
-      }
-    ],
-    "notification": [
-      {
-        "matcher": ".*",
-        "command": "npx agentic-flow@alpha hooks notify"
-      }
-    ]
-  },
-  "agents": {
-    "source": ".claude/agents",
-    "customAgents": []
-  },
-  "skills": {
-    "source": ".claude/commands",
-    "enabled": true
-  },
-  "statusline": {
-    "enabled": true,
-    "components": [
-      "model",
-      "tokens",
-      "cost",
-      "time"
-    ]
-  },
-  "mcpServers": {
-    "claude-flow": {
-      "command": "npx",
-      "args": [
-        "agentic-flow@alpha",
-        "mcp",
-        "start"
-      ]
-    }
-  }
-}
@@ -0,0 +1,550 @@
+---
+name: "AgentDB Advanced Features"
+description: "Master advanced AgentDB features including QUIC synchronization, multi-database management, custom distance metrics, hybrid search, and distributed systems integration. Use when building distributed AI systems, multi-agent coordination, or advanced vector search applications."
+---
+
+# AgentDB Advanced Features
+
+## What This Skill Does
+
+Covers advanced AgentDB capabilities for distributed systems, multi-database coordination, custom distance metrics, hybrid search (vector + metadata), QUIC synchronization, and production deployment patterns. Enables building sophisticated AI systems with sub-millisecond cross-node communication and advanced search capabilities.
+
+**Performance**: <1ms QUIC sync, hybrid search with filters, custom distance metrics.
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow)
+- Understanding of distributed systems (for QUIC sync)
+- Vector search fundamentals
+
+---
+
+## QUIC Synchronization
+
+### What is QUIC Sync?
+
+QUIC (Quick UDP Internet Connections) enables sub-millisecond latency synchronization between AgentDB instances across network boundaries with automatic retry, multiplexing, and encryption.
+
+**Benefits**:
+- <1ms latency between nodes
+- Multiplexed streams (multiple operations simultaneously)
+- Built-in encryption (TLS 1.3)
+- Automatic retry and recovery
+- Event-based broadcasting
+
+### Enable QUIC Sync
+
+```typescript
+import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';
+
+// Initialize with QUIC synchronization
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/distributed.db',
+  enableQUICSync: true,
+  syncPort: 4433,
+  syncPeers: [
+    '192.168.1.10:4433',
+    '192.168.1.11:4433',
+    '192.168.1.12:4433',
+  ],
+});
+
+// Patterns automatically sync across all peers
+await adapter.insertPattern({
+  // ... pattern data
+});
+
+// Available on all peers within ~1ms
+```
+
+### QUIC Configuration
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  enableQUICSync: true,
+  syncPort: 4433,              // QUIC server port
+  syncPeers: ['host1:4433'],   // Peer addresses
+  syncInterval: 1000,          // Sync interval (ms)
+  syncBatchSize: 100,          // Patterns per batch
+  maxRetries: 3,               // Retry failed syncs
+  compression: true,           // Enable compression
+});
+```
+
+### Multi-Node Deployment
+
+```bash
+# Node 1 (192.168.1.10)
+AGENTDB_QUIC_SYNC=true \
+AGENTDB_QUIC_PORT=4433 \
+AGENTDB_QUIC_PEERS=192.168.1.11:4433,192.168.1.12:4433 \
+node server.js
+
+# Node 2 (192.168.1.11)
+AGENTDB_QUIC_SYNC=true \
+AGENTDB_QUIC_PORT=4433 \
+AGENTDB_QUIC_PEERS=192.168.1.10:4433,192.168.1.12:4433 \
+node server.js
+
+# Node 3 (192.168.1.12)
+AGENTDB_QUIC_SYNC=true \
+AGENTDB_QUIC_PORT=4433 \
+AGENTDB_QUIC_PEERS=192.168.1.10:4433,192.168.1.11:4433 \
+node server.js
+```
+
+---
+
+## Distance Metrics
+
+### Cosine Similarity (Default)
+
+Best for normalized vectors, semantic similarity:
+
+```bash
+# CLI
+npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m cosine
+
+# API
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  metric: 'cosine',
+  k: 10,
+});
+```
+
+**Use Cases**:
+- Text embeddings (BERT, GPT, etc.)
+- Semantic search
+- Document similarity
+- Most general-purpose applications
+
+**Formula**: `cos(θ) = (A · B) / (||A|| × ||B||)`
+**Range**: [-1, 1] (1 = identical, -1 = opposite)
+
+### Euclidean Distance (L2)
+
+Best for spatial data, geometric similarity:
+
+```bash
+# CLI
+npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m euclidean
+
+# API
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  metric: 'euclidean',
+  k: 10,
+});
+```
+
+**Use Cases**:
+- Image embeddings
+- Spatial data
+- Computer vision
+- When vector magnitude matters
+
+**Formula**: `d = √(Σ(ai - bi)²)`
+**Range**: [0, ∞] (0 = identical, ∞ = very different)
+
+### Dot Product
+
+Best for pre-normalized vectors, fast computation:
+
+```bash
+# CLI
+npx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m dot
+
+# API
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  metric: 'dot',
+  k: 10,
+});
+```
+
+**Use Cases**:
+- Pre-normalized embeddings
+- Fast similarity computation
+- When vectors are already unit-length
+
+**Formula**: `dot = Σ(ai × bi)`
+**Range**: [-∞, ∞] (higher = more similar)
+
+### Custom Distance Metrics
+
+```typescript
+// Implement custom distance function
+function customDistance(vec1: number[], vec2: number[]): number {
+  // Weighted Euclidean distance
+  const weights = [1.0, 2.0, 1.5, ...];
+  let sum = 0;
+  for (let i = 0; i < vec1.length; i++) {
+    sum += weights[i] * Math.pow(vec1[i] - vec2[i], 2);
+  }
+  return Math.sqrt(sum);
+}
+
+// Use in search (requires custom implementation)
+```
+
+---
+
+## Hybrid Search (Vector + Metadata)
+
+### Basic Hybrid Search
+
+Combine vector similarity with metadata filtering:
+
+```typescript
+// Store documents with metadata
+await adapter.insertPattern({
+  id: '',
+  type: 'document',
+  domain: 'research-papers',
+  pattern_data: JSON.stringify({
+    embedding: documentEmbedding,
+    text: documentText,
+    metadata: {
+      author: 'Jane Smith',
+      year: 2025,
+      category: 'machine-learning',
+      citations: 150,
+    }
+  }),
+  confidence: 1.0,
+  usage_count: 0,
+  success_count: 0,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Hybrid search: vector similarity + metadata filters
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'research-papers',
+  k: 20,
+  filters: {
+    year: { $gte: 2023 },          // Published 2023 or later
+    category: 'machine-learning',   // ML papers only
+    citations: { $gte: 50 },       // Highly cited
+  },
+});
+```
+
+### Advanced Filtering
+
+```typescript
+// Complex metadata queries
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'products',
+  k: 50,
+  filters: {
+    price: { $gte: 10, $lte: 100 },      // Price range
+    category: { $in: ['electronics', 'gadgets'] },  // Multiple categories
+    rating: { $gte: 4.0 },                // High rated
+    inStock: true,                        // Available
+    tags: { $contains: 'wireless' },      // Has tag
+  },
+});
+```
+
+### Weighted Hybrid Search
+
+Combine vector and metadata scores:
+
+```typescript
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'content',
+  k: 20,
+  hybridWeights: {
+    vectorSimilarity: 0.7,  // 70% weight on semantic similarity
+    metadataScore: 0.3,     // 30% weight on metadata match
+  },
+  filters: {
+    category: 'technology',
+    recency: { $gte: Date.now() - 30 * 24 * 3600000 },  // Last 30 days
+  },
+});
+```
+
+---
+
+## Multi-Database Management
+
+### Multiple Databases
+
+```typescript
+// Separate databases for different domains
+const knowledgeDB = await createAgentDBAdapter({
+  dbPath: '.agentdb/knowledge.db',
+});
+
+const conversationDB = await createAgentDBAdapter({
+  dbPath: '.agentdb/conversations.db',
+});
+
+const codeDB = await createAgentDBAdapter({
+  dbPath: '.agentdb/code.db',
+});
+
+// Use appropriate database for each task
+await knowledgeDB.insertPattern({ /* knowledge */ });
+await conversationDB.insertPattern({ /* conversation */ });
+await codeDB.insertPattern({ /* code */ });
+```
+
+### Database Sharding
+
+```typescript
+// Shard by domain for horizontal scaling
+const shards = {
+  'domain-a': await createAgentDBAdapter({ dbPath: '.agentdb/shard-a.db' }),
+  'domain-b': await createAgentDBAdapter({ dbPath: '.agentdb/shard-b.db' }),
+  'domain-c': await createAgentDBAdapter({ dbPath: '.agentdb/shard-c.db' }),
+};
+
+// Route queries to appropriate shard
+function getDBForDomain(domain: string) {
+  const shardKey = domain.split('-')[0];  // Extract shard key
+  return shards[shardKey] || shards['domain-a'];
+}
+
+// Insert to correct shard
+const db = getDBForDomain('domain-a-task');
+await db.insertPattern({ /* ... */ });
+```
+
+---
+
+## MMR (Maximal Marginal Relevance)
+
+Retrieve diverse results to avoid redundancy:
+
+```typescript
+// Without MMR: Similar results may be redundant
+const standardResults = await adapter.retrieveWithReasoning(queryEmbedding, {
+  k: 10,
+  useMMR: false,
+});
+
+// With MMR: Diverse, non-redundant results
+const diverseResults = await adapter.retrieveWithReasoning(queryEmbedding, {
+  k: 10,
+  useMMR: true,
+  mmrLambda: 0.5,  // Balance relevance (0) vs diversity (1)
+});
+```
+
+**MMR Parameters**:
+- `mmrLambda = 0`: Maximum relevance (may be redundant)
+- `mmrLambda = 0.5`: Balanced (default)
+- `mmrLambda = 1`: Maximum diversity (may be less relevant)
+
+**Use Cases**:
+- Search result diversification
+- Recommendation systems
+- Avoiding echo chambers
+- Exploratory search
+
+---
+
+## Context Synthesis
+
+Generate rich context from multiple memories:
+
+```typescript
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'problem-solving',
+  k: 10,
+  synthesizeContext: true,  // Enable context synthesis
+});
+
+// ContextSynthesizer creates coherent narrative
+console.log('Synthesized Context:', result.context);
+// "Based on 10 similar problem-solving attempts, the most effective
+//  approach involves: 1) analyzing root cause, 2) brainstorming solutions,
+//  3) evaluating trade-offs, 4) implementing incrementally. Success rate: 85%"
+
+console.log('Patterns:', result.patterns);
+// Extracted common patterns across memories
+```
+
+---
+
+## Production Patterns
+
+### Connection Pooling
+
+```typescript
+// Singleton pattern for shared adapter
+class AgentDBPool {
+  private static instance: AgentDBAdapter;
+
+  static async getInstance() {
+    if (!this.instance) {
+      this.instance = await createAgentDBAdapter({
+        dbPath: '.agentdb/production.db',
+        quantizationType: 'scalar',
+        cacheSize: 2000,
+      });
+    }
+    return this.instance;
+  }
+}
+
+// Use in application
+const db = await AgentDBPool.getInstance();
+const results = await db.retrieveWithReasoning(queryEmbedding, { k: 10 });
+```
+
+### Error Handling
+
+```typescript
+async function safeRetrieve(queryEmbedding: number[], options: any) {
+  try {
+    const result = await adapter.retrieveWithReasoning(queryEmbedding, options);
+    return result;
+  } catch (error) {
+    if (error.code === 'DIMENSION_MISMATCH') {
+      console.error('Query embedding dimension mismatch');
+      // Handle dimension error
+    } else if (error.code === 'DATABASE_LOCKED') {
+      // Retry with exponential backoff
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return safeRetrieve(queryEmbedding, options);
+    }
+    throw error;
+  }
+}
+```
+
+### Monitoring and Logging
+
+```typescript
+// Performance monitoring
+const startTime = Date.now();
+const result = await adapter.retrieveWithReasoning(queryEmbedding, { k: 10 });
+const latency = Date.now() - startTime;
+
+if (latency > 100) {
+  console.warn('Slow query detected:', latency, 'ms');
+}
+
+// Log statistics
+const stats = await adapter.getStats();
+console.log('Database Stats:', {
+  totalPatterns: stats.totalPatterns,
+  dbSize: stats.dbSize,
+  cacheHitRate: stats.cacheHitRate,
+  avgSearchLatency: stats.avgSearchLatency,
+});
+```
+
+---
+
+## CLI Advanced Operations
+
+### Database Import/Export
+
+```bash
+# Export with compression
+npx agentdb@latest export ./vectors.db ./backup.json.gz --compress
+
+# Import from backup
+npx agentdb@latest import ./backup.json.gz --decompress
+
+# Merge databases
+npx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite
+```
+
+### Database Optimization
+
+```bash
+# Vacuum database (reclaim space)
+sqlite3 .agentdb/vectors.db "VACUUM;"
+
+# Analyze for query optimization
+sqlite3 .agentdb/vectors.db "ANALYZE;"
+
+# Rebuild indices
+npx agentdb@latest reindex ./vectors.db
+```
+
+---
+
+## Environment Variables
+
+```bash
+# AgentDB configuration
+AGENTDB_PATH=.agentdb/reasoningbank.db
+AGENTDB_ENABLED=true
+
+# Performance tuning
+AGENTDB_QUANTIZATION=binary     # binary|scalar|product|none
+AGENTDB_CACHE_SIZE=2000
+AGENTDB_HNSW_M=16
+AGENTDB_HNSW_EF=100
+
+# Learning plugins
+AGENTDB_LEARNING=true
+
+# Reasoning agents
+AGENTDB_REASONING=true
+
+# QUIC synchronization
+AGENTDB_QUIC_SYNC=true
+AGENTDB_QUIC_PORT=4433
+AGENTDB_QUIC_PEERS=host1:4433,host2:4433
+```
+
+---
+
+## Troubleshooting
+
+### Issue: QUIC sync not working
+
+```bash
+# Check firewall allows UDP port 4433
+sudo ufw allow 4433/udp
+
+# Verify peers are reachable
+ping host1
+
+# Check QUIC logs
+DEBUG=agentdb:quic node server.js
+```
+
+### Issue: Hybrid search returns no results
+
+```typescript
+// Relax filters
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  k: 100,  // Increase k
+  filters: {
+    // Remove or relax filters
+  },
+});
+```
+
+### Issue: Memory consolidation too aggressive
+
+```typescript
+// Disable automatic optimization
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  optimizeMemory: false,  // Disable auto-consolidation
+  k: 10,
+});
+```
+
+---
+
+## Learn More
+
+- **QUIC Protocol**: docs/quic-synchronization.pdf
+- **Hybrid Search**: docs/hybrid-search-guide.md
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- **Website**: https://agentdb.ruv.io
+
+---
+
+**Category**: Advanced / Distributed Systems
+**Difficulty**: Advanced
+**Estimated Time**: 45-60 minutes
@@ -0,0 +1,545 @@
+---
+name: "AgentDB Learning Plugins"
+description: "Create and train AI learning plugins with AgentDB's 9 reinforcement learning algorithms. Includes Decision Transformer, Q-Learning, SARSA, Actor-Critic, and more. Use when building self-learning agents, implementing RL, or optimizing agent behavior through experience."
+---
+
+# AgentDB Learning Plugins
+
+## What This Skill Does
+
+Provides access to 9 reinforcement learning algorithms via AgentDB's plugin system. Create, train, and deploy learning plugins for autonomous agents that improve through experience. Includes offline RL (Decision Transformer), value-based learning (Q-Learning), policy gradients (Actor-Critic), and advanced techniques.
+
+**Performance**: Train models 10-100x faster with WASM-accelerated neural inference.
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow)
+- Basic understanding of reinforcement learning (recommended)
+
+---
+
+## Quick Start with CLI
+
+### Create Learning Plugin
+
+```bash
+# Interactive wizard
+npx agentdb@latest create-plugin
+
+# Use specific template
+npx agentdb@latest create-plugin -t decision-transformer -n my-agent
+
+# Preview without creating
+npx agentdb@latest create-plugin -t q-learning --dry-run
+
+# Custom output directory
+npx agentdb@latest create-plugin -t actor-critic -o ./plugins
+```
+
+### List Available Templates
+
+```bash
+# Show all plugin templates
+npx agentdb@latest list-templates
+
+# Available templates:
+# - decision-transformer (sequence modeling RL - recommended)
+# - q-learning (value-based learning)
+# - sarsa (on-policy TD learning)
+# - actor-critic (policy gradient with baseline)
+# - curiosity-driven (exploration-based)
+```
+
+### Manage Plugins
+
+```bash
+# List installed plugins
+npx agentdb@latest list-plugins
+
+# Get plugin information
+npx agentdb@latest plugin-info my-agent
+
+# Shows: algorithm, configuration, training status
+```
+
+---
+
+## Quick Start with API
+
+```typescript
+import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';
+
+// Initialize with learning enabled
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/learning.db',
+  enableLearning: true,       // Enable learning plugins
+  enableReasoning: true,
+  cacheSize: 1000,
+});
+
+// Store training experience
+await adapter.insertPattern({
+  id: '',
+  type: 'experience',
+  domain: 'game-playing',
+  pattern_data: JSON.stringify({
+    embedding: await computeEmbedding('state-action-reward'),
+    pattern: {
+      state: [0.1, 0.2, 0.3],
+      action: 2,
+      reward: 1.0,
+      next_state: [0.15, 0.25, 0.35],
+      done: false
+    }
+  }),
+  confidence: 0.9,
+  usage_count: 1,
+  success_count: 1,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Train learning model
+const metrics = await adapter.train({
+  epochs: 50,
+  batchSize: 32,
+});
+
+console.log('Training Loss:', metrics.loss);
+console.log('Duration:', metrics.duration, 'ms');
+```
+
+---
+
+## Available Learning Algorithms (9 Total)
+
+### 1. Decision Transformer (Recommended)
+
+**Type**: Offline Reinforcement Learning
+**Best For**: Learning from logged experiences, imitation learning
+**Strengths**: No online interaction needed, stable training
+
+```bash
+npx agentdb@latest create-plugin -t decision-transformer -n dt-agent
+```
+
+**Use Cases**:
+- Learn from historical data
+- Imitation learning from expert demonstrations
+- Safe learning without environment interaction
+- Sequence modeling tasks
+
+**Configuration**:
+```json
+{
+  "algorithm": "decision-transformer",
+  "model_size": "base",
+  "context_length": 20,
+  "embed_dim": 128,
+  "n_heads": 8,
+  "n_layers": 6
+}
+```
+
+### 2. Q-Learning
+
+**Type**: Value-Based RL (Off-Policy)
+**Best For**: Discrete action spaces, sample efficiency
+**Strengths**: Proven, simple, works well for small/medium problems
+
+```bash
+npx agentdb@latest create-plugin -t q-learning -n q-agent
+```
+
+**Use Cases**:
+- Grid worlds, board games
+- Navigation tasks
+- Resource allocation
+- Discrete decision-making
+
+**Configuration**:
+```json
+{
+  "algorithm": "q-learning",
+  "learning_rate": 0.001,
+  "gamma": 0.99,
+  "epsilon": 0.1,
+  "epsilon_decay": 0.995
+}
+```
+
+### 3. SARSA
+
+**Type**: Value-Based RL (On-Policy)
+**Best For**: Safe exploration, risk-sensitive tasks
+**Strengths**: More conservative than Q-Learning, better for safety
+
+```bash
+npx agentdb@latest create-plugin -t sarsa -n sarsa-agent
+```
+
+**Use Cases**:
+- Safety-critical applications
+- Risk-sensitive decision-making
+- Online learning with exploration
+
+**Configuration**:
+```json
+{
+  "algorithm": "sarsa",
+  "learning_rate": 0.001,
+  "gamma": 0.99,
+  "epsilon": 0.1
+}
+```
+
+### 4. Actor-Critic
+
+**Type**: Policy Gradient with Value Baseline
+**Best For**: Continuous actions, variance reduction
+**Strengths**: Stable, works for continuous/discrete actions
+
+```bash
+npx agentdb@latest create-plugin -t actor-critic -n ac-agent
+```
+
+**Use Cases**:
+- Continuous control (robotics, simulations)
+- Complex action spaces
+- Multi-agent coordination
+
+**Configuration**:
+```json
+{
+  "algorithm": "actor-critic",
+  "actor_lr": 0.001,
+  "critic_lr": 0.002,
+  "gamma": 0.99,
+  "entropy_coef": 0.01
+}
+```
+
+### 5. Active Learning
+
+**Type**: Query-Based Learning
+**Best For**: Label-efficient learning, human-in-the-loop
+**Strengths**: Minimizes labeling cost, focuses on uncertain samples
+
+**Use Cases**:
+- Human feedback incorporation
+- Label-efficient training
+- Uncertainty sampling
+- Annotation cost reduction
+
+### 6. Adversarial Training
+
+**Type**: Robustness Enhancement
+**Best For**: Safety, robustness to perturbations
+**Strengths**: Improves model robustness, adversarial defense
+
+**Use Cases**:
+- Security applications
+- Robust decision-making
+- Adversarial defense
+- Safety testing
+
+### 7. Curriculum Learning
+
+**Type**: Progressive Difficulty Training
+**Best For**: Complex tasks, faster convergence
+**Strengths**: Stable learning, faster convergence on hard tasks
+
+**Use Cases**:
+- Complex multi-stage tasks
+- Hard exploration problems
+- Skill composition
+- Transfer learning
+
+### 8. Federated Learning
+
+**Type**: Distributed Learning
+**Best For**: Privacy, distributed data
+**Strengths**: Privacy-preserving, scalable
+
+**Use Cases**:
+- Multi-agent systems
+- Privacy-sensitive data
+- Distributed training
+- Collaborative learning
+
+### 9. Multi-Task Learning
+
+**Type**: Transfer Learning
+**Best For**: Related tasks, knowledge sharing
+**Strengths**: Faster learning on new tasks, better generalization
+
+**Use Cases**:
+- Task families
+- Transfer learning
+- Domain adaptation
+- Meta-learning
+
+---
+
+## Training Workflow
+
+### 1. Collect Experiences
+
+```typescript
+// Store experiences during agent execution
+for (let i = 0; i < numEpisodes; i++) {
+  const episode = runEpisode();
+
+  for (const step of episode.steps) {
+    await adapter.insertPattern({
+      id: '',
+      type: 'experience',
+      domain: 'task-domain',
+      pattern_data: JSON.stringify({
+        embedding: await computeEmbedding(JSON.stringify(step)),
+        pattern: {
+          state: step.state,
+          action: step.action,
+          reward: step.reward,
+          next_state: step.next_state,
+          done: step.done
+        }
+      }),
+      confidence: step.reward > 0 ? 0.9 : 0.5,
+      usage_count: 1,
+      success_count: step.reward > 0 ? 1 : 0,
+      created_at: Date.now(),
+      last_used: Date.now(),
+    });
+  }
+}
+```
+
+### 2. Train Model
+
+```typescript
+// Train on collected experiences
+const trainingMetrics = await adapter.train({
+  epochs: 100,
+  batchSize: 64,
+  learningRate: 0.001,
+  validationSplit: 0.2,
+});
+
+console.log('Training Metrics:', trainingMetrics);
+// {
+//   loss: 0.023,
+//   valLoss: 0.028,
+//   duration: 1523,
+//   epochs: 100
+// }
+```
+
+### 3. Evaluate Performance
+
+```typescript
+// Retrieve similar successful experiences
+const testQuery = await computeEmbedding(JSON.stringify(testState));
+const result = await adapter.retrieveWithReasoning(testQuery, {
+  domain: 'task-domain',
+  k: 10,
+  synthesizeContext: true,
+});
+
+// Evaluate action quality
+const suggestedAction = result.memories[0].pattern.action;
+const confidence = result.memories[0].similarity;
+
+console.log('Suggested Action:', suggestedAction);
+console.log('Confidence:', confidence);
+```
+
+---
+
+## Advanced Training Techniques
+
+### Experience Replay
+
+```typescript
+// Store experiences in buffer
+const replayBuffer = [];
+
+// Sample random batch for training
+const batch = sampleRandomBatch(replayBuffer, batchSize: 32);
+
+// Train on batch
+await adapter.train({
+  data: batch,
+  epochs: 1,
+  batchSize: 32,
+});
+```
+
+### Prioritized Experience Replay
+
+```typescript
+// Store experiences with priority (TD error)
+await adapter.insertPattern({
+  // ... standard fields
+  confidence: tdError,  // Use TD error as confidence/priority
+  // ...
+});
+
+// Retrieve high-priority experiences
+const highPriority = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'task-domain',
+  k: 32,
+  minConfidence: 0.7,  // Only high TD-error experiences
+});
+```
+
+### Multi-Agent Training
+
+```typescript
+// Collect experiences from multiple agents
+for (const agent of agents) {
+  const experience = await agent.step();
+
+  await adapter.insertPattern({
+    // ... store experience with agent ID
+    domain: `multi-agent/${agent.id}`,
+  });
+}
+
+// Train shared model
+await adapter.train({
+  epochs: 50,
+  batchSize: 64,
+});
+```
+
+---
+
+## Performance Optimization
+
+### Batch Training
+
+```typescript
+// Collect batch of experiences
+const experiences = collectBatch(size: 1000);
+
+// Batch insert (500x faster)
+for (const exp of experiences) {
+  await adapter.insertPattern({ /* ... */ });
+}
+
+// Train on batch
+await adapter.train({
+  epochs: 10,
+  batchSize: 128,  // Larger batch for efficiency
+});
+```
+
+### Incremental Learning
+
+```typescript
+// Train incrementally as new data arrives
+setInterval(async () => {
+  const newExperiences = getNewExperiences();
+
+  if (newExperiences.length > 100) {
+    await adapter.train({
+      epochs: 5,
+      batchSize: 32,
+    });
+  }
+}, 60000);  // Every minute
+```
+
+---
+
+## Integration with Reasoning Agents
+
+Combine learning with reasoning for better performance:
+
+```typescript
+// Train learning model
+await adapter.train({ epochs: 50, batchSize: 32 });
+
+// Use reasoning agents for inference
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'decision-making',
+  k: 10,
+  useMMR: true,              // Diverse experiences
+  synthesizeContext: true,    // Rich context
+  optimizeMemory: true,       // Consolidate patterns
+});
+
+// Make decision based on learned experiences + reasoning
+const decision = result.context.suggestedAction;
+const confidence = result.memories[0].similarity;
+```
+
+---
+
+## CLI Operations
+
+```bash
+# Create plugin
+npx agentdb@latest create-plugin -t decision-transformer -n my-plugin
+
+# List plugins
+npx agentdb@latest list-plugins
+
+# Get plugin info
+npx agentdb@latest plugin-info my-plugin
+
+# List templates
+npx agentdb@latest list-templates
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Training not converging
+```typescript
+// Reduce learning rate
+await adapter.train({
+  epochs: 100,
+  batchSize: 32,
+  learningRate: 0.0001,  // Lower learning rate
+});
+```
+
+### Issue: Overfitting
+```typescript
+// Use validation split
+await adapter.train({
+  epochs: 50,
+  batchSize: 64,
+  validationSplit: 0.2,  // 20% validation
+});
+
+// Enable memory optimization
+await adapter.retrieveWithReasoning(queryEmbedding, {
+  optimizeMemory: true,  // Consolidate, reduce overfitting
+});
+```
+
+### Issue: Slow training
+```bash
+# Enable quantization for faster inference
+# Use binary quantization (32x faster)
+```
+
+---
+
+## Learn More
+
+- **Algorithm Papers**: See docs/algorithms/ for detailed papers
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- **MCP Integration**: `npx agentdb@latest mcp`
+- **Website**: https://agentdb.ruv.io
+
+---
+
+**Category**: Machine Learning / Reinforcement Learning
+**Difficulty**: Intermediate to Advanced
+**Estimated Time**: 30-60 minutes
@@ -0,0 +1,339 @@
+---
+name: "AgentDB Memory Patterns"
+description: "Implement persistent memory patterns for AI agents using AgentDB. Includes session memory, long-term storage, pattern learning, and context management. Use when building stateful agents, chat systems, or intelligent assistants."
+---
+
+# AgentDB Memory Patterns
+
+## What This Skill Does
+
+Provides memory management patterns for AI agents using AgentDB's persistent storage and ReasoningBank integration. Enables agents to remember conversations, learn from interactions, and maintain context across sessions.
+
+**Performance**: 150x-12,500x faster than traditional solutions with 100% backward compatibility.
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow or standalone)
+- Understanding of agent architectures
+
+## Quick Start with CLI
+
+### Initialize AgentDB
+
+```bash
+# Initialize vector database
+npx agentdb@latest init ./agents.db
+
+# Or with custom dimensions
+npx agentdb@latest init ./agents.db --dimension 768
+
+# Use preset configurations
+npx agentdb@latest init ./agents.db --preset large
+
+# In-memory database for testing
+npx agentdb@latest init ./memory.db --in-memory
+```
+
+### Start MCP Server for Claude Code
+
+```bash
+# Start MCP server (integrates with Claude Code)
+npx agentdb@latest mcp
+
+# Add to Claude Code (one-time setup)
+claude mcp add agentdb npx agentdb@latest mcp
+```
+
+### Create Learning Plugin
+
+```bash
+# Interactive plugin wizard
+npx agentdb@latest create-plugin
+
+# Use template directly
+npx agentdb@latest create-plugin -t decision-transformer -n my-agent
+
+# Available templates:
+# - decision-transformer (sequence modeling RL)
+# - q-learning (value-based learning)
+# - sarsa (on-policy TD learning)
+# - actor-critic (policy gradient)
+# - curiosity-driven (exploration-based)
+```
+
+## Quick Start with API
+
+```typescript
+import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';
+
+// Initialize with default configuration
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/reasoningbank.db',
+  enableLearning: true,      // Enable learning plugins
+  enableReasoning: true,      // Enable reasoning agents
+  quantizationType: 'scalar', // binary | scalar | product | none
+  cacheSize: 1000,            // In-memory cache
+});
+
+// Store interaction memory
+const patternId = await adapter.insertPattern({
+  id: '',
+  type: 'pattern',
+  domain: 'conversation',
+  pattern_data: JSON.stringify({
+    embedding: await computeEmbedding('What is the capital of France?'),
+    pattern: {
+      user: 'What is the capital of France?',
+      assistant: 'The capital of France is Paris.',
+      timestamp: Date.now()
+    }
+  }),
+  confidence: 0.95,
+  usage_count: 1,
+  success_count: 1,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Retrieve context with reasoning
+const context = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'conversation',
+  k: 10,
+  useMMR: true,              // Maximal Marginal Relevance
+  synthesizeContext: true,    // Generate rich context
+});
+```
+
+## Memory Patterns
+
+### 1. Session Memory
+```typescript
+class SessionMemory {
+  async storeMessage(role: string, content: string) {
+    return await db.storeMemory({
+      sessionId: this.sessionId,
+      role,
+      content,
+      timestamp: Date.now()
+    });
+  }
+
+  async getSessionHistory(limit = 20) {
+    return await db.query({
+      filters: { sessionId: this.sessionId },
+      orderBy: 'timestamp',
+      limit
+    });
+  }
+}
+```
+
+### 2. Long-Term Memory
+```typescript
+// Store important facts
+await db.storeFact({
+  category: 'user_preference',
+  key: 'language',
+  value: 'English',
+  confidence: 1.0,
+  source: 'explicit'
+});
+
+// Retrieve facts
+const prefs = await db.getFacts({
+  category: 'user_preference'
+});
+```
+
+### 3. Pattern Learning
+```typescript
+// Learn from successful interactions
+await db.storePattern({
+  trigger: 'user_asks_time',
+  response: 'provide_formatted_time',
+  success: true,
+  context: { timezone: 'UTC' }
+});
+
+// Apply learned patterns
+const pattern = await db.matchPattern(currentContext);
+```
+
+## Advanced Patterns
+
+### Hierarchical Memory
+```typescript
+// Organize memory in hierarchy
+await memory.organize({
+  immediate: recentMessages,    // Last 10 messages
+  shortTerm: sessionContext,    // Current session
+  longTerm: importantFacts,     // Persistent facts
+  semantic: embeddedKnowledge   // Vector search
+});
+```
+
+### Memory Consolidation
+```typescript
+// Periodically consolidate memories
+await memory.consolidate({
+  strategy: 'importance',       // Keep important memories
+  maxSize: 10000,              // Size limit
+  minScore: 0.5                // Relevance threshold
+});
+```
+
+## CLI Operations
+
+### Query Database
+
+```bash
+# Query with vector embedding
+npx agentdb@latest query ./agents.db "[0.1,0.2,0.3,...]"
+
+# Top-k results
+npx agentdb@latest query ./agents.db "[0.1,0.2,0.3]" -k 10
+
+# With similarity threshold
+npx agentdb@latest query ./agents.db "0.1 0.2 0.3" -t 0.75
+
+# JSON output
+npx agentdb@latest query ./agents.db "[...]" -f json
+```
+
+### Import/Export Data
+
+```bash
+# Export vectors to file
+npx agentdb@latest export ./agents.db ./backup.json
+
+# Import vectors from file
+npx agentdb@latest import ./backup.json
+
+# Get database statistics
+npx agentdb@latest stats ./agents.db
+```
+
+### Performance Benchmarks
+
+```bash
+# Run performance benchmarks
+npx agentdb@latest benchmark
+
+# Results show:
+# - Pattern Search: 150x faster (100µs vs 15ms)
+# - Batch Insert: 500x faster (2ms vs 1s)
+# - Large-scale Query: 12,500x faster (8ms vs 100s)
+```
+
+## Integration with ReasoningBank
+
+```typescript
+import { createAgentDBAdapter, migrateToAgentDB } from 'agentic-flow/reasoningbank';
+
+// Migrate from legacy ReasoningBank
+const result = await migrateToAgentDB(
+  '.swarm/memory.db',           // Source (legacy)
+  '.agentdb/reasoningbank.db'   // Destination (AgentDB)
+);
+
+console.log(`✅ Migrated ${result.patternsMigrated} patterns`);
+
+// Train learning model
+const adapter = await createAgentDBAdapter({
+  enableLearning: true,
+});
+
+await adapter.train({
+  epochs: 50,
+  batchSize: 32,
+});
+
+// Get optimal strategy with reasoning
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'task-planning',
+  synthesizeContext: true,
+  optimizeMemory: true,
+});
+```
+
+## Learning Plugins
+
+### Available Algorithms (9 Total)
+
+1. **Decision Transformer** - Sequence modeling RL (recommended)
+2. **Q-Learning** - Value-based learning
+3. **SARSA** - On-policy TD learning
+4. **Actor-Critic** - Policy gradient with baseline
+5. **Active Learning** - Query selection
+6. **Adversarial Training** - Robustness
+7. **Curriculum Learning** - Progressive difficulty
+8. **Federated Learning** - Distributed learning
+9. **Multi-task Learning** - Transfer learning
+
+### List and Manage Plugins
+
+```bash
+# List available plugins
+npx agentdb@latest list-plugins
+
+# List plugin templates
+npx agentdb@latest list-templates
+
+# Get plugin info
+npx agentdb@latest plugin-info <name>
+```
+
+## Reasoning Agents (4 Modules)
+
+1. **PatternMatcher** - Find similar patterns with HNSW indexing
+2. **ContextSynthesizer** - Generate rich context from multiple sources
+3. **MemoryOptimizer** - Consolidate similar patterns, prune low-quality
+4. **ExperienceCurator** - Quality-based experience filtering
+
+## Best Practices
+
+1. **Enable quantization**: Use scalar/binary for 4-32x memory reduction
+2. **Use caching**: 1000 pattern cache for <1ms retrieval
+3. **Batch operations**: 500x faster than individual inserts
+4. **Train regularly**: Update learning models with new experiences
+5. **Enable reasoning**: Automatic context synthesis and optimization
+6. **Monitor metrics**: Use `stats` command to track performance
+
+## Troubleshooting
+
+### Issue: Memory growing too large
+```bash
+# Check database size
+npx agentdb@latest stats ./agents.db
+
+# Enable quantization
+# Use 'binary' (32x smaller) or 'scalar' (4x smaller)
+```
+
+### Issue: Slow search performance
+```bash
+# Enable HNSW indexing and caching
+# Results: <100µs search time
+```
+
+### Issue: Migration from legacy ReasoningBank
+```bash
+# Automatic migration with validation
+npx agentdb@latest migrate --source .swarm/memory.db
+```
+
+## Performance Characteristics
+
+- **Vector Search**: <100µs (HNSW indexing)
+- **Pattern Retrieval**: <1ms (with cache)
+- **Batch Insert**: 2ms for 100 patterns
+- **Memory Efficiency**: 4-32x reduction with quantization
+- **Backward Compatibility**: 100% compatible with ReasoningBank API
+
+## Learn More
+
+- GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- Documentation: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
+- MCP Integration: `npx agentdb@latest mcp` for Claude Code
+- Website: https://agentdb.ruv.io
@@ -0,0 +1,509 @@
+---
+name: "AgentDB Performance Optimization"
+description: "Optimize AgentDB performance with quantization (4-32x memory reduction), HNSW indexing (150x faster search), caching, and batch operations. Use when optimizing memory usage, improving search speed, or scaling to millions of vectors."
+---
+
+# AgentDB Performance Optimization
+
+## What This Skill Does
+
+Provides comprehensive performance optimization techniques for AgentDB vector databases. Achieve 150x-12,500x performance improvements through quantization, HNSW indexing, caching strategies, and batch operations. Reduce memory usage by 4-32x while maintaining accuracy.
+
+**Performance**: <100µs vector search, <1ms pattern retrieval, 2ms batch insert for 100 vectors.
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow)
+- Existing AgentDB database or application
+
+---
+
+## Quick Start
+
+### Run Performance Benchmarks
+
+```bash
+# Comprehensive performance benchmarking
+npx agentdb@latest benchmark
+
+# Results show:
+# ✅ Pattern Search: 150x faster (100µs vs 15ms)
+# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors)
+# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors)
+# ✅ Memory Efficiency: 4-32x reduction with quantization
+```
+
+### Enable Optimizations
+
+```typescript
+import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';
+
+// Optimized configuration
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/optimized.db',
+  quantizationType: 'binary',   // 32x memory reduction
+  cacheSize: 1000,               // In-memory cache
+  enableLearning: true,
+  enableReasoning: true,
+});
+```
+
+---
+
+## Quantization Strategies
+
+### 1. Binary Quantization (32x Reduction)
+
+**Best For**: Large-scale deployments (1M+ vectors), memory-constrained environments
+**Trade-off**: ~2-5% accuracy loss, 32x memory reduction, 10x faster
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'binary',
+  // 768-dim float32 (3072 bytes) → 96 bytes binary
+  // 1M vectors: 3GB → 96MB
+});
+```
+
+**Use Cases**:
+- Mobile/edge deployment
+- Large-scale vector storage (millions of vectors)
+- Real-time search with memory constraints
+
+**Performance**:
+- Memory: 32x smaller
+- Search Speed: 10x faster (bit operations)
+- Accuracy: 95-98% of original
+
+### 2. Scalar Quantization (4x Reduction)
+
+**Best For**: Balanced performance/accuracy, moderate datasets
+**Trade-off**: ~1-2% accuracy loss, 4x memory reduction, 3x faster
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'scalar',
+  // 768-dim float32 (3072 bytes) → 768 bytes (uint8)
+  // 1M vectors: 3GB → 768MB
+});
+```
+
+**Use Cases**:
+- Production applications requiring high accuracy
+- Medium-scale deployments (10K-1M vectors)
+- General-purpose optimization
+
+**Performance**:
+- Memory: 4x smaller
+- Search Speed: 3x faster
+- Accuracy: 98-99% of original
+
+### 3. Product Quantization (8-16x Reduction)
+
+**Best For**: High-dimensional vectors, balanced compression
+**Trade-off**: ~3-7% accuracy loss, 8-16x memory reduction, 5x faster
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'product',
+  // 768-dim float32 (3072 bytes) → 48-96 bytes
+  // 1M vectors: 3GB → 192MB
+});
+```
+
+**Use Cases**:
+- High-dimensional embeddings (>512 dims)
+- Image/video embeddings
+- Large-scale similarity search
+
+**Performance**:
+- Memory: 8-16x smaller
+- Search Speed: 5x faster
+- Accuracy: 93-97% of original
+
+### 4. No Quantization (Full Precision)
+
+**Best For**: Maximum accuracy, small datasets
+**Trade-off**: No accuracy loss, full memory usage
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'none',
+  // Full float32 precision
+});
+```
+
+---
+
+## HNSW Indexing
+
+**Hierarchical Navigable Small World** - O(log n) search complexity
+
+### Automatic HNSW
+
+AgentDB automatically builds HNSW indices:
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/vectors.db',
+  // HNSW automatically enabled
+});
+
+// Search with HNSW (100µs vs 15ms linear scan)
+const results = await adapter.retrieveWithReasoning(queryEmbedding, {
+  k: 10,
+});
+```
+
+### HNSW Parameters
+
+```typescript
+// Advanced HNSW configuration
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/vectors.db',
+  hnswM: 16,              // Connections per layer (default: 16)
+  hnswEfConstruction: 200, // Build quality (default: 200)
+  hnswEfSearch: 100,       // Search quality (default: 100)
+});
+```
+
+**Parameter Tuning**:
+- **M** (connections): Higher = better recall, more memory
+  - Small datasets (<10K): M = 8
+  - Medium datasets (10K-100K): M = 16
+  - Large datasets (>100K): M = 32
+- **efConstruction**: Higher = better index quality, slower build
+  - Fast build: 100
+  - Balanced: 200 (default)
+  - High quality: 400
+- **efSearch**: Higher = better recall, slower search
+  - Fast search: 50
+  - Balanced: 100 (default)
+  - High recall: 200
+
+---
+
+## Caching Strategies
+
+### In-Memory Pattern Cache
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  cacheSize: 1000,  // Cache 1000 most-used patterns
+});
+
+// First retrieval: ~2ms (database)
+// Subsequent: <1ms (cache hit)
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  k: 10,
+});
+```
+
+**Cache Tuning**:
+- Small applications: 100-500 patterns
+- Medium applications: 500-2000 patterns
+- Large applications: 2000-5000 patterns
+
+### LRU Cache Behavior
+
+```typescript
+// Cache automatically evicts least-recently-used patterns
+// Most frequently accessed patterns stay in cache
+
+// Monitor cache performance
+const stats = await adapter.getStats();
+console.log('Cache Hit Rate:', stats.cacheHitRate);
+// Aim for >80% hit rate
+```
+
+---
+
+## Batch Operations
+
+### Batch Insert (500x Faster)
+
+```typescript
+// ❌ SLOW: Individual inserts
+for (const doc of documents) {
+  await adapter.insertPattern({ /* ... */ });  // 1s for 100 docs
+}
+
+// ✅ FAST: Batch insert
+const patterns = documents.map(doc => ({
+  id: '',
+  type: 'document',
+  domain: 'knowledge',
+  pattern_data: JSON.stringify({
+    embedding: doc.embedding,
+    text: doc.text,
+  }),
+  confidence: 1.0,
+  usage_count: 0,
+  success_count: 0,
+  created_at: Date.now(),
+  last_used: Date.now(),
+}));
+
+// Insert all at once (2ms for 100 docs)
+for (const pattern of patterns) {
+  await adapter.insertPattern(pattern);
+}
+```
+
+### Batch Retrieval
+
+```typescript
+// Retrieve multiple queries efficiently
+const queries = [queryEmbedding1, queryEmbedding2, queryEmbedding3];
+
+// Parallel retrieval
+const results = await Promise.all(
+  queries.map(q => adapter.retrieveWithReasoning(q, { k: 5 }))
+);
+```
+
+---
+
+## Memory Optimization
+
+### Automatic Consolidation
+
+```typescript
+// Enable automatic pattern consolidation
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'documents',
+  optimizeMemory: true,  // Consolidate similar patterns
+  k: 10,
+});
+
+console.log('Optimizations:', result.optimizations);
+// {
+//   consolidated: 15,  // Merged 15 similar patterns
+//   pruned: 3,         // Removed 3 low-quality patterns
+//   improved_quality: 0.12  // 12% quality improvement
+// }
+```
+
+### Manual Optimization
+
+```typescript
+// Manually trigger optimization
+await adapter.optimize();
+
+// Get statistics
+const stats = await adapter.getStats();
+console.log('Before:', stats.totalPatterns);
+console.log('After:', stats.totalPatterns);  // Reduced by ~10-30%
+```
+
+### Pruning Strategies
+
+```typescript
+// Prune low-confidence patterns
+await adapter.prune({
+  minConfidence: 0.5,     // Remove confidence < 0.5
+  minUsageCount: 2,       // Remove usage_count < 2
+  maxAge: 30 * 24 * 3600, // Remove >30 days old
+});
+```
+
+---
+
+## Performance Monitoring
+
+### Database Statistics
+
+```bash
+# Get comprehensive stats
+npx agentdb@latest stats .agentdb/vectors.db
+
+# Output:
+# Total Patterns: 125,430
+# Database Size: 47.2 MB (with binary quantization)
+# Avg Confidence: 0.87
+# Domains: 15
+# Cache Hit Rate: 84%
+# Index Type: HNSW
+```
+
+### Runtime Metrics
+
+```typescript
+const stats = await adapter.getStats();
+
+console.log('Performance Metrics:');
+console.log('Total Patterns:', stats.totalPatterns);
+console.log('Database Size:', stats.dbSize);
+console.log('Avg Confidence:', stats.avgConfidence);
+console.log('Cache Hit Rate:', stats.cacheHitRate);
+console.log('Search Latency (avg):', stats.avgSearchLatency);
+console.log('Insert Latency (avg):', stats.avgInsertLatency);
+```
+
+---
+
+## Optimization Recipes
+
+### Recipe 1: Maximum Speed (Sacrifice Accuracy)
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'binary',  // 32x memory reduction
+  cacheSize: 5000,             // Large cache
+  hnswM: 8,                    // Fewer connections = faster
+  hnswEfSearch: 50,            // Low search quality = faster
+});
+
+// Expected: <50µs search, 90-95% accuracy
+```
+
+### Recipe 2: Balanced Performance
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'scalar',  // 4x memory reduction
+  cacheSize: 1000,             // Standard cache
+  hnswM: 16,                   // Balanced connections
+  hnswEfSearch: 100,           // Balanced quality
+});
+
+// Expected: <100µs search, 98-99% accuracy
+```
+
+### Recipe 3: Maximum Accuracy
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'none',    // No quantization
+  cacheSize: 2000,             // Large cache
+  hnswM: 32,                   // Many connections
+  hnswEfSearch: 200,           // High search quality
+});
+
+// Expected: <200µs search, 100% accuracy
+```
+
+### Recipe 4: Memory-Constrained (Mobile/Edge)
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'binary',  // 32x memory reduction
+  cacheSize: 100,              // Small cache
+  hnswM: 8,                    // Minimal connections
+});
+
+// Expected: <100µs search, ~10MB for 100K vectors
+```
+
+---
+
+## Scaling Strategies
+
+### Small Scale (<10K vectors)
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'none',    // Full precision
+  cacheSize: 500,
+  hnswM: 8,
+});
+```
+
+### Medium Scale (10K-100K vectors)
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'scalar',  // 4x reduction
+  cacheSize: 1000,
+  hnswM: 16,
+});
+```
+
+### Large Scale (100K-1M vectors)
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'binary',  // 32x reduction
+  cacheSize: 2000,
+  hnswM: 32,
+});
+```
+
+### Massive Scale (>1M vectors)
+
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'product',  // 8-16x reduction
+  cacheSize: 5000,
+  hnswM: 48,
+  hnswEfConstruction: 400,
+});
+```
+
+---
+
+## Troubleshooting
+
+### Issue: High memory usage
+
+```bash
+# Check database size
+npx agentdb@latest stats .agentdb/vectors.db
+
+# Enable quantization
+# Use 'binary' for 32x reduction
+```
+
+### Issue: Slow search performance
+
+```typescript
+// Increase cache size
+const adapter = await createAgentDBAdapter({
+  cacheSize: 2000,  // Increase from 1000
+});
+
+// Reduce search quality (faster)
+const result = await adapter.retrieveWithReasoning(queryEmbedding, {
+  k: 5,  // Reduce from 10
+});
+```
+
+### Issue: Low accuracy
+
+```typescript
+// Disable or use lighter quantization
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'scalar',  // Instead of 'binary'
+  hnswEfSearch: 200,           // Higher search quality
+});
+```
+
+---
+
+## Performance Benchmarks
+
+**Test System**: AMD Ryzen 9 5950X, 64GB RAM
+
+| Operation | Vector Count | No Optimization | Optimized | Improvement |
+|-----------|-------------|-----------------|-----------|-------------|
+| Search | 10K | 15ms | 100µs | 150x |
+| Search | 100K | 150ms | 120µs | 1,250x |
+| Search | 1M | 100s | 8ms | 12,500x |
+| Batch Insert (100) | - | 1s | 2ms | 500x |
+| Memory Usage | 1M | 3GB | 96MB | 32x (binary) |
+
+---
+
+## Learn More
+
+- **Quantization Paper**: docs/quantization-techniques.pdf
+- **HNSW Algorithm**: docs/hnsw-index.pdf
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- **Website**: https://agentdb.ruv.io
+
+---
+
+**Category**: Performance / Optimization
+**Difficulty**: Intermediate
+**Estimated Time**: 20-30 minutes
@@ -0,0 +1,339 @@
+---
+name: "AgentDB Vector Search"
+description: "Implement semantic vector search with AgentDB for intelligent document retrieval, similarity matching, and context-aware querying. Use when building RAG systems, semantic search engines, or intelligent knowledge bases."
+---
+
+# AgentDB Vector Search
+
+## What This Skill Does
+
+Implements vector-based semantic search using AgentDB's high-performance vector database with **150x-12,500x faster** operations than traditional solutions. Features HNSW indexing, quantization, and sub-millisecond search (<100µs).
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow or standalone)
+- OpenAI API key (for embeddings) or custom embedding model
+
+## Quick Start with CLI
+
+### Initialize Vector Database
+
+```bash
+# Initialize with default dimensions (1536 for OpenAI ada-002)
+npx agentdb@latest init ./vectors.db
+
+# Custom dimensions for different embedding models
+npx agentdb@latest init ./vectors.db --dimension 768  # sentence-transformers
+npx agentdb@latest init ./vectors.db --dimension 384  # all-MiniLM-L6-v2
+
+# Use preset configurations
+npx agentdb@latest init ./vectors.db --preset small   # <10K vectors
+npx agentdb@latest init ./vectors.db --preset medium  # 10K-100K vectors
+npx agentdb@latest init ./vectors.db --preset large   # >100K vectors
+
+# In-memory database for testing
+npx agentdb@latest init ./vectors.db --in-memory
+```
+
+### Query Vector Database
+
+```bash
+# Basic similarity search
+npx agentdb@latest query ./vectors.db "[0.1,0.2,0.3,...]"
+
+# Top-k results
+npx agentdb@latest query ./vectors.db "[0.1,0.2,0.3]" -k 10
+
+# With similarity threshold (cosine similarity)
+npx agentdb@latest query ./vectors.db "0.1 0.2 0.3" -t 0.75 -m cosine
+
+# Different distance metrics
+npx agentdb@latest query ./vectors.db "[...]" -m euclidean  # L2 distance
+npx agentdb@latest query ./vectors.db "[...]" -m dot        # Dot product
+
+# JSON output for automation
+npx agentdb@latest query ./vectors.db "[...]" -f json -k 5
+
+# Verbose output with distances
+npx agentdb@latest query ./vectors.db "[...]" -v
+```
+
+### Import/Export Vectors
+
+```bash
+# Export vectors to JSON
+npx agentdb@latest export ./vectors.db ./backup.json
+
+# Import vectors from JSON
+npx agentdb@latest import ./backup.json
+
+# Get database statistics
+npx agentdb@latest stats ./vectors.db
+```
+
+## Quick Start with API
+
+```typescript
+import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank';
+
+// Initialize with vector search optimizations
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/vectors.db',
+  enableLearning: false,       // Vector search only
+  enableReasoning: true,       // Enable semantic matching
+  quantizationType: 'binary',  // 32x memory reduction
+  cacheSize: 1000,             // Fast retrieval
+});
+
+// Store document with embedding
+const text = "The quantum computer achieved 100 qubits";
+const embedding = await computeEmbedding(text);
+
+await adapter.insertPattern({
+  id: '',
+  type: 'document',
+  domain: 'technology',
+  pattern_data: JSON.stringify({
+    embedding,
+    text,
+    metadata: { category: "quantum", date: "2025-01-15" }
+  }),
+  confidence: 1.0,
+  usage_count: 0,
+  success_count: 0,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Semantic search with MMR (Maximal Marginal Relevance)
+const queryEmbedding = await computeEmbedding("quantum computing advances");
+const results = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'technology',
+  k: 10,
+  useMMR: true,              // Diverse results
+  synthesizeContext: true,    // Rich context
+});
+```
+
+## Core Features
+
+### 1. Vector Storage
+```typescript
+// Store with automatic embedding
+await db.storeWithEmbedding({
+  content: "Your document text",
+  metadata: { source: "docs", page: 42 }
+});
+```
+
+### 2. Similarity Search
+```typescript
+// Find similar documents
+const similar = await db.findSimilar("quantum computing", {
+  limit: 5,
+  minScore: 0.75
+});
+```
+
+### 3. Hybrid Search (Vector + Metadata)
+```typescript
+// Combine vector similarity with metadata filtering
+const results = await db.hybridSearch({
+  query: "machine learning models",
+  filters: {
+    category: "research",
+    date: { $gte: "2024-01-01" }
+  },
+  limit: 20
+});
+```
+
+## Advanced Usage
+
+### RAG (Retrieval Augmented Generation)
+```typescript
+// Build RAG pipeline
+async function ragQuery(question: string) {
+  // 1. Get relevant context
+  const context = await db.searchSimilar(
+    await embed(question),
+    { limit: 5, threshold: 0.7 }
+  );
+
+  // 2. Generate answer with context
+  const prompt = `Context: ${context.map(c => c.text).join('\n')}
+Question: ${question}`;
+
+  return await llm.generate(prompt);
+}
+```
+
+### Batch Operations
+```typescript
+// Efficient batch storage
+await db.batchStore(documents.map(doc => ({
+  text: doc.content,
+  embedding: doc.vector,
+  metadata: doc.meta
+})));
+```
+
+## MCP Server Integration
+
+```bash
+# Start AgentDB MCP server for Claude Code
+npx agentdb@latest mcp
+
+# Add to Claude Code (one-time setup)
+claude mcp add agentdb npx agentdb@latest mcp
+
+# Now use MCP tools in Claude Code:
+# - agentdb_query: Semantic vector search
+# - agentdb_store: Store documents with embeddings
+# - agentdb_stats: Database statistics
+```
+
+## Performance Benchmarks
+
+```bash
+# Run comprehensive benchmarks
+npx agentdb@latest benchmark
+
+# Results:
+# ✅ Pattern Search: 150x faster (100µs vs 15ms)
+# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors)
+# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors)
+# ✅ Memory Efficiency: 4-32x reduction with quantization
+```
+
+## Quantization Options
+
+AgentDB provides multiple quantization strategies for memory efficiency:
+
+### Binary Quantization (32x reduction)
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'binary',  // 768-dim → 96 bytes
+});
+```
+
+### Scalar Quantization (4x reduction)
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'scalar',  // 768-dim → 768 bytes
+});
+```
+
+### Product Quantization (8-16x reduction)
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'product',  // 768-dim → 48-96 bytes
+});
+```
+
+## Distance Metrics
+
+```bash
+# Cosine similarity (default, best for most use cases)
+npx agentdb@latest query ./db.sqlite "[...]" -m cosine
+
+# Euclidean distance (L2 norm)
+npx agentdb@latest query ./db.sqlite "[...]" -m euclidean
+
+# Dot product (for normalized vectors)
+npx agentdb@latest query ./db.sqlite "[...]" -m dot
+```
+
+## Advanced Features
+
+### HNSW Indexing
+- **O(log n) search complexity**
+- **Sub-millisecond retrieval** (<100µs)
+- **Automatic index building**
+
+### Caching
+- **1000 pattern in-memory cache**
+- **<1ms pattern retrieval**
+- **Automatic cache invalidation**
+
+### MMR (Maximal Marginal Relevance)
+- **Diverse result sets**
+- **Avoid redundancy**
+- **Balance relevance and diversity**
+
+## Performance Tips
+
+1. **Enable HNSW indexing**: Automatic with AgentDB, 10-100x faster
+2. **Use quantization**: Binary (32x), Scalar (4x), Product (8-16x) memory reduction
+3. **Batch operations**: 500x faster for bulk inserts
+4. **Match dimensions**: 1536 (OpenAI), 768 (sentence-transformers), 384 (MiniLM)
+5. **Similarity threshold**: Start at 0.7 for quality, adjust based on use case
+6. **Enable caching**: 1000 pattern cache for frequent queries
+
+## Troubleshooting
+
+### Issue: Slow search performance
+```bash
+# Check if HNSW indexing is enabled (automatic)
+npx agentdb@latest stats ./vectors.db
+
+# Expected: <100µs search time
+```
+
+### Issue: High memory usage
+```bash
+# Enable binary quantization (32x reduction)
+# Use in adapter: quantizationType: 'binary'
+```
+
+### Issue: Poor relevance
+```bash
+# Adjust similarity threshold
+npx agentdb@latest query ./db.sqlite "[...]" -t 0.8  # Higher threshold
+
+# Or use MMR for diverse results
+# Use in adapter: useMMR: true
+```
+
+### Issue: Wrong dimensions
+```bash
+# Check embedding model dimensions:
+# - OpenAI ada-002: 1536
+# - sentence-transformers: 768
+# - all-MiniLM-L6-v2: 384
+
+npx agentdb@latest init ./db.sqlite --dimension 768
+```
+
+## Database Statistics
+
+```bash
+# Get comprehensive stats
+npx agentdb@latest stats ./vectors.db
+
+# Shows:
+# - Total patterns/vectors
+# - Database size
+# - Average confidence
+# - Domains distribution
+# - Index status
+```
+
+## Performance Characteristics
+
+- **Vector Search**: <100µs (HNSW indexing)
+- **Pattern Retrieval**: <1ms (with cache)
+- **Batch Insert**: 2ms for 100 vectors
+- **Memory Efficiency**: 4-32x reduction with quantization
+- **Scalability**: Handles 1M+ vectors efficiently
+- **Latency**: Sub-millisecond for most operations
+
+## Learn More
+
+- GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- Documentation: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
+- MCP Integration: `npx agentdb@latest mcp` for Claude Code
+- Website: https://agentdb.ruv.io
+- CLI Help: `npx agentdb@latest --help`
+- Command Help: `npx agentdb@latest help <command>`
@@ -0,0 +1,645 @@
+---
+name: agentic-jujutsu
+version: 2.3.2
+description: Quantum-resistant, self-learning version control for AI agents with ReasoningBank intelligence and multi-agent coordination
+---
+
+# Agentic Jujutsu - AI Agent Version Control
+
+> Quantum-ready, self-learning version control designed for multiple AI agents working simultaneously without conflicts.
+
+## When to Use This Skill
+
+Use **agentic-jujutsu** when you need:
+- ✅ Multiple AI agents modifying code simultaneously
+- ✅ Lock-free version control (23x faster than Git)
+- ✅ Self-learning AI that improves from experience
+- ✅ Quantum-resistant security for future-proof protection
+- ✅ Automatic conflict resolution (87% success rate)
+- ✅ Pattern recognition and intelligent suggestions
+- ✅ Multi-agent coordination without blocking
+
+## Quick Start
+
+### Installation
+
+```bash
+npx agentic-jujutsu
+```
+
+### Basic Usage
+
+```javascript
+const { JjWrapper } = require('agentic-jujutsu');
+
+const jj = new JjWrapper();
+
+// Basic operations
+await jj.status();
+await jj.newCommit('Add feature');
+await jj.log(10);
+
+// Self-learning trajectory
+const id = jj.startTrajectory('Implement authentication');
+await jj.branchCreate('feature/auth');
+await jj.newCommit('Add auth');
+jj.addToTrajectory();
+jj.finalizeTrajectory(0.9, 'Clean implementation');
+
+// Get AI suggestions
+const suggestion = JSON.parse(jj.getSuggestion('Add logout feature'));
+console.log(`Confidence: ${suggestion.confidence}`);
+```
+
+## Core Capabilities
+
+### 1. Self-Learning with ReasoningBank
+
+Track operations, learn patterns, and get intelligent suggestions:
+
+```javascript
+// Start learning trajectory
+const trajectoryId = jj.startTrajectory('Deploy to production');
+
+// Perform operations (automatically tracked)
+await jj.execute(['git', 'push', 'origin', 'main']);
+await jj.branchCreate('release/v1.0');
+await jj.newCommit('Release v1.0');
+
+// Record operations to trajectory
+jj.addToTrajectory();
+
+// Finalize with success score (0.0-1.0) and critique
+jj.finalizeTrajectory(0.95, 'Deployment successful, no issues');
+
+// Later: Get AI-powered suggestions for similar tasks
+const suggestion = JSON.parse(jj.getSuggestion('Deploy to staging'));
+console.log('AI Recommendation:', suggestion.reasoning);
+console.log('Confidence:', (suggestion.confidence * 100).toFixed(1) + '%');
+console.log('Expected Success:', (suggestion.expectedSuccessRate * 100).toFixed(1) + '%');
+```
+
+**Validation (v2.3.1)**:
+- ✅ Tasks must be non-empty (max 10KB)
+- ✅ Success scores must be 0.0-1.0
+- ✅ Must have operations before finalizing
+- ✅ Contexts cannot be empty
+
+### 2. Pattern Discovery
+
+Automatically identify successful operation sequences:
+
+```javascript
+// Get discovered patterns
+const patterns = JSON.parse(jj.getPatterns());
+
+patterns.forEach(pattern => {
+    console.log(`Pattern: ${pattern.name}`);
+    console.log(`  Success rate: ${(pattern.successRate * 100).toFixed(1)}%`);
+    console.log(`  Used ${pattern.observationCount} times`);
+    console.log(`  Operations: ${pattern.operationSequence.join(' → ')}`);
+    console.log(`  Confidence: ${(pattern.confidence * 100).toFixed(1)}%`);
+});
+```
+
+### 3. Learning Statistics
+
+Track improvement over time:
+
+```javascript
+const stats = JSON.parse(jj.getLearningStats());
+
+console.log('Learning Progress:');
+console.log(`  Total trajectories: ${stats.totalTrajectories}`);
+console.log(`  Patterns discovered: ${stats.totalPatterns}`);
+console.log(`  Average success: ${(stats.avgSuccessRate * 100).toFixed(1)}%`);
+console.log(`  Improvement rate: ${(stats.improvementRate * 100).toFixed(1)}%`);
+console.log(`  Prediction accuracy: ${(stats.predictionAccuracy * 100).toFixed(1)}%`);
+```
+
+### 4. Multi-Agent Coordination
+
+Multiple agents work concurrently without conflicts:
+
+```javascript
+// Agent 1: Developer
+const dev = new JjWrapper();
+dev.startTrajectory('Implement feature');
+await dev.newCommit('Add feature X');
+dev.addToTrajectory();
+dev.finalizeTrajectory(0.85);
+
+// Agent 2: Reviewer (learns from Agent 1)
+const reviewer = new JjWrapper();
+const suggestion = JSON.parse(reviewer.getSuggestion('Review feature X'));
+
+if (suggestion.confidence > 0.7) {
+    console.log('High confidence approach:', suggestion.reasoning);
+}
+
+// Agent 3: Tester (benefits from both)
+const tester = new JjWrapper();
+const similar = JSON.parse(tester.queryTrajectories('test feature', 5));
+console.log(`Found ${similar.length} similar test approaches`);
+```
+
+### 5. Quantum-Resistant Security (v2.3.0+)
+
+Fast integrity verification with quantum-resistant cryptography:
+
+```javascript
+const { generateQuantumFingerprint, verifyQuantumFingerprint } = require('agentic-jujutsu');
+
+// Generate SHA3-512 fingerprint (NIST FIPS 202)
+const data = Buffer.from('commit-data');
+const fingerprint = generateQuantumFingerprint(data);
+console.log('Fingerprint:', fingerprint.toString('hex'));
+
+// Verify integrity (<1ms)
+const isValid = verifyQuantumFingerprint(data, fingerprint);
+console.log('Valid:', isValid);
+
+// HQC-128 encryption for trajectories
+const crypto = require('crypto');
+const key = crypto.randomBytes(32).toString('base64');
+jj.enableEncryption(key);
+```
+
+### 6. Operation Tracking with AgentDB
+
+Automatic tracking of all operations:
+
+```javascript
+// Operations are tracked automatically
+await jj.status();
+await jj.newCommit('Fix bug');
+await jj.rebase('main');
+
+// Get operation statistics
+const stats = JSON.parse(jj.getStats());
+console.log(`Total operations: ${stats.total_operations}`);
+console.log(`Success rate: ${(stats.success_rate * 100).toFixed(1)}%`);
+console.log(`Avg duration: ${stats.avg_duration_ms.toFixed(2)}ms`);
+
+// Query recent operations
+const ops = jj.getOperations(10);
+ops.forEach(op => {
+    console.log(`${op.operationType}: ${op.command}`);
+    console.log(`  Duration: ${op.durationMs}ms, Success: ${op.success}`);
+});
+
+// Get user operations (excludes snapshots)
+const userOps = jj.getUserOperations(20);
+```
+
+## Advanced Use Cases
+
+### Use Case 1: Adaptive Workflow Optimization
+
+Learn and improve deployment workflows:
+
+```javascript
+async function adaptiveDeployment(jj, environment) {
+    // Get AI suggestion based on past deployments
+    const suggestion = JSON.parse(jj.getSuggestion(`Deploy to ${environment}`));
+    
+    console.log(`Deploying with ${(suggestion.confidence * 100).toFixed(0)}% confidence`);
+    console.log(`Expected duration: ${suggestion.estimatedDurationMs}ms`);
+    
+    // Start tracking
+    jj.startTrajectory(`Deploy to ${environment}`);
+    
+    // Execute recommended operations
+    for (const op of suggestion.recommendedOperations) {
+        console.log(`Executing: ${op}`);
+        await executeOperation(op);
+    }
+    
+    jj.addToTrajectory();
+    
+    // Record outcome
+    const success = await verifyDeployment();
+    jj.finalizeTrajectory(
+        success ? 0.95 : 0.5,
+        success ? 'Deployment successful' : 'Issues detected'
+    );
+}
+```
+
+### Use Case 2: Multi-Agent Code Review
+
+Coordinate review across multiple agents:
+
+```javascript
+async function coordinatedReview(agents) {
+    const reviews = await Promise.all(agents.map(async (agent) => {
+        const jj = new JjWrapper();
+        
+        // Start review trajectory
+        jj.startTrajectory(`Review by ${agent.name}`);
+        
+        // Get AI suggestion for review approach
+        const suggestion = JSON.parse(jj.getSuggestion('Code review'));
+        
+        // Perform review
+        const diff = await jj.diff('@', '@-');
+        const issues = await agent.analyze(diff);
+        
+        jj.addToTrajectory();
+        jj.finalizeTrajectory(
+            issues.length === 0 ? 0.9 : 0.6,
+            `Found ${issues.length} issues`
+        );
+        
+        return { agent: agent.name, issues, suggestion };
+    }));
+    
+    // Aggregate learning from all agents
+    return reviews;
+}
+```
+
+### Use Case 3: Error Pattern Detection
+
+Learn from failures to prevent future issues:
+
+```javascript
+async function smartMerge(jj, branch) {
+    // Query similar merge attempts
+    const similar = JSON.parse(jj.queryTrajectories(`merge ${branch}`, 10));
+    
+    // Analyze past failures
+    const failures = similar.filter(t => t.successScore < 0.5);
+    
+    if (failures.length > 0) {
+        console.log('⚠️ Similar merges failed in the past:');
+        failures.forEach(f => {
+            if (f.critique) {
+                console.log(`  - ${f.critique}`);
+            }
+        });
+    }
+    
+    // Get AI recommendation
+    const suggestion = JSON.parse(jj.getSuggestion(`merge ${branch}`));
+    
+    if (suggestion.confidence < 0.7) {
+        console.log('⚠️ Low confidence. Recommended steps:');
+        suggestion.recommendedOperations.forEach(op => console.log(`  - ${op}`));
+    }
+    
+    // Execute merge with tracking
+    jj.startTrajectory(`Merge ${branch}`);
+    try {
+        await jj.execute(['merge', branch]);
+        jj.addToTrajectory();
+        jj.finalizeTrajectory(0.9, 'Merge successful');
+    } catch (err) {
+        jj.addToTrajectory();
+        jj.finalizeTrajectory(0.3, `Merge failed: ${err.message}`);
+        throw err;
+    }
+}
+```
+
+### Use Case 4: Continuous Learning Loop
+
+Implement a self-improving agent:
+
+```javascript
+class SelfImprovingAgent {
+    constructor() {
+        this.jj = new JjWrapper();
+    }
+    
+    async performTask(taskDescription) {
+        // Get AI suggestion
+        const suggestion = JSON.parse(this.jj.getSuggestion(taskDescription));
+        
+        console.log(`Task: ${taskDescription}`);
+        console.log(`AI Confidence: ${(suggestion.confidence * 100).toFixed(1)}%`);
+        console.log(`Expected Success: ${(suggestion.expectedSuccessRate * 100).toFixed(1)}%`);
+        
+        // Start trajectory
+        this.jj.startTrajectory(taskDescription);
+        
+        // Execute with recommended approach
+        const startTime = Date.now();
+        let success = false;
+        
+        try {
+            for (const op of suggestion.recommendedOperations) {
+                await this.execute(op);
+            }
+            success = true;
+        } catch (err) {
+            console.error('Task failed:', err.message);
+        }
+        
+        const duration = Date.now() - startTime;
+        
+        // Record learning
+        this.jj.addToTrajectory();
+        this.jj.finalizeTrajectory(
+            success ? 0.9 : 0.4,
+            success 
+                ? `Completed in ${duration}ms using ${suggestion.recommendedOperations.length} operations`
+                : `Failed after ${duration}ms`
+        );
+        
+        // Check improvement
+        const stats = JSON.parse(this.jj.getLearningStats());
+        console.log(`Improvement rate: ${(stats.improvementRate * 100).toFixed(1)}%`);
+        
+        return success;
+    }
+    
+    async execute(operation) {
+        // Execute operation logic
+    }
+}
+
+// Usage
+const agent = new SelfImprovingAgent();
+
+// Agent improves over time
+for (let i = 1; i <= 10; i++) {
+    console.log(`\n--- Attempt ${i} ---`);
+    await agent.performTask('Deploy application');
+}
+```
+
+## API Reference
+
+### Core Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `new JjWrapper()` | Create wrapper instance | JjWrapper |
+| `status()` | Get repository status | Promise<JjResult> |
+| `newCommit(msg)` | Create new commit | Promise<JjResult> |
+| `log(limit)` | Show commit history | Promise<JjCommit[]> |
+| `diff(from, to)` | Show differences | Promise<JjDiff> |
+| `branchCreate(name, rev?)` | Create branch | Promise<JjResult> |
+| `rebase(source, dest)` | Rebase commits | Promise<JjResult> |
+
+### ReasoningBank Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `startTrajectory(task)` | Begin learning trajectory | string (trajectory ID) |
+| `addToTrajectory()` | Add recent operations | void |
+| `finalizeTrajectory(score, critique?)` | Complete trajectory (score: 0.0-1.0) | void |
+| `getSuggestion(task)` | Get AI recommendation | JSON: DecisionSuggestion |
+| `getLearningStats()` | Get learning metrics | JSON: LearningStats |
+| `getPatterns()` | Get discovered patterns | JSON: Pattern[] |
+| `queryTrajectories(task, limit)` | Find similar trajectories | JSON: Trajectory[] |
+| `resetLearning()` | Clear learned data | void |
+
+### AgentDB Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `getStats()` | Get operation statistics | JSON: Stats |
+| `getOperations(limit)` | Get recent operations | JjOperation[] |
+| `getUserOperations(limit)` | Get user operations only | JjOperation[] |
+| `clearLog()` | Clear operation log | void |
+
+### Quantum Security Methods (v2.3.0+)
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `generateQuantumFingerprint(data)` | Generate SHA3-512 fingerprint | Buffer (64 bytes) |
+| `verifyQuantumFingerprint(data, fp)` | Verify fingerprint | boolean |
+| `enableEncryption(key, pubKey?)` | Enable HQC-128 encryption | void |
+| `disableEncryption()` | Disable encryption | void |
+| `isEncryptionEnabled()` | Check encryption status | boolean |
+
+## Performance Characteristics
+
+| Metric | Git | Agentic Jujutsu |
+|--------|-----|-----------------|
+| Concurrent commits | 15 ops/s | 350 ops/s (23x) |
+| Context switching | 500-1000ms | 50-100ms (10x) |
+| Conflict resolution | 30-40% auto | 87% auto (2.5x) |
+| Lock waiting | 50 min/day | 0 min (∞) |
+| Quantum fingerprints | N/A | <1ms |
+
+## Best Practices
+
+### 1. Trajectory Management
+
+```javascript
+// ✅ Good: Meaningful task descriptions
+jj.startTrajectory('Implement user authentication with JWT');
+
+// ❌ Bad: Vague descriptions
+jj.startTrajectory('fix stuff');
+
+// ✅ Good: Honest success scores
+jj.finalizeTrajectory(0.7, 'Works but needs refactoring');
+
+// ❌ Bad: Always 1.0
+jj.finalizeTrajectory(1.0, 'Perfect!'); // Prevents learning
+```
+
+### 2. Pattern Recognition
+
+```javascript
+// ✅ Good: Let patterns emerge naturally
+for (let i = 0; i < 10; i++) {
+    jj.startTrajectory('Deploy feature');
+    await deploy();
+    jj.addToTrajectory();
+    jj.finalizeTrajectory(wasSuccessful ? 0.9 : 0.5);
+}
+
+// ❌ Bad: Not recording outcomes
+await deploy(); // No learning
+```
+
+### 3. Multi-Agent Coordination
+
+```javascript
+// ✅ Good: Concurrent operations
+const agents = ['agent1', 'agent2', 'agent3'];
+await Promise.all(agents.map(async (agent) => {
+    const jj = new JjWrapper();
+    // Each agent works independently
+    await jj.newCommit(`Changes by ${agent}`);
+}));
+
+// ❌ Bad: Sequential with locks
+for (const agent of agents) {
+    await agent.waitForLock(); // Not needed!
+    await agent.commit();
+}
+```
+
+### 4. Error Handling
+
+```javascript
+// ✅ Good: Record failures with details
+try {
+    await jj.execute(['complex-operation']);
+    jj.finalizeTrajectory(0.9);
+} catch (err) {
+    jj.finalizeTrajectory(0.3, `Failed: ${err.message}. Root cause: ...`);
+}
+
+// ❌ Bad: Silent failures
+try {
+    await jj.execute(['operation']);
+} catch (err) {
+    // No learning from failure
+}
+```
+
+## Validation Rules (v2.3.1+)
+
+### Task Description
+- ✅ Cannot be empty or whitespace-only
+- ✅ Maximum length: 10,000 bytes
+- ✅ Automatically trimmed
+
+### Success Score
+- ✅ Must be finite (not NaN or Infinity)
+- ✅ Must be between 0.0 and 1.0 (inclusive)
+
+### Operations
+- ✅ Must have at least one operation before finalizing
+
+### Context
+- ✅ Cannot be empty
+- ✅ Keys cannot be empty or whitespace-only
+- ✅ Keys max 1,000 bytes, values max 10,000 bytes
+
+## Troubleshooting
+
+### Issue: Low Confidence Suggestions
+
+```javascript
+const suggestion = JSON.parse(jj.getSuggestion('new task'));
+
+if (suggestion.confidence < 0.5) {
+    // Not enough data - check learning stats
+    const stats = JSON.parse(jj.getLearningStats());
+    console.log(`Need more data. Current trajectories: ${stats.totalTrajectories}`);
+    
+    // Recommend: Record 5-10 trajectories first
+}
+```
+
+### Issue: Validation Errors
+
+```javascript
+try {
+    jj.startTrajectory(''); // Empty task
+} catch (err) {
+    if (err.message.includes('Validation error')) {
+        console.log('Invalid input:', err.message);
+        // Use non-empty, meaningful task description
+    }
+}
+
+try {
+    jj.finalizeTrajectory(1.5); // Score > 1.0
+} catch (err) {
+    // Use score between 0.0 and 1.0
+    jj.finalizeTrajectory(Math.max(0, Math.min(1, score)));
+}
+```
+
+### Issue: No Patterns Discovered
+
+```javascript
+const patterns = JSON.parse(jj.getPatterns());
+
+if (patterns.length === 0) {
+    // Need more trajectories with >70% success
+    // Record at least 3-5 successful trajectories
+}
+```
+
+## Examples
+
+### Example 1: Simple Learning Workflow
+
+```javascript
+const { JjWrapper } = require('agentic-jujutsu');
+
+async function learnFromWork() {
+    const jj = new JjWrapper();
+    
+    // Start tracking
+    jj.startTrajectory('Add user profile feature');
+    
+    // Do work
+    await jj.branchCreate('feature/user-profile');
+    await jj.newCommit('Add user profile model');
+    await jj.newCommit('Add profile API endpoints');
+    await jj.newCommit('Add profile UI');
+    
+    // Record operations
+    jj.addToTrajectory();
+    
+    // Finalize with result
+    jj.finalizeTrajectory(0.85, 'Feature complete, minor styling issues remain');
+    
+    // Next time, get suggestions
+    const suggestion = JSON.parse(jj.getSuggestion('Add settings page'));
+    console.log('AI suggests:', suggestion.reasoning);
+}
+```
+
+### Example 2: Multi-Agent Swarm
+
+```javascript
+async function agentSwarm(taskList) {
+    const agents = taskList.map((task, i) => ({
+        name: `agent-${i}`,
+        jj: new JjWrapper(),
+        task
+    }));
+    
+    // All agents work concurrently (no conflicts!)
+    const results = await Promise.all(agents.map(async (agent) => {
+        agent.jj.startTrajectory(agent.task);
+        
+        // Get AI suggestion
+        const suggestion = JSON.parse(agent.jj.getSuggestion(agent.task));
+        
+        // Execute task
+        const success = await executeTask(agent, suggestion);
+        
+        agent.jj.addToTrajectory();
+        agent.jj.finalizeTrajectory(success ? 0.9 : 0.5);
+        
+        return { agent: agent.name, success };
+    }));
+    
+    console.log('Results:', results);
+}
+```
+
+## Related Documentation
+
+- **NPM Package**: https://npmjs.com/package/agentic-jujutsu
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentic-jujutsu
+- **Full README**: See package README.md
+- **Validation Guide**: docs/VALIDATION_FIXES_v2.3.1.md
+- **AgentDB Guide**: docs/AGENTDB_GUIDE.md
+
+## Version History
+
+- **v2.3.2** - Documentation updates
+- **v2.3.1** - Validation fixes for ReasoningBank
+- **v2.3.0** - Quantum-resistant security with @qudag/napi-core
+- **v2.1.0** - Self-learning AI with ReasoningBank
+- **v2.0.0** - Zero-dependency installation with embedded jj binary
+
+---
+
+**Status**: ✅ Production Ready
+**License**: MIT
+**Maintained**: Active
@@ -0,0 +1,738 @@
+---
+name: flow-nexus-neural
+description: Train and deploy neural networks in distributed E2B sandboxes with Flow Nexus
+version: 1.0.0
+category: ai-ml
+tags:
+  - neural-networks
+  - distributed-training
+  - machine-learning
+  - deep-learning
+  - flow-nexus
+  - e2b-sandboxes
+requires_auth: true
+mcp_server: flow-nexus
+---
+
+# Flow Nexus Neural Networks
+
+Deploy, train, and manage neural networks in distributed E2B sandbox environments. Train custom models with multiple architectures (feedforward, LSTM, GAN, transformer) or use pre-built templates from the marketplace.
+
+## Prerequisites
+
+```bash
+# Add Flow Nexus MCP server
+claude mcp add flow-nexus npx flow-nexus@latest mcp start
+
+# Register and login
+npx flow-nexus@latest register
+npx flow-nexus@latest login
+```
+
+## Core Capabilities
+
+### 1. Single-Node Neural Training
+
+Train neural networks with custom architectures and configurations.
+
+**Available Architectures:**
+- `feedforward` - Standard fully-connected networks
+- `lstm` - Long Short-Term Memory for sequences
+- `gan` - Generative Adversarial Networks
+- `autoencoder` - Dimensionality reduction
+- `transformer` - Attention-based models
+
+**Training Tiers:**
+- `nano` - Minimal resources (fast, limited)
+- `mini` - Small models
+- `small` - Standard models
+- `medium` - Complex models
+- `large` - Large-scale training
+
+#### Example: Train Custom Classifier
+
+```javascript
+mcp__flow-nexus__neural_train({
+  config: {
+    architecture: {
+      type: "feedforward",
+      layers: [
+        { type: "dense", units: 256, activation: "relu" },
+        { type: "dropout", rate: 0.3 },
+        { type: "dense", units: 128, activation: "relu" },
+        { type: "dropout", rate: 0.2 },
+        { type: "dense", units: 64, activation: "relu" },
+        { type: "dense", units: 10, activation: "softmax" }
+      ]
+    },
+    training: {
+      epochs: 100,
+      batch_size: 32,
+      learning_rate: 0.001,
+      optimizer: "adam"
+    },
+    divergent: {
+      enabled: true,
+      pattern: "lateral", // quantum, chaotic, associative, evolutionary
+      factor: 0.5
+    }
+  },
+  tier: "small",
+  user_id: "your_user_id"
+})
+```
+
+#### Example: LSTM for Time Series
+
+```javascript
+mcp__flow-nexus__neural_train({
+  config: {
+    architecture: {
+      type: "lstm",
+      layers: [
+        { type: "lstm", units: 128, return_sequences: true },
+        { type: "dropout", rate: 0.2 },
+        { type: "lstm", units: 64 },
+        { type: "dense", units: 1, activation: "linear" }
+      ]
+    },
+    training: {
+      epochs: 150,
+      batch_size: 64,
+      learning_rate: 0.01,
+      optimizer: "adam"
+    }
+  },
+  tier: "medium"
+})
+```
+
+#### Example: Transformer Architecture
+
+```javascript
+mcp__flow-nexus__neural_train({
+  config: {
+    architecture: {
+      type: "transformer",
+      layers: [
+        { type: "embedding", vocab_size: 10000, embedding_dim: 512 },
+        { type: "transformer_encoder", num_heads: 8, ff_dim: 2048 },
+        { type: "global_average_pooling" },
+        { type: "dense", units: 128, activation: "relu" },
+        { type: "dense", units: 2, activation: "softmax" }
+      ]
+    },
+    training: {
+      epochs: 50,
+      batch_size: 16,
+      learning_rate: 0.0001,
+      optimizer: "adam"
+    }
+  },
+  tier: "large"
+})
+```
+
+### 2. Model Inference
+
+Run predictions on trained models.
+
+```javascript
+mcp__flow-nexus__neural_predict({
+  model_id: "model_abc123",
+  input: [
+    [0.5, 0.3, 0.2, 0.1],
+    [0.8, 0.1, 0.05, 0.05],
+    [0.2, 0.6, 0.15, 0.05]
+  ],
+  user_id: "your_user_id"
+})
+```
+
+**Response:**
+```json
+{
+  "predictions": [
+    [0.12, 0.85, 0.03],
+    [0.89, 0.08, 0.03],
+    [0.05, 0.92, 0.03]
+  ],
+  "inference_time_ms": 45,
+  "model_version": "1.0.0"
+}
+```
+
+### 3. Template Marketplace
+
+Browse and deploy pre-trained models from the marketplace.
+
+#### List Available Templates
+
+```javascript
+mcp__flow-nexus__neural_list_templates({
+  category: "classification", // timeseries, regression, nlp, vision, anomaly, generative
+  tier: "free", // or "paid"
+  search: "sentiment",
+  limit: 20
+})
+```
+
+**Response:**
+```json
+{
+  "templates": [
+    {
+      "id": "sentiment-analysis-v2",
+      "name": "Sentiment Analysis Classifier",
+      "description": "Pre-trained BERT model for sentiment analysis",
+      "category": "nlp",
+      "accuracy": 0.94,
+      "downloads": 1523,
+      "tier": "free"
+    },
+    {
+      "id": "image-classifier-resnet",
+      "name": "ResNet Image Classifier",
+      "description": "ResNet-50 for image classification",
+      "category": "vision",
+      "accuracy": 0.96,
+      "downloads": 2341,
+      "tier": "paid"
+    }
+  ]
+}
+```
+
+#### Deploy Template
+
+```javascript
+mcp__flow-nexus__neural_deploy_template({
+  template_id: "sentiment-analysis-v2",
+  custom_config: {
+    training: {
+      epochs: 50,
+      learning_rate: 0.0001
+    }
+  },
+  user_id: "your_user_id"
+})
+```
+
+### 4. Distributed Training Clusters
+
+Train large models across multiple E2B sandboxes with distributed computing.
+
+#### Initialize Cluster
+
+```javascript
+mcp__flow-nexus__neural_cluster_init({
+  name: "large-model-cluster",
+  architecture: "transformer", // transformer, cnn, rnn, gnn, hybrid
+  topology: "mesh", // mesh, ring, star, hierarchical
+  consensus: "proof-of-learning", // byzantine, raft, gossip
+  daaEnabled: true, // Decentralized Autonomous Agents
+  wasmOptimization: true
+})
+```
+
+**Response:**
+```json
+{
+  "cluster_id": "cluster_xyz789",
+  "name": "large-model-cluster",
+  "status": "initializing",
+  "topology": "mesh",
+  "max_nodes": 100,
+  "created_at": "2025-10-19T10:30:00Z"
+}
+```
+
+#### Deploy Worker Nodes
+
+```javascript
+// Deploy parameter server
+mcp__flow-nexus__neural_node_deploy({
+  cluster_id: "cluster_xyz789",
+  node_type: "parameter_server",
+  model: "large",
+  template: "nodejs",
+  capabilities: ["parameter_management", "gradient_aggregation"],
+  autonomy: 0.8
+})
+
+// Deploy worker nodes
+mcp__flow-nexus__neural_node_deploy({
+  cluster_id: "cluster_xyz789",
+  node_type: "worker",
+  model: "xl",
+  role: "worker",
+  capabilities: ["training", "inference"],
+  layers: [
+    { type: "transformer_encoder", num_heads: 16 },
+    { type: "feed_forward", units: 4096 }
+  ],
+  autonomy: 0.9
+})
+
+// Deploy aggregator
+mcp__flow-nexus__neural_node_deploy({
+  cluster_id: "cluster_xyz789",
+  node_type: "aggregator",
+  model: "large",
+  capabilities: ["gradient_aggregation", "model_synchronization"]
+})
+```
+
+#### Connect Cluster Topology
+
+```javascript
+mcp__flow-nexus__neural_cluster_connect({
+  cluster_id: "cluster_xyz789",
+  topology: "mesh" // Override default if needed
+})
+```
+
+#### Start Distributed Training
+
+```javascript
+mcp__flow-nexus__neural_train_distributed({
+  cluster_id: "cluster_xyz789",
+  dataset: "imagenet", // or custom dataset identifier
+  epochs: 100,
+  batch_size: 128,
+  learning_rate: 0.001,
+  optimizer: "adam", // sgd, rmsprop, adagrad
+  federated: true // Enable federated learning
+})
+```
+
+**Federated Learning Example:**
+```javascript
+mcp__flow-nexus__neural_train_distributed({
+  cluster_id: "cluster_xyz789",
+  dataset: "medical_images_distributed",
+  epochs: 200,
+  batch_size: 64,
+  learning_rate: 0.0001,
+  optimizer: "adam",
+  federated: true, // Data stays on local nodes
+  aggregation_rounds: 50,
+  min_nodes_per_round: 5
+})
+```
+
+#### Monitor Cluster Status
+
+```javascript
+mcp__flow-nexus__neural_cluster_status({
+  cluster_id: "cluster_xyz789"
+})
+```
+
+**Response:**
+```json
+{
+  "cluster_id": "cluster_xyz789",
+  "status": "training",
+  "nodes": [
+    {
+      "node_id": "node_001",
+      "type": "parameter_server",
+      "status": "active",
+      "cpu_usage": 0.75,
+      "memory_usage": 0.82
+    },
+    {
+      "node_id": "node_002",
+      "type": "worker",
+      "status": "active",
+      "training_progress": 0.45
+    }
+  ],
+  "training_metrics": {
+    "current_epoch": 45,
+    "total_epochs": 100,
+    "loss": 0.234,
+    "accuracy": 0.891
+  }
+}
+```
+
+#### Run Distributed Inference
+
+```javascript
+mcp__flow-nexus__neural_predict_distributed({
+  cluster_id: "cluster_xyz789",
+  input_data: JSON.stringify([
+    [0.1, 0.2, 0.3],
+    [0.4, 0.5, 0.6]
+  ]),
+  aggregation: "ensemble" // mean, majority, weighted, ensemble
+})
+```
+
+#### Terminate Cluster
+
+```javascript
+mcp__flow-nexus__neural_cluster_terminate({
+  cluster_id: "cluster_xyz789"
+})
+```
+
+### 5. Model Management
+
+#### List Your Models
+
+```javascript
+mcp__flow-nexus__neural_list_models({
+  user_id: "your_user_id",
+  include_public: true
+})
+```
+
+**Response:**
+```json
+{
+  "models": [
+    {
+      "model_id": "model_abc123",
+      "name": "Custom Classifier v1",
+      "architecture": "feedforward",
+      "accuracy": 0.92,
+      "created_at": "2025-10-15T14:20:00Z",
+      "status": "trained"
+    },
+    {
+      "model_id": "model_def456",
+      "name": "LSTM Forecaster",
+      "architecture": "lstm",
+      "mse": 0.0045,
+      "created_at": "2025-10-18T09:15:00Z",
+      "status": "training"
+    }
+  ]
+}
+```
+
+#### Check Training Status
+
+```javascript
+mcp__flow-nexus__neural_training_status({
+  job_id: "job_training_xyz"
+})
+```
+
+**Response:**
+```json
+{
+  "job_id": "job_training_xyz",
+  "status": "training",
+  "progress": 0.67,
+  "current_epoch": 67,
+  "total_epochs": 100,
+  "current_loss": 0.234,
+  "estimated_completion": "2025-10-19T12:45:00Z"
+}
+```
+
+#### Performance Benchmarking
+
+```javascript
+mcp__flow-nexus__neural_performance_benchmark({
+  model_id: "model_abc123",
+  benchmark_type: "comprehensive" // inference, throughput, memory, comprehensive
+})
+```
+
+**Response:**
+```json
+{
+  "model_id": "model_abc123",
+  "benchmarks": {
+    "inference_latency_ms": 12.5,
+    "throughput_qps": 8000,
+    "memory_usage_mb": 245,
+    "gpu_utilization": 0.78,
+    "accuracy": 0.92,
+    "f1_score": 0.89
+  },
+  "timestamp": "2025-10-19T11:00:00Z"
+}
+```
+
+#### Create Validation Workflow
+
+```javascript
+mcp__flow-nexus__neural_validation_workflow({
+  model_id: "model_abc123",
+  user_id: "your_user_id",
+  validation_type: "comprehensive" // performance, accuracy, robustness, comprehensive
+})
+```
+
+### 6. Publishing and Marketplace
+
+#### Publish Model as Template
+
+```javascript
+mcp__flow-nexus__neural_publish_template({
+  model_id: "model_abc123",
+  name: "High-Accuracy Sentiment Classifier",
+  description: "Fine-tuned BERT model for sentiment analysis with 94% accuracy",
+  category: "nlp",
+  price: 0, // 0 for free, or credits amount
+  user_id: "your_user_id"
+})
+```
+
+#### Rate a Template
+
+```javascript
+mcp__flow-nexus__neural_rate_template({
+  template_id: "sentiment-analysis-v2",
+  rating: 5,
+  review: "Excellent model! Achieved 95% accuracy on my dataset.",
+  user_id: "your_user_id"
+})
+```
+
+## Common Use Cases
+
+### Image Classification with CNN
+
+```javascript
+// Initialize cluster for large-scale image training
+const cluster = await mcp__flow-nexus__neural_cluster_init({
+  name: "image-classification-cluster",
+  architecture: "cnn",
+  topology: "hierarchical",
+  wasmOptimization: true
+})
+
+// Deploy worker nodes
+await mcp__flow-nexus__neural_node_deploy({
+  cluster_id: cluster.cluster_id,
+  node_type: "worker",
+  model: "large",
+  capabilities: ["training", "data_augmentation"]
+})
+
+// Start training
+await mcp__flow-nexus__neural_train_distributed({
+  cluster_id: cluster.cluster_id,
+  dataset: "custom_images",
+  epochs: 100,
+  batch_size: 64,
+  learning_rate: 0.001,
+  optimizer: "adam"
+})
+```
+
+### NLP Sentiment Analysis
+
+```javascript
+// Use pre-built template
+const deployment = await mcp__flow-nexus__neural_deploy_template({
+  template_id: "sentiment-analysis-v2",
+  custom_config: {
+    training: {
+      epochs: 30,
+      batch_size: 16
+    }
+  }
+})
+
+// Run inference
+const result = await mcp__flow-nexus__neural_predict({
+  model_id: deployment.model_id,
+  input: ["This product is amazing!", "Terrible experience."]
+})
+```
+
+### Time Series Forecasting
+
+```javascript
+// Train LSTM model
+const training = await mcp__flow-nexus__neural_train({
+  config: {
+    architecture: {
+      type: "lstm",
+      layers: [
+        { type: "lstm", units: 128, return_sequences: true },
+        { type: "dropout", rate: 0.2 },
+        { type: "lstm", units: 64 },
+        { type: "dense", units: 1 }
+      ]
+    },
+    training: {
+      epochs: 150,
+      batch_size: 64,
+      learning_rate: 0.01,
+      optimizer: "adam"
+    }
+  },
+  tier: "medium"
+})
+
+// Monitor progress
+const status = await mcp__flow-nexus__neural_training_status({
+  job_id: training.job_id
+})
+```
+
+### Federated Learning for Privacy
+
+```javascript
+// Initialize federated cluster
+const cluster = await mcp__flow-nexus__neural_cluster_init({
+  name: "federated-medical-cluster",
+  architecture: "transformer",
+  topology: "mesh",
+  consensus: "proof-of-learning",
+  daaEnabled: true
+})
+
+// Deploy nodes across different locations
+for (let i = 0; i < 5; i++) {
+  await mcp__flow-nexus__neural_node_deploy({
+    cluster_id: cluster.cluster_id,
+    node_type: "worker",
+    model: "large",
+    autonomy: 0.9
+  })
+}
+
+// Train with federated learning (data never leaves nodes)
+await mcp__flow-nexus__neural_train_distributed({
+  cluster_id: cluster.cluster_id,
+  dataset: "medical_records_distributed",
+  epochs: 200,
+  federated: true,
+  aggregation_rounds: 100
+})
+```
+
+## Architecture Patterns
+
+### Feedforward Networks
+Best for: Classification, regression, simple pattern recognition
+```javascript
+{
+  type: "feedforward",
+  layers: [
+    { type: "dense", units: 256, activation: "relu" },
+    { type: "dropout", rate: 0.3 },
+    { type: "dense", units: 128, activation: "relu" },
+    { type: "dense", units: 10, activation: "softmax" }
+  ]
+}
+```
+
+### LSTM Networks
+Best for: Time series, sequences, forecasting
+```javascript
+{
+  type: "lstm",
+  layers: [
+    { type: "lstm", units: 128, return_sequences: true },
+    { type: "lstm", units: 64 },
+    { type: "dense", units: 1 }
+  ]
+}
+```
+
+### Transformers
+Best for: NLP, attention mechanisms, large-scale text
+```javascript
+{
+  type: "transformer",
+  layers: [
+    { type: "embedding", vocab_size: 10000, embedding_dim: 512 },
+    { type: "transformer_encoder", num_heads: 8, ff_dim: 2048 },
+    { type: "global_average_pooling" },
+    { type: "dense", units: 2, activation: "softmax" }
+  ]
+}
+```
+
+### GANs
+Best for: Generative tasks, image synthesis
+```javascript
+{
+  type: "gan",
+  generator_layers: [...],
+  discriminator_layers: [...]
+}
+```
+
+### Autoencoders
+Best for: Dimensionality reduction, anomaly detection
+```javascript
+{
+  type: "autoencoder",
+  encoder_layers: [
+    { type: "dense", units: 128, activation: "relu" },
+    { type: "dense", units: 64, activation: "relu" }
+  ],
+  decoder_layers: [
+    { type: "dense", units: 128, activation: "relu" },
+    { type: "dense", units: input_dim, activation: "sigmoid" }
+  ]
+}
+```
+
+## Best Practices
+
+1. **Start Small**: Begin with `nano` or `mini` tiers for experimentation
+2. **Use Templates**: Leverage marketplace templates for common tasks
+3. **Monitor Training**: Check status regularly to catch issues early
+4. **Benchmark Models**: Always benchmark before production deployment
+5. **Distributed Training**: Use clusters for large models (>1B parameters)
+6. **Federated Learning**: Use for privacy-sensitive data
+7. **Version Models**: Publish successful models as templates for reuse
+8. **Validate Thoroughly**: Use validation workflows before deployment
+
+## Troubleshooting
+
+### Training Stalled
+```javascript
+// Check cluster status
+const status = await mcp__flow-nexus__neural_cluster_status({
+  cluster_id: "cluster_id"
+})
+
+// Terminate and restart if needed
+await mcp__flow-nexus__neural_cluster_terminate({
+  cluster_id: "cluster_id"
+})
+```
+
+### Low Accuracy
+- Increase epochs
+- Adjust learning rate
+- Add regularization (dropout)
+- Try different optimizer
+- Use data augmentation
+
+### Out of Memory
+- Reduce batch size
+- Use smaller model tier
+- Enable gradient accumulation
+- Use distributed training
+
+## Related Skills
+
+- `flow-nexus-sandbox` - E2B sandbox management
+- `flow-nexus-swarm` - AI swarm orchestration
+- `flow-nexus-workflow` - Workflow automation
+
+## Resources
+
+- Flow Nexus Docs: https://flow-nexus.ruv.io/docs
+- Neural Network Guide: https://flow-nexus.ruv.io/docs/neural
+- Template Marketplace: https://flow-nexus.ruv.io/templates
+- API Reference: https://flow-nexus.ruv.io/api
+
+---
+
+**Note**: Distributed training requires authentication. Register at https://flow-nexus.ruv.io or use `npx flow-nexus@latest register`.
@@ -0,0 +1,610 @@
+---
+name: flow-nexus-swarm
+description: Cloud-based AI swarm deployment and event-driven workflow automation with Flow Nexus platform
+category: orchestration
+tags: [swarm, workflow, cloud, agents, automation, message-queue]
+version: 1.0.0
+requires:
+  - flow-nexus MCP server
+  - Active Flow Nexus account (register at flow-nexus.ruv.io)
+---
+
+# Flow Nexus Swarm & Workflow Orchestration
+
+Deploy and manage cloud-based AI agent swarms with event-driven workflow automation, message queue processing, and intelligent agent coordination.
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Swarm Management](#swarm-management)
+3. [Workflow Automation](#workflow-automation)
+4. [Agent Orchestration](#agent-orchestration)
+5. [Templates & Patterns](#templates--patterns)
+6. [Advanced Features](#advanced-features)
+7. [Best Practices](#best-practices)
+
+## Overview
+
+Flow Nexus provides cloud-based orchestration for AI agent swarms with:
+
+- **Multi-topology Support**: Hierarchical, mesh, ring, and star architectures
+- **Event-driven Workflows**: Message queue processing with async execution
+- **Template Library**: Pre-built swarm configurations for common use cases
+- **Intelligent Agent Assignment**: Vector similarity matching for optimal agent selection
+- **Real-time Monitoring**: Comprehensive metrics and audit trails
+- **Scalable Infrastructure**: Cloud-based execution with auto-scaling
+
+## Swarm Management
+
+### Initialize Swarm
+
+Create a new swarm with specified topology and configuration:
+
+```javascript
+mcp__flow-nexus__swarm_init({
+  topology: "hierarchical", // Options: mesh, ring, star, hierarchical
+  maxAgents: 8,
+  strategy: "balanced" // Options: balanced, specialized, adaptive
+})
+```
+
+**Topology Guide:**
+- **Hierarchical**: Tree structure with coordinator nodes (best for complex projects)
+- **Mesh**: Peer-to-peer collaboration (best for research and analysis)
+- **Ring**: Circular coordination (best for sequential workflows)
+- **Star**: Centralized hub (best for simple delegation)
+
+**Strategy Guide:**
+- **Balanced**: Equal distribution of workload across agents
+- **Specialized**: Agents focus on specific expertise areas
+- **Adaptive**: Dynamic adjustment based on task complexity
+
+### Spawn Agents
+
+Add specialized agents to the swarm:
+
+```javascript
+mcp__flow-nexus__agent_spawn({
+  type: "researcher", // Options: researcher, coder, analyst, optimizer, coordinator
+  name: "Lead Researcher",
+  capabilities: ["web_search", "analysis", "summarization"]
+})
+```
+
+**Agent Types:**
+- **Researcher**: Information gathering, web search, analysis
+- **Coder**: Code generation, refactoring, implementation
+- **Analyst**: Data analysis, pattern recognition, insights
+- **Optimizer**: Performance tuning, resource optimization
+- **Coordinator**: Task delegation, progress tracking, integration
+
+### Orchestrate Tasks
+
+Distribute tasks across the swarm:
+
+```javascript
+mcp__flow-nexus__task_orchestrate({
+  task: "Build a REST API with authentication and database integration",
+  strategy: "parallel", // Options: parallel, sequential, adaptive
+  maxAgents: 5,
+  priority: "high" // Options: low, medium, high, critical
+})
+```
+
+**Execution Strategies:**
+- **Parallel**: Maximum concurrency for independent subtasks
+- **Sequential**: Step-by-step execution with dependencies
+- **Adaptive**: AI-powered strategy selection based on task analysis
+
+### Monitor & Scale Swarms
+
+```javascript
+// Get detailed swarm status
+mcp__flow-nexus__swarm_status({
+  swarm_id: "optional-id" // Uses active swarm if not provided
+})
+
+// List all active swarms
+mcp__flow-nexus__swarm_list({
+  status: "active" // Options: active, destroyed, all
+})
+
+// Scale swarm up or down
+mcp__flow-nexus__swarm_scale({
+  target_agents: 10,
+  swarm_id: "optional-id"
+})
+
+// Gracefully destroy swarm
+mcp__flow-nexus__swarm_destroy({
+  swarm_id: "optional-id"
+})
+```
+
+## Workflow Automation
+
+### Create Workflow
+
+Define event-driven workflows with message queue processing:
+
+```javascript
+mcp__flow-nexus__workflow_create({
+  name: "CI/CD Pipeline",
+  description: "Automated testing, building, and deployment",
+  steps: [
+    {
+      id: "test",
+      action: "run_tests",
+      agent: "tester",
+      parallel: true
+    },
+    {
+      id: "build",
+      action: "build_app",
+      agent: "builder",
+      depends_on: ["test"]
+    },
+    {
+      id: "deploy",
+      action: "deploy_prod",
+      agent: "deployer",
+      depends_on: ["build"]
+    }
+  ],
+  triggers: ["push_to_main", "manual_trigger"],
+  metadata: {
+    priority: 10,
+    retry_policy: "exponential_backoff"
+  }
+})
+```
+
+**Workflow Features:**
+- **Dependency Management**: Define step dependencies with `depends_on`
+- **Parallel Execution**: Set `parallel: true` for concurrent steps
+- **Event Triggers**: GitHub events, schedules, manual triggers
+- **Retry Policies**: Automatic retry on transient failures
+- **Priority Queuing**: High-priority workflows execute first
+
+### Execute Workflow
+
+Run workflows synchronously or asynchronously:
+
+```javascript
+mcp__flow-nexus__workflow_execute({
+  workflow_id: "workflow_id",
+  input_data: {
+    branch: "main",
+    commit: "abc123",
+    environment: "production"
+  },
+  async: true // Queue-based execution for long-running workflows
+})
+```
+
+**Execution Modes:**
+- **Sync (async: false)**: Immediate execution, wait for completion
+- **Async (async: true)**: Message queue processing, non-blocking
+
+### Monitor Workflows
+
+```javascript
+// Get workflow status and metrics
+mcp__flow-nexus__workflow_status({
+  workflow_id: "id",
+  execution_id: "specific-run-id", // Optional
+  include_metrics: true
+})
+
+// List workflows with filters
+mcp__flow-nexus__workflow_list({
+  status: "running", // Options: running, completed, failed, pending
+  limit: 10,
+  offset: 0
+})
+
+// Get complete audit trail
+mcp__flow-nexus__workflow_audit_trail({
+  workflow_id: "id",
+  limit: 50,
+  start_time: "2025-01-01T00:00:00Z"
+})
+```
+
+### Agent Assignment
+
+Intelligently assign agents to workflow tasks:
+
+```javascript
+mcp__flow-nexus__workflow_agent_assign({
+  task_id: "task_id",
+  agent_type: "coder", // Preferred agent type
+  use_vector_similarity: true // AI-powered capability matching
+})
+```
+
+**Vector Similarity Matching:**
+- Analyzes task requirements and agent capabilities
+- Finds optimal agent based on past performance
+- Considers workload and availability
+
+### Queue Management
+
+Monitor and manage message queues:
+
+```javascript
+mcp__flow-nexus__workflow_queue_status({
+  queue_name: "optional-specific-queue",
+  include_messages: true // Show pending messages
+})
+```
+
+## Agent Orchestration
+
+### Full-Stack Development Pattern
+
+```javascript
+// 1. Initialize swarm with hierarchical topology
+mcp__flow-nexus__swarm_init({
+  topology: "hierarchical",
+  maxAgents: 8,
+  strategy: "specialized"
+})
+
+// 2. Spawn specialized agents
+mcp__flow-nexus__agent_spawn({ type: "coordinator", name: "Project Manager" })
+mcp__flow-nexus__agent_spawn({ type: "coder", name: "Backend Developer" })
+mcp__flow-nexus__agent_spawn({ type: "coder", name: "Frontend Developer" })
+mcp__flow-nexus__agent_spawn({ type: "coder", name: "Database Architect" })
+mcp__flow-nexus__agent_spawn({ type: "analyst", name: "QA Engineer" })
+
+// 3. Create development workflow
+mcp__flow-nexus__workflow_create({
+  name: "Full-Stack Development",
+  steps: [
+    { id: "requirements", action: "analyze_requirements", agent: "coordinator" },
+    { id: "db_design", action: "design_schema", agent: "Database Architect" },
+    { id: "backend", action: "build_api", agent: "Backend Developer", depends_on: ["db_design"] },
+    { id: "frontend", action: "build_ui", agent: "Frontend Developer", depends_on: ["requirements"] },
+    { id: "integration", action: "integrate", agent: "Backend Developer", depends_on: ["backend", "frontend"] },
+    { id: "testing", action: "qa_testing", agent: "QA Engineer", depends_on: ["integration"] }
+  ]
+})
+
+// 4. Execute workflow
+mcp__flow-nexus__workflow_execute({
+  workflow_id: "workflow_id",
+  input_data: {
+    project: "E-commerce Platform",
+    tech_stack: ["Node.js", "React", "PostgreSQL"]
+  }
+})
+```
+
+### Research & Analysis Pattern
+
+```javascript
+// 1. Initialize mesh topology for collaborative research
+mcp__flow-nexus__swarm_init({
+  topology: "mesh",
+  maxAgents: 5,
+  strategy: "balanced"
+})
+
+// 2. Spawn research agents
+mcp__flow-nexus__agent_spawn({ type: "researcher", name: "Primary Researcher" })
+mcp__flow-nexus__agent_spawn({ type: "researcher", name: "Secondary Researcher" })
+mcp__flow-nexus__agent_spawn({ type: "analyst", name: "Data Analyst" })
+mcp__flow-nexus__agent_spawn({ type: "analyst", name: "Insights Analyst" })
+
+// 3. Orchestrate research task
+mcp__flow-nexus__task_orchestrate({
+  task: "Research machine learning trends for 2025 and analyze market opportunities",
+  strategy: "parallel",
+  maxAgents: 4,
+  priority: "high"
+})
+```
+
+### CI/CD Pipeline Pattern
+
+```javascript
+mcp__flow-nexus__workflow_create({
+  name: "Deployment Pipeline",
+  description: "Automated testing, building, and multi-environment deployment",
+  steps: [
+    { id: "lint", action: "lint_code", agent: "code_quality", parallel: true },
+    { id: "unit_test", action: "unit_tests", agent: "test_runner", parallel: true },
+    { id: "integration_test", action: "integration_tests", agent: "test_runner", parallel: true },
+    { id: "build", action: "build_artifacts", agent: "builder", depends_on: ["lint", "unit_test", "integration_test"] },
+    { id: "security_scan", action: "security_scan", agent: "security", depends_on: ["build"] },
+    { id: "deploy_staging", action: "deploy", agent: "deployer", depends_on: ["security_scan"] },
+    { id: "smoke_test", action: "smoke_tests", agent: "test_runner", depends_on: ["deploy_staging"] },
+    { id: "deploy_prod", action: "deploy", agent: "deployer", depends_on: ["smoke_test"] }
+  ],
+  triggers: ["github_push", "github_pr_merged"],
+  metadata: {
+    priority: 10,
+    auto_rollback: true
+  }
+})
+```
+
+### Data Processing Pipeline Pattern
+
+```javascript
+mcp__flow-nexus__workflow_create({
+  name: "ETL Pipeline",
+  description: "Extract, Transform, Load data processing",
+  steps: [
+    { id: "extract", action: "extract_data", agent: "data_extractor" },
+    { id: "validate_raw", action: "validate_data", agent: "validator", depends_on: ["extract"] },
+    { id: "transform", action: "transform_data", agent: "transformer", depends_on: ["validate_raw"] },
+    { id: "enrich", action: "enrich_data", agent: "enricher", depends_on: ["transform"] },
+    { id: "load", action: "load_data", agent: "loader", depends_on: ["enrich"] },
+    { id: "validate_final", action: "validate_data", agent: "validator", depends_on: ["load"] }
+  ],
+  triggers: ["schedule:0 2 * * *"], // Daily at 2 AM
+  metadata: {
+    retry_policy: "exponential_backoff",
+    max_retries: 3
+  }
+})
+```
+
+## Templates & Patterns
+
+### Use Pre-built Templates
+
+```javascript
+// Create swarm from template
+mcp__flow-nexus__swarm_create_from_template({
+  template_name: "full-stack-dev",
+  overrides: {
+    maxAgents: 6,
+    strategy: "specialized"
+  }
+})
+
+// List available templates
+mcp__flow-nexus__swarm_templates_list({
+  category: "quickstart", // Options: quickstart, specialized, enterprise, custom, all
+  includeStore: true
+})
+```
+
+**Available Template Categories:**
+
+**Quickstart Templates:**
+- `full-stack-dev`: Complete web development swarm
+- `research-team`: Research and analysis swarm
+- `code-review`: Automated code review swarm
+- `data-pipeline`: ETL and data processing
+
+**Specialized Templates:**
+- `ml-development`: Machine learning project swarm
+- `mobile-dev`: Mobile app development
+- `devops-automation`: Infrastructure and deployment
+- `security-audit`: Security analysis and testing
+
+**Enterprise Templates:**
+- `enterprise-migration`: Large-scale system migration
+- `multi-repo-sync`: Multi-repository coordination
+- `compliance-review`: Regulatory compliance workflows
+- `incident-response`: Automated incident management
+
+### Custom Template Creation
+
+Save successful swarm configurations as reusable templates for future projects.
+
+## Advanced Features
+
+### Real-time Monitoring
+
+```javascript
+// Subscribe to execution streams
+mcp__flow-nexus__execution_stream_subscribe({
+  stream_type: "claude-flow-swarm",
+  deployment_id: "deployment_id"
+})
+
+// Get execution status
+mcp__flow-nexus__execution_stream_status({
+  stream_id: "stream_id"
+})
+
+// List files created during execution
+mcp__flow-nexus__execution_files_list({
+  stream_id: "stream_id",
+  created_by: "claude-flow"
+})
+```
+
+### Swarm Metrics & Analytics
+
+```javascript
+// Get swarm performance metrics
+mcp__flow-nexus__swarm_status({
+  swarm_id: "id"
+})
+
+// Analyze workflow efficiency
+mcp__flow-nexus__workflow_status({
+  workflow_id: "id",
+  include_metrics: true
+})
+```
+
+### Multi-Swarm Coordination
+
+Coordinate multiple swarms for complex, multi-phase projects:
+
+```javascript
+// Phase 1: Research swarm
+const researchSwarm = await mcp__flow-nexus__swarm_init({
+  topology: "mesh",
+  maxAgents: 4
+})
+
+// Phase 2: Development swarm
+const devSwarm = await mcp__flow-nexus__swarm_init({
+  topology: "hierarchical",
+  maxAgents: 8
+})
+
+// Phase 3: Testing swarm
+const testSwarm = await mcp__flow-nexus__swarm_init({
+  topology: "star",
+  maxAgents: 5
+})
+```
+
+## Best Practices
+
+### 1. Choose the Right Topology
+
+```javascript
+// Simple projects: Star
+mcp__flow-nexus__swarm_init({ topology: "star", maxAgents: 3 })
+
+// Collaborative work: Mesh
+mcp__flow-nexus__swarm_init({ topology: "mesh", maxAgents: 5 })
+
+// Complex projects: Hierarchical
+mcp__flow-nexus__swarm_init({ topology: "hierarchical", maxAgents: 10 })
+
+// Sequential workflows: Ring
+mcp__flow-nexus__swarm_init({ topology: "ring", maxAgents: 4 })
+```
+
+### 2. Optimize Agent Assignment
+
+```javascript
+// Use vector similarity for optimal matching
+mcp__flow-nexus__workflow_agent_assign({
+  task_id: "complex-task",
+  use_vector_similarity: true
+})
+```
+
+### 3. Implement Proper Error Handling
+
+```javascript
+mcp__flow-nexus__workflow_create({
+  name: "Resilient Workflow",
+  steps: [...],
+  metadata: {
+    retry_policy: "exponential_backoff",
+    max_retries: 3,
+    timeout: 300000, // 5 minutes
+    on_failure: "notify_and_rollback"
+  }
+})
+```
+
+### 4. Monitor and Scale
+
+```javascript
+// Regular monitoring
+const status = await mcp__flow-nexus__swarm_status()
+
+// Scale based on workload
+if (status.workload > 0.8) {
+  await mcp__flow-nexus__swarm_scale({ target_agents: status.agents + 2 })
+}
+```
+
+### 5. Use Async Execution for Long-Running Workflows
+
+```javascript
+// Long-running workflows should use message queues
+mcp__flow-nexus__workflow_execute({
+  workflow_id: "data-pipeline",
+  async: true // Non-blocking execution
+})
+
+// Monitor progress
+mcp__flow-nexus__workflow_queue_status({ include_messages: true })
+```
+
+### 6. Clean Up Resources
+
+```javascript
+// Destroy swarm when complete
+mcp__flow-nexus__swarm_destroy({ swarm_id: "id" })
+```
+
+### 7. Leverage Templates
+
+```javascript
+// Use proven templates instead of building from scratch
+mcp__flow-nexus__swarm_create_from_template({
+  template_name: "code-review",
+  overrides: { maxAgents: 4 }
+})
+```
+
+## Integration with Claude Flow
+
+Flow Nexus swarms integrate seamlessly with Claude Flow hooks:
+
+```bash
+# Pre-task coordination setup
+npx claude-flow@alpha hooks pre-task --description "Initialize swarm"
+
+# Post-task metrics export
+npx claude-flow@alpha hooks post-task --task-id "swarm-execution"
+```
+
+## Common Use Cases
+
+### 1. Multi-Repo Development
+- Coordinate development across multiple repositories
+- Synchronized testing and deployment
+- Cross-repo dependency management
+
+### 2. Research Projects
+- Distributed information gathering
+- Parallel analysis of different data sources
+- Collaborative synthesis and reporting
+
+### 3. DevOps Automation
+- Infrastructure as Code deployment
+- Multi-environment testing
+- Automated rollback and recovery
+
+### 4. Code Quality Workflows
+- Automated code review
+- Security scanning
+- Performance benchmarking
+
+### 5. Data Processing
+- Large-scale ETL pipelines
+- Real-time data transformation
+- Data validation and quality checks
+
+## Authentication & Setup
+
+```bash
+# Install Flow Nexus
+npm install -g flow-nexus@latest
+
+# Register account
+npx flow-nexus@latest register
+
+# Login
+npx flow-nexus@latest login
+
+# Add MCP server to Claude Code
+claude mcp add flow-nexus npx flow-nexus@latest mcp start
+```
+
+## Support & Resources
+
+- **Platform**: https://flow-nexus.ruv.io
+- **Documentation**: https://github.com/ruvnet/flow-nexus
+- **Issues**: https://github.com/ruvnet/flow-nexus/issues
+
+---
+
+**Remember**: Flow Nexus provides cloud-based orchestration infrastructure. For local execution and coordination, use the core `claude-flow` MCP server alongside Flow Nexus for maximum flexibility.
@@ -0,0 +1,874 @@
+---
+name: github-multi-repo
+version: 1.0.0
+description: Multi-repository coordination, synchronization, and architecture management with AI swarm orchestration
+category: github-integration
+tags: [multi-repo, synchronization, architecture, coordination, github]
+author: Claude Flow Team
+requires:
+  - ruv-swarm@^1.0.11
+  - gh-cli@^2.0.0
+capabilities:
+  - cross-repository coordination
+  - package synchronization
+  - architecture optimization
+  - template management
+  - distributed workflows
+---
+
+# GitHub Multi-Repository Coordination Skill
+
+## Overview
+
+Advanced multi-repository coordination system that combines swarm intelligence, package synchronization, and repository architecture optimization. This skill enables organization-wide automation, cross-project collaboration, and scalable repository management.
+
+## Core Capabilities
+
+### 🔄 Multi-Repository Swarm Coordination
+Cross-repository AI swarm orchestration for distributed development workflows.
+
+### 📦 Package Synchronization
+Intelligent dependency resolution and version alignment across multiple packages.
+
+### 🏗️ Repository Architecture
+Structure optimization and template management for scalable projects.
+
+### 🔗 Integration Management
+Cross-package integration testing and deployment coordination.
+
+## Quick Start
+
+### Initialize Multi-Repo Coordination
+```bash
+# Basic swarm initialization
+npx claude-flow skill run github-multi-repo init \
+  --repos "org/frontend,org/backend,org/shared" \
+  --topology hierarchical
+
+# Advanced initialization with synchronization
+npx claude-flow skill run github-multi-repo init \
+  --repos "org/frontend,org/backend,org/shared" \
+  --topology mesh \
+  --shared-memory \
+  --sync-strategy eventual
+```
+
+### Synchronize Packages
+```bash
+# Synchronize package versions and dependencies
+npx claude-flow skill run github-multi-repo sync \
+  --packages "claude-code-flow,ruv-swarm" \
+  --align-versions \
+  --update-docs
+```
+
+### Optimize Architecture
+```bash
+# Analyze and optimize repository structure
+npx claude-flow skill run github-multi-repo optimize \
+  --analyze-structure \
+  --suggest-improvements \
+  --create-templates
+```
+
+## Features
+
+### 1. Cross-Repository Swarm Orchestration
+
+#### Repository Discovery
+```javascript
+// Auto-discover related repositories with gh CLI
+const REPOS = Bash(`gh repo list my-organization --limit 100 \
+  --json name,description,languages,topics \
+  --jq '.[] | select(.languages | keys | contains(["TypeScript"]))'`)
+
+// Analyze repository dependencies
+const DEPS = Bash(`gh repo list my-organization --json name | \
+  jq -r '.[].name' | while read -r repo; do
+    gh api repos/my-organization/$repo/contents/package.json \
+      --jq '.content' 2>/dev/null | base64 -d | jq '{name, dependencies}'
+  done | jq -s '.'`)
+
+// Initialize swarm with discovered repositories
+mcp__claude-flow__swarm_init({
+  topology: "hierarchical",
+  maxAgents: 8,
+  metadata: { repos: REPOS, dependencies: DEPS }
+})
+```
+
+#### Synchronized Operations
+```javascript
+// Execute synchronized changes across repositories
+[Parallel Multi-Repo Operations]:
+  // Spawn coordination agents
+  Task("Repository Coordinator", "Coordinate changes across all repositories", "coordinator")
+  Task("Dependency Analyzer", "Analyze cross-repo dependencies", "analyst")
+  Task("Integration Tester", "Validate cross-repo changes", "tester")
+
+  // Get matching repositories
+  Bash(`gh repo list org --limit 100 --json name \
+    --jq '.[] | select(.name | test("-service$")) | .name' > /tmp/repos.txt`)
+
+  // Execute task across repositories
+  Bash(`cat /tmp/repos.txt | while read -r repo; do
+    gh repo clone org/$repo /tmp/$repo -- --depth=1
+    cd /tmp/$repo
+
+    # Apply changes
+    npm update
+    npm test
+
+    # Create PR if successful
+    if [ $? -eq 0 ]; then
+      git checkout -b update-dependencies-$(date +%Y%m%d)
+      git add -A
+      git commit -m "chore: Update dependencies"
+      git push origin HEAD
+      gh pr create --title "Update dependencies" --body "Automated update" --label "dependencies"
+    fi
+  done`)
+
+  // Track all operations
+  TodoWrite { todos: [
+    { id: "discover", content: "Discover all service repositories", status: "completed" },
+    { id: "update", content: "Update dependencies", status: "completed" },
+    { id: "test", content: "Run integration tests", status: "in_progress" },
+    { id: "pr", content: "Create pull requests", status: "pending" }
+  ]}
+```
+
+### 2. Package Synchronization
+
+#### Version Alignment
+```javascript
+// Synchronize package dependencies and versions
+[Complete Package Sync]:
+  // Initialize sync swarm
+  mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 5 })
+
+  // Spawn sync agents
+  Task("Sync Coordinator", "Coordinate version alignment", "coordinator")
+  Task("Dependency Analyzer", "Analyze dependencies", "analyst")
+  Task("Integration Tester", "Validate synchronization", "tester")
+
+  // Read package states
+  Read("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow/package.json")
+  Read("/workspaces/ruv-FANN/ruv-swarm/npm/package.json")
+
+  // Align versions using gh CLI
+  Bash(`gh api repos/:owner/:repo/git/refs \
+    -f ref='refs/heads/sync/package-alignment' \
+    -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')`)
+
+  // Update package.json files
+  Bash(`gh api repos/:owner/:repo/contents/package.json \
+    --method PUT \
+    -f message="feat: Align Node.js version requirements" \
+    -f branch="sync/package-alignment" \
+    -f content="$(cat aligned-package.json | base64)"`)
+
+  // Store sync state
+  mcp__claude-flow__memory_usage({
+    action: "store",
+    key: "sync/packages/status",
+    value: {
+      timestamp: Date.now(),
+      packages_synced: ["claude-code-flow", "ruv-swarm"],
+      status: "synchronized"
+    }
+  })
+```
+
+#### Documentation Synchronization
+```javascript
+// Synchronize CLAUDE.md files across packages
+[Documentation Sync]:
+  // Get source documentation
+  Bash(`gh api repos/:owner/:repo/contents/ruv-swarm/docs/CLAUDE.md \
+    --jq '.content' | base64 -d > /tmp/claude-source.md`)
+
+  // Update target documentation
+  Bash(`gh api repos/:owner/:repo/contents/claude-code-flow/CLAUDE.md \
+    --method PUT \
+    -f message="docs: Synchronize CLAUDE.md" \
+    -f branch="sync/documentation" \
+    -f content="$(cat /tmp/claude-source.md | base64)"`)
+
+  // Track sync status
+  mcp__claude-flow__memory_usage({
+    action: "store",
+    key: "sync/documentation/status",
+    value: { status: "synchronized", files: ["CLAUDE.md"] }
+  })
+```
+
+#### Cross-Package Integration
+```javascript
+// Coordinate feature implementation across packages
+[Cross-Package Feature]:
+  // Push changes to all packages
+  mcp__github__push_files({
+    branch: "feature/github-integration",
+    files: [
+      {
+        path: "claude-code-flow/.claude/commands/github/github-modes.md",
+        content: "[GitHub modes documentation]"
+      },
+      {
+        path: "ruv-swarm/src/github-coordinator/hooks.js",
+        content: "[GitHub coordination hooks]"
+      }
+    ],
+    message: "feat: Add GitHub workflow integration"
+  })
+
+  // Create coordinated PR
+  Bash(`gh pr create \
+    --title "Feature: GitHub Workflow Integration" \
+    --body "## 🚀 GitHub Integration
+
+### Features
+- ✅ Multi-repo coordination
+- ✅ Package synchronization
+- ✅ Architecture optimization
+
+### Testing
+- [x] Package dependency verification
+- [x] Integration tests
+- [x] Cross-package compatibility"`)
+```
+
+### 3. Repository Architecture
+
+#### Structure Analysis
+```javascript
+// Analyze and optimize repository structure
+[Architecture Analysis]:
+  // Initialize architecture swarm
+  mcp__claude-flow__swarm_init({ topology: "hierarchical", maxAgents: 6 })
+
+  // Spawn architecture agents
+  Task("Senior Architect", "Analyze repository structure", "architect")
+  Task("Structure Analyst", "Identify optimization opportunities", "analyst")
+  Task("Performance Optimizer", "Optimize structure for scalability", "optimizer")
+  Task("Best Practices Researcher", "Research architecture patterns", "researcher")
+
+  // Analyze current structures
+  LS("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow")
+  LS("/workspaces/ruv-FANN/ruv-swarm/npm")
+
+  // Search for best practices
+  Bash(`gh search repos "language:javascript template architecture" \
+    --limit 10 \
+    --json fullName,description,stargazersCount \
+    --sort stars \
+    --order desc`)
+
+  // Store analysis results
+  mcp__claude-flow__memory_usage({
+    action: "store",
+    key: "architecture/analysis/results",
+    value: {
+      repositories_analyzed: ["claude-code-flow", "ruv-swarm"],
+      optimization_areas: ["structure", "workflows", "templates"],
+      recommendations: ["standardize_structure", "improve_workflows"]
+    }
+  })
+```
+
+#### Template Creation
+```javascript
+// Create standardized repository template
+[Template Creation]:
+  // Create template repository
+  mcp__github__create_repository({
+    name: "claude-project-template",
+    description: "Standardized template for Claude Code projects",
+    private: false,
+    autoInit: true
+  })
+
+  // Push template structure
+  mcp__github__push_files({
+    repo: "claude-project-template",
+    files: [
+      {
+        path: ".claude/commands/github/github-modes.md",
+        content: "[GitHub modes template]"
+      },
+      {
+        path: ".claude/config.json",
+        content: JSON.stringify({
+          version: "1.0",
+          mcp_servers: {
+            "ruv-swarm": {
+              command: "npx",
+              args: ["ruv-swarm", "mcp", "start"]
+            }
+          }
+        })
+      },
+      {
+        path: "CLAUDE.md",
+        content: "[Standardized CLAUDE.md]"
+      },
+      {
+        path: "package.json",
+        content: JSON.stringify({
+          name: "claude-project-template",
+          engines: { node: ">=20.0.0" },
+          dependencies: { "ruv-swarm": "^1.0.11" }
+        })
+      }
+    ],
+    message: "feat: Create standardized template"
+  })
+```
+
+#### Cross-Repository Standardization
+```javascript
+// Synchronize structure across repositories
+[Structure Standardization]:
+  const repositories = ["claude-code-flow", "ruv-swarm", "claude-extensions"]
+
+  // Update common files across all repositories
+  repositories.forEach(repo => {
+    mcp__github__create_or_update_file({
+      repo: "ruv-FANN",
+      path: `${repo}/.github/workflows/integration.yml`,
+      content: `name: Integration Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with: { node-version: '20' }
+      - run: npm install && npm test`,
+      message: "ci: Standardize integration workflow",
+      branch: "structure/standardization"
+    })
+  })
+```
+
+### 4. Orchestration Workflows
+
+#### Dependency Management
+```javascript
+// Update dependencies across all repositories
+[Organization-Wide Dependency Update]:
+  // Create tracking issue
+  TRACKING_ISSUE=$(Bash(`gh issue create \
+    --title "Dependency Update: typescript@5.0.0" \
+    --body "Tracking TypeScript update across all repositories" \
+    --label "dependencies,tracking" \
+    --json number -q .number`))
+
+  // Find all TypeScript repositories
+  TS_REPOS=$(Bash(`gh repo list org --limit 100 --json name | \
+    jq -r '.[].name' | while read -r repo; do
+      if gh api repos/org/$repo/contents/package.json 2>/dev/null | \
+         jq -r '.content' | base64 -d | grep -q '"typescript"'; then
+        echo "$repo"
+      fi
+    done`))
+
+  // Update each repository
+  Bash(`echo "$TS_REPOS" | while read -r repo; do
+    gh repo clone org/$repo /tmp/$repo -- --depth=1
+    cd /tmp/$repo
+
+    npm install --save-dev typescript@5.0.0
+
+    if npm test; then
+      git checkout -b update-typescript-5
+      git add package.json package-lock.json
+      git commit -m "chore: Update TypeScript to 5.0.0
+
+Part of #$TRACKING_ISSUE"
+
+      git push origin HEAD
+      gh pr create \
+        --title "Update TypeScript to 5.0.0" \
+        --body "Updates TypeScript\n\nTracking: #$TRACKING_ISSUE" \
+        --label "dependencies"
+    else
+      gh issue comment $TRACKING_ISSUE \
+        --body "❌ Failed to update $repo - tests failing"
+    fi
+  done`)
+```
+
+#### Refactoring Operations
+```javascript
+// Coordinate large-scale refactoring
+[Cross-Repo Refactoring]:
+  // Initialize refactoring swarm
+  mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 8 })
+
+  // Spawn specialized agents
+  Task("Refactoring Coordinator", "Coordinate refactoring across repos", "coordinator")
+  Task("Impact Analyzer", "Analyze refactoring impact", "analyst")
+  Task("Code Transformer", "Apply refactoring changes", "coder")
+  Task("Migration Guide Creator", "Create migration documentation", "documenter")
+  Task("Integration Tester", "Validate refactored code", "tester")
+
+  // Execute refactoring
+  mcp__claude-flow__task_orchestrate({
+    task: "Rename OldAPI to NewAPI across all repositories",
+    strategy: "sequential",
+    priority: "high"
+  })
+```
+
+#### Security Updates
+```javascript
+// Coordinate security patches
+[Security Patch Deployment]:
+  // Scan all repositories
+  Bash(`gh repo list org --limit 100 --json name | jq -r '.[].name' | \
+    while read -r repo; do
+      gh repo clone org/$repo /tmp/$repo -- --depth=1
+      cd /tmp/$repo
+      npm audit --json > /tmp/audit-$repo.json
+    done`)
+
+  // Apply patches
+  Bash(`for repo in /tmp/audit-*.json; do
+    if [ $(jq '.vulnerabilities | length' $repo) -gt 0 ]; then
+      cd /tmp/$(basename $repo .json | sed 's/audit-//')
+      npm audit fix
+
+      if npm test; then
+        git checkout -b security/patch-$(date +%Y%m%d)
+        git add -A
+        git commit -m "security: Apply security patches"
+        git push origin HEAD
+        gh pr create --title "Security patches" --label "security"
+      fi
+    fi
+  done`)
+```
+
+## Configuration
+
+### Multi-Repo Config File
+```yaml
+# .swarm/multi-repo.yml
+version: 1
+organization: my-org
+
+repositories:
+  - name: frontend
+    url: github.com/my-org/frontend
+    role: ui
+    agents: [coder, designer, tester]
+
+  - name: backend
+    url: github.com/my-org/backend
+    role: api
+    agents: [architect, coder, tester]
+
+  - name: shared
+    url: github.com/my-org/shared
+    role: library
+    agents: [analyst, coder]
+
+coordination:
+  topology: hierarchical
+  communication: webhook
+  memory: redis://shared-memory
+
+dependencies:
+  - from: frontend
+    to: [backend, shared]
+  - from: backend
+    to: [shared]
+```
+
+### Repository Roles
+```javascript
+{
+  "roles": {
+    "ui": {
+      "responsibilities": ["user-interface", "ux", "accessibility"],
+      "default-agents": ["designer", "coder", "tester"]
+    },
+    "api": {
+      "responsibilities": ["endpoints", "business-logic", "data"],
+      "default-agents": ["architect", "coder", "security"]
+    },
+    "library": {
+      "responsibilities": ["shared-code", "utilities", "types"],
+      "default-agents": ["analyst", "coder", "documenter"]
+    }
+  }
+}
+```
+
+## Communication Strategies
+
+### 1. Webhook-Based Coordination
+```javascript
+const { MultiRepoSwarm } = require('ruv-swarm');
+
+const swarm = new MultiRepoSwarm({
+  webhook: {
+    url: 'https://swarm-coordinator.example.com',
+    secret: process.env.WEBHOOK_SECRET
+  }
+});
+
+swarm.on('repo:update', async (event) => {
+  await swarm.propagate(event, {
+    to: event.dependencies,
+    strategy: 'eventual-consistency'
+  });
+});
+```
+
+### 2. Event Streaming
+```yaml
+# Kafka configuration for real-time coordination
+kafka:
+  brokers: ['kafka1:9092', 'kafka2:9092']
+  topics:
+    swarm-events:
+      partitions: 10
+      replication: 3
+    swarm-memory:
+      partitions: 5
+      replication: 3
+```
+
+## Synchronization Patterns
+
+### 1. Eventually Consistent
+```javascript
+{
+  "sync": {
+    "strategy": "eventual",
+    "max-lag": "5m",
+    "retry": {
+      "attempts": 3,
+      "backoff": "exponential"
+    }
+  }
+}
+```
+
+### 2. Strong Consistency
+```javascript
+{
+  "sync": {
+    "strategy": "strong",
+    "consensus": "raft",
+    "quorum": 0.51,
+    "timeout": "30s"
+  }
+}
+```
+
+### 3. Hybrid Approach
+```javascript
+{
+  "sync": {
+    "default": "eventual",
+    "overrides": {
+      "security-updates": "strong",
+      "dependency-updates": "strong",
+      "documentation": "eventual"
+    }
+  }
+}
+```
+
+## Use Cases
+
+### 1. Microservices Coordination
+```bash
+npx claude-flow skill run github-multi-repo microservices \
+  --services "auth,users,orders,payments" \
+  --ensure-compatibility \
+  --sync-contracts \
+  --integration-tests
+```
+
+### 2. Library Updates
+```bash
+npx claude-flow skill run github-multi-repo lib-update \
+  --library "org/shared-lib" \
+  --version "2.0.0" \
+  --find-consumers \
+  --update-imports \
+  --run-tests
+```
+
+### 3. Organization-Wide Changes
+```bash
+npx claude-flow skill run github-multi-repo org-policy \
+  --policy "add-security-headers" \
+  --repos "org/*" \
+  --validate-compliance \
+  --create-reports
+```
+
+## Architecture Patterns
+
+### Monorepo Structure
+```
+ruv-FANN/
+├── packages/
+│   ├── claude-code-flow/
+│   │   ├── src/
+│   │   ├── .claude/
+│   │   └── package.json
+│   ├── ruv-swarm/
+│   │   ├── src/
+│   │   ├── wasm/
+│   │   └── package.json
+│   └── shared/
+│       ├── types/
+│       ├── utils/
+│       └── config/
+├── tools/
+│   ├── build/
+│   ├── test/
+│   └── deploy/
+├── docs/
+│   ├── architecture/
+│   ├── integration/
+│   └── examples/
+└── .github/
+    ├── workflows/
+    ├── templates/
+    └── actions/
+```
+
+### Command Structure
+```
+.claude/
+├── commands/
+│   ├── github/
+│   │   ├── github-modes.md
+│   │   ├── pr-manager.md
+│   │   ├── issue-tracker.md
+│   │   └── sync-coordinator.md
+│   ├── sparc/
+│   │   ├── sparc-modes.md
+│   │   ├── coder.md
+│   │   └── tester.md
+│   └── swarm/
+│       ├── coordination.md
+│       └── orchestration.md
+├── templates/
+│   ├── issue.md
+│   ├── pr.md
+│   └── project.md
+└── config.json
+```
+
+## Monitoring & Visualization
+
+### Multi-Repo Dashboard
+```bash
+npx claude-flow skill run github-multi-repo dashboard \
+  --port 3000 \
+  --metrics "agent-activity,task-progress,memory-usage" \
+  --real-time
+```
+
+### Dependency Graph
+```bash
+npx claude-flow skill run github-multi-repo dep-graph \
+  --format mermaid \
+  --include-agents \
+  --show-data-flow
+```
+
+### Health Monitoring
+```bash
+npx claude-flow skill run github-multi-repo health-check \
+  --repos "org/*" \
+  --check "connectivity,memory,agents" \
+  --alert-on-issues
+```
+
+## Best Practices
+
+### 1. Repository Organization
+- Clear repository roles and boundaries
+- Consistent naming conventions
+- Documented dependencies
+- Shared configuration standards
+
+### 2. Communication
+- Use appropriate sync strategies
+- Implement circuit breakers
+- Monitor latency and failures
+- Clear error propagation
+
+### 3. Security
+- Secure cross-repo authentication
+- Encrypted communication channels
+- Audit trail for all operations
+- Principle of least privilege
+
+### 4. Version Management
+- Semantic versioning alignment
+- Dependency compatibility validation
+- Automated version bump coordination
+
+### 5. Testing Integration
+- Cross-package test validation
+- Integration test automation
+- Performance regression detection
+
+## Performance Optimization
+
+### Caching Strategy
+```bash
+npx claude-flow skill run github-multi-repo cache-strategy \
+  --analyze-patterns \
+  --suggest-cache-layers \
+  --implement-invalidation
+```
+
+### Parallel Execution
+```bash
+npx claude-flow skill run github-multi-repo parallel-optimize \
+  --analyze-dependencies \
+  --identify-parallelizable \
+  --execute-optimal
+```
+
+### Resource Pooling
+```bash
+npx claude-flow skill run github-multi-repo resource-pool \
+  --share-agents \
+  --distribute-load \
+  --monitor-usage
+```
+
+## Troubleshooting
+
+### Connectivity Issues
+```bash
+npx claude-flow skill run github-multi-repo diagnose-connectivity \
+  --test-all-repos \
+  --check-permissions \
+  --verify-webhooks
+```
+
+### Memory Synchronization
+```bash
+npx claude-flow skill run github-multi-repo debug-memory \
+  --check-consistency \
+  --identify-conflicts \
+  --repair-state
+```
+
+### Performance Bottlenecks
+```bash
+npx claude-flow skill run github-multi-repo perf-analysis \
+  --profile-operations \
+  --identify-bottlenecks \
+  --suggest-optimizations
+```
+
+## Advanced Features
+
+### 1. Distributed Task Queue
+```bash
+npx claude-flow skill run github-multi-repo queue \
+  --backend redis \
+  --workers 10 \
+  --priority-routing \
+  --dead-letter-queue
+```
+
+### 2. Cross-Repo Testing
+```bash
+npx claude-flow skill run github-multi-repo test \
+  --setup-test-env \
+  --link-services \
+  --run-e2e \
+  --tear-down
+```
+
+### 3. Monorepo Migration
+```bash
+npx claude-flow skill run github-multi-repo to-monorepo \
+  --analyze-repos \
+  --suggest-structure \
+  --preserve-history \
+  --create-migration-prs
+```
+
+## Examples
+
+### Full-Stack Application Update
+```bash
+npx claude-flow skill run github-multi-repo fullstack-update \
+  --frontend "org/web-app" \
+  --backend "org/api-server" \
+  --database "org/db-migrations" \
+  --coordinate-deployment
+```
+
+### Cross-Team Collaboration
+```bash
+npx claude-flow skill run github-multi-repo cross-team \
+  --teams "frontend,backend,devops" \
+  --task "implement-feature-x" \
+  --assign-by-expertise \
+  --track-progress
+```
+
+## Metrics and Reporting
+
+### Sync Quality Metrics
+- Package version alignment percentage
+- Documentation consistency score
+- Integration test success rate
+- Synchronization completion time
+
+### Architecture Health Metrics
+- Repository structure consistency score
+- Documentation coverage percentage
+- Cross-repository integration success rate
+- Template adoption and usage statistics
+
+### Automated Reporting
+- Weekly sync status reports
+- Dependency drift detection
+- Documentation divergence alerts
+- Integration health monitoring
+
+## Integration Points
+
+### Related Skills
+- `github-workflow` - GitHub workflow automation
+- `github-pr` - Pull request management
+- `sparc-architect` - Architecture design
+- `sparc-optimizer` - Performance optimization
+
+### Related Commands
+- `/github sync-coordinator` - Cross-repo synchronization
+- `/github release-manager` - Coordinated releases
+- `/github repo-architect` - Repository optimization
+- `/sparc architect` - Detailed architecture design
+
+## Support and Resources
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues
+- Examples: `.claude/examples/github-multi-repo/`
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2025-10-19
+**Maintainer:** Claude Flow Team
@@ -0,0 +1,712 @@
+---
+name: hive-mind-advanced
+description: Advanced Hive Mind collective intelligence system for queen-led multi-agent coordination with consensus mechanisms and persistent memory
+version: 1.0.0
+category: coordination
+tags: [hive-mind, swarm, queen-worker, consensus, collective-intelligence, multi-agent, coordination]
+author: Claude Flow Team
+---
+
+# Hive Mind Advanced Skill
+
+Master the advanced Hive Mind collective intelligence system for sophisticated multi-agent coordination using queen-led architecture, Byzantine consensus, and collective memory.
+
+## Overview
+
+The Hive Mind system represents the pinnacle of multi-agent coordination in Claude Flow, implementing a queen-led hierarchical architecture where a strategic queen coordinator directs specialized worker agents through collective decision-making and shared memory.
+
+## Core Concepts
+
+### Architecture Patterns
+
+**Queen-Led Coordination**
+- Strategic queen agents orchestrate high-level objectives
+- Tactical queens manage mid-level execution
+- Adaptive queens dynamically adjust strategies based on performance
+
+**Worker Specialization**
+- Researcher agents: Analysis and investigation
+- Coder agents: Implementation and development
+- Analyst agents: Data processing and metrics
+- Tester agents: Quality assurance and validation
+- Architect agents: System design and planning
+- Reviewer agents: Code review and improvement
+- Optimizer agents: Performance enhancement
+- Documenter agents: Documentation generation
+
+**Collective Memory System**
+- Shared knowledge base across all agents
+- LRU cache with memory pressure handling
+- SQLite persistence with WAL mode
+- Memory consolidation and association
+- Access pattern tracking and optimization
+
+### Consensus Mechanisms
+
+**Majority Consensus**
+Simple voting where the option with most votes wins.
+
+**Weighted Consensus**
+Queen vote counts as 3x weight, providing strategic guidance.
+
+**Byzantine Fault Tolerance**
+Requires 2/3 majority for decision approval, ensuring robust consensus even with faulty agents.
+
+## Getting Started
+
+### 1. Initialize Hive Mind
+
+```bash
+# Basic initialization
+npx claude-flow hive-mind init
+
+# Force reinitialize
+npx claude-flow hive-mind init --force
+
+# Custom configuration
+npx claude-flow hive-mind init --config hive-config.json
+```
+
+### 2. Spawn a Swarm
+
+```bash
+# Basic spawn with objective
+npx claude-flow hive-mind spawn "Build microservices architecture"
+
+# Strategic queen type
+npx claude-flow hive-mind spawn "Research AI patterns" --queen-type strategic
+
+# Tactical queen with max workers
+npx claude-flow hive-mind spawn "Implement API" --queen-type tactical --max-workers 12
+
+# Adaptive queen with consensus
+npx claude-flow hive-mind spawn "Optimize system" --queen-type adaptive --consensus byzantine
+
+# Generate Claude Code commands
+npx claude-flow hive-mind spawn "Build full-stack app" --claude
+```
+
+### 3. Monitor Status
+
+```bash
+# Check hive mind status
+npx claude-flow hive-mind status
+
+# Get detailed metrics
+npx claude-flow hive-mind metrics
+
+# Monitor collective memory
+npx claude-flow hive-mind memory
+```
+
+## Advanced Workflows
+
+### Session Management
+
+**Create and Manage Sessions**
+
+```bash
+# List active sessions
+npx claude-flow hive-mind sessions
+
+# Pause a session
+npx claude-flow hive-mind pause <session-id>
+
+# Resume a paused session
+npx claude-flow hive-mind resume <session-id>
+
+# Stop a running session
+npx claude-flow hive-mind stop <session-id>
+```
+
+**Session Features**
+- Automatic checkpoint creation
+- Progress tracking with completion percentages
+- Parent-child process management
+- Session logs with event tracking
+- Export/import capabilities
+
+### Consensus Building
+
+The Hive Mind builds consensus through structured voting:
+
+```javascript
+// Programmatic consensus building
+const decision = await hiveMind.buildConsensus(
+  'Architecture pattern selection',
+  ['microservices', 'monolith', 'serverless']
+);
+
+// Result includes:
+// - decision: Winning option
+// - confidence: Vote percentage
+// - votes: Individual agent votes
+```
+
+**Consensus Algorithms**
+
+1. **Majority** - Simple democratic voting
+2. **Weighted** - Queen has 3x voting power
+3. **Byzantine** - 2/3 supermajority required
+
+### Collective Memory
+
+**Storing Knowledge**
+
+```javascript
+// Store in collective memory
+await memory.store('api-patterns', {
+  rest: { pros: [...], cons: [...] },
+  graphql: { pros: [...], cons: [...] }
+}, 'knowledge', { confidence: 0.95 });
+```
+
+**Memory Types**
+- `knowledge`: Permanent insights (no TTL)
+- `context`: Session context (1 hour TTL)
+- `task`: Task-specific data (30 min TTL)
+- `result`: Execution results (permanent, compressed)
+- `error`: Error logs (24 hour TTL)
+- `metric`: Performance metrics (1 hour TTL)
+- `consensus`: Decision records (permanent)
+- `system`: System configuration (permanent)
+
+**Searching and Retrieval**
+
+```javascript
+// Search memory by pattern
+const results = await memory.search('api*', {
+  type: 'knowledge',
+  minConfidence: 0.8,
+  limit: 50
+});
+
+// Get related memories
+const related = await memory.getRelated('api-patterns', 10);
+
+// Build associations
+await memory.associate('rest-api', 'authentication', 0.9);
+```
+
+### Task Distribution
+
+**Automatic Worker Assignment**
+
+The system intelligently assigns tasks based on:
+- Keyword matching with agent specialization
+- Historical performance metrics
+- Worker availability and load
+- Task complexity analysis
+
+```javascript
+// Create task (auto-assigned)
+const task = await hiveMind.createTask(
+  'Implement user authentication',
+  priority: 8,
+  { estimatedDuration: 30000 }
+);
+```
+
+**Auto-Scaling**
+
+```javascript
+// Configure auto-scaling
+const config = {
+  autoScale: true,
+  maxWorkers: 12,
+  scaleUpThreshold: 2, // Pending tasks per idle worker
+  scaleDownThreshold: 2 // Idle workers above pending tasks
+};
+```
+
+## Integration Patterns
+
+### With Claude Code
+
+Generate Claude Code spawn commands directly:
+
+```bash
+npx claude-flow hive-mind spawn "Build REST API" --claude
+```
+
+Output:
+```javascript
+Task("Queen Coordinator", "Orchestrate REST API development...", "coordinator")
+Task("Backend Developer", "Implement Express routes...", "backend-dev")
+Task("Database Architect", "Design PostgreSQL schema...", "code-analyzer")
+Task("Test Engineer", "Create Jest test suite...", "tester")
+```
+
+### With SPARC Methodology
+
+```bash
+# Use hive mind for SPARC workflow
+npx claude-flow sparc tdd "User authentication" --hive-mind
+
+# Spawns:
+# - Specification agent
+# - Architecture agent
+# - Coder agents
+# - Tester agents
+# - Reviewer agents
+```
+
+### With GitHub Integration
+
+```bash
+# Repository analysis with hive mind
+npx claude-flow hive-mind spawn "Analyze repo quality" --objective "owner/repo"
+
+# PR review coordination
+npx claude-flow hive-mind spawn "Review PR #123" --queen-type tactical
+```
+
+## Performance Optimization
+
+### Memory Optimization
+
+The collective memory system includes advanced optimizations:
+
+**LRU Cache**
+- Configurable cache size (default: 1000 entries)
+- Memory pressure handling (default: 50MB)
+- Automatic eviction of least-used entries
+
+**Database Optimization**
+- WAL (Write-Ahead Logging) mode
+- 64MB cache size
+- 256MB memory mapping
+- Prepared statements for common queries
+- Automatic ANALYZE and OPTIMIZE
+
+**Object Pooling**
+- Query result pooling
+- Memory entry pooling
+- Reduced garbage collection pressure
+
+### Performance Metrics
+
+```javascript
+// Get performance insights
+const insights = hiveMind.getPerformanceInsights();
+
+// Includes:
+// - asyncQueue utilization
+// - Batch processing stats
+// - Success rates
+// - Average processing times
+// - Memory efficiency
+```
+
+### Task Execution
+
+**Parallel Processing**
+- Batch agent spawning (5 agents per batch)
+- Concurrent task orchestration
+- Async operation optimization
+- Non-blocking task assignment
+
+**Benchmarks**
+- 10-20x faster batch spawning
+- 2.8-4.4x speed improvement overall
+- 32.3% token reduction
+- 84.8% SWE-Bench solve rate
+
+## Configuration
+
+### Hive Mind Config
+
+```javascript
+{
+  "objective": "Build microservices",
+  "name": "my-hive",
+  "queenType": "strategic", // strategic | tactical | adaptive
+  "maxWorkers": 8,
+  "consensusAlgorithm": "byzantine", // majority | weighted | byzantine
+  "autoScale": true,
+  "memorySize": 100, // MB
+  "taskTimeout": 60, // minutes
+  "encryption": false
+}
+```
+
+### Memory Config
+
+```javascript
+{
+  "maxSize": 100, // MB
+  "compressionThreshold": 1024, // bytes
+  "gcInterval": 300000, // 5 minutes
+  "cacheSize": 1000,
+  "cacheMemoryMB": 50,
+  "enablePooling": true,
+  "enableAsyncOperations": true
+}
+```
+
+## Hooks Integration
+
+Hive Mind integrates with Claude Flow hooks for automation:
+
+**Pre-Task Hooks**
+- Auto-assign agents by file type
+- Validate objective complexity
+- Optimize topology selection
+- Cache search patterns
+
+**Post-Task Hooks**
+- Auto-format deliverables
+- Train neural patterns
+- Update collective memory
+- Analyze performance bottlenecks
+
+**Session Hooks**
+- Generate session summaries
+- Persist checkpoint data
+- Track comprehensive metrics
+- Restore execution context
+
+## Best Practices
+
+### 1. Choose the Right Queen Type
+
+**Strategic Queens** - For research, planning, and analysis
+```bash
+npx claude-flow hive-mind spawn "Research ML frameworks" --queen-type strategic
+```
+
+**Tactical Queens** - For implementation and execution
+```bash
+npx claude-flow hive-mind spawn "Build authentication" --queen-type tactical
+```
+
+**Adaptive Queens** - For optimization and dynamic tasks
+```bash
+npx claude-flow hive-mind spawn "Optimize performance" --queen-type adaptive
+```
+
+### 2. Leverage Consensus
+
+Use consensus for critical decisions:
+- Architecture pattern selection
+- Technology stack choices
+- Implementation approach
+- Code review approval
+- Release readiness
+
+### 3. Utilize Collective Memory
+
+**Store Learnings**
+```javascript
+// After successful pattern implementation
+await memory.store('auth-pattern', {
+  approach: 'JWT with refresh tokens',
+  pros: ['Stateless', 'Scalable'],
+  cons: ['Token size', 'Revocation complexity'],
+  implementation: {...}
+}, 'knowledge', { confidence: 0.95 });
+```
+
+**Build Associations**
+```javascript
+// Link related concepts
+await memory.associate('jwt-auth', 'refresh-tokens', 0.9);
+await memory.associate('jwt-auth', 'oauth2', 0.7);
+```
+
+### 4. Monitor Performance
+
+```bash
+# Regular status checks
+npx claude-flow hive-mind status
+
+# Track metrics
+npx claude-flow hive-mind metrics
+
+# Analyze memory usage
+npx claude-flow hive-mind memory
+```
+
+### 5. Session Management
+
+**Checkpoint Frequently**
+```javascript
+// Create checkpoints at key milestones
+await sessionManager.saveCheckpoint(
+  sessionId,
+  'api-routes-complete',
+  { completedRoutes: [...], remaining: [...] }
+);
+```
+
+**Resume Sessions**
+```bash
+# Resume from any previous state
+npx claude-flow hive-mind resume <session-id>
+```
+
+## Troubleshooting
+
+### Memory Issues
+
+**High Memory Usage**
+```bash
+# Run garbage collection
+npx claude-flow hive-mind memory --gc
+
+# Optimize database
+npx claude-flow hive-mind memory --optimize
+
+# Export and clear
+npx claude-flow hive-mind memory --export --clear
+```
+
+**Low Cache Hit Rate**
+```javascript
+// Increase cache size in config
+{
+  "cacheSize": 2000,
+  "cacheMemoryMB": 100
+}
+```
+
+### Performance Issues
+
+**Slow Task Assignment**
+```javascript
+// Enable worker type caching
+// The system caches best worker matches for 5 minutes
+// Automatic - no configuration needed
+```
+
+**High Queue Utilization**
+```javascript
+// Increase async queue concurrency
+{
+  "asyncQueueConcurrency": 20 // Default: min(maxWorkers * 2, 20)
+}
+```
+
+### Consensus Failures
+
+**No Consensus Reached (Byzantine)**
+```bash
+# Switch to weighted consensus for more decisive results
+npx claude-flow hive-mind spawn "..." --consensus weighted
+
+# Or use simple majority
+npx claude-flow hive-mind spawn "..." --consensus majority
+```
+
+## Advanced Topics
+
+### Custom Worker Types
+
+Define specialized workers in `.claude/agents/`:
+
+```yaml
+name: security-auditor
+type: specialist
+capabilities:
+  - vulnerability-scanning
+  - security-review
+  - penetration-testing
+  - compliance-checking
+priority: high
+```
+
+### Neural Pattern Training
+
+The system trains on successful patterns:
+
+```javascript
+// Automatic pattern learning
+// Happens after successful task completion
+// Stores in collective memory
+// Improves future task matching
+```
+
+### Multi-Hive Coordination
+
+Run multiple hive minds simultaneously:
+
+```bash
+# Frontend hive
+npx claude-flow hive-mind spawn "Build UI" --name frontend-hive
+
+# Backend hive
+npx claude-flow hive-mind spawn "Build API" --name backend-hive
+
+# They share collective memory for coordination
+```
+
+### Export/Import Sessions
+
+```bash
+# Export session for backup
+npx claude-flow hive-mind export <session-id> --output backup.json
+
+# Import session
+npx claude-flow hive-mind import backup.json
+```
+
+## API Reference
+
+### HiveMindCore
+
+```javascript
+const hiveMind = new HiveMindCore({
+  objective: 'Build system',
+  queenType: 'strategic',
+  maxWorkers: 8,
+  consensusAlgorithm: 'byzantine'
+});
+
+await hiveMind.initialize();
+await hiveMind.spawnQueen(queenData);
+await hiveMind.spawnWorkers(['coder', 'tester']);
+await hiveMind.createTask('Implement feature', 7);
+const decision = await hiveMind.buildConsensus('topic', options);
+const status = hiveMind.getStatus();
+await hiveMind.shutdown();
+```
+
+### CollectiveMemory
+
+```javascript
+const memory = new CollectiveMemory({
+  swarmId: 'hive-123',
+  maxSize: 100,
+  cacheSize: 1000
+});
+
+await memory.store(key, value, type, metadata);
+const data = await memory.retrieve(key);
+const results = await memory.search(pattern, options);
+const related = await memory.getRelated(key, limit);
+await memory.associate(key1, key2, strength);
+const stats = memory.getStatistics();
+const analytics = memory.getAnalytics();
+const health = await memory.healthCheck();
+```
+
+### HiveMindSessionManager
+
+```javascript
+const sessionManager = new HiveMindSessionManager();
+
+const sessionId = await sessionManager.createSession(
+  swarmId, swarmName, objective, metadata
+);
+
+await sessionManager.saveCheckpoint(sessionId, name, data);
+const sessions = await sessionManager.getActiveSessions();
+const session = await sessionManager.getSession(sessionId);
+await sessionManager.pauseSession(sessionId);
+await sessionManager.resumeSession(sessionId);
+await sessionManager.stopSession(sessionId);
+await sessionManager.completeSession(sessionId);
+```
+
+## Examples
+
+### Full-Stack Development
+
+```bash
+# Initialize hive mind
+npx claude-flow hive-mind init
+
+# Spawn full-stack hive
+npx claude-flow hive-mind spawn "Build e-commerce platform" \
+  --queen-type strategic \
+  --max-workers 10 \
+  --consensus weighted \
+  --claude
+
+# Output generates Claude Code commands:
+# - Queen coordinator
+# - Frontend developers (React)
+# - Backend developers (Node.js)
+# - Database architects
+# - DevOps engineers
+# - Security auditors
+# - Test engineers
+# - Documentation specialists
+```
+
+### Research and Analysis
+
+```bash
+# Spawn research hive
+npx claude-flow hive-mind spawn "Research GraphQL vs REST" \
+  --queen-type adaptive \
+  --consensus byzantine
+
+# Researchers gather data
+# Analysts process findings
+# Queen builds consensus on recommendation
+# Results stored in collective memory
+```
+
+### Code Review
+
+```bash
+# Review coordination
+npx claude-flow hive-mind spawn "Review PR #456" \
+  --queen-type tactical \
+  --max-workers 6
+
+# Spawns:
+# - Code analyzers
+# - Security reviewers
+# - Performance reviewers
+# - Test coverage analyzers
+# - Documentation reviewers
+# - Consensus on approval/changes
+```
+
+## Skill Progression
+
+### Beginner
+1. Initialize hive mind
+2. Spawn basic swarms
+3. Monitor status
+4. Use majority consensus
+
+### Intermediate
+1. Configure queen types
+2. Implement session management
+3. Use weighted consensus
+4. Access collective memory
+5. Enable auto-scaling
+
+### Advanced
+1. Byzantine fault tolerance
+2. Memory optimization
+3. Custom worker types
+4. Multi-hive coordination
+5. Neural pattern training
+6. Session export/import
+7. Performance tuning
+
+## Related Skills
+
+- `swarm-orchestration`: Basic swarm coordination
+- `consensus-mechanisms`: Distributed decision making
+- `memory-systems`: Advanced memory management
+- `sparc-methodology`: Structured development workflow
+- `github-integration`: Repository coordination
+
+## References
+
+- [Hive Mind Documentation](https://github.com/ruvnet/claude-flow/docs/hive-mind)
+- [Collective Intelligence Patterns](https://github.com/ruvnet/claude-flow/docs/patterns)
+- [Byzantine Consensus](https://github.com/ruvnet/claude-flow/docs/consensus)
+- [Memory Optimization](https://github.com/ruvnet/claude-flow/docs/memory)
+
+---
+
+**Skill Version**: 1.0.0
+**Last Updated**: 2025-10-19
+**Maintained By**: Claude Flow Team
+**License**: MIT
@@ -0,0 +1,563 @@
+---
+name: performance-analysis
+version: 1.0.0
+description: Comprehensive performance analysis, bottleneck detection, and optimization recommendations for Claude Flow swarms
+category: monitoring
+tags: [performance, bottleneck, optimization, profiling, metrics, analysis]
+author: Claude Flow Team
+---
+
+# Performance Analysis Skill
+
+Comprehensive performance analysis suite for identifying bottlenecks, profiling swarm operations, generating detailed reports, and providing actionable optimization recommendations.
+
+## Overview
+
+This skill consolidates all performance analysis capabilities:
+- **Bottleneck Detection**: Identify performance bottlenecks across communication, processing, memory, and network
+- **Performance Profiling**: Real-time monitoring and historical analysis of swarm operations
+- **Report Generation**: Create comprehensive performance reports in multiple formats
+- **Optimization Recommendations**: AI-powered suggestions for improving performance
+
+## Quick Start
+
+### Basic Bottleneck Detection
+```bash
+npx claude-flow bottleneck detect
+```
+
+### Generate Performance Report
+```bash
+npx claude-flow analysis performance-report --format html --include-metrics
+```
+
+### Analyze and Auto-Fix
+```bash
+npx claude-flow bottleneck detect --fix --threshold 15
+```
+
+## Core Capabilities
+
+### 1. Bottleneck Detection
+
+#### Command Syntax
+```bash
+npx claude-flow bottleneck detect [options]
+```
+
+#### Options
+- `--swarm-id, -s <id>` - Analyze specific swarm (default: current)
+- `--time-range, -t <range>` - Analysis period: 1h, 24h, 7d, all (default: 1h)
+- `--threshold <percent>` - Bottleneck threshold percentage (default: 20)
+- `--export, -e <file>` - Export analysis to file
+- `--fix` - Apply automatic optimizations
+
+#### Usage Examples
+```bash
+# Basic detection for current swarm
+npx claude-flow bottleneck detect
+
+# Analyze specific swarm over 24 hours
+npx claude-flow bottleneck detect --swarm-id swarm-123 -t 24h
+
+# Export detailed analysis
+npx claude-flow bottleneck detect -t 24h -e bottlenecks.json
+
+# Auto-fix detected issues
+npx claude-flow bottleneck detect --fix --threshold 15
+
+# Low threshold for sensitive detection
+npx claude-flow bottleneck detect --threshold 10 --export critical-issues.json
+```
+
+#### Metrics Analyzed
+
+**Communication Bottlenecks:**
+- Message queue delays
+- Agent response times
+- Coordination overhead
+- Memory access patterns
+- Inter-agent communication latency
+
+**Processing Bottlenecks:**
+- Task completion times
+- Agent utilization rates
+- Parallel execution efficiency
+- Resource contention
+- CPU/memory usage patterns
+
+**Memory Bottlenecks:**
+- Cache hit rates
+- Memory access patterns
+- Storage I/O performance
+- Neural pattern loading times
+- Memory allocation efficiency
+
+**Network Bottlenecks:**
+- API call latency
+- MCP communication delays
+- External service timeouts
+- Concurrent request limits
+- Network throughput issues
+
+#### Output Format
+```
+🔍 Bottleneck Analysis Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Summary
+├── Time Range: Last 1 hour
+├── Agents Analyzed: 6
+├── Tasks Processed: 42
+└── Critical Issues: 2
+
+🚨 Critical Bottlenecks
+1. Agent Communication (35% impact)
+   └── coordinator → coder-1 messages delayed by 2.3s avg
+
+2. Memory Access (28% impact)
+   └── Neural pattern loading taking 1.8s per access
+
+⚠️ Warning Bottlenecks
+1. Task Queue (18% impact)
+   └── 5 tasks waiting > 10s for assignment
+
+💡 Recommendations
+1. Switch to hierarchical topology (est. 40% improvement)
+2. Enable memory caching (est. 25% improvement)
+3. Increase agent concurrency to 8 (est. 20% improvement)
+
+✅ Quick Fixes Available
+Run with --fix to apply:
+- Enable smart caching
+- Optimize message routing
+- Adjust agent priorities
+```
+
+### 2. Performance Profiling
+
+#### Real-time Detection
+Automatic analysis during task execution:
+- Execution time vs. complexity
+- Agent utilization rates
+- Resource constraints
+- Operation patterns
+
+#### Common Bottleneck Patterns
+
+**Time Bottlenecks:**
+- Tasks taking > 5 minutes
+- Sequential operations that could parallelize
+- Redundant file operations
+- Inefficient algorithm implementations
+
+**Coordination Bottlenecks:**
+- Single agent for complex tasks
+- Unbalanced agent workloads
+- Poor topology selection
+- Excessive synchronization points
+
+**Resource Bottlenecks:**
+- High operation count (> 100)
+- Memory constraints
+- I/O limitations
+- Thread pool saturation
+
+#### MCP Integration
+```javascript
+// Check for bottlenecks in Claude Code
+mcp__claude-flow__bottleneck_detect({
+  timeRange: "1h",
+  threshold: 20,
+  autoFix: false
+})
+
+// Get detailed task results with bottleneck analysis
+mcp__claude-flow__task_results({
+  taskId: "task-123",
+  format: "detailed"
+})
+```
+
+**Result Format:**
+```json
+{
+  "bottlenecks": [
+    {
+      "type": "coordination",
+      "severity": "high",
+      "description": "Single agent used for complex task",
+      "recommendation": "Spawn specialized agents for parallel work",
+      "impact": "35%",
+      "affectedComponents": ["coordinator", "coder-1"]
+    }
+  ],
+  "improvements": [
+    {
+      "area": "execution_time",
+      "suggestion": "Use parallel task execution",
+      "expectedImprovement": "30-50% time reduction",
+      "implementationSteps": [
+        "Split task into smaller units",
+        "Spawn 3-4 specialized agents",
+        "Use mesh topology for coordination"
+      ]
+    }
+  ],
+  "metrics": {
+    "avgExecutionTime": "142s",
+    "agentUtilization": "67%",
+    "cacheHitRate": "82%",
+    "parallelizationFactor": 1.2
+  }
+}
+```
+
+### 3. Report Generation
+
+#### Command Syntax
+```bash
+npx claude-flow analysis performance-report [options]
+```
+
+#### Options
+- `--format <type>` - Report format: json, html, markdown (default: markdown)
+- `--include-metrics` - Include detailed metrics and charts
+- `--compare <id>` - Compare with previous swarm
+- `--time-range <range>` - Analysis period: 1h, 24h, 7d, 30d, all
+- `--output <file>` - Output file path
+- `--sections <list>` - Comma-separated sections to include
+
+#### Report Sections
+1. **Executive Summary**
+   - Overall performance score
+   - Key metrics overview
+   - Critical findings
+
+2. **Swarm Overview**
+   - Topology configuration
+   - Agent distribution
+   - Task statistics
+
+3. **Performance Metrics**
+   - Execution times
+   - Throughput analysis
+   - Resource utilization
+   - Latency breakdown
+
+4. **Bottleneck Analysis**
+   - Identified bottlenecks
+   - Impact assessment
+   - Optimization priorities
+
+5. **Comparative Analysis** (when --compare used)
+   - Performance trends
+   - Improvement metrics
+   - Regression detection
+
+6. **Recommendations**
+   - Prioritized action items
+   - Expected improvements
+   - Implementation guidance
+
+#### Usage Examples
+```bash
+# Generate HTML report with all metrics
+npx claude-flow analysis performance-report --format html --include-metrics
+
+# Compare current swarm with previous
+npx claude-flow analysis performance-report --compare swarm-123 --format markdown
+
+# Custom output with specific sections
+npx claude-flow analysis performance-report \
+  --sections summary,metrics,recommendations \
+  --output reports/perf-analysis.html \
+  --format html
+
+# Weekly performance report
+npx claude-flow analysis performance-report \
+  --time-range 7d \
+  --include-metrics \
+  --format markdown \
+  --output docs/weekly-performance.md
+
+# JSON format for CI/CD integration
+npx claude-flow analysis performance-report \
+  --format json \
+  --output build/performance.json
+```
+
+#### Sample Markdown Report
+```markdown
+# Performance Analysis Report
+
+## Executive Summary
+- **Overall Score**: 87/100
+- **Analysis Period**: Last 24 hours
+- **Swarms Analyzed**: 3
+- **Critical Issues**: 1
+
+## Key Metrics
+| Metric | Value | Trend | Target |
+|--------|-------|-------|--------|
+| Avg Task Time | 42s | ↓ 12% | 35s |
+| Agent Utilization | 78% | ↑ 5% | 85% |
+| Cache Hit Rate | 91% | → | 90% |
+| Parallel Efficiency | 2.3x | ↑ 0.4x | 2.5x |
+
+## Bottleneck Analysis
+### Critical
+1. **Agent Communication Delay** (Impact: 35%)
+   - Coordinator → Coder messages delayed by 2.3s avg
+   - **Fix**: Switch to hierarchical topology
+
+### Warnings
+1. **Memory Access Pattern** (Impact: 18%)
+   - Neural pattern loading: 1.8s per access
+   - **Fix**: Enable memory caching
+
+## Recommendations
+1. **High Priority**: Switch to hierarchical topology (40% improvement)
+2. **Medium Priority**: Enable memory caching (25% improvement)
+3. **Low Priority**: Increase agent concurrency to 8 (20% improvement)
+```
+
+### 4. Optimization Recommendations
+
+#### Automatic Fixes
+When using `--fix`, the following optimizations may be applied:
+
+**1. Topology Optimization**
+- Switch to more efficient topology (mesh → hierarchical)
+- Adjust communication patterns
+- Reduce coordination overhead
+- Optimize message routing
+
+**2. Caching Enhancement**
+- Enable memory caching
+- Optimize cache strategies
+- Preload common patterns
+- Implement cache warming
+
+**3. Concurrency Tuning**
+- Adjust agent counts
+- Optimize parallel execution
+- Balance workload distribution
+- Implement load balancing
+
+**4. Priority Adjustment**
+- Reorder task queues
+- Prioritize critical paths
+- Reduce wait times
+- Implement fair scheduling
+
+**5. Resource Optimization**
+- Optimize memory usage
+- Reduce I/O operations
+- Batch API calls
+- Implement connection pooling
+
+#### Performance Impact
+Typical improvements after bottleneck resolution:
+
+- **Communication**: 30-50% faster message delivery
+- **Processing**: 20-40% reduced task completion time
+- **Memory**: 40-60% fewer cache misses
+- **Network**: 25-45% reduced API latency
+- **Overall**: 25-45% total performance improvement
+
+## Advanced Usage
+
+### Continuous Monitoring
+```bash
+# Monitor performance in real-time
+npx claude-flow swarm monitor --interval 5
+
+# Generate hourly reports
+while true; do
+  npx claude-flow analysis performance-report \
+    --format json \
+    --output logs/perf-$(date +%Y%m%d-%H%M).json
+  sleep 3600
+done
+```
+
+### CI/CD Integration
+```yaml
+# .github/workflows/performance.yml
+name: Performance Analysis
+on: [push, pull_request]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run Performance Analysis
+        run: |
+          npx claude-flow analysis performance-report \
+            --format json \
+            --output performance.json
+      - name: Check Performance Thresholds
+        run: |
+          npx claude-flow bottleneck detect \
+            --threshold 15 \
+            --export bottlenecks.json
+      - name: Upload Reports
+        uses: actions/upload-artifact@v2
+        with:
+          name: performance-reports
+          path: |
+            performance.json
+            bottlenecks.json
+```
+
+### Custom Analysis Scripts
+```javascript
+// scripts/analyze-performance.js
+const { exec } = require('child_process');
+const fs = require('fs');
+
+async function analyzePerformance() {
+  // Run bottleneck detection
+  const bottlenecks = await runCommand(
+    'npx claude-flow bottleneck detect --format json'
+  );
+
+  // Generate performance report
+  const report = await runCommand(
+    'npx claude-flow analysis performance-report --format json'
+  );
+
+  // Analyze results
+  const analysis = {
+    bottlenecks: JSON.parse(bottlenecks),
+    performance: JSON.parse(report),
+    timestamp: new Date().toISOString()
+  };
+
+  // Save combined analysis
+  fs.writeFileSync(
+    'analysis/combined-report.json',
+    JSON.stringify(analysis, null, 2)
+  );
+
+  // Generate alerts if needed
+  if (analysis.bottlenecks.critical.length > 0) {
+    console.error('CRITICAL: Performance bottlenecks detected!');
+    process.exit(1);
+  }
+}
+
+function runCommand(cmd) {
+  return new Promise((resolve, reject) => {
+    exec(cmd, (error, stdout, stderr) => {
+      if (error) reject(error);
+      else resolve(stdout);
+    });
+  });
+}
+
+analyzePerformance().catch(console.error);
+```
+
+## Best Practices
+
+### 1. Regular Analysis
+- Run bottleneck detection after major changes
+- Generate weekly performance reports
+- Monitor trends over time
+- Set up automated alerts
+
+### 2. Threshold Tuning
+- Start with default threshold (20%)
+- Lower for production systems (10-15%)
+- Higher for development (25-30%)
+- Adjust based on requirements
+
+### 3. Fix Strategy
+- Always review before applying --fix
+- Test fixes in development first
+- Apply fixes incrementally
+- Monitor impact after changes
+
+### 4. Report Integration
+- Include in documentation
+- Share with team regularly
+- Track improvements over time
+- Use for capacity planning
+
+### 5. Continuous Optimization
+- Learn from each analysis
+- Build performance budgets
+- Establish baselines
+- Set improvement goals
+
+## Troubleshooting
+
+### Common Issues
+
+**High Memory Usage**
+```bash
+# Analyze memory bottlenecks
+npx claude-flow bottleneck detect --threshold 10
+
+# Check cache performance
+npx claude-flow cache manage --action stats
+
+# Review memory metrics
+npx claude-flow memory usage
+```
+
+**Slow Task Execution**
+```bash
+# Identify slow tasks
+npx claude-flow task status --detailed
+
+# Analyze coordination overhead
+npx claude-flow bottleneck detect --time-range 1h
+
+# Check agent utilization
+npx claude-flow agent metrics
+```
+
+**Poor Cache Performance**
+```bash
+# Analyze cache hit rates
+npx claude-flow analysis performance-report --sections metrics
+
+# Review cache strategy
+npx claude-flow cache manage --action analyze
+
+# Enable cache warming
+npx claude-flow bottleneck detect --fix
+```
+
+## Integration with Other Skills
+
+- **swarm-orchestration**: Use performance data to optimize topology
+- **memory-management**: Improve cache strategies based on analysis
+- **task-coordination**: Adjust scheduling based on bottlenecks
+- **neural-training**: Train patterns from performance data
+
+## Related Commands
+
+- `npx claude-flow swarm monitor` - Real-time monitoring
+- `npx claude-flow token usage` - Token optimization analysis
+- `npx claude-flow cache manage` - Cache optimization
+- `npx claude-flow agent metrics` - Agent performance metrics
+- `npx claude-flow task status` - Task execution analysis
+
+## See Also
+
+- [Bottleneck Detection Guide](/workspaces/claude-code-flow/.claude/commands/analysis/bottleneck-detect.md)
+- [Performance Report Guide](/workspaces/claude-code-flow/.claude/commands/analysis/performance-report.md)
+- [Performance Bottlenecks Overview](/workspaces/claude-code-flow/.claude/commands/analysis/performance-bottlenecks.md)
+- [Swarm Monitoring Documentation](../swarm-orchestration/SKILL.md)
+- [Memory Management Documentation](../memory-management/SKILL.md)
+
+---
+
+**Version**: 1.0.0
+**Last Updated**: 2025-10-19
+**Maintainer**: Claude Flow Team
@@ -0,0 +1,446 @@
+---
+name: "ReasoningBank with AgentDB"
+description: "Implement ReasoningBank adaptive learning with AgentDB's 150x faster vector database. Includes trajectory tracking, verdict judgment, memory distillation, and pattern recognition. Use when building self-learning agents, optimizing decision-making, or implementing experience replay systems."
+---
+
+# ReasoningBank with AgentDB
+
+## What This Skill Does
+
+Provides ReasoningBank adaptive learning patterns using AgentDB's high-performance backend (150x-12,500x faster). Enables agents to learn from experiences, judge outcomes, distill memories, and improve decision-making over time with 100% backward compatibility.
+
+**Performance**: 150x faster pattern retrieval, 500x faster batch operations, <1ms memory access.
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow)
+- Understanding of reinforcement learning concepts (optional)
+
+---
+
+## Quick Start with CLI
+
+### Initialize ReasoningBank Database
+
+```bash
+# Initialize AgentDB for ReasoningBank
+npx agentdb@latest init ./.agentdb/reasoningbank.db --dimension 1536
+
+# Start MCP server for Claude Code integration
+npx agentdb@latest mcp
+claude mcp add agentdb npx agentdb@latest mcp
+```
+
+### Migrate from Legacy ReasoningBank
+
+```bash
+# Automatic migration with validation
+npx agentdb@latest migrate --source .swarm/memory.db
+
+# Verify migration
+npx agentdb@latest stats ./.agentdb/reasoningbank.db
+```
+
+---
+
+## Quick Start with API
+
+```typescript
+import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank';
+
+// Initialize ReasoningBank with AgentDB
+const rb = await createAgentDBAdapter({
+  dbPath: '.agentdb/reasoningbank.db',
+  enableLearning: true,      // Enable learning plugins
+  enableReasoning: true,      // Enable reasoning agents
+  cacheSize: 1000,            // 1000 pattern cache
+});
+
+// Store successful experience
+const query = "How to optimize database queries?";
+const embedding = await computeEmbedding(query);
+
+await rb.insertPattern({
+  id: '',
+  type: 'experience',
+  domain: 'database-optimization',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: {
+      query,
+      approach: 'indexing + query optimization',
+      outcome: 'success',
+      metrics: { latency_reduction: 0.85 }
+    }
+  }),
+  confidence: 0.95,
+  usage_count: 1,
+  success_count: 1,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Retrieve similar experiences with reasoning
+const result = await rb.retrieveWithReasoning(embedding, {
+  domain: 'database-optimization',
+  k: 5,
+  useMMR: true,              // Diverse results
+  synthesizeContext: true,    // Rich context synthesis
+});
+
+console.log('Memories:', result.memories);
+console.log('Context:', result.context);
+console.log('Patterns:', result.patterns);
+```
+
+---
+
+## Core ReasoningBank Concepts
+
+### 1. Trajectory Tracking
+
+Track agent execution paths and outcomes:
+
+```typescript
+// Record trajectory (sequence of actions)
+const trajectory = {
+  task: 'optimize-api-endpoint',
+  steps: [
+    { action: 'analyze-bottleneck', result: 'found N+1 query' },
+    { action: 'add-eager-loading', result: 'reduced queries' },
+    { action: 'add-caching', result: 'improved latency' }
+  ],
+  outcome: 'success',
+  metrics: { latency_before: 2500, latency_after: 150 }
+};
+
+const embedding = await computeEmbedding(JSON.stringify(trajectory));
+
+await rb.insertPattern({
+  id: '',
+  type: 'trajectory',
+  domain: 'api-optimization',
+  pattern_data: JSON.stringify({ embedding, pattern: trajectory }),
+  confidence: 0.9,
+  usage_count: 1,
+  success_count: 1,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+```
+
+### 2. Verdict Judgment
+
+Judge whether a trajectory was successful:
+
+```typescript
+// Retrieve similar past trajectories
+const similar = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'api-optimization',
+  k: 10,
+});
+
+// Judge based on similarity to successful patterns
+const verdict = similar.memories.filter(m =>
+  m.pattern.outcome === 'success' &&
+  m.similarity > 0.8
+).length > 5 ? 'likely_success' : 'needs_review';
+
+console.log('Verdict:', verdict);
+console.log('Confidence:', similar.memories[0]?.similarity || 0);
+```
+
+### 3. Memory Distillation
+
+Consolidate similar experiences into patterns:
+
+```typescript
+// Get all experiences in domain
+const experiences = await rb.retrieveWithReasoning(embedding, {
+  domain: 'api-optimization',
+  k: 100,
+  optimizeMemory: true,  // Automatic consolidation
+});
+
+// Distill into high-level pattern
+const distilledPattern = {
+  domain: 'api-optimization',
+  pattern: 'For N+1 queries: add eager loading, then cache',
+  success_rate: 0.92,
+  sample_size: experiences.memories.length,
+  confidence: 0.95
+};
+
+await rb.insertPattern({
+  id: '',
+  type: 'distilled-pattern',
+  domain: 'api-optimization',
+  pattern_data: JSON.stringify({
+    embedding: await computeEmbedding(JSON.stringify(distilledPattern)),
+    pattern: distilledPattern
+  }),
+  confidence: 0.95,
+  usage_count: 0,
+  success_count: 0,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+```
+
+---
+
+## Integration with Reasoning Agents
+
+AgentDB provides 4 reasoning modules that enhance ReasoningBank:
+
+### 1. PatternMatcher
+
+Find similar successful patterns:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'problem-solving',
+  k: 10,
+  useMMR: true,  // Maximal Marginal Relevance for diversity
+});
+
+// PatternMatcher returns diverse, relevant memories
+result.memories.forEach(mem => {
+  console.log(`Pattern: ${mem.pattern.approach}`);
+  console.log(`Similarity: ${mem.similarity}`);
+  console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
+});
+```
+
+### 2. ContextSynthesizer
+
+Generate rich context from multiple memories:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'code-optimization',
+  synthesizeContext: true,  // Enable context synthesis
+  k: 5,
+});
+
+// ContextSynthesizer creates coherent narrative
+console.log('Synthesized Context:', result.context);
+// "Based on 5 similar optimizations, the most effective approach
+//  involves profiling, identifying bottlenecks, and applying targeted
+//  improvements. Success rate: 87%"
+```
+
+### 3. MemoryOptimizer
+
+Automatically consolidate and prune:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'testing',
+  optimizeMemory: true,  // Enable automatic optimization
+});
+
+// MemoryOptimizer consolidates similar patterns and prunes low-quality
+console.log('Optimizations:', result.optimizations);
+// { consolidated: 15, pruned: 3, improved_quality: 0.12 }
+```
+
+### 4. ExperienceCurator
+
+Filter by quality and relevance:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'debugging',
+  k: 20,
+  minConfidence: 0.8,  // Only high-confidence experiences
+});
+
+// ExperienceCurator returns only quality experiences
+result.memories.forEach(mem => {
+  console.log(`Confidence: ${mem.confidence}`);
+  console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
+});
+```
+
+---
+
+## Legacy API Compatibility
+
+AgentDB maintains 100% backward compatibility with legacy ReasoningBank:
+
+```typescript
+import {
+  retrieveMemories,
+  judgeTrajectory,
+  distillMemories
+} from 'agentic-flow/reasoningbank';
+
+// Legacy API works unchanged (uses AgentDB backend automatically)
+const memories = await retrieveMemories(query, {
+  domain: 'code-generation',
+  agent: 'coder'
+});
+
+const verdict = await judgeTrajectory(trajectory, query);
+
+const newMemories = await distillMemories(
+  trajectory,
+  verdict,
+  query,
+  { domain: 'code-generation' }
+);
+```
+
+---
+
+## Performance Characteristics
+
+- **Pattern Search**: 150x faster (100µs vs 15ms)
+- **Memory Retrieval**: <1ms (with cache)
+- **Batch Insert**: 500x faster (2ms vs 1s for 100 patterns)
+- **Trajectory Judgment**: <5ms (including retrieval + analysis)
+- **Memory Distillation**: <50ms (consolidate 100 patterns)
+
+---
+
+## Advanced Patterns
+
+### Hierarchical Memory
+
+Organize memories by abstraction level:
+
+```typescript
+// Low-level: Specific implementation
+await rb.insertPattern({
+  type: 'concrete',
+  domain: 'debugging/null-pointer',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: { bug: 'NPE in UserService.getUser()', fix: 'Add null check' }
+  }),
+  confidence: 0.9,
+  // ...
+});
+
+// Mid-level: Pattern across similar cases
+await rb.insertPattern({
+  type: 'pattern',
+  domain: 'debugging',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: { category: 'null-pointer', approach: 'defensive-checks' }
+  }),
+  confidence: 0.85,
+  // ...
+});
+
+// High-level: General principle
+await rb.insertPattern({
+  type: 'principle',
+  domain: 'software-engineering',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: { principle: 'fail-fast with clear errors' }
+  }),
+  confidence: 0.95,
+  // ...
+});
+```
+
+### Multi-Domain Learning
+
+Transfer learning across domains:
+
+```typescript
+// Learn from backend optimization
+const backendExperience = await rb.retrieveWithReasoning(embedding, {
+  domain: 'backend-optimization',
+  k: 10,
+});
+
+// Apply to frontend optimization
+const transferredKnowledge = backendExperience.memories.map(mem => ({
+  ...mem,
+  domain: 'frontend-optimization',
+  adapted: true,
+}));
+```
+
+---
+
+## CLI Operations
+
+### Database Management
+
+```bash
+# Export trajectories and patterns
+npx agentdb@latest export ./.agentdb/reasoningbank.db ./backup.json
+
+# Import experiences
+npx agentdb@latest import ./experiences.json
+
+# Get statistics
+npx agentdb@latest stats ./.agentdb/reasoningbank.db
+# Shows: total patterns, domains, confidence distribution
+```
+
+### Migration
+
+```bash
+# Migrate from legacy ReasoningBank
+npx agentdb@latest migrate --source .swarm/memory.db --target .agentdb/reasoningbank.db
+
+# Validate migration
+npx agentdb@latest stats .agentdb/reasoningbank.db
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Migration fails
+```bash
+# Check source database exists
+ls -la .swarm/memory.db
+
+# Run with verbose logging
+DEBUG=agentdb:* npx agentdb@latest migrate --source .swarm/memory.db
+```
+
+### Issue: Low confidence scores
+```typescript
+// Enable context synthesis for better quality
+const result = await rb.retrieveWithReasoning(embedding, {
+  synthesizeContext: true,
+  useMMR: true,
+  k: 10,
+});
+```
+
+### Issue: Memory growing too large
+```typescript
+// Enable automatic optimization
+const result = await rb.retrieveWithReasoning(embedding, {
+  optimizeMemory: true,  // Consolidates similar patterns
+});
+
+// Or manually optimize
+await rb.optimize();
+```
+
+---
+
+## Learn More
+
+- **AgentDB Integration**: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- **MCP Integration**: `npx agentdb@latest mcp`
+- **Website**: https://agentdb.ruv.io
+
+---
+
+**Category**: Machine Learning / Reinforcement Learning
+**Difficulty**: Intermediate
+**Estimated Time**: 20-30 minutes
@@ -0,0 +1,201 @@
+---
+name: "ReasoningBank Intelligence"
+description: "Implement adaptive learning with ReasoningBank for pattern recognition, strategy optimization, and continuous improvement. Use when building self-learning agents, optimizing workflows, or implementing meta-cognitive systems."
+---
+
+# ReasoningBank Intelligence
+
+## What This Skill Does
+
+Implements ReasoningBank's adaptive learning system for AI agents to learn from experience, recognize patterns, and optimize strategies over time. Enables meta-cognitive capabilities and continuous improvement.
+
+## Prerequisites
+
+- agentic-flow v1.5.11+
+- AgentDB v1.0.4+ (for persistence)
+- Node.js 18+
+
+## Quick Start
+
+```typescript
+import { ReasoningBank } from 'agentic-flow/reasoningbank';
+
+// Initialize ReasoningBank
+const rb = new ReasoningBank({
+  persist: true,
+  learningRate: 0.1,
+  adapter: 'agentdb' // Use AgentDB for storage
+});
+
+// Record task outcome
+await rb.recordExperience({
+  task: 'code_review',
+  approach: 'static_analysis_first',
+  outcome: {
+    success: true,
+    metrics: {
+      bugs_found: 5,
+      time_taken: 120,
+      false_positives: 1
+    }
+  },
+  context: {
+    language: 'typescript',
+    complexity: 'medium'
+  }
+});
+
+// Get optimal strategy
+const strategy = await rb.recommendStrategy('code_review', {
+  language: 'typescript',
+  complexity: 'high'
+});
+```
+
+## Core Features
+
+### 1. Pattern Recognition
+```typescript
+// Learn patterns from data
+await rb.learnPattern({
+  pattern: 'api_errors_increase_after_deploy',
+  triggers: ['deployment', 'traffic_spike'],
+  actions: ['rollback', 'scale_up'],
+  confidence: 0.85
+});
+
+// Match patterns
+const matches = await rb.matchPatterns(currentSituation);
+```
+
+### 2. Strategy Optimization
+```typescript
+// Compare strategies
+const comparison = await rb.compareStrategies('bug_fixing', [
+  'tdd_approach',
+  'debug_first',
+  'reproduce_then_fix'
+]);
+
+// Get best strategy
+const best = comparison.strategies[0];
+console.log(`Best: ${best.name} (score: ${best.score})`);
+```
+
+### 3. Continuous Learning
+```typescript
+// Enable auto-learning from all tasks
+await rb.enableAutoLearning({
+  threshold: 0.7,        // Only learn from high-confidence outcomes
+  updateFrequency: 100   // Update models every 100 experiences
+});
+```
+
+## Advanced Usage
+
+### Meta-Learning
+```typescript
+// Learn about learning
+await rb.metaLearn({
+  observation: 'parallel_execution_faster_for_independent_tasks',
+  confidence: 0.95,
+  applicability: {
+    task_types: ['batch_processing', 'data_transformation'],
+    conditions: ['tasks_independent', 'io_bound']
+  }
+});
+```
+
+### Transfer Learning
+```typescript
+// Apply knowledge from one domain to another
+await rb.transferKnowledge({
+  from: 'code_review_javascript',
+  to: 'code_review_typescript',
+  similarity: 0.8
+});
+```
+
+### Adaptive Agents
+```typescript
+// Create self-improving agent
+class AdaptiveAgent {
+  async execute(task: Task) {
+    // Get optimal strategy
+    const strategy = await rb.recommendStrategy(task.type, task.context);
+
+    // Execute with strategy
+    const result = await this.executeWithStrategy(task, strategy);
+
+    // Learn from outcome
+    await rb.recordExperience({
+      task: task.type,
+      approach: strategy.name,
+      outcome: result,
+      context: task.context
+    });
+
+    return result;
+  }
+}
+```
+
+## Integration with AgentDB
+
+```typescript
+// Persist ReasoningBank data
+await rb.configure({
+  storage: {
+    type: 'agentdb',
+    options: {
+      database: './reasoning-bank.db',
+      enableVectorSearch: true
+    }
+  }
+});
+
+// Query learned patterns
+const patterns = await rb.query({
+  category: 'optimization',
+  minConfidence: 0.8,
+  timeRange: { last: '30d' }
+});
+```
+
+## Performance Metrics
+
+```typescript
+// Track learning effectiveness
+const metrics = await rb.getMetrics();
+console.log(`
+  Total Experiences: ${metrics.totalExperiences}
+  Patterns Learned: ${metrics.patternsLearned}
+  Strategy Success Rate: ${metrics.strategySuccessRate}
+  Improvement Over Time: ${metrics.improvement}
+`);
+```
+
+## Best Practices
+
+1. **Record consistently**: Log all task outcomes, not just successes
+2. **Provide context**: Rich context improves pattern matching
+3. **Set thresholds**: Filter low-confidence learnings
+4. **Review periodically**: Audit learned patterns for quality
+5. **Use vector search**: Enable semantic pattern matching
+
+## Troubleshooting
+
+### Issue: Poor recommendations
+**Solution**: Ensure sufficient training data (100+ experiences per task type)
+
+### Issue: Slow pattern matching
+**Solution**: Enable vector indexing in AgentDB
+
+### Issue: Memory growing large
+**Solution**: Set TTL for old experiences or enable pruning
+
+## Learn More
+
+- ReasoningBank Guide: agentic-flow/src/reasoningbank/README.md
+- AgentDB Integration: packages/agentdb/docs/reasoningbank.md
+- Pattern Learning: docs/reasoning/patterns.md
@@ -0,0 +1,910 @@
+---
+name: "Skill Builder"
+description: "Create new Claude Code Skills with proper YAML frontmatter, progressive disclosure structure, and complete directory organization. Use when you need to build custom skills for specific workflows, generate skill templates, or understand the Claude Skills specification."
+---
+
+# Skill Builder
+
+## What This Skill Does
+
+Creates production-ready Claude Code Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file/folder structure. This skill guides you through building skills that Claude can autonomously discover and use across all surfaces (Claude.ai, Claude Code, SDK, API).
+
+## Prerequisites
+
+- Claude Code 2.0+ or Claude.ai with Skills support
+- Basic understanding of Markdown and YAML
+- Text editor or IDE
+
+## Quick Start
+
+### Creating Your First Skill
+
+```bash
+# 1. Create skill directory (MUST be at top level, NOT in subdirectories!)
+mkdir -p ~/.claude/skills/my-first-skill
+
+# 2. Create SKILL.md with proper format
+cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
+---
+name: "My First Skill"
+description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
+---
+
+# My First Skill
+
+## What This Skill Does
+[Your instructions here]
+
+## Quick Start
+[Basic usage]
+EOF
+
+# 3. Verify skill is detected
+# Restart Claude Code or refresh Claude.ai
+```
+
+---
+
+## Complete Specification
+
+### 📋 YAML Frontmatter (REQUIRED)
+
+Every SKILL.md **must** start with YAML frontmatter containing exactly two required fields:
+
+```yaml
+---
+name: "Skill Name"                    # REQUIRED: Max 64 chars
+description: "What this skill does    # REQUIRED: Max 1024 chars
+and when Claude should use it."       # Include BOTH what & when
+---
+```
+
+#### Field Requirements
+
+**`name`** (REQUIRED):
+- **Type**: String
+- **Max Length**: 64 characters
+- **Format**: Human-friendly display name
+- **Usage**: Shown in skill lists, UI, and loaded into Claude's system prompt
+- **Best Practice**: Use Title Case, be concise and descriptive
+- **Examples**:
+  - ✅ "API Documentation Generator"
+  - ✅ "React Component Builder"
+  - ✅ "Database Schema Designer"
+  - ❌ "skill-1" (not descriptive)
+  - ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)
+
+**`description`** (REQUIRED):
+- **Type**: String
+- **Max Length**: 1024 characters
+- **Format**: Plain text or minimal markdown
+- **Content**: MUST include:
+  1. **What** the skill does (functionality)
+  2. **When** Claude should invoke it (trigger conditions)
+- **Usage**: Loaded into Claude's system prompt for autonomous matching
+- **Best Practice**: Front-load key trigger words, be specific about use cases
+- **Examples**:
+  - ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
+  - ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
+  - ❌ "A comprehensive guide to API documentation" (no "when" clause)
+  - ❌ "Documentation tool" (too vague)
+
+#### YAML Formatting Rules
+
+```yaml
+---
+# ✅ CORRECT: Simple string
+name: "API Builder"
+description: "Creates REST APIs with Express and TypeScript."
+
+# ✅ CORRECT: Multi-line description
+name: "Full-Stack Generator"
+description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."
+
+# ✅ CORRECT: Special characters quoted
+name: "JSON:API Builder"
+description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships."
+
+# ❌ WRONG: Missing quotes with special chars
+name: API:Builder  # YAML parse error!
+
+# ❌ WRONG: Extra fields (ignored but discouraged)
+name: "My Skill"
+description: "My description"
+version: "1.0.0"       # NOT part of spec
+author: "Me"           # NOT part of spec
+tags: ["dev", "api"]   # NOT part of spec
+---
+```
+
+**Critical**: Only `name` and `description` are used by Claude. Additional fields are ignored.
+
+---
+
+### 📂 Directory Structure
+
+#### Minimal Skill (Required)
+```
+~/.claude/skills/                    # Personal skills location
+└── my-skill/                        # Skill directory (MUST be at top level!)
+    └── SKILL.md                     # REQUIRED: Main skill file
+```
+
+**IMPORTANT**: Skills MUST be directly under `~/.claude/skills/[skill-name]/`.
+Claude Code does NOT support nested subdirectories or namespaces!
+
+#### Full-Featured Skill (Recommended)
+```
+~/.claude/skills/
+└── my-skill/                        # Top-level skill directory
+        ├── SKILL.md                 # REQUIRED: Main skill file
+        ├── README.md                # Optional: Human-readable docs
+        ├── scripts/                 # Optional: Executable scripts
+        │   ├── setup.sh
+        │   ├── validate.js
+        │   └── deploy.py
+        ├── resources/               # Optional: Supporting files
+        │   ├── templates/
+        │   │   ├── api-template.js
+        │   │   └── component.tsx
+        │   ├── examples/
+        │   │   └── sample-output.json
+        │   └── schemas/
+        │       └── config-schema.json
+        └── docs/                    # Optional: Additional documentation
+            ├── ADVANCED.md
+            ├── TROUBLESHOOTING.md
+            └── API_REFERENCE.md
+```
+
+#### Skills Locations
+
+**Personal Skills** (available across all projects):
+```
+~/.claude/skills/
+└── [your-skills]/
+```
+- **Path**: `~/.claude/skills/` or `$HOME/.claude/skills/`
+- **Scope**: Available in all projects for this user
+- **Version Control**: NOT committed to git (outside repo)
+- **Use Case**: Personal productivity tools, custom workflows
+
+**Project Skills** (team-shared, version controlled):
+```
+<project-root>/.claude/skills/
+└── [team-skills]/
+```
+- **Path**: `.claude/skills/` in project root
+- **Scope**: Available only in this project
+- **Version Control**: SHOULD be committed to git
+- **Use Case**: Team workflows, project-specific tools, shared knowledge
+
+---
+
+### 🎯 Progressive Disclosure Architecture
+
+Claude Code uses a **3-level progressive disclosure system** to scale to 100+ skills without context penalty:
+
+#### Level 1: Metadata (Name + Description)
+**Loaded**: At Claude Code startup, always
+**Size**: ~200 chars per skill
+**Purpose**: Enable autonomous skill matching
+**Context**: Loaded into system prompt for ALL skills
+
+```yaml
+---
+name: "API Builder"                   # 11 chars
+description: "Creates REST APIs..."   # ~50 chars
+---
+# Total: ~61 chars per skill
+# 100 skills = ~6KB context (minimal!)
+```
+
+#### Level 2: SKILL.md Body
+**Loaded**: When skill is triggered/matched
+**Size**: ~1-10KB typically
+**Purpose**: Main instructions and procedures
+**Context**: Only loaded for ACTIVE skills
+
+```markdown
+# API Builder
+
+## What This Skill Does
+[Main instructions - loaded only when skill is active]
+
+## Quick Start
+[Basic procedures]
+
+## Step-by-Step Guide
+[Detailed instructions]
+```
+
+#### Level 3+: Referenced Files
+**Loaded**: On-demand as Claude navigates
+**Size**: Variable (KB to MB)
+**Purpose**: Deep reference, examples, schemas
+**Context**: Loaded only when Claude accesses specific files
+
+```markdown
+# In SKILL.md
+See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
+See [API Reference](docs/API_REFERENCE.md) for complete documentation.
+Use template: `resources/templates/api-template.js`
+
+# Claude will load these files ONLY if needed
+```
+
+**Benefit**: Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context.
+
+---
+
+### 📝 SKILL.md Content Structure
+
+#### Recommended 4-Level Structure
+
+```markdown
+---
+name: "Your Skill Name"
+description: "What it does and when to use it"
+---
+
+# Your Skill Name
+
+## Level 1: Overview (Always Read First)
+Brief 2-3 sentence description of the skill.
+
+## Prerequisites
+- Requirement 1
+- Requirement 2
+
+## What This Skill Does
+1. Primary function
+2. Secondary function
+3. Key benefit
+
+---
+
+## Level 2: Quick Start (For Fast Onboarding)
+
+### Basic Usage
+```bash
+# Simplest use case
+command --option value
+```
+
+### Common Scenarios
+1. **Scenario 1**: How to...
+2. **Scenario 2**: How to...
+
+---
+
+## Level 3: Detailed Instructions (For Deep Work)
+
+### Step-by-Step Guide
+
+#### Step 1: Initial Setup
+```bash
+# Commands
+```
+Expected output:
+```
+Success message
+```
+
+#### Step 2: Configuration
+- Configuration option 1
+- Configuration option 2
+
+#### Step 3: Execution
+- Run the main command
+- Verify results
+
+### Advanced Options
+
+#### Option 1: Custom Configuration
+```bash
+# Advanced usage
+```
+
+#### Option 2: Integration
+```bash
+# Integration steps
+```
+
+---
+
+## Level 4: Reference (Rarely Needed)
+
+### Troubleshooting
+
+#### Issue: Common Problem
+**Symptoms**: What you see
+**Cause**: Why it happens
+**Solution**: How to fix
+```bash
+# Fix command
+```
+
+#### Issue: Another Problem
+**Solution**: Steps to resolve
+
+### Complete API Reference
+See [API_REFERENCE.md](docs/API_REFERENCE.md)
+
+### Examples
+See [examples/](resources/examples/)
+
+### Related Skills
+- [Related Skill 1](#)
+- [Related Skill 2](#)
+
+### Resources
+- [External Link 1](https://example.com)
+- [Documentation](https://docs.example.com)
+```
+
+---
+
+### 🎨 Content Best Practices
+
+#### Writing Effective Descriptions
+
+**Front-Load Keywords**:
+```yaml
+# ✅ GOOD: Keywords first
+description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients."
+
+# ❌ BAD: Keywords buried
+description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces."
+```
+
+**Include Trigger Conditions**:
+```yaml
+# ✅ GOOD: Clear "when" clause
+description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size."
+
+# ❌ BAD: No trigger conditions
+description: "Helps with React performance debugging."
+```
+
+**Be Specific**:
+```yaml
+# ✅ GOOD: Specific technologies
+description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints."
+
+# ❌ BAD: Too generic
+description: "Build API endpoints with proper validation and testing."
+```
+
+#### Progressive Disclosure Writing
+
+**Keep Level 1 Brief** (Overview):
+```markdown
+## What This Skill Does
+Creates production-ready React components with TypeScript, hooks, and tests in 3 steps.
+```
+
+**Level 2 for Common Paths** (Quick Start):
+```markdown
+## Quick Start
+```bash
+# Most common use case (80% of users)
+generate-component MyComponent
+```
+```
+
+**Level 3 for Details** (Step-by-Step):
+```markdown
+## Step-by-Step Guide
+
+### Creating a Basic Component
+1. Run generator
+2. Choose template
+3. Customize options
+[Detailed explanations]
+```
+
+**Level 4 for Edge Cases** (Reference):
+```markdown
+## Advanced Configuration
+For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md).
+```
+
+---
+
+### 🛠️ Adding Scripts and Resources
+
+#### Scripts Directory
+
+**Purpose**: Executable scripts that Claude can run
+**Location**: `scripts/` in skill directory
+**Usage**: Referenced from SKILL.md
+
+Example:
+```bash
+# In skill directory
+scripts/
+├── setup.sh          # Initialization script
+├── validate.js       # Validation logic
+├── generate.py       # Code generation
+└── deploy.sh         # Deployment script
+```
+
+Reference from SKILL.md:
+```markdown
+## Setup
+Run the setup script:
+```bash
+./scripts/setup.sh
+```
+
+## Validation
+Validate your configuration:
+```bash
+node scripts/validate.js config.json
+```
+```
+
+#### Resources Directory
+
+**Purpose**: Templates, examples, schemas, static files
+**Location**: `resources/` in skill directory
+**Usage**: Referenced or copied by scripts
+
+Example:
+```bash
+resources/
+├── templates/
+│   ├── component.tsx.template
+│   ├── test.spec.ts.template
+│   └── story.stories.tsx.template
+├── examples/
+│   ├── basic-example/
+│   ├── advanced-example/
+│   └── integration-example/
+└── schemas/
+    ├── config.schema.json
+    └── output.schema.json
+```
+
+Reference from SKILL.md:
+```markdown
+## Templates
+Use the component template:
+```bash
+cp resources/templates/component.tsx.template src/components/MyComponent.tsx
+```
+
+## Examples
+See working examples in `resources/examples/`:
+- `basic-example/` - Simple component
+- `advanced-example/` - With hooks and context
+```
+
+---
+
+### 🔗 File References and Navigation
+
+Claude can navigate to referenced files automatically. Use these patterns:
+
+#### Markdown Links
+```markdown
+See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
+See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors.
+```
+
+#### Relative File Paths
+```markdown
+Use the template located at `resources/templates/api-template.js`
+See examples in `resources/examples/basic-usage/`
+```
+
+#### Inline File Content
+```markdown
+## Example Configuration
+See `resources/examples/config.json`:
+```json
+{
+  "option": "value"
+}
+```
+```
+
+**Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed.
+
+---
+
+### ✅ Validation Checklist
+
+Before publishing a skill, verify:
+
+**YAML Frontmatter**:
+- [ ] Starts with `---`
+- [ ] Contains `name` field (max 64 chars)
+- [ ] Contains `description` field (max 1024 chars)
+- [ ] Description includes "what" and "when"
+- [ ] Ends with `---`
+- [ ] No YAML syntax errors
+
+**File Structure**:
+- [ ] SKILL.md exists in skill directory
+- [ ] Directory is DIRECTLY in `~/.claude/skills/[skill-name]/` or `.claude/skills/[skill-name]/`
+- [ ] Uses clear, descriptive directory name
+- [ ] **NO nested subdirectories** (Claude Code requires top-level structure)
+
+**Content Quality**:
+- [ ] Level 1 (Overview) is brief and clear
+- [ ] Level 2 (Quick Start) shows common use case
+- [ ] Level 3 (Details) provides step-by-step guide
+- [ ] Level 4 (Reference) links to advanced content
+- [ ] Examples are concrete and runnable
+- [ ] Troubleshooting section addresses common issues
+
+**Progressive Disclosure**:
+- [ ] Core instructions in SKILL.md (~2-5KB)
+- [ ] Advanced content in separate docs/
+- [ ] Large resources in resources/ directory
+- [ ] Clear navigation between levels
+
+**Testing**:
+- [ ] Skill appears in Claude's skill list
+- [ ] Description triggers on relevant queries
+- [ ] Instructions are clear and actionable
+- [ ] Scripts execute successfully (if included)
+- [ ] Examples work as documented
+
+---
+
+## Skill Builder Templates
+
+### Template 1: Basic Skill (Minimal)
+
+```markdown
+---
+name: "My Basic Skill"
+description: "One sentence what. One sentence when to use."
+---
+
+# My Basic Skill
+
+## What This Skill Does
+[2-3 sentences describing functionality]
+
+## Quick Start
+```bash
+# Single command to get started
+```
+
+## Step-by-Step Guide
+
+### Step 1: Setup
+[Instructions]
+
+### Step 2: Usage
+[Instructions]
+
+### Step 3: Verify
+[Instructions]
+
+## Troubleshooting
+- **Issue**: Problem description
+  - **Solution**: Fix description
+```
+
+### Template 2: Intermediate Skill (With Scripts)
+
+```markdown
+---
+name: "My Intermediate Skill"
+description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building."
+---
+
+# My Intermediate Skill
+
+## Prerequisites
+- Requirement 1
+- Requirement 2
+
+## What This Skill Does
+1. Primary function
+2. Secondary function
+3. Integration capability
+
+## Quick Start
+```bash
+./scripts/setup.sh
+./scripts/generate.sh my-project
+```
+
+## Configuration
+Edit `config.json`:
+```json
+{
+  "option1": "value1",
+  "option2": "value2"
+}
+```
+
+## Step-by-Step Guide
+
+### Basic Usage
+[Steps for 80% use case]
+
+### Advanced Usage
+[Steps for complex scenarios]
+
+## Available Scripts
+- `scripts/setup.sh` - Initial setup
+- `scripts/generate.sh` - Code generation
+- `scripts/validate.sh` - Validation
+
+## Resources
+- Templates: `resources/templates/`
+- Examples: `resources/examples/`
+
+## Troubleshooting
+[Common issues and solutions]
+```
+
+### Template 3: Advanced Skill (Full-Featured)
+
+```markdown
+---
+name: "My Advanced Skill"
+description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]."
+---
+
+# My Advanced Skill
+
+## Overview
+[Brief 2-3 sentence description]
+
+## Prerequisites
+- Technology 1 (version X+)
+- Technology 2 (version Y+)
+- API keys or credentials
+
+## What This Skill Does
+1. **Core Feature**: Description
+2. **Integration**: Description
+3. **Automation**: Description
+
+---
+
+## Quick Start (60 seconds)
+
+### Installation
+```bash
+./scripts/install.sh
+```
+
+### First Use
+```bash
+./scripts/quickstart.sh
+```
+
+Expected output:
+```
+✓ Setup complete
+✓ Configuration validated
+→ Ready to use
+```
+
+---
+
+## Configuration
+
+### Basic Configuration
+Edit `config.json`:
+```json
+{
+  "mode": "production",
+  "features": ["feature1", "feature2"]
+}
+```
+
+### Advanced Configuration
+See [Configuration Guide](docs/CONFIGURATION.md)
+
+---
+
+## Step-by-Step Guide
+
+### 1. Initial Setup
+[Detailed steps]
+
+### 2. Core Workflow
+[Main procedures]
+
+### 3. Integration
+[Integration steps]
+
+---
+
+## Advanced Features
+
+### Feature 1: Custom Templates
+```bash
+./scripts/generate.sh --template custom
+```
+
+### Feature 2: Batch Processing
+```bash
+./scripts/batch.sh --input data.json
+```
+
+### Feature 3: CI/CD Integration
+See [CI/CD Guide](docs/CICD.md)
+
+---
+
+## Scripts Reference
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `install.sh` | Install dependencies | `./scripts/install.sh` |
+| `generate.sh` | Generate code | `./scripts/generate.sh [name]` |
+| `validate.sh` | Validate output | `./scripts/validate.sh` |
+| `deploy.sh` | Deploy to environment | `./scripts/deploy.sh [env]` |
+
+---
+
+## Resources
+
+### Templates
+- `resources/templates/basic.template` - Basic template
+- `resources/templates/advanced.template` - Advanced template
+
+### Examples
+- `resources/examples/basic/` - Simple example
+- `resources/examples/advanced/` - Complex example
+- `resources/examples/integration/` - Integration example
+
+### Schemas
+- `resources/schemas/config.schema.json` - Configuration schema
+- `resources/schemas/output.schema.json` - Output validation
+
+---
+
+## Troubleshooting
+
+### Issue: Installation Failed
+**Symptoms**: Error during `install.sh`
+**Cause**: Missing dependencies
+**Solution**:
+```bash
+# Install prerequisites
+npm install -g required-package
+./scripts/install.sh --force
+```
+
+### Issue: Validation Errors
+**Symptoms**: Validation script fails
+**Solution**: See [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
+
+---
+
+## API Reference
+Complete API documentation: [API_REFERENCE.md](docs/API_REFERENCE.md)
+
+## Related Skills
+- [Related Skill 1](../related-skill-1/)
+- [Related Skill 2](../related-skill-2/)
+
+## Resources
+- [Official Documentation](https://example.com/docs)
+- [GitHub Repository](https://github.com/example/repo)
+- [Community Forum](https://forum.example.com)
+
+---
+
+**Created**: 2025-10-19
+**Category**: Advanced
+**Difficulty**: Intermediate
+**Estimated Time**: 15-30 minutes
+```
+
+---
+
+## Examples from the Wild
+
+### Example 1: Simple Documentation Skill
+
+```markdown
+---
+name: "README Generator"
+description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs."
+---
+
+# README Generator
+
+## What This Skill Does
+Creates well-structured README.md files with badges, installation, usage, and contribution sections.
+
+## Quick Start
+```bash
+# Answer a few questions
+./scripts/generate-readme.sh
+
+# README.md created with:
+# - Project title and description
+# - Installation instructions
+# - Usage examples
+# - Contribution guidelines
+```
+
+## Customization
+Edit sections in `resources/templates/sections/` before generating.
+```
+
+### Example 2: Code Generation Skill
+
+```markdown
+---
+name: "React Component Generator"
+description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns."
+---
+
+# React Component Generator
+
+## Prerequisites
+- Node.js 18+
+- React 18+
+- TypeScript 5+
+
+## Quick Start
+```bash
+./scripts/generate-component.sh MyComponent
+
+# Creates:
+# - src/components/MyComponent/MyComponent.tsx
+# - src/components/MyComponent/MyComponent.test.tsx
+# - src/components/MyComponent/MyComponent.stories.tsx
+# - src/components/MyComponent/index.ts
+```
+
+## Step-by-Step Guide
+
+### 1. Run Generator
+```bash
+./scripts/generate-component.sh ComponentName
+```
+
+### 2. Choose Template
+- Basic: Simple functional component
+- With State: useState hooks
+- With Context: useContext integration
+- With API: Data fetching component
+
+### 3. Customize
+Edit generated files in `src/components/ComponentName/`
+
+## Templates
+See `resources/templates/` for available component templates.
+```
+
+---
+
+## Learn More
+
+### Official Resources
+- [Anthropic Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
+- [GitHub Skills Repository](https://github.com/anthropics/skills)
+- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
+
+### Community
+- [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills
+- [Anthropic Discord](https://discord.gg/anthropic) - Get help from community
+
+### Advanced Topics
+- Multi-file skills with complex navigation
+- Skills that spawn other skills
+- Integration with MCP tools
+- Dynamic skill generation
+
+---
+
+**Created**: 2025-10-19
+**Version**: 1.0.0
+**Maintained By**: agentic-flow team
+**License**: MIT
@@ -0,0 +1,563 @@
+---
+name: stream-chain
+description: Stream-JSON chaining for multi-agent pipelines, data transformation, and sequential workflows
+version: 1.0.0
+category: workflow
+tags: [streaming, pipeline, chaining, multi-agent, workflow]
+---
+
+# Stream-Chain Skill
+
+Execute sophisticated multi-step workflows where each agent's output flows into the next, enabling complex data transformations and sequential processing pipelines.
+
+## Overview
+
+Stream-Chain provides two powerful modes for orchestrating multi-agent workflows:
+
+1. **Custom Chains** (`run`): Execute custom prompt sequences with full control
+2. **Predefined Pipelines** (`pipeline`): Use battle-tested workflows for common tasks
+
+Each step in a chain receives the complete output from the previous step, enabling sophisticated multi-agent coordination through streaming data flow.
+
+---
+
+## Quick Start
+
+### Run a Custom Chain
+
+```bash
+claude-flow stream-chain run \
+  "Analyze codebase structure" \
+  "Identify improvement areas" \
+  "Generate action plan"
+```
+
+### Execute a Pipeline
+
+```bash
+claude-flow stream-chain pipeline analysis
+```
+
+---
+
+## Custom Chains (`run`)
+
+Execute custom stream chains with your own prompts for maximum flexibility.
+
+### Syntax
+
+```bash
+claude-flow stream-chain run <prompt1> <prompt2> [...] [options]
+```
+
+**Requirements:**
+- Minimum 2 prompts required
+- Each prompt becomes a step in the chain
+- Output flows sequentially through all steps
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--verbose` | Show detailed execution information | `false` |
+| `--timeout <seconds>` | Timeout per step | `30` |
+| `--debug` | Enable debug mode with full logging | `false` |
+
+### How Context Flows
+
+Each step receives the previous output as context:
+
+```
+Step 1: "Write a sorting function"
+Output: [function implementation]
+
+Step 2 receives:
+  "Previous step output:
+  [function implementation]
+
+  Next task: Add comprehensive tests"
+
+Step 3 receives:
+  "Previous steps output:
+  [function + tests]
+
+  Next task: Optimize performance"
+```
+
+### Examples
+
+#### Basic Development Chain
+
+```bash
+claude-flow stream-chain run \
+  "Write a user authentication function" \
+  "Add input validation and error handling" \
+  "Create unit tests with edge cases"
+```
+
+#### Security Audit Workflow
+
+```bash
+claude-flow stream-chain run \
+  "Analyze authentication system for vulnerabilities" \
+  "Identify and categorize security issues by severity" \
+  "Propose fixes with implementation priority" \
+  "Generate security test cases" \
+  --timeout 45 \
+  --verbose
+```
+
+#### Code Refactoring Chain
+
+```bash
+claude-flow stream-chain run \
+  "Identify code smells in src/ directory" \
+  "Create refactoring plan with specific changes" \
+  "Apply refactoring to top 3 priority items" \
+  "Verify refactored code maintains behavior" \
+  --debug
+```
+
+#### Data Processing Pipeline
+
+```bash
+claude-flow stream-chain run \
+  "Extract data from API responses" \
+  "Transform data into normalized format" \
+  "Validate data against schema" \
+  "Generate data quality report"
+```
+
+---
+
+## Predefined Pipelines (`pipeline`)
+
+Execute battle-tested workflows optimized for common development tasks.
+
+### Syntax
+
+```bash
+claude-flow stream-chain pipeline <type> [options]
+```
+
+### Available Pipelines
+
+#### 1. Analysis Pipeline
+
+Comprehensive codebase analysis and improvement identification.
+
+```bash
+claude-flow stream-chain pipeline analysis
+```
+
+**Workflow Steps:**
+1. **Structure Analysis**: Map directory structure and identify components
+2. **Issue Detection**: Find potential improvements and problems
+3. **Recommendations**: Generate actionable improvement report
+
+**Use Cases:**
+- New codebase onboarding
+- Technical debt assessment
+- Architecture review
+- Code quality audits
+
+#### 2. Refactor Pipeline
+
+Systematic code refactoring with prioritization.
+
+```bash
+claude-flow stream-chain pipeline refactor
+```
+
+**Workflow Steps:**
+1. **Candidate Identification**: Find code needing refactoring
+2. **Prioritization**: Create ranked refactoring plan
+3. **Implementation**: Provide refactored code for top priorities
+
+**Use Cases:**
+- Technical debt reduction
+- Code quality improvement
+- Legacy code modernization
+- Design pattern implementation
+
+#### 3. Test Pipeline
+
+Comprehensive test generation with coverage analysis.
+
+```bash
+claude-flow stream-chain pipeline test
+```
+
+**Workflow Steps:**
+1. **Coverage Analysis**: Identify areas lacking tests
+2. **Test Design**: Create test cases for critical functions
+3. **Implementation**: Generate unit tests with assertions
+
+**Use Cases:**
+- Increasing test coverage
+- TDD workflow support
+- Regression test creation
+- Quality assurance
+
+#### 4. Optimize Pipeline
+
+Performance optimization with profiling and implementation.
+
+```bash
+claude-flow stream-chain pipeline optimize
+```
+
+**Workflow Steps:**
+1. **Profiling**: Identify performance bottlenecks
+2. **Strategy**: Analyze and suggest optimization approaches
+3. **Implementation**: Provide optimized code
+
+**Use Cases:**
+- Performance improvement
+- Resource optimization
+- Scalability enhancement
+- Latency reduction
+
+### Pipeline Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--verbose` | Show detailed execution | `false` |
+| `--timeout <seconds>` | Timeout per step | `30` |
+| `--debug` | Enable debug mode | `false` |
+
+### Pipeline Examples
+
+#### Quick Analysis
+
+```bash
+claude-flow stream-chain pipeline analysis
+```
+
+#### Extended Refactoring
+
+```bash
+claude-flow stream-chain pipeline refactor --timeout 60 --verbose
+```
+
+#### Debug Test Generation
+
+```bash
+claude-flow stream-chain pipeline test --debug
+```
+
+#### Comprehensive Optimization
+
+```bash
+claude-flow stream-chain pipeline optimize --timeout 90 --verbose
+```
+
+### Pipeline Output
+
+Each pipeline execution provides:
+
+- **Progress**: Step-by-step execution status
+- **Results**: Success/failure per step
+- **Timing**: Total and per-step execution time
+- **Summary**: Consolidated results and recommendations
+
+---
+
+## Custom Pipeline Definitions
+
+Define reusable pipelines in `.claude-flow/config.json`:
+
+### Configuration Format
+
+```json
+{
+  "streamChain": {
+    "pipelines": {
+      "security": {
+        "name": "Security Audit Pipeline",
+        "description": "Comprehensive security analysis",
+        "prompts": [
+          "Scan codebase for security vulnerabilities",
+          "Categorize issues by severity (critical/high/medium/low)",
+          "Generate fixes with priority and implementation steps",
+          "Create security test suite"
+        ],
+        "timeout": 45
+      },
+      "documentation": {
+        "name": "Documentation Generation Pipeline",
+        "prompts": [
+          "Analyze code structure and identify undocumented areas",
+          "Generate API documentation with examples",
+          "Create usage guides and tutorials",
+          "Build architecture diagrams and flow charts"
+        ]
+      }
+    }
+  }
+}
+```
+
+### Execute Custom Pipeline
+
+```bash
+claude-flow stream-chain pipeline security
+claude-flow stream-chain pipeline documentation
+```
+
+---
+
+## Advanced Use Cases
+
+### Multi-Agent Coordination
+
+Chain different agent types for complex workflows:
+
+```bash
+claude-flow stream-chain run \
+  "Research best practices for API design" \
+  "Design REST API with discovered patterns" \
+  "Implement API endpoints with validation" \
+  "Generate OpenAPI specification" \
+  "Create integration tests" \
+  "Write deployment documentation"
+```
+
+### Data Transformation Pipeline
+
+Process and transform data through multiple stages:
+
+```bash
+claude-flow stream-chain run \
+  "Extract user data from CSV files" \
+  "Normalize and validate data format" \
+  "Enrich data with external API calls" \
+  "Generate analytics report" \
+  "Create visualization code"
+```
+
+### Code Migration Workflow
+
+Systematic code migration with validation:
+
+```bash
+claude-flow stream-chain run \
+  "Analyze legacy codebase dependencies" \
+  "Create migration plan with risk assessment" \
+  "Generate modernized code for high-priority modules" \
+  "Create migration tests" \
+  "Document migration steps and rollback procedures"
+```
+
+### Quality Assurance Chain
+
+Comprehensive code quality workflow:
+
+```bash
+claude-flow stream-chain pipeline analysis
+claude-flow stream-chain pipeline refactor
+claude-flow stream-chain pipeline test
+claude-flow stream-chain pipeline optimize
+```
+
+---
+
+## Best Practices
+
+### 1. Clear and Specific Prompts
+
+**Good:**
+```bash
+"Analyze authentication.js for SQL injection vulnerabilities"
+```
+
+**Avoid:**
+```bash
+"Check security"
+```
+
+### 2. Logical Progression
+
+Order prompts to build on previous outputs:
+```bash
+1. "Identify the problem"
+2. "Analyze root causes"
+3. "Design solution"
+4. "Implement solution"
+5. "Verify implementation"
+```
+
+### 3. Appropriate Timeouts
+
+- Simple tasks: 30 seconds (default)
+- Analysis tasks: 45-60 seconds
+- Implementation tasks: 60-90 seconds
+- Complex workflows: 90-120 seconds
+
+### 4. Verification Steps
+
+Include validation in your chains:
+```bash
+claude-flow stream-chain run \
+  "Implement feature X" \
+  "Write tests for feature X" \
+  "Verify tests pass and cover edge cases"
+```
+
+### 5. Iterative Refinement
+
+Use chains for iterative improvement:
+```bash
+claude-flow stream-chain run \
+  "Generate initial implementation" \
+  "Review and identify issues" \
+  "Refine based on issues found" \
+  "Final quality check"
+```
+
+---
+
+## Integration with Claude Flow
+
+### Combine with Swarm Coordination
+
+```bash
+# Initialize swarm for coordination
+claude-flow swarm init --topology mesh
+
+# Execute stream chain with swarm agents
+claude-flow stream-chain run \
+  "Agent 1: Research task" \
+  "Agent 2: Implement solution" \
+  "Agent 3: Test implementation" \
+  "Agent 4: Review and refine"
+```
+
+### Memory Integration
+
+Stream chains automatically store context in memory for cross-session persistence:
+
+```bash
+# Execute chain with memory
+claude-flow stream-chain run \
+  "Analyze requirements" \
+  "Design architecture" \
+  --verbose
+
+# Results stored in .claude-flow/memory/stream-chain/
+```
+
+### Neural Pattern Training
+
+Successful chains train neural patterns for improved performance:
+
+```bash
+# Enable neural training
+claude-flow stream-chain pipeline optimize --debug
+
+# Patterns learned and stored for future optimizations
+```
+
+---
+
+## Troubleshooting
+
+### Chain Timeout
+
+If steps timeout, increase timeout value:
+
+```bash
+claude-flow stream-chain run "complex task" --timeout 120
+```
+
+### Context Loss
+
+If context not flowing properly, use `--debug`:
+
+```bash
+claude-flow stream-chain run "step 1" "step 2" --debug
+```
+
+### Pipeline Not Found
+
+Verify pipeline name and custom definitions:
+
+```bash
+# Check available pipelines
+cat .claude-flow/config.json | grep -A 10 "streamChain"
+```
+
+---
+
+## Performance Characteristics
+
+- **Throughput**: 2-5 steps per minute (varies by complexity)
+- **Context Size**: Up to 100K tokens per step
+- **Memory Usage**: ~50MB per active chain
+- **Concurrency**: Supports parallel chain execution
+
+---
+
+## Related Skills
+
+- **SPARC Methodology**: Systematic development workflow
+- **Swarm Coordination**: Multi-agent orchestration
+- **Memory Management**: Persistent context storage
+- **Neural Patterns**: Adaptive learning
+
+---
+
+## Examples Repository
+
+### Complete Development Workflow
+
+```bash
+# Full feature development chain
+claude-flow stream-chain run \
+  "Analyze requirements for user profile feature" \
+  "Design database schema and API endpoints" \
+  "Implement backend with validation" \
+  "Create frontend components" \
+  "Write comprehensive tests" \
+  "Generate API documentation" \
+  --timeout 60 \
+  --verbose
+```
+
+### Code Review Pipeline
+
+```bash
+# Automated code review workflow
+claude-flow stream-chain run \
+  "Analyze recent git changes" \
+  "Identify code quality issues" \
+  "Check for security vulnerabilities" \
+  "Verify test coverage" \
+  "Generate code review report with recommendations"
+```
+
+### Migration Assistant
+
+```bash
+# Framework migration helper
+claude-flow stream-chain run \
+  "Analyze current Vue 2 codebase" \
+  "Identify Vue 3 breaking changes" \
+  "Create migration checklist" \
+  "Generate migration scripts" \
+  "Provide updated code examples"
+```
+
+---
+
+## Conclusion
+
+Stream-Chain enables sophisticated multi-step workflows by:
+
+- **Sequential Processing**: Each step builds on previous results
+- **Context Preservation**: Full output history flows through chain
+- **Flexible Orchestration**: Custom chains or predefined pipelines
+- **Agent Coordination**: Natural multi-agent collaboration pattern
+- **Data Transformation**: Complex processing through simple steps
+
+Use `run` for custom workflows and `pipeline` for battle-tested solutions.
@@ -0,0 +1,973 @@
+---
+name: swarm-advanced
+description: Advanced swarm orchestration patterns for research, development, testing, and complex distributed workflows
+version: 2.0.0
+category: orchestration
+tags: [swarm, distributed, parallel, research, testing, development, coordination]
+author: Claude Flow Team
+---
+
+# Advanced Swarm Orchestration
+
+Master advanced swarm patterns for distributed research, development, and testing workflows. This skill covers comprehensive orchestration strategies using both MCP tools and CLI commands.
+
+## Quick Start
+
+### Prerequisites
+```bash
+# Ensure Claude Flow is installed
+npm install -g claude-flow@alpha
+
+# Add MCP server (if using MCP tools)
+claude mcp add claude-flow npx claude-flow@alpha mcp start
+```
+
+### Basic Pattern
+```javascript
+// 1. Initialize swarm topology
+mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 6 })
+
+// 2. Spawn specialized agents
+mcp__claude-flow__agent_spawn({ type: "researcher", name: "Agent 1" })
+
+// 3. Orchestrate tasks
+mcp__claude-flow__task_orchestrate({ task: "...", strategy: "parallel" })
+```
+
+## Core Concepts
+
+### Swarm Topologies
+
+**Mesh Topology** - Peer-to-peer communication, best for research and analysis
+- All agents communicate directly
+- High flexibility and resilience
+- Use for: Research, analysis, brainstorming
+
+**Hierarchical Topology** - Coordinator with subordinates, best for development
+- Clear command structure
+- Sequential workflow support
+- Use for: Development, structured workflows
+
+**Star Topology** - Central coordinator, best for testing
+- Centralized control and monitoring
+- Parallel execution with coordination
+- Use for: Testing, validation, quality assurance
+
+**Ring Topology** - Sequential processing chain
+- Step-by-step processing
+- Pipeline workflows
+- Use for: Multi-stage processing, data pipelines
+
+### Agent Strategies
+
+**Adaptive** - Dynamic adjustment based on task complexity
+**Balanced** - Equal distribution of work across agents
+**Specialized** - Task-specific agent assignment
+**Parallel** - Maximum concurrent execution
+
+## Pattern 1: Research Swarm
+
+### Purpose
+Deep research through parallel information gathering, analysis, and synthesis.
+
+### Architecture
+```javascript
+// Initialize research swarm
+mcp__claude-flow__swarm_init({
+  "topology": "mesh",
+  "maxAgents": 6,
+  "strategy": "adaptive"
+})
+
+// Spawn research team
+const researchAgents = [
+  {
+    type: "researcher",
+    name: "Web Researcher",
+    capabilities: ["web-search", "content-extraction", "source-validation"]
+  },
+  {
+    type: "researcher",
+    name: "Academic Researcher",
+    capabilities: ["paper-analysis", "citation-tracking", "literature-review"]
+  },
+  {
+    type: "analyst",
+    name: "Data Analyst",
+    capabilities: ["data-processing", "statistical-analysis", "visualization"]
+  },
+  {
+    type: "analyst",
+    name: "Pattern Analyzer",
+    capabilities: ["trend-detection", "correlation-analysis", "outlier-detection"]
+  },
+  {
+    type: "documenter",
+    name: "Report Writer",
+    capabilities: ["synthesis", "technical-writing", "formatting"]
+  }
+]
+
+// Spawn all agents
+researchAgents.forEach(agent => {
+  mcp__claude-flow__agent_spawn({
+    type: agent.type,
+    name: agent.name,
+    capabilities: agent.capabilities
+  })
+})
+```
+
+### Research Workflow
+
+#### Phase 1: Information Gathering
+```javascript
+// Parallel information collection
+mcp__claude-flow__parallel_execute({
+  "tasks": [
+    {
+      "id": "web-search",
+      "command": "search recent publications and articles"
+    },
+    {
+      "id": "academic-search",
+      "command": "search academic databases and papers"
+    },
+    {
+      "id": "data-collection",
+      "command": "gather relevant datasets and statistics"
+    },
+    {
+      "id": "expert-search",
+      "command": "identify domain experts and thought leaders"
+    }
+  ]
+})
+
+// Store research findings in memory
+mcp__claude-flow__memory_usage({
+  "action": "store",
+  "key": "research-findings-" + Date.now(),
+  "value": JSON.stringify(findings),
+  "namespace": "research",
+  "ttl": 604800 // 7 days
+})
+```
+
+#### Phase 2: Analysis and Validation
+```javascript
+// Pattern recognition in findings
+mcp__claude-flow__pattern_recognize({
+  "data": researchData,
+  "patterns": ["trend", "correlation", "outlier", "emerging-pattern"]
+})
+
+// Cognitive analysis
+mcp__claude-flow__cognitive_analyze({
+  "behavior": "research-synthesis"
+})
+
+// Quality assessment
+mcp__claude-flow__quality_assess({
+  "target": "research-sources",
+  "criteria": ["credibility", "relevance", "recency", "authority"]
+})
+
+// Cross-reference validation
+mcp__claude-flow__neural_patterns({
+  "action": "analyze",
+  "operation": "fact-checking",
+  "metadata": { "sources": sourcesArray }
+})
+```
+
+#### Phase 3: Knowledge Management
+```javascript
+// Search existing knowledge base
+mcp__claude-flow__memory_search({
+  "pattern": "topic X",
+  "namespace": "research",
+  "limit": 20
+})
+
+// Create knowledge graph connections
+mcp__claude-flow__neural_patterns({
+  "action": "learn",
+  "operation": "knowledge-graph",
+  "metadata": {
+    "topic": "X",
+    "connections": relatedTopics,
+    "depth": 3
+  }
+})
+
+// Store connections for future use
+mcp__claude-flow__memory_usage({
+  "action": "store",
+  "key": "knowledge-graph-X",
+  "value": JSON.stringify(knowledgeGraph),
+  "namespace": "research/graphs",
+  "ttl": 2592000 // 30 days
+})
+```
+
+#### Phase 4: Report Generation
+```javascript
+// Orchestrate report generation
+mcp__claude-flow__task_orchestrate({
+  "task": "generate comprehensive research report",
+  "strategy": "sequential",
+  "priority": "high",
+  "dependencies": ["gather", "analyze", "validate", "synthesize"]
+})
+
+// Monitor research progress
+mcp__claude-flow__swarm_status({
+  "swarmId": "research-swarm"
+})
+
+// Generate final report
+mcp__claude-flow__workflow_execute({
+  "workflowId": "research-report-generation",
+  "params": {
+    "findings": findings,
+    "format": "comprehensive",
+    "sections": ["executive-summary", "methodology", "findings", "analysis", "conclusions", "references"]
+  }
+})
+```
+
+### CLI Fallback
+```bash
+# Quick research swarm
+npx claude-flow swarm "research AI trends in 2025" \
+  --strategy research \
+  --mode distributed \
+  --max-agents 6 \
+  --parallel \
+  --output research-report.md
+```
+
+## Pattern 2: Development Swarm
+
+### Purpose
+Full-stack development through coordinated specialist agents.
+
+### Architecture
+```javascript
+// Initialize development swarm with hierarchy
+mcp__claude-flow__swarm_init({
+  "topology": "hierarchical",
+  "maxAgents": 8,
+  "strategy": "balanced"
+})
+
+// Spawn development team
+const devTeam = [
+  { type: "architect", name: "System Architect", role: "coordinator" },
+  { type: "coder", name: "Backend Developer", capabilities: ["node", "api", "database"] },
+  { type: "coder", name: "Frontend Developer", capabilities: ["react", "ui", "ux"] },
+  { type: "coder", name: "Database Engineer", capabilities: ["sql", "nosql", "optimization"] },
+  { type: "tester", name: "QA Engineer", capabilities: ["unit", "integration", "e2e"] },
+  { type: "reviewer", name: "Code Reviewer", capabilities: ["security", "performance", "best-practices"] },
+  { type: "documenter", name: "Technical Writer", capabilities: ["api-docs", "guides", "tutorials"] },
+  { type: "monitor", name: "DevOps Engineer", capabilities: ["ci-cd", "deployment", "monitoring"] }
+]
+
+// Spawn all team members
+devTeam.forEach(member => {
+  mcp__claude-flow__agent_spawn({
+    type: member.type,
+    name: member.name,
+    capabilities: member.capabilities,
+    swarmId: "dev-swarm"
+  })
+})
+```
+
+### Development Workflow
+
+#### Phase 1: Architecture and Design
+```javascript
+// System architecture design
+mcp__claude-flow__task_orchestrate({
+  "task": "design system architecture for REST API",
+  "strategy": "sequential",
+  "priority": "critical",
+  "assignTo": "System Architect"
+})
+
+// Store architecture decisions
+mcp__claude-flow__memory_usage({
+  "action": "store",
+  "key": "architecture-decisions",
+  "value": JSON.stringify(architectureDoc),
+  "namespace": "development/design"
+})
+```
+
+#### Phase 2: Parallel Implementation
+```javascript
+// Parallel development tasks
+mcp__claude-flow__parallel_execute({
+  "tasks": [
+    {
+      "id": "backend-api",
+      "command": "implement REST API endpoints",
+      "assignTo": "Backend Developer"
+    },
+    {
+      "id": "frontend-ui",
+      "command": "build user interface components",
+      "assignTo": "Frontend Developer"
+    },
+    {
+      "id": "database-schema",
+      "command": "design and implement database schema",
+      "assignTo": "Database Engineer"
+    },
+    {
+      "id": "api-documentation",
+      "command": "create API documentation",
+      "assignTo": "Technical Writer"
+    }
+  ]
+})
+
+// Monitor development progress
+mcp__claude-flow__swarm_monitor({
+  "swarmId": "dev-swarm",
+  "interval": 5000
+})
+```
+
+#### Phase 3: Testing and Validation
+```javascript
+// Comprehensive testing
+mcp__claude-flow__batch_process({
+  "items": [
+    { type: "unit", target: "all-modules" },
+    { type: "integration", target: "api-endpoints" },
+    { type: "e2e", target: "user-flows" },
+    { type: "performance", target: "critical-paths" }
+  ],
+  "operation": "execute-tests"
+})
+
+// Quality assessment
+mcp__claude-flow__quality_assess({
+  "target": "codebase",
+  "criteria": ["coverage", "complexity", "maintainability", "security"]
+})
+```
+
+#### Phase 4: Review and Deployment
+```javascript
+// Code review workflow
+mcp__claude-flow__workflow_execute({
+  "workflowId": "code-review-process",
+  "params": {
+    "reviewers": ["Code Reviewer"],
+    "criteria": ["security", "performance", "best-practices"]
+  }
+})
+
+// CI/CD pipeline
+mcp__claude-flow__pipeline_create({
+  "config": {
+    "stages": ["build", "test", "security-scan", "deploy"],
+    "environment": "production"
+  }
+})
+```
+
+### CLI Fallback
+```bash
+# Quick development swarm
+npx claude-flow swarm "build REST API with authentication" \
+  --strategy development \
+  --mode hierarchical \
+  --monitor \
+  --output sqlite
+```
+
+## Pattern 3: Testing Swarm
+
+### Purpose
+Comprehensive quality assurance through distributed testing.
+
+### Architecture
+```javascript
+// Initialize testing swarm with star topology
+mcp__claude-flow__swarm_init({
+  "topology": "star",
+  "maxAgents": 7,
+  "strategy": "parallel"
+})
+
+// Spawn testing team
+const testingTeam = [
+  {
+    type: "tester",
+    name: "Unit Test Coordinator",
+    capabilities: ["unit-testing", "mocking", "coverage", "tdd"]
+  },
+  {
+    type: "tester",
+    name: "Integration Tester",
+    capabilities: ["integration", "api-testing", "contract-testing"]
+  },
+  {
+    type: "tester",
+    name: "E2E Tester",
+    capabilities: ["e2e", "ui-testing", "user-flows", "selenium"]
+  },
+  {
+    type: "tester",
+    name: "Performance Tester",
+    capabilities: ["load-testing", "stress-testing", "benchmarking"]
+  },
+  {
+    type: "monitor",
+    name: "Security Tester",
+    capabilities: ["security-testing", "penetration-testing", "vulnerability-scanning"]
+  },
+  {
+    type: "analyst",
+    name: "Test Analyst",
+    capabilities: ["coverage-analysis", "test-optimization", "reporting"]
+  },
+  {
+    type: "documenter",
+    name: "Test Documenter",
+    capabilities: ["test-documentation", "test-plans", "reports"]
+  }
+]
+
+// Spawn all testers
+testingTeam.forEach(tester => {
+  mcp__claude-flow__agent_spawn({
+    type: tester.type,
+    name: tester.name,
+    capabilities: tester.capabilities,
+    swarmId: "testing-swarm"
+  })
+})
+```
+
+### Testing Workflow
+
+#### Phase 1: Test Planning
+```javascript
+// Analyze test coverage requirements
+mcp__claude-flow__quality_assess({
+  "target": "test-coverage",
+  "criteria": [
+    "line-coverage",
+    "branch-coverage",
+    "function-coverage",
+    "edge-cases"
+  ]
+})
+
+// Identify test scenarios
+mcp__claude-flow__pattern_recognize({
+  "data": testScenarios,
+  "patterns": [
+    "edge-case",
+    "boundary-condition",
+    "error-path",
+    "happy-path"
+  ]
+})
+
+// Store test plan
+mcp__claude-flow__memory_usage({
+  "action": "store",
+  "key": "test-plan-" + Date.now(),
+  "value": JSON.stringify(testPlan),
+  "namespace": "testing/plans"
+})
+```
+
+#### Phase 2: Parallel Test Execution
+```javascript
+// Execute all test suites in parallel
+mcp__claude-flow__parallel_execute({
+  "tasks": [
+    {
+      "id": "unit-tests",
+      "command": "npm run test:unit",
+      "assignTo": "Unit Test Coordinator"
+    },
+    {
+      "id": "integration-tests",
+      "command": "npm run test:integration",
+      "assignTo": "Integration Tester"
+    },
+    {
+      "id": "e2e-tests",
+      "command": "npm run test:e2e",
+      "assignTo": "E2E Tester"
+    },
+    {
+      "id": "performance-tests",
+      "command": "npm run test:performance",
+      "assignTo": "Performance Tester"
+    },
+    {
+      "id": "security-tests",
+      "command": "npm run test:security",
+      "assignTo": "Security Tester"
+    }
+  ]
+})
+
+// Batch process test suites
+mcp__claude-flow__batch_process({
+  "items": testSuites,
+  "operation": "execute-test-suite"
+})
+```
+
+#### Phase 3: Performance and Security
+```javascript
+// Run performance benchmarks
+mcp__claude-flow__benchmark_run({
+  "suite": "comprehensive-performance"
+})
+
+// Bottleneck analysis
+mcp__claude-flow__bottleneck_analyze({
+  "component": "application",
+  "metrics": ["response-time", "throughput", "memory", "cpu"]
+})
+
+// Security scanning
+mcp__claude-flow__security_scan({
+  "target": "application",
+  "depth": "comprehensive"
+})
+
+// Vulnerability analysis
+mcp__claude-flow__error_analysis({
+  "logs": securityScanLogs
+})
+```
+
+#### Phase 4: Monitoring and Reporting
+```javascript
+// Real-time test monitoring
+mcp__claude-flow__swarm_monitor({
+  "swarmId": "testing-swarm",
+  "interval": 2000
+})
+
+// Generate comprehensive test report
+mcp__claude-flow__performance_report({
+  "format": "detailed",
+  "timeframe": "current-run"
+})
+
+// Get test results
+mcp__claude-flow__task_results({
+  "taskId": "test-execution-001"
+})
+
+// Trend analysis
+mcp__claude-flow__trend_analysis({
+  "metric": "test-coverage",
+  "period": "30d"
+})
+```
+
+### CLI Fallback
+```bash
+# Quick testing swarm
+npx claude-flow swarm "test application comprehensively" \
+  --strategy testing \
+  --mode star \
+  --parallel \
+  --timeout 600
+```
+
+## Pattern 4: Analysis Swarm
+
+### Purpose
+Deep code and system analysis through specialized analyzers.
+
+### Architecture
+```javascript
+// Initialize analysis swarm
+mcp__claude-flow__swarm_init({
+  "topology": "mesh",
+  "maxAgents": 5,
+  "strategy": "adaptive"
+})
+
+// Spawn analysis specialists
+const analysisTeam = [
+  {
+    type: "analyst",
+    name: "Code Analyzer",
+    capabilities: ["static-analysis", "complexity-analysis", "dead-code-detection"]
+  },
+  {
+    type: "analyst",
+    name: "Security Analyzer",
+    capabilities: ["security-scan", "vulnerability-detection", "dependency-audit"]
+  },
+  {
+    type: "analyst",
+    name: "Performance Analyzer",
+    capabilities: ["profiling", "bottleneck-detection", "optimization"]
+  },
+  {
+    type: "analyst",
+    name: "Architecture Analyzer",
+    capabilities: ["dependency-analysis", "coupling-detection", "modularity-assessment"]
+  },
+  {
+    type: "documenter",
+    name: "Analysis Reporter",
+    capabilities: ["reporting", "visualization", "recommendations"]
+  }
+]
+
+// Spawn all analysts
+analysisTeam.forEach(analyst => {
+  mcp__claude-flow__agent_spawn({
+    type: analyst.type,
+    name: analyst.name,
+    capabilities: analyst.capabilities
+  })
+})
+```
+
+### Analysis Workflow
+```javascript
+// Parallel analysis execution
+mcp__claude-flow__parallel_execute({
+  "tasks": [
+    { "id": "analyze-code", "command": "analyze codebase structure and quality" },
+    { "id": "analyze-security", "command": "scan for security vulnerabilities" },
+    { "id": "analyze-performance", "command": "identify performance bottlenecks" },
+    { "id": "analyze-architecture", "command": "assess architectural patterns" }
+  ]
+})
+
+// Generate comprehensive analysis report
+mcp__claude-flow__performance_report({
+  "format": "detailed",
+  "timeframe": "current"
+})
+
+// Cost analysis
+mcp__claude-flow__cost_analysis({
+  "timeframe": "30d"
+})
+```
+
+## Advanced Techniques
+
+### Error Handling and Fault Tolerance
+
+```javascript
+// Setup fault tolerance for all agents
+mcp__claude-flow__daa_fault_tolerance({
+  "agentId": "all",
+  "strategy": "auto-recovery"
+})
+
+// Error handling pattern
+try {
+  await mcp__claude-flow__task_orchestrate({
+    "task": "complex operation",
+    "strategy": "parallel",
+    "priority": "high"
+  })
+} catch (error) {
+  // Check swarm health
+  const status = await mcp__claude-flow__swarm_status({})
+
+  // Analyze error patterns
+  await mcp__claude-flow__error_analysis({
+    "logs": [error.message]
+  })
+
+  // Auto-recovery attempt
+  if (status.healthy) {
+    await mcp__claude-flow__task_orchestrate({
+      "task": "retry failed operation",
+      "strategy": "sequential"
+    })
+  }
+}
+```
+
+### Memory and State Management
+
+```javascript
+// Cross-session persistence
+mcp__claude-flow__memory_persist({
+  "sessionId": "swarm-session-001"
+})
+
+// Namespace management for different swarms
+mcp__claude-flow__memory_namespace({
+  "namespace": "research-swarm",
+  "action": "create"
+})
+
+// Create state snapshot
+mcp__claude-flow__state_snapshot({
+  "name": "development-checkpoint-1"
+})
+
+// Restore from snapshot if needed
+mcp__claude-flow__context_restore({
+  "snapshotId": "development-checkpoint-1"
+})
+
+// Backup memory stores
+mcp__claude-flow__memory_backup({
+  "path": "/workspaces/claude-code-flow/backups/swarm-memory.json"
+})
+```
+
+### Neural Pattern Learning
+
+```javascript
+// Train neural patterns from successful workflows
+mcp__claude-flow__neural_train({
+  "pattern_type": "coordination",
+  "training_data": JSON.stringify(successfulWorkflows),
+  "epochs": 50
+})
+
+// Adaptive learning from experience
+mcp__claude-flow__learning_adapt({
+  "experience": {
+    "workflow": "research-to-report",
+    "success": true,
+    "duration": 3600,
+    "quality": 0.95
+  }
+})
+
+// Pattern recognition for optimization
+mcp__claude-flow__pattern_recognize({
+  "data": workflowMetrics,
+  "patterns": ["bottleneck", "optimization-opportunity", "efficiency-gain"]
+})
+```
+
+### Workflow Automation
+
+```javascript
+// Create reusable workflow
+mcp__claude-flow__workflow_create({
+  "name": "full-stack-development",
+  "steps": [
+    { "phase": "design", "agents": ["architect"] },
+    { "phase": "implement", "agents": ["backend-dev", "frontend-dev"], "parallel": true },
+    { "phase": "test", "agents": ["tester", "security-tester"], "parallel": true },
+    { "phase": "review", "agents": ["reviewer"] },
+    { "phase": "deploy", "agents": ["devops"] }
+  ],
+  "triggers": ["on-commit", "scheduled-daily"]
+})
+
+// Setup automation rules
+mcp__claude-flow__automation_setup({
+  "rules": [
+    {
+      "trigger": "file-changed",
+      "pattern": "*.js",
+      "action": "run-tests"
+    },
+    {
+      "trigger": "PR-created",
+      "action": "code-review-swarm"
+    }
+  ]
+})
+
+// Event-driven triggers
+mcp__claude-flow__trigger_setup({
+  "events": ["code-commit", "PR-merge", "deployment"],
+  "actions": ["test", "analyze", "document"]
+})
+```
+
+### Performance Optimization
+
+```javascript
+// Topology optimization
+mcp__claude-flow__topology_optimize({
+  "swarmId": "current-swarm"
+})
+
+// Load balancing
+mcp__claude-flow__load_balance({
+  "swarmId": "development-swarm",
+  "tasks": taskQueue
+})
+
+// Agent coordination sync
+mcp__claude-flow__coordination_sync({
+  "swarmId": "development-swarm"
+})
+
+// Auto-scaling
+mcp__claude-flow__swarm_scale({
+  "swarmId": "development-swarm",
+  "targetSize": 12
+})
+```
+
+### Monitoring and Metrics
+
+```javascript
+// Real-time swarm monitoring
+mcp__claude-flow__swarm_monitor({
+  "swarmId": "active-swarm",
+  "interval": 3000
+})
+
+// Collect comprehensive metrics
+mcp__claude-flow__metrics_collect({
+  "components": ["agents", "tasks", "memory", "performance"]
+})
+
+// Health monitoring
+mcp__claude-flow__health_check({
+  "components": ["swarm", "agents", "neural", "memory"]
+})
+
+// Usage statistics
+mcp__claude-flow__usage_stats({
+  "component": "swarm-orchestration"
+})
+
+// Trend analysis
+mcp__claude-flow__trend_analysis({
+  "metric": "agent-performance",
+  "period": "7d"
+})
+```
+
+## Best Practices
+
+### 1. Choosing the Right Topology
+
+- **Mesh**: Research, brainstorming, collaborative analysis
+- **Hierarchical**: Structured development, sequential workflows
+- **Star**: Testing, validation, centralized coordination
+- **Ring**: Pipeline processing, staged workflows
+
+### 2. Agent Specialization
+
+- Assign specific capabilities to each agent
+- Avoid overlapping responsibilities
+- Use coordination agents for complex workflows
+- Leverage memory for agent communication
+
+### 3. Parallel Execution
+
+- Identify independent tasks for parallelization
+- Use sequential execution for dependent tasks
+- Monitor resource usage during parallel execution
+- Implement proper error handling
+
+### 4. Memory Management
+
+- Use namespaces to organize memory
+- Set appropriate TTL values
+- Create regular backups
+- Implement state snapshots for checkpoints
+
+### 5. Monitoring and Optimization
+
+- Monitor swarm health regularly
+- Collect and analyze metrics
+- Optimize topology based on performance
+- Use neural patterns to learn from success
+
+### 6. Error Recovery
+
+- Implement fault tolerance strategies
+- Use auto-recovery mechanisms
+- Analyze error patterns
+- Create fallback workflows
+
+## Real-World Examples
+
+### Example 1: AI Research Project
+```javascript
+// Research AI trends, analyze findings, generate report
+mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 6 })
+// Spawn: 2 researchers, 2 analysts, 1 synthesizer, 1 documenter
+// Parallel gather → Analyze patterns → Synthesize → Report
+```
+
+### Example 2: Full-Stack Application
+```javascript
+// Build complete web application with testing
+mcp__claude-flow__swarm_init({ topology: "hierarchical", maxAgents: 8 })
+// Spawn: 1 architect, 2 devs, 1 db engineer, 2 testers, 1 reviewer, 1 devops
+// Design → Parallel implement → Test → Review → Deploy
+```
+
+### Example 3: Security Audit
+```javascript
+// Comprehensive security analysis
+mcp__claude-flow__swarm_init({ topology: "star", maxAgents: 5 })
+// Spawn: 1 coordinator, 1 code analyzer, 1 security scanner, 1 penetration tester, 1 reporter
+// Parallel scan → Vulnerability analysis → Penetration test → Report
+```
+
+### Example 4: Performance Optimization
+```javascript
+// Identify and fix performance bottlenecks
+mcp__claude-flow__swarm_init({ topology: "mesh", maxAgents: 4 })
+// Spawn: 1 profiler, 1 bottleneck analyzer, 1 optimizer, 1 tester
+// Profile → Identify bottlenecks → Optimize → Validate
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Swarm agents not coordinating properly
+**Solution**: Check topology selection, verify memory usage, enable monitoring
+
+**Issue**: Parallel execution failing
+**Solution**: Verify task dependencies, check resource limits, implement error handling
+
+**Issue**: Memory persistence not working
+**Solution**: Verify namespaces, check TTL settings, ensure backup configuration
+
+**Issue**: Performance degradation
+**Solution**: Optimize topology, reduce agent count, analyze bottlenecks
+
+## Related Skills
+
+- `sparc-methodology` - Systematic development workflow
+- `github-integration` - Repository management and automation
+- `neural-patterns` - AI-powered coordination optimization
+- `memory-management` - Cross-session state persistence
+
+## References
+
+- [Claude Flow Documentation](https://github.com/ruvnet/claude-flow)
+- [Swarm Orchestration Guide](https://github.com/ruvnet/claude-flow/wiki/swarm)
+- [MCP Tools Reference](https://github.com/ruvnet/claude-flow/wiki/mcp)
+- [Performance Optimization](https://github.com/ruvnet/claude-flow/wiki/performance)
+
+---
+
+**Version**: 2.0.0
+**Last Updated**: 2025-10-19
+**Skill Level**: Advanced
+**Estimated Learning Time**: 2-3 hours
@@ -0,0 +1,179 @@
+---
+name: "Swarm Orchestration"
+description: "Orchestrate multi-agent swarms with agentic-flow for parallel task execution, dynamic topology, and intelligent coordination. Use when scaling beyond single agents, implementing complex workflows, or building distributed AI systems."
+---
+
+# Swarm Orchestration
+
+## What This Skill Does
+
+Orchestrates multi-agent swarms using agentic-flow's advanced coordination system. Supports mesh, hierarchical, and adaptive topologies with automatic task distribution, load balancing, and fault tolerance.
+
+## Prerequisites
+
+- agentic-flow v1.5.11+
+- Node.js 18+
+- Understanding of distributed systems (helpful)
+
+## Quick Start
+
+```bash
+# Initialize swarm
+npx agentic-flow hooks swarm-init --topology mesh --max-agents 5
+
+# Spawn agents
+npx agentic-flow hooks agent-spawn --type coder
+npx agentic-flow hooks agent-spawn --type tester
+npx agentic-flow hooks agent-spawn --type reviewer
+
+# Orchestrate task
+npx agentic-flow hooks task-orchestrate \
+  --task "Build REST API with tests" \
+  --mode parallel
+```
+
+## Topology Patterns
+
+### 1. Mesh (Peer-to-Peer)
+```typescript
+// Equal peers, distributed decision-making
+await swarm.init({
+  topology: 'mesh',
+  agents: ['coder', 'tester', 'reviewer'],
+  communication: 'broadcast'
+});
+```
+
+### 2. Hierarchical (Queen-Worker)
+```typescript
+// Centralized coordination, specialized workers
+await swarm.init({
+  topology: 'hierarchical',
+  queen: 'architect',
+  workers: ['backend-dev', 'frontend-dev', 'db-designer']
+});
+```
+
+### 3. Adaptive (Dynamic)
+```typescript
+// Automatically switches topology based on task
+await swarm.init({
+  topology: 'adaptive',
+  optimization: 'task-complexity'
+});
+```
+
+## Task Orchestration
+
+### Parallel Execution
+```typescript
+// Execute tasks concurrently
+const results = await swarm.execute({
+  tasks: [
+    { agent: 'coder', task: 'Implement API endpoints' },
+    { agent: 'frontend', task: 'Build UI components' },
+    { agent: 'tester', task: 'Write test suite' }
+  ],
+  mode: 'parallel',
+  timeout: 300000 // 5 minutes
+});
+```
+
+### Pipeline Execution
+```typescript
+// Sequential pipeline with dependencies
+await swarm.pipeline([
+  { stage: 'design', agent: 'architect' },
+  { stage: 'implement', agent: 'coder', after: 'design' },
+  { stage: 'test', agent: 'tester', after: 'implement' },
+  { stage: 'review', agent: 'reviewer', after: 'test' }
+]);
+```
+
+### Adaptive Execution
+```typescript
+// Let swarm decide execution strategy
+await swarm.autoOrchestrate({
+  goal: 'Build production-ready API',
+  constraints: {
+    maxTime: 3600,
+    maxAgents: 8,
+    quality: 'high'
+  }
+});
+```
+
+## Memory Coordination
+
+```typescript
+// Share state across swarm
+await swarm.memory.store('api-schema', {
+  endpoints: [...],
+  models: [...]
+});
+
+// Agents read shared memory
+const schema = await swarm.memory.retrieve('api-schema');
+```
+
+## Advanced Features
+
+### Load Balancing
+```typescript
+// Automatic work distribution
+await swarm.enableLoadBalancing({
+  strategy: 'dynamic',
+  metrics: ['cpu', 'memory', 'task-queue']
+});
+```
+
+### Fault Tolerance
+```typescript
+// Handle agent failures
+await swarm.setResiliency({
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+  fallback: 'reassign-task'
+});
+```
+
+### Performance Monitoring
+```typescript
+// Track swarm metrics
+const metrics = await swarm.getMetrics();
+// { throughput, latency, success_rate, agent_utilization }
+```
+
+## Integration with Hooks
+
+```bash
+# Pre-task coordination
+npx agentic-flow hooks pre-task --description "Build API"
+
+# Post-task synchronization
+npx agentic-flow hooks post-task --task-id "task-123"
+
+# Session restore
+npx agentic-flow hooks session-restore --session-id "swarm-001"
+```
+
+## Best Practices
+
+1. **Start small**: Begin with 2-3 agents, scale up
+2. **Use memory**: Share context through swarm memory
+3. **Monitor metrics**: Track performance and bottlenecks
+4. **Enable hooks**: Automatic coordination and sync
+5. **Set timeouts**: Prevent hung tasks
+
+## Troubleshooting
+
+### Issue: Agents not coordinating
+**Solution**: Verify memory access and enable hooks
+
+### Issue: Poor performance
+**Solution**: Check topology (use adaptive) and enable load balancing
+
+## Learn More
+
+- Swarm Guide: docs/swarm/orchestration.md
+- Topology Patterns: docs/swarm/topologies.md
+- Hooks Integration: docs/hooks/coordination.md
@@ -0,0 +1,872 @@
+---
+name: "V3 CLI Modernization"
+description: "CLI modernization and hooks system enhancement for claude-flow v3. Implements interactive prompts, command decomposition, enhanced hooks integration, and intelligent workflow automation."
+---
+
+# V3 CLI Modernization
+
+## What This Skill Does
+
+Modernizes claude-flow v3 CLI with interactive prompts, intelligent command decomposition, enhanced hooks integration, performance optimization, and comprehensive workflow automation capabilities.
+
+## Quick Start
+
+```bash
+# Initialize CLI modernization analysis
+Task("CLI architecture", "Analyze current CLI structure and identify optimization opportunities", "cli-hooks-developer")
+
+# Modernization implementation (parallel)
+Task("Command decomposition", "Break down large CLI files into focused modules", "cli-hooks-developer")
+Task("Interactive prompts", "Implement intelligent interactive CLI experience", "cli-hooks-developer")
+Task("Hooks enhancement", "Deep integrate hooks with CLI lifecycle", "cli-hooks-developer")
+```
+
+## CLI Architecture Modernization
+
+### Current State Analysis
+```
+Current CLI Issues:
+├── index.ts: 108KB monolithic file
+├── enterprise.ts: 68KB feature module
+├── Limited interactivity: Basic command parsing
+├── Hooks integration: Basic pre/post execution
+└── No intelligent workflows: Manual command chaining
+
+Target Architecture:
+├── Modular Commands: <500 lines per command
+├── Interactive Prompts: Smart context-aware UX
+├── Enhanced Hooks: Deep lifecycle integration
+├── Workflow Automation: Intelligent command orchestration
+└── Performance: <200ms command response time
+```
+
+### Modular Command Architecture
+```typescript
+// src/cli/core/command-registry.ts
+interface CommandModule {
+  name: string;
+  description: string;
+  category: CommandCategory;
+  handler: CommandHandler;
+  middleware: MiddlewareStack;
+  permissions: Permission[];
+  examples: CommandExample[];
+}
+
+export class ModularCommandRegistry {
+  private commands = new Map<string, CommandModule>();
+  private categories = new Map<CommandCategory, CommandModule[]>();
+  private aliases = new Map<string, string>();
+
+  registerCommand(command: CommandModule): void {
+    this.commands.set(command.name, command);
+
+    // Register in category index
+    if (!this.categories.has(command.category)) {
+      this.categories.set(command.category, []);
+    }
+    this.categories.get(command.category)!.push(command);
+  }
+
+  async executeCommand(name: string, args: string[]): Promise<CommandResult> {
+    const command = this.resolveCommand(name);
+    if (!command) {
+      throw new CommandNotFoundError(name, this.getSuggestions(name));
+    }
+
+    // Execute middleware stack
+    const context = await this.buildExecutionContext(command, args);
+    const result = await command.middleware.execute(context);
+
+    return result;
+  }
+
+  private resolveCommand(name: string): CommandModule | undefined {
+    // Try exact match first
+    if (this.commands.has(name)) {
+      return this.commands.get(name);
+    }
+
+    // Try alias
+    const aliasTarget = this.aliases.get(name);
+    if (aliasTarget) {
+      return this.commands.get(aliasTarget);
+    }
+
+    // Try fuzzy match
+    return this.findFuzzyMatch(name);
+  }
+}
+```
+
+## Command Decomposition Strategy
+
+### Swarm Commands Module
+```typescript
+// src/cli/commands/swarm/swarm.command.ts
+@Command({
+  name: 'swarm',
+  description: 'Swarm coordination and management',
+  category: 'orchestration'
+})
+export class SwarmCommand {
+  constructor(
+    private swarmCoordinator: UnifiedSwarmCoordinator,
+    private promptService: InteractivePromptService
+  ) {}
+
+  @SubCommand('init')
+  @Option('--topology', 'Swarm topology (mesh|hierarchical|adaptive)', 'hierarchical')
+  @Option('--agents', 'Number of agents to spawn', 5)
+  @Option('--interactive', 'Interactive agent configuration', false)
+  async init(
+    @Arg('projectName') projectName: string,
+    options: SwarmInitOptions
+  ): Promise<CommandResult> {
+
+    if (options.interactive) {
+      return this.interactiveSwarmInit(projectName);
+    }
+
+    return this.quickSwarmInit(projectName, options);
+  }
+
+  private async interactiveSwarmInit(projectName: string): Promise<CommandResult> {
+    console.log(`🚀 Initializing Swarm for ${projectName}`);
+
+    // Interactive topology selection
+    const topology = await this.promptService.select({
+      message: 'Select swarm topology:',
+      choices: [
+        { name: 'Hierarchical (Queen-led coordination)', value: 'hierarchical' },
+        { name: 'Mesh (Peer-to-peer collaboration)', value: 'mesh' },
+        { name: 'Adaptive (Dynamic topology switching)', value: 'adaptive' }
+      ]
+    });
+
+    // Agent configuration
+    const agents = await this.promptAgentConfiguration();
+
+    // Initialize with configuration
+    const swarm = await this.swarmCoordinator.initialize({
+      name: projectName,
+      topology,
+      agents,
+      hooks: {
+        onAgentSpawn: this.handleAgentSpawn.bind(this),
+        onTaskComplete: this.handleTaskComplete.bind(this),
+        onSwarmComplete: this.handleSwarmComplete.bind(this)
+      }
+    });
+
+    return CommandResult.success({
+      message: `✅ Swarm ${projectName} initialized with ${agents.length} agents`,
+      data: { swarmId: swarm.id, topology, agentCount: agents.length }
+    });
+  }
+
+  @SubCommand('status')
+  async status(): Promise<CommandResult> {
+    const swarms = await this.swarmCoordinator.listActiveSwarms();
+
+    if (swarms.length === 0) {
+      return CommandResult.info('No active swarms found');
+    }
+
+    // Interactive swarm selection if multiple
+    const selectedSwarm = swarms.length === 1
+      ? swarms[0]
+      : await this.promptService.select({
+          message: 'Select swarm to inspect:',
+          choices: swarms.map(s => ({
+            name: `${s.name} (${s.agents.length} agents, ${s.topology})`,
+            value: s
+          }))
+        });
+
+    return this.displaySwarmStatus(selectedSwarm);
+  }
+}
+```
+
+### Learning Commands Module
+```typescript
+// src/cli/commands/learning/learning.command.ts
+@Command({
+  name: 'learning',
+  description: 'Learning system management and optimization',
+  category: 'intelligence'
+})
+export class LearningCommand {
+  constructor(
+    private learningService: IntegratedLearningService,
+    private promptService: InteractivePromptService
+  ) {}
+
+  @SubCommand('start')
+  @Option('--algorithm', 'RL algorithm to use', 'auto')
+  @Option('--tier', 'Learning tier (basic|standard|advanced)', 'standard')
+  async start(options: LearningStartOptions): Promise<CommandResult> {
+    // Auto-detect optimal algorithm if not specified
+    if (options.algorithm === 'auto') {
+      const taskContext = await this.analyzeCurrentContext();
+      options.algorithm = this.learningService.selectOptimalAlgorithm(taskContext);
+
+      console.log(`🧠 Auto-selected ${options.algorithm} algorithm based on context`);
+    }
+
+    const session = await this.learningService.startSession({
+      algorithm: options.algorithm,
+      tier: options.tier,
+      userId: await this.getCurrentUser()
+    });
+
+    return CommandResult.success({
+      message: `🚀 Learning session started with ${options.algorithm}`,
+      data: { sessionId: session.id, algorithm: options.algorithm, tier: options.tier }
+    });
+  }
+
+  @SubCommand('feedback')
+  @Arg('reward', 'Reward value (0-1)', 'number')
+  async feedback(
+    @Arg('reward') reward: number,
+    @Option('--context', 'Additional context for learning')
+    context?: string
+  ): Promise<CommandResult> {
+    const activeSession = await this.learningService.getActiveSession();
+    if (!activeSession) {
+      return CommandResult.error('No active learning session found. Start one with `learning start`');
+    }
+
+    await this.learningService.submitFeedback({
+      sessionId: activeSession.id,
+      reward,
+      context,
+      timestamp: new Date()
+    });
+
+    return CommandResult.success({
+      message: `📊 Feedback recorded (reward: ${reward})`,
+      data: { reward, sessionId: activeSession.id }
+    });
+  }
+
+  @SubCommand('metrics')
+  async metrics(): Promise<CommandResult> {
+    const metrics = await this.learningService.getMetrics();
+
+    // Interactive metrics display
+    await this.displayInteractiveMetrics(metrics);
+
+    return CommandResult.success('Metrics displayed');
+  }
+}
+```
+
+## Interactive Prompt System
+
+### Advanced Prompt Service
+```typescript
+// src/cli/services/interactive-prompt.service.ts
+interface PromptOptions {
+  message: string;
+  type: 'select' | 'multiselect' | 'input' | 'confirm' | 'progress';
+  choices?: PromptChoice[];
+  default?: any;
+  validate?: (input: any) => boolean | string;
+  transform?: (input: any) => any;
+}
+
+export class InteractivePromptService {
+  private inquirer: any; // Dynamic import for tree-shaking
+
+  async select<T>(options: SelectPromptOptions<T>): Promise<T> {
+    const { default: inquirer } = await import('inquirer');
+
+    const result = await inquirer.prompt([{
+      type: 'list',
+      name: 'selection',
+      message: options.message,
+      choices: options.choices,
+      default: options.default
+    }]);
+
+    return result.selection;
+  }
+
+  async multiSelect<T>(options: MultiSelectPromptOptions<T>): Promise<T[]> {
+    const { default: inquirer } = await import('inquirer');
+
+    const result = await inquirer.prompt([{
+      type: 'checkbox',
+      name: 'selections',
+      message: options.message,
+      choices: options.choices,
+      validate: (input: T[]) => {
+        if (options.minSelections && input.length < options.minSelections) {
+          return `Please select at least ${options.minSelections} options`;
+        }
+        if (options.maxSelections && input.length > options.maxSelections) {
+          return `Please select at most ${options.maxSelections} options`;
+        }
+        return true;
+      }
+    }]);
+
+    return result.selections;
+  }
+
+  async input(options: InputPromptOptions): Promise<string> {
+    const { default: inquirer } = await import('inquirer');
+
+    const result = await inquirer.prompt([{
+      type: 'input',
+      name: 'input',
+      message: options.message,
+      default: options.default,
+      validate: options.validate,
+      transformer: options.transform
+    }]);
+
+    return result.input;
+  }
+
+  async progressTask<T>(
+    task: ProgressTask<T>,
+    options: ProgressOptions
+  ): Promise<T> {
+    const { default: cliProgress } = await import('cli-progress');
+
+    const progressBar = new cliProgress.SingleBar({
+      format: `${options.title} |{bar}| {percentage}% | {status}`,
+      barCompleteChar: '█',
+      barIncompleteChar: '░',
+      hideCursor: true
+    });
+
+    progressBar.start(100, 0, { status: 'Starting...' });
+
+    try {
+      const result = await task({
+        updateProgress: (percent: number, status?: string) => {
+          progressBar.update(percent, { status: status || 'Processing...' });
+        }
+      });
+
+      progressBar.update(100, { status: 'Complete!' });
+      progressBar.stop();
+
+      return result;
+    } catch (error) {
+      progressBar.stop();
+      throw error;
+    }
+  }
+
+  async confirmWithDetails(
+    message: string,
+    details: ConfirmationDetails
+  ): Promise<boolean> {
+    console.log('\n' + chalk.bold(message));
+    console.log(chalk.gray('Details:'));
+
+    for (const [key, value] of Object.entries(details)) {
+      console.log(chalk.gray(`  ${key}: ${value}`));
+    }
+
+    return this.confirm('\nProceed?');
+  }
+}
+```
+
+## Enhanced Hooks Integration
+
+### Deep CLI Hooks Integration
+```typescript
+// src/cli/hooks/cli-hooks-manager.ts
+interface CLIHookEvent {
+  type: 'command_start' | 'command_end' | 'command_error' | 'agent_spawn' | 'task_complete';
+  command: string;
+  args: string[];
+  context: ExecutionContext;
+  timestamp: Date;
+}
+
+export class CLIHooksManager {
+  private hooks: Map<string, HookHandler[]> = new Map();
+  private learningIntegration: LearningHooksIntegration;
+
+  constructor() {
+    this.learningIntegration = new LearningHooksIntegration();
+    this.setupDefaultHooks();
+  }
+
+  private setupDefaultHooks(): void {
+    // Learning integration hooks
+    this.registerHook('command_start', async (event: CLIHookEvent) => {
+      await this.learningIntegration.recordCommandStart(event);
+    });
+
+    this.registerHook('command_end', async (event: CLIHookEvent) => {
+      await this.learningIntegration.recordCommandSuccess(event);
+    });
+
+    this.registerHook('command_error', async (event: CLIHookEvent) => {
+      await this.learningIntegration.recordCommandError(event);
+    });
+
+    // Intelligent suggestions
+    this.registerHook('command_start', async (event: CLIHookEvent) => {
+      const suggestions = await this.generateIntelligentSuggestions(event);
+      if (suggestions.length > 0) {
+        this.displaySuggestions(suggestions);
+      }
+    });
+
+    // Performance monitoring
+    this.registerHook('command_end', async (event: CLIHookEvent) => {
+      await this.recordPerformanceMetrics(event);
+    });
+  }
+
+  async executeHooks(type: string, event: CLIHookEvent): Promise<void> {
+    const handlers = this.hooks.get(type) || [];
+
+    await Promise.all(handlers.map(handler =>
+      this.executeHookSafely(handler, event)
+    ));
+  }
+
+  private async generateIntelligentSuggestions(event: CLIHookEvent): Promise<Suggestion[]> {
+    const context = await this.learningIntegration.getExecutionContext(event);
+    const patterns = await this.learningIntegration.findSimilarPatterns(context);
+
+    return patterns.map(pattern => ({
+      type: 'optimization',
+      message: `Based on similar executions, consider: ${pattern.suggestion}`,
+      confidence: pattern.confidence
+    }));
+  }
+}
+```
+
+### Learning Integration
+```typescript
+// src/cli/hooks/learning-hooks-integration.ts
+export class LearningHooksIntegration {
+  constructor(
+    private agenticFlowHooks: AgenticFlowHooksClient,
+    private agentDBLearning: AgentDBLearningClient
+  ) {}
+
+  async recordCommandStart(event: CLIHookEvent): Promise<void> {
+    // Start trajectory tracking
+    await this.agenticFlowHooks.trajectoryStart({
+      sessionId: event.context.sessionId,
+      command: event.command,
+      args: event.args,
+      context: event.context
+    });
+
+    // Record experience in AgentDB
+    await this.agentDBLearning.recordExperience({
+      type: 'command_execution',
+      state: this.encodeCommandState(event),
+      action: event.command,
+      timestamp: event.timestamp
+    });
+  }
+
+  async recordCommandSuccess(event: CLIHookEvent): Promise<void> {
+    const executionTime = Date.now() - event.timestamp.getTime();
+    const reward = this.calculateReward(event, executionTime, true);
+
+    // Complete trajectory
+    await this.agenticFlowHooks.trajectoryEnd({
+      sessionId: event.context.sessionId,
+      success: true,
+      reward,
+      verdict: 'positive'
+    });
+
+    // Submit feedback to learning system
+    await this.agentDBLearning.submitFeedback({
+      sessionId: event.context.learningSessionId,
+      reward,
+      success: true,
+      latencyMs: executionTime
+    });
+
+    // Store successful pattern
+    if (reward > 0.8) {
+      await this.agenticFlowHooks.storePattern({
+        pattern: event.command,
+        solution: event.context.result,
+        confidence: reward
+      });
+    }
+  }
+
+  async recordCommandError(event: CLIHookEvent): Promise<void> {
+    const executionTime = Date.now() - event.timestamp.getTime();
+    const reward = this.calculateReward(event, executionTime, false);
+
+    // Complete trajectory with error
+    await this.agenticFlowHooks.trajectoryEnd({
+      sessionId: event.context.sessionId,
+      success: false,
+      reward,
+      verdict: 'negative',
+      error: event.context.error
+    });
+
+    // Learn from failure
+    await this.agentDBLearning.submitFeedback({
+      sessionId: event.context.learningSessionId,
+      reward,
+      success: false,
+      latencyMs: executionTime,
+      error: event.context.error
+    });
+  }
+
+  private calculateReward(event: CLIHookEvent, executionTime: number, success: boolean): number {
+    if (!success) return 0;
+
+    // Base reward for success
+    let reward = 0.5;
+
+    // Performance bonus (faster execution)
+    const expectedTime = this.getExpectedExecutionTime(event.command);
+    if (executionTime < expectedTime) {
+      reward += 0.3 * (1 - executionTime / expectedTime);
+    }
+
+    // Complexity bonus
+    const complexity = this.calculateCommandComplexity(event);
+    reward += complexity * 0.2;
+
+    return Math.min(reward, 1.0);
+  }
+}
+```
+
+## Intelligent Workflow Automation
+
+### Workflow Orchestrator
+```typescript
+// src/cli/workflows/workflow-orchestrator.ts
+interface WorkflowStep {
+  id: string;
+  command: string;
+  args: string[];
+  dependsOn: string[];
+  condition?: WorkflowCondition;
+  retryPolicy?: RetryPolicy;
+}
+
+export class WorkflowOrchestrator {
+  constructor(
+    private commandRegistry: ModularCommandRegistry,
+    private promptService: InteractivePromptService
+  ) {}
+
+  async executeWorkflow(workflow: Workflow): Promise<WorkflowResult> {
+    const context = new WorkflowExecutionContext(workflow);
+
+    // Display workflow overview
+    await this.displayWorkflowOverview(workflow);
+
+    const confirmed = await this.promptService.confirm(
+      'Execute this workflow?'
+    );
+
+    if (!confirmed) {
+      return WorkflowResult.cancelled();
+    }
+
+    // Execute steps
+    return this.promptService.progressTask(
+      async ({ updateProgress }) => {
+        const steps = this.sortStepsByDependencies(workflow.steps);
+
+        for (let i = 0; i < steps.length; i++) {
+          const step = steps[i];
+          updateProgress((i / steps.length) * 100, `Executing ${step.command}`);
+
+          await this.executeStep(step, context);
+        }
+
+        return WorkflowResult.success(context.getResults());
+      },
+      { title: `Workflow: ${workflow.name}` }
+    );
+  }
+
+  async generateWorkflowFromIntent(intent: string): Promise<Workflow> {
+    // Use learning system to generate workflow
+    const patterns = await this.findWorkflowPatterns(intent);
+
+    if (patterns.length === 0) {
+      throw new Error('Could not generate workflow for intent');
+    }
+
+    // Select best pattern or let user choose
+    const selectedPattern = patterns.length === 1
+      ? patterns[0]
+      : await this.promptService.select({
+          message: 'Select workflow template:',
+          choices: patterns.map(p => ({
+            name: `${p.name} (${p.confidence}% match)`,
+            value: p
+          }))
+        });
+
+    return this.customizeWorkflow(selectedPattern, intent);
+  }
+
+  private async executeStep(step: WorkflowStep, context: WorkflowExecutionContext): Promise<void> {
+    // Check conditions
+    if (step.condition && !this.evaluateCondition(step.condition, context)) {
+      context.skipStep(step.id, 'Condition not met');
+      return;
+    }
+
+    // Check dependencies
+    const missingDeps = step.dependsOn.filter(dep => !context.isStepCompleted(dep));
+    if (missingDeps.length > 0) {
+      throw new WorkflowError(`Step ${step.id} has unmet dependencies: ${missingDeps.join(', ')}`);
+    }
+
+    // Execute with retry policy
+    const retryPolicy = step.retryPolicy || { maxAttempts: 1 };
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt++) {
+      try {
+        const result = await this.commandRegistry.executeCommand(step.command, step.args);
+        context.completeStep(step.id, result);
+        return;
+      } catch (error) {
+        lastError = error as Error;
+
+        if (attempt < retryPolicy.maxAttempts) {
+          await this.delay(retryPolicy.backoffMs || 1000);
+        }
+      }
+    }
+
+    throw new WorkflowError(`Step ${step.id} failed after ${retryPolicy.maxAttempts} attempts: ${lastError?.message}`);
+  }
+}
+```
+
+## Performance Optimization
+
+### Command Performance Monitoring
+```typescript
+// src/cli/performance/command-performance.ts
+export class CommandPerformanceMonitor {
+  private metrics = new Map<string, CommandMetrics>();
+
+  async measureCommand<T>(
+    commandName: string,
+    executor: () => Promise<T>
+  ): Promise<T> {
+    const start = performance.now();
+    const memBefore = process.memoryUsage();
+
+    try {
+      const result = await executor();
+      const end = performance.now();
+      const memAfter = process.memoryUsage();
+
+      this.recordMetrics(commandName, {
+        executionTime: end - start,
+        memoryDelta: memAfter.heapUsed - memBefore.heapUsed,
+        success: true
+      });
+
+      return result;
+    } catch (error) {
+      const end = performance.now();
+
+      this.recordMetrics(commandName, {
+        executionTime: end - start,
+        memoryDelta: 0,
+        success: false,
+        error: error as Error
+      });
+
+      throw error;
+    }
+  }
+
+  private recordMetrics(command: string, measurement: PerformanceMeasurement): void {
+    if (!this.metrics.has(command)) {
+      this.metrics.set(command, new CommandMetrics(command));
+    }
+
+    const metrics = this.metrics.get(command)!;
+    metrics.addMeasurement(measurement);
+
+    // Alert if performance degrades
+    if (metrics.getP95ExecutionTime() > 5000) { // 5 seconds
+      console.warn(`⚠️  Command '${command}' is performing slowly (P95: ${metrics.getP95ExecutionTime()}ms)`);
+    }
+  }
+
+  getCommandReport(command: string): PerformanceReport {
+    const metrics = this.metrics.get(command);
+    if (!metrics) {
+      throw new Error(`No metrics found for command: ${command}`);
+    }
+
+    return {
+      command,
+      totalExecutions: metrics.getTotalExecutions(),
+      successRate: metrics.getSuccessRate(),
+      avgExecutionTime: metrics.getAverageExecutionTime(),
+      p95ExecutionTime: metrics.getP95ExecutionTime(),
+      avgMemoryUsage: metrics.getAverageMemoryUsage(),
+      recommendations: this.generateRecommendations(metrics)
+    };
+  }
+}
+```
+
+## Smart Auto-completion
+
+### Intelligent Command Completion
+```typescript
+// src/cli/completion/intelligent-completion.ts
+export class IntelligentCompletion {
+  constructor(
+    private learningService: LearningService,
+    private commandRegistry: ModularCommandRegistry
+  ) {}
+
+  async generateCompletions(
+    partial: string,
+    context: CompletionContext
+  ): Promise<Completion[]> {
+    const completions: Completion[] = [];
+
+    // 1. Exact command matches
+    const exactMatches = this.commandRegistry.findCommandsByPrefix(partial);
+    completions.push(...exactMatches.map(cmd => ({
+      value: cmd.name,
+      description: cmd.description,
+      type: 'command',
+      confidence: 1.0
+    })));
+
+    // 2. Learning-based suggestions
+    const learnedSuggestions = await this.learningService.suggestCommands(
+      partial,
+      context
+    );
+    completions.push(...learnedSuggestions);
+
+    // 3. Context-aware suggestions
+    const contextualSuggestions = await this.generateContextualSuggestions(
+      partial,
+      context
+    );
+    completions.push(...contextualSuggestions);
+
+    // Sort by confidence and relevance
+    return completions
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, 10); // Top 10 suggestions
+  }
+
+  private async generateContextualSuggestions(
+    partial: string,
+    context: CompletionContext
+  ): Promise<Completion[]> {
+    const suggestions: Completion[] = [];
+
+    // If in git repository, suggest git-related commands
+    if (context.isGitRepository) {
+      if (partial.startsWith('git')) {
+        suggestions.push({
+          value: 'git commit',
+          description: 'Create git commit with generated message',
+          type: 'workflow',
+          confidence: 0.8
+        });
+      }
+    }
+
+    // If package.json exists, suggest npm commands
+    if (context.hasPackageJson) {
+      if (partial.startsWith('npm') || partial.startsWith('swarm')) {
+        suggestions.push({
+          value: 'swarm init',
+          description: 'Initialize swarm for this project',
+          type: 'workflow',
+          confidence: 0.9
+        });
+      }
+    }
+
+    return suggestions;
+  }
+}
+```
+
+## Success Metrics
+
+### CLI Performance Targets
+- [ ] **Command Response**: <200ms average command execution time
+- [ ] **File Decomposition**: index.ts (108KB) → <10KB per command module
+- [ ] **Interactive UX**: Smart prompts with context awareness
+- [ ] **Hook Integration**: Deep lifecycle integration with learning
+- [ ] **Workflow Automation**: Intelligent multi-step command orchestration
+- [ ] **Auto-completion**: >90% accuracy for command suggestions
+
+### User Experience Improvements
+```typescript
+const cliImprovements = {
+  before: {
+    commandResponse: '~500ms',
+    interactivity: 'Basic command parsing',
+    workflows: 'Manual command chaining',
+    suggestions: 'Static help text'
+  },
+
+  after: {
+    commandResponse: '<200ms with caching',
+    interactivity: 'Smart context-aware prompts',
+    workflows: 'Automated multi-step execution',
+    suggestions: 'Learning-based intelligent completion'
+  }
+};
+```
+
+## Related V3 Skills
+
+- `v3-core-implementation` - Core domain integration
+- `v3-memory-unification` - Memory-backed command caching
+- `v3-swarm-coordination` - CLI swarm management integration
+- `v3-performance-optimization` - CLI performance monitoring
+
+## Usage Examples
+
+### Complete CLI Modernization
+```bash
+# Full CLI modernization implementation
+Task("CLI modernization implementation",
+     "Implement modular commands, interactive prompts, and intelligent workflows",
+     "cli-hooks-developer")
+```
+
+### Interactive Command Enhancement
+```bash
+# Enhanced interactive commands
+claude-flow swarm init --interactive
+claude-flow learning start --guided
+claude-flow workflow create --from-intent "setup new project"
+```
@@ -0,0 +1,797 @@
+---
+name: "V3 Core Implementation"
+description: "Core module implementation for claude-flow v3. Implements DDD domains, clean architecture patterns, dependency injection, and modular TypeScript codebase with comprehensive testing."
+---
+
+# V3 Core Implementation
+
+## What This Skill Does
+
+Implements the core TypeScript modules for claude-flow v3 following Domain-Driven Design principles, clean architecture patterns, and modern TypeScript best practices with comprehensive test coverage.
+
+## Quick Start
+
+```bash
+# Initialize core implementation
+Task("Core foundation", "Set up DDD domain structure and base classes", "core-implementer")
+
+# Domain implementation (parallel)
+Task("Task domain", "Implement task management domain with entities and services", "core-implementer")
+Task("Session domain", "Implement session management domain", "core-implementer")
+Task("Health domain", "Implement health monitoring domain", "core-implementer")
+```
+
+## Core Implementation Architecture
+
+### Domain Structure
+```
+src/
+├── core/
+│   ├── kernel/                     # Microkernel pattern
+│   │   ├── claude-flow-kernel.ts
+│   │   ├── domain-registry.ts
+│   │   └── plugin-loader.ts
+│   │
+│   ├── domains/                    # DDD Bounded Contexts
+│   │   ├── task-management/
+│   │   │   ├── entities/
+│   │   │   ├── value-objects/
+│   │   │   ├── services/
+│   │   │   ├── repositories/
+│   │   │   └── events/
+│   │   │
+│   │   ├── session-management/
+│   │   ├── health-monitoring/
+│   │   ├── lifecycle-management/
+│   │   └── event-coordination/
+│   │
+│   ├── shared/                     # Shared kernel
+│   │   ├── domain/
+│   │   │   ├── entity.ts
+│   │   │   ├── value-object.ts
+│   │   │   ├── domain-event.ts
+│   │   │   └── aggregate-root.ts
+│   │   │
+│   │   ├── infrastructure/
+│   │   │   ├── event-bus.ts
+│   │   │   ├── dependency-container.ts
+│   │   │   └── logger.ts
+│   │   │
+│   │   └── types/
+│   │       ├── common.ts
+│   │       ├── errors.ts
+│   │       └── interfaces.ts
+│   │
+│   └── application/                # Application services
+│       ├── use-cases/
+│       ├── commands/
+│       ├── queries/
+│       └── handlers/
+```
+
+## Base Domain Classes
+
+### Entity Base Class
+```typescript
+// src/core/shared/domain/entity.ts
+export abstract class Entity<T> {
+  protected readonly _id: T;
+  private _domainEvents: DomainEvent[] = [];
+
+  constructor(id: T) {
+    this._id = id;
+  }
+
+  get id(): T {
+    return this._id;
+  }
+
+  public equals(object?: Entity<T>): boolean {
+    if (object == null || object == undefined) {
+      return false;
+    }
+
+    if (this === object) {
+      return true;
+    }
+
+    if (!(object instanceof Entity)) {
+      return false;
+    }
+
+    return this._id === object._id;
+  }
+
+  protected addDomainEvent(domainEvent: DomainEvent): void {
+    this._domainEvents.push(domainEvent);
+  }
+
+  public getUncommittedEvents(): DomainEvent[] {
+    return this._domainEvents;
+  }
+
+  public markEventsAsCommitted(): void {
+    this._domainEvents = [];
+  }
+}
+```
+
+### Value Object Base Class
+```typescript
+// src/core/shared/domain/value-object.ts
+export abstract class ValueObject<T> {
+  protected readonly props: T;
+
+  constructor(props: T) {
+    this.props = Object.freeze(props);
+  }
+
+  public equals(object?: ValueObject<T>): boolean {
+    if (object == null || object == undefined) {
+      return false;
+    }
+
+    if (this === object) {
+      return true;
+    }
+
+    return JSON.stringify(this.props) === JSON.stringify(object.props);
+  }
+
+  get value(): T {
+    return this.props;
+  }
+}
+```
+
+### Aggregate Root
+```typescript
+// src/core/shared/domain/aggregate-root.ts
+export abstract class AggregateRoot<T> extends Entity<T> {
+  private _version: number = 0;
+
+  get version(): number {
+    return this._version;
+  }
+
+  protected incrementVersion(): void {
+    this._version++;
+  }
+
+  public applyEvent(event: DomainEvent): void {
+    this.addDomainEvent(event);
+    this.incrementVersion();
+  }
+}
+```
+
+## Task Management Domain Implementation
+
+### Task Entity
+```typescript
+// src/core/domains/task-management/entities/task.entity.ts
+import { AggregateRoot } from '../../../shared/domain/aggregate-root';
+import { TaskId } from '../value-objects/task-id.vo';
+import { TaskStatus } from '../value-objects/task-status.vo';
+import { Priority } from '../value-objects/priority.vo';
+import { TaskAssignedEvent } from '../events/task-assigned.event';
+
+interface TaskProps {
+  id: TaskId;
+  description: string;
+  priority: Priority;
+  status: TaskStatus;
+  assignedAgentId?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export class Task extends AggregateRoot<TaskId> {
+  private props: TaskProps;
+
+  private constructor(props: TaskProps) {
+    super(props.id);
+    this.props = props;
+  }
+
+  static create(description: string, priority: Priority): Task {
+    const task = new Task({
+      id: TaskId.create(),
+      description,
+      priority,
+      status: TaskStatus.pending(),
+      createdAt: new Date(),
+      updatedAt: new Date()
+    });
+
+    return task;
+  }
+
+  static reconstitute(props: TaskProps): Task {
+    return new Task(props);
+  }
+
+  public assignTo(agentId: string): void {
+    if (this.props.status.equals(TaskStatus.completed())) {
+      throw new Error('Cannot assign completed task');
+    }
+
+    this.props.assignedAgentId = agentId;
+    this.props.status = TaskStatus.assigned();
+    this.props.updatedAt = new Date();
+
+    this.applyEvent(new TaskAssignedEvent(
+      this.id.value,
+      agentId,
+      this.props.priority
+    ));
+  }
+
+  public complete(result: TaskResult): void {
+    if (!this.props.assignedAgentId) {
+      throw new Error('Cannot complete unassigned task');
+    }
+
+    this.props.status = TaskStatus.completed();
+    this.props.updatedAt = new Date();
+
+    this.applyEvent(new TaskCompletedEvent(
+      this.id.value,
+      result,
+      this.calculateDuration()
+    ));
+  }
+
+  // Getters
+  get description(): string { return this.props.description; }
+  get priority(): Priority { return this.props.priority; }
+  get status(): TaskStatus { return this.props.status; }
+  get assignedAgentId(): string | undefined { return this.props.assignedAgentId; }
+  get createdAt(): Date { return this.props.createdAt; }
+  get updatedAt(): Date { return this.props.updatedAt; }
+
+  private calculateDuration(): number {
+    return this.props.updatedAt.getTime() - this.props.createdAt.getTime();
+  }
+}
+```
+
+### Task Value Objects
+```typescript
+// src/core/domains/task-management/value-objects/task-id.vo.ts
+export class TaskId extends ValueObject<string> {
+  private constructor(value: string) {
+    super({ value });
+  }
+
+  static create(): TaskId {
+    return new TaskId(crypto.randomUUID());
+  }
+
+  static fromString(id: string): TaskId {
+    if (!id || id.length === 0) {
+      throw new Error('TaskId cannot be empty');
+    }
+    return new TaskId(id);
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}
+
+// src/core/domains/task-management/value-objects/task-status.vo.ts
+type TaskStatusType = 'pending' | 'assigned' | 'in_progress' | 'completed' | 'failed';
+
+export class TaskStatus extends ValueObject<TaskStatusType> {
+  private constructor(status: TaskStatusType) {
+    super({ value: status });
+  }
+
+  static pending(): TaskStatus { return new TaskStatus('pending'); }
+  static assigned(): TaskStatus { return new TaskStatus('assigned'); }
+  static inProgress(): TaskStatus { return new TaskStatus('in_progress'); }
+  static completed(): TaskStatus { return new TaskStatus('completed'); }
+  static failed(): TaskStatus { return new TaskStatus('failed'); }
+
+  get value(): TaskStatusType {
+    return this.props.value;
+  }
+
+  public isPending(): boolean { return this.value === 'pending'; }
+  public isAssigned(): boolean { return this.value === 'assigned'; }
+  public isInProgress(): boolean { return this.value === 'in_progress'; }
+  public isCompleted(): boolean { return this.value === 'completed'; }
+  public isFailed(): boolean { return this.value === 'failed'; }
+}
+
+// src/core/domains/task-management/value-objects/priority.vo.ts
+type PriorityLevel = 'low' | 'medium' | 'high' | 'critical';
+
+export class Priority extends ValueObject<PriorityLevel> {
+  private constructor(level: PriorityLevel) {
+    super({ value: level });
+  }
+
+  static low(): Priority { return new Priority('low'); }
+  static medium(): Priority { return new Priority('medium'); }
+  static high(): Priority { return new Priority('high'); }
+  static critical(): Priority { return new Priority('critical'); }
+
+  get value(): PriorityLevel {
+    return this.props.value;
+  }
+
+  public getNumericValue(): number {
+    const priorities = { low: 1, medium: 2, high: 3, critical: 4 };
+    return priorities[this.value];
+  }
+}
+```
+
+## Domain Services
+
+### Task Scheduling Service
+```typescript
+// src/core/domains/task-management/services/task-scheduling.service.ts
+import { Injectable } from '../../../shared/infrastructure/dependency-container';
+import { Task } from '../entities/task.entity';
+import { Priority } from '../value-objects/priority.vo';
+
+@Injectable()
+export class TaskSchedulingService {
+  public prioritizeTasks(tasks: Task[]): Task[] {
+    return tasks.sort((a, b) =>
+      b.priority.getNumericValue() - a.priority.getNumericValue()
+    );
+  }
+
+  public canSchedule(task: Task, agentCapacity: number): boolean {
+    if (agentCapacity <= 0) return false;
+
+    // Critical tasks always schedulable
+    if (task.priority.equals(Priority.critical())) return true;
+
+    // Other logic based on capacity
+    return true;
+  }
+
+  public calculateEstimatedDuration(task: Task): number {
+    // Simple heuristic - would use ML in real implementation
+    const baseTime = 300000; // 5 minutes
+    const priorityMultiplier = {
+      low: 0.5,
+      medium: 1.0,
+      high: 1.5,
+      critical: 2.0
+    };
+
+    return baseTime * priorityMultiplier[task.priority.value];
+  }
+}
+```
+
+## Repository Interfaces & Implementations
+
+### Task Repository Interface
+```typescript
+// src/core/domains/task-management/repositories/task.repository.ts
+export interface ITaskRepository {
+  save(task: Task): Promise<void>;
+  findById(id: TaskId): Promise<Task | null>;
+  findByAgentId(agentId: string): Promise<Task[]>;
+  findByStatus(status: TaskStatus): Promise<Task[]>;
+  findPendingTasks(): Promise<Task[]>;
+  delete(id: TaskId): Promise<void>;
+}
+```
+
+### SQLite Implementation
+```typescript
+// src/core/domains/task-management/repositories/sqlite-task.repository.ts
+@Injectable()
+export class SqliteTaskRepository implements ITaskRepository {
+  constructor(
+    @Inject('Database') private db: Database,
+    @Inject('Logger') private logger: ILogger
+  ) {}
+
+  async save(task: Task): Promise<void> {
+    const sql = `
+      INSERT OR REPLACE INTO tasks (
+        id, description, priority, status, assigned_agent_id, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `;
+
+    await this.db.run(sql, [
+      task.id.value,
+      task.description,
+      task.priority.value,
+      task.status.value,
+      task.assignedAgentId,
+      task.createdAt.toISOString(),
+      task.updatedAt.toISOString()
+    ]);
+
+    this.logger.debug(`Task saved: ${task.id.value}`);
+  }
+
+  async findById(id: TaskId): Promise<Task | null> {
+    const sql = 'SELECT * FROM tasks WHERE id = ?';
+    const row = await this.db.get(sql, [id.value]);
+
+    return row ? this.mapRowToTask(row) : null;
+  }
+
+  async findPendingTasks(): Promise<Task[]> {
+    const sql = 'SELECT * FROM tasks WHERE status = ? ORDER BY priority DESC, created_at ASC';
+    const rows = await this.db.all(sql, ['pending']);
+
+    return rows.map(row => this.mapRowToTask(row));
+  }
+
+  private mapRowToTask(row: any): Task {
+    return Task.reconstitute({
+      id: TaskId.fromString(row.id),
+      description: row.description,
+      priority: Priority.fromString(row.priority),
+      status: TaskStatus.fromString(row.status),
+      assignedAgentId: row.assigned_agent_id,
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at)
+    });
+  }
+}
+```
+
+## Application Layer
+
+### Use Case Implementation
+```typescript
+// src/core/application/use-cases/assign-task.use-case.ts
+@Injectable()
+export class AssignTaskUseCase {
+  constructor(
+    @Inject('TaskRepository') private taskRepository: ITaskRepository,
+    @Inject('AgentRepository') private agentRepository: IAgentRepository,
+    @Inject('DomainEventBus') private eventBus: DomainEventBus,
+    @Inject('Logger') private logger: ILogger
+  ) {}
+
+  async execute(command: AssignTaskCommand): Promise<AssignTaskResult> {
+    try {
+      // 1. Validate command
+      await this.validateCommand(command);
+
+      // 2. Load aggregates
+      const task = await this.taskRepository.findById(command.taskId);
+      if (!task) {
+        throw new TaskNotFoundError(command.taskId);
+      }
+
+      const agent = await this.agentRepository.findById(command.agentId);
+      if (!agent) {
+        throw new AgentNotFoundError(command.agentId);
+      }
+
+      // 3. Business logic
+      if (!agent.canAcceptTask(task)) {
+        throw new AgentCannotAcceptTaskError(command.agentId, command.taskId);
+      }
+
+      task.assignTo(command.agentId);
+      agent.acceptTask(task.id);
+
+      // 4. Persist changes
+      await Promise.all([
+        this.taskRepository.save(task),
+        this.agentRepository.save(agent)
+      ]);
+
+      // 5. Publish domain events
+      const events = [
+        ...task.getUncommittedEvents(),
+        ...agent.getUncommittedEvents()
+      ];
+
+      for (const event of events) {
+        await this.eventBus.publish(event);
+      }
+
+      task.markEventsAsCommitted();
+      agent.markEventsAsCommitted();
+
+      // 6. Return result
+      this.logger.info(`Task ${command.taskId.value} assigned to agent ${command.agentId}`);
+
+      return AssignTaskResult.success({
+        taskId: task.id,
+        agentId: command.agentId,
+        assignedAt: new Date()
+      });
+
+    } catch (error) {
+      this.logger.error(`Failed to assign task ${command.taskId.value}:`, error);
+      return AssignTaskResult.failure(error);
+    }
+  }
+
+  private async validateCommand(command: AssignTaskCommand): Promise<void> {
+    if (!command.taskId) {
+      throw new ValidationError('Task ID is required');
+    }
+    if (!command.agentId) {
+      throw new ValidationError('Agent ID is required');
+    }
+  }
+}
+```
+
+## Dependency Injection Setup
+
+### Container Configuration
+```typescript
+// src/core/shared/infrastructure/dependency-container.ts
+import { Container } from 'inversify';
+import { TYPES } from './types';
+
+export class DependencyContainer {
+  private container: Container;
+
+  constructor() {
+    this.container = new Container();
+    this.setupBindings();
+  }
+
+  private setupBindings(): void {
+    // Repositories
+    this.container.bind<ITaskRepository>(TYPES.TaskRepository)
+      .to(SqliteTaskRepository)
+      .inSingletonScope();
+
+    this.container.bind<IAgentRepository>(TYPES.AgentRepository)
+      .to(SqliteAgentRepository)
+      .inSingletonScope();
+
+    // Services
+    this.container.bind<TaskSchedulingService>(TYPES.TaskSchedulingService)
+      .to(TaskSchedulingService)
+      .inSingletonScope();
+
+    // Use Cases
+    this.container.bind<AssignTaskUseCase>(TYPES.AssignTaskUseCase)
+      .to(AssignTaskUseCase)
+      .inSingletonScope();
+
+    // Infrastructure
+    this.container.bind<ILogger>(TYPES.Logger)
+      .to(ConsoleLogger)
+      .inSingletonScope();
+
+    this.container.bind<DomainEventBus>(TYPES.DomainEventBus)
+      .to(InMemoryDomainEventBus)
+      .inSingletonScope();
+  }
+
+  get<T>(serviceIdentifier: symbol): T {
+    return this.container.get<T>(serviceIdentifier);
+  }
+
+  bind<T>(serviceIdentifier: symbol): BindingToSyntax<T> {
+    return this.container.bind<T>(serviceIdentifier);
+  }
+}
+```
+
+## Modern TypeScript Configuration
+
+### Strict TypeScript Setup
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@core/*": ["src/core/*"],
+      "@shared/*": ["src/core/shared/*"],
+      "@domains/*": ["src/core/domains/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+## Testing Implementation
+
+### Domain Unit Tests
+```typescript
+// src/core/domains/task-management/__tests__/entities/task.entity.test.ts
+describe('Task Entity', () => {
+  let task: Task;
+
+  beforeEach(() => {
+    task = Task.create('Test task', Priority.medium());
+  });
+
+  describe('creation', () => {
+    it('should create task with pending status', () => {
+      expect(task.status.isPending()).toBe(true);
+      expect(task.description).toBe('Test task');
+      expect(task.priority.equals(Priority.medium())).toBe(true);
+    });
+
+    it('should generate unique ID', () => {
+      const task1 = Task.create('Task 1', Priority.low());
+      const task2 = Task.create('Task 2', Priority.low());
+
+      expect(task1.id.equals(task2.id)).toBe(false);
+    });
+  });
+
+  describe('assignment', () => {
+    it('should assign to agent and change status', () => {
+      const agentId = 'agent-123';
+
+      task.assignTo(agentId);
+
+      expect(task.assignedAgentId).toBe(agentId);
+      expect(task.status.isAssigned()).toBe(true);
+    });
+
+    it('should emit TaskAssignedEvent when assigned', () => {
+      const agentId = 'agent-123';
+
+      task.assignTo(agentId);
+
+      const events = task.getUncommittedEvents();
+      expect(events).toHaveLength(1);
+      expect(events[0]).toBeInstanceOf(TaskAssignedEvent);
+    });
+
+    it('should not allow assignment of completed task', () => {
+      task.assignTo('agent-123');
+      task.complete(TaskResult.success('done'));
+
+      expect(() => task.assignTo('agent-456'))
+        .toThrow('Cannot assign completed task');
+    });
+  });
+});
+```
+
+### Integration Tests
+```typescript
+// src/core/domains/task-management/__tests__/integration/task-repository.integration.test.ts
+describe('TaskRepository Integration', () => {
+  let repository: SqliteTaskRepository;
+  let db: Database;
+
+  beforeEach(async () => {
+    db = new Database(':memory:');
+    await setupTasksTable(db);
+    repository = new SqliteTaskRepository(db, new ConsoleLogger());
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  it('should save and retrieve task', async () => {
+    const task = Task.create('Test task', Priority.high());
+
+    await repository.save(task);
+    const retrieved = await repository.findById(task.id);
+
+    expect(retrieved).toBeDefined();
+    expect(retrieved!.id.equals(task.id)).toBe(true);
+    expect(retrieved!.description).toBe('Test task');
+    expect(retrieved!.priority.equals(Priority.high())).toBe(true);
+  });
+
+  it('should find pending tasks ordered by priority', async () => {
+    const lowTask = Task.create('Low priority', Priority.low());
+    const highTask = Task.create('High priority', Priority.high());
+
+    await repository.save(lowTask);
+    await repository.save(highTask);
+
+    const pending = await repository.findPendingTasks();
+
+    expect(pending).toHaveLength(2);
+    expect(pending[0].id.equals(highTask.id)).toBe(true); // High priority first
+    expect(pending[1].id.equals(lowTask.id)).toBe(true);
+  });
+});
+```
+
+## Performance Optimizations
+
+### Entity Caching
+```typescript
+// src/core/shared/infrastructure/entity-cache.ts
+@Injectable()
+export class EntityCache<T extends Entity<any>> {
+  private cache = new Map<string, { entity: T; timestamp: number }>();
+  private readonly ttl: number = 300000; // 5 minutes
+
+  set(id: string, entity: T): void {
+    this.cache.set(id, { entity, timestamp: Date.now() });
+  }
+
+  get(id: string): T | null {
+    const cached = this.cache.get(id);
+    if (!cached) return null;
+
+    // Check TTL
+    if (Date.now() - cached.timestamp > this.ttl) {
+      this.cache.delete(id);
+      return null;
+    }
+
+    return cached.entity;
+  }
+
+  invalidate(id: string): void {
+    this.cache.delete(id);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+}
+```
+
+## Success Metrics
+
+- [ ] **Domain Isolation**: 100% clean dependency boundaries
+- [ ] **Test Coverage**: >90% unit test coverage for domain logic
+- [ ] **Type Safety**: Strict TypeScript compilation with zero any types
+- [ ] **Performance**: <50ms average use case execution time
+- [ ] **Memory Efficiency**: <100MB heap usage for core domains
+- [ ] **Plugin Architecture**: Modular domain loading capability
+
+## Related V3 Skills
+
+- `v3-ddd-architecture` - DDD architectural design
+- `v3-mcp-optimization` - MCP server integration
+- `v3-memory-unification` - AgentDB repository integration
+- `v3-swarm-coordination` - Swarm domain implementation
+
+## Usage Examples
+
+### Complete Core Implementation
+```bash
+# Full core module implementation
+Task("Core implementation",
+     "Implement all core domains with DDD patterns and comprehensive testing",
+     "core-implementer")
+```
+
+### Domain-Specific Implementation
+```bash
+# Single domain implementation
+Task("Task domain implementation",
+     "Implement task management domain with entities, services, and repositories",
+     "core-implementer")
+```
@@ -0,0 +1,442 @@
+---
+name: "V3 DDD Architecture"
+description: "Domain-Driven Design architecture for claude-flow v3. Implements modular, bounded context architecture with clean separation of concerns and microkernel pattern."
+---
+
+# V3 DDD Architecture
+
+## What This Skill Does
+
+Designs and implements Domain-Driven Design (DDD) architecture for claude-flow v3, decomposing god objects into bounded contexts, implementing clean architecture patterns, and enabling modular, testable code structure.
+
+## Quick Start
+
+```bash
+# Initialize DDD architecture analysis
+Task("Architecture analysis", "Analyze current architecture and design DDD boundaries", "core-architect")
+
+# Domain modeling (parallel)
+Task("Domain decomposition", "Break down orchestrator god object into domains", "core-architect")
+Task("Context mapping", "Map bounded contexts and relationships", "core-architect")
+Task("Interface design", "Design clean domain interfaces", "core-architect")
+```
+
+## DDD Implementation Strategy
+
+### Current Architecture Analysis
+```
+├── PROBLEMATIC: core/orchestrator.ts (1,440 lines - GOD OBJECT)
+│   ├── Task management responsibilities
+│   ├── Session management responsibilities
+│   ├── Health monitoring responsibilities
+│   ├── Lifecycle management responsibilities
+│   └── Event coordination responsibilities
+│
+└── TARGET: Modular DDD Architecture
+    ├── core/domains/
+    │   ├── task-management/
+    │   ├── session-management/
+    │   ├── health-monitoring/
+    │   ├── lifecycle-management/
+    │   └── event-coordination/
+    └── core/shared/
+        ├── interfaces/
+        ├── value-objects/
+        └── domain-events/
+```
+
+### Domain Boundaries
+
+#### 1. Task Management Domain
+```typescript
+// core/domains/task-management/
+interface TaskManagementDomain {
+  // Entities
+  Task: TaskEntity;
+  TaskQueue: TaskQueueEntity;
+
+  // Value Objects
+  TaskId: TaskIdVO;
+  TaskStatus: TaskStatusVO;
+  Priority: PriorityVO;
+
+  // Services
+  TaskScheduler: TaskSchedulingService;
+  TaskValidator: TaskValidationService;
+
+  // Repository
+  TaskRepository: ITaskRepository;
+}
+```
+
+#### 2. Session Management Domain
+```typescript
+// core/domains/session-management/
+interface SessionManagementDomain {
+  // Entities
+  Session: SessionEntity;
+  SessionState: SessionStateEntity;
+
+  // Value Objects
+  SessionId: SessionIdVO;
+  SessionStatus: SessionStatusVO;
+
+  // Services
+  SessionLifecycle: SessionLifecycleService;
+  SessionPersistence: SessionPersistenceService;
+
+  // Repository
+  SessionRepository: ISessionRepository;
+}
+```
+
+#### 3. Health Monitoring Domain
+```typescript
+// core/domains/health-monitoring/
+interface HealthMonitoringDomain {
+  // Entities
+  HealthCheck: HealthCheckEntity;
+  Metric: MetricEntity;
+
+  // Value Objects
+  HealthStatus: HealthStatusVO;
+  Threshold: ThresholdVO;
+
+  // Services
+  HealthCollector: HealthCollectionService;
+  AlertManager: AlertManagementService;
+
+  // Repository
+  MetricsRepository: IMetricsRepository;
+}
+```
+
+## Microkernel Architecture Pattern
+
+### Core Kernel
+```typescript
+// core/kernel/claude-flow-kernel.ts
+export class ClaudeFlowKernel {
+  private domains: Map<string, Domain> = new Map();
+  private eventBus: DomainEventBus;
+  private dependencyContainer: Container;
+
+  async initialize(): Promise<void> {
+    // Load core domains
+    await this.loadDomain('task-management', new TaskManagementDomain());
+    await this.loadDomain('session-management', new SessionManagementDomain());
+    await this.loadDomain('health-monitoring', new HealthMonitoringDomain());
+
+    // Wire up domain events
+    this.setupDomainEventHandlers();
+  }
+
+  async loadDomain(name: string, domain: Domain): Promise<void> {
+    await domain.initialize(this.dependencyContainer);
+    this.domains.set(name, domain);
+  }
+
+  getDomain<T extends Domain>(name: string): T {
+    const domain = this.domains.get(name);
+    if (!domain) {
+      throw new DomainNotLoadedError(name);
+    }
+    return domain as T;
+  }
+}
+```
+
+### Plugin Architecture
+```typescript
+// core/plugins/
+interface DomainPlugin {
+  name: string;
+  version: string;
+  dependencies: string[];
+
+  initialize(kernel: ClaudeFlowKernel): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+// Example: Swarm Coordination Plugin
+export class SwarmCoordinationPlugin implements DomainPlugin {
+  name = 'swarm-coordination';
+  version = '3.0.0';
+  dependencies = ['task-management', 'session-management'];
+
+  async initialize(kernel: ClaudeFlowKernel): Promise<void> {
+    const taskDomain = kernel.getDomain<TaskManagementDomain>('task-management');
+    const sessionDomain = kernel.getDomain<SessionManagementDomain>('session-management');
+
+    // Register swarm coordination services
+    this.swarmCoordinator = new UnifiedSwarmCoordinator(taskDomain, sessionDomain);
+    kernel.registerService('swarm-coordinator', this.swarmCoordinator);
+  }
+}
+```
+
+## Domain Events & Integration
+
+### Event-Driven Communication
+```typescript
+// core/shared/domain-events/
+abstract class DomainEvent {
+  public readonly eventId: string;
+  public readonly aggregateId: string;
+  public readonly occurredOn: Date;
+  public readonly eventVersion: number;
+
+  constructor(aggregateId: string) {
+    this.eventId = crypto.randomUUID();
+    this.aggregateId = aggregateId;
+    this.occurredOn = new Date();
+    this.eventVersion = 1;
+  }
+}
+
+// Task domain events
+export class TaskAssignedEvent extends DomainEvent {
+  constructor(
+    taskId: string,
+    public readonly agentId: string,
+    public readonly priority: Priority
+  ) {
+    super(taskId);
+  }
+}
+
+export class TaskCompletedEvent extends DomainEvent {
+  constructor(
+    taskId: string,
+    public readonly result: TaskResult,
+    public readonly duration: number
+  ) {
+    super(taskId);
+  }
+}
+
+// Event handlers
+@EventHandler(TaskCompletedEvent)
+export class TaskCompletedHandler {
+  constructor(
+    private metricsRepository: IMetricsRepository,
+    private sessionService: SessionLifecycleService
+  ) {}
+
+  async handle(event: TaskCompletedEvent): Promise<void> {
+    // Update metrics
+    await this.metricsRepository.recordTaskCompletion(
+      event.aggregateId,
+      event.duration
+    );
+
+    // Update session state
+    await this.sessionService.markTaskCompleted(
+      event.aggregateId,
+      event.result
+    );
+  }
+}
+```
+
+## Clean Architecture Layers
+
+```typescript
+// Architecture layers
+┌─────────────────────────────────────────┐
+│              Presentation               │  ← CLI, API, UI
+├─────────────────────────────────────────┤
+│              Application                │  ← Use Cases, Commands
+├─────────────────────────────────────────┤
+│               Domain                    │  ← Entities, Services, Events
+├─────────────────────────────────────────┤
+│            Infrastructure               │  ← DB, MCP, External APIs
+└─────────────────────────────────────────┘
+
+// Dependency direction: Outside → Inside
+// Domain layer has NO external dependencies
+```
+
+### Application Layer (Use Cases)
+```typescript
+// core/application/use-cases/
+export class AssignTaskUseCase {
+  constructor(
+    private taskRepository: ITaskRepository,
+    private agentRepository: IAgentRepository,
+    private eventBus: DomainEventBus
+  ) {}
+
+  async execute(command: AssignTaskCommand): Promise<TaskResult> {
+    // 1. Validate command
+    await this.validateCommand(command);
+
+    // 2. Load aggregates
+    const task = await this.taskRepository.findById(command.taskId);
+    const agent = await this.agentRepository.findById(command.agentId);
+
+    // 3. Business logic (in domain)
+    task.assignTo(agent);
+
+    // 4. Persist changes
+    await this.taskRepository.save(task);
+
+    // 5. Publish domain events
+    task.getUncommittedEvents().forEach(event =>
+      this.eventBus.publish(event)
+    );
+
+    // 6. Return result
+    return TaskResult.success(task);
+  }
+}
+```
+
+## Module Configuration
+
+### Bounded Context Modules
+```typescript
+// core/domains/task-management/module.ts
+export const taskManagementModule = {
+  name: 'task-management',
+
+  entities: [
+    TaskEntity,
+    TaskQueueEntity
+  ],
+
+  valueObjects: [
+    TaskIdVO,
+    TaskStatusVO,
+    PriorityVO
+  ],
+
+  services: [
+    TaskSchedulingService,
+    TaskValidationService
+  ],
+
+  repositories: [
+    { provide: ITaskRepository, useClass: SqliteTaskRepository }
+  ],
+
+  eventHandlers: [
+    TaskAssignedHandler,
+    TaskCompletedHandler
+  ]
+};
+```
+
+## Migration Strategy
+
+### Phase 1: Extract Domain Services
+```typescript
+// Extract services from orchestrator.ts
+const extractionPlan = {
+  week1: [
+    'TaskManager → task-management domain',
+    'SessionManager → session-management domain'
+  ],
+  week2: [
+    'HealthMonitor → health-monitoring domain',
+    'LifecycleManager → lifecycle-management domain'
+  ],
+  week3: [
+    'EventCoordinator → event-coordination domain',
+    'Wire up domain events'
+  ]
+};
+```
+
+### Phase 2: Implement Clean Interfaces
+```typescript
+// Clean separation with dependency injection
+export class TaskController {
+  constructor(
+    @Inject('AssignTaskUseCase') private assignTask: AssignTaskUseCase,
+    @Inject('CompleteTaskUseCase') private completeTask: CompleteTaskUseCase
+  ) {}
+
+  async assign(request: AssignTaskRequest): Promise<TaskResponse> {
+    const command = AssignTaskCommand.fromRequest(request);
+    const result = await this.assignTask.execute(command);
+    return TaskResponse.fromResult(result);
+  }
+}
+```
+
+### Phase 3: Plugin System
+```typescript
+// Enable plugin-based extensions
+const pluginSystem = {
+  core: ['task-management', 'session-management', 'health-monitoring'],
+  optional: ['swarm-coordination', 'learning-integration', 'performance-monitoring']
+};
+```
+
+## Testing Strategy
+
+### Domain Testing (London School TDD)
+```typescript
+// Pure domain logic testing
+describe('Task Entity', () => {
+  let task: TaskEntity;
+  let mockAgent: jest.Mocked<AgentEntity>;
+
+  beforeEach(() => {
+    task = new TaskEntity(TaskId.create(), 'Test task');
+    mockAgent = createMock<AgentEntity>();
+  });
+
+  it('should assign to agent when valid', () => {
+    mockAgent.canAcceptTask.mockReturnValue(true);
+
+    task.assignTo(mockAgent);
+
+    expect(task.assignedAgent).toBe(mockAgent);
+    expect(task.status.value).toBe('assigned');
+  });
+
+  it('should emit TaskAssignedEvent when assigned', () => {
+    mockAgent.canAcceptTask.mockReturnValue(true);
+
+    task.assignTo(mockAgent);
+
+    const events = task.getUncommittedEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toBeInstanceOf(TaskAssignedEvent);
+  });
+});
+```
+
+## Success Metrics
+
+- [ ] **God Object Elimination**: orchestrator.ts (1,440 lines) → 5 focused domains (<300 lines each)
+- [ ] **Bounded Context Isolation**: 100% domain independence
+- [ ] **Plugin Architecture**: Core + optional modules loading
+- [ ] **Clean Architecture**: Dependency inversion maintained
+- [ ] **Event-Driven Communication**: Loose coupling between domains
+- [ ] **Test Coverage**: >90% domain logic coverage
+
+## Related V3 Skills
+
+- `v3-core-implementation` - Implementation of DDD domains
+- `v3-memory-unification` - AgentDB integration within bounded contexts
+- `v3-swarm-coordination` - Swarm coordination as domain plugin
+- `v3-performance-optimization` - Performance optimization across domains
+
+## Usage Examples
+
+### Complete Domain Extraction
+```bash
+# Full DDD architecture implementation
+Task("DDD architecture implementation",
+     "Extract orchestrator into DDD domains with clean architecture",
+     "core-architect")
+```
+
+### Plugin Development
+```bash
+# Create domain plugin
+npm run create:plugin -- --name swarm-coordination --template domain
+```
@@ -0,0 +1,241 @@
+---
+name: "V3 Deep Integration"
+description: "Deep agentic-flow@alpha integration implementing ADR-001. Eliminates 10,000+ duplicate lines by building claude-flow as specialized extension rather than parallel implementation."
+---
+
+# V3 Deep Integration
+
+## What This Skill Does
+
+Transforms claude-flow from parallel implementation to specialized extension of agentic-flow@alpha, eliminating massive code duplication while achieving performance improvements and feature parity.
+
+## Quick Start
+
+```bash
+# Initialize deep integration
+Task("Integration architecture", "Design agentic-flow@alpha adapter layer", "v3-integration-architect")
+
+# Feature integration (parallel)
+Task("SONA integration", "Integrate 5 SONA learning modes", "v3-integration-architect")
+Task("Flash Attention", "Implement 2.49x-7.47x speedup", "v3-integration-architect")
+Task("AgentDB coordination", "Setup 150x-12,500x search", "v3-integration-architect")
+```
+
+## Code Deduplication Strategy
+
+### Current Overlap → Integration
+```
+┌─────────────────────────────────────────┐
+│  claude-flow          agentic-flow      │
+├─────────────────────────────────────────┤
+│ SwarmCoordinator  →   Swarm System      │ 80% overlap (eliminate)
+│ AgentManager      →   Agent Lifecycle   │ 70% overlap (eliminate)
+│ TaskScheduler     →   Task Execution    │ 60% overlap (eliminate)
+│ SessionManager    →   Session Mgmt      │ 50% overlap (eliminate)
+└─────────────────────────────────────────┘
+
+TARGET: <5,000 lines (vs 15,000+ currently)
+```
+
+## agentic-flow@alpha Feature Integration
+
+### SONA Learning Modes
+```typescript
+class SONAIntegration {
+  async initializeMode(mode: SONAMode): Promise<void> {
+    switch(mode) {
+      case 'real-time':   // ~0.05ms adaptation
+      case 'balanced':    // general purpose
+      case 'research':    // deep exploration
+      case 'edge':        // resource-constrained
+      case 'batch':       // high-throughput
+    }
+    await this.agenticFlow.sona.setMode(mode);
+  }
+}
+```
+
+### Flash Attention Integration
+```typescript
+class FlashAttentionIntegration {
+  async optimizeAttention(): Promise<AttentionResult> {
+    return this.agenticFlow.attention.flashAttention({
+      speedupTarget: '2.49x-7.47x',
+      memoryReduction: '50-75%',
+      mechanisms: ['multi-head', 'linear', 'local', 'global']
+    });
+  }
+}
+```
+
+### AgentDB Coordination
+```typescript
+class AgentDBIntegration {
+  async setupCrossAgentMemory(): Promise<void> {
+    await this.agentdb.enableCrossAgentSharing({
+      indexType: 'HNSW',
+      speedupTarget: '150x-12500x',
+      dimensions: 1536
+    });
+  }
+}
+```
+
+### MCP Tools Integration
+```typescript
+class MCPToolsIntegration {
+  async integrateBuiltinTools(): Promise<void> {
+    // Leverage 213 pre-built tools
+    const tools = await this.agenticFlow.mcp.getAvailableTools();
+    await this.registerClaudeFlowSpecificTools(tools);
+
+    // Use 19 hook types
+    const hookTypes = await this.agenticFlow.hooks.getTypes();
+    await this.configureClaudeFlowHooks(hookTypes);
+  }
+}
+```
+
+## Migration Implementation
+
+### Phase 1: Adapter Layer
+```typescript
+import { Agent as AgenticFlowAgent } from 'agentic-flow@alpha';
+
+export class ClaudeFlowAgent extends AgenticFlowAgent {
+  async handleClaudeFlowTask(task: ClaudeTask): Promise<TaskResult> {
+    return this.executeWithSONA(task);
+  }
+
+  // Backward compatibility
+  async legacyCompatibilityLayer(oldAPI: any): Promise<any> {
+    return this.adaptToNewAPI(oldAPI);
+  }
+}
+```
+
+### Phase 2: System Migration
+```typescript
+class SystemMigration {
+  async migrateSwarmCoordination(): Promise<void> {
+    // Replace SwarmCoordinator (800+ lines) with agentic-flow Swarm
+    const swarmConfig = await this.extractSwarmConfig();
+    await this.agenticFlow.swarm.initialize(swarmConfig);
+  }
+
+  async migrateAgentManagement(): Promise<void> {
+    // Replace AgentManager (1,736+ lines) with agentic-flow lifecycle
+    const agents = await this.extractActiveAgents();
+    for (const agent of agents) {
+      await this.agenticFlow.agent.create(agent);
+    }
+  }
+
+  async migrateTaskExecution(): Promise<void> {
+    // Replace TaskScheduler with agentic-flow task graph
+    const tasks = await this.extractTasks();
+    await this.agenticFlow.task.executeGraph(this.buildTaskGraph(tasks));
+  }
+}
+```
+
+### Phase 3: Cleanup
+```typescript
+class CodeCleanup {
+  async removeDeprecatedCode(): Promise<void> {
+    // Remove massive duplicate implementations
+    await this.removeFile('src/core/SwarmCoordinator.ts');    // 800+ lines
+    await this.removeFile('src/agents/AgentManager.ts');      // 1,736+ lines
+    await this.removeFile('src/task/TaskScheduler.ts');       // 500+ lines
+
+    // Total reduction: 10,000+ → <5,000 lines
+  }
+}
+```
+
+## RL Algorithm Integration
+
+```typescript
+class RLIntegration {
+  algorithms = [
+    'PPO', 'DQN', 'A2C', 'MCTS', 'Q-Learning',
+    'SARSA', 'Actor-Critic', 'Decision-Transformer'
+  ];
+
+  async optimizeAgentBehavior(): Promise<void> {
+    for (const algorithm of this.algorithms) {
+      await this.agenticFlow.rl.train(algorithm, {
+        episodes: 1000,
+        rewardFunction: this.claudeFlowRewardFunction
+      });
+    }
+  }
+}
+```
+
+## Performance Integration
+
+### Flash Attention Targets
+```typescript
+const attentionBenchmark = {
+  baseline: 'current attention mechanism',
+  target: '2.49x-7.47x improvement',
+  memoryReduction: '50-75%',
+  implementation: 'agentic-flow@alpha Flash Attention'
+};
+```
+
+### AgentDB Search Performance
+```typescript
+const searchBenchmark = {
+  baseline: 'linear search in current systems',
+  target: '150x-12,500x via HNSW indexing',
+  implementation: 'agentic-flow@alpha AgentDB'
+};
+```
+
+## Backward Compatibility
+
+### Gradual Migration
+```typescript
+class BackwardCompatibility {
+  // Phase 1: Dual operation
+  async enableDualOperation(): Promise<void> {
+    this.oldSystem.continue();
+    this.newSystem.initialize();
+    this.syncState(this.oldSystem, this.newSystem);
+  }
+
+  // Phase 2: Feature-by-feature migration
+  async migrateGradually(): Promise<void> {
+    const features = this.getAllFeatures();
+    for (const feature of features) {
+      await this.migrateFeature(feature);
+      await this.validateFeatureParity(feature);
+    }
+  }
+
+  // Phase 3: Complete transition
+  async completeTransition(): Promise<void> {
+    await this.validateFullParity();
+    await this.deprecateOldSystem();
+  }
+}
+```
+
+## Success Metrics
+
+- **Code Reduction**: <5,000 lines orchestration (vs 15,000+)
+- **Performance**: 2.49x-7.47x Flash Attention speedup
+- **Search**: 150x-12,500x AgentDB improvement
+- **Memory**: 50-75% usage reduction
+- **Feature Parity**: 100% v2 functionality maintained
+- **SONA**: <0.05ms adaptation time
+- **Integration**: All 213 MCP tools + 19 hook types available
+
+## Related V3 Skills
+
+- `v3-memory-unification` - Memory system integration
+- `v3-performance-optimization` - Performance target validation
+- `v3-swarm-coordination` - Swarm system migration
+- `v3-security-overhaul` - Secure integration patterns
@@ -0,0 +1,777 @@
+---
+name: "V3 MCP Optimization"
+description: "MCP server optimization and transport layer enhancement for claude-flow v3. Implements connection pooling, load balancing, tool registry optimization, and performance monitoring for sub-100ms response times."
+---
+
+# V3 MCP Optimization
+
+## What This Skill Does
+
+Optimizes claude-flow v3 MCP (Model Context Protocol) server implementation with advanced transport layer optimizations, connection pooling, load balancing, and comprehensive performance monitoring to achieve sub-100ms response times.
+
+## Quick Start
+
+```bash
+# Initialize MCP optimization analysis
+Task("MCP architecture", "Analyze current MCP server performance and bottlenecks", "mcp-specialist")
+
+# Optimization implementation (parallel)
+Task("Connection pooling", "Implement MCP connection pooling and reuse", "mcp-specialist")
+Task("Load balancing", "Add dynamic load balancing for MCP tools", "mcp-specialist")
+Task("Transport optimization", "Optimize transport layer performance", "mcp-specialist")
+```
+
+## MCP Performance Architecture
+
+### Current State Analysis
+```
+Current MCP Issues:
+├── Cold Start Latency: ~1.8s MCP server init
+├── Connection Overhead: New connection per request
+├── Tool Registry: Linear search O(n) for 213+ tools
+├── Transport Layer: No connection reuse
+└── Memory Usage: No cleanup of idle connections
+
+Target Performance:
+├── Startup Time: <400ms (4.5x improvement)
+├── Tool Lookup: <5ms (O(1) hash table)
+├── Connection Reuse: 90%+ connection pool hits
+├── Response Time: <100ms p95
+└── Memory Efficiency: 50% reduction
+```
+
+### MCP Server Architecture
+```typescript
+// src/core/mcp/mcp-server.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+interface OptimizedMCPConfig {
+  // Connection pooling
+  maxConnections: number;
+  idleTimeoutMs: number;
+  connectionReuseEnabled: boolean;
+
+  // Tool registry
+  toolCacheEnabled: boolean;
+  toolIndexType: 'hash' | 'trie';
+
+  // Performance
+  requestTimeoutMs: number;
+  batchingEnabled: boolean;
+  compressionEnabled: boolean;
+
+  // Monitoring
+  metricsEnabled: boolean;
+  healthCheckIntervalMs: number;
+}
+
+export class OptimizedMCPServer {
+  private server: Server;
+  private connectionPool: ConnectionPool;
+  private toolRegistry: FastToolRegistry;
+  private loadBalancer: MCPLoadBalancer;
+  private metrics: MCPMetrics;
+
+  constructor(config: OptimizedMCPConfig) {
+    this.server = new Server({
+      name: 'claude-flow-v3',
+      version: '3.0.0'
+    }, {
+      capabilities: {
+        tools: { listChanged: true },
+        resources: { subscribe: true, listChanged: true },
+        prompts: { listChanged: true }
+      }
+    });
+
+    this.connectionPool = new ConnectionPool(config);
+    this.toolRegistry = new FastToolRegistry(config.toolIndexType);
+    this.loadBalancer = new MCPLoadBalancer();
+    this.metrics = new MCPMetrics(config.metricsEnabled);
+  }
+
+  async start(): Promise<void> {
+    // Pre-warm connection pool
+    await this.connectionPool.preWarm();
+
+    // Pre-build tool index
+    await this.toolRegistry.buildIndex();
+
+    // Setup request handlers with optimizations
+    this.setupOptimizedHandlers();
+
+    // Start health monitoring
+    this.startHealthMonitoring();
+
+    // Start server
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    this.metrics.recordStartup();
+  }
+}
+```
+
+## Connection Pool Implementation
+
+### Advanced Connection Pooling
+```typescript
+// src/core/mcp/connection-pool.ts
+interface PooledConnection {
+  id: string;
+  connection: MCPConnection;
+  lastUsed: number;
+  usageCount: number;
+  isHealthy: boolean;
+}
+
+export class ConnectionPool {
+  private pool: Map<string, PooledConnection> = new Map();
+  private readonly config: ConnectionPoolConfig;
+  private healthChecker: HealthChecker;
+
+  constructor(config: ConnectionPoolConfig) {
+    this.config = {
+      maxConnections: 50,
+      minConnections: 5,
+      idleTimeoutMs: 300000, // 5 minutes
+      maxUsageCount: 1000,
+      healthCheckIntervalMs: 30000,
+      ...config
+    };
+
+    this.healthChecker = new HealthChecker(this.config.healthCheckIntervalMs);
+  }
+
+  async getConnection(endpoint: string): Promise<MCPConnection> {
+    const start = performance.now();
+
+    // Try to get from pool first
+    const pooled = this.findAvailableConnection(endpoint);
+    if (pooled) {
+      pooled.lastUsed = Date.now();
+      pooled.usageCount++;
+
+      this.recordMetric('pool_hit', performance.now() - start);
+      return pooled.connection;
+    }
+
+    // Check pool capacity
+    if (this.pool.size >= this.config.maxConnections) {
+      await this.evictLeastUsedConnection();
+    }
+
+    // Create new connection
+    const connection = await this.createConnection(endpoint);
+    const pooledConn: PooledConnection = {
+      id: this.generateConnectionId(),
+      connection,
+      lastUsed: Date.now(),
+      usageCount: 1,
+      isHealthy: true
+    };
+
+    this.pool.set(pooledConn.id, pooledConn);
+    this.recordMetric('pool_miss', performance.now() - start);
+
+    return connection;
+  }
+
+  async releaseConnection(connection: MCPConnection): Promise<void> {
+    // Mark connection as available for reuse
+    const pooled = this.findConnectionById(connection.id);
+    if (pooled) {
+      // Check if connection should be retired
+      if (pooled.usageCount >= this.config.maxUsageCount) {
+        await this.removeConnection(pooled.id);
+      }
+    }
+  }
+
+  async preWarm(): Promise<void> {
+    const connections: Promise<MCPConnection>[] = [];
+
+    for (let i = 0; i < this.config.minConnections; i++) {
+      connections.push(this.createConnection('default'));
+    }
+
+    await Promise.all(connections);
+  }
+
+  private async evictLeastUsedConnection(): Promise<void> {
+    let oldestConn: PooledConnection | null = null;
+    let oldestTime = Date.now();
+
+    for (const conn of this.pool.values()) {
+      if (conn.lastUsed < oldestTime) {
+        oldestTime = conn.lastUsed;
+        oldestConn = conn;
+      }
+    }
+
+    if (oldestConn) {
+      await this.removeConnection(oldestConn.id);
+    }
+  }
+
+  private findAvailableConnection(endpoint: string): PooledConnection | null {
+    for (const conn of this.pool.values()) {
+      if (conn.isHealthy &&
+          conn.connection.endpoint === endpoint &&
+          Date.now() - conn.lastUsed < this.config.idleTimeoutMs) {
+        return conn;
+      }
+    }
+    return null;
+  }
+}
+```
+
+## Fast Tool Registry
+
+### O(1) Tool Lookup Implementation
+```typescript
+// src/core/mcp/fast-tool-registry.ts
+interface ToolIndexEntry {
+  name: string;
+  handler: ToolHandler;
+  metadata: ToolMetadata;
+  usageCount: number;
+  avgLatencyMs: number;
+}
+
+export class FastToolRegistry {
+  private toolIndex: Map<string, ToolIndexEntry> = new Map();
+  private categoryIndex: Map<string, string[]> = new Map();
+  private fuzzyMatcher: FuzzyMatcher;
+  private cache: LRUCache<string, ToolIndexEntry>;
+
+  constructor(indexType: 'hash' | 'trie' = 'hash') {
+    this.fuzzyMatcher = new FuzzyMatcher();
+    this.cache = new LRUCache<string, ToolIndexEntry>(1000); // Cache 1000 most used tools
+  }
+
+  async buildIndex(): Promise<void> {
+    const start = performance.now();
+
+    // Load all available tools
+    const tools = await this.loadAllTools();
+
+    // Build hash index for O(1) lookup
+    for (const tool of tools) {
+      const entry: ToolIndexEntry = {
+        name: tool.name,
+        handler: tool.handler,
+        metadata: tool.metadata,
+        usageCount: 0,
+        avgLatencyMs: 0
+      };
+
+      this.toolIndex.set(tool.name, entry);
+
+      // Build category index
+      const category = tool.metadata.category || 'general';
+      if (!this.categoryIndex.has(category)) {
+        this.categoryIndex.set(category, []);
+      }
+      this.categoryIndex.get(category)!.push(tool.name);
+    }
+
+    // Build fuzzy search index
+    await this.fuzzyMatcher.buildIndex(tools.map(t => t.name));
+
+    console.log(`Tool index built in ${(performance.now() - start).toFixed(2)}ms for ${tools.length} tools`);
+  }
+
+  findTool(name: string): ToolIndexEntry | null {
+    // Try cache first
+    const cached = this.cache.get(name);
+    if (cached) return cached;
+
+    // Try exact match
+    const exact = this.toolIndex.get(name);
+    if (exact) {
+      this.cache.set(name, exact);
+      return exact;
+    }
+
+    // Try fuzzy match
+    const fuzzyMatches = this.fuzzyMatcher.search(name, 1);
+    if (fuzzyMatches.length > 0) {
+      const match = this.toolIndex.get(fuzzyMatches[0]);
+      if (match) {
+        this.cache.set(name, match);
+        return match;
+      }
+    }
+
+    return null;
+  }
+
+  findToolsByCategory(category: string): ToolIndexEntry[] {
+    const toolNames = this.categoryIndex.get(category) || [];
+    return toolNames
+      .map(name => this.toolIndex.get(name))
+      .filter(entry => entry !== undefined) as ToolIndexEntry[];
+  }
+
+  getMostUsedTools(limit: number = 10): ToolIndexEntry[] {
+    return Array.from(this.toolIndex.values())
+      .sort((a, b) => b.usageCount - a.usageCount)
+      .slice(0, limit);
+  }
+
+  recordToolUsage(toolName: string, latencyMs: number): void {
+    const entry = this.toolIndex.get(toolName);
+    if (entry) {
+      entry.usageCount++;
+      // Moving average for latency
+      entry.avgLatencyMs = (entry.avgLatencyMs + latencyMs) / 2;
+    }
+  }
+}
+```
+
+## Load Balancing & Request Distribution
+
+### Intelligent Load Balancer
+```typescript
+// src/core/mcp/load-balancer.ts
+interface ServerInstance {
+  id: string;
+  endpoint: string;
+  load: number;
+  responseTime: number;
+  isHealthy: boolean;
+  maxConnections: number;
+  currentConnections: number;
+}
+
+export class MCPLoadBalancer {
+  private servers: Map<string, ServerInstance> = new Map();
+  private routingStrategy: RoutingStrategy = 'least-connections';
+
+  addServer(server: ServerInstance): void {
+    this.servers.set(server.id, server);
+  }
+
+  selectServer(toolCategory?: string): ServerInstance | null {
+    const healthyServers = Array.from(this.servers.values())
+      .filter(server => server.isHealthy);
+
+    if (healthyServers.length === 0) return null;
+
+    switch (this.routingStrategy) {
+      case 'round-robin':
+        return this.roundRobinSelection(healthyServers);
+
+      case 'least-connections':
+        return this.leastConnectionsSelection(healthyServers);
+
+      case 'response-time':
+        return this.responseTimeSelection(healthyServers);
+
+      case 'weighted':
+        return this.weightedSelection(healthyServers, toolCategory);
+
+      default:
+        return healthyServers[0];
+    }
+  }
+
+  private leastConnectionsSelection(servers: ServerInstance[]): ServerInstance {
+    return servers.reduce((least, current) =>
+      current.currentConnections < least.currentConnections ? current : least
+    );
+  }
+
+  private responseTimeSelection(servers: ServerInstance[]): ServerInstance {
+    return servers.reduce((fastest, current) =>
+      current.responseTime < fastest.responseTime ? current : fastest
+    );
+  }
+
+  private weightedSelection(servers: ServerInstance[], category?: string): ServerInstance {
+    // Prefer servers with lower load and better response time
+    const scored = servers.map(server => ({
+      server,
+      score: this.calculateServerScore(server, category)
+    }));
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored[0].server;
+  }
+
+  private calculateServerScore(server: ServerInstance, category?: string): number {
+    const loadFactor = 1 - (server.currentConnections / server.maxConnections);
+    const responseFactor = 1 / (server.responseTime + 1);
+    const categoryBonus = this.getCategoryBonus(server, category);
+
+    return loadFactor * 0.4 + responseFactor * 0.4 + categoryBonus * 0.2;
+  }
+
+  updateServerMetrics(serverId: string, metrics: Partial<ServerInstance>): void {
+    const server = this.servers.get(serverId);
+    if (server) {
+      Object.assign(server, metrics);
+    }
+  }
+}
+```
+
+## Transport Layer Optimization
+
+### High-Performance Transport
+```typescript
+// src/core/mcp/optimized-transport.ts
+export class OptimizedTransport {
+  private compression: boolean = true;
+  private batching: boolean = true;
+  private batchBuffer: MCPMessage[] = [];
+  private batchTimeout: NodeJS.Timeout | null = null;
+
+  constructor(private config: TransportConfig) {}
+
+  async send(message: MCPMessage): Promise<void> {
+    if (this.batching && this.canBatch(message)) {
+      this.addToBatch(message);
+      return;
+    }
+
+    await this.sendImmediate(message);
+  }
+
+  private async sendImmediate(message: MCPMessage): Promise<void> {
+    const start = performance.now();
+
+    // Compress if enabled
+    const payload = this.compression
+      ? await this.compress(message)
+      : message;
+
+    // Send through transport
+    await this.transport.send(payload);
+
+    // Record metrics
+    this.recordLatency(performance.now() - start);
+  }
+
+  private addToBatch(message: MCPMessage): void {
+    this.batchBuffer.push(message);
+
+    // Start batch timeout if not already running
+    if (!this.batchTimeout) {
+      this.batchTimeout = setTimeout(
+        () => this.flushBatch(),
+        this.config.batchTimeoutMs || 10
+      );
+    }
+
+    // Flush if batch is full
+    if (this.batchBuffer.length >= this.config.maxBatchSize) {
+      this.flushBatch();
+    }
+  }
+
+  private async flushBatch(): Promise<void> {
+    if (this.batchBuffer.length === 0) return;
+
+    const batch = this.batchBuffer.splice(0);
+    this.batchTimeout = null;
+
+    // Send as single batched message
+    await this.sendImmediate({
+      type: 'batch',
+      messages: batch
+    });
+  }
+
+  private canBatch(message: MCPMessage): boolean {
+    // Don't batch urgent messages or responses
+    return message.type !== 'response' &&
+           message.priority !== 'high' &&
+           message.type !== 'error';
+  }
+
+  private async compress(data: any): Promise<Buffer> {
+    // Use fast compression for smaller messages
+    return gzipSync(JSON.stringify(data));
+  }
+}
+```
+
+## Performance Monitoring
+
+### Real-time MCP Metrics
+```typescript
+// src/core/mcp/metrics.ts
+interface MCPMetrics {
+  requestCount: number;
+  errorCount: number;
+  avgResponseTime: number;
+  p95ResponseTime: number;
+  connectionPoolHits: number;
+  connectionPoolMisses: number;
+  toolLookupTime: number;
+  startupTime: number;
+}
+
+export class MCPMetricsCollector {
+  private metrics: MCPMetrics;
+  private responseTimeBuffer: number[] = [];
+  private readonly bufferSize = 1000;
+
+  constructor() {
+    this.metrics = this.createInitialMetrics();
+  }
+
+  recordRequest(latencyMs: number): void {
+    this.metrics.requestCount++;
+    this.updateResponseTimes(latencyMs);
+  }
+
+  recordError(): void {
+    this.metrics.errorCount++;
+  }
+
+  recordConnectionPoolHit(): void {
+    this.metrics.connectionPoolHits++;
+  }
+
+  recordConnectionPoolMiss(): void {
+    this.metrics.connectionPoolMisses++;
+  }
+
+  recordToolLookup(latencyMs: number): void {
+    this.metrics.toolLookupTime = this.updateMovingAverage(
+      this.metrics.toolLookupTime,
+      latencyMs
+    );
+  }
+
+  recordStartup(latencyMs: number): void {
+    this.metrics.startupTime = latencyMs;
+  }
+
+  getMetrics(): MCPMetrics {
+    return { ...this.metrics };
+  }
+
+  getHealthStatus(): HealthStatus {
+    const errorRate = this.metrics.errorCount / this.metrics.requestCount;
+    const poolHitRate = this.metrics.connectionPoolHits /
+      (this.metrics.connectionPoolHits + this.metrics.connectionPoolMisses);
+
+    return {
+      status: this.determineHealthStatus(errorRate, poolHitRate),
+      errorRate,
+      poolHitRate,
+      avgResponseTime: this.metrics.avgResponseTime,
+      p95ResponseTime: this.metrics.p95ResponseTime
+    };
+  }
+
+  private updateResponseTimes(latency: number): void {
+    this.responseTimeBuffer.push(latency);
+
+    if (this.responseTimeBuffer.length > this.bufferSize) {
+      this.responseTimeBuffer.shift();
+    }
+
+    this.metrics.avgResponseTime = this.calculateAverage(this.responseTimeBuffer);
+    this.metrics.p95ResponseTime = this.calculatePercentile(this.responseTimeBuffer, 95);
+  }
+
+  private calculatePercentile(arr: number[], percentile: number): number {
+    const sorted = arr.slice().sort((a, b) => a - b);
+    const index = Math.ceil((percentile / 100) * sorted.length) - 1;
+    return sorted[index] || 0;
+  }
+
+  private determineHealthStatus(errorRate: number, poolHitRate: number): 'healthy' | 'warning' | 'critical' {
+    if (errorRate > 0.1 || poolHitRate < 0.5) return 'critical';
+    if (errorRate > 0.05 || poolHitRate < 0.7) return 'warning';
+    return 'healthy';
+  }
+}
+```
+
+## Tool Registry Optimization
+
+### Pre-compiled Tool Index
+```typescript
+// src/core/mcp/tool-precompiler.ts
+export class ToolPrecompiler {
+  async precompileTools(): Promise<CompiledToolRegistry> {
+    const tools = await this.loadAllTools();
+
+    // Create optimized lookup structures
+    const nameIndex = new Map<string, Tool>();
+    const categoryIndex = new Map<string, Tool[]>();
+    const fuzzyIndex = new Map<string, string[]>();
+
+    for (const tool of tools) {
+      // Exact name index
+      nameIndex.set(tool.name, tool);
+
+      // Category index
+      const category = tool.metadata.category || 'general';
+      if (!categoryIndex.has(category)) {
+        categoryIndex.set(category, []);
+      }
+      categoryIndex.get(category)!.push(tool);
+
+      // Pre-compute fuzzy variations
+      const variations = this.generateFuzzyVariations(tool.name);
+      for (const variation of variations) {
+        if (!fuzzyIndex.has(variation)) {
+          fuzzyIndex.set(variation, []);
+        }
+        fuzzyIndex.get(variation)!.push(tool.name);
+      }
+    }
+
+    return {
+      nameIndex,
+      categoryIndex,
+      fuzzyIndex,
+      totalTools: tools.length,
+      compiledAt: new Date()
+    };
+  }
+
+  private generateFuzzyVariations(name: string): string[] {
+    const variations: string[] = [];
+
+    // Common typos and abbreviations
+    variations.push(name.toLowerCase());
+    variations.push(name.replace(/[-_]/g, ''));
+    variations.push(name.replace(/[aeiou]/gi, '')); // Consonants only
+
+    // Add more fuzzy matching logic as needed
+
+    return variations;
+  }
+}
+```
+
+## Advanced Caching Strategy
+
+### Multi-Level Caching
+```typescript
+// src/core/mcp/multi-level-cache.ts
+export class MultiLevelCache {
+  private l1Cache: Map<string, any> = new Map(); // In-memory, fastest
+  private l2Cache: LRUCache<string, any>; // LRU cache, larger capacity
+  private l3Cache: DiskCache; // Persistent disk cache
+
+  constructor(config: CacheConfig) {
+    this.l2Cache = new LRUCache<string, any>({
+      max: config.l2MaxEntries || 10000,
+      ttl: config.l2TTL || 300000 // 5 minutes
+    });
+
+    this.l3Cache = new DiskCache(config.l3Path || './.cache/mcp');
+  }
+
+  async get(key: string): Promise<any | null> {
+    // Try L1 cache first (fastest)
+    if (this.l1Cache.has(key)) {
+      return this.l1Cache.get(key);
+    }
+
+    // Try L2 cache
+    const l2Value = this.l2Cache.get(key);
+    if (l2Value) {
+      // Promote to L1
+      this.l1Cache.set(key, l2Value);
+      return l2Value;
+    }
+
+    // Try L3 cache (disk)
+    const l3Value = await this.l3Cache.get(key);
+    if (l3Value) {
+      // Promote to L2 and L1
+      this.l2Cache.set(key, l3Value);
+      this.l1Cache.set(key, l3Value);
+      return l3Value;
+    }
+
+    return null;
+  }
+
+  async set(key: string, value: any, options?: CacheOptions): Promise<void> {
+    // Set in all levels
+    this.l1Cache.set(key, value);
+    this.l2Cache.set(key, value);
+
+    if (options?.persistent) {
+      await this.l3Cache.set(key, value);
+    }
+
+    // Manage L1 cache size
+    if (this.l1Cache.size > 1000) {
+      const firstKey = this.l1Cache.keys().next().value;
+      this.l1Cache.delete(firstKey);
+    }
+  }
+}
+```
+
+## Success Metrics
+
+### Performance Targets
+- [ ] **Startup Time**: <400ms MCP server initialization (4.5x improvement)
+- [ ] **Response Time**: <100ms p95 for tool execution
+- [ ] **Tool Lookup**: <5ms average lookup time
+- [ ] **Connection Pool**: >90% hit rate
+- [ ] **Memory Usage**: 50% reduction in idle memory
+- [ ] **Error Rate**: <1% failed requests
+- [ ] **Throughput**: >1000 requests/second
+
+### Monitoring Dashboards
+```typescript
+const mcpDashboard = {
+  metrics: [
+    'Request latency (p50, p95, p99)',
+    'Error rate by tool category',
+    'Connection pool utilization',
+    'Tool lookup performance',
+    'Memory usage trends',
+    'Cache hit rates (L1, L2, L3)'
+  ],
+
+  alerts: [
+    'Response time >200ms for 5 minutes',
+    'Error rate >5% for 1 minute',
+    'Pool hit rate <70% for 10 minutes',
+    'Memory usage >500MB for 5 minutes'
+  ]
+};
+```
+
+## Related V3 Skills
+
+- `v3-core-implementation` - Core domain integration with MCP
+- `v3-performance-optimization` - Overall performance optimization
+- `v3-swarm-coordination` - MCP integration with swarm coordination
+- `v3-memory-unification` - Memory sharing via MCP tools
+
+## Usage Examples
+
+### Complete MCP Optimization
+```bash
+# Full MCP server optimization
+Task("MCP optimization implementation",
+     "Implement all MCP performance optimizations with monitoring",
+     "mcp-specialist")
+```
+
+### Specific Optimization
+```bash
+# Connection pool optimization
+Task("MCP connection pooling",
+     "Implement advanced connection pooling with health monitoring",
+     "mcp-specialist")
+```
@@ -0,0 +1,174 @@
+---
+name: "V3 Memory Unification"
+description: "Unify 6+ memory systems into AgentDB with HNSW indexing for 150x-12,500x search improvements. Implements ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend)."
+---
+
+# V3 Memory Unification
+
+## What This Skill Does
+
+Consolidates disparate memory systems into unified AgentDB backend with HNSW vector search, achieving 150x-12,500x search performance improvements while maintaining backward compatibility.
+
+## Quick Start
+
+```bash
+# Initialize memory unification
+Task("Memory architecture", "Design AgentDB unification strategy", "v3-memory-specialist")
+
+# AgentDB integration
+Task("AgentDB setup", "Configure HNSW indexing and vector search", "v3-memory-specialist")
+
+# Data migration
+Task("Memory migration", "Migrate SQLite/Markdown to AgentDB", "v3-memory-specialist")
+```
+
+## Systems to Unify
+
+### Legacy Systems → AgentDB
+```
+┌─────────────────────────────────────────┐
+│  • MemoryManager (basic operations)     │
+│  • DistributedMemorySystem (clustering) │
+│  • SwarmMemory (agent-specific)         │
+│  • AdvancedMemoryManager (features)     │
+│  • SQLiteBackend (structured)           │
+│  • MarkdownBackend (file-based)         │
+│  • HybridBackend (combination)          │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│       🚀 AgentDB with HNSW             │
+│  • 150x-12,500x faster search          │
+│  • Unified query interface             │
+│  • Cross-agent memory sharing          │
+│  • SONA learning integration           │
+└─────────────────────────────────────────┘
+```
+
+## Implementation Architecture
+
+### Unified Memory Service
+```typescript
+class UnifiedMemoryService implements IMemoryBackend {
+  constructor(
+    private agentdb: AgentDBAdapter,
+    private indexer: HNSWIndexer,
+    private migrator: DataMigrator
+  ) {}
+
+  async store(entry: MemoryEntry): Promise<void> {
+    await this.agentdb.store(entry);
+    await this.indexer.index(entry);
+  }
+
+  async query(query: MemoryQuery): Promise<MemoryEntry[]> {
+    if (query.semantic) {
+      return this.indexer.search(query); // 150x-12,500x faster
+    }
+    return this.agentdb.query(query);
+  }
+}
+```
+
+### HNSW Vector Search
+```typescript
+class HNSWIndexer {
+  constructor(dimensions: number = 1536) {
+    this.index = new HNSWIndex({
+      dimensions,
+      efConstruction: 200,
+      M: 16,
+      speedupTarget: '150x-12500x'
+    });
+  }
+
+  async search(query: MemoryQuery): Promise<MemoryEntry[]> {
+    const embedding = await this.embedContent(query.content);
+    const results = this.index.search(embedding, query.limit || 10);
+    return this.retrieveEntries(results);
+  }
+}
+```
+
+## Migration Strategy
+
+### Phase 1: Foundation
+```typescript
+// AgentDB adapter setup
+const agentdb = new AgentDBAdapter({
+  dimensions: 1536,
+  indexType: 'HNSW',
+  speedupTarget: '150x-12500x'
+});
+```
+
+### Phase 2: Data Migration
+```typescript
+// SQLite → AgentDB
+const migrateFromSQLite = async () => {
+  const entries = await sqlite.getAll();
+  for (const entry of entries) {
+    const embedding = await generateEmbedding(entry.content);
+    await agentdb.store({ ...entry, embedding });
+  }
+};
+
+// Markdown → AgentDB
+const migrateFromMarkdown = async () => {
+  const files = await glob('**/*.md');
+  for (const file of files) {
+    const content = await fs.readFile(file, 'utf-8');
+    await agentdb.store({
+      id: generateId(),
+      content,
+      embedding: await generateEmbedding(content),
+      metadata: { originalFile: file }
+    });
+  }
+};
+```
+
+## SONA Integration
+
+### Learning Pattern Storage
+```typescript
+class SONAMemoryIntegration {
+  async storePattern(pattern: LearningPattern): Promise<void> {
+    await this.memory.store({
+      id: pattern.id,
+      content: pattern.data,
+      metadata: {
+        sonaMode: pattern.mode,
+        reward: pattern.reward,
+        adaptationTime: pattern.adaptationTime
+      },
+      embedding: await this.generateEmbedding(pattern.data)
+    });
+  }
+
+  async retrieveSimilarPatterns(query: string): Promise<LearningPattern[]> {
+    return this.memory.query({
+      type: 'semantic',
+      content: query,
+      filters: { type: 'learning_pattern' }
+    });
+  }
+}
+```
+
+## Performance Targets
+
+- **Search Speed**: 150x-12,500x improvement via HNSW
+- **Memory Usage**: 50-75% reduction through optimization
+- **Query Latency**: <100ms for 1M+ entries
+- **Cross-Agent Sharing**: Real-time memory synchronization
+- **SONA Integration**: <0.05ms adaptation time
+
+## Success Metrics
+
+- [ ] All 7 legacy memory systems migrated to AgentDB
+- [ ] 150x-12,500x search performance validated
+- [ ] 50-75% memory usage reduction achieved
+- [ ] Backward compatibility maintained
+- [ ] SONA learning patterns integrated
+- [ ] Cross-agent memory sharing operational
@@ -0,0 +1,390 @@
+---
+name: "V3 Performance Optimization"
+description: "Achieve aggressive v3 performance targets: 2.49x-7.47x Flash Attention speedup, 150x-12,500x search improvements, 50-75% memory reduction. Comprehensive benchmarking and optimization suite."
+---
+
+# V3 Performance Optimization
+
+## What This Skill Does
+
+Validates and optimizes claude-flow v3 to achieve industry-leading performance through Flash Attention, AgentDB HNSW indexing, and comprehensive system optimization with continuous benchmarking.
+
+## Quick Start
+
+```bash
+# Initialize performance optimization
+Task("Performance baseline", "Establish v2 performance benchmarks", "v3-performance-engineer")
+
+# Target validation (parallel)
+Task("Flash Attention", "Validate 2.49x-7.47x speedup target", "v3-performance-engineer")
+Task("Search optimization", "Validate 150x-12,500x search improvement", "v3-performance-engineer")
+Task("Memory optimization", "Achieve 50-75% memory reduction", "v3-performance-engineer")
+```
+
+## Performance Target Matrix
+
+### Flash Attention Revolution
+```
+┌─────────────────────────────────────────┐
+│           FLASH ATTENTION               │
+├─────────────────────────────────────────┤
+│  Baseline: Standard attention           │
+│  Target:   2.49x - 7.47x speedup       │
+│  Memory:   50-75% reduction             │
+│  Latency:  Sub-millisecond processing   │
+└─────────────────────────────────────────┘
+```
+
+### Search Performance Revolution
+```
+┌─────────────────────────────────────────┐
+│            SEARCH OPTIMIZATION         │
+├─────────────────────────────────────────┤
+│  Current:  O(n) linear search           │
+│  Target:   150x - 12,500x improvement   │
+│  Method:   HNSW indexing                │
+│  Latency:  <100ms for 1M+ entries       │
+└─────────────────────────────────────────┘
+```
+
+## Comprehensive Benchmark Suite
+
+### Startup Performance
+```typescript
+class StartupBenchmarks {
+  async benchmarkColdStart(): Promise<BenchmarkResult> {
+    const startTime = performance.now();
+
+    await this.initializeCLI();
+    await this.initializeMCPServer();
+    await this.spawnTestAgent();
+
+    const totalTime = performance.now() - startTime;
+
+    return {
+      total: totalTime,
+      target: 500, // ms
+      achieved: totalTime < 500
+    };
+  }
+}
+```
+
+### Memory Operation Benchmarks
+```typescript
+class MemoryBenchmarks {
+  async benchmarkVectorSearch(): Promise<SearchBenchmark> {
+    const queries = this.generateTestQueries(10000);
+
+    // Baseline: Current linear search
+    const baselineTime = await this.timeOperation(() =>
+      this.currentMemory.searchAll(queries)
+    );
+
+    // Target: HNSW search
+    const hnswTime = await this.timeOperation(() =>
+      this.agentDBMemory.hnswSearchAll(queries)
+    );
+
+    const improvement = baselineTime / hnswTime;
+
+    return {
+      baseline: baselineTime,
+      hnsw: hnswTime,
+      improvement,
+      targetRange: [150, 12500],
+      achieved: improvement >= 150
+    };
+  }
+
+  async benchmarkMemoryUsage(): Promise<MemoryBenchmark> {
+    const baseline = process.memoryUsage().heapUsed;
+
+    await this.loadTestDataset();
+    const withData = process.memoryUsage().heapUsed;
+
+    await this.enableOptimization();
+    const optimized = process.memoryUsage().heapUsed;
+
+    const reduction = (withData - optimized) / withData;
+
+    return {
+      baseline,
+      withData,
+      optimized,
+      reductionPercent: reduction * 100,
+      targetReduction: [50, 75],
+      achieved: reduction >= 0.5
+    };
+  }
+}
+```
+
+### Swarm Coordination Benchmarks
+```typescript
+class SwarmBenchmarks {
+  async benchmark15AgentCoordination(): Promise<SwarmBenchmark> {
+    const agents = await this.spawn15Agents();
+
+    // Coordination latency
+    const coordinationTime = await this.timeOperation(() =>
+      this.coordinateSwarmTask(agents)
+    );
+
+    // Task decomposition
+    const decompositionTime = await this.timeOperation(() =>
+      this.decomposeComplexTask()
+    );
+
+    // Consensus achievement
+    const consensusTime = await this.timeOperation(() =>
+      this.achieveSwarmConsensus(agents)
+    );
+
+    return {
+      coordination: coordinationTime,
+      decomposition: decompositionTime,
+      consensus: consensusTime,
+      agentCount: 15,
+      efficiency: this.calculateEfficiency(agents)
+    };
+  }
+}
+```
+
+### Flash Attention Benchmarks
+```typescript
+class AttentionBenchmarks {
+  async benchmarkFlashAttention(): Promise<AttentionBenchmark> {
+    const sequences = this.generateSequences([512, 1024, 2048, 4096]);
+    const results = [];
+
+    for (const sequence of sequences) {
+      // Baseline attention
+      const baselineResult = await this.benchmarkStandardAttention(sequence);
+
+      // Flash attention
+      const flashResult = await this.benchmarkFlashAttention(sequence);
+
+      results.push({
+        sequenceLength: sequence.length,
+        speedup: baselineResult.time / flashResult.time,
+        memoryReduction: (baselineResult.memory - flashResult.memory) / baselineResult.memory,
+        targetSpeedup: [2.49, 7.47],
+        achieved: this.checkTarget(flashResult, [2.49, 7.47])
+      });
+    }
+
+    return {
+      results,
+      averageSpeedup: this.calculateAverage(results, 'speedup'),
+      averageMemoryReduction: this.calculateAverage(results, 'memoryReduction')
+    };
+  }
+}
+```
+
+### SONA Learning Benchmarks
+```typescript
+class SONABenchmarks {
+  async benchmarkAdaptationTime(): Promise<SONABenchmark> {
+    const scenarios = [
+      'pattern_recognition',
+      'task_optimization',
+      'error_correction',
+      'performance_tuning'
+    ];
+
+    const results = [];
+
+    for (const scenario of scenarios) {
+      const startTime = performance.hrtime.bigint();
+      await this.sona.adapt(scenario);
+      const endTime = performance.hrtime.bigint();
+
+      const adaptationTimeMs = Number(endTime - startTime) / 1000000;
+
+      results.push({
+        scenario,
+        adaptationTime: adaptationTimeMs,
+        target: 0.05, // ms
+        achieved: adaptationTimeMs <= 0.05
+      });
+    }
+
+    return {
+      scenarios: results,
+      averageTime: results.reduce((sum, r) => sum + r.adaptationTime, 0) / results.length,
+      successRate: results.filter(r => r.achieved).length / results.length
+    };
+  }
+}
+```
+
+## Performance Monitoring Dashboard
+
+### Real-time Metrics
+```typescript
+class PerformanceMonitor {
+  async collectMetrics(): Promise<PerformanceSnapshot> {
+    return {
+      timestamp: Date.now(),
+      flashAttention: await this.measureFlashAttention(),
+      searchPerformance: await this.measureSearchSpeed(),
+      memoryUsage: await this.measureMemoryEfficiency(),
+      startupTime: await this.measureStartupLatency(),
+      sonaAdaptation: await this.measureSONASpeed(),
+      swarmCoordination: await this.measureSwarmEfficiency()
+    };
+  }
+
+  async generateReport(): Promise<PerformanceReport> {
+    const snapshot = await this.collectMetrics();
+
+    return {
+      summary: this.generateSummary(snapshot),
+      achievements: this.checkTargetAchievements(snapshot),
+      trends: this.analyzeTrends(),
+      recommendations: this.generateOptimizations(),
+      regressions: await this.detectRegressions()
+    };
+  }
+}
+```
+
+### Continuous Regression Detection
+```typescript
+class PerformanceRegression {
+  async detectRegressions(): Promise<RegressionReport> {
+    const current = await this.runFullBenchmark();
+    const baseline = await this.getBaseline();
+
+    const regressions = [];
+
+    for (const [metric, currentValue] of Object.entries(current)) {
+      const baselineValue = baseline[metric];
+      const change = (currentValue - baselineValue) / baselineValue;
+
+      if (change < -0.05) { // 5% regression threshold
+        regressions.push({
+          metric,
+          baseline: baselineValue,
+          current: currentValue,
+          regressionPercent: change * 100,
+          severity: this.classifyRegression(change)
+        });
+      }
+    }
+
+    return {
+      hasRegressions: regressions.length > 0,
+      regressions,
+      recommendations: this.generateRegressionFixes(regressions)
+    };
+  }
+}
+```
+
+## Optimization Strategies
+
+### Memory Optimization
+```typescript
+class MemoryOptimization {
+  async optimizeMemoryUsage(): Promise<OptimizationResult> {
+    // Implement memory pooling
+    await this.setupMemoryPools();
+
+    // Enable garbage collection tuning
+    await this.optimizeGarbageCollection();
+
+    // Implement object reuse patterns
+    await this.setupObjectPools();
+
+    // Enable memory compression
+    await this.enableMemoryCompression();
+
+    return this.validateMemoryReduction();
+  }
+}
+```
+
+### CPU Optimization
+```typescript
+class CPUOptimization {
+  async optimizeCPUUsage(): Promise<OptimizationResult> {
+    // Implement worker thread pools
+    await this.setupWorkerThreads();
+
+    // Enable CPU-specific optimizations
+    await this.enableSIMDInstructions();
+
+    // Implement task batching
+    await this.optimizeTaskBatching();
+
+    return this.validateCPUImprovement();
+  }
+}
+```
+
+## Target Validation Framework
+
+### Performance Gates
+```typescript
+class PerformanceGates {
+  async validateAllTargets(): Promise<ValidationReport> {
+    const results = await Promise.all([
+      this.validateFlashAttention(),     // 2.49x-7.47x
+      this.validateSearchPerformance(),  // 150x-12,500x
+      this.validateMemoryReduction(),    // 50-75%
+      this.validateStartupTime(),        // <500ms
+      this.validateSONAAdaptation()      // <0.05ms
+    ]);
+
+    return {
+      allTargetsAchieved: results.every(r => r.achieved),
+      results,
+      overallScore: this.calculateOverallScore(results),
+      recommendations: this.generateRecommendations(results)
+    };
+  }
+}
+```
+
+## Success Metrics
+
+### Primary Targets
+- [ ] **Flash Attention**: 2.49x-7.47x speedup validated
+- [ ] **Search Performance**: 150x-12,500x improvement confirmed
+- [ ] **Memory Reduction**: 50-75% usage optimization achieved
+- [ ] **Startup Time**: <500ms cold start consistently
+- [ ] **SONA Adaptation**: <0.05ms learning response time
+- [ ] **15-Agent Coordination**: Efficient parallel execution
+
+### Continuous Monitoring
+- [ ] **Performance Dashboard**: Real-time metrics collection
+- [ ] **Regression Testing**: Automated performance validation
+- [ ] **Trend Analysis**: Performance evolution tracking
+- [ ] **Alert System**: Immediate regression notification
+
+## Related V3 Skills
+
+- `v3-integration-deep` - Performance integration with agentic-flow
+- `v3-memory-unification` - Memory performance optimization
+- `v3-swarm-coordination` - Swarm performance coordination
+- `v3-security-overhaul` - Secure performance patterns
+
+## Usage Examples
+
+### Complete Performance Validation
+```bash
+# Full performance suite
+npm run benchmark:v3
+
+# Specific target validation
+npm run benchmark:flash-attention
+npm run benchmark:agentdb-search
+npm run benchmark:memory-optimization
+
+# Continuous monitoring
+npm run monitor:performance
+```
@@ -0,0 +1,82 @@
+---
+name: "V3 Security Overhaul"
+description: "Complete security architecture overhaul for claude-flow v3. Addresses critical CVEs (CVE-1, CVE-2, CVE-3) and implements secure-by-default patterns. Use for security-first v3 implementation."
+---
+
+# V3 Security Overhaul
+
+## What This Skill Does
+
+Orchestrates comprehensive security overhaul for claude-flow v3, addressing critical vulnerabilities and establishing security-first development practices using specialized v3 security agents.
+
+## Quick Start
+
+```bash
+# Initialize V3 security domain (parallel)
+Task("Security architecture", "Design v3 threat model and security boundaries", "v3-security-architect")
+Task("CVE remediation", "Fix CVE-1, CVE-2, CVE-3 critical vulnerabilities", "security-auditor")
+Task("Security testing", "Implement TDD London School security framework", "test-architect")
+```
+
+## Critical Security Fixes
+
+### CVE-1: Vulnerable Dependencies
+```bash
+npm update @anthropic-ai/claude-code@^2.0.31
+npm audit --audit-level high
+```
+
+### CVE-2: Weak Password Hashing
+```typescript
+// ❌ Old: SHA-256 with hardcoded salt
+const hash = crypto.createHash('sha256').update(password + salt).digest('hex');
+
+// ✅ New: bcrypt with 12 rounds
+import bcrypt from 'bcrypt';
+const hash = await bcrypt.hash(password, 12);
+```
+
+### CVE-3: Hardcoded Credentials
+```typescript
+// ✅ Generate secure random credentials
+const apiKey = crypto.randomBytes(32).toString('hex');
+```
+
+## Security Patterns
+
+### Input Validation (Zod)
+```typescript
+import { z } from 'zod';
+
+const TaskSchema = z.object({
+  taskId: z.string().uuid(),
+  content: z.string().max(10000),
+  agentType: z.enum(['security', 'core', 'integration'])
+});
+```
+
+### Path Sanitization
+```typescript
+function securePath(userPath: string, allowedPrefix: string): string {
+  const resolved = path.resolve(allowedPrefix, userPath);
+  if (!resolved.startsWith(path.resolve(allowedPrefix))) {
+    throw new SecurityError('Path traversal detected');
+  }
+  return resolved;
+}
+```
+
+### Safe Command Execution
+```typescript
+import { execFile } from 'child_process';
+
+// ✅ Safe: No shell interpretation
+const { stdout } = await execFile('git', [userInput], { shell: false });
+```
+
+## Success Metrics
+
+- **Security Score**: 90/100 (npm audit + custom scans)
+- **CVE Resolution**: 100% of critical vulnerabilities fixed
+- **Test Coverage**: >95% security-critical code
+- **Implementation**: All secure patterns documented and tested
@@ -0,0 +1,340 @@
+---
+name: "V3 Swarm Coordination"
+description: "15-agent hierarchical mesh coordination for v3 implementation. Orchestrates parallel execution across security, core, and integration domains following 10 ADRs with 14-week timeline."
+---
+
+# V3 Swarm Coordination
+
+## What This Skill Does
+
+Orchestrates the complete 15-agent hierarchical mesh swarm for claude-flow v3 implementation, coordinating parallel execution across domains while maintaining dependencies and timeline adherence.
+
+## Quick Start
+
+```bash
+# Initialize 15-agent v3 swarm
+Task("Swarm initialization", "Initialize hierarchical mesh for v3 implementation", "v3-queen-coordinator")
+
+# Security domain (Phase 1 - Critical priority)
+Task("Security architecture", "Design v3 threat model and security boundaries", "v3-security-architect")
+Task("CVE remediation", "Fix CVE-1, CVE-2, CVE-3 vulnerabilities", "security-auditor")
+Task("Security testing", "Implement TDD security framework", "test-architect")
+
+# Core domain (Phase 2 - Parallel execution)
+Task("Memory unification", "Implement AgentDB 150x improvement", "v3-memory-specialist")
+Task("Integration architecture", "Deep agentic-flow@alpha integration", "v3-integration-architect")
+Task("Performance validation", "Validate 2.49x-7.47x targets", "v3-performance-engineer")
+```
+
+## 15-Agent Swarm Architecture
+
+### Hierarchical Mesh Topology
+```
+                    👑 QUEEN COORDINATOR
+                         (Agent #1)
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                   │                    │
+   🛡️ SECURITY         🧠 CORE              🔗 INTEGRATION
+   (Agents #2-4)       (Agents #5-9)        (Agents #10-12)
+        │                   │                    │
+        └────────────────────┼────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                   │                    │
+   🧪 QUALITY          ⚡ PERFORMANCE        🚀 DEPLOYMENT
+   (Agent #13)         (Agent #14)          (Agent #15)
+```
+
+### Agent Roster
+| ID | Agent | Domain | Phase | Responsibility |
+|----|-------|--------|-------|----------------|
+| 1 | Queen Coordinator | Orchestration | All | GitHub issues, dependencies, timeline |
+| 2 | Security Architect | Security | Foundation | Threat modeling, CVE planning |
+| 3 | Security Implementer | Security | Foundation | CVE fixes, secure patterns |
+| 4 | Security Tester | Security | Foundation | TDD security testing |
+| 5 | Core Architect | Core | Systems | DDD architecture, coordination |
+| 6 | Core Implementer | Core | Systems | Core module implementation |
+| 7 | Memory Specialist | Core | Systems | AgentDB unification |
+| 8 | Swarm Specialist | Core | Systems | Unified coordination engine |
+| 9 | MCP Specialist | Core | Systems | MCP server optimization |
+| 10 | Integration Architect | Integration | Integration | agentic-flow@alpha deep integration |
+| 11 | CLI/Hooks Developer | Integration | Integration | CLI modernization |
+| 12 | Neural/Learning Dev | Integration | Integration | SONA integration |
+| 13 | TDD Test Engineer | Quality | All | London School TDD |
+| 14 | Performance Engineer | Performance | Optimization | Benchmarking validation |
+| 15 | Release Engineer | Deployment | Release | CI/CD and v3.0.0 release |
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1-2)
+**Active Agents**: #1, #2-4, #5-6
+```typescript
+const phase1 = async () => {
+  // Parallel security and architecture foundation
+  await Promise.all([
+    // Security domain (critical priority)
+    Task("Security architecture", "Complete threat model and security boundaries", "v3-security-architect"),
+    Task("CVE-1 fix", "Update vulnerable dependencies", "security-implementer"),
+    Task("CVE-2 fix", "Replace weak password hashing", "security-implementer"),
+    Task("CVE-3 fix", "Remove hardcoded credentials", "security-implementer"),
+    Task("Security testing", "TDD London School security framework", "test-architect"),
+
+    // Core architecture foundation
+    Task("DDD architecture", "Design domain boundaries and structure", "core-architect"),
+    Task("Type modernization", "Update type system for v3", "core-implementer")
+  ]);
+};
+```
+
+### Phase 2: Core Systems (Week 3-6)
+**Active Agents**: #1, #5-9, #13
+```typescript
+const phase2 = async () => {
+  // Parallel core system implementation
+  await Promise.all([
+    Task("Memory unification", "Implement AgentDB with 150x-12,500x improvement", "v3-memory-specialist"),
+    Task("Swarm coordination", "Merge 4 coordination systems into unified engine", "swarm-specialist"),
+    Task("MCP optimization", "Optimize MCP server performance", "mcp-specialist"),
+    Task("Core implementation", "Implement DDD modular architecture", "core-implementer"),
+    Task("TDD core tests", "Comprehensive test coverage for core systems", "test-architect")
+  ]);
+};
+```
+
+### Phase 3: Integration (Week 7-10)
+**Active Agents**: #1, #10-12, #13-14
+```typescript
+const phase3 = async () => {
+  // Parallel integration and optimization
+  await Promise.all([
+    Task("agentic-flow integration", "Eliminate 10,000+ duplicate lines", "v3-integration-architect"),
+    Task("CLI modernization", "Enhance CLI with hooks system", "cli-hooks-developer"),
+    Task("SONA integration", "Implement <0.05ms learning adaptation", "neural-learning-developer"),
+    Task("Performance benchmarking", "Validate 2.49x-7.47x targets", "v3-performance-engineer"),
+    Task("Integration testing", "End-to-end system validation", "test-architect")
+  ]);
+};
+```
+
+### Phase 4: Release (Week 11-14)
+**Active Agents**: All 15
+```typescript
+const phase4 = async () => {
+  // Full swarm final optimization
+  await Promise.all([
+    Task("Performance optimization", "Final optimization pass", "v3-performance-engineer"),
+    Task("Release preparation", "CI/CD pipeline and v3.0.0 release", "release-engineer"),
+    Task("Final testing", "Complete test coverage validation", "test-architect"),
+
+    // All agents: Final polish and optimization
+    ...agents.map(agent =>
+      Task("Final polish", `Agent ${agent.id} final optimization`, agent.name)
+    )
+  ]);
+};
+```
+
+## Coordination Patterns
+
+### Dependency Management
+```typescript
+class DependencyCoordination {
+  private dependencies = new Map([
+    // Security first (no dependencies)
+    [2, []], [3, [2]], [4, [2, 3]],
+
+    // Core depends on security foundation
+    [5, [2]], [6, [5]], [7, [5]], [8, [5, 7]], [9, [5]],
+
+    // Integration depends on core systems
+    [10, [5, 7, 8]], [11, [5, 10]], [12, [7, 10]],
+
+    // Quality and performance cross-cutting
+    [13, [2, 5]], [14, [5, 7, 8, 10]], [15, [13, 14]]
+  ]);
+
+  async coordinateExecution(): Promise<void> {
+    const completed = new Set<number>();
+
+    while (completed.size < 15) {
+      const ready = this.getReadyAgents(completed);
+
+      if (ready.length === 0) {
+        throw new Error('Deadlock detected in dependency chain');
+      }
+
+      // Execute ready agents in parallel
+      await Promise.all(ready.map(agentId => this.executeAgent(agentId)));
+
+      ready.forEach(id => completed.add(id));
+    }
+  }
+}
+```
+
+### GitHub Integration
+```typescript
+class GitHubCoordination {
+  async initializeV3Milestone(): Promise<void> {
+    await gh.createMilestone({
+      title: 'Claude-Flow v3.0.0 Implementation',
+      description: '15-agent swarm implementation of 10 ADRs',
+      dueDate: this.calculate14WeekDeadline()
+    });
+  }
+
+  async createEpicIssues(): Promise<void> {
+    const epics = [
+      { title: 'Security Overhaul (CVE-1,2,3)', agents: [2, 3, 4] },
+      { title: 'Memory Unification (AgentDB)', agents: [7] },
+      { title: 'agentic-flow Integration', agents: [10] },
+      { title: 'Performance Optimization', agents: [14] },
+      { title: 'DDD Architecture', agents: [5, 6] }
+    ];
+
+    for (const epic of epics) {
+      await gh.createIssue({
+        title: epic.title,
+        labels: ['epic', 'v3', ...epic.agents.map(id => `agent-${id}`)],
+        assignees: epic.agents.map(id => this.getAgentGithubUser(id))
+      });
+    }
+  }
+
+  async trackProgress(): Promise<void> {
+    // Hourly progress updates from each agent
+    setInterval(async () => {
+      for (const agent of this.agents) {
+        await this.postAgentProgress(agent);
+      }
+    }, 3600000); // 1 hour
+  }
+}
+```
+
+### Communication Bus
+```typescript
+class SwarmCommunication {
+  private bus = new QuicSwarmBus({
+    maxAgents: 15,
+    messageTimeout: 30000,
+    retryAttempts: 3
+  });
+
+  async broadcastToSecurityDomain(message: SwarmMessage): Promise<void> {
+    await this.bus.broadcast(message, {
+      targetAgents: [2, 3, 4],
+      priority: 'critical'
+    });
+  }
+
+  async coordinateCoreSystems(message: SwarmMessage): Promise<void> {
+    await this.bus.broadcast(message, {
+      targetAgents: [5, 6, 7, 8, 9],
+      priority: 'high'
+    });
+  }
+
+  async notifyIntegrationTeam(message: SwarmMessage): Promise<void> {
+    await this.bus.broadcast(message, {
+      targetAgents: [10, 11, 12],
+      priority: 'medium'
+    });
+  }
+}
+```
+
+## Performance Coordination
+
+### Parallel Efficiency Monitoring
+```typescript
+class EfficiencyMonitor {
+  async measureParallelEfficiency(): Promise<EfficiencyReport> {
+    const agentUtilization = await this.measureAgentUtilization();
+    const coordinationOverhead = await this.measureCoordinationCost();
+
+    return {
+      totalEfficiency: agentUtilization.average,
+      target: 0.85, // >85% utilization
+      achieved: agentUtilization.average > 0.85,
+      bottlenecks: this.identifyBottlenecks(agentUtilization),
+      recommendations: this.generateOptimizations()
+    };
+  }
+}
+```
+
+### Load Balancing
+```typescript
+class SwarmLoadBalancer {
+  async balanceWorkload(): Promise<void> {
+    const workloads = await this.analyzeAgentWorkloads();
+
+    for (const [agentId, load] of workloads.entries()) {
+      if (load > this.getCapacityThreshold(agentId)) {
+        await this.redistributeWork(agentId);
+      }
+    }
+  }
+
+  async redistributeWork(overloadedAgent: number): Promise<void> {
+    const availableAgents = this.getAvailableAgents();
+    const tasks = await this.getAgentTasks(overloadedAgent);
+
+    // Redistribute tasks to available agents
+    for (const task of tasks) {
+      const bestAgent = this.selectOptimalAgent(task, availableAgents);
+      await this.reassignTask(task, bestAgent);
+    }
+  }
+}
+```
+
+## Success Metrics
+
+### Swarm Coordination
+- [ ] **Parallel Efficiency**: >85% agent utilization time
+- [ ] **Dependency Resolution**: Zero deadlocks or blocking issues
+- [ ] **Communication Latency**: <100ms inter-agent messaging
+- [ ] **Timeline Adherence**: 14-week delivery maintained
+- [ ] **GitHub Integration**: <4h automated issue response
+
+### Implementation Targets
+- [ ] **ADR Coverage**: All 10 ADRs implemented successfully
+- [ ] **Performance**: 2.49x-7.47x Flash Attention achieved
+- [ ] **Search**: 150x-12,500x AgentDB improvement validated
+- [ ] **Code Reduction**: <5,000 lines (vs 15,000+)
+- [ ] **Security**: 90/100 security score achieved
+
+## Related V3 Skills
+
+- `v3-security-overhaul` - Security domain coordination
+- `v3-memory-unification` - Memory system coordination
+- `v3-integration-deep` - Integration domain coordination
+- `v3-performance-optimization` - Performance domain coordination
+
+## Usage Examples
+
+### Initialize Complete V3 Swarm
+```bash
+# Queen Coordinator initializes full swarm
+Task("V3 swarm initialization",
+     "Initialize 15-agent hierarchical mesh for complete v3 implementation",
+     "v3-queen-coordinator")
+```
+
+### Phase-based Execution
+```bash
+# Phase 1: Security-first foundation
+npm run v3:phase1:security
+
+# Phase 2: Core systems parallel
+npm run v3:phase2:core-systems
+
+# Phase 3: Integration and optimization
+npm run v3:phase3:integration
+
+# Phase 4: Release preparation
+npm run v3:phase4:release
+```
@@ -0,0 +1,649 @@
+---
+name: "Verification & Quality Assurance"
+description: "Comprehensive truth scoring, code quality verification, and automatic rollback system with 0.95 accuracy threshold for ensuring high-quality agent outputs and codebase reliability."
+version: "2.0.0"
+category: "quality-assurance"
+tags: ["verification", "truth-scoring", "quality", "rollback", "metrics", "ci-cd"]
+---
+
+# Verification & Quality Assurance Skill
+
+## What This Skill Does
+
+This skill provides a comprehensive verification and quality assurance system that ensures code quality and correctness through:
+
+- **Truth Scoring**: Real-time reliability metrics (0.0-1.0 scale) for code, agents, and tasks
+- **Verification Checks**: Automated code correctness, security, and best practices validation
+- **Automatic Rollback**: Instant reversion of changes that fail verification (default threshold: 0.95)
+- **Quality Metrics**: Statistical analysis with trends, confidence intervals, and improvement tracking
+- **CI/CD Integration**: Export capabilities for continuous integration pipelines
+- **Real-time Monitoring**: Live dashboards and watch modes for ongoing verification
+
+## Prerequisites
+
+- Claude Flow installed (`npx claude-flow@alpha`)
+- Git repository (for rollback features)
+- Node.js 18+ (for dashboard features)
+
+## Quick Start
+
+```bash
+# View current truth scores
+npx claude-flow@alpha truth
+
+# Run verification check
+npx claude-flow@alpha verify check
+
+# Verify specific file with custom threshold
+npx claude-flow@alpha verify check --file src/app.js --threshold 0.98
+
+# Rollback last failed verification
+npx claude-flow@alpha verify rollback --last-good
+```
+
+---
+
+## Complete Guide
+
+### Truth Scoring System
+
+#### View Truth Metrics
+
+Display comprehensive quality and reliability metrics for your codebase and agent tasks.
+
+**Basic Usage:**
+```bash
+# View current truth scores (default: table format)
+npx claude-flow@alpha truth
+
+# View scores for specific time period
+npx claude-flow@alpha truth --period 7d
+
+# View scores for specific agent
+npx claude-flow@alpha truth --agent coder --period 24h
+
+# Find files/tasks below threshold
+npx claude-flow@alpha truth --threshold 0.8
+```
+
+**Output Formats:**
+```bash
+# Table format (default)
+npx claude-flow@alpha truth --format table
+
+# JSON for programmatic access
+npx claude-flow@alpha truth --format json
+
+# CSV for spreadsheet analysis
+npx claude-flow@alpha truth --format csv
+
+# HTML report with visualizations
+npx claude-flow@alpha truth --format html --export report.html
+```
+
+**Real-time Monitoring:**
+```bash
+# Watch mode with live updates
+npx claude-flow@alpha truth --watch
+
+# Export metrics automatically
+npx claude-flow@alpha truth --export .claude-flow/metrics/truth-$(date +%Y%m%d).json
+```
+
+#### Truth Score Dashboard
+
+Example dashboard output:
+```
+📊 Truth Metrics Dashboard
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall Truth Score: 0.947 ✅
+Trend: ↗️ +2.3% (7d)
+
+Top Performers:
+  verification-agent   0.982 ⭐
+  code-analyzer       0.971 ⭐
+  test-generator      0.958 ✅
+
+Needs Attention:
+  refactor-agent      0.821 ⚠️
+  docs-generator      0.794 ⚠️
+
+Recent Tasks:
+  task-456  0.991 ✅  "Implement auth"
+  task-455  0.967 ✅  "Add tests"
+  task-454  0.743 ❌  "Refactor API"
+```
+
+#### Metrics Explained
+
+**Truth Scores (0.0-1.0):**
+- `1.0-0.95`: Excellent ⭐ (production-ready)
+- `0.94-0.85`: Good ✅ (acceptable quality)
+- `0.84-0.75`: Warning ⚠️ (needs attention)
+- `<0.75`: Critical ❌ (requires immediate action)
+
+**Trend Indicators:**
+- ↗️ Improving (positive trend)
+- → Stable (consistent performance)
+- ↘️ Declining (quality regression detected)
+
+**Statistics:**
+- **Mean Score**: Average truth score across all measurements
+- **Median Score**: Middle value (less affected by outliers)
+- **Standard Deviation**: Consistency of scores (lower = more consistent)
+- **Confidence Interval**: Statistical reliability of measurements
+
+### Verification Checks
+
+#### Run Verification
+
+Execute comprehensive verification checks on code, tasks, or agent outputs.
+
+**File Verification:**
+```bash
+# Verify single file
+npx claude-flow@alpha verify check --file src/app.js
+
+# Verify directory recursively
+npx claude-flow@alpha verify check --directory src/
+
+# Verify with auto-fix enabled
+npx claude-flow@alpha verify check --file src/utils.js --auto-fix
+
+# Verify current working directory
+npx claude-flow@alpha verify check
+```
+
+**Task Verification:**
+```bash
+# Verify specific task output
+npx claude-flow@alpha verify check --task task-123
+
+# Verify with custom threshold
+npx claude-flow@alpha verify check --task task-456 --threshold 0.99
+
+# Verbose output for debugging
+npx claude-flow@alpha verify check --task task-789 --verbose
+```
+
+**Batch Verification:**
+```bash
+# Verify multiple files in parallel
+npx claude-flow@alpha verify batch --files "*.js" --parallel
+
+# Verify with pattern matching
+npx claude-flow@alpha verify batch --pattern "src/**/*.ts"
+
+# Integration test suite
+npx claude-flow@alpha verify integration --test-suite full
+```
+
+#### Verification Criteria
+
+The verification system evaluates:
+
+1. **Code Correctness**
+   - Syntax validation
+   - Type checking (TypeScript)
+   - Logic flow analysis
+   - Error handling completeness
+
+2. **Best Practices**
+   - Code style adherence
+   - SOLID principles
+   - Design patterns usage
+   - Modularity and reusability
+
+3. **Security**
+   - Vulnerability scanning
+   - Secret detection
+   - Input validation
+   - Authentication/authorization checks
+
+4. **Performance**
+   - Algorithmic complexity
+   - Memory usage patterns
+   - Database query optimization
+   - Bundle size impact
+
+5. **Documentation**
+   - JSDoc/TypeDoc completeness
+   - README accuracy
+   - API documentation
+   - Code comments quality
+
+#### JSON Output for CI/CD
+
+```bash
+# Get structured JSON output
+npx claude-flow@alpha verify check --json > verification.json
+
+# Example JSON structure:
+{
+  "overallScore": 0.947,
+  "passed": true,
+  "threshold": 0.95,
+  "checks": [
+    {
+      "name": "code-correctness",
+      "score": 0.98,
+      "passed": true
+    },
+    {
+      "name": "security",
+      "score": 0.91,
+      "passed": false,
+      "issues": [...]
+    }
+  ]
+}
+```
+
+### Automatic Rollback
+
+#### Rollback Failed Changes
+
+Automatically revert changes that fail verification checks.
+
+**Basic Rollback:**
+```bash
+# Rollback to last known good state
+npx claude-flow@alpha verify rollback --last-good
+
+# Rollback to specific commit
+npx claude-flow@alpha verify rollback --to-commit abc123
+
+# Interactive rollback with preview
+npx claude-flow@alpha verify rollback --interactive
+```
+
+**Smart Rollback:**
+```bash
+# Rollback only failed files (preserve good changes)
+npx claude-flow@alpha verify rollback --selective
+
+# Rollback with automatic backup
+npx claude-flow@alpha verify rollback --backup-first
+
+# Dry-run mode (preview without executing)
+npx claude-flow@alpha verify rollback --dry-run
+```
+
+**Rollback Performance:**
+- Git-based rollback: <1 second
+- Selective file rollback: <500ms
+- Backup creation: Automatic before rollback
+
+### Verification Reports
+
+#### Generate Reports
+
+Create detailed verification reports with metrics and visualizations.
+
+**Report Formats:**
+```bash
+# JSON report
+npx claude-flow@alpha verify report --format json
+
+# HTML report with charts
+npx claude-flow@alpha verify report --export metrics.html --format html
+
+# CSV for data analysis
+npx claude-flow@alpha verify report --format csv --export metrics.csv
+
+# Markdown summary
+npx claude-flow@alpha verify report --format markdown
+```
+
+**Time-based Reports:**
+```bash
+# Last 24 hours
+npx claude-flow@alpha verify report --period 24h
+
+# Last 7 days
+npx claude-flow@alpha verify report --period 7d
+
+# Last 30 days with trends
+npx claude-flow@alpha verify report --period 30d --include-trends
+
+# Custom date range
+npx claude-flow@alpha verify report --from 2025-01-01 --to 2025-01-31
+```
+
+**Report Content:**
+- Overall truth scores
+- Per-agent performance metrics
+- Task completion quality
+- Verification pass/fail rates
+- Rollback frequency
+- Quality improvement trends
+- Statistical confidence intervals
+
+### Interactive Dashboard
+
+#### Launch Dashboard
+
+Run interactive web-based verification dashboard with real-time updates.
+
+```bash
+# Launch dashboard on default port (3000)
+npx claude-flow@alpha verify dashboard
+
+# Custom port
+npx claude-flow@alpha verify dashboard --port 8080
+
+# Export dashboard data
+npx claude-flow@alpha verify dashboard --export
+
+# Dashboard with auto-refresh
+npx claude-flow@alpha verify dashboard --refresh 5s
+```
+
+**Dashboard Features:**
+- Real-time truth score updates (WebSocket)
+- Interactive charts and graphs
+- Agent performance comparison
+- Task history timeline
+- Rollback history viewer
+- Export to PDF/HTML
+- Filter by time period/agent/score
+
+### Configuration
+
+#### Default Configuration
+
+Set verification preferences in `.claude-flow/config.json`:
+
+```json
+{
+  "verification": {
+    "threshold": 0.95,
+    "autoRollback": true,
+    "gitIntegration": true,
+    "hooks": {
+      "preCommit": true,
+      "preTask": true,
+      "postEdit": true
+    },
+    "checks": {
+      "codeCorrectness": true,
+      "security": true,
+      "performance": true,
+      "documentation": true,
+      "bestPractices": true
+    }
+  },
+  "truth": {
+    "defaultFormat": "table",
+    "defaultPeriod": "24h",
+    "warningThreshold": 0.85,
+    "criticalThreshold": 0.75,
+    "autoExport": {
+      "enabled": true,
+      "path": ".claude-flow/metrics/truth-daily.json"
+    }
+  }
+}
+```
+
+#### Threshold Configuration
+
+**Adjust verification strictness:**
+```bash
+# Strict mode (99% accuracy required)
+npx claude-flow@alpha verify check --threshold 0.99
+
+# Lenient mode (90% acceptable)
+npx claude-flow@alpha verify check --threshold 0.90
+
+# Set default threshold
+npx claude-flow@alpha config set verification.threshold 0.98
+```
+
+**Per-environment thresholds:**
+```json
+{
+  "verification": {
+    "thresholds": {
+      "production": 0.99,
+      "staging": 0.95,
+      "development": 0.90
+    }
+  }
+}
+```
+
+### Integration Examples
+
+#### CI/CD Integration
+
+**GitHub Actions:**
+```yaml
+name: Quality Verification
+
+on: [push, pull_request]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install Dependencies
+        run: npm install
+
+      - name: Run Verification
+        run: |
+          npx claude-flow@alpha verify check --json > verification.json
+
+      - name: Check Truth Score
+        run: |
+          score=$(jq '.overallScore' verification.json)
+          if (( $(echo "$score < 0.95" | bc -l) )); then
+            echo "Truth score too low: $score"
+            exit 1
+          fi
+
+      - name: Upload Report
+        uses: actions/upload-artifact@v3
+        with:
+          name: verification-report
+          path: verification.json
+```
+
+**GitLab CI:**
+```yaml
+verify:
+  stage: test
+  script:
+    - npx claude-flow@alpha verify check --threshold 0.95 --json > verification.json
+    - |
+      score=$(jq '.overallScore' verification.json)
+      if [ $(echo "$score < 0.95" | bc) -eq 1 ]; then
+        echo "Verification failed with score: $score"
+        exit 1
+      fi
+  artifacts:
+    paths:
+      - verification.json
+    reports:
+      junit: verification.json
+```
+
+#### Swarm Integration
+
+Run verification automatically during swarm operations:
+
+```bash
+# Swarm with verification enabled
+npx claude-flow@alpha swarm --verify --threshold 0.98
+
+# Hive Mind with auto-rollback
+npx claude-flow@alpha hive-mind --verify --rollback-on-fail
+
+# Training pipeline with verification
+npx claude-flow@alpha train --verify --threshold 0.99
+```
+
+#### Pair Programming Integration
+
+Enable real-time verification during collaborative development:
+
+```bash
+# Pair with verification
+npx claude-flow@alpha pair --verify --real-time
+
+# Pair with custom threshold
+npx claude-flow@alpha pair --verify --threshold 0.97 --auto-fix
+```
+
+### Advanced Workflows
+
+#### Continuous Verification
+
+Monitor codebase continuously during development:
+
+```bash
+# Watch directory for changes
+npx claude-flow@alpha verify watch --directory src/
+
+# Watch with auto-fix
+npx claude-flow@alpha verify watch --directory src/ --auto-fix
+
+# Watch with notifications
+npx claude-flow@alpha verify watch --notify --threshold 0.95
+```
+
+#### Monitoring Integration
+
+Send metrics to external monitoring systems:
+
+```bash
+# Export to Prometheus
+npx claude-flow@alpha truth --format json | \
+  curl -X POST https://pushgateway.example.com/metrics/job/claude-flow \
+  -d @-
+
+# Send to DataDog
+npx claude-flow@alpha verify report --format json | \
+  curl -X POST "https://api.datadoghq.com/api/v1/series?api_key=${DD_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d @-
+
+# Custom webhook
+npx claude-flow@alpha truth --format json | \
+  curl -X POST https://metrics.example.com/api/truth \
+  -H "Content-Type: application/json" \
+  -d @-
+```
+
+#### Pre-commit Hooks
+
+Automatically verify before commits:
+
+```bash
+# Install pre-commit hook
+npx claude-flow@alpha verify install-hook --pre-commit
+
+# .git/hooks/pre-commit example:
+#!/bin/bash
+npx claude-flow@alpha verify check --threshold 0.95 --json > /tmp/verify.json
+
+score=$(jq '.overallScore' /tmp/verify.json)
+if (( $(echo "$score < 0.95" | bc -l) )); then
+  echo "❌ Verification failed with score: $score"
+  echo "Run 'npx claude-flow@alpha verify check --verbose' for details"
+  exit 1
+fi
+
+echo "✅ Verification passed with score: $score"
+```
+
+### Performance Metrics
+
+**Verification Speed:**
+- Single file check: <100ms
+- Directory scan: <500ms (per 100 files)
+- Full codebase analysis: <5s (typical project)
+- Truth score calculation: <50ms
+
+**Rollback Speed:**
+- Git-based rollback: <1s
+- Selective file rollback: <500ms
+- Backup creation: <2s
+
+**Dashboard Performance:**
+- Initial load: <1s
+- Real-time updates: <100ms latency (WebSocket)
+- Chart rendering: 60 FPS
+
+### Troubleshooting
+
+#### Common Issues
+
+**Low Truth Scores:**
+```bash
+# Get detailed breakdown
+npx claude-flow@alpha truth --verbose --threshold 0.0
+
+# Check specific criteria
+npx claude-flow@alpha verify check --verbose
+
+# View agent-specific issues
+npx claude-flow@alpha truth --agent <agent-name> --format json
+```
+
+**Rollback Failures:**
+```bash
+# Check git status
+git status
+
+# View rollback history
+npx claude-flow@alpha verify rollback --history
+
+# Manual rollback
+git reset --hard HEAD~1
+```
+
+**Verification Timeouts:**
+```bash
+# Increase timeout
+npx claude-flow@alpha verify check --timeout 60s
+
+# Verify in batches
+npx claude-flow@alpha verify batch --batch-size 10
+```
+
+### Exit Codes
+
+Verification commands return standard exit codes:
+
+- `0`: Verification passed (score ≥ threshold)
+- `1`: Verification failed (score < threshold)
+- `2`: Error during verification (invalid input, system error)
+
+### Related Commands
+
+- `npx claude-flow@alpha pair` - Collaborative development with verification
+- `npx claude-flow@alpha train` - Training with verification feedback
+- `npx claude-flow@alpha swarm` - Multi-agent coordination with quality checks
+- `npx claude-flow@alpha report` - Generate comprehensive project reports
+
+### Best Practices
+
+1. **Set Appropriate Thresholds**: Use 0.99 for critical code, 0.95 for standard, 0.90 for experimental
+2. **Enable Auto-rollback**: Prevent bad code from persisting
+3. **Monitor Trends**: Track improvement over time, not just current scores
+4. **Integrate with CI/CD**: Make verification part of your pipeline
+5. **Use Watch Mode**: Get immediate feedback during development
+6. **Export Metrics**: Track quality metrics in your monitoring system
+7. **Review Rollbacks**: Understand why changes were rejected
+8. **Train Agents**: Use verification feedback to improve agent performance
+
+### Additional Resources
+
+- Truth Scoring Algorithm: See `/docs/truth-scoring.md`
+- Verification Criteria: See `/docs/verification-criteria.md`
+- Integration Examples: See `/examples/verification/`
+- API Reference: See `/docs/api/verification.md`
@@ -0,0 +1,109 @@
+/**
+ * Agentic Flow Statusline for Claude Code
+ * Shows model, tokens, cost, swarm status, and memory usage
+ */
+
+import { execSync } from 'child_process';
+
+// Cache for expensive operations
+let lastSwarmCheck = 0;
+let cachedSwarmStatus = null;
+const CACHE_TTL = 5000; // 5 seconds
+
+/**
+ * Get swarm status (cached)
+ */
+function getSwarmStatus() {
+  const now = Date.now();
+  if (cachedSwarmStatus && (now - lastSwarmCheck) < CACHE_TTL) {
+    return cachedSwarmStatus;
+  }
+
+  try {
+    const result = execSync('npx agentic-flow@alpha mcp status 2>/dev/null || echo "idle"', {
+      encoding: 'utf-8',
+      timeout: 2000
+    }).trim();
+
+    cachedSwarmStatus = result.includes('running') ? '🐝' : '⚡';
+    lastSwarmCheck = now;
+    return cachedSwarmStatus;
+  } catch {
+    cachedSwarmStatus = '⚡';
+    lastSwarmCheck = now;
+    return cachedSwarmStatus;
+  }
+}
+
+/**
+ * Format token count
+ */
+function formatTokens(tokens) {
+  if (tokens >= 1000000) {
+    return `${(tokens / 1000000).toFixed(1)}M`;
+  }
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}K`;
+  }
+  return String(tokens);
+}
+
+/**
+ * Format cost
+ */
+function formatCost(cost) {
+  if (cost >= 1) {
+    return `$${cost.toFixed(2)}`;
+  }
+  return `$${cost.toFixed(4)}`;
+}
+
+/**
+ * Main statusline export
+ */
+export default function statusline(context) {
+  const parts = [];
+
+  // Agentic Flow indicator
+  parts.push('🤖');
+
+  // Model name (shortened)
+  if (context.model) {
+    const model = context.model
+      .replace('claude-', '')
+      .replace('-20250514', '')
+      .replace('sonnet-4', 'S4')
+      .replace('opus-4', 'O4')
+      .replace('haiku-3.5', 'H3.5');
+    parts.push(model);
+  }
+
+  // Token usage
+  if (context.inputTokens !== undefined || context.outputTokens !== undefined) {
+    const input = formatTokens(context.inputTokens || 0);
+    const output = formatTokens(context.outputTokens || 0);
+    parts.push(`↑${input} ↓${output}`);
+  }
+
+  // Cost
+  if (context.totalCost !== undefined && context.totalCost > 0) {
+    parts.push(formatCost(context.totalCost));
+  }
+
+  // Swarm/MCP status indicator
+  parts.push(getSwarmStatus());
+
+  // Session time
+  if (context.sessionStartTime) {
+    const elapsed = Math.floor((Date.now() - context.sessionStartTime) / 1000);
+    const mins = Math.floor(elapsed / 60);
+    const secs = elapsed % 60;
+    if (mins > 0) {
+      parts.push(`${mins}m${secs}s`);
+    } else {
+      parts.push(`${secs}s`);
+    }
+  }
+
+  return parts.join(' │ ');
+}
@@ -0,0 +1,186 @@
+#!/bin/bash
+# Claude Flow V3 Development Status Line
+# Shows DDD architecture progress, security status, and performance targets
+
+V3_METRICS=".claude-flow/metrics/v3-progress.json"
+SECURITY_AUDIT=".claude-flow/security/audit-status.json"
+PERFORMANCE_METRICS=".claude-flow/metrics/performance.json"
+
+# ANSI Color Codes
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+PURPLE='\033[0;35m'
+CYAN='\033[0;36m'
+WHITE='\033[0;37m'
+BOLD='\033[1m'
+DIM='\033[2m'
+UNDERLINE='\033[4m'
+RESET='\033[0m'
+
+# Bright colors
+BRIGHT_RED='\033[1;31m'
+BRIGHT_GREEN='\033[1;32m'
+BRIGHT_YELLOW='\033[1;33m'
+BRIGHT_BLUE='\033[1;34m'
+BRIGHT_PURPLE='\033[1;35m'
+BRIGHT_CYAN='\033[1;36m'
+
+# V3 Development Targets
+DOMAINS_TOTAL=5
+AGENTS_TARGET=15
+PERF_TARGET="2.49x-7.47x"
+SECURITY_CVES=3
+
+# Default values
+DOMAINS_COMPLETED=0
+AGENTS_ACTIVE=0
+PERF_CURRENT="1.0x"
+SECURITY_STATUS="PENDING"
+DDD_PROGRESS=0
+INTEGRATION_STATUS="○"
+
+# Get current git branch
+GIT_BRANCH=""
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+fi
+
+# Check V3 domain implementation progress
+if [ -f "$V3_METRICS" ]; then
+  DOMAINS_COMPLETED=$(jq -r '.domains.completed // 0' "$V3_METRICS" 2>/dev/null || echo "0")
+  DDD_PROGRESS=$(jq -r '.ddd.progress // 0' "$V3_METRICS" 2>/dev/null || echo "0")
+  AGENTS_ACTIVE=$(jq -r '.swarm.activeAgents // 0' "$V3_METRICS" 2>/dev/null || echo "0")
+else
+  # Check for actual domain directories
+  DOMAINS_COMPLETED=0
+  [ -d "src/domains/task-management" ] && ((DOMAINS_COMPLETED++))
+  [ -d "src/domains/session-management" ] && ((DOMAINS_COMPLETED++))
+  [ -d "src/domains/health-monitoring" ] && ((DOMAINS_COMPLETED++))
+  [ -d "src/domains/lifecycle-management" ] && ((DOMAINS_COMPLETED++))
+  [ -d "src/domains/event-coordination" ] && ((DOMAINS_COMPLETED++))
+fi
+
+# Check security audit status
+if [ -f "$SECURITY_AUDIT" ]; then
+  SECURITY_STATUS=$(jq -r '.status // "PENDING"' "$SECURITY_AUDIT" 2>/dev/null || echo "PENDING")
+  CVES_FIXED=$(jq -r '.cvesFixed // 0' "$SECURITY_AUDIT" 2>/dev/null || echo "0")
+else
+  CVES_FIXED=0
+fi
+
+# Check performance metrics
+if [ -f "$PERFORMANCE_METRICS" ]; then
+  PERF_CURRENT=$(jq -r '.flashAttention.speedup // "1.0x"' "$PERFORMANCE_METRICS" 2>/dev/null || echo "1.0x")
+  MEMORY_REDUCTION=$(jq -r '.memory.reduction // "0%"' "$PERFORMANCE_METRICS" 2>/dev/null || echo "0%")
+else
+  MEMORY_REDUCTION="0%"
+fi
+
+# Check agentic-flow@alpha integration status
+INTEGRATION_STATUS="○"
+if [ -f "package.json" ]; then
+  if grep -q "agentic-flow.*alpha" package.json 2>/dev/null; then
+    INTEGRATION_STATUS="●"
+  fi
+fi
+
+# Colorful domain status indicators
+COMPLETED_DOMAIN="${BRIGHT_GREEN}●${RESET}"
+PENDING_DOMAIN="${DIM}○${RESET}"
+DOMAIN_STATUS="${PENDING_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}"
+
+case $DOMAINS_COMPLETED in
+  1) DOMAIN_STATUS="${COMPLETED_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}" ;;
+  2) DOMAIN_STATUS="${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}" ;;
+  3) DOMAIN_STATUS="${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${PENDING_DOMAIN}${PENDING_DOMAIN}" ;;
+  4) DOMAIN_STATUS="${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${PENDING_DOMAIN}" ;;
+  5) DOMAIN_STATUS="${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}${COMPLETED_DOMAIN}" ;;
+esac
+
+# Colorful security status
+SECURITY_ICON="🔴"
+SECURITY_COLOR="${BRIGHT_RED}"
+if [ "$SECURITY_STATUS" = "CLEAN" ]; then
+  SECURITY_ICON="🟢"
+  SECURITY_COLOR="${BRIGHT_GREEN}"
+elif [ "$CVES_FIXED" -gt 0 ]; then
+  SECURITY_ICON="🟡"
+  SECURITY_COLOR="${BRIGHT_YELLOW}"
+fi
+
+# Integration status colors
+INTEGRATION_COLOR="${DIM}"
+if [ "$INTEGRATION_STATUS" = "●" ]; then
+  INTEGRATION_COLOR="${BRIGHT_CYAN}"
+fi
+
+# Build colorful output with better formatting
+OUTPUT=""
+
+# Header Line: V3 Project + Branch + Integration Status
+OUTPUT="${BOLD}${BRIGHT_PURPLE}▊ Claude Flow V3 ${RESET}"
+OUTPUT="${OUTPUT}${INTEGRATION_COLOR}${INTEGRATION_STATUS} ${BRIGHT_CYAN}agentic-flow@alpha${RESET}"
+if [ -n "$GIT_BRANCH" ]; then
+  OUTPUT="${OUTPUT}  ${DIM}│${RESET}  ${BRIGHT_BLUE}⎇ ${GIT_BRANCH}${RESET}"
+fi
+
+# Separator line
+OUTPUT="${OUTPUT}\n${DIM}─────────────────────────────────────────────────────${RESET}"
+
+# Line 1: DDD Domain Decomposition Progress
+DOMAINS_COLOR="${BRIGHT_GREEN}"
+if [ "$DOMAINS_COMPLETED" -lt 3 ]; then
+  DOMAINS_COLOR="${YELLOW}"
+fi
+if [ "$DOMAINS_COMPLETED" -eq 0 ]; then
+  DOMAINS_COLOR="${RED}"
+fi
+
+PERF_COLOR="${BRIGHT_YELLOW}"
+if [[ "$PERF_CURRENT" =~ ^[0-9]+\.[0-9]+x$ ]] && [[ "${PERF_CURRENT%x}" > "2.0" ]]; then
+  PERF_COLOR="${BRIGHT_GREEN}"
+fi
+
+OUTPUT="${OUTPUT}\n${BRIGHT_CYAN}🏗️  DDD Domains${RESET}    [${DOMAIN_STATUS}]  ${DOMAINS_COLOR}${DOMAINS_COMPLETED}${RESET}/${BRIGHT_WHITE}${DOMAINS_TOTAL}${RESET}"
+OUTPUT="${OUTPUT}    ${PERF_COLOR}⚡ ${PERF_CURRENT}${RESET} ${DIM}→${RESET} ${BRIGHT_YELLOW}${PERF_TARGET}${RESET}"
+
+# Line 2: 15-Agent Swarm Coordination Status
+AGENTS_COLOR="${BRIGHT_GREEN}"
+if [ "$AGENTS_ACTIVE" -lt 8 ]; then
+  AGENTS_COLOR="${YELLOW}"
+fi
+if [ "$AGENTS_ACTIVE" -eq 0 ]; then
+  AGENTS_COLOR="${RED}"
+fi
+
+MEMORY_COLOR="${BRIGHT_GREEN}"
+if [[ "$MEMORY_REDUCTION" == "0%" ]]; then
+  MEMORY_COLOR="${DIM}"
+fi
+
+# Format agent count with padding
+AGENT_DISPLAY=$(printf "%2d" "$AGENTS_ACTIVE")
+
+OUTPUT="${OUTPUT}\n${BRIGHT_YELLOW}🤖 Swarm Agents${RESET}    [${AGENTS_COLOR}${AGENT_DISPLAY}${RESET}/${BRIGHT_WHITE}${AGENTS_TARGET}${RESET}]      ${SECURITY_ICON} ${SECURITY_COLOR}CVE ${CVES_FIXED}${RESET}/${BRIGHT_WHITE}${SECURITY_CVES}${RESET}    ${MEMORY_COLOR}💾 ${MEMORY_REDUCTION}${RESET}"
+
+# Line 3: V3 Architecture Components with better alignment
+DDD_COLOR="${BRIGHT_GREEN}"
+if [ "$DDD_PROGRESS" -lt 50 ]; then
+  DDD_COLOR="${YELLOW}"
+fi
+if [ "$DDD_PROGRESS" -eq 0 ]; then
+  DDD_COLOR="${RED}"
+fi
+
+# Format DDD progress with padding
+DDD_DISPLAY=$(printf "%3d" "$DDD_PROGRESS")
+
+OUTPUT="${OUTPUT}\n${BRIGHT_PURPLE}🔧 Architecture${RESET}    ${CYAN}DDD${RESET} ${DDD_COLOR}●${DDD_DISPLAY}%${RESET}  ${DIM}│${RESET}  ${CYAN}Security${RESET} ${SECURITY_COLOR}●${SECURITY_STATUS}${RESET}"
+OUTPUT="${OUTPUT}  ${DIM}│${RESET}  ${CYAN}Memory${RESET} ${BRIGHT_GREEN}●AgentDB${RESET}  ${DIM}│${RESET}  ${CYAN}Integration${RESET} ${INTEGRATION_COLOR}●${RESET}"
+
+# Footer separator
+OUTPUT="${OUTPUT}\n${DIM}─────────────────────────────────────────────────────${RESET}"
+
+printf "%b\n" "$OUTPUT"
@@ -1,12 +1,52 @@
 # Claude Code Configuration - Agentic Flow

-## Project Setup
+## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT

-This project is configured with Agentic Flow for AI agent orchestration.
+**ABSOLUTE RULES**:
+1. ALL operations MUST be concurrent/parallel in a single message
+2. **NEVER save working files, text/mds and tests to the root folder**
+3. ALWAYS organize files in appropriate subdirectories
+4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP

-## Available Commands
+### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
+
+**MANDATORY PATTERNS:**
+- **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
+- **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
+- **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
+- **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
+- **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
+
+### 🎯 CRITICAL: Claude Code Task Tool for Agent Execution
+
+**Claude Code's Task tool is the PRIMARY way to spawn agents:**
+```javascript
+// ✅ CORRECT: Use Claude Code's Task tool for parallel agent execution
+[Single Message]:
+  Task("Research agent", "Analyze requirements and patterns...", "researcher")
+  Task("Coder agent", "Implement core features...", "coder")
+  Task("Tester agent", "Create comprehensive tests...", "tester")
+  Task("Reviewer agent", "Review code quality...", "reviewer")
+  Task("Architect agent", "Design system architecture...", "system-architect")
+```
+
+**MCP tools are ONLY for coordination setup:**
+- `mcp__claude-flow__swarm_init` - Initialize coordination topology
+- `mcp__claude-flow__agent_spawn` - Define agent types for coordination
+- `mcp__claude-flow__task_orchestrate` - Orchestrate high-level workflows
+
+### 📁 File Organization Rules
+
+**NEVER save to root folder. Use these directories:**
+- `/src` - Source code files
+- `/tests` - Test files
+- `/docs` - Documentation and markdown files
+- `/config` - Configuration files
+- `/scripts` - Utility scripts
+- `/examples` - Example code
+
+## 🚀 Quick Start

-### Quick Start
 ```bash
 # Start MCP server for Claude Code integration
 npx agentic-flow@alpha mcp start
@@ -18,27 +58,636 @@ npx agentic-flow@alpha --agent coder --task "Your task here"
 npx agentic-flow@alpha --list
 ```

-### Hooks (Self-learning Intelligence)
+## 🚀 Available Agents (54+ Total)
+
+### 🆕 V3 Specialized Swarm Agents
+**15-Agent Concurrent Implementation:**
+- `queen-coordinator` - V3 orchestration & GitHub issue management
+- `security-architect` - Security architecture & threat modeling
+- `security-auditor` - CVE remediation & security testing
+- `memory-specialist` - AgentDB unification (150x-12,500x faster)
+- `swarm-specialist` - Unified coordination engine
+- `integration-architect` - agentic-flow@alpha deep integration
+- `performance-engineer` - 2.49x-7.47x optimization targets
+- `core-architect` - Domain-driven design restructure
+- `test-architect` - TDD London School methodology
+- `project-coordinator` - Cross-domain coordination
+
+### Core Development
+`coder`, `reviewer`, `tester`, `planner`, `researcher`
+
+### Swarm Coordination
+`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager`
+
+### Consensus & Distributed
+`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager`
+
+### Performance & Optimization
+`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent`
+
+### GitHub & Repository
+`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm`
+
+### SPARC Methodology
+`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement`
+
+### Specialized Development
+`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
+
+## 🎯 Claude Code vs MCP Tools
+
+### Claude Code Handles ALL EXECUTION:
+- **Task tool**: Spawn and run agents concurrently for actual work
+- File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
+- Code generation and programming
+- Bash commands and system operations
+- Implementation work
+- Project navigation and analysis
+- TodoWrite and task management
+- Git operations
+- Package management
+- Testing and debugging
+
+### MCP Tools ONLY COORDINATE:
+- Swarm initialization (topology setup)
+- Agent type definitions (coordination patterns)
+- Task orchestration (high-level planning)
+- Memory management
+- Neural features
+- Performance tracking
+- GitHub integration
+
+**KEY**: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.
+
+## MCP Tool Categories
+
+### Coordination
+`swarm_init`, `agent_spawn`, `task_orchestrate`
+
+### Monitoring
+`swarm_status`, `agent_list`, `agent_metrics`, `task_status`, `task_results`
+
+### Memory & Neural
+`memory_usage`, `neural_status`, `neural_train`, `neural_patterns`
+
+### GitHub Integration
+`github_swarm`, `repo_analyze`, `pr_enhance`, `issue_triage`, `code_review`
+
+## 🧠 Self-Learning Hooks System
+
+### Available Hooks Commands:
 ```bash
-npx agentic-flow@alpha hooks pre-edit <file>    # Get context before editing
-npx agentic-flow@alpha hooks post-edit <file>   # Learn from edits
-npx agentic-flow@alpha hooks route <task>       # Smart agent routing
+# Before editing - get context and agent suggestions
+npx agentic-flow@alpha hooks pre-edit <filePath>
+
+# After editing - record outcome for learning
+npx agentic-flow@alpha hooks post-edit <filePath> --success true
+
+# Before commands - assess risk
+npx agentic-flow@alpha hooks pre-command "<command>"
+
+# After commands - record outcome
+npx agentic-flow@alpha hooks post-command "<command>" --success true
+
+# Route task to optimal agent using learned patterns
+npx agentic-flow@alpha hooks route "<task description>"
+
+# Explain routing decision with transparency
+npx agentic-flow@alpha hooks explain "<task description>"
+
+# Bootstrap intelligence from repository
+npx agentic-flow@alpha hooks pretrain
+
+# Generate optimized agent configs from pretrain data
+npx agentic-flow@alpha hooks build-agents
+
+# View learning metrics dashboard
+npx agentic-flow@alpha hooks metrics
+
+# Transfer patterns from another project
+npx agentic-flow@alpha hooks transfer <sourceProject>
+
+# RuVector intelligence (SONA, MoE, HNSW 150x faster)
+npx agentic-flow@alpha hooks intelligence
 ```

-### Workers (Background Tasks)
+### Pretraining System (4-Step Pipeline):
+1. **RETRIEVE** - Top-k memory injection with MMR diversity
+2. **JUDGE** - LLM-as-judge trajectory evaluation
+3. **DISTILL** - Extract strategy memories from trajectories
+4. **CONSOLIDATE** - Dedup, detect contradictions, prune old patterns
+
+## Performance Benefits
+
+- **84.8% SWE-Bench solve rate**
+- **32.3% token reduction**
+- **2.8-4.4x speed improvement**
+- **27+ neural models**
+
+## Advanced Features (v2.0.0)
+
+- 🚀 Automatic Topology Selection
+- ⚡ Parallel Execution (2.8-4.4x speed)
+- 🧠 Neural Training
+- 📊 Bottleneck Analysis
+- 🤖 Smart Auto-Spawning
+- 🛡️ Self-Healing Workflows
+- 💾 Cross-Session Memory
+- 🔗 GitHub Integration
+
+## 🆚 V3 Development Guide
+
+### 🎯 V3 Implementation Strategy
+
+**Based on 10 Architecture Decision Records (ADRs):**
+- **ADR-001**: Adopt agentic-flow as core foundation (eliminate 10,000+ duplicate lines)
+- **ADR-002**: Domain-Driven Design structure (bounded contexts)
+- **ADR-003**: Single coordination engine (unified SwarmCoordinator)
+- **ADR-004**: Plugin-based architecture (microkernel pattern)
+- **ADR-005**: MCP-first API design (consistent interfaces)
+- **ADR-006**: Unified memory service (AgentDB integration)
+- **ADR-007**: Event sourcing for state changes (audit trail)
+- **ADR-008**: Vitest over Jest (10x faster testing)
+- **ADR-009**: Hybrid memory backend default (SQLite + AgentDB)
+- **ADR-010**: Remove Deno support (Node.js 20+ focus)
+
+### 🛠️ V3 Agent Usage Patterns
+
+**15-Agent Concurrent Swarm Commands:**
 ```bash
-npx agentic-flow@alpha workers status           # Check worker status
-npx agentic-flow@alpha workers dispatch <task>  # Dispatch background task
+# Initialize v3 swarm (hierarchical mesh)
+npx agentic-flow@alpha hooks init --v3-mode
+
+# Spawn Queen Coordinator (manages all 15 agents)
+npx agentic-flow@alpha agent spawn queen-coordinator --id 1
+
+# Security Domain (Critical Priority - Agents #2-4)
+npx agentic-flow@alpha agent spawn security-architect --id 2 &
+npx agentic-flow@alpha agent spawn security-auditor --cve-focus &
+npx agentic-flow@alpha agent spawn test-architect --security-tdd &
+
+# Core Domain (Agents #5-9)
+npx agentic-flow@alpha agent spawn core-architect --ddd-patterns &
+npx agentic-flow@alpha agent spawn memory-specialist --agentdb-integration &
+npx agentic-flow@alpha agent spawn swarm-specialist --unified-coordinator &
+
+# Integration & Performance (Agents #10-15)
+npx agentic-flow@alpha agent spawn integration-architect --agentic-flow-alpha &
+npx agentic-flow@alpha agent spawn performance-engineer --2.49x-target &
+
+# Wait for all agents to complete phase
+wait
 ```

-## Code Style
+### 📊 V3 Performance Targets
+- **Flash Attention**: 2.49x-7.47x speedup
+- **AgentDB Search**: 150x-12,500x improvement
+- **Memory Reduction**: 50-75%
+- **Code Reduction**: <5,000 lines (vs 15,000+)
+- **Startup Time**: <500ms
+- **SONA Learning**: <0.05ms adaptation

- Use TypeScript for new code
- Follow existing patterns in the codebase
- Add tests for new functionality
+### 🏗️ V3 Domain Structure
+```
+src/
+├── agent-lifecycle/      # Bounded Context 1
+│   ├── domain/          # Business logic
+│   ├── application/     # Use cases
+│   ├── infrastructure/  # Persistence
+│   └── api/            # CLI, MCP interfaces
+├── task-execution/      # Bounded Context 2
+├── memory-management/   # Bounded Context 3
+├── coordination/        # Bounded Context 4
+├── shared-kernel/       # Shared utilities
+└── infrastructure/      # Cross-cutting concerns
+```

-## Important Notes
+### 🔧 V3 Development Commands
+```bash
+# V3-specific agent builds
+npx agentic-flow@alpha hooks build-agents --focus "v3-implementation"

- Never hardcode secrets - use environment variables
- Keep files under 500 lines when possible
- Write tests before implementation (TDD)
+# Security-first approach
+npx agentic-flow@alpha hooks build-agents --focus "security"
+
+# Performance optimization
+npx agentic-flow@alpha hooks build-agents --focus "performance"
+
+# Route tasks to optimal v3 agents
+npx agentic-flow@alpha hooks route "Implement unified memory service for v3"
+
+# Monitor v3 swarm performance
+npx agentic-flow@alpha hooks metrics --v3-dashboard
+```
+
+## 🏗️ V3 Module Constellation Architecture
+
+### **Modular Design Philosophy**
+V3 implements a **constellation of @claude-flow modules** in `/v3/module-names/` for maximum flexibility, security, and cross-platform compatibility.
+
+### **Module Structure**
+```
+v3/
+├── @claude-flow/security/          # Security module (CVE fixes, patterns)
+├── @claude-flow/memory/            # AgentDB unification module
+├── @claude-flow/integration/       # agentic-flow@alpha integration
+├── @claude-flow/performance/       # Optimization & benchmarking
+├── @claude-flow/swarm/             # 15-agent coordination
+├── @claude-flow/cli/               # CLI modernization
+├── @claude-flow/neural/            # SONA learning integration
+├── @claude-flow/testing/           # TDD London School framework
+├── @claude-flow/deployment/        # Release & CI/CD
+└── @claude-flow/shared/            # Shared utilities & types
+```
+
+### **Cross-Platform Module Commands**
+
+#### **Windows (PowerShell/CMD)**
+```powershell
+# Security module
+npx @claude-flow/security@latest audit --platform windows
+npm run security:scan --if-present
+
+# Memory module
+npx @claude-flow/memory@latest unify --backend agentdb
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Integration module
+npx @claude-flow/integration@latest --agentic-flow-version alpha
+$env:CLAUDE_FLOW_MODE = "integration"
+```
+
+#### **macOS (Bash/Zsh)**
+```bash
+# Security module
+npx @claude-flow/security@latest audit --platform darwin
+export CLAUDE_FLOW_SECURITY_MODE="strict"
+
+# Memory module
+npx @claude-flow/memory@latest unify --backend agentdb
+export CLAUDE_FLOW_MEMORY_PATH="./data"
+
+# Integration module
+npx @claude-flow/integration@latest --agentic-flow-version alpha
+export CLAUDE_FLOW_MODE="integration"
+```
+
+#### **Linux (Bash)**
+```bash
+# Security module
+npx @claude-flow/security@latest audit --platform linux
+export CLAUDE_FLOW_SECURITY_MODE="strict"
+
+# Memory module
+npx @claude-flow/memory@latest unify --backend agentdb
+export CLAUDE_FLOW_MEMORY_PATH="./data"
+
+# Performance module
+npx @claude-flow/performance@latest benchmark --target "2.49x-7.47x"
+ulimit -n 65536  # Increase file descriptor limit
+```
+
+### **Module Installation & Usage**
+
+#### **Individual Module Installation**
+```bash
+# Install specific modules
+npm install @claude-flow/security@latest
+npm install @claude-flow/memory@latest
+npm install @claude-flow/integration@latest
+
+# Or install all v3 modules
+npm install @claude-flow/v3-complete@latest
+```
+
+#### **Module Composition**
+```typescript
+// v3/main.ts - Module orchestration
+import { SecurityModule } from '@claude-flow/security';
+import { MemoryModule } from '@claude-flow/memory';
+import { IntegrationModule } from '@claude-flow/integration';
+import { PerformanceModule } from '@claude-flow/performance';
+import { SwarmModule } from '@claude-flow/swarm';
+
+class V3ClaudeFlow {
+  constructor() {
+    this.security = new SecurityModule({ strict: true });
+    this.memory = new MemoryModule({ backend: 'agentdb' });
+    this.integration = new IntegrationModule({
+      agentic: { version: 'alpha' }
+    });
+    this.performance = new PerformanceModule({
+      targets: { flashAttention: '2.49x-7.47x' }
+    });
+    this.swarm = new SwarmModule({
+      topology: 'hierarchical-mesh',
+      agents: 15
+    });
+  }
+
+  async initialize(): Promise<void> {
+    // Initialize in dependency order
+    await this.security.initialize();
+    await this.memory.initialize();
+    await this.integration.initialize();
+    await this.performance.initialize();
+    await this.swarm.initialize();
+  }
+}
+```
+
+## 🛡️ V3 Security Guidelines
+
+### **Security-First Development**
+```bash
+# Pre-commit security checks (all platforms)
+npm run security:pre-commit
+npx @claude-flow/security audit --strict
+
+# CVE scanning
+npm audit --audit-level high
+npx @claude-flow/security cve-scan --fix-critical
+```
+
+### **Environment-Specific Security**
+
+#### **Windows Security**
+```powershell
+# Enable Windows Defender scanning
+Add-MpPreference -ExclusionPath ".\node_modules" -Force
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Windows-specific security checks
+npx @claude-flow/security@latest --platform windows --check-acl
+Get-Acl -Path ".\v3" | Format-List
+```
+
+#### **macOS Security**
+```bash
+# macOS keychain integration
+security add-generic-password -a claude-flow -s claude-flow-v3 -w
+export CLAUDE_FLOW_KEYCHAIN="claude-flow-v3"
+
+# macOS-specific security
+npx @claude-flow/security@latest --platform darwin --check-gatekeeper
+codesign --verify --deep ./v3/
+```
+
+#### **Linux Security**
+```bash
+# SELinux/AppArmor compatibility
+npx @claude-flow/security@latest --platform linux --check-selinux
+sestatus # Check SELinux status
+
+# File permissions security
+chmod 750 ./v3/
+chown -R $USER:$USER ./v3/
+```
+
+### **Secure Module Configuration**
+```typescript
+// v3/config/security.ts
+export const securityConfig = {
+  // Input validation
+  validation: {
+    maxInputSize: 10000,
+    allowedChars: /^[a-zA-Z0-9._\-\s]+$/,
+    sanitizeHtml: true
+  },
+
+  // Path security
+  paths: {
+    allowedDirectories: ['./v3/', './src/', './tests/'],
+    blockedPatterns: ['../', '~/', '/etc/', '/tmp/'],
+    maxPathLength: 255
+  },
+
+  // Command execution
+  execution: {
+    shell: false,
+    timeout: 30000,
+    allowedCommands: ['npm', 'npx', 'node', 'git'],
+    blockedCommands: ['rm', 'del', 'format', 'dd']
+  },
+
+  // Network security
+  network: {
+    allowedHosts: ['api.anthropic.com', 'github.com'],
+    requireHttps: true,
+    timeoutMs: 10000
+  },
+
+  // Memory security
+  memory: {
+    maxHeapSize: '2GB',
+    enableGC: true,
+    clearSensitiveData: true
+  }
+};
+```
+
+### **Credential Management**
+```bash
+# Environment-specific credential setup
+## Windows
+setx CLAUDE_FLOW_API_KEY "your-secure-key"
+setx CLAUDE_FLOW_ENV "production"
+
+## macOS/Linux
+export CLAUDE_FLOW_API_KEY="your-secure-key"
+export CLAUDE_FLOW_ENV="production"
+
+# Secure credential validation
+npx @claude-flow/security validate-credentials --env production
+```
+
+## 🌍 Multi-Environment Support
+
+### **Platform Detection & Adaptation**
+```typescript
+// v3/utils/platform.ts
+export class PlatformAdapter {
+  static detect(): 'windows' | 'darwin' | 'linux' {
+    return process.platform as any;
+  }
+
+  static getCommands() {
+    switch (this.detect()) {
+      case 'windows':
+        return {
+          shell: 'powershell.exe',
+          npm: 'npm.cmd',
+          npx: 'npx.cmd'
+        };
+      case 'darwin':
+      case 'linux':
+        return {
+          shell: '/bin/bash',
+          npm: 'npm',
+          npx: 'npx'
+        };
+    }
+  }
+
+  static getPaths() {
+    const platform = this.detect();
+    return {
+      home: platform === 'windows' ? process.env.USERPROFILE : process.env.HOME,
+      sep: platform === 'windows' ? '\\' : '/',
+      config: platform === 'windows'
+        ? path.join(process.env.APPDATA!, 'claude-flow')
+        : path.join(process.env.HOME!, '.claude-flow')
+    };
+  }
+}
+```
+
+### **Cross-Platform Module Scripts**
+```json
+// package.json - Cross-platform scripts
+{
+  "scripts": {
+    "v3:security": "npx @claude-flow/security audit",
+    "v3:security:win": "powershell -Command \"npx @claude-flow/security audit --platform windows\"",
+    "v3:security:unix": "npx @claude-flow/security audit --platform $(uname -s | tr '[:upper:]' '[:lower:]')",
+
+    "v3:memory": "npx @claude-flow/memory unify --backend agentdb",
+    "v3:memory:win": "set CLAUDE_FLOW_MEMORY_PATH=.\\data && npm run v3:memory",
+    "v3:memory:unix": "CLAUDE_FLOW_MEMORY_PATH=./data npm run v3:memory",
+
+    "v3:performance": "npx @claude-flow/performance benchmark",
+    "v3:performance:win": "powershell -Command \"npx @claude-flow/performance benchmark --platform windows\"",
+    "v3:performance:unix": "npx @claude-flow/performance benchmark --platform $(uname)",
+
+    "v3:swarm": "npx @claude-flow/swarm coordinate --agents 15",
+    "v3:integration": "npx @claude-flow/integration --agentic-flow-version alpha",
+
+    "v3:full-stack": "npm-run-all --parallel v3:security v3:memory v3:integration v3:performance"
+  }
+}
+```
+
+### **Environment-Specific Configuration**
+```typescript
+// v3/config/environment.ts
+export class EnvironmentConfig {
+  static getConfig() {
+    const platform = process.platform;
+    const env = process.env.NODE_ENV || 'development';
+
+    const baseConfig = {
+      security: { strict: env === 'production' },
+      memory: { backend: 'agentdb' },
+      performance: { targets: { flashAttention: '2.49x-7.47x' } }
+    };
+
+    const platformConfig = {
+      win32: {
+        paths: { separator: '\\', config: process.env.APPDATA },
+        commands: { shell: 'powershell.exe' },
+        security: { useWindowsACL: true }
+      },
+      darwin: {
+        paths: { separator: '/', config: '~/.claude-flow' },
+        commands: { shell: '/bin/bash' },
+        security: { useKeychain: true }
+      },
+      linux: {
+        paths: { separator: '/', config: '~/.claude-flow' },
+        commands: { shell: '/bin/bash' },
+        security: { useSELinux: true }
+      }
+    };
+
+    return {
+      ...baseConfig,
+      platform: platformConfig[platform] || platformConfig.linux
+    };
+  }
+}
+```
+
+## 📦 V3 Module Development Workflow
+
+### **Module Development Commands**
+```bash
+# Create new v3 module
+npx @claude-flow/cli create-module --name "@claude-flow/my-module"
+
+# Test module across platforms
+npm run test:cross-platform
+npm run test:windows    # Windows-specific tests
+npm run test:darwin     # macOS-specific tests
+npm run test:linux      # Linux-specific tests
+
+# Build and publish module
+npm run build:multi-platform
+npm publish --tag v3-latest
+```
+
+### **Module Testing Framework**
+```typescript
+// v3/testing/cross-platform.test.ts
+describe('V3 Cross-Platform Compatibility', () => {
+  test('should work on Windows', async () => {
+    if (process.platform !== 'win32') return;
+
+    const result = await executeModule('@claude-flow/security', {
+      platform: 'windows'
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.windowsSpecific).toBeDefined();
+  });
+
+  test('should work on macOS', async () => {
+    if (process.platform !== 'darwin') return;
+
+    const result = await executeModule('@claude-flow/security', {
+      platform: 'darwin'
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.keychainIntegration).toBe(true);
+  });
+
+  test('should work on Linux', async () => {
+    if (process.platform !== 'linux') return;
+
+    const result = await executeModule('@claude-flow/security', {
+      platform: 'linux'
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.linuxSpecific).toBeDefined();
+  });
+});
+```
+
+## Code Style & Best Practices
+
+- **Domain-Driven Design**: Clear bounded contexts (ADR-002)
+- **Modular Design**: Files under 500 lines
+- **Security-First**: Address CVE-1, CVE-2, CVE-3 immediately
+- **agentic-flow Integration**: Build on, don't duplicate (ADR-001)
+- **Event Sourcing**: Critical state changes for audit (ADR-007)
+- **TDD London School**: Mock-first approach
+- **Performance Conscious**: Target 2.49x-7.47x improvements
+- **Environment Safety**: Never hardcode secrets
+- **Documentation**: Keep updated with ADR decisions
+
+## Support
+
+- Documentation: https://github.com/ruvnet/agentic-flow
+- Issues: https://github.com/ruvnet/agentic-flow/issues
+
+---
+
+Remember: **Agentic Flow coordinates, Claude Code creates!**
+
+# important-instruction-reminders
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+Never save working files, text/mds and tests to the root folder.
@@ -0,0 +1,51 @@
+{
+  "name": "claude-flow-v3",
+  "version": "3.0.0-alpha.1",
+  "description": "Claude Flow V3 - Domain-Driven Design Architecture with 15-Agent Swarm Coordination",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint src/**/*.ts",
+    "security:audit": "npm audit --audit-level high",
+    "v3:domains": "npm run build:domains",
+    "v3:swarm": "npm run start:swarm",
+    "v3:security": "npm run security:audit"
+  },
+  "dependencies": {
+    "agentic-flow": "alpha",
+    "@claude-flow/security": "^3.0.0-alpha.1",
+    "@claude-flow/memory": "^3.0.0-alpha.1",
+    "@claude-flow/integration": "^3.0.0-alpha.1",
+    "@claude-flow/performance": "^3.0.0-alpha.1",
+    "@claude-flow/swarm": "^3.0.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "eslint": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/claude-flow.git"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "agents",
+    "swarm",
+    "ddd",
+    "domain-driven-design",
+    "v3"
+  ],
+  "author": "RuvNet",
+  "license": "MIT"
+}
@@ -0,0 +1,2 @@
+# Task Management Domain
+# This domain handles task lifecycle, scheduling, and coordination
@@ -0,0 +1,361 @@
+# Claude-Flow V3 Optimization Implementation Roadmap
+
+## 🚀 Executive Summary
+
+This roadmap implements the comprehensive optimization recommendations for claude-flow V3, incorporating security-first development, enhanced parallel execution, phased performance targets, and intelligent learning integration.
+
+**Key Optimizations Applied:**
+- ✅ **Agent-Skills Perfect Alignment**: 15 agents → 9 specialized skills (4 new skills created)
+- ✅ **Enhanced Settings Configuration**: V3-optimized learning and performance settings
+- ✅ **Phased Performance Targets**: Risk-mitigated 4-phase rollout strategy
+- ✅ **Dependency Optimization**: 90% agent utilization vs 75% original
+- ✅ **Intelligence Bootstrap**: 7,862 files analyzed, patterns learned
+
+---
+
+## 🎯 **Optimization Overview**
+
+### **Timeline Improvement**
+| Metric | Original Plan | Optimized Plan | Improvement |
+|--------|---------------|----------------|-------------|
+| **Total Duration** | 14 weeks (high risk) | 16 weeks (controlled) | **+2 week buffer** |
+| **Parallel Efficiency** | 75% | 90% | **+15% improvement** |
+| **Agent Utilization** | 80% | 95% | **+15% productivity** |
+| **Risk Level** | High | Medium-Low | **Significantly reduced** |
+
+### **Performance Delivery Strategy**
+```
+Phase 1 (Weeks 1-3):  Conservative targets + Security first
+Phase 2 (Weeks 4-8):  Mid-range targets + Core optimization
+Phase 3 (Weeks 9-12): High targets + Integration excellence
+Phase 4 (Weeks 13-16): Stretch targets + Final polish
+```
+
+---
+
+## 📋 **Implementation Checklist**
+
+### ✅ **Completed Optimizations**
+
+- [x] **V3 Skills Created**: 4 new specialized skills
+  - `v3-ddd-architecture` - Domain-driven design implementation
+  - `v3-core-implementation` - TypeScript core modules
+  - `v3-mcp-optimization` - MCP server performance
+  - `v3-cli-modernization` - Interactive CLI enhancement
+
+- [x] **Intelligence Bootstrap**: Repository pretrained
+  - 7,862 files analyzed for patterns
+  - Learning system optimized for V3 development
+  - Agent routing intelligence enhanced
+
+- [x] **Settings Optimization**: Enhanced .claude/settings.json
+  - V3-specific environment variables
+  - Enhanced hooks with security checks
+  - Learning integration with pattern extraction
+  - Performance monitoring enabled
+
+- [x] **Agent Configurations**: Optimized agents generated
+  - Security-focused agent set
+  - Quality-focused agent set for V3
+  - Enhanced capabilities for V3 patterns
+
+- [x] **Performance Targets**: Phased rollout strategy
+  - 4-phase implementation plan
+  - Risk-mitigated target progression
+  - Adaptive strategy with rollback triggers
+
+- [x] **Dependency Optimization**: Enhanced parallelism
+  - Reduced blocking dependencies
+  - 90% agent utilization target
+  - Overlapping phase boundaries
+
+---
+
+## 🏗️ **Implementation Phases**
+
+### **Phase 1: Security-First Foundation (Weeks 1-3)**
+
+**Enhanced Parallel Execution:**
+```typescript
+Week 1-3 Parallel Groups:
+├── Security Foundation (Agents #2, #3, #4)
+├── Core Architecture (Agent #5)
+├── Testing Framework (Agent #13)
+└── Performance Setup (Agent #14)
+```
+
+**Performance Targets:**
+- Flash Attention: 2.49x minimum (conservative)
+- Search: 150x minimum (basic HNSW)
+- Memory: 40% reduction (achievable)
+- Startup: <750ms (less aggressive)
+- Security: 75/100 score (significant improvement)
+
+**Critical Success Factors:**
+- Security baseline established
+- No critical regressions introduced
+- Foundation ready for next phase
+
+### **Phase 2: Core Systems Optimization (Weeks 2-6)**
+
+**Enhanced Parallel Execution:**
+```typescript
+Week 2-6 Overlapped Groups:
+├── Core Implementation (Agents #6, #7, #8)
+├── MCP Optimization (Agent #9)
+├── Queen Coordination (Agent #1)
+└── Continued Testing & Performance (#13, #14)
+```
+
+**Performance Targets:**
+- Flash Attention: 3.5x-5.0x (mid-range)
+- Search: 500x-2000x (optimized HNSW)
+- Memory: 50% reduction (enhanced)
+- Startup: <500ms (target achieved)
+- Swarm: <100ms coordination
+
+**Critical Success Factors:**
+- Core systems fully operational
+- 15-agent swarm coordination working
+- Performance mid-range targets achieved
+
+### **Phase 3: Integration Excellence (Weeks 5-9)**
+
+**Enhanced Parallel Execution:**
+```typescript
+Week 5-9 Reduced Dependencies:
+├── Integration Core (Agent #10) - depends only on [5,7]
+├── CLI Modernization (Agent #11) - depends only on [5] ✅ OPTIMIZED
+├── Neural Learning (Agent #12) - depends only on [5] ✅ OPTIMIZED
+└── Continued all other agents
+```
+
+**Performance Targets:**
+- Flash Attention: 5.0x-7.47x (near maximum)
+- Search: 2000x-12,500x (maximum performance)
+- Memory: 65% reduction (advanced compression)
+- Startup: <350ms (excellence target)
+- MCP: <100ms p95 response time
+
+**Critical Success Factors:**
+- agentic-flow integration complete
+- All V3 features operational
+- High-performance targets achieved
+
+### **Phase 4: Excellence & Polish (Weeks 9-16)**
+
+**Enhanced Parallel Execution:**
+```typescript
+Week 9-16 Full Swarm:
+├── Release Preparation (Agent #15)
+└── All 15 Agents Final Optimization (Parallel)
+```
+
+**Performance Targets:**
+- Flash Attention: 7.47x (stretch target)
+- Search: 12,500x (peak performance)
+- Memory: 75% reduction (maximum efficiency)
+- Startup: <300ms (sub-300ms goal)
+- Throughput: 10x overall improvement
+
+**Critical Success Factors:**
+- Production-ready stability
+- Maximum performance where achievable
+- Comprehensive testing validation
+
+---
+
+## 🔧 **Technical Implementation Details**
+
+### **Enhanced Agent-Skills Mapping**
+```typescript
+const optimizedMapping = {
+  // Perfect 1:1 alignment
+  'v3-security-architect': 'v3-security-overhaul',
+  'v3-memory-specialist': 'v3-memory-unification',
+  'v3-integration-architect': 'v3-integration-deep',
+  'v3-performance-engineer': 'v3-performance-optimization',
+  'swarm-specialist': 'v3-swarm-coordination',
+
+  // New specialized skills
+  'core-architect': 'v3-ddd-architecture',
+  'core-implementer': 'v3-core-implementation',
+  'mcp-specialist': 'v3-mcp-optimization',
+  'cli-hooks-developer': 'v3-cli-modernization'
+};
+```
+
+### **Enhanced Settings Configuration**
+```json
+{
+  "env": {
+    "AGENTIC_FLOW_V3_MODE": "true",
+    "AGENTIC_FLOW_SWARM_SIZE": "15",
+    "AGENTIC_FLOW_TOPOLOGY": "hierarchical",
+    "AGENTIC_FLOW_SECURITY_FIRST": "true",
+    "AGENTIC_FLOW_PERFORMANCE_TIER": "standard",
+    "AGENTIC_FLOW_SONA_ENABLED": "true",
+    "AGENTIC_FLOW_HNSW_ENABLED": "true",
+    "AGENTIC_FLOW_MOE_ATTENTION": "true"
+  }
+}
+```
+
+### **Dependency Chain Optimization**
+```typescript
+const reducedBlocking = {
+  // Major optimizations
+  'cli-hooks-developer': [5], // was [5, 10] - 2 weeks earlier
+  'neural-learning-developer': [5], // was [7, 10] - 3 weeks earlier
+  'queen-coordinator': [2, 5], // added dependencies for better coordination
+
+  // Efficiency gains
+  agentUtilization: '90%', // vs 75% original
+  parallelAgents: '8-12 concurrent', // vs 6-8 original
+  timelineReduction: '20% faster execution'
+};
+```
+
+### **Phased Performance Strategy**
+```typescript
+const phasedTargets = {
+  // Risk mitigation through progressive targets
+  phase1: 'conservative_baseline',
+  phase2: 'mid_range_optimization',
+  phase3: 'high_performance',
+  phase4: 'stretch_goals',
+
+  // Rollback triggers
+  rollback: [
+    'Security score < 70/100',
+    'Startup time > 1000ms',
+    'Memory increase > 50%',
+    'Performance regression > 25%'
+  ]
+};
+```
+
+---
+
+## 📊 **Success Metrics & KPIs**
+
+### **Phase-wise Success Criteria**
+
+**Phase 1 Success:**
+- ✅ Security score ≥75/100
+- ✅ Startup time <750ms
+- ✅ No critical regressions
+- ✅ Foundation established
+
+**Phase 2 Success:**
+- ✅ Flash Attention 3.5x-5.0x
+- ✅ Search improvement 500x-2000x
+- ✅ 15-agent coordination <100ms
+- ✅ Core systems operational
+
+**Phase 3 Success:**
+- ✅ Flash Attention 5.0x-7.47x
+- ✅ Search improvement 2000x-12,500x
+- ✅ Integration complete
+- ✅ All features operational
+
+**Phase 4 Success:**
+- ✅ Overall throughput 10x
+- ✅ Reliability 99.9%
+- ✅ Production ready
+- ✅ Stretch targets achieved
+
+### **Continuous Monitoring**
+```typescript
+const monitoring = {
+  frequency: 'continuous',
+  alerts: {
+    regressionThreshold: '10%',
+    criticalThreshold: '25%'
+  },
+  benchmarks: {
+    automated: true,
+    schedule: 'daily',
+    regressionDetection: true
+  }
+};
+```
+
+---
+
+## 🛠️ **Next Steps**
+
+### **Immediate Actions (Week 1)**
+1. **Initialize Phase 1 Agents**
+   ```bash
+   # Security foundation (parallel)
+   Task("Security architecture", "Design v3 threat model", "v3-security-architect")
+   Task("CVE remediation", "Fix critical vulnerabilities", "security-implementer")
+   Task("Security testing", "TDD security framework", "security-tester")
+   Task("Core architecture", "DDD design", "core-architect")
+   ```
+
+2. **Performance Monitoring Setup**
+   - Enable continuous benchmarking
+   - Set up performance dashboard
+   - Configure alert thresholds
+
+3. **Agent Coordination**
+   - Initialize Queen coordinator
+   - Set up GitHub integration
+   - Enable progress tracking
+
+### **Ongoing Optimization**
+- **Week 2:** Begin Phase 2 overlap
+- **Week 5:** Start Phase 3 integration
+- **Week 9:** Launch Phase 4 polish
+- **Week 16:** Production release
+
+---
+
+## 🎉 **Expected Outcomes**
+
+### **Performance Improvements**
+| Metric | Before | After | Improvement |
+|--------|---------|-------|-------------|
+| **Flash Attention** | N/A | 2.49x-7.47x | New capability |
+| **Search Speed** | Linear | 150x-12,500x | **Revolutionary** |
+| **Memory Usage** | Baseline | 40-75% reduction | **Massive savings** |
+| **Startup Time** | ~2.5s | <300-750ms | **5-8x faster** |
+| **Agent Coordination** | N/A | <100ms | **Real-time** |
+
+### **Development Improvements**
+| Aspect | Before | After | Benefit |
+|--------|---------|-------|---------|
+| **Agent Utilization** | 75% | 90% | **+15% productivity** |
+| **Parallel Efficiency** | Basic | Enhanced | **+25% throughput** |
+| **Risk Level** | High | Medium-Low | **Controlled delivery** |
+| **Timeline Buffer** | None | 2 weeks | **Risk mitigation** |
+
+### **Quality Improvements**
+| Factor | Before | After | Enhancement |
+|--------|---------|-------|-------------|
+| **Security Score** | 45/100 | 75-90/100 | **2x improvement** |
+| **Test Coverage** | Variable | >90% | **Comprehensive** |
+| **Code Quality** | Mixed | DDD + Clean Arch | **Architecture excellence** |
+| **Learning System** | Manual | Intelligent | **Continuous improvement** |
+
+---
+
+## 🏆 **Conclusion**
+
+The V3 optimization implementation roadmap provides a comprehensive, risk-mitigated approach to achieving ambitious performance and functionality targets. Key innovations include:
+
+1. **Phased Performance Rollout** - Reduces delivery risk while maintaining ambitious goals
+2. **Enhanced Parallel Execution** - 90% agent utilization vs 75% original
+3. **Security-First Foundation** - Addresses critical vulnerabilities from day 1
+4. **Intelligent Learning Integration** - Continuous improvement throughout development
+5. **Module Constellation Architecture** - Scalable, maintainable codebase
+
+**This roadmap transforms the V3 implementation from high-risk aggressive targets to a controlled, strategic rollout that delivers exceptional results with managed risk.**
+
+---
+
+*Implementation Roadmap - Version 1.0*
+*Created: 2026-01-04*
+*Next Review: Weekly during implementation*