@nyxa/nyx-agent 0.3.1 → 0.3.2

package/dist/runtime/buildPrompt.js

@@ -41,6 +41,11 @@ 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),

package/dist/runtime/runPhase.js

@@ -83,6 +83,7 @@ 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 ?? [],

package/dist/runtime/runWorkflow.js

@@ -27,6 +27,7 @@ export async function runWorkflow(options) {
         current_iteration: 0,
         completed_iterations: 0,
         available_work_items: [],
+        recommended_work_item_queue: [],
         selected_work_item_queue: [],
         skipped_work_item_keys: [],
         selection_groups: [],
@@ -64,14 +65,17 @@ export async function runWorkflow(options) {
         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({
-            queue: selection.workItems,
+            availableWorkItems: selection.availableWorkItems,
             confirmed: await (options.confirmWorkItems ?? confirmWorkItemsWithCheckbox)({
-                workItems: selection.workItems,
+                availableWorkItems: selection.availableWorkItems,
+                recommendedWorkItems: selection.workItems,
+                workItems: selection.availableWorkItems,
                 selectionGroups: selection.selectionGroups,
                 maxIterations: config.workflow.max_iterations
             })
@@ -113,6 +117,7 @@ export async function runWorkflow(options) {
             status: "running",
             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],
@@ -202,6 +207,7 @@ async function runSelectionPhase(input) {
         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],
@@ -251,6 +257,7 @@ async function runSelectionPhase(input) {
     });
     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);
@@ -319,24 +326,29 @@ async function runWorkflowPhase(input) {
     return phaseResult;
 }
 export async function confirmWorkItemsWithCheckbox(input) {
-    if (input.workItems.length === 0) {
+    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: buildConfirmationChoices(input),
+        choices: confirmationView.choices,
         required: false,
-        pageSize: Math.min(Math.max(input.workItems.length + 2, 5), 20)
+        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 input.workItems.filter((item) => selected.has(item.key));
+    return confirmationView.workItems.filter((item) => selected.has(item.key));
 }
-function buildConfirmationChoices(input) {
+function buildConfirmationView(input) {
     const choices = [];
-    const byKey = new Map(input.workItems.map((item) => [item.key, item]));
+    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
@@ -352,25 +364,27 @@ function buildConfirmationChoices(input) {
         }
         choices.push(new Separator(`-- ${group.title} --`));
         for (const item of groupItems) {
-            choices.push(buildConfirmationChoice(item));
+            choices.push(buildConfirmationChoice(item, recommendedKeys));
+            workItems.push(item);
             displayed.add(item.key);
         }
     }
-    const ungroupedItems = input.workItems.filter((item) => !displayed.has(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));
+        choices.push(buildConfirmationChoice(item, recommendedKeys));
+        workItems.push(item);
     }
-    return choices;
+    return { choices, workItems };
 }
-function buildConfirmationChoice(item) {
+function buildConfirmationChoice(item, recommendedKeys) {
     return {
         value: item.key,
         name: `${item.title} (${item.key})`,
         description: item.excerpt,
-        checked: true
+        checked: recommendedKeys.has(item.key)
     };
 }
 function resolveNextTarget(phase, outcome) {
@@ -429,19 +443,19 @@ function readSelectedWorkItems(input) {
     return validation.workItems;
 }
 function normalizeConfirmedWorkItems(input) {
-    const queuedByKey = new Map(input.queue.map((item) => [item.key, item]));
+    const availableByKey = new Map(input.availableWorkItems.map((item) => [item.key, item]));
     const selected = new Set();
     const normalized = [];
     for (const item of input.confirmed) {
-        const queued = queuedByKey.get(item.key);
-        if (!queued) {
-            throw new Error(`Confirmed work item key "${item.key}" is not in selected queue`);
+        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(queued);
+        normalized.push(available);
     }
     return normalized;
 }

package/docs/nyxagent-v0-spec.md

@@ -185,12 +185,13 @@ max_visits_per_iteration = 1
 - `work_items.excerpt_chars` defaults to `800` and bounds candidate excerpts.
 - 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 `work_items` queue. NyxAgent validates
-  each selected identity against `[work_items]`, rejects duplicates, and
-  requires every selected key to exist in `available_work_items`.
-- Before executing, NyxAgent shows the selected queue in an interactive
-  checkbox prompt. The user can uncheck work items; only confirmed items are
-  executed.
+- 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.
@@ -199,7 +200,8 @@ max_visits_per_iteration = 1
   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
-  and may include optional `selection_groups` for user review.
+  and may include optional `selection_groups` for user review. Groups may cover
+  the full available inventory, not only the recommended queue.
 
 ## Workflow Model
 
@@ -222,7 +224,7 @@ only knows phases, outcomes, transitions, and visit limits.
 The default template expresses the standard run:
 
 ```text
-selection -> user confirms queue
+selection -> user confirms inventory with recommended queue pre-checked
 for each confirmed work item:
   execution -> review
 review.approved -> closure -> next_iteration
@@ -299,6 +301,7 @@ 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`
@@ -314,6 +317,7 @@ 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}}
@@ -381,8 +385,9 @@ Each run creates a timestamped directory:
 - 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 selected work item keys
+- skipped recommended work item keys
 - selection groups returned for user review
 - seen work item keys
 - completed work item keys
@@ -442,14 +447,15 @@ Default prompts should be concise but operational.
 
 Selection:
 
-- choose an ordered queue 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 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 plan or PRD
+- 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.1",
+  "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,13 +1,16 @@
-Select the ordered work item queue for this run.
+Recommend the ordered work item queue for this run.
 
 Use `available_work_items` from the runtime contract as the complete inventory
-for selection. Some candidates may be plans, PRDs, or concrete tasks. Build the
-most actionable queue for this run, up to `workflow.max_iterations` items.
+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 candidates appear to belong to the same plan or PRD, keep related concrete
-tasks together and use `selection_groups` to describe the grouping. The grouping
-is only for user review; every executable item must still be included in
-`work_items`.
+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.
@@ -27,7 +30,7 @@ The selected work item identities must match the inventory entries:
 
 Return one of these outcomes:
 
-- `selected`: include ordered `work_items`; optionally include
+- `selected`: include recommended ordered `work_items`; optionally include
   `selection_groups` with `title`, optional `kind`, and `work_item_keys`
 - `no_work`: include a short `reason`