ultracode-for-codex 0.2.4 → 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.4.tgz
+npm install --save-dev /path/to/ultracode-for-codex-0.2.5.tgz
 ```
 
 Run a workflow:
@@ -68,6 +68,10 @@ 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
 
@@ -80,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",
@@ -94,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
 
@@ -101,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

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.4.tgz
+npm install --save-dev ./ultracode-for-codex-0.2.5.tgz
 ```
 
 Optional Codex companion skill:
@@ -63,6 +63,9 @@ 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:
 
@@ -73,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",
@@ -89,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

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,6 +98,16 @@ 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',
@@ -106,7 +116,7 @@ const DEFAULT_BUILTIN_WORKFLOWS = [
             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.',
+            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.',
         }),
@@ -118,7 +128,7 @@ const DEFAULT_BUILTIN_WORKFLOWS = [
             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.',
+            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.',
         }),
@@ -152,6 +162,8 @@ 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.",
   "",
@@ -202,6 +214,23 @@ const plan = await agent([
   }
 });
 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];
@@ -1048,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) => {
@@ -1494,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.');
@@ -2929,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 });',
@@ -3612,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.4",
+  "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

@@ -22,6 +22,9 @@ The default Ultracode work shape is phase-wise parallel execution: built-in
 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
 
@@ -41,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.4.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-0.2.5.tgz
 ```
 
 CLI behavior:
@@ -53,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