@tangle-network/starter-foundry 0.5.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/starter-foundry",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Deterministic project scaffold engine for AI coding platforms",
   "type": "module",
   "license": "MIT",
@@ -35,10 +35,27 @@
   "bin": {
     "starter-foundry": "./dist/cli.js"
   },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@tangle-network/agent-eval": "^0.7.0",
+    "@types/node": "^20.0.0",
+    "knip": "^6.6.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "@ax-llm/ax": "^19.0.45",
+    "@huggingface/transformers": "^4.0.0",
+    "@tangle-network/tcloud": "^0.4.2"
+  },
+  "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "tsc",
-    "test": "tsc && tsc -p tsconfig.test.json && node --test dist-tests/*.test.js",
+    "pretest": "node scripts/check-toolchain.mjs && node scripts/ensure-test-fixtures.mjs",
+    "test": "tsc && tsc -p tsconfig.test.json && node --test --test-concurrency=1 dist-tests/*.test.js",
     "catalog": "node dist/cli.js catalog",
     "select": "node dist/cli.js select",
     "compose": "node dist/cli.js compose",
@@ -55,16 +72,42 @@
     "release": "node dist/cli.js release",
     "sync:warm-list": "node scripts/sync-warm-list.mjs",
     "sync:warm-list:write": "node scripts/sync-warm-list.mjs --write",
-    "audit:visual": "node scripts/visual-audit.mjs"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.7.0"
-  },
-  "dependencies": {
-    "@huggingface/transformers": "^4.0.0"
+    "audit:visual": "node scripts/visual-audit.mjs",
+    "validate:registry": "node scripts/validate-registry.mjs",
+    "new:family": "node scripts/new-family.mjs",
+    "new:capability": "node scripts/new-capability.mjs",
+    "new:partner": "node scripts/new-partner.mjs",
+    "repl": "node scripts/repl.mjs",
+    "watch": "node scripts/watch.mjs",
+    "docs:gen": "node scripts/generate-docs.mjs",
+    "scorecard": "node scripts/refresh-scorecard.mjs",
+    "measure:refresh": "node scripts/measure-refresh.mjs",
+    "measure:check": "node scripts/measure-refresh.mjs --dry-run",
+    "setup:hooks": "node scripts/install-git-hooks.mjs",
+    "eval:scaffold": "node scripts/agent-eval-scaffold.mjs",
+    "eval:scaffold:sample": "node scripts/agent-eval-scaffold.mjs --sample 20 --no-judge",
+    "eval:scaffold:structural": "node scripts/agent-eval-scaffold.mjs --no-judge",
+    "changelog": "node scripts/generate-changelog.mjs",
+    "propose:capabilities": "node scripts/propose-capabilities.mjs",
+    "propose:archive-dead": "node scripts/archive-dead-families.mjs",
+    "refresh:partners": "node scripts/refresh-partner-configs.mjs",
+    "trend:archive": "node scripts/archive-scorecard-trend.mjs",
+    "cve:sweep": "node scripts/cve-sweep.mjs",
+    "propose:family": "node scripts/propose-family.mjs",
+    "propose:family-candidates": "node scripts/propose-family-candidates.mjs",
+    "propose:capability-candidates": "node scripts/propose-capability-candidates.mjs",
+    "detect:family-gaps": "node scripts/detect-family-gaps.mjs",
+    "detect:capability-gaps": "node scripts/detect-capability-gaps.mjs",
+    "promote:family-proposal": "node scripts/promote-family-proposal.mjs",
+    "promote:capability-proposal": "node scripts/promote-capability-proposal.mjs",
+    "template:sweep": "node scripts/template-quality-sweep.mjs",
+    "template:open-prs": "node scripts/open-template-prs.mjs",
+    "template:regression-watch": "node scripts/template-regression-watcher.mjs",
+    "trend:pass-rate": "node scripts/family-pass-rate-trend.mjs",
+    "dep:cascade": "node scripts/dep-cascade-detector.mjs",
+    "sla:probe": "node scripts/sla-probe.mjs",
+    "sla:rollup": "node scripts/sla-rollup.mjs",
+    "rollback:version": "node scripts/rollback-version.mjs",
+    "gen:types": "node scripts/gen-types-from-schemas.mjs"
   }
