ultracode-for-codex 0.2.3 → 0.2.5

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.5.tgz
 ```
 
 Run a workflow:
@@ -60,10 +60,19 @@ 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.
+Planner guidance includes dynamic workflow patterns such as classify-and-act,
+fan-out-and-synthesize, adversarial verification, generate-and-filter,
+tournament, and loop-until-done, so different work types can use different
+phase shapes.
+
 ## Settings
 
 Package defaults live in `settings.json`:
@@ -75,7 +84,7 @@ Package defaults live in `settings.json`:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 180000,
+    "timeoutMs": 900000,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -89,6 +98,7 @@ Package defaults live in `settings.json`:
 
 Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
 `--timeout-ms` to override settings for one run.
+The package default workflow timeout is `900000` ms, or 15 minutes.
 
 ## CLI Controls
 
@@ -96,6 +106,8 @@ Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
 - The final workflow result is printed as JSON to stdout.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
+- Built-in `task` and `code-review` emit `workflow.plan.ready` before phase
+  agents start, including phase titles and planned agent role labels.
 - Press `Ctrl-C` once to cancel the active workflow.
 - Use `--retry-limit <n>` to retry failed workflows inside the same process.
 - `--timeout-ms` is the workflow timeout and the default per-agent silence
@@ -122,8 +134,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.5.tgz
 ```
 
 Optional Codex companion skill:
