@dragonflymcp/plugin 1.0.0

package/dist/utils/vectors.test.js

@@ -0,0 +1,96 @@
+/**
+ * Vector Utilities Tests
+ * Tests for embedding operations and serialization
+ */
+import { describe, it, expect } from 'vitest';
+import { cosineSimilarity, numberArrayToBytes, bytesToNumberArray, } from './vectors.js';
+describe('Vector Utilities', () => {
+    describe('cosineSimilarity', () => {
+        it('should return 1 for identical vectors', () => {
+            const v = [1, 2, 3, 4, 5];
+            expect(cosineSimilarity(v, v)).toBeCloseTo(1.0, 5);
+        });
+        it('should return 0 for orthogonal vectors', () => {
+            const v1 = [1, 0, 0];
+            const v2 = [0, 1, 0];
+            expect(cosineSimilarity(v1, v2)).toBeCloseTo(0.0, 5);
+        });
+        it('should return -1 for opposite vectors', () => {
+            const v1 = [1, 2, 3];
+            const v2 = [-1, -2, -3];
+            expect(cosineSimilarity(v1, v2)).toBeCloseTo(-1.0, 5);
+        });
+        it('should handle normalized vectors correctly', () => {
+            // Two unit vectors at 60 degrees
+            const v1 = [1, 0];
+            const v2 = [0.5, Math.sqrt(3) / 2];
+            expect(cosineSimilarity(v1, v2)).toBeCloseTo(0.5, 5);
+        });
+        it('should handle high-dimensional vectors', () => {
+            const dim = 384; // MiniLM dimension
+            const v1 = new Array(dim).fill(0).map(() => Math.random());
+            const v2 = v1.map(x => x * 1.5); // Scaled version
+            // Scaled vectors should have similarity 1
+            expect(cosineSimilarity(v1, v2)).toBeCloseTo(1.0, 5);
+        });
+        it('should be symmetric', () => {
+            const v1 = [1, 2, 3, 4];
+            const v2 = [4, 3, 2, 1];
+            expect(cosineSimilarity(v1, v2)).toBeCloseTo(cosineSimilarity(v2, v1), 10);
+        });
+        it('should handle zero vectors gracefully', () => {
+            const v1 = [0, 0, 0];
+            const v2 = [1, 2, 3];
+            const result = cosineSimilarity(v1, v2);
+            expect(Number.isNaN(result) || result === 0).toBe(true);
+        });
+    });
+    describe('numberArrayToBytes and bytesToNumberArray', () => {
+        it('should round-trip small arrays', () => {
+            const original = [1.5, -2.3, 0.0, 100.123];
+            const bytes = numberArrayToBytes(original);
+            const recovered = bytesToNumberArray(bytes);
+            expect(recovered.length).toBe(original.length);
+            original.forEach((val, i) => {
+                expect(recovered[i]).toBeCloseTo(val, 5);
+            });
+        });
+        it('should round-trip large arrays (embedding size)', () => {
+            const original = new Array(384).fill(0).map(() => Math.random() * 2 - 1);
+            const bytes = numberArrayToBytes(original);
+            const recovered = bytesToNumberArray(bytes);
+            expect(recovered.length).toBe(original.length);
+            original.forEach((val, i) => {
+                expect(recovered[i]).toBeCloseTo(val, 5);
+            });
+        });
+        it('should produce correct byte size', () => {
+            const arr = [1, 2, 3, 4, 5];
+            const bytes = numberArrayToBytes(arr);
+            // Float32 = 4 bytes per number
+            expect(bytes.length).toBe(arr.length * 4);
+        });
+        it('should handle empty arrays', () => {
+            const original = [];
+            const bytes = numberArrayToBytes(original);
+            const recovered = bytesToNumberArray(bytes);
+            expect(recovered.length).toBe(0);
+        });
+        it('should handle special values', () => {
+            const original = [Number.MAX_VALUE / 2, Number.MIN_VALUE * 2, 0, -0];
+            const bytes = numberArrayToBytes(original);
+            const recovered = bytesToNumberArray(bytes);
+            // Float32 has limited precision, so we use looser comparison
+            expect(recovered.length).toBe(original.length);
+        });
+        it('should handle negative numbers', () => {
+            const original = [-1, -0.5, -100, -0.001];
+            const bytes = numberArrayToBytes(original);
+            const recovered = bytesToNumberArray(bytes);
+            original.forEach((val, i) => {
+                expect(recovered[i]).toBeCloseTo(val, 5);
+            });
+        });
+    });
+});
+//# sourceMappingURL=vectors.test.js.map

