ultracode-for-codex 0.2.3 → 0.2.4

package/README.md

@@ -26,7 +26,7 @@ npm run pack:ultracode-for-codex
 Install the tarball from a target project:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-0.2.3.tgz
+npm install --save-dev /path/to/ultracode-for-codex-0.2.4.tgz
 ```
 
 Run a workflow:
@@ -60,10 +60,15 @@ plugin workflow folders, and built-ins:
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
   --cwd /path/to/target-repo \
-  --name code-review \
-  --args '{"prompt":"review correctness risks"}'
+  --name task \
+  --args '{"prompt":"review correctness risks and propose fixes"}'
 ```
 
+The built-in `task` and `code-review` workflows use an LLM planner first, then
+run work phase by phase. Within each phase, multiple focused Codex subagents run
+in parallel by default, followed by phase and final synthesis. The planner may
+choose a single-agent path only when parallel execution would add risk or waste.
+
 ## Settings
 
 Package defaults live in `settings.json`:
@@ -122,8 +127,9 @@ want Codex to auto-load the package boundaries and verification routine.
   environment.
 - Codex subagents run against the requested workflow cwd and receive bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `code-review` injects deterministic workspace context before calling
-  its subagent so file-specific prompts carry local evidence into the review.
+- Built-in `task` and `code-review` inject deterministic workspace context into
+  planner-selected phase-wise parallel subagents, then synthesize each phase and
+  the final result.
 - Workflow execution is local and command-owned; settings default to OS
   background execution and `--execution attached` keeps the process connected
   until completion.

package/ULTRACODE_INSTALL.md

@@ -31,7 +31,7 @@ npm exec -- ultracode-for-codex --llm-guide
 For source-checkout validation, install the generated tarball instead:
 
 ```bash
-npm install --save-dev ./ultracode-for-codex-0.2.3.tgz
+npm install --save-dev ./ultracode-for-codex-0.2.4.tgz
 ```
 
 Optional Codex companion skill:
@@ -58,6 +58,12 @@ npm exec -- ultracode-for-codex run \
 The default run prints a background launch record to stdout. Use
 `--execution attached` when Codex should read progress until completion.
 
+Use built-in `task` for general work and `code-review` for review-specific work.
+Both start with an LLM planner, execute phase by phase, run multiple focused
+Codex subagents in parallel within each phase by default, and synthesize phase
+and final results. The planner chooses a single-agent path only when parallel
+execution would add risk or waste.
+
 Settings defaults:
 
 ```json
@@ -108,8 +114,9 @@ Useful controls:
 - Strip direct provider credentials from child CLI environments.
 - Run Codex subagents against the requested workflow cwd and provide bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `code-review` adds deterministic workspace context before the agent
-  call, prioritizing files explicitly mentioned in the prompt.
+- Built-in `task` and `code-review` add deterministic workspace context to
+  planner-selected phase-wise parallel subagents, then synthesize each phase and
+  the final result.
 - Install consumers from a packaged artifact.
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
   Local runtime state may still contain runtime-owned

package/dist/runtime/workflow-runtime.js

@@ -99,39 +99,209 @@ const WORKSPACE_CONTEXT_PRIORITY_FILES = new Set([
     'tsconfig.json',
 ]);
 const DEFAULT_BUILTIN_WORKFLOWS = [
+    {
+        name: 'task',
+        script: phaseWiseBuiltinWorkflowScript({
+            name: 'task',
+            description: 'Run an LLM-planned phase-wise parallel task workflow',
+            defaultPrompt: 'Complete the requested repository task.',
+            plannerKind: 'general task',
+            plannerGuidance: 'Plan phases that make the work faster and more accurate through parallel agents. Default to phase_parallel. Choose single only for tiny changes, strictly sequential investigations, or one indivisible failure mode.',
+            agentGuidance: 'Complete the assigned phase work. Prefer concrete evidence, file paths, commands, and risks over broad narration.',
+            finalGuidance: 'Return the completed task result, key evidence, decisions made, verification status, and residual risk.',
+        }),
+    },
     {
         name: 'code-review',
-        script: `export const meta = {
-  name: "code-review",
-  description: "Run a code review workflow"
-};
-const input = args && typeof args === "object" ? args : {};
-const prompt = typeof input.prompt === "string" && input.prompt.trim()
-  ? input.prompt
-  : "Review the current repository for correctness risks.";
-const context = await workspaceContext({ query: prompt });
-return await agent([
-  prompt,
-  "",
-  "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
-  "",
-  context
-].join("\\n"), { label: "code-review" });`,
+        script: phaseWiseBuiltinWorkflowScript({
+            name: 'code-review',
+            description: 'Run an LLM-planned phase-wise parallel code review workflow',
+            defaultPrompt: 'Review the current repository for correctness risks.',
+            plannerKind: 'code review',
+            plannerGuidance: 'Plan an effective code review. Default to phase_parallel with multiple focused reviewers per phase. Commonly useful lenses include runtime correctness, security/capability boundaries, API/CLI contracts, persistence/retry/cancel behavior, and test coverage. Choose single only for a tiny scoped diff or one indivisible failure mode.',
+            agentGuidance: 'Return material findings only. Prioritize root cause, severity, exact file/line evidence, reproduction or impact, and residual risk.',
+            finalGuidance: 'Return findings ordered by severity with exact file/line references. Deduplicate overlaps, preserve dissent or uncertainty, and say clearly if there are no material findings.',
+        }),
     },
     {
         name: 'batch',
         script: `export const meta = {
   name: "batch",
-  description: "Run multiple prompts in parallel"
+  description: "Run explicitly supplied prompts in one parallel phase"
 };
 const input = args && typeof args === "object" ? args : {};
 const prompts = Array.isArray(input.prompts) ? input.prompts : [];