@@ -58,6 +58,15 @@ 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.
+Planner guidance includes classify-and-act, fan-out-and-synthesize,
+adversarial verification, generate-and-filter, tournament, and loop-until-done
+patterns so different work types can use different phase shapes.
+
 Settings defaults:
 
 ```json
@@ -67,7 +76,7 @@ Settings defaults:
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 180000,
+    "timeoutMs": 900000,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",
@@ -83,8 +92,11 @@ Useful controls:
 
 - Progress events are printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
+- The package default workflow timeout is `900000` ms, or 15 minutes.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
+- Built-in `task` and `code-review` emit `workflow.plan.ready` before phase
+  agents start, including phase titles and planned agent role labels.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
 - `--timeout-ms` is the workflow timeout and the default per-agent silence
@@ -108,8 +120,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/cli.js

@@ -350,6 +350,15 @@ function renderWorkflowEvent(event, progressMode) {
         case 'workflow.phase.started':
             process.stderr.write(`[phase] ${event.title}${event.detail ? ` - ${event.detail}` : ''}\n`);
             return;
+        case 'workflow.plan.ready':
+            process.stderr.write(`[plan] mode=${event.mode} phases=${event.phases.length}${event.rationale ? ` - ${event.rationale}` : ''}\n`);
+            for (const [phaseIndex, phase] of event.phases.entries()) {
+                process.stderr.write(`[plan] ${phaseIndex + 1}. ${phase.title}${phase.goal ? ` - ${phase.goal}` : ''}\n`);
+                for (const agent of phase.agents) {
+                    process.stderr.write(`[plan]    - ${agent.title}${agent.label ? ` (${agent.label})` : ''}${agent.focus ? `: ${agent.focus}` : ''}\n`);
+                }
+            }
+            return;
         case 'workflow.log':
             process.stderr.write(`[log] ${event.message}\n`);
             return;
@@ -425,6 +434,18 @@ function progressPayloadForEvent(event) {
                 title: event.title,
                 detail: event.detail,
             };
+        case 'workflow.plan.ready':
+            return {
+                event: event.type,
+                status: 'planned',
+                summary: `Workflow plan ready: ${event.phases.length} phase${event.phases.length === 1 ? '' : 's'}, mode=${event.mode}`,
+                taskId: event.taskId,
+                runId: event.runId,
+                mode: event.mode,
+                rationale: event.rationale,
+                phaseCount: event.phases.length,
+                planPhases: event.phases,
+            };
         case 'workflow.log':
             return {
                 event: event.type,

package/dist/runtime/workflow-runtime.d.ts

@@ -4,6 +4,18 @@ export type WorkflowTaskStatus = 'running' | 'completed' | 'failed';
 export type WorkflowTaskType = 'local_workflow';
 export type WorkflowSource = 'inline' | 'script_path' | 'project' | 'user' | 'plugin' | 'built_in';
 export type WorkflowPermissionDecision = 'allow' | 'deny';
+export interface WorkflowPlanAgent {
+    readonly id?: string;
+    readonly title: string;
+    readonly focus?: string;
+    readonly label?: string;
+}
+export interface WorkflowPlanPhase {
+    readonly id?: string;
+    readonly title: string;
+    readonly goal?: string;
+    readonly agents: readonly WorkflowPlanAgent[];
+}
 export type WorkflowEvent = {
     readonly type: 'workflow.started';
     readonly taskId: string;
@@ -20,6 +32,13 @@ export type WorkflowEvent = {
     readonly phaseIndex: number;
     readonly title: string;
     readonly detail?: string;
+} | {
+    readonly type: 'workflow.plan.ready';
+    readonly taskId: string;
+    readonly runId: string;
+    readonly mode: string;
+    readonly rationale?: string;
+    readonly phases: readonly WorkflowPlanPhase[];
 } | {
     readonly type: 'workflow.log';
     readonly taskId: string;
@@ -250,6 +269,7 @@ export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private runAgentAttempt;
     private parallel;
     private pipeline;
+    private announcePlan;
     private phase;
     private completeTask;
     private failTask;

package/dist/runtime/workflow-runtime.js

@@ -98,40 +98,239 @@ const WORKSPACE_CONTEXT_PRIORITY_FILES = new Set([
     'package.json',
     'tsconfig.json',
 ]);
+const DYNAMIC_WORKFLOW_PATTERN_GUIDANCE = [
+    'Use dynamic workflow patterns intentionally:',
+    '- classify-and-act: classify the request, risk, or repository area before choosing phase shape.',
+    '- fan-out-and-synthesize: split independent lenses across parallel agents, then merge evidence.',
+    '- adversarial verification: assign at least one agent to challenge correctness, security, or assumptions on high-risk work.',
+    '- generate-and-filter: create candidate approaches or fixes, then select by evidence and constraints.',
+    '- tournament: compare competing alternatives when the best path is unclear.',
+    '- loop-until-done: iterate repair and verification only when there is a clear stop condition.',
+    'Prefer pipelines when later phases need earlier summaries; prefer parallel agents when independent evidence can be gathered at the same time.',
+].join('\n');
 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. Pick workflow patterns that match the request instead of using one fixed shape.',
+            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. Prefer fan-out-and-synthesize plus adversarial verification unless the diff is tiny 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)},
+  "",
+  ${JSON.stringify(DYNAMIC_WORKFLOW_PATTERN_GUIDANCE)},
+  "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;
+announcePlan({
+  mode: plan.mode,
+  rationale: plan.rationale,
+  phases: selectedPhases.map((phasePlan) => ({
+    id: phasePlan.id,
+    title: phasePlan.title,
+    goal: phasePlan.goal,
+    agents: (plan.mode === "single" ? [phasePlan.agents[0]] : phasePlan.agents).map((phaseAgent) => ({
+      id: phaseAgent.id,
+      title: phaseAgent.title,
+      focus: phaseAgent.focus,
+      label: plan.mode === "single"
+        ? ${JSON.stringify(`${input.name}-single`)}
+        : ${JSON.stringify(`${input.name}-`)} + phasePlan.id + "-" + phaseAgent.id
+    }))
+  }))
+});
+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();
@@ -878,6 +1077,7 @@ export class WorkflowTaskRegistry {
         host.workspaceContext = hardenCallable((options) => {
             return this.trackWorkflowPromise(ctx, this.workspaceContext(ctx, options));
         });
+        host.announcePlan = hardenCallable((plan) => this.announcePlan(ctx, plan));
         host.phase = hardenCallable((title) => this.phase(ctx, title));
         host.log = hardenCallable(log);
         host.consoleLog = hardenCallable((...values) => {
@@ -1324,6 +1524,18 @@ export class WorkflowTaskRegistry {
             return current;
         });
     }
+    announcePlan(ctx, plan) {
+        if (ctx.controller.signal.aborted || ctx.task.status !== 'running') {
+            throw workflowInputError('Workflow is aborted.');
+        }
+        const normalized = normalizeWorkflowExecutionPlan(plan);
+        this.emit(ctx.task, {
+            type: 'workflow.plan.ready',
+            taskId: ctx.task.taskId,
+            runId: ctx.task.runId,
+            ...normalized,
+        });
+    }
     phase(ctx, title) {
         if (typeof title !== 'string' || title.trim() === '') {
             throw workflowInputError('phase() requires a non-empty string title.');
@@ -2759,6 +2971,7 @@ function installWorkflowVmGlobals(context, globals) {
         '  define(globalThis, "parallel", { value: (...values) => __host.parallel(...values), writable: false, configurable: false });',
         '  define(globalThis, "pipeline", { value: (...values) => __host.pipeline(...values), writable: false, configurable: false });',
         '  define(globalThis, "workspaceContext", { value: (...values) => __host.workspaceContext(...values), writable: false, configurable: false });',
+        '  define(globalThis, "announcePlan", { value: (...values) => __host.announcePlan(...values), writable: false, configurable: false });',
         '  define(globalThis, "phase", { value: (...values) => __host.phase(...values), writable: false, configurable: false });',
         '  define(globalThis, "log", { value: (...values) => __host.log(...values), writable: false, configurable: false });',
         '  define(globalThis, "workflow", { value: (...values) => __host.workflow(...values), writable: false, configurable: false });',
@@ -3442,6 +3655,56 @@ function previewValue(value, limit) {
         : JSON.stringify(value) ?? String(value);
     return preview(text, limit);
 }
+function normalizeWorkflowExecutionPlan(value) {
+    const record = asRecord(value);
+    if (!record)
+        throw workflowInputError('announcePlan(plan) requires a plan object.');
+    const mode = boundedPlanString(record.mode, 'phase_parallel', 48);
+    const rationale = optionalBoundedPlanString(record.rationale, 400);
+    const rawPhases = Array.isArray(record.phases) ? Array.from(record.phases) : [];
+    if (rawPhases.length === 0)
+        throw workflowInputError('announcePlan(plan) requires at least one phase.');
+    const phases = rawPhases.slice(0, 16).map((phaseValue, phaseIndex) => {
+        const phase = asRecord(phaseValue);
+        if (!phase)
+            throw workflowInputError(`announcePlan(plan).phases[${phaseIndex}] must be an object.`);
+        const rawAgents = Array.isArray(phase.agents) ? Array.from(phase.agents) : [];
+        if (rawAgents.length === 0) {
+            throw workflowInputError(`announcePlan(plan).phases[${phaseIndex}].agents requires at least one agent.`);
+        }
+        return {
+            ...(typeof phase.id === 'string' && phase.id.trim() ? { id: boundedPlanString(phase.id, '', 48) } : {}),
+            title: boundedPlanString(phase.title, `Phase ${phaseIndex + 1}`, 96),
+            ...(typeof phase.goal === 'string' && phase.goal.trim() ? { goal: boundedPlanString(phase.goal, '', 600) } : {}),
+            agents: rawAgents.slice(0, 16).map((agentValue, agentIndex) => {
+                const agent = asRecord(agentValue);
+                if (!agent) {
+                    throw workflowInputError(`announcePlan(plan).phases[${phaseIndex}].agents[${agentIndex}] must be an object.`);
+                }
+                return {
+                    ...(typeof agent.id === 'string' && agent.id.trim() ? { id: boundedPlanString(agent.id, '', 48) } : {}),
+                    title: boundedPlanString(agent.title, `Agent ${agentIndex + 1}`, 96),
+                    ...(typeof agent.focus === 'string' && agent.focus.trim() ? { focus: boundedPlanString(agent.focus, '', 600) } : {}),
+                    ...(typeof agent.label === 'string' && agent.label.trim() ? { label: boundedPlanString(agent.label, '', 96) } : {}),
+                };
+            }),
+        };
+    });
+    return {
+        mode,
+        ...(rationale ? { rationale } : {}),
+        phases,
+    };
+}
+function boundedPlanString(value, fallback, limit) {
+    const text = typeof value === 'string' && value.trim() ? value.trim() : fallback;
+    return preview(text, limit);
+}
+function optionalBoundedPlanString(value, limit) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    return boundedPlanString(value, '', limit);
+}
 function asRecord(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return null;

package/package.json

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

package/settings.json

@@ -4,7 +4,7 @@
     "progress": "jsonl",
     "permission": "ask",
     "retryLimit": 0,
-    "timeoutMs": 180000,
+    "timeoutMs": 900000,
     "background": {
       "runDir": ".ultracode-for-codex/background/{jobId}",
       "resultFile": "result.json",

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

@@ -17,6 +17,15 @@ 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.
+Planner guidance includes classify-and-act, fan-out-and-synthesize,
+adversarial verification, generate-and-filter, tournament, and loop-until-done
+patterns so workflow shape can follow the task instead of a fixed template.
+
 ## Install And Run
 
 Use the npm package for consumer installs.
@@ -35,7 +44,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.5.tgz
 ```
 
 CLI behavior:
@@ -47,10 +56,13 @@ CLI behavior:
 - attached final workflow result prints as JSON to stdout;
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`,
   with agent identity and label fields on agent records;
+- built-in `task` and `code-review` emit `workflow.plan.ready` before phase
+  agents start, including phase titles and planned agent role labels;
 - `Ctrl-C` cancels the active attached workflow;
 - `--retry-limit <n>` retries failed workflows inside the same process;
 - `--timeout-ms` is the workflow timeout and the default per-agent silence
-  budget; it is not divided by the retry budget.
+  budget; the package default is `900000` ms, or 15 minutes, and it is not
+  divided by the retry budget.
 - `--permission ask|allow|deny` handles project/user/plugin/scriptPath reviews.
 - `--progress plain` switches to human-readable progress lines.
 - background file locations are controlled by `workflow.background` in
@@ -62,8 +74,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.