package/dist/utils/vectors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectors.test.js","sourceRoot":"","sources":["../../src/utils/vectors.test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;YAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1B,MAAM,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAChD,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACrB,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACrB,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;YAC/C,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACrB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;YACpD,iCAAiC;YACjC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAClB,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACnC,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAChD,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,mBAAmB;YACpC,MAAM,EAAE,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAC3D,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,iBAAiB;YAElD,0CAA0C;YAC1C,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;YAC7B,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAExB,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;YAC/C,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACrB,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAErB,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACxC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACzD,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;YACxC,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YAC3C,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAE5C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/C,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;gBAC1B,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;YACzD,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YACzE,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAE5C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/C,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;gBAC1B,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;YAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC5B,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YAEtC,+BAA+B;YAC/B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;YACpC,MAAM,QAAQ,GAAa,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAE5C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACtC,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACrE,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAE5C,6DAA6D;YAC7D,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;YACxC,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;YAC1C,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAE5C,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;gBAC1B,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@dragonflymcp/plugin",
+  "version": "1.0.0",
+  "description": "Dragonfly MCP Plugin — Sonnet-optimized code intelligence, memory, and workflow tools",
+  "main": "dist/index.js",
+  "type": "module",
+  "files": [
+    "dist/",
+    "templates/",
+    "scripts/",
+    ".claude-plugin/"
+  ],
+  "bin": {
+    "dragonfly-init": "./scripts/init.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "postinstall": "node scripts/init.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "better-sqlite3": "^11.10.0",
+    "fast-glob": "^3.3.3",
+    "web-tree-sitter": "^0.24.7",
+    "tree-sitter-wasms": "^0.1.13",
+    "@huggingface/transformers": "^3.8.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.19.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.0",
+    "eslint": "^9.39.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Michael Kolb",
+    "url": "https://github.com/mkolb22"
+  },
+  "homepage": "https://github.com/mkolb22/dragonfly-plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mkolb22/dragonfly-plugin.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "ast",
+    "semantic-search",
+    "test-generation",
+    "code-repair",
+    "claude-code",
+    "dragonfly",
+    "sonnet"
+  ]
+}