-}
+}

package/registry/_mirrors.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "mirrors": [
+    {
+      "url": "https://raw.githubusercontent.com/tangle-network/starter-foundry/main/registry-bundle.json",
+      "region": "global",
+      "priority": 1,
+      "notes": "GitHub raw — canonical source of truth"
+    },
+    {
+      "url": "https://cdn.jsdelivr.net/gh/tangle-network/starter-foundry@main/registry-bundle.json",
+      "region": "global",
+      "priority": 2,
+      "notes": "jsDelivr auto-mirrors GitHub with global CDN; 1-minute TTL typical"
+    },
+    {
+      "url": "https://unpkg.com/@tangle-network/starter-foundry/registry-bundle.json",
+      "region": "global",
+      "priority": 3,
+      "notes": "unpkg — pulls from npm; requires a published release with the bundle"
+    },
+    {
+      "url": "https://starter-foundry.tangle.network/registry-bundle.json",
+      "region": "global",
+      "priority": 4,
+      "notes": "Cloudflare R2 mirror — fallback when the above are blocked or degraded"
+    }
+  ]
+}

package/registry/_schemas/buildhints.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "buildhints.schema.json",
+  "title": "BuildHints",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "pages": { "type": "array", "items": { "type": "string" } },
+    "apiRoutes": { "type": "array", "items": { "type": "string" } },
+    "components": { "type": "array", "items": { "type": "string" } },
+    "dataModels": { "type": "array", "items": { "type": "string" } },
+    "integrations": { "type": "array", "items": { "type": "string" } },
+    "architectureNotes": { "type": "array", "items": { "type": "string" } },
+    "firstSteps": { "type": "array", "items": { "type": "string" } },
+    "gotchas": { "type": "array", "items": { "type": "string" } },
+    "whenToUse": { "type": "string" },
+    "placeholders": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string" },
+          "description": { "type": "string", "minLength": 20 }
+        }
+      }
+    }
+  }
+}

