@jenga-ai/agent 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # JengaAgent
 
-**A structured multi-agent development workflow built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code).** Three specialised AI agents — Scrum Master, Developer, and Tester — collaborate through a shared scrum board, an event-driven trigger queue, and 28 slash-command skills to take a project from idea to verified, committed code — across as many sessions as it takes.
+**A structured multi-agent development workflow that works with any AI agent or AI-native IDE.** Three specialised AI agents — Scrum Master, Developer, and Tester — collaborate through a shared scrum board, an event-driven trigger queue, and 28 slash-command skills to take a project from idea to verified, committed code — across as many sessions as it takes.
 
 > 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
 
@@ -12,7 +12,7 @@ Without a framework like JengaAgent, AI-assisted development has serious structu
 
 | Problem | Reality |
 |---|---|
-| **AI has no session memory** | Each Claude Code session starts from scratch — no awareness of open tasks, past decisions, or what was already tested |
+| **AI has no session memory** | Every AI agent session starts from scratch — no awareness of open tasks, past decisions, or what was already tested |
 | **No role separation** | The AI writes *and* "tests" code in the same context, leading to hallucinated test results and self-affirming bugs |
 | **No structured planning** | Work happens ad-hoc — no Epic → Story → Task hierarchy to organise or track progress |
 | **No handoff protocol** | Switching from implementing to testing means manually re-explaining context every time |
@@ -30,11 +30,11 @@ JengaAgent solves each of these with structure: persistent board state, strict a
 **Without JengaAgent:**
 ```
 You: "Add user authentication"
-Claude: [writes auth code, declares it works, session ends]
+AI agent: [writes auth code, declares it works, session ends]
 
 Next session:
 You: "What's the status of auth?"
-Claude: "I don't have context from the previous session."
+AI agent: "I don't have context from the previous session."
 ```
 
 **With JengaAgent:**
@@ -136,7 +136,11 @@ Each agent is defined in `.agents/agents/`. They communicate exclusively through
 
 ## Getting Started
 
