supipowers 1.5.3 → 2.0.0

package/skills/ultraplan-review-structure/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ultraplan-review-structure
+description: Structural integrity checker — verifies every applicable stack has domains and scenarios, all fields are present, IDs are unique, and the dependency graph is acyclic
+---
+
+# UltraPlan Review: Structure Checker
+
+Verify the structural integrity of a synthesized draft. This checker runs as part of the review stage. It does not evaluate correctness of content — it verifies that the shape of the plan satisfies the invariants required for execution.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Draft `authored.json`; intake artifact (to know which stacks are applicable) |
+| **Output** | Findings via `ultraplan_review_finding` with `source: "structure-checker"` |
+| **Scope** | Shape, presence, uniqueness, and graph constraints only |
+| **Storage tool** | `ultraplan_review_finding` — one call per distinct structural violation |
+
+## Checks
+
+### Check 1 — Stack Coverage
+
+Every stack marked `applicable` in the intake MUST appear in `authored.stacks` with at least one domain.
+
+- BLOCKER if an applicable stack is absent from `authored.stacks`.
+- BLOCKER if an applicable stack is present but has zero domains.
+- WARNING if a stack marked `unknown` in the intake is absent (the planner may have determined it is not needed, but should confirm).
+
+### Check 2 — Domain Coverage
+
+Every domain in every stack MUST have at least one scenario.
+
+- BLOCKER if a domain has zero scenarios.
+
+### Check 3 — Required Scenario Fields
+
+Every scenario MUST have all of: `id`, `title`, `level`, `slot`, `steps`, `dependencies`.
+
+- BLOCKER if any field is missing or null on any scenario.
+- BLOCKER if `steps` is an empty array.
+- BLOCKER if `level` is not one of `unit`, `integration`, `e2e`.
+- BLOCKER if `dependencies` is absent (empty array `[]` is valid).
+
+### Check 4 — ID Uniqueness
+
+All scenario IDs across all stacks and domains MUST be globally unique.
+
+- BLOCKER if any two scenarios share the same `id`.
+
+### Check 5 — Dependency Graph Validity
+
+For every scenario that lists dependencies:
+- Each dependency ID MUST resolve to an existing scenario.
+- The graph MUST be acyclic.
+
+Detection algorithm: perform a depth-first traversal from each scenario. If you encounter a node already on the current path, a cycle exists.
+
+- BLOCKER if a dependency ID does not resolve to an existing scenario.
+- BLOCKER if a cycle is detected. Report all scenario IDs in the cycle in the `message`.
+
+### Check 6 — Slot Presence
+
+Every `slot` value on every scenario MUST be a non-empty string.
+
+- BLOCKER if `slot` is empty, null, or whitespace.
+
+## Finding Format
+
+```
+ultraplan_review_finding({
+  id: "struct-<N>",
+  severity: "BLOCKER" | "WARNING",
+  source: "structure-checker",
+  target: {
+    stack: "<stack-id>" | null,
+    domainId: "<domain-id>" | null,
+    scenarioId: "<scenario-id>" | null
+  },
+  message: string,          // what is structurally wrong and where
+  recommendation: string    // what to add, fix, or remove
+})
+```
+
+Set `target` fields to the most specific level at which the violation occurs. If a stack is missing entirely, `domainId` and `scenarioId` are null.
+
+## Process
+
+Run all six checks in order. Do not stop at the first BLOCKER — complete all checks and emit all findings.
+
+### Example Finding — Missing Required Field
+
+```
+ultraplan_review_finding({
+  id: "struct-1",
+  severity: "BLOCKER",
+  source: "structure-checker",
+  target: { stack: "backend", domainId: "auth", scenarioId: "auth-login-happy" },
+  message: "Scenario 'auth-login-happy' in backend/auth is missing the 'slot' field.",
+  recommendation: "Add a slot value matching the TDD ownership rules, e.g. 'backend-executor' for unit-level scenarios."
+})
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Check all six structural invariants | Stop checking after the first BLOCKER |
+| Report every violation as a separate finding | Batch multiple violations into one finding |
+| Detect and report all cycle participants | Report only one node in a cycle |
+| Set `target` to the most specific location | Use null targets when a specific location is available |
+| Complete all checks even if count of findings is high | Skip checks to reduce finding volume |
+
+## Final Checklist
+
+- [ ] All six checks executed
+- [ ] Every applicable stack verified for domain coverage
+- [ ] ID uniqueness verified across all stacks globally
+- [ ] Dependency graph traversed for cycles
+- [ ] Every finding has a specific `target` and actionable `recommendation`
+- [ ] Zero findings explicitly recorded if no violations found (emit no calls, do not suppress output)

package/skills/ultraplan-review-tdd/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: ultraplan-review-tdd
+description: TDD ownership correctness checker — verifies executor/tester slot assignments match scenario levels and every scenario's first step is a failing test
+---
+
+# UltraPlan Review: TDD Checker
+
+Verify that every scenario is assigned to the correct slot for its test level and that every scenario's step sequence begins with a failing test. This checker runs as part of the review stage.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Draft `authored.json` |
+| **Output** | Findings via `ultraplan_review_finding` with `source: "tdd-checker"` |
+| **Scope** | Slot-to-level alignment, red-test step presence, proof obligations |
+| **Storage tool** | `ultraplan_review_finding` — one call per distinct TDD violation |
+
+## TDD Ownership Rules
+
+| Level | Valid slots | Invalid slots |
+|-------|-------------|---------------|
+| `unit` | `frontend-executor`, `backend-executor`, `infrastructure-executor` | Any tester or domain-reviewer slot |
+| `integration` | `frontend-tester`, `backend-tester`, `infrastructure-tester` | Any executor or domain-reviewer slot |
+| `e2e` | `frontend-tester`, `backend-tester`, `infrastructure-tester`, `frontend-domain-reviewer`, `backend-domain-reviewer`, `infrastructure-domain-reviewer` | Any executor slot |
+
+A slot name is invalid for a level if it does not appear in the "Valid slots" column.
+
+## Checks
+
+### Check 1 — Slot-Level Alignment
+
+Every scenario's `slot` MUST be in the valid-slots list for its `level`.
+
+Severity:
+- BLOCKER if a `unit` scenario uses a tester or domain-reviewer slot.
+- BLOCKER if an `integration` scenario uses an executor or domain-reviewer slot.
+- BLOCKER if an `e2e` scenario uses an executor slot.
+
+### Check 2 — Slot-Stack Consistency
+
+The slot's stack prefix MUST match the scenario's containing stack.
+
+- BLOCKER if a scenario in `frontend` stack uses a `backend-*` or `infrastructure-*` slot.
+- BLOCKER if a scenario in `backend` stack uses a `frontend-*` or `infrastructure-*` slot.
+- BLOCKER if a scenario in `infrastructure` stack uses a `frontend-*` or `backend-*` slot.
+
+### Check 3 — Red-Test Step Presence
+
+Every scenario's `steps` array MUST contain a step that creates and runs a failing test before any implementation step.
+
+Detection: The first step MUST contain language indicating test creation and failure verification. Acceptable signals: "write a failing test", "add a failing test", "run the test and confirm it fails", "commit the red test". Presence of implementation language in the first step without a preceding test step is a violation.
+
+Severity:
+- BLOCKER if the first step does not write or run a test.
+- BLOCKER if no step in the array runs the test before implementation steps begin.
+- WARNING if a step writes a test but does not verify it fails (does not mention "fails", "red", or "failing").
+
+### Check 4 — Proof Obligation Completeness
+
+For `unit` scenarios: the steps MUST include a step that runs the test after implementation and confirms it passes.
+
+For `integration` and `e2e` scenarios: the steps MUST include a step that runs the full test suite for the relevant layer after implementation.
+
+Severity:
+- WARNING if no "verify it passes" step exists after implementation.
+
+### Check 5 — No Implementation Before Red Test
+
+No implementation step (writing source code, calling an API, creating a database migration) MUST appear before the first red-test step.
+
+Severity:
+- BLOCKER if an implementation step precedes the red-test step.
+
+## Finding Format
+
+```
+ultraplan_review_finding({
+  id: "tdd-<N>",
+  severity: "BLOCKER" | "WARNING",
+  source: "tdd-checker",
+  target: {
+    stack: "<stack-id>",
+    domainId: "<domain-id>",
+    scenarioId: "<scenario-id>"
+  },
+  message: string,
+  recommendation: string
+})
+```
+
+Every TDD finding MUST include all three target fields — the violation is always locatable to a specific scenario.
+
+## Process
+
+Run all five checks across every scenario. Do not stop at the first BLOCKER.
+
+### Example Finding — Wrong Slot for Level
+
+```
+ultraplan_review_finding({
+  id: "tdd-1",
+  severity: "BLOCKER",
+  source: "tdd-checker",
+  target: { stack: "backend", domainId: "auth", scenarioId: "auth-login-unit" },
+  message: "Scenario 'auth-login-unit' has level 'unit' but is assigned slot 'backend-tester'. Unit scenarios must use executor slots.",
+  recommendation: "Change slot to 'backend-executor'."
+})
+```
+
+### Example Finding — Missing Red-Test Step
+
+```
+ultraplan_review_finding({
+  id: "tdd-2",
+  severity: "BLOCKER",
+  source: "tdd-checker",
+  target: { stack: "frontend", domainId: "dashboard", scenarioId: "dashboard-load" },
+  message: "Scenario 'dashboard-load' first step is 'Implement the data fetching hook', which is an implementation step. No preceding failing test step exists.",
+  recommendation: "Prepend a step: 'Write a failing test for the dashboard data fetching hook and run it to confirm it fails.'"
+})
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Check every scenario individually | Sample scenarios and extrapolate |
+| Apply slot-level rules strictly per the ownership table | Accept executor slots for integration scenarios "because it is simpler" |
+| Report slot-stack mismatch separately from slot-level mismatch | Combine into one finding when both violations exist on the same scenario |
+| Set all three target fields on every TDD finding | Use null targets for locatable violations |
+| Complete all five checks before emitting findings | Stop after discovering Check 1 failures |
+
+## Final Checklist
+
+- [ ] All five checks executed for every scenario
+- [ ] Every `unit` scenario uses an executor slot matching its stack
+- [ ] Every `integration` scenario uses a tester slot matching its stack
+- [ ] Every `e2e` scenario uses a tester or domain-reviewer slot matching its stack
+- [ ] Every scenario's first step is a failing test
+- [ ] No implementation step precedes the red-test step in any scenario
+- [ ] Every finding targets a specific scenario with all three target fields populated