package/registry/_schemas/family.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "family.schema.json",
+  "title": "FamilyManifest",
+  "type": "object",
+  "required": ["id", "description", "tags"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 20 },
+    "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "taxonomy": {
+      "type": "object",
+      "properties": {
+        "language": { "type": "string" },
+        "runtime": { "type": "string" },
+        "surface": { "type": "string" }
+      }
+    },
+    "slots": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "options": { "type": "array", "items": { "type": "string" } },
+          "default": { "type": "string" }
+        }
+      }
+    },
+    "requires": { "type": "array", "items": { "type": "string" } },
+    "defaults": { "type": "object" },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target"],
+        "properties": {
+          "source": { "type": "string" },
+          "target": { "type": "string" }
+        }
+      }
+    },
+    "validationChecks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type"],
+        "properties": {
+          "type": { "enum": ["file-exists", "node-syntax", "http-start", "command-success", "python-compile"] },
+          "path": { "type": "string" },
+          "command": { "type": "array", "items": { "type": "string" } },
+          "expect": { "type": "string" },
+          "env": { "type": "object" },
+          "port": { "type": "string" },
+          "runOnce": { "type": "boolean" }
+        }
+      }
+    },
+    "contextHints": {
+      "type": "object",
+      "properties": {
+        "commands": { "type": "array", "items": { "type": "string" } },
+        "entrypoints": { "type": "array", "items": { "type": "string" } },
+        "preview": {
+          "type": ["object", "null"],
+          "properties": {
+            "path": { "type": "string" },
+            "port": { "type": ["string", "number"] }
+          }
+        },
+        "extensionPoints": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "tieredKeywords": {
+      "type": "object",
+      "properties": {
+        "tier1": { "type": "array", "items": { "type": "string" } },
+        "tier2": { "type": "array", "items": { "type": "string" } },
+        "tier3": { "type": "array", "items": { "type": "string" } },
+        "archetypes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "scoring": {
+      "type": "object",
+      "properties": {
+        "boost": { "type": "object", "additionalProperties": { "type": "number" } }
+      }
+    },
+    "buildHints": { "$ref": "buildhints.schema.json" }
+  }
+}

package/registry/_schemas/layer.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "layer.schema.json",
+  "title": "LayerManifest",
+  "type": "object",
+  "required": ["id", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 20 },
+    "group": { "type": "string" },
+    "slot": { "type": "string" },
+    "appliesTo": { "type": "array", "items": { "type": "string" } },
+    "defaults": { "type": "object" },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target"],
+        "properties": {
+          "source": { "type": "string" },
+          "target": { "type": "string" }
+        }
+      }
+    },
+    "validationChecks": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "contextHints": {
+      "type": "object",
+      "properties": {
+        "commands": { "type": "array", "items": { "type": "string" } },
+        "entrypoints": { "type": "array", "items": { "type": "string" } },
+        "extensionPoints": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "tieredKeywords": {
+      "type": "object",
+      "properties": {
+        "tier1": { "type": "array", "items": { "type": "string" } },
+        "tier2": { "type": "array", "items": { "type": "string" } },
+        "tier3": { "type": "array", "items": { "type": "string" } },
+        "archetypes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "capabilityRequires": { "type": "array", "items": { "type": "string" } },
+    "variants": { "type": "array", "items": { "type": "string" } },
+    "buildHints": { "$ref": "buildhints.schema.json" },
+    "packageDeps": {
+      "type": "object",
+      "properties": {
+        "dependencies": { "type": "object", "additionalProperties": { "type": "string" } },
+        "devDependencies": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    }
+  }
+}

package/registry/_schemas/partner.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "partner.schema.json",
+  "title": "PartnerManifest",
+  "type": "object",
+  "required": ["id", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 20 },
+    "appliesTo": { "type": "array", "items": { "type": "string" } },
+    "defaults": { "type": "object" },
+    "slotDefaults": { "type": "object", "additionalProperties": { "type": "string" } },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target"],
+        "properties": {
+          "source": { "type": "string" },
+          "target": { "type": "string" }
+        }
+      }
+    },
+    "buildHints": { "$ref": "buildhints.schema.json" }
+  }
+}

package/registry/families/agent-service-py/manifest.json

@@ -155,5 +155,14 @@
       "sentiment analyzer",
       "opinion mining"
     ]
+  },
+  "scoring": {
+    "boost": {
+      "crewai": 4,
+      "pydanticai": 4,
+      "autogen": 4,
+      "agno": 3,
+      "llamaindex": 3
+    }
   }
 }

package/registry/families/agent-service-ts/files/package.json

@@ -4,5 +4,13 @@
   "type": "module",
   "scripts": {
     "start": "node agent.mjs"
+  },
+  "overrides": {
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.4.2"
+    }
   }
 }

package/registry/families/agent-service-ts/manifest.json

@@ -172,10 +172,7 @@
       "openai agents",
       "openai agents sdk",
       "typescript agent",
-      "langchain",
-      "multi-agent",
-      "multi agent",
-      "supervisor agent"
+      "langchain"
     ],
     "tier2": [
       "ai agent",

package/registry/families/agent-swarm-ts/files/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "tsx src/server.ts",
+    "test": "vitest run",
+    "validate": "node validate-swarm.mjs"
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.0",
+    "@langchain/langgraph": "^0.2.0",
+    "@langchain/openai": "^0.3.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.0"
+  },
+  "overrides": {
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.4.2"
+    }
+  }
+}

package/registry/families/agent-swarm-ts/files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowJs": true,
+    "lib": ["ESNext"]
+  },
+  "include": ["src/**/*.ts", "validate-swarm.mjs"]
+}