+phase("Batch");
 return await parallel(prompts.map((prompt, index) => () => agent(
   prompt == null ? "" : "" + prompt,
   { label: "batch-" + (index + 1) }
 )));`,
     },
 ];
+function phaseWiseBuiltinWorkflowScript(input) {
+    return `export const meta = {
+  name: ${JSON.stringify(input.name)},
+  description: ${JSON.stringify(input.description)}
+};
+const workflowInput = args && typeof args === "object" ? args : {};
+const prompt = typeof workflowInput.prompt === "string" && workflowInput.prompt.trim()
+  ? workflowInput.prompt
+  : ${JSON.stringify(input.defaultPrompt)};
+const context = await workspaceContext({ query: prompt });
+const plan = await agent([
+  ${JSON.stringify(`Plan the phase-wise execution strategy for ${input.plannerKind}.`)},
+  "",
+  ${JSON.stringify(input.plannerGuidance)},
+  "A phase runs after previous phase summaries are available. Within each phase, use parallel agents by default.",
+  "Return 1 to 4 phases. For ordinary work, prefer 2 phases with 2 to 4 parallel agents each. Use concise stable ids.",
+  "",
+  "User request:",
+  prompt,
+  "",
+  context
+].join("\\n"), {
+  label: ${JSON.stringify(`${input.name}-planner`)},
+  schema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      mode: { type: "string", enum: ["phase_parallel", "single"] },
+      rationale: { type: "string", minLength: 1 },
+      phases: {
+        type: "array",
+        minItems: 1,
+        maxItems: 4,
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            id: { type: "string", minLength: 1, maxLength: 32 },
+            title: { type: "string", minLength: 1, maxLength: 80 },
+            goal: { type: "string", minLength: 1, maxLength: 800 },
+            agents: {
+              type: "array",
+              minItems: 1,
+              maxItems: 4,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1, maxLength: 32 },
+                  title: { type: "string", minLength: 1, maxLength: 80 },
+                  focus: { type: "string", minLength: 1, maxLength: 800 }
+                },
+                required: ["id", "title", "focus"]
+              }
+            }
+          },
+          required: ["id", "title", "goal", "agents"]
+        }
+      }
+    },
+    required: ["mode", "rationale", "phases"]
+  }
+});
+const selectedPhases = plan.mode === "single" ? [plan.phases[0]] : plan.phases;
+if (plan.mode === "single") {
+  const singlePhase = selectedPhases[0];
+  const singleAgent = singlePhase.agents[0];
+  phase(singlePhase.title);
+  return await agent([
+    "Single-agent execution selected by the LLM planner.",
+    "Planner rationale: " + plan.rationale,
+    "Phase goal: " + singlePhase.goal,
+    "Agent focus: " + singleAgent.title + " - " + singleAgent.focus,
+    "",
+    "Original request:",
+    prompt,
+    "",
+    ${JSON.stringify(input.agentGuidance)},
+    "",
+    "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+    "",
+    context
+  ].join("\\n"), { label: ${JSON.stringify(`${input.name}-single`)}, phase: singlePhase.title });
+}
+const phaseOutputs = [];
+const priorSummaries = [];
+for (const phasePlan of selectedPhases) {
+  phase(phasePlan.title);
+  const agents = phasePlan.agents;
+  const agentOutputs = agents.length < 2
+    ? [await agent([
+        "Parallel phase agent: " + agents[0].title,
+        "Phase: " + phasePlan.title,
+        "Phase goal: " + phasePlan.goal,
+        "Agent focus: " + agents[0].focus,
+        "",
+        "Previous phase summaries:",
+        JSON.stringify(priorSummaries, null, 2),
+        "",
+        "Original request:",
+        prompt,
+        "",
+        ${JSON.stringify(input.agentGuidance)},
+        "",
+        "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+        "",
+        context
+      ].join("\\n"), { label: ${JSON.stringify(`${input.name}-`)} + phasePlan.id + "-" + agents[0].id, phase: phasePlan.title })]
+    : await parallel(agents.map((phaseAgent) => () => agent([
+        "Parallel phase agent: " + phaseAgent.title,
+        "Phase: " + phasePlan.title,
+        "Phase goal: " + phasePlan.goal,
+        "Agent focus: " + phaseAgent.focus,
+        "",
+        "Previous phase summaries:",
+        JSON.stringify(priorSummaries, null, 2),
+        "",
+        "Original request:",
+        prompt,
+        "",
+        ${JSON.stringify(input.agentGuidance)},
+        "",
+        "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+        "",
+        context
+      ].join("\\n"), { label: ${JSON.stringify(`${input.name}-`)} + phasePlan.id + "-" + phaseAgent.id, phase: phasePlan.title })));
+  const phaseSummary = await agent([
+    "Synthesize this phase.",
+    "Phase: " + phasePlan.title,
+    "Phase goal: " + phasePlan.goal,
+    "",
+    "Original request:",
+    prompt,
+    "",
+    "Agent outputs:",
+    JSON.stringify(agentOutputs, null, 2),
+    "",
+    "Return a concise phase summary with material findings, completed work, open questions, and what the next phase should know."
+  ].join("\\n"), { label: ${JSON.stringify(`${input.name}-phase-`)} + phasePlan.id + "-synthesis", phase: phasePlan.title });
+  const phaseRecord = {
+    id: phasePlan.id,
+    title: phasePlan.title,
+    goal: phasePlan.goal,
+    results: agentOutputs,
+    summary: phaseSummary
+  };
+  phaseOutputs.push(phaseRecord);
+  priorSummaries.push({ id: phaseRecord.id, title: phaseRecord.title, summary: phaseRecord.summary });
+}
+return await agent([
+  ${JSON.stringify(`Synthesize the phase-wise ${input.plannerKind} workflow into the final result.`)},
+  "",
+  "Original request:",
+  prompt,
+  "",
+  "Planner rationale:",
+  plan.rationale,
+  "",
+  "Phase outputs:",
+  JSON.stringify(phaseOutputs, null, 2),
+  "",
+  ${JSON.stringify(input.finalGuidance)}
+].join("\\n"), { label: ${JSON.stringify(`${input.name}-final-synthesis`)} });`;
+}
 export class WorkflowTaskRegistry {
     options;
     tasks = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
   "keywords": [
     "codex",

package/skills/ultracode-for-codex/SKILL.md

@@ -17,6 +17,12 @@ command process. `settings.json` defaults runs to OS background execution.
 Attached runs stream stderr JSONL for Codex-readable status, while stdout
 remains the final workflow result JSON.
 
+The default Ultracode work shape is phase-wise parallel execution: built-in
+`task` and `code-review` first call a planner agent, then execute each planned
+phase with parallel focused subagents by default, followed by phase and final
+synthesis. A single-agent path is reserved for cases where the planner judges
+parallel execution risky or wasteful.
+
 ## Install And Run
 
 Use the npm package for consumer installs.
@@ -35,7 +41,7 @@ For source-checkout validation before publish:
 
 ```bash
 npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-0.2.3.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-0.2.4.tgz
 ```
 
 CLI behavior:
@@ -62,8 +68,8 @@ CLI behavior:
 - Keep direct provider credentials out of Codex child process environments.
 - Codex subagents run against the requested workflow cwd and have bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `code-review` injects deterministic workspace context and prioritizes
-  files explicitly mentioned in the prompt.
+- Built-in `task` and `code-review` inject deterministic workspace context into
+  planner-selected phase-wise parallel subagents.
 - Keep workflow execution local and command-owned; settings default to OS
   background execution and `--execution attached` keeps the process connected
   until completion.