@nyxa/nyx-agent 0.3.0 → 0.3.2

package/dist/runtime/buildPrompt.js

@@ -41,6 +41,16 @@ async function buildRuntimeContract(input) {
         JSON.stringify(input.context.available_work_items ?? [], null, 2),
         "```",
         "",
+        "Recommended work item queue:",
+        "```json",
+        JSON.stringify(input.context.recommended_work_item_queue ?? [], null, 2),
+        "```",
+        "",
+        "Selected work item queue:",
+        "```json",
+        JSON.stringify(input.context.selected_work_item_queue ?? [], null, 2),
+        "```",
+        "",
         "Seen work item keys:",
         "```json",
         JSON.stringify(input.context.seen_work_item_keys ?? [], null, 2),

package/dist/runtime/runPhase.js

@@ -8,7 +8,7 @@ import { parseNyxAgentResult, getOutcome } from "./parseResult.js";
 import { resolveNyxPath } from "./paths.js";
 import { renderTemplate } from "./renderTemplate.js";
 import { validateAgainstSchema } from "./validateResult.js";
-import { validateWorkItemIdentity } from "./validateWorkItem.js";
+import { validateWorkItemIdentity, validateWorkItemQueue } from "./validateWorkItem.js";
 export async function runPhase(input) {
     const phaseDir = path.join(input.iterationDir, "phases", input.phase.id);
     await ensureDir(phaseDir);
@@ -83,6 +83,8 @@ function buildContext(input) {
         workflow: input.config.workflow,
         work_items: input.config.work_items ?? {},
         available_work_items: input.state.available_work_items ?? [],
+        recommended_work_item_queue: input.state.recommended_work_item_queue ?? [],
+        selected_work_item_queue: input.state.selected_work_item_queue ?? [],
         work_item: input.state.work_item ?? {},
         seen_work_item_keys: input.state.seen_work_item_keys ?? [],
         completed_work_item_keys: input.state.completed_work_item_keys ?? [],
@@ -190,6 +192,19 @@ async function parseAndValidatePhaseResult(input) {
             return workItemValidation;
         }
     }
+    const workItems = readObjectProperty(parsed.value, "work_items");
+    if (workItems !== undefined) {
+        const workItemQueueValidation = validateWorkItemQueue({
+            config: input.input.config,
+            workItems,
+            availableWorkItems: readWorkItemCandidates(input.input.state.available_work_items),
+            seenWorkItemKeys: readStringArray(input.input.state.seen_work_item_keys),
+            completedWorkItemKeys: readStringArray(input.input.state.completed_work_item_keys)
+        });
+        if (!workItemQueueValidation.ok) {
+            return workItemQueueValidation;
+        }
+    }
     await writeJson(path.join(input.phaseDir, "result.json"), parsed.value);
     return {
         ok: true,

package/dist/runtime/runWorkflow.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { checkbox, Separator } from "@inquirer/prompts";
 import pc from "picocolors";
 import { loadConfig } from "../config/loadConfig.js";
 import { ensureDir, writeJson } from "./files.js";
@@ -7,6 +8,7 @@ import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger } from "
 import { getNyxDir, relativeToProject } from "./paths.js";
 import { runPhase } from "./runPhase.js";
 import { createRunId } from "./time.js";
+import { validateWorkItemQueue } from "./validateWorkItem.js";
 import { filterAvailableWorkItems, listWorkItemCandidates } from "./workItems.js";
 export async function runWorkflow(options) {
     const projectRoot = path.resolve(options.projectRoot);
@@ -24,6 +26,11 @@ export async function runWorkflow(options) {
         status: "running",
         current_iteration: 0,
         completed_iterations: 0,
+        available_work_items: [],
+        recommended_work_item_queue: [],
+        selected_work_item_queue: [],
+        skipped_work_item_keys: [],
+        selection_groups: [],
         seen_work_item_keys: [],
         completed_work_item_keys: [...ledger.completed_work_item_keys],
         last_completed_work_item: ledger.last_completed_work_item
@@ -46,21 +53,72 @@ export async function runWorkflow(options) {
     console.log(`Model: ${config.model.name}`);
     console.log("");
     const phasesById = new Map(config.phases.map((phase) => [phase.id, phase]));
-    for (let iterationNumber = 1; iterationNumber <= config.workflow.max_iterations; iterationNumber += 1) {
+    const selection = await runSelectionPhase({
+        projectRoot,
+        runDir,
+        config,
+        phasesById,
+        runState,
+        ledger
+    });
+    if (selection.status === "stopped") {
+        return;
+    }
+    runState.available_work_items = selection.availableWorkItems;
+    runState.recommended_work_item_queue = selection.workItems;
+    runState.selection_groups = selection.selectionGroups;
+    await writeJson(path.join(runDir, "state.json"), runState);
+    let confirmedWorkItems;
+    try {
+        confirmedWorkItems = normalizeConfirmedWorkItems({
+            availableWorkItems: selection.availableWorkItems,
+            confirmed: await (options.confirmWorkItems ?? confirmWorkItemsWithCheckbox)({
+                availableWorkItems: selection.availableWorkItems,
+                recommendedWorkItems: selection.workItems,
+                workItems: selection.availableWorkItems,
+                selectionGroups: selection.selectionGroups,
+                maxIterations: config.workflow.max_iterations
+            })
+        });
+    }
+    catch (error) {
+        runState.status = "failed";
+        await writeJson(path.join(runDir, "state.json"), runState);
+        throw error;
+    }
+    const selectedWorkItems = confirmedWorkItems.slice(0, config.workflow.max_iterations);
+    const selectedKeys = new Set(selectedWorkItems.map((item) => item.key));
+    runState.selected_work_item_queue = selectedWorkItems;
+    runState.skipped_work_item_keys = selection.workItems
+        .filter((item) => !selectedKeys.has(item.key))
+        .map((item) => item.key);
+    runState.seen_work_item_keys = selectedWorkItems.map((item) => item.key);
+    await writeJson(path.join(runDir, "state.json"), runState);
+    if (confirmedWorkItems.length > config.workflow.max_iterations) {
+        console.log(pc.yellow(`Only the first ${config.workflow.max_iterations} selected work items will run.`));
+    }
+    if (selectedWorkItems.length === 0) {
+        runState.status = "completed_no_selected_work";
+        await writeJson(path.join(runDir, "state.json"), runState);
+        console.log("");
+        console.log(`Done: ${runState.status}`);
+        console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
+        return;
+    }
+    for (let queueIndex = 0; queueIndex < selectedWorkItems.length; queueIndex += 1) {
+        const iterationNumber = queueIndex + 1;
+        const workItem = selectedWorkItems[queueIndex];
         runState.current_iteration = iterationNumber;
         await writeJson(path.join(runDir, "state.json"), runState);
         const iterationDir = path.join(runDir, "iterations", String(iterationNumber).padStart(3, "0"));
         await ensureDir(iterationDir);
-        const availableWorkItems = await loadAvailableWorkItems({
-            projectRoot,
-            config,
-            runState,
-            ledger
-        });
         const iterationState = {
             iteration: iterationNumber,
             status: "running",
-            available_work_items: availableWorkItems,
+            work_item: workItem,
+            available_work_items: selectedWorkItems,
+            recommended_work_item_queue: selection.workItems,
+            selected_work_item_queue: selectedWorkItems,
             seen_work_item_keys: [...runState.seen_work_item_keys],
             completed_work_item_keys: [...ledger.completed_work_item_keys],
             last_completed_work_item: ledger.last_completed_work_item,
@@ -69,62 +127,31 @@ export async function runWorkflow(options) {
         };
         const iterationStateFile = path.join(iterationDir, "state.json");
         await writeJson(iterationStateFile, iterationState);
-        let currentPhaseId = config.workflow.entry_phase;
+        let currentPhaseId = selection.nextPhaseId;
         while (currentPhaseId) {
             const phase = phasesById.get(currentPhaseId);
             if (!phase) {
                 throw new Error(`Unknown phase "${currentPhaseId}"`);
             }
-            const visits = (iterationState.phase_visit_counts[phase.id] ?? 0) + 1;
-            iterationState.phase_visit_counts[phase.id] = visits;
-            if (visits > phase.max_visits_per_iteration) {
-                iterationState.status = "failed";
-                runState.status = "failed";
-                await writeJson(iterationStateFile, iterationState);
-                await writeJson(path.join(runDir, "state.json"), runState);
-                throw new Error(`Phase "${phase.id}" exceeded max_visits_per_iteration=${phase.max_visits_per_iteration}`);
-            }
-            process.stdout.write(`[${iterationNumber}/${config.workflow.max_iterations}] ${phase.id} ... `);
-            await writeJson(iterationStateFile, iterationState);
-            const phaseResult = await runPhase({
+            const phaseResult = await runWorkflowPhase({
                 projectRoot,
                 runDir,
                 iterationDir,
-                stateFile: iterationStateFile,
+                iterationStateFile,
                 config,
                 phase,
-                state: iterationState
+                iterationState,
+                runState,
+                iterationNumber,
+                maxIterations: selectedWorkItems.length
             });
             if (!phaseResult.ok) {
-                console.log(pc.red("failed"));
-                iterationState.status = "failed";
-                iterationState.phase_results[phase.id] = {
-                    status: "failed",
-                    error: phaseResult.error
-                };
-                runState.status = "failed";
-                await writeJson(iterationStateFile, iterationState);
-                await writeJson(path.join(runDir, "state.json"), runState);
                 throw new Error(phaseResult.error);
             }
-            iterationState.phase_results[phase.id] =
-                phaseResult.result ?? { status: "ok" };
-            const workItem = readObjectProperty(phaseResult.result, "work_item");
-            if (workItem !== undefined) {
-                iterationState.work_item = workItem;
-                const key = readObjectProperty(workItem, "key");
-                if (typeof key === "string" && !runState.seen_work_item_keys.includes(key)) {
-                    runState.seen_work_item_keys.push(key);
-                    iterationState.seen_work_item_keys = [...runState.seen_work_item_keys];
-                }
-            }
             const nextTarget = resolveNextTarget(phase, phaseResult.outcome);
-            const label = phaseResult.outcome ?? "ok";
-            console.log(pc.green(label));
-            await writeJson(iterationStateFile, iterationState);
-            await writeJson(path.join(runDir, "state.json"), runState);
             if (nextTarget === "stop_run") {
-                iterationState.status = phaseResult.outcome === "no_work" ? "no_work" : "stopped";
+                iterationState.status =
+                    phaseResult.outcome === "no_work" ? "no_work" : "stopped";
                 runState.status =
                     phaseResult.outcome === "no_work" ? "completed_no_work" : "stopped";
                 await writeJson(iterationStateFile, iterationState);
@@ -154,12 +181,212 @@ export async function runWorkflow(options) {
             currentPhaseId = nextTarget;
         }
     }
-    runState.status = "completed_max_iterations";
+    runState.status =
+        selectedWorkItems.length >= config.workflow.max_iterations
+            ? "completed_max_iterations"
+            : "completed_queue";
     await writeJson(path.join(runDir, "state.json"), runState);
     console.log("");
     console.log(`Done: ${runState.status}`);
     console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
 }
+async function runSelectionPhase(input) {
+    const selectionPhase = input.phasesById.get(input.config.workflow.entry_phase);
+    if (!selectionPhase) {
+        throw new Error(`Unknown phase "${input.config.workflow.entry_phase}"`);
+    }
+    const availableWorkItems = await loadAvailableWorkItems({
+        projectRoot: input.projectRoot,
+        config: input.config,
+        runState: input.runState,
+        ledger: input.ledger
+    });
+    const selectionDir = path.join(input.runDir, "selection");
+    await ensureDir(selectionDir);
+    const selectionState = {
+        iteration: 0,
+        status: "running",
+        available_work_items: availableWorkItems,
+        recommended_work_item_queue: [],
+        selected_work_item_queue: [],
+        seen_work_item_keys: [...input.runState.seen_work_item_keys],
+        completed_work_item_keys: [...input.ledger.completed_work_item_keys],
+        last_completed_work_item: input.ledger.last_completed_work_item,
+        phase_results: {},
+        phase_visit_counts: {}
+    };
+    const selectionStateFile = path.join(selectionDir, "state.json");
+    await writeJson(selectionStateFile, selectionState);
+    const phaseResult = await runWorkflowPhase({
+        projectRoot: input.projectRoot,
+        runDir: input.runDir,
+        iterationDir: selectionDir,
+        iterationStateFile: selectionStateFile,
+        config: input.config,
+        phase: selectionPhase,
+        iterationState: selectionState,
+        runState: input.runState,
+        iterationNumber: "selection",
+        maxIterations: input.config.workflow.max_iterations
+    });
+    if (!phaseResult.ok) {
+        throw new Error(phaseResult.error);
+    }
+    const nextTarget = resolveNextTarget(selectionPhase, phaseResult.outcome);
+    if (nextTarget === "stop_run") {
+        selectionState.status =
+            phaseResult.outcome === "no_work" ? "no_work" : "stopped";
+        input.runState.status =
+            phaseResult.outcome === "no_work" ? "completed_no_work" : "stopped";
+        await writeJson(selectionStateFile, selectionState);
+        await writeJson(path.join(input.runDir, "state.json"), input.runState);
+        console.log("");
+        console.log(`Done: ${input.runState.status}`);
+        console.log(`Run dir: ${relativeToProject(input.projectRoot, input.runDir)}`);
+        return { status: "stopped" };
+    }
+    if (!nextTarget || isReservedTarget(nextTarget)) {
+        throw new Error(`Selection phase must transition to a runnable phase, got "${nextTarget ?? "none"}"`);
+    }
+    const workItems = readSelectedWorkItems({
+        config: input.config,
+        result: phaseResult.result,
+        availableWorkItems,
+        seenWorkItemKeys: selectionState.seen_work_item_keys,
+        completedWorkItemKeys: selectionState.completed_work_item_keys
+    });
+    const selectionGroups = readSelectionGroups(phaseResult.result);
+    selectionState.status = "completed";
+    selectionState.recommended_work_item_queue = workItems;
+    selectionState.selected_work_item_queue = workItems;
+    await writeJson(selectionStateFile, selectionState);
+    await writeJson(path.join(input.runDir, "state.json"), input.runState);
+    return {
+        status: "selected",
+        workItems,
+        selectionGroups,
+        availableWorkItems,
+        nextPhaseId: nextTarget
+    };
+}
+async function runWorkflowPhase(input) {
+    const visits = (input.iterationState.phase_visit_counts[input.phase.id] ?? 0) + 1;
+    input.iterationState.phase_visit_counts[input.phase.id] = visits;
+    if (visits > input.phase.max_visits_per_iteration) {
+        input.iterationState.status = "failed";
+        input.runState.status = "failed";
+        await writeJson(input.iterationStateFile, input.iterationState);
+        await writeJson(path.join(input.runDir, "state.json"), input.runState);
+        return {
+            ok: false,
+            error: `Phase "${input.phase.id}" exceeded max_visits_per_iteration=${input.phase.max_visits_per_iteration}`
+        };
+    }
+    process.stdout.write(`[${input.iterationNumber}/${input.maxIterations}] ${input.phase.id} ... `);
+    await writeJson(input.iterationStateFile, input.iterationState);
+    const phaseResult = await runPhase({
+        projectRoot: input.projectRoot,
+        runDir: input.runDir,
+        iterationDir: input.iterationDir,
+        stateFile: input.iterationStateFile,
+        config: input.config,
+        phase: input.phase,
+        state: input.iterationState
+    });
+    if (!phaseResult.ok) {
+        console.log(pc.red("failed"));
+        input.iterationState.status = "failed";
+        input.iterationState.phase_results[input.phase.id] = {
+            status: "failed",
+            error: phaseResult.error
+        };
+        input.runState.status = "failed";
+        await writeJson(input.iterationStateFile, input.iterationState);
+        await writeJson(path.join(input.runDir, "state.json"), input.runState);
+        return phaseResult;
+    }
+    input.iterationState.phase_results[input.phase.id] =
+        phaseResult.result ?? { status: "ok" };
+    const workItem = readObjectProperty(phaseResult.result, "work_item");
+    if (workItem !== undefined && input.iterationNumber !== "selection") {
+        input.iterationState.work_item = workItem;
+        const key = readObjectProperty(workItem, "key");
+        if (typeof key === "string" &&
+            !input.runState.seen_work_item_keys.includes(key)) {
+            input.runState.seen_work_item_keys.push(key);
+            input.iterationState.seen_work_item_keys = [
+                ...input.runState.seen_work_item_keys
+            ];
+        }
+    }
+    const label = phaseResult.outcome ?? "ok";
+    console.log(pc.green(label));
+    await writeJson(input.iterationStateFile, input.iterationState);
+    await writeJson(path.join(input.runDir, "state.json"), input.runState);
+    return phaseResult;
+}
+export async function confirmWorkItemsWithCheckbox(input) {
+    if (input.availableWorkItems.length === 0) {
+        return [];
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Work item selection confirmation requires an interactive TTY");
+    }
+    const confirmationView = buildConfirmationView(input);
+    const selectedKeys = await checkbox({
+        message: `Confirm work items to run (max ${input.maxIterations})`,
+        choices: confirmationView.choices,
+        required: false,
+        pageSize: Math.min(Math.max(input.availableWorkItems.length + 2, 5), 20),
+        validate: (selected) => selected.length <= input.maxIterations ||
+            `Select at most ${input.maxIterations} work items.`
+    });
+    const selected = new Set(selectedKeys);
+    return confirmationView.workItems.filter((item) => selected.has(item.key));
+}
+function buildConfirmationView(input) {
+    const choices = [];
+    const workItems = [];
+    const byKey = new Map(input.availableWorkItems.map((item) => [item.key, item]));
+    const recommendedKeys = new Set(input.recommendedWorkItems.map((item) => item.key));
+    const displayed = new Set();
+    for (const group of input.selectionGroups) {
+        const groupItems = group.work_item_keys
+            .map((key) => byKey.get(key))
+            .filter((item) => {
+            if (!item) {
+                return false;
+            }
+            return !displayed.has(item.key);
+        });
+        if (groupItems.length === 0) {
+            continue;
+        }
+        choices.push(new Separator(`-- ${group.title} --`));
+        for (const item of groupItems) {
+            choices.push(buildConfirmationChoice(item, recommendedKeys));
+            workItems.push(item);
+            displayed.add(item.key);
+        }
+    }
+    const ungroupedItems = input.availableWorkItems.filter((item) => !displayed.has(item.key));
+    if (input.selectionGroups.length > 0 && ungroupedItems.length > 0) {
+        choices.push(new Separator("-- Ungrouped --"));
+    }
+    for (const item of ungroupedItems) {
+        choices.push(buildConfirmationChoice(item, recommendedKeys));
+        workItems.push(item);
+    }
+    return { choices, workItems };
+}
+function buildConfirmationChoice(item, recommendedKeys) {
+    return {
+        value: item.key,
+        name: `${item.title} (${item.key})`,
+        description: item.excerpt,
+        checked: recommendedKeys.has(item.key)
+    };
+}
 function resolveNextTarget(phase, outcome) {
     if (phase.transitions) {
         if (!outcome) {
@@ -196,6 +423,74 @@ async function completeIterationWorkItem(input) {
     await writeWorkItemLedger(input.nyxDir, ledger);
     return ledger;
 }
+function readSelectedWorkItems(input) {
+    const workItems = readObjectProperty(input.result, "work_items");
+    const legacyWorkItem = readObjectProperty(input.result, "work_item");
+    const selection = workItems ?? (legacyWorkItem === undefined ? undefined : [legacyWorkItem]);
+    if (selection === undefined) {
+        throw new Error('Selection phase returned "selected" without work_items');
+    }
+    const validation = validateWorkItemQueue({
+        config: input.config,
+        workItems: selection,
+        availableWorkItems: input.availableWorkItems,
+        seenWorkItemKeys: input.seenWorkItemKeys,
+        completedWorkItemKeys: input.completedWorkItemKeys
+    });
+    if (!validation.ok) {
+        throw new Error(validation.error);
+    }
+    return validation.workItems;
+}
+function normalizeConfirmedWorkItems(input) {
+    const availableByKey = new Map(input.availableWorkItems.map((item) => [item.key, item]));
+    const selected = new Set();
+    const normalized = [];
+    for (const item of input.confirmed) {
+        const available = availableByKey.get(item.key);
+        if (!available) {
+            throw new Error(`Confirmed work item key "${item.key}" is not in available_work_items`);
+        }
+        if (selected.has(item.key)) {
+            throw new Error(`Confirmed work item key "${item.key}" was selected twice`);
+        }
+        selected.add(item.key);
+        normalized.push(available);
+    }
+    return normalized;
+}
+function readSelectionGroups(result) {
+    const groups = readObjectProperty(result, "selection_groups");
+    if (!Array.isArray(groups)) {
+        return [];
+    }
+    return groups
+        .map((group) => {
+        if (!isRecord(group) || typeof group.title !== "string") {
+            return undefined;
+        }
+        const keys = Array.isArray(group.work_item_keys)
+            ? group.work_item_keys.filter((key) => typeof key === "string")
+            : [];
+        if (keys.length === 0) {
+            return undefined;
+        }
+        const normalized = {
+            title: group.title,
+            work_item_keys: keys
+        };
+        if (typeof group.kind === "string") {
+            normalized.kind = group.kind;
+        }
+        return normalized;
+    })
+        .filter((group) => Boolean(group));
+}
+function isReservedTarget(target) {
+    return (target === "stop_run" ||
+        target === "stop_iteration" ||
+        target === "next_iteration");
+}
 function readObjectProperty(value, key) {
     if (value &&
         typeof value === "object" &&
@@ -204,3 +499,6 @@ function readObjectProperty(value, key) {
     }
     return undefined;
 }
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/runtime/validateWorkItem.js

@@ -73,6 +73,54 @@ export function validateWorkItemIdentity(input) {
     }
     return { ok: true };
 }
+export function validateWorkItemQueue(input) {
+    if (!Array.isArray(input.workItems)) {
+        return {
+            ok: false,
+            error: "Selected work_items must be an array"
+        };
+    }
+    if (input.workItems.length === 0) {
+        return {
+            ok: false,
+            error: "Selected work_items must contain at least one item"
+        };
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const [index, workItem] of input.workItems.entries()) {
+        const validation = validateWorkItemIdentity({
+            config: input.config,
+            workItem,
+            availableWorkItems: input.availableWorkItems,
+            seenWorkItemKeys: input.seenWorkItemKeys,
+            completedWorkItemKeys: input.completedWorkItemKeys
+        });
+        if (!validation.ok) {
+            return {
+                ok: false,
+                error: `Selected work_items[${index}] ${validation.error}`
+            };
+        }
+        const key = readObjectProperty(workItem, "key");
+        if (typeof key !== "string") {
+            return {
+                ok: false,
+                error: `Selected work_items[${index}] key must be a string`
+            };
+        }
+        if (seen.has(key)) {
+            return {
+                ok: false,
+                error: `Selected work_items contains duplicate key "${key}"`
+            };
+        }
+        seen.add(key);
+        const candidate = input.availableWorkItems?.find((item) => item.key === key);
+        normalized.push(candidate ?? workItem);
+    }
+    return { ok: true, workItems: normalized };
+}
 function validateCandidateMembership(input) {
     const candidate = input.availableWorkItems.find((item) => item.key === input.key);
     if (!candidate) {
@@ -154,3 +202,11 @@ function normalizeRelativePath(value) {
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+function readObjectProperty(value, key) {
+    if (value &&
+        typeof value === "object" &&
+        Object.prototype.hasOwnProperty.call(value, key)) {
+        return value[key];
+    }
+    return undefined;
+}

package/docs/nyxagent-v0-spec.md

@@ -16,7 +16,8 @@ configuration.
 ## Goals
 
 - Install a `.nyxagent/` folder into a project with sensible templates.
-- Run a configurable phase workflow for up to `max_iterations` work items.
+- Select an ordered work-item queue once, then run a configurable phase workflow
+  for up to `max_iterations` confirmed work items.
 - Launch a fresh harness process for each phase.
 - Keep workflow structure generic through phase transitions and outcomes.
 - Keep prompts focused on agent behavior, not runtime mechanics.
@@ -171,8 +172,8 @@ max_visits_per_iteration = 1
 
 ### Config Semantics
 
-- `workflow.max_iterations` is the maximum number of distinct work items in a
-  run.
+- `workflow.max_iterations` is the maximum number of distinct confirmed work
+  items in a run.
 - `phases[*].max_visits_per_iteration` prevents infinite loops inside one work
   item.
 - `model.reasoning_level` is a harness-neutral string.
@@ -180,13 +181,17 @@ max_visits_per_iteration = 1
 - Per-phase `model` and `harness` blocks override global values.
 - `work_items` supports only `local` and `github` in v0.
 - `work_items.max_candidates` defaults to `50` and caps the inventory sent to
-  the selection prompt.
+  the initial selection prompt.
 - `work_items.excerpt_chars` defaults to `800` and bounds candidate excerpts.
-- The engine scans the configured provider, normalizes candidates into
-  `available_work_items`, and injects that inventory into runtime context.
-- The engine validates the selected `work_item` identity against `[work_items]`
-  and requires the selected key to exist in `available_work_items` before
-  recording phase results.
+- At run start, the engine scans the configured provider, normalizes candidates
+  into `available_work_items`, and sends that inventory to the selection phase.
+- The selection phase returns an ordered recommended `work_items` queue.
+  NyxAgent validates each recommended identity against `[work_items]`, rejects
+  duplicates, and requires every selected key to exist in
+  `available_work_items`.
+- Before executing, NyxAgent shows the full `available_work_items` inventory in
+  an interactive checkbox prompt. The recommended queue is pre-checked, and the
+  user can add or remove available items. Only confirmed items are executed.
 - Local markdown work items do not have a required frontmatter schema. The
   provider infers titles from the first heading or filename and includes a
   bounded content excerpt.
@@ -194,7 +199,9 @@ max_visits_per_iteration = 1
 - GitHub keys use `github:<owner>/<repo>#<issue-number>` and must match the
   configured repository.
 - NyxAgent does not decide whether an item is a plan, PRD, or task. The
-  selection agent makes that semantic choice from the deterministic inventory.
+  selection agent makes that semantic choice from the deterministic inventory
+  and may include optional `selection_groups` for user review. Groups may cover
+  the full available inventory, not only the recommended queue.
 
 ## Workflow Model
 
@@ -214,10 +221,12 @@ Reserved next targets:
 The engine does not know about development, review, approval, or closure. It
 only knows phases, outcomes, transitions, and visit limits.
 
-The default template expresses the standard loop:
+The default template expresses the standard run:
 
 ```text
-selection -> execution -> review
+selection -> user confirms inventory with recommended queue pre-checked
+for each confirmed work item:
+  execution -> review
 review.approved -> closure -> next_iteration
 review.changes_requested -> execution
 selection.no_work -> stop_run
@@ -292,6 +301,8 @@ The runtime contract includes:
 - work item context, when selected
 - work item config from `[work_items]`
 - `available_work_items`
+- `recommended_work_item_queue`
+- `selected_work_item_queue`
 - `seen_work_item_keys`
 - `completed_work_item_keys`
 - `last_completed_work_item`
@@ -306,6 +317,8 @@ Prompts may use simple interpolation:
 {{iteration_dir}}
 {{phase_dir}}
 {{state_file}}
+{{recommended_work_item_queue}}
+{{selected_work_item_queue}}
 {{work_item.key}}
 {{work_item.title}}
 {{model.name}}
@@ -322,17 +335,20 @@ Each run creates a timestamped directory:
 .nyxagent/runs/2026-05-23T12-30-00/
   run.json
   state.json
+  selection/
+    state.json
+    phases/
+      selection/
+        attempt-001/
+          prompt.md
+          stdout.log
+          stderr.log
+          meta.json
+        result.json
   iterations/
     001/
       state.json
       phases/
-        selection/
-          attempt-001/
-            prompt.md
-            stdout.log
-            stderr.log
-            meta.json
-          result.json
         execution/
           attempt-001/
             prompt.md
@@ -368,6 +384,11 @@ Each run creates a timestamped directory:
 - run status
 - current iteration
 - completed iterations
+- available work items seen by the initial selection phase
+- recommended work item queue returned by the selection agent
+- selected work item queue confirmed for the run
+- skipped recommended work item keys
+- selection groups returned for user review
 - seen work item keys
 - completed work item keys
 - last completed work item
@@ -382,7 +403,7 @@ Each run creates a timestamped directory:
 
 - iteration number
 - work item
-- available work items for the iteration
+- selected work item queue for the run
 - seen work item keys
 - completed work item keys
 - last completed work item
@@ -426,13 +447,15 @@ Default prompts should be concise but operational.
 
 Selection:
 
-- choose one item from `available_work_items`
+- recommend an ordered queue from `available_work_items`
 - treat candidates agnostically: they may be plans, PRDs, or tasks
-- prefer the most actionable item based on the candidate title and excerpt
+- prefer the most actionable items based on candidate titles and excerpts
 - if a plan references concrete candidate tasks, choose the concrete task when
   that is the best next work
 - avoid keys already present in `seen_work_item_keys` or
   `completed_work_item_keys`
+- optionally include `selection_groups` to present related work by the most
+  useful grouping the agent can infer
 - return `selected` or `no_work`
 
 Execution:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyxa/nyx-agent",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {

package/templates/default/prompts/selection.md

@@ -1,19 +1,26 @@
-Select exactly one work item for this iteration.
+Recommend the ordered work item queue for this run.
 
 Use `available_work_items` from the runtime contract as the complete inventory
-for this selection. Some candidates may be plans, PRDs, or concrete tasks. Pick
-the most actionable next item from the provided context.
+for selection. Some candidates may be plans, PRDs, or concrete tasks.
+Recommend the most actionable queue for this run, up to
+`workflow.max_iterations` items. NyxAgent will show the complete inventory to
+the user afterward with your recommendation pre-selected.
 
-If a candidate is a plan that references more concrete candidates also present
-in `available_work_items`, you may choose the concrete task. If the plan itself
-is the best next work, choose the plan. If no candidate is exploitable, return
-`no_work`.
+If candidates appear to belong together, use `selection_groups` to describe the
+most useful review grouping. Infer grouping from titles, paths, excerpts, and
+declared relationships when available, but do not assume every project uses
+plan/PRD subdirectories. Groups may include any key from `available_work_items`,
+including items that are not part of your recommended `work_items` queue.
+
+Prefer concrete tasks over their parent plan when both are present and the task
+is ready to execute. Choose the plan itself only when it is the best next work.
+If no candidate is exploitable, return `no_work`.
 
 Do not choose any key listed in `seen_work_item_keys` or
-`completed_work_item_keys`. The selected work item must be copied from
-`available_work_items`; do not invent a key.
+`completed_work_item_keys`. Every selected work item must be copied from
+`available_work_items`; do not invent keys.
 
-The selected work item identity must match the inventory entry:
+The selected work item identities must match the inventory entries:
 
 - local: `source.type` is `local`, `source.locator` is the project-relative
   markdown path, and `key` is `local:<source.locator>`.
@@ -23,7 +30,11 @@ The selected work item identity must match the inventory entry:
 
 Return one of these outcomes:
 
-- `selected`: include a stable `work_item`
+- `selected`: include recommended ordered `work_items`; optionally include
+  `selection_groups` with `title`, optional `kind`, and `work_item_keys`
 - `no_work`: include a short `reason`
 
+For compatibility, `work_item` is still accepted for a single selected item, but
+new results should use `work_items`.
+
 Do not modify project files or task files during selection.

package/templates/default/schemas/selection.schema.json

@@ -2,12 +2,8 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "required": ["outcome"],
-  "properties": {
-    "outcome": {
-      "type": "string",
-      "enum": ["selected", "no_work"]
-    },
-    "work_item": {
+  "$defs": {
+    "workItem": {
       "type": "object",
       "required": ["key", "title", "source"],
       "properties": {
@@ -39,6 +35,47 @@
         }
       },
       "additionalProperties": true
+    }
+  },
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": ["selected", "no_work"]
+    },
+    "work_items": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/workItem"
+      }
+    },
+    "work_item": {
+      "$ref": "#/$defs/workItem"
+    },
+    "selection_groups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["title", "work_item_keys"],
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string"
+          },
+          "work_item_keys": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "additionalProperties": true
+      }
     },
     "reason": {
       "type": "string"
@@ -54,7 +91,14 @@
         }
       },
       "then": {
-        "required": ["work_item"]
+        "anyOf": [
+          {
+            "required": ["work_items"]
+          },
+          {
+            "required": ["work_item"]
+          }
+        ]
       }
     },
     {