package/registry/families/agent-swarm-ts/files/validate-swarm.mjs

@@ -0,0 +1,28 @@
+import fs from "node:fs/promises";
+
+const [supervisor, researcher, writer, pkgSource] = await Promise.all([
+  fs.readFile("src/supervisor.ts", "utf8"),
+  fs.readFile("src/agents/researcher.ts", "utf8"),
+  fs.readFile("src/agents/writer.ts", "utf8"),
+  fs.readFile("package.json", "utf8"),
+]);
+
+const pkg = JSON.parse(pkgSource);
+if (pkg.name !== "{{packageName}}") {
+  throw new Error(`package.json name should be "{{packageName}}", got "${pkg.name}"`);
+}
+if (!pkg.dependencies?.["@langchain/langgraph"]) {
+  throw new Error("package.json missing @langchain/langgraph — swarm needs the orchestrator");
+}
+
+if (!supervisor.includes("StateGraph") && !supervisor.includes("createSupervisor")) {
+  throw new Error("src/supervisor.ts missing LangGraph StateGraph or createSupervisor call");
+}
+if (!researcher.includes("export")) {
+  throw new Error("src/agents/researcher.ts must export the researcher agent");
+}
+if (!writer.includes("export")) {
+  throw new Error("src/agents/writer.ts must export the writer agent");
+}
+
+console.log("agent-swarm-ts starter ok");

package/registry/families/agent-swarm-ts/manifest.json