-**Prerequisites:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured.
+**Prerequisites:** An AI agent or AI-native IDE. Supported platforms include:
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- GitHub Copilot (VS Code extension or CLI)
+- [Warp](https://www.warp.dev/)
+- Codex CLI
 
 **Install from npm:**
 ```sh
@@ -155,9 +159,24 @@ Run `/status` at any time to see where the project stands.
 
 ---
 
+## Supported Platforms
+
+JengaAgent has been tested with:
+
+| Platform | Type |
+|---|---|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | AI coding agent |
+| [GitHub Copilot](https://github.com/features/copilot) | AI coding assistant |
+| [Warp](https://www.warp.dev/) | AI-native terminal |
+| Codex CLI | AI coding agent |
+
+The framework is platform-agnostic by design — any AI agent that can read Markdown files and execute slash commands can use it.
+
+---
+
 ## Skills (Slash Commands)
 
-Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `/<name>` in any Claude Code session.
+Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `/<name>` in your AI agent or IDE's command interface.
 
 ### Setup & Planning
 
@@ -216,11 +235,10 @@ Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `/<name>` in any Cl
 
 JengaAgent can propagate its workflow files to other projects on your machine via `/distribute`.
 
-1. **Register consumer projects** — place `jenga.config.json` at each consumer root (copy from `templates/JENGA_CONFIG_TEMPLATE.json`).
-2. **Add search paths** — add absolute directory paths to `.jenga_paths` (one per line, git-ignored).
-3. **Run `/distribute`** — choose `major`, `minor`, `patch`, or `amend` release type; the skill handles versioning and syncs all registered projects.
+1. **Register consumer projects** — add each consuming project to `distribute.config.json` at the repo root (or pass a path directly: `/distribute /path/to/project`).
+2. **Run `/distribute`** — choose `major`, `minor`, `patch`, or `amend` release type; the skill handles versioning, dry-run preview, file copy, and a version bump commit.
 
-To exclude specific files per consumer project, add a `.jenga_ignore` at the consumer root (never overwritten by distribute).
+Each consuming project holds a `jenga.config.json` tracking the distributed version, last distribution date, and source. To exclude specific files per consumer project, add a `.jenga_ignore` at the consumer root (never overwritten by distribute).
 
 ---
 

package/agents/scrum-master.md

@@ -118,6 +118,81 @@ Used for smaller, more technical units of work — typically a sub-item within a
 
 ---
 
+## Execution Scope Assignment
+
+When breaking down a story into tasks, assign `execution_scope` to each task using the heuristics below. Read all numeric thresholds from `project/configs/scope-thresholds.json` at breakdown time — do not embed literal values in these instructions. The relevant fields are `inline_max_files`, `inline_max_lines`, and `story_max_files`.
+
+### `inline` scope
+
+Assign `inline` when **all** of the following are true:
+- The task touches exactly `inline_max_files` file (per `project/configs/scope-thresholds.json`)
+- No new tests are required
+- The change is purely additive or config-level (no logic branches introduced)
+- The estimated diff is `inline_max_lines` lines or fewer (per `project/configs/scope-thresholds.json`)
+
+`needs_docs` for every `inline`-scoped task is always `false`.
+
+### `story` scope
+
+Assign `story` when **all** of the following are true:
+- All tasks in the story operate in the same module or directory
+- No cross-story dependencies exist
+- The total file count across all tasks in the story is fewer than `story_max_files` (per `project/configs/scope-thresholds.json`)
+- The mandatory contention check passes (see below)
+
+**Mandatory contention check (required before assigning `story` scope):** Before assigning `story` scope to any task, confirm that no two tasks in the story write to the same shared infrastructure file (e.g. `package.json`, `settings.json`, `pyproject.toml`, `distribute.config.json`). This check is required — it is not optional.
+
+If contention exists between any two tasks, downgrade **both** conflicting tasks to `task` scope and document the conflict in each task's `scope_rationale` (e.g. `"downgraded from story: contention on package.json with T02"`). Do not assign `story` scope to either conflicting task.
+
+### `task` scope (default)
+
+Use `task` scope when **any** of the following are true:
+- Branching logic or non-trivial architecture is involved
+- Tester validation is sensitive to the implementation approach
+- Shared infrastructure is touched (e.g. `package.json`, `settings.json`)
+- Cross-story dependencies exist
+- The mandatory contention check fails for `story` scope
+- Uncertainty makes a more optimistic scope assignment unjustifiable
+
+When in doubt, default to `task`. `task` is the safe choice and imposes no penalty.
+
+### `epic` scope
+
+**Never assign `epic` scope autonomously.** If a task appears to require epic-level scope, do **not** set `execution_scope: epic` in the frontmatter. Instead:
+1. Assign `execution_scope: task` in the frontmatter.
+2. Add a note in the story description or `scope_rationale` explaining that this task may require epic-level scope and why, directed at the human operator.
+3. The human operator sets `epic_scope_approval: true` when they are ready to authorise it. Never set `epic_scope_approval: true` autonomously.
+
+---
+
+## `needs_docs` Assessment
+
+`needs_docs` is assessed **independently** from `execution_scope`. Do not derive one from the other (except for `inline`, which always sets `needs_docs: false`).
+
+**Assign `needs_docs: false` when:**
+- The task is `inline` scope (always false)
+- The acceptance criteria are binary and self-evident from reading the diff (e.g. "add field X to schema")
+- No non-obvious architectural decision is required
+
+**Assign `needs_docs: true` when:**
+- A non-obvious architectural decision is required
+- Multiple valid implementation approaches exist and the chosen one needs justification
+- The tester cannot verify correctness without understanding the implementation intent
+
+---
+
+## `scope_rationale` Requirement
+
+Every task with `execution_scope` set in frontmatter **must** include a `scope_rationale` string. The rationale must reference at least one measurable or file-count criterion. Generic statements (e.g. "this task is small") are not acceptable.
+
+**Acceptable example:** `"touches 1 file (SCRUM_BOARD_SCHEMA.md); purely additive schema documentation change, estimated under 30 lines"`
+
+**Not acceptable:** `"this is a small change"`
+
+If a measurable rationale cannot be constructed, default to `execution_scope: task` rather than guessing at a more optimistic scope.
+
+---
+
 ## Workflow
 
 ### 1. Intake & Mapping

package/mcp/router/embedder.js

@@ -1,4 +1,4 @@
-import { pipeline } from "@xenova/transformers";
+import { pipeline } from "@huggingface/transformers";
 
 let _pipe = null;
 

package/mcp/training_runner/index.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * training_runner — MCP server
+ *
+ * Exposes a single tool: run_training_job
+ *   - Validates the job directory and config.yaml
+ *   - Checks confirm_before_run flag
+ *   - Executes bash start.sh, collecting stdout/stderr
+ *   - Returns a structured result including exit_code, duration, and results.json contents
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+import { spawn } from "child_process";
+import { load as yamlLoad } from "js-yaml";
+
+const server = new McpServer({
+  name: "training_runner",
+  version: "1.0.0",
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and parse config.yaml from the job directory.
+ * Returns { config, error } — error is a string if loading failed.
+ */
+function loadConfig(jobDir) {
+  const configPath = join(jobDir, "input", "config.yaml");
+  if (!existsSync(configPath)) {
+    return { config: null, error: `config.yaml not found at: ${configPath}` };
+  }
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const config = yamlLoad(raw) || {};
+    return { config, error: null };
+  } catch (err) {
+    return { config: null, error: `Failed to parse config.yaml: ${err.message}` };
+  }
+}
+
+/**
+ * Validate required config fields.
+ * Returns an array of missing field names (empty = all present).
+ */
+function validateRequiredFields(config) {
+  const missing = [];
+  const model = config.model || {};
+
+  // Every job type requires at least one of model.type or model.name
+  if (!model.type && !model.name) {
+    missing.push("model.type (classifiers) or model.name (transformers/nlp)");
+  }
+
+  return missing;
+}
+
+/**
+ * Run `bash start.sh` in jobDir; collect output lines and exit code.
+ * Returns a Promise<{ lines: string[], exitCode: number }>.
+ */
+function runStartSh(jobDir) {
+  return new Promise((resolve_) => {
+    const lines = [];
+    const proc = spawn("bash", ["start.sh"], {
+      cwd: jobDir,
+      env: process.env,
+    });
+
+    const collect = (data) => {
+      const text = data.toString();
+      text.split("\n").forEach((line) => {
+        if (line !== "") lines.push(line);
+      });
+    };
+
+    proc.stdout.on("data", collect);
+    proc.stderr.on("data", collect);
+
+    proc.on("close", (exitCode) => {
+      resolve_({ lines, exitCode: exitCode ?? -1 });
+    });
+
+    proc.on("error", (err) => {
+      lines.push(`[runner error] ${err.message}`);
+      resolve_({ lines, exitCode: -1 });
+    });
+  });
+}
+
+/**
+ * Read results.json from the job directory, if it exists.
+ * Returns the parsed object or null.
+ */
+function readResultsJson(jobDir) {
+  const resultsPath = join(jobDir, "results.json");
+  if (!existsSync(resultsPath)) return null;
+  try {
+    const raw = readFileSync(resultsPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool: run_training_job
+// ---------------------------------------------------------------------------
+server.tool(
+  "run_training_job",
+  "Validate and run an ML training job by executing bash start.sh in the job directory.",
+  {
+    job_dir: z
+      .string()
+      .describe("Absolute or relative path to the job directory (must contain input/config.yaml and start.sh)."),
+    confirm: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        "Set to true to confirm execution when confirm_before_run is enabled in config.yaml."
+      ),
+  },
+  async ({ job_dir, confirm }) => {
+    const jobDir = resolve(job_dir);
+
+    // --- T02: Directory validation ---
+    if (!existsSync(jobDir)) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Job directory not found: ${jobDir}`,
+          },
+        ],
+      };
+    }
+
+    // --- T02: config.yaml validation ---
+    const { config, error: configError } = loadConfig(jobDir);
+    if (configError) {
+      return {
+        content: [{ type: "text", text: `❌ ${configError}` }],
+      };
+    }
+
+    // --- T02: Required field validation ---
+    const missingFields = validateRequiredFields(config);
+    if (missingFields.length > 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ config.yaml is missing required fields:\n${missingFields.map((f) => `  - ${f}`).join("\n")}`,
+          },
+        ],
+      };
+    }
+
+    // --- T02: start.sh must exist ---
+    const startSh = join(jobDir, "start.sh");
+    if (!existsSync(startSh)) {
+      return {
+        content: [{ type: "text", text: `❌ start.sh not found in ${jobDir}. Re-scaffold with /train new to generate it.` }],
+      };
+    }
+
+    // --- T04: confirm_before_run gate ---
+    const workflow = config.workflow || {};
+    if (workflow.confirm_before_run === true && !confirm) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `⚠️  This job has confirm_before_run: true in its config.yaml.`,
+              ``,
+              `Job directory: ${jobDir}`,
+              ``,
+              `To proceed, re-invoke this tool with confirm: true.`,
+            ].join("\n"),
+          },
+        ],
+      };
+    }
+
+    // --- T03: Execute bash start.sh ---
+    const startTime = Date.now();
+    const { lines, exitCode } = await runStartSh(jobDir);
+    const durationSeconds = ((Date.now() - startTime) / 1000).toFixed(2);
+
+    // --- T04 / E01_S04_T02: Read results.json if present ---
+    const results = readResultsJson(jobDir);
+
+    // Build response
+    const outputText = lines.join("\n");
+    const status = exitCode === 0 ? "✅ Completed" : `❌ Failed (exit code ${exitCode})`;
+
+    const summary = [
+      `${status}`,
+      `Job directory : ${jobDir}`,
+      `Duration      : ${durationSeconds}s`,
+      `Exit code     : ${exitCode}`,
+      ``,
+      `--- Output ---`,
+      outputText || "(no output)",
+    ];
+
+    if (results !== null) {
+      summary.push(``, `--- results.json ---`, JSON.stringify(results, null, 2));
+    }
+
+    // Structured result as JSON (appended as second content block)
+    const structuredResult = {
+      exit_code: exitCode,
+      job_dir: jobDir,
+      duration_seconds: parseFloat(durationSeconds),
+      output: lines,
+      results: results,
+    };
+
+    return {
+      content: [
+        { type: "text", text: summary.join("\n") },
+        { type: "text", text: JSON.stringify(structuredResult, null, 2) },
+      ],
+    };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Start server
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);