package/skills/ultraplan-scout/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: ultraplan-scout
+description: Codebase reconnaissance stage — maps reusable assets, integration points, conventions, and test patterns for each applicable stack
+---
+
+# UltraPlan Scout
+
+Perform structured codebase reconnaissance and write findings as a JSON artifact. This stage runs after intake and before discover. It provides the factual foundation that all later stages depend on.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Intake artifact (provided by pipeline runner); repo access |
+| **Output** | Scout artifact written via `ultraplan_scout_record` |
+| **Tools** | `task`, `search`, `find`, `read`, `lsp` |
+| **Scope** | Read-only. No edits. No inferences beyond what is observed. |
+| **Storage tool** | `ultraplan_scout_record` — called exactly once |
+
+## Reconnaissance Areas
+
+For each stack marked `applicable` or `unknown` in the intake artifact, you MUST gather findings in all five areas below. For stacks marked `not-applicable`, skip them.
+
+### 1. Reusable Assets
+
+- Shared utilities, hooks, middleware, helper functions, base classes
+- Existing abstractions in the relevant stack directory (e.g. `src/`, `app/`, `server/`, `infra/`)
+- Package dependencies (read `package.json`, `pyproject.toml`, `go.mod`, etc.)
+
+### 2. Integration Points
+
+- Entry points, route handlers, API boundaries, event emitters, message queues
+- Shared state surfaces (databases, caches, shared configs)
+- Cross-stack interfaces (e.g. REST contracts, gRPC definitions, shared types)
+
+### 3. Conventions
+
+- Directory structure and file naming patterns
+- Module/import patterns (path aliases, barrel exports, index files)
+- Error handling patterns (Result types, thrown exceptions, error middleware)
+- Coding style signals (linting config, tsconfig settings, eslint rules)
+
+### 4. Existing Test Patterns
+
+- Test runner and framework in use (Jest, Vitest, pytest, Go test, etc.)
+- Test file location conventions (`__tests__/`, `.test.ts`, `_test.go`, etc.)
+- Fixture and factory patterns
+- Coverage configuration and thresholds
+
+### 5. Gotchas
+
+- Deprecated modules or patterns in active use
+- Known workarounds or TODO comments in relevant files
+- Circular dependencies or architectural debts visible from file structure
+- Missing abstractions that multiple callers work around
+
+## Investigation Strategy
+
+Use `find` to map structure before reading individual files. Use `search` to locate patterns (error handlers, test factories, shared types). Use `read` for targeted file reads. Use `lsp` to follow type definitions and usages. Delegate broad parallel investigations to `task`.
+
+Do not read entire files unless necessary. Read only the sections relevant to each reconnaissance area.
+
+## Output Schema
+
+Call `ultraplan_scout_record` exactly once with:
+
+```
+ultraplan_scout_record({
+  stacks: {
+    [stackId: "frontend" | "backend" | "infrastructure"]: {
+      reusableAssets: string[],       // file paths or symbol names
+      integrationPoints: string[],    // file paths or description strings
+      conventions: {
+        directories: string[],
+        naming: string,
+        errorHandling: string,
+        importStyle: string
+      },
+      testPatterns: {
+        runner: string,
+        fileConvention: string,
+        fixturePattern: string | null,
+        coverageConfig: string | null
+      },
+      gotchas: string[]
+    }
+  },
+  crossCuttingConcerns: string[]      // patterns that span multiple stacks
+})
+```
+
+Report only what was observed. Use `null` for fields where no evidence was found.
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Investigate every applicable and unknown stack | Skip stacks because they seem unrelated to the goal |
+| Report file paths as evidence for every asset and integration point | Make assertions without observed evidence |
+| Use `null` for fields with no evidence | Invent conventions or test patterns |
+| Parallelize independent stack investigations via `task` | Read files serially when parallel is safe |
+| Call `ultraplan_scout_record` exactly once | Write narrative prose instead of structured JSON |
+
+## Final Checklist
+
+- [ ] Every applicable/unknown stack has entries in all five reconnaissance areas
+- [ ] Every asset and integration point has a file path or symbol name as evidence
+- [ ] `crossCuttingConcerns` captured where applicable
+- [ ] `ultraplan_scout_record` called exactly once
+- [ ] No edits made to any file

