open-agents-ai 0.187.497 → 0.187.498

package/dist/index.js

@@ -255310,6 +255310,281 @@ var init_working_notes = __esm({
   }
 });
 
+// packages/execution/dist/tools/project-scaffolding.js
+function detectShape(task) {
+  const lower = task.toLowerCase();
+  if (/\b(cli|command[ -]line|terminal app)\b/.test(lower))
+    return "cli";
+  if (/\b(library|sdk|public api package)\b/.test(lower))
+    return "library";
+  if (/\b(pipeline|etl|data flow|stream processing)\b/.test(lower))
+    return "pipeline";
+  if (/\b(game|game loop|gameplay)\b/.test(lower))
+    return "game";
+  if (/\b(compiler|interpreter|lexer|parser|language|syntax)\b/.test(lower))
+    return "compiler";
+  if (/\b(frontend|ui|page|browser|dashboard|chat|app|website|spa)\b/.test(lower))
+    return "web-app";
+  return "service";
+}
+function defaultVerifyCommands(shape) {
+  switch (shape) {
+    case "library":
+      return [
+        "test suite passes (e.g. `npm test`, `pytest`, `cargo test`) — exit 0",
+        "type check / static analysis passes — exit 0",
+        "package builds without errors — exit 0"
+      ];
+    case "cli":
+      return [
+        "test suite passes — exit 0",
+        "build produces a runnable binary or script — exit 0",
+        "smoke test: `<binary> --help` exits 0 with usage text"
+      ];
+    case "pipeline":
+      return [
+        "test suite passes (incl. property tests for idempotency) — exit 0",
+        "end-to-end fixture run succeeds — exit 0"
+      ];
+    case "game":
+      return [
+        "test suite passes — exit 0",
+        "headless / smoke run completes one full update tick — exit 0"
+      ];
+    case "compiler":
+      return [
+        "test suite passes (incl. example-program eval tests) — exit 0",
+        "build / compile of the compiler itself — exit 0"
+      ];
+    default:
+      return [
+        "test suite passes — exit 0",
+        "type check / lint passes — exit 0",
+        "build produces a working artifact — exit 0"
+      ];
+  }
+}
+function bulletList(items, fallback = "(none specified)") {
+  if (!items || items.length === 0)
+    return `  ${fallback}`;
+  return items.map((i2) => `  - ${i2}`).join("\n");
+}
+function renderSections(shape) {
+  const sections = SHAPE_SECTIONS[shape];
+  return sections.map(([title, hint], i2) => ` ${(i2 + 1).toString().padStart(2, " ")}. **${title}** — ${hint}`).join("\n");
+}
+function buildScaffoldedPrompt(args) {
+  const task = (args.task || "").trim();
+  if (task.length === 0) {
+    throw new Error("project_scaffolding: 'task' is required and must be non-empty");
+  }
+  const shape = !args.shape || args.shape === "auto" ? detectShape(task) : args.shape;
+  const outputPath = (args.output_path || "./IMPLEMENTATION_GUIDE.md").trim();
+  const projectName = (args.project_name || "").trim();
+  const verifyCmds = args.verify_commands && args.verify_commands.length > 0 ? args.verify_commands : defaultVerifyCommands(shape);
+  const lines = [];
+  lines.push(`Create a detailed implementation specification${projectName ? ` for **${projectName}**` : ""}, written to:`);
+  lines.push(`  ${outputPath}`);
+  lines.push("");
+  lines.push(`## Task description`);
+  lines.push(task);
+  lines.push("");
+  if (args.features && args.features.length > 0) {
+    lines.push(`## Required features`);
+    lines.push(bulletList(args.features));
+    lines.push("");
+  }
+  lines.push(`## Tech stack — POSITIVE constraints (use these)`);
+  lines.push(bulletList(args.stack));
+  lines.push("");
+  lines.push(`## Tech stack — NEGATIVE constraints (do NOT use these)`);
+  lines.push(`These prohibitions are load-bearing. Default training data favors popular alternatives; you must respect the explicit "no" here even when a forbidden choice would be conventional.`);
+  lines.push("");
+  lines.push(bulletList(args.anti_stack));
+  lines.push("");
+  if (args.notes && args.notes.trim().length > 0) {
+    lines.push(`## Additional constraints / notes`);
+    lines.push(args.notes.trim());
+    lines.push("");
+  }
+  lines.push(`## Required spec sections (numbered, in order)`);
+  lines.push(`The spec MUST contain the following sections, each titled and numbered as below. Each section must be detailed enough to stand on its own; do not defer details to later sections.`);
+  lines.push("");
+  lines.push(renderSections(shape));
+  lines.push("");
+  lines.push(`## Reproducibility test (the load-bearing acceptance criterion)`);
+  lines.push(`The spec must be detailed enough that **a different agent**, with no access to this conversation and no shared memory with you, can implement it from the document alone — and produce a result that satisfies the verification commands below.`);
+  lines.push("");
+  lines.push(`## Verifiable acceptance criteria`);
+  lines.push(`Final implementation must pass:`);
+  lines.push(bulletList(verifyCmds));
+  lines.push("");
+  lines.push(`## Output discipline`);
+  lines.push(`- Write the entire spec to ${outputPath} in a single file_write call when you have a complete document. Iterating section-by-section across multiple calls produces incoherent specs; plan the whole document first, then emit.`);
+  lines.push(`- Do NOT implement any code outside the spec document itself. The spec is the deliverable; implementation is a separate downstream task.`);
+  lines.push(`- Call task_complete only after the spec is on disk and you have read it back to verify it covers every numbered section above.`);
+  return lines.join("\n");
+}
+var COMMON_HEAD_SECTIONS, COMMON_TAIL_SECTIONS, SHAPE_SECTIONS, ProjectScaffoldingTool;
+var init_project_scaffolding = __esm({
+  "packages/execution/dist/tools/project-scaffolding.js"() {
+    "use strict";
+    COMMON_HEAD_SECTIONS = [
+      ["Overview", "Goal, scope, non-goals."],
+      ["Non-functional requirements", "Performance, persistence, observability, error handling."]
+    ];
+    COMMON_TAIL_SECTIONS = [
+      ["Build commands", "All scripts (build, test, typecheck, dev). Each must be runnable and reproducible."],
+      ["Acceptance criteria", "Specific test counts and categories. The exact commands that must exit 0 to declare done."],
+      ["Test fixtures + sample data", "All sample inputs/outputs needed to run tests deterministically."],
+      ["Anti-requirements", "Explicit things NOT to do (frameworks, patterns, dependencies excluded)."]
+    ];
+    SHAPE_SECTIONS = {
+      "web-app": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Data models", "Schema (DB) + type definitions."],
+        ["API contract", "Endpoints, request/response shapes, error codes."],
+        ["Real-time events (if any)", "Event types, lifecycle, sequencing rules."],
+        ["Frontend architecture", "Module structure, state management, rendering pattern."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "service": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Data models", "Schema + type definitions."],
+        ["API contract", "Endpoints, request/response shapes, error codes."],
+        ["Background processing (if any)", "Workers, queues, scheduled jobs."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ["Operational concerns", "Logging, metrics, health checks, configuration."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "cli": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Command surface", "All commands, flags, args, exit codes, stdout/stderr format."],
+        ["Configuration", "Config file format, environment variables, precedence rules."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ["Error handling", "Error categories and how each surfaces to the user."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "library": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Public API surface", "Every exported symbol with signature, semantics, examples."],
+        ["Internal architecture", "Module breakdown, invariants, data flow."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ["Backward compatibility", "Versioning policy, deprecation rules."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "pipeline": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Stages", "Each stage's input, transform, output, idempotency property."],
+        ["Schemas", "Input/output schema for every stage boundary."],
+        ["Failure handling", "Retry, dead-letter, rollback, monitoring."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "game": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Game loop", "Tick rate, update/render cycle, fixed vs variable timestep."],
+        ["State machines", "All entities/scenes with transitions and invariants."],
+        ["Asset pipeline", "Format, loader, lifecycle."],
+        ["Input handling", "Mapping from device → game action."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "compiler": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Source language", "Grammar (BNF), example programs."],
+        ["Lexer", "Token kinds, error reporting."],
+        ["Parser", "AST shape, precedence, error recovery."],
+        ["Type system / static analysis", "Rules, inference algorithm if any."],
+        ["Evaluator / runtime", "Semantics, error model, foreign function calls."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ]
+    };
+    ProjectScaffoldingTool = class {
+      name = "project_scaffolding";
+      description = "Convert a brief, mushy task description into a structured spec-generation prompt with concrete deliverable, positive+negative stack constraints, numbered sections, reproducibility framing, and verifiable acceptance criteria. Use BEFORE delegating spec generation to another agent — the scaffolded prompt produces coherent implementable specs where a mush prompt produces hand-waving. Args: task (required string), output_path (optional, default ./IMPLEMENTATION_GUIDE.md), stack (string array of POSITIVE constraints), anti_stack (string array of NEGATIVE constraints — load-bearing for small models that default to popular patterns), features (string array of required features), shape (one of 'web-app' | 'service' | 'cli' | 'library' | 'pipeline' | 'game' | 'compiler' | 'auto', default 'auto'), notes (free-text additional constraints), project_name (display name in spec heading), verify_commands (override default verification commands). Returns the scaffolded prompt as a string. The agent should then either (a) hand the prompt off to a sub-agent / another OA run, or (b) execute the spec generation itself.";
+      parameters = {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: "Brief task description (the mush). E.g. 'a real-time chat app with rooms and reactions'."
+          },
+          output_path: {
+            type: "string",
+            description: "File path the downstream agent should write the spec to. Default: ./IMPLEMENTATION_GUIDE.md."
+          },
+          stack: {
+            type: "array",
+            items: { type: "string" },
+            description: "POSITIVE tech-stack constraints. E.g. ['Node.js', 'TypeScript', 'Express', 'PostgreSQL']."
+          },
+          anti_stack: {
+            type: "array",
+            items: { type: "string" },
+            description: "NEGATIVE tech-stack constraints — things to explicitly avoid. Load-bearing for small models. E.g. ['WebSockets', 'React', 'in-memory only']."
+          },
+          features: {
+            type: "array",
+            items: { type: "string" },
+            description: "Required features to surface as MUST-have. E.g. ['user auth', 'rate limiting', 'audit log']."
+          },
+          shape: {
+            type: "string",
+            enum: ["web-app", "service", "cli", "library", "pipeline", "game", "compiler", "auto"],
+            description: "Project shape. Determines which sections appear in the spec. Default: 'auto' (detect from task)."
+          },
+          notes: {
+            type: "string",
+            description: "Free-text additional constraints (operational, security, performance, deployment)."
+          },
+          project_name: {
+            type: "string",
+            description: "Display name used in spec heading. Optional."
+          },
+          verify_commands: {
+            type: "array",
+            items: { type: "string" },
+            description: "Override default verification commands. Each item describes a command + expected outcome."
+          }
+        },
+        required: ["task"]
+      };
+      async execute(args) {
+        const start2 = Date.now();
+        try {
+          const scaffArgs = {
+            task: String(args["task"] ?? ""),
+            output_path: typeof args["output_path"] === "string" ? args["output_path"] : void 0,
+            stack: Array.isArray(args["stack"]) ? args["stack"].map(String) : void 0,
+            anti_stack: Array.isArray(args["anti_stack"]) ? args["anti_stack"].map(String) : void 0,
+            features: Array.isArray(args["features"]) ? args["features"].map(String) : void 0,
+            shape: typeof args["shape"] === "string" ? args["shape"] : void 0,
+            notes: typeof args["notes"] === "string" ? args["notes"] : void 0,
+            project_name: typeof args["project_name"] === "string" ? args["project_name"] : void 0,
+            verify_commands: Array.isArray(args["verify_commands"]) ? args["verify_commands"].map(String) : void 0
+          };
+          const prompt = buildScaffoldedPrompt(scaffArgs);
+          return {
+            success: true,
+            output: prompt,
+            durationMs: Date.now() - start2
+          };
+        } catch (e2) {
+          return {
+            success: false,
+            output: "",
+            error: e2 instanceof Error ? e2.message : String(e2),
+            durationMs: Date.now() - start2
+          };
+        }
+      }
+    };
+  }
+});
+
 // packages/execution/dist/tools/todo-store.js
 import { existsSync as existsSync30, readFileSync as readFileSync24, writeFileSync as writeFileSync12, mkdirSync as mkdirSync11, renameSync, unlinkSync as unlinkSync5, readdirSync as readdirSync9 } from "node:fs";
 import { join as join47 } from "node:path";
@@ -510376,6 +510651,7 @@ __export(dist_exports, {
   PlaywrightBrowserTool: () => PlaywrightBrowserTool,
   PluginManager: () => PluginManager,
   ProcessHealthTool: () => ProcessHealthTool,
+  ProjectScaffoldingTool: () => ProjectScaffoldingTool,
   ReflectionIntegrityTool: () => ReflectionIntegrityTool,
   ReminderTool: () => ReminderTool,
   ReplTool: () => ReplTool,
@@ -510418,6 +510694,7 @@ __export(dist_exports, {
   buildCustomTools: () => buildCustomTools,
   buildGraph: () => buildGraph,
   buildMcpToolName: () => buildMcpToolName,
+  buildScaffoldedPrompt: () => buildScaffoldedPrompt,
   buildSkillsSummary: () => buildSkillsSummary,
   buildSubProcessArgs: () => buildSubProcessArgs,
   canInvokeTool: () => canInvokeTool,
@@ -510597,6 +510874,7 @@ var init_dist5 = __esm({
     init_cron_agent();
     init_file_explore();
     init_working_notes();
+    init_project_scaffolding();
     init_todo_write();
     init_todo_store();
     init_semantic_map();
@@ -596018,6 +596296,7 @@ function buildSubAgentTools(repoRoot, config) {
     new TodoWriteTool(),
     new TodoReadTool(),
     new WorkingNotesTool(),
+    new ProjectScaffoldingTool(),
     // Code understanding + navigation
     new CodebaseMapTool(repoRoot),
     new SemanticMapTool(repoRoot),
@@ -596181,6 +596460,7 @@ function buildTools(repoRoot, config, contextWindowSize, modelTier) {
     // Chunked file exploration + working notes + semantic map
     new FileExploreTool(repoRoot),
     new WorkingNotesTool(),
+    new ProjectScaffoldingTool(),
     // Agent-facing checklist (WO-TASK-02 — TodoWrite/TodoRead)
     new TodoWriteTool(),
     new TodoReadTool(),

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "open-agents-ai",
-  "version": "0.187.497",
+  "version": "0.187.498",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "open-agents-ai",
-      "version": "0.187.497",
+      "version": "0.187.498",
       "hasInstallScript": true,
       "license": "CC-BY-NC-4.0",
       "dependencies": {
@@ -7165,12 +7165,12 @@
       }
     },
     "node_modules/p-queue": {
-      "version": "9.1.2",
-      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.1.2.tgz",
-      "integrity": "sha512-ktsDOALzTYTWWF1PbkNVg2rOt+HaOaMWJMUnt7T3qf5tvZ1L8dBW3tObzprBcXNMKkwj+yFSLqHso0x+UFcJXw==",
+      "version": "9.2.0",
+      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.2.0.tgz",
+      "integrity": "sha512-dWgLE8AH0HjQ9fe74pUkKkvzzYT18Inp4zra3lKHnnwqGvcfcUBrvF2EAVX+envufDNBOzpPq/IBUONDbI7+3g==",
       "license": "MIT",
       "dependencies": {
-        "eventemitter3": "^5.0.1",
+        "eventemitter3": "^5.0.4",
         "p-timeout": "^7.0.0"
       },
       "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-agents-ai",
-  "version": "0.187.497",
+  "version": "0.187.498",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",