@@ -0,0 +1,174 @@
+{
+  "id": "agent-swarm-ts",
+  "description": "Multi-agent swarm family \u2014 supervisor/worker orchestration with shared state, tool-routing, and handoff protocols. Based on LangGraph state machines or CrewAI role-based crews. For products where one LLM call isn't enough: research assistants that delegate to search/code/analysis sub-agents, customer support with triage + specialist agents, document pipelines with extract/analyze/summarize roles.",
+  "tags": [
+    "agent",
+    "multi-agent",
+    "swarm",
+    "langgraph",
+    "crewai",
+    "supervisor",
+    "typescript"
+  ],
+  "taxonomy": {
+    "language": "typescript",
+    "runtime": "node",
+    "surface": "api"
+  },
+  "slots": {
+    "database": {
+      "options": [
+        "database:sqlite",
+        "database:postgres",
+        "database:mongodb",
+        "database:convex"
+      ],
+      "default": "database:postgres"
+    },
+    "auth": {
+      "options": [
+        "auth:none",
+        "auth:better-auth",
+        "auth:clerk"
+      ],
+      "default": "auth:none"
+    }
+  },
+  "defaults": {
+    "projectType": "multi-agent",
+    "serviceName": "starter-foundry-swarm",
+    "port": 8098,
+    "orchestrator": "langgraph"
+  },
+  "files": [
+    {
+      "source": "files/package.json",
+      "target": "package.json"
+    },
+    {
+      "source": "files/tsconfig.json",
+      "target": "tsconfig.json"
+    },
+    {
+      "source": "files/validate-swarm.mjs",
+      "target": "validate-swarm.mjs"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/supervisor.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/agents/researcher.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/agents/writer.ts"
+    },
+    {
+      "type": "command-success",
+      "command": [
+        "node",
+        "validate-swarm.mjs"
+      ],
+      "expect": "agent-swarm-ts starter ok"
+    }
+  ],
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm run dev",
+      "pnpm test"
+    ],
+    "entrypoints": [
+      "src/supervisor.ts",
+      "src/agents/",
+      "src/state.ts",
+      "package.json"
+    ],
+    "preview": {
+      "path": "/health"
+    },
+    "extensionPoints": [
+      "src/agents/",
+      "src/state.ts",
+      "src/tools/"
+    ]
+  },
+  "keywords": [
+    "multi-agent",
+    "multi agent",
+    "agent swarm",
+    "supervisor agent",
+    "langgraph-js",
+    "langgraphjs",
+    "typescript multi-agent",
+    "agent handoff",
+    "specialist agents",
+    "agent team",
+    "role-based agents"
+  ],
+  "scoring": {
+    "boost": {
+      "langgraph-js": 3
+    }
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "multi-agent",
+      "multi agent",
+      "agent swarm",
+      "langgraph-js",
+      "langgraphjs",
+      "typescript multi-agent"
+    ],
+    "tier2": [
+      "supervisor agent",
+      "agent handoff",
+      "specialist agents",
+      "agent team"
+    ],
+    "archetypes": [
+      "research assistant with sub-agents",
+      "triage and specialist support",
+      "document pipeline agents",
+      "planner and executor agents"
+    ]
+  },
+  "buildHints": {
+    "whenToUse": "Multi-agent orchestration with supervisor/worker handoffs. Use when ONE LLM call isn't enough \u2014 research agents that delegate to search/analyze/summarize roles, triage+specialist support, document pipelines. For a single agent with tool use, use `agent-service-ts` instead.",
+    "firstSteps": [
+      "Set the router API key: `export OPENAI_API_KEY=$TANGLE_ROUTER_KEY` \u2014 agents call via router.tangle.tools, NOT OpenAI directly.",
+      "Add a new specialist: create `src/agents/<name>.ts` exporting a `run<Name>(state)` function. Register it in supervisor.ts's node graph.",
+      "Extend `SwarmState` in src/state.ts when adding fields the new agent reads/writes. Use the Annotation<T>({ reducer }) pattern \u2014 reducers determine how updates merge.",
+      "The supervisor is rule-based (src/supervisor.ts). Swap to an LLM-driven supervisor by replacing `supervise()` with an LLM call if the routing is non-obvious.",
+      "Test end-to-end: `curl -X POST http://localhost:{{port}}/run -d '{\"task\": \"your task\"}'` \u2014 kicks off researcher \u2192 writer."
+    ],
+    "gotchas": [
+      "LangGraph's Annotation reducers fire on EVERY state update. Accidentally returning {messages: state.messages} duplicates history. Return only the FIELDS you're changing.",
+      "The `END` marker terminates the graph. The supervisor must set `nextAgent: \"END\"` when work is done \u2014 otherwise the graph loops forever.",
+      "ChatOpenAI needs `configuration.baseURL` set to router.tangle.tools \u2014 without it calls go to api.openai.com and fail/cost unexpectedly.",
+      "Shared state = tight coupling. If a new agent needs a field that no other agent reads, DON'T put it in SwarmState \u2014 use private module-scope instead."
+    ],
+    "architectureNotes": [
+      "StateGraph flow: START \u2192 supervisor \u2192 (researcher | writer | END). Each specialist edges back to supervisor, enabling re-routing.",
+      "LangGraph checkpointing (MemorySaver, SqliteSaver) lets you pause/resume sessions. Enable via `graph.compile({ checkpointer })` for long-running workflows."
+    ],
+    "placeholders": [
+      {
+        "path": "src/agents/researcher.ts",
+        "description": "Placeholder researcher agent returning generic bullet notes. Replace system prompt + tool surface for the product's actual research domain."
+      },
+      {
+        "path": "src/agents/writer.ts",
+        "description": "Placeholder writer converting notes to prose. Replace system prompt for the product's target voice/format."
+      },
+      {
+        "path": "src/supervisor.ts",
+        "description": "Rule-based supervisor (has-notes? \u2192 writer; else \u2192 researcher). Replace with product-specific routing or an LLM-driven supervisor for non-linear flows."
+      }
+    ]
+  }
+}

package/registry/families/angular-ts/files/package.json

@@ -12,5 +12,13 @@
   "devDependencies": {
     "@angular/cli": "^19.0.0",
     "@angular/compiler-cli": "^19.0.0"
+  },
+  "overrides": {
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.4.2"
+    }
   }
 }