poe-code 3.0.196 → 3.0.198

package/packages/superintendent/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/packages/superintendent/dist/runtime/workflow-tool.d.ts

@@ -0,0 +1,29 @@
+import type { StatusBlock } from "../document/parse.js";
+export type WorkflowTransition = {
+    action: "request_review";
+    summary: string;
+} | {
+    action: "approve_completion";
+} | {
+    action: "request_changes";
+    feedback: string;
+};
+type McpToolProperty = {
+    type: "string";
+    description: string;
+    enum?: Array<WorkflowTransition["action"]>;
+};
+type McpToolInputSchema = {
+    type: "object";
+    additionalProperties: false;
+    properties: Record<string, McpToolProperty>;
+    required: string[];
+};
+export type McpToolDefinition = {
+    name: "workflow_transition";
+    description: string;
+    inputSchema: McpToolInputSchema;
+};
+export declare function createWorkflowTool(role: "superintendent" | "owner", state: StatusBlock["state"]): McpToolDefinition;
+export declare function parseWorkflowCall(input: unknown): WorkflowTransition;
+export {};

package/packages/superintendent/dist/runtime/workflow-tool.js

@@ -0,0 +1,83 @@
+export function createWorkflowTool(role, state) {
+    const actions = getAllowedActions(role, state);
+    return {
+        name: "workflow_transition",
+        description: actions.length === 0
+            ? "Transition the workflow state. No transitions are available in the current role/state."
+            : `Transition the workflow state. Valid actions: ${actions.join(", ")}.`,
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: createProperties(actions),
+            required: createRequiredFields(actions)
+        }
+    };
+}
+export function parseWorkflowCall(input) {
+    if (!isRecord(input)) {
+        throw invalidActionError();
+    }
+    const { action } = input;
+    if (action !== "request_review" && action !== "approve_completion" && action !== "request_changes") {
+        throw invalidActionError();
+    }
+    if (action === "request_review") {
+        return {
+            action,
+            summary: getNonEmptyString(input.summary, 'workflow_transition summary must be a non-empty string for "request_review"')
+        };
+    }
+    if (action === "request_changes") {
+        return {
+            action,
+            feedback: getNonEmptyString(input.feedback, 'workflow_transition feedback must be a non-empty string for "request_changes"')
+        };
+    }
+    return { action };
+}
+function createProperties(actions) {
+    const properties = {
+        action: {
+            type: "string",
+            description: "Workflow transition action to apply.",
+            enum: actions
+        }
+    };
+    if (actions.includes("request_review")) {
+        properties.summary = {
+            type: "string",
+            description: "Summarize why the work is ready for owner review."
+        };
+    }
+    if (actions.includes("request_changes")) {
+        properties.feedback = {
+            type: "string",
+            description: "Required when action is request_changes. Explain what needs to change."
+        };
+    }
+    return properties;
+}
+function createRequiredFields(actions) {
+    return actions.length === 1 && actions[0] === "request_review" ? ["action", "summary"] : ["action"];
+}
+function getAllowedActions(role, state) {
+    if (role === "superintendent" && (state === "in_progress" || state === "review")) {
+        return ["request_review"];
+    }
+    if (role === "owner" && state === "review") {
+        return ["approve_completion", "request_changes"];
+    }
+    return [];
+}
+function getNonEmptyString(value, errorMessage) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(errorMessage);
+    }
+    return value;
+}
+function invalidActionError() {
+    return new Error('workflow_transition action must be one of "request_review", "approve_completion", or "request_changes"');
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/superintendent/dist/state/machine.d.ts

@@ -0,0 +1,14 @@
+import type { SuperintendentDoc } from "../document/parse.js";
+import type { WorkflowTransition } from "../runtime/workflow-tool.js";
+export type LoopState = {
+    state: "in_progress" | "review" | "completed";
+    round: number;
+    reviewTurn: number;
+    maxRounds: number;
+    maxReviewTurns: number;
+};
+export declare function createLoopState(doc: SuperintendentDoc): LoopState;
+export declare function applyTransition(state: LoopState, transition: WorkflowTransition): LoopState;
+export declare function startNewRound(state: LoopState): LoopState;
+export declare function isComplete(state: LoopState): boolean;
+export declare function shouldRunBuilder(state: LoopState): boolean;

package/packages/superintendent/dist/state/machine.js

@@ -0,0 +1,53 @@
+const DEFAULT_MAX_ROUNDS = 100;
+const MAX_REVIEW_TURNS = 5;
+export function createLoopState(doc) {
+    return {
+        state: doc.frontmatter.status.state,
+        round: doc.frontmatter.status.round,
+        reviewTurn: doc.frontmatter.status.review_turn,
+        maxRounds: doc.frontmatter.max_rounds ?? DEFAULT_MAX_ROUNDS,
+        maxReviewTurns: MAX_REVIEW_TURNS
+    };
+}
+export function applyTransition(state, transition) {
+    switch (transition.action) {
+        case "request_review":
+            return {
+                ...state,
+                state: "review",
+                reviewTurn: 0
+            };
+        case "approve_completion":
+            return {
+                ...state,
+                state: "completed"
+            };
+        case "request_changes":
+            if (state.reviewTurn < state.maxReviewTurns) {
+                return {
+                    ...state,
+                    state: "review",
+                    reviewTurn: state.reviewTurn + 1
+                };
+            }
+            return {
+                ...state,
+                state: "in_progress",
+                reviewTurn: 0
+            };
+    }
+}
+export function startNewRound(state) {
+    return {
+        ...state,
+        state: "in_progress",
+        round: state.round + 1,
+        reviewTurn: 0
+    };
+}
+export function isComplete(state) {
+    return state.state === "completed" || state.round > state.maxRounds;
+}
+export function shouldRunBuilder(state) {
+    return state.state === "in_progress";
+}

package/packages/superintendent/dist/templates/SKILL_superintendent.md

@@ -0,0 +1,193 @@
+---
+name: poe-code-superintendent-plan
+description: 'Create a superintendent markdown document for the autonomous build-inspect-review loop. Triggers on: create superintendent, superintendent plan, superintendent doc, autonomous loop.'
+---
+
+## If The Request Is Empty
+
+Ask the user for a one-sentence description of what they want to build autonomously.
+
+## Goal
+
+There is exactly **one plan document per feature**, at `<plan-directory>/<name>.md` (see Plan Directory section below). The superintendent frontmatter and Task Board live in that same file alongside the feature plan body.
+
+Use canonical frontmatter metadata at the top of the document:
+
+If a plan file already exists (e.g. drafted by `/poe-code-plan`), augment it in place by adding the YAML frontmatter at the top and a `## Task Board` section at the bottom. Do not create a second file.
+
+## Before Writing: Study Existing Plans
+
+Before drafting a new plan, find existing superintendent plans in this repo and use them as a reference for inspector choices, prompt phrasing, Task Board granularity, and MCP wiring.
+
+1. Run `grep -rl "^kind: superintendent" <plan-directory>/` to list existing plans (use the resolved plan directory).
+2. Read the most recent 1–2 (prefer ones whose scope resembles the current task).
+3. Reuse inspector names, role phrasing, and structural conventions from those plans unless the new task clearly warrants deviation. Do not copy body content — only patterns.
+
+If no existing plans are found, fall back to the template below.
+
+## Document Shape
+
+1. **YAML frontmatter** — wires the runtime (agents, prompts, MCP servers).
+2. **Markdown body** — the feature plan plus a `## Task Board` with checkbox tasks.
+
+## Frontmatter Format
+
+Role prompts are one line. Do not repeat anything that lives in `CLAUDE.md` (TDD, SOLID, project conventions). The plan file is the source of truth — agents read it.
+
+```yaml
+---
+$schema: https://poe-platform.github.io/poe-code/schemas/plans/superintendent.schema.json
+kind: superintendent
+version: 1
+
+builder:
+  prompt: |
+    Build the highest-priority open task from {{plan.path}}.
+
+inspectors:
+  code-quality:
+    prompt: |
+      Make sure this code follows convention and good architecture.
+
+superintendent:
+  prompt: |
+    Review the builder and inspector output, update the Task Board in {{plan.path}},
+    and request owner review when the board is complete.
+
+    Builder summary:
+    {{builder.summary}}
+
+    Inspector summaries:
+
+    ## Code quality
+    {{inspectors.code-quality}}
+
+owner:
+  agent: claude-code
+  prompt: |
+    Decide whether the work is done. Approve or send back with feedback.
+
+    Superintendent summary:
+    {{superintendent.summary}}
+
+max_rounds: 50
+
+status:
+  state: in_progress
+  round: 0
+  review_turn: 0
+---
+```
+
+## Task Board
+
+The markdown body must contain a `## Task Board` section with checkbox tasks:
+
+```markdown
+## Task Board
+
+- [ ] First task to accomplish
+- [ ] Second task to accomplish
+- [ ] Third task to accomplish
+```
+
+Priority is top-to-bottom: the first unchecked item is the highest priority. Use `- [ ]` for open tasks and `- [x]` for completed tasks.
+
+## Available Prompt Variables
+
+Use Mustache syntax in agent prompts:
+
+| Variable | Description |
+|---|---|
+| `{{plan.path}}` | Path to the plan document |
+| `{{builder.summary}}` | Short builder outcome |
+| `{{builder.log}}` | Builder execution log (text) |
+| `{{builder.log_path}}` | Path to the builder's spawn log file (for `npm run replay`) |
+| `{{inspectors.<name>}}` | Summary from a named inspector |
+| `{{superintendent.summary}}` | Superintendent's completion or review summary |
+| `{{owner.feedback}}` | Owner's decline feedback |
+
+## Agent Roles
+
+| Role | Purpose |
+|---|---|
+| `builder` | Does the actual work on the highest-priority task |
+| `inspectors` | One-off evaluators that review the builder's work |
+| `superintendent` | Reviews all outputs, updates the Task Board, requests owner review when done |
+| `owner` | Decides whether to approve completion or send work back |
+
+## Optional: MCP Servers
+
+Declare MCP servers globally (all roles get them) or inline on a single role.
+
+Global (every role can use it):
+
+```yaml
+mcp:
+  my-server:
+    command: npx
+    args: [my-server]
+```
+
+Per-role (only that role gets it):
+
+```yaml
+inspectors:
+  testing:
+    agent: claude-code
+    mcp:
+      terminal-pilot:
+        command: npx
+        args: [terminal-pilot-mcp]
+    prompt: |
+      Test it.
+```
+
+## Optional: Agent Specifiers
+
+Pin a specific model:
+
+```yaml
+builder:
+  agent: claude-code:anthropic/claude-opus-4.6
+```
+
+## Optional: Working Directory
+
+Any role may set `cwd` to override the default (the directory containing the plan doc). Absolute paths are used as-is; relative paths resolve against the plan doc's directory.
+
+```yaml
+builder:
+  agent: claude-code
+  cwd: ../../packages/agent-harness-tools
+  prompt: |
+    Build the next task.
+```
+
+## Auto-Run vs On-Demand Inspectors
+
+An inspector auto-runs each round only if its summary is referenced in the superintendent prompt via `{{inspectors.<name>}}` (transitively — if an auto-run inspector's own prompt references another inspector, that one also auto-runs). Inspectors configured but not referenced remain available: the superintendent can invoke them mid-round via the `inspector_run` MCP tool.
+
+## Rules
+
+- One plan document per feature: `<plan-directory>/<name>.md`. Do not create a second file in `.poe-code/superintendent/`.
+- Superintendent docs must start with `$schema`, `kind: superintendent`, and `version: 1`.
+- Role prompts are one line where possible. Do not restate CLAUDE.md.
+- Do not link the plan path inside every prompt — `{{plan.path}}` is in the template context.
+- `builder`, `superintendent`, and `owner` roles are required. `inspectors` is optional.
+- `max_rounds` defaults to 100 if omitted.
+- `status` must start with `state: in_progress`, `round: 0`, `review_turn: 0`.
+
+## After Writing
+
+Run `poe-code superintendent validate <path>` to check the document is valid.
+
+## Output
+
+```text
+Created (or augmented):
+  <plan-directory>/<name>.md
+
+Run with:
+  poe-code superintendent run <plan-directory>/<name>.md
+```

package/packages/superintendent/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { createSuperintendentSimulation, successTurn, failTurn, builderTurn, inspectorTurn, superintendentTurn, ownerApproveTurn, ownerRejectTurn } from "./simulation.js";
+export type { TurnSpec, TurnContext, SimulationOptions, SimulationResult, SimulationRun } from "./simulation.js";

package/packages/superintendent/dist/testing/index.js

@@ -0,0 +1 @@
+export { createSuperintendentSimulation, successTurn, failTurn, builderTurn, inspectorTurn, superintendentTurn, ownerApproveTurn, ownerRejectTurn } from "./simulation.js";

package/packages/superintendent/dist/testing/simulation.d.ts

@@ -0,0 +1,57 @@
+import { type SuperintendentDoc } from "../document/parse.js";
+import { runLoop, type AgentRunInput, type SuperintendentFileSystem } from "../runtime/loop.js";
+import type { WorkflowTransition } from "../runtime/workflow-tool.js";
+type SimulationFs = SuperintendentFileSystem;
+type SuperintendentRunResult = Awaited<ReturnType<typeof runLoop>>;
+type TurnOutput = {
+    stdout: string;
+    stderr?: string;
+    exitCode?: number;
+    summary?: string;
+    log?: string;
+    output?: string;
+    text?: string;
+    transition?: unknown;
+    toolCalls?: unknown;
+    sessionResult?: unknown;
+};
+export type TurnContext = {
+    fs: SimulationFs;
+    readFile: (filePath: string) => Promise<string>;
+    writeFile: (filePath: string, content: string) => Promise<void>;
+    readDoc: () => Promise<SuperintendentDoc>;
+};
+export type TurnSpec = {
+    assertPrompt?: (prompt: string, ctx: TurnContext) => void | Promise<void>;
+    fileChanges?: Record<string, string>;
+    output: TurnOutput;
+};
+export type SimulationOptions = {
+    docContent: string;
+    docPath?: string;
+    turns: TurnSpec[];
+    files?: Record<string, string>;
+    maxRounds?: number;
+    signal?: AbortSignal;
+};
+export type SimulationRun = AgentRunInput;
+export type SimulationResult = {
+    result: SuperintendentRunResult;
+    prompts: string[];
+    runs: SimulationRun[];
+    fs: SimulationFs;
+    readFile: (filePath: string) => Promise<string>;
+    readDoc: () => Promise<SuperintendentDoc>;
+};
+export type SimulationFailureContext = Omit<SimulationResult, "result">;
+export declare function successTurn(assertPrompt?: TurnSpec["assertPrompt"], fileChanges?: Record<string, string>): TurnSpec;
+export declare function failTurn(stderr: string, assertPrompt?: TurnSpec["assertPrompt"], fileChanges?: Record<string, string>): TurnSpec;
+export declare function builderTurn(fileChanges?: Record<string, string>, assertPrompt?: TurnSpec["assertPrompt"]): TurnSpec;
+export declare function inspectorTurn(summary: string, assertPrompt?: TurnSpec["assertPrompt"]): TurnSpec;
+export declare function superintendentTurn(transition?: WorkflowTransition, fileChanges?: Record<string, string>, assertPrompt?: TurnSpec["assertPrompt"]): TurnSpec;
+export declare function ownerApproveTurn(assertPrompt?: TurnSpec["assertPrompt"]): TurnSpec;
+export declare function ownerRejectTurn(feedback: string, assertPrompt?: TurnSpec["assertPrompt"]): TurnSpec;
+export declare function createSuperintendentSimulation(options: SimulationOptions): {
+    run: () => Promise<SimulationResult>;
+};
+export {};