package/skills/ultraplan-synthesize/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ultraplan-synthesize
+description: Scenario decomposition stage — produces a complete authored.json and manifest.json draft from all prior pipeline artifacts
+---
+
+# UltraPlan Synthesize
+
+Decompose the intake goal into executable scenarios with TDD ownership, slot assignments, and dependency edges. This stage runs after all research artifacts are available. Its output is the plan draft submitted to the review checkers.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | Intake + scout + discover + all research artifacts (provided by pipeline runner) |
+| **Output** | Authored draft written via `ultraplan_synth_draft` |
+| **Scope** | All applicable stacks; every intake success criterion must map to ≥1 scenario |
+| **Storage tool** | `ultraplan_synth_draft({ authored, manifest })` — called exactly once |
+
+## Structural Rules
+
+These rules are enforced by the structure-checker. Violating them produces BLOCKER findings.
+
+| Rule | Constraint |
+|------|-----------|
+| Stack coverage | Every applicable stack has ≥1 domain |
+| Domain coverage | Every domain has ≥1 scenario |
+| Scenario fields | Every scenario has: `id`, `title`, `level`, `slot`, `steps`, `dependencies` |
+| ID uniqueness | All scenario IDs are unique across all stacks and domains |
+| Dependency graph | No cycles — if A depends on B, B must not depend on A (directly or transitively) |
+| Intake coverage | Every intake success criterion maps to ≥1 scenario (checked by scope-checker) |
+
+## TDD Ownership Rules
+
+These rules are enforced by the tdd-checker. Violating them produces BLOCKER findings.
+
+| Level | Owning slot | Proof obligation |
+|-------|-------------|-----------------|
+| `unit` | `backend-executor`, `frontend-executor`, or `infrastructure-executor` | Red test committed before implementation |
+| `integration` | `backend-tester`, `frontend-tester`, or `infrastructure-tester` | Red test committed; covers cross-boundary behavior |
+| `e2e` | `backend-tester`, `frontend-tester`, `infrastructure-tester`, or `*-domain-reviewer` | Red test committed; simulates end-user flow |
+
+Every scenario marked `level: unit` MUST have a `steps` entry that creates and runs a failing test before implementation. Every scenario at `integration` or `e2e` MUST have a `steps` entry that writes and runs the failing test as its first step.
+
+## Decomposition Process
+
+### Step 1 — Map intake success criteria to domains
+
+Group success criteria into logical domains per stack. A domain is a coherent capability boundary (e.g. "authentication", "billing", "data-export"). Avoid single-scenario domains unless the capability genuinely stands alone.
+
+### Step 2 — Decompose each domain into scenarios
+
+A scenario is the smallest independently verifiable unit of work. Split along these seams:
+- Happy path vs error path (separate scenarios if the error path requires different test setup)
+- Read vs write (if they have independent validation requirements)
+- Sync vs async (if they have different timing constraints)
+
+Do not split for its own sake. If two behaviors are always tested together, they belong in one scenario.
+
+### Step 3 — Assign levels and slots
+
+Apply TDD ownership rules. When a scenario touches multiple stacks, assign it to the stack that owns the primary side effect.
+
+### Step 4 — Order dependencies
+
+Mark `dependencies` as a list of scenario IDs that must be complete before this scenario can begin. Use `[]` for no dependencies. Verify there are no cycles.
+
+### Step 5 — Write the draft
+
+Call `ultraplan_synth_draft` exactly once:
+
+```
+ultraplan_synth_draft({
+  authored: {
+    stacks: [
+      {
+        id: "frontend" | "backend" | "infrastructure",
+        domains: [
+          {
+            id: string,
+            name: string,
+            scenarios: [
+              {
+                id: string,
+                title: string,
+                level: "unit" | "integration" | "e2e",
+                slot: string,              // e.g. "backend-executor"
+                steps: string[],           // imperative steps; first step writes failing test
+                dependencies: string[]     // scenario IDs
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  manifest: {
+    title: string,
+    goal: string,
+    successCriteria: string[],
+    deferredIdeas: string[]
+  }
+})
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Map every intake success criterion to ≥1 scenario | Generate scenarios with no connection to the intake goal |
+| Assign `unit` scenarios to executor slots | Assign `unit` scenarios to tester slots |
+| Make the first step of every scenario a failing test | Write implementation steps before a test step |
+| Verify no dependency cycles before calling `ultraplan_synth_draft` | Produce a cyclic dependency graph |
+| Cover every applicable stack with ≥1 domain | Leave an applicable stack with no scenarios |
+
+## Final Checklist
+
+- [ ] Every intake success criterion maps to ≥1 scenario
+- [ ] Every applicable stack has ≥1 domain with ≥1 scenario
+- [ ] Every scenario has all required fields
+- [ ] All scenario IDs are unique
+- [ ] All `unit` scenarios use executor slots; all `integration`/`e2e` use tester or domain-reviewer slots
+- [ ] Every scenario's first step creates a failing test
+- [ ] Dependency graph is acyclic (verified by inspection)
+- [ ] `ultraplan_synth_draft` called exactly once

package/src/{quality/ai-session.ts → ai/final-message.ts}

@@ -1,3 +1,18 @@
+// src/ai/final-message.ts
+//
+// Generic helpers for running a one-shot structured agent session and
+// extracting the final assistant message. Lives under src/ai/ because it has
+// no dependencies on review, planning, quality, or any other workflow.
+//
+// Consumers:
+//   - src/ai/structured-output.ts (the schema-backed retry loop)
+//   - src/quality/gates/ai-review.ts, src/quality/ai-setup.ts (one-shot AI)
+//   - src/lsp/bridge.ts, src/docs/drift.ts, src/commands/release.ts
+//
+// Phase 5 / P7B will migrate the remaining one-shot consumers to the schema-
+// backed runner; until then, runStructuredAgentSession is the lowest-level
+// shared primitive.
+
 import type { GateExecutionContext } from "../types.js";
 
 export interface StructuredAgentRunOptions {
@@ -5,6 +20,8 @@ export interface StructuredAgentRunOptions {
   prompt: string;
   model?: string;
   thinkingLevel?: string | null;
+  agentId?: string;
+  agentDisplayName?: string;
   timeoutMs?: number;
 }
 
@@ -39,6 +56,10 @@ function extractTextFromContent(content: unknown): string {
   return "";
 }
 
+/**
+ * Walk the message list backwards and return the last assistant message text.
+ * Returns null when no assistant message contains usable text.
+ */
 export function extractFinalAssistantText(messages: unknown[]): string | null {
   for (let index = messages.length - 1; index >= 0; index -= 1) {
     const message = messages[index];
@@ -61,6 +82,10 @@ export function extractFinalAssistantText(messages: unknown[]): string | null {
   return null;
 }
 
+/**
+ * Run a one-shot agent session and return the final assistant message text.
+ * Disposes the session whether the prompt succeeds or throws.
+ */
 export async function runStructuredAgentSession(
   createAgentSession: GateExecutionContext["createAgentSession"],
   options: StructuredAgentRunOptions,
@@ -69,6 +94,8 @@ export async function runStructuredAgentSession(
     cwd: options.cwd,
     model: options.model,
     thinkingLevel: options.thinkingLevel ?? null,
+    ...(options.agentId ? { agentId: options.agentId } : {}),
+    ...(options.agentDisplayName ? { agentDisplayName: options.agentDisplayName } : {}),
   });
 
   try {

package/src/ai/schema-text.ts

@@ -0,0 +1,129 @@
+// src/ai/schema-text.ts
+//
+// Render a TypeBox schema as compact TS-like text suitable for embedding in
+// prompts. One canonical rendering means that adding a field to a TypeBox
+// contract automatically updates every prompt that references it through
+// this module — no hand-maintained schema prose to drift.
+//
+// Consumers:
+//   - src/review/* (runner, multi-agent-runner, validator, fixer) render
+//     ReviewOutputSchema / ReviewFixOutputSchema for both the main prompt
+//     and the retry prompt produced by runWithOutputValidation.
+//
+// Non-goals:
+//   - Produce standards-compliant JSON Schema output. Use TypeBox's own
+//     JSON Schema accessors for that. This renderer optimises for model
+//     readability, not spec compliance.
+//   - Capture every TypeBox modifier. Supported shapes cover the current
+//     contract surface; extend when a real consumer needs more.
+
+import type { TSchema } from "@sinclair/typebox";
+
+const INDENT = "  ";
+
+export interface RenderSchemaOptions {
+  /** Start indent (internal recursion use). */
+  depth?: number;
+}
+
+function indent(depth: number): string {
+  return INDENT.repeat(depth);
+}
+
+function renderLiteral(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null) return "null";
+  return String(value);
+}
+
+function renderUnion(parts: readonly TSchema[], depth: number): string {
+  if (parts.length === 0) return "never";
+  return parts.map((p) => renderSchemaText(p, { depth })).join(" | ");
+}
+
+function renderObject(schema: any, depth: number): string {
+  const props = schema.properties as Record<string, TSchema> | undefined;
+  if (!props || Object.keys(props).length === 0) {
+    return "{}";
+  }
+
+  const required: string[] = Array.isArray(schema.required) ? schema.required : [];
+  const lines: string[] = ["{"];
+  const childDepth = depth + 1;
+
+  for (const [key, child] of Object.entries(props)) {
+    const isRequired = required.includes(key);
+    const separator = isRequired ? ":" : "?:";
+    lines.push(`${indent(childDepth)}${key}${separator} ${renderSchemaText(child, { depth: childDepth })};`);
+  }
+
+  lines.push(`${indent(depth)}}`);
+  return lines.join("\n");
+}
+
+function renderArray(schema: any, depth: number): string {
+  const inner = renderSchemaText(schema.items as TSchema, { depth });
+  // Wrap multiline object types as Array<...> for readability.
+  if (inner.includes("\n")) {
+    return `Array<${inner}>`;
+  }
+  return `${inner}[]`;
+}
+
+function hasKey(schema: any, key: string): boolean {
+  return schema != null && typeof schema === "object" && key in schema;
+}
+
+/**
+ * Render a TypeBox schema as a compact TS-like type string. Safe to pass as
+ * the `schema:` param to `runWithOutputValidation` and the `{{outputSchema}}`
+ * placeholder inside review prompts.
+ */
+export function renderSchemaText(schema: TSchema, options: RenderSchemaOptions = {}): string {
+  const depth = options.depth ?? 0;
+  const any = schema as any;
+
+  // Literal / const
+  if (hasKey(any, "const")) {
+    return renderLiteral(any.const);
+  }
+
+  // Explicit enum
+  if (Array.isArray(any.enum)) {
+    return any.enum.map(renderLiteral).join(" | ");
+  }
+
+  // Union (anyOf / oneOf)
+  if (Array.isArray(any.anyOf)) {
+    return renderUnion(any.anyOf, depth);
+  }
+  if (Array.isArray(any.oneOf)) {
+    return renderUnion(any.oneOf, depth);
+  }
+
+  // Primitive / structural by `type`
+  const type = any.type as string | undefined;
+  switch (type) {
+    case "object":
+      return renderObject(any, depth);
+    case "array":
+      return renderArray(any, depth);
+    case "string":
+      return "string";
+    case "integer":
+      return "integer";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    default:
+      // Fall through — unknown shape
+      break;
+  }
+
+  // Nothing matched — render as `unknown` rather than throwing so prompts
+  // still get something readable if someone adds an exotic schema.
+  return "unknown";
+}