package/scripts/init.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * dragonfly-init — one-shot setup for consuming projects
+ *
+ * Run from the project root after installing @dragonflymcp/plugin:
+ *   npx dragonfly-init
+ *
+ * Steps:
+ *   1. Write .mcp.json
+ *   2. Copy agents → .claude/agents/
+ *   3. Copy skills → .claude/skills/  (strip .template suffix)
+ *   4. Copy commands → .claude/commands/ (strip .template suffix)
+ *   5. Copy hooks → .claude/hooks/     (strip .template suffix, chmod +x *.sh)
+ *   6. Copy hooks/lib → .claude/hooks/lib/
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, basename, resolve } from 'path';
+import {
+  existsSync, mkdirSync, copyFileSync, chmodSync,
+  readdirSync, cpSync, writeFileSync,
+} from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, '..');   // node_modules/@dragonflymcp/plugin
+
+// When running as a postinstall hook, npm sets INIT_CWD to the directory
+// where `npm install` was invoked (the consuming project root). Use it
+// preferentially over cwd(), which points to the package dir inside node_modules.
+const projectRoot = process.env.INIT_CWD ?? process.cwd();
+
+// Guard: skip if we'd be writing into our own package (dev npm install).
+if (projectRoot === pkgRoot || resolve(projectRoot) === resolve(pkgRoot)) {
+  process.exit(0);
+}
+
+function ensure(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function log(msg) {
+  process.stdout.write(msg + '\n');
+}
+
+// ── Step 1: .mcp.json ────────────────────────────────────────────────────────
+const mcpPath = join(projectRoot, '.mcp.json');
+if (existsSync(mcpPath)) {
+  log(`[skip] .mcp.json already exists — review manually if needed`);
+} else {
+  const mcpConfig = {
+    mcpServers: {
+      dragonfly: {
+        type: 'stdio',
+        command: 'node',
+        args: [
+          '--no-wasm-tier-up',
+          '--liftoff-only',
+          'node_modules/@dragonflymcp/plugin/dist/index.js',
+        ],
+      },
+    },
+  };
+  writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+  log(`[write] .mcp.json`);
+}
+
+// ── Step 2: Agents ───────────────────────────────────────────────────────────
+const agentsSrc = join(pkgRoot, 'templates', 'agents');
+const agentsDst = join(projectRoot, '.claude', 'agents');
+ensure(agentsDst);
+let agentCount = 0;
+for (const file of readdirSync(agentsSrc)) {
+  if (!file.endsWith('.md')) continue;
+  const dst = join(agentsDst, file);
+  if (!existsSync(dst)) {
+    copyFileSync(join(agentsSrc, file), dst);
+    agentCount++;
+  }
+}
+log(`[agents] ${agentCount} copied → .claude/agents/`);
+
+// ── Step 3: Skills ───────────────────────────────────────────────────────────
+const skillsSrc = join(pkgRoot, 'templates', 'skills');
+const skillsDst = join(projectRoot, '.claude', 'skills');
+ensure(skillsDst);
+let skillCount = 0;
+for (const file of readdirSync(skillsSrc)) {
+  if (!file.endsWith('.md.template')) continue;
+  const dstName = basename(file, '.template'); // strip .template → keep .md
+  const dst = join(skillsDst, dstName);
+  if (!existsSync(dst)) {
+    copyFileSync(join(skillsSrc, file), dst);
+    skillCount++;
+  }
+}
+log(`[skills] ${skillCount} copied → .claude/skills/`);
+
+// ── Step 4: Commands ─────────────────────────────────────────────────────────
+const commandsSrc = join(pkgRoot, 'templates', 'commands');
+const commandsDst = join(projectRoot, '.claude', 'commands');
+ensure(commandsDst);
+let commandCount = 0;
+for (const file of readdirSync(commandsSrc)) {
+  if (!file.endsWith('.md.template')) continue;
+  const dstName = basename(file, '.template');
+  const dst = join(commandsDst, dstName);
+  if (!existsSync(dst)) {
+    copyFileSync(join(commandsSrc, file), dst);
+    commandCount++;
+  }
+}
+log(`[commands] ${commandCount} copied → .claude/commands/`);
+
+// ── Step 5: Hooks ────────────────────────────────────────────────────────────
+const hooksSrc = join(pkgRoot, 'templates', 'hooks');
+const hooksDst = join(projectRoot, '.claude', 'hooks');
+ensure(hooksDst);
+let hookCount = 0;
+for (const file of readdirSync(hooksSrc)) {
+  if (!file.endsWith('.template')) continue;
+  const dstName = basename(file, '.template');
+  const dst = join(hooksDst, dstName);
+  if (!existsSync(dst)) {
+    copyFileSync(join(hooksSrc, file), dst);
+    if (dstName.endsWith('.sh')) {
+      chmodSync(dst, 0o755);
+    }
+    hookCount++;
+  }
+}
+log(`[hooks] ${hookCount} copied → .claude/hooks/`);
+
+// ── Step 6: hooks/lib ────────────────────────────────────────────────────────
+const libSrc = join(hooksSrc, 'lib');
+const libDst = join(hooksDst, 'lib');
+if (existsSync(libSrc) && !existsSync(libDst)) {
+  cpSync(libSrc, libDst, { recursive: true });
+  log(`[hooks/lib] copied → .claude/hooks/lib/`);
+}
+
+// ── Done ─────────────────────────────────────────────────────────────────────
+log(`\nDragonfly setup complete. Restart Claude Code to activate the MCP server.`);

package/templates/CLAUDE.md.template

@@ -0,0 +1,96 @@
+<!-- zen:managed:start - DO NOT EDIT (regenerated by .zen/install.sh) -->
+
+## How to Work on This Project
+
+**These are standing orders, not suggestions. Follow them without being prompted.**
+
+### Before Writing Code
+
+1. **Index the codebase** (`index_project`) on affected packages. Then use `get_call_graph`, `find_references`, and `find_implementations` to understand call chains, blast radius, and interface contracts before changing anything.
+2. **Check existing specs** (`zen_spec_list`, `zen_spec_get`). If a spec covers the area you're modifying, use its contracts to validate your implementation. If no spec exists for a significant module, create one with `zen_spec_save`.
+3. **Search for patterns** (`semantic_search`, `find_similar_code`). Find related implementations already in the codebase. If semantic search returns nothing, run `embed_project` first. Don't reinvent what exists.
+4. **Read before writing**. Use `get_symbol_info` with `includeBody: true` to inspect specific symbols. Never propose changes to code you haven't read.
+
+### While Writing Code
+
+Apply these patterns in every module, on the first pass — not as a second-pass optimization:
+
+- **Cache clients and connections**: Any SDK client, DB handle, or connection created in a hot path must be cached and reused. Never create-and-close per call.
+- **Bound all collections**: Every map or list that grows with user data must have a cleanup/eviction path. If an entry is created on add, it must be deleted on remove.
+- **Pre-allocate**: When the capacity is known or estimable, pre-allocate collections.
+- **Conditional writes**: Don't write to DB/store when the value hasn't changed. Compare before writing.
+- **Limit input**: All external input (HTTP bodies, webhook payloads) must be size-limited.
+- **Thread parsed data**: If a value is parsed/deserialized, pass it through the call chain. Never re-parse.
+- **No duplication**: If logic exists in a helper, call it. Don't inline a copy.
+
+### After Writing Code
+
+1. **Build and test** before declaring anything complete.
+2. **Save a checkpoint** (`zen_checkpoint_save`) after completing significant milestones — not just when asked.
+3. **Update memory** (`memory_store`) if you learned something stable about the project (architecture, gotchas, patterns).
+
+### For Features and Multi-Step Work
+
+Use zen workflow tools to structure work:
+- `zen_start_workflow` for new features — plans steps and assigns models
+- `zen_advance_workflow` to move through phases
+- `zen_get_concept` to load phase-specific instructions (story, architecture, implementation, quality)
+- `zen_story_save` / `zen_story_get` to capture and retrieve requirements
+- `zen_spec_save` / `zen_spec_generate` to define contracts and generate code from specs
+
+Don't skip phases. The story phase catches requirement gaps. The architecture phase catches design issues. The quality phase catches bugs. Each phase exists because skipping it has cost rework.
+
+### What This Means in Practice
+
+If the user says "add feature X", the response is NOT to start writing code. It is:
+1. Index the codebase (`index_project`, `embed_project`)
+2. Search for related patterns (`semantic_search`, `find_symbol`, `find_similar_code`)
+3. Understand the call graph (`get_call_graph`, `find_references`, `find_implementations`)
+4. Check/create specs (`zen_spec_list`, `zen_spec_save`)
+5. Plan the approach, then implement — applying the code quality standards above on the first pass
+
+The tools were built for you. Use them.
+
+## After Auto-Compact
+
+After context compression (auto-compact), always:
+- Read `CLAUDE.md` to restore project context
+- Run `zen_checkpoint_restore` with `latest: true` to reload pending work
+- Use `memory_recall` to retrieve relevant project knowledge
+
+## Critical: .zen/ is Read-Only
+
+The `.zen/` directory is a **read-only git submodule**. NEVER edit, create, or delete files in `.zen/`.
+
+## Available Commands
+
+- `/feature "description"` - Start a new feature workflow
+- `/workflow "description"` - Full automatic workflow
+- `/health` - Check context health status
+- `/checkpoint` - Save session state
+- `/restore` - Restore from checkpoint
+- `/remember "fact"` - Store in semantic memory
+- `/recall query` - Retrieve memories
+
+<!-- zen:managed:end -->
+
+# ${PROJECT_NAME}
+
+> Powered by [Zen](https://github.com/mkolb22/zen) - Self-evolving architecture with persistent memory and multi-tier model optimization.
+
+## Project Description
+
+_Describe your project here._
+
+## Build Commands
+
+```bash
+# Add your build commands here
+```
+
+## Repository Structure
+
+_Add your project structure here._
+
+---
+*Zen installed: ${TIMESTAMP}*

package/templates/agents/architecture-concept.md

@@ -0,0 +1,237 @@
+---
+name: architecture-concept
+type: workflow
+execution: task-tool
+model: sonnet
+color: purple
+description: Architecture Concept - Designs system architecture and makes technical decisions using Sonnet for high-quality trade-off analysis
+tools: "*"
+
+# Enhanced Metadata (Phase 3)
+cost_per_action: 0.003
+optimization_level: "phase2"
+expected_context_tokens: 1100
+baseline_context_tokens: 100000
+context_reduction: "99%"
+expected_duration_seconds: 15
+---
+
+# 🏗️ Architecture Concept
+
+## Model Assignment
+
+**Model**: Sonnet (high-quality architecture design — MAP-Elites evolution proved equivalent to Opus at 5x lower cost)
+**Cost per Action**: ~$0.003
+**Never Calls**: No other concepts (pure design work)
+
+## Core Principle: Structured Trade-Off Analysis
+
+Architecture requires:
+- Complex trade-off analysis
+- Novel problem solving
+- Pattern synthesis across domains
+- Risk evaluation
+- Long-term impact assessment
+
+MAP-Elites evolution (Feb 2026) proved Sonnet produces equivalent or superior architecture output to Opus on complex benchmarks (0.96 vs 0.90), while costing 5x less.
+
+## Actions
+
+### design(story_id, context)
+
+Creates technical architecture for a requirement.
+
+**Inputs**:
+- `story_id`: Reference to the story being architected
+- `context`: Existing system architecture, constraints, patterns
+
+**Process**:
+1. Analyze the requirement and acceptance criteria
+2. **Use INCREMENTAL LOADING with MCP tools** (99% context reduction)
+3. Identify technical approaches (2-3 options)
+4. Evaluate trade-offs for each approach
+5. Select recommended approach with justification
+6. Design component structure, interfaces, data flow
+7. Identify risks and mitigation strategies
+8. Generate technical specifications
+9. Return architecture results to parent workflow
+
+## Incremental Context Loading
+
+Use MCP tools to understand the codebase before designing:
+
+**Stage 1: Overview** — `get_file_symbols` for key files, `find_symbol` to locate components
+**Stage 2: Targeted** — `get_symbol_info` with `includeBody: true` for specific symbols, `find_references` for usage patterns
+**Stage 3: Deep Dive** — Read full files only when stages 1-2 prove insufficient
+
+**Golden Rule**: Never read a full file before checking if MCP tools can answer your question.
+
+## Output Format (YAML with Progressive Disclosure)
+
+```yaml
+id: "arch-001"
+status: "completed"
+estimated_risk: "medium"
+summary: "OAuth2 authentication using passport.js with Google provider"
+
+details:
+  story_id: "story-001"
+
+  approaches_evaluated:
+    - name: "OAuth2 with Passport.js"
+      pros: ["Well-tested library", "Multiple provider support", "Active maintenance"]
+      cons: ["Additional dependency", "Learning curve"]
+      score: 8/10
+
+    - name: "Custom OAuth2 implementation"
+      pros: ["Full control", "No dependencies"]
+      cons: ["Security risk", "Maintenance burden", "Reinventing wheel"]
+      score: 3/10
+
+    - name: "SAML with passport-saml"
+      pros: ["Enterprise-ready", "Strong security"]
+      cons: ["Complex setup", "Overkill for use case"]
+      score: 5/10
+
+  selected_approach:
+    name: "OAuth2 with Passport.js"
+    justification: |
+      Passport.js is battle-tested with 1M+ downloads/week,
+      supports multiple providers, and has strong security practices.
+      The team has experience with it from previous projects.
+
+  technical_design:
+    components:
+      - name: "AuthController"
+        purpose: "Handle OAuth2 flow and callbacks"
+        interfaces: ["POST /auth/google", "GET /auth/google/callback"]
+
+      - name: "PassportStrategy"
+        purpose: "Configure Google OAuth2 strategy"
+        config: ["CLIENT_ID", "CLIENT_SECRET", "CALLBACK_URL"]
+
+      - name: "UserService"
+        purpose: "Create/update user from OAuth profile"
+        methods: ["findOrCreateFromOAuth(profile)"]
+
+    data_flow:
+      - "User clicks 'Sign in with Google'"
+      - "Redirect to Google consent screen"
+      - "Google redirects to /auth/google/callback with code"
+      - "Exchange code for access token"
+      - "Fetch user profile from Google"
+      - "Create/update user in database"
+      - "Generate session token"
+      - "Redirect to dashboard"
+
+    security_considerations:
+      - "Store CLIENT_SECRET in environment variables"
+      - "Validate redirect_uri to prevent open redirects"
+      - "Use HTTPS in production"
+      - "Implement CSRF protection on auth endpoints"
+
+  risks:
+    - risk: "OAuth provider downtime affects login"
+      severity: "medium"
+      mitigation: "Implement fallback to email/password login"
+
+    - risk: "User profile changes at provider"
+      severity: "low"
+      mitigation: "Sync profile on each login, handle missing fields gracefully"
+
+  metadata:
+    created_at: "2025-11-11T10:35:00Z"
+    concept: "architecture"
+    model: "sonnet"
+    cost: 0.003
+    context_tokens: 1100
+```
+
+## State Management
+
+### Progressive Disclosure Pattern
+
+All architecture outputs use the progressive disclosure pattern:
+
+**Summary Section** (first 5 lines):
+- `arch_id`: Unique identifier
+- `status`: Current state (in_progress/completed/blocked)
+- `estimated_risk`: Risk level (low/medium/high)
+- `summary`: One-line description of the selected approach
+
+**Details Section** (loaded on demand):
+- Approaches evaluated with trade-offs
+- Selected approach with justification
+- Complete technical design
+- Component structure and data flow
+- Security considerations
+- Risk assessment and mitigation
+- Metadata and provenance
+
+### State Management
+
+Architecture results are returned to the parent workflow session. Use `zen_event_log` MCP tool for architecture provenance tracking.
+
+### Status Values
+
+- `in_progress`: Design work ongoing
+- `completed`: Architecture finalized, ready for implementation
+- `blocked`: Cannot proceed without external input
+
+## Integration with Synchronizations
+
+The architecture concept is triggered by:
+- Story completion (via `story-to-arch` sync)
+- Direct invocation (`/architecture <story-id>`)
+
+The architecture concept triggers (via synchronizations):
+- `implementation` concept when status = "completed"
+- User notification if status = "blocked"
+
+## Validation Rules
+
+Architecture is "completed" when:
+- [ ] At least 2 approaches evaluated
+- [ ] Selected approach has clear justification
+- [ ] Component structure is defined
+- [ ] Data flow is documented
+- [ ] Security considerations identified
+- [ ] Risks assessed with mitigations
+- [ ] Technical specs are implementable
+
+## Error Handling
+
+If architecture fails:
+1. Save partial state with status="blocked"
+2. Document what information is missing
+3. Return clear error message
+4. Do not trigger implementation concept
+
+## Never Do This
+
+- ❌ Call other concepts directly
+- ❌ Implement any code
+- ❌ Run tests or quality checks
+- ❌ Perform git operations
+- ❌ Read entire codebase (use MCP tools)
+- ❌ Skip incremental loading stages
+
+## Always Do This
+
+- ✅ Use Sonnet model
+- ✅ Use MCP tools before reading full files
+- ✅ Evaluate multiple approaches
+- ✅ Document trade-offs and reasoning
+- ✅ Return structured results to parent workflow
+- ✅ Use progressive disclosure format
+- ✅ Track context usage in metadata
+- ✅ Follow YAML safety rules (see below)
+
+## YAML Safety Rules
+
+All YAML output MUST follow these rules to prevent silent parse failures:
+
+1. **Quote strings containing special characters.** Any string with `@`, `#`, `:`, `{`, `[`, `"`, `!`, `*`, `&`, `|`, `>`, or `%` must be wrapped in double quotes with inner quotes escaped.
+2. **Avoid nested quotes in unquoted list items.** If a list item (`- ...`) contains embedded double quotes, wrap the entire value in double quotes and escape the inner quotes, or remove the inner quotes.
+3. **Use block scalars for long text.** Multi-line strings and strings with special characters should use `|` (literal) or `>` (folded) block scalar syntax.
+4. **Validate output parses.** Before saving, mentally verify the YAML is valid — unquoted `@scope/package` or unmatched `"` will cause silent load failures downstream.