@nyxa/nyx-agent 0.4.1 → 0.6.0

package/docs/nyxagent-v0-spec.md

@@ -1,742 +0,0 @@
-# NyxAgent v0 Spec
-
-## Purpose
-
-NyxAgent is a lightweight orchestration CLI for repeatedly launching coding
-agents against work items without carrying long-lived agent context across
-tasks or phases.
-
-The tool is primarily built for personal use, but the v0 architecture should be
-simple, explicit, and configurable enough for other repositories and harnesses.
-
-NyxAgent is an orchestrator. It does not own project-specific development,
-review, tracking, or closure policy. Those policies live in prompts and project
-configuration.
-
-## Goals
-
-- Install a `.nyxagent/` folder into a project with sensible templates.
-- 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.
-- Capture complete run artifacts for audit and debugging.
-- Support Codex and Claude-style harnesses through configurable commands.
-- Support structured phase results through a common XML result contract.
-
-## Non-Goals For v0
-
-- No native classification of work items as plans, PRDs, or tasks.
-- No native Git commit or issue close logic in the engine.
-- No resume command.
-- No fully general DAG/workflow engine.
-- No local `loop.ts` copied into `.nyxagent/`.
-- No automatic mutation of work item files by the engine.
-
-## CLI
-
-Package and binary naming:
-
-- npm package: `nyx-agent` or `@nyxa/nyx-agent`
-- CLI binary: `nyxagent`
-- project directory: `.nyxagent`
-
-Initial commands:
-
-```bash
-nyxagent init
-nyxagent init --missing
-nyxagent run
-nyxagent update
-```
-
-`nyxagent init` is interactive by default and scriptable through flags.
-
-`nyxagent update [version]` self-updates the global install. It resolves the
-target from the npm registry (`latest` by default, or an explicit version /
-dist-tag), guards against accidental downgrades when following a moving tag, and
-reinstalls globally with the detected package manager (npm/pnpm/yarn/bun,
-overridable with `--package-manager`). Use `--check` to report without
-installing and `-y`/`--yes` to skip the confirmation prompt.
-
-If `.nyxagent/` already exists:
-
-- default behavior: refuse and explain
-- `--missing`: add only missing template files
-- no `--force` in v0
-
-## Installed Project Layout
-
-```text
-.nyxagent/
-  config.toml
-  state.json
-  prompts/
-    selection.md
-    execution.md
-    review.md
-    revision.md
-    closure.md
-    pull-request.md
-    repair-result.md
-  schemas/
-    selection.schema.json
-    review.schema.json
-    closure.schema.json
-    pull-request.schema.json
-  runs/
-  worktrees/        # created when [git].mode = "worktree"
-```
-
-Configuration, prompts, schemas, and run artifacts are kept under
-`.nyxagent/`.
-
-Work items may live outside `.nyxagent/` when configured through
-`[work_items]`.
-
-## Configuration
-
-Primary config format: TOML.
-
-Secrets are not stored in `config.toml`. v0 does not require `.env`.
-
-Example:
-
-```toml
-[workflow]
-entry_phase = "selection"
-max_iterations = 5
-
-[model]
-name = "gpt-5.5"
-reasoning_level = "medium"
-
-[harness]
-preset = "codex"
-command = "codex"
-args = [
-  "exec",
-  "--model", "{{model.name}}",
-  "-c", "model_reasoning_effort=\"{{model.reasoning_level}}\"",
-  "-"
-]
-prompt_input = "stdin"
-
-[repair]
-max_attempts = 1
-prompt = "prompts/repair-result.md"
-
-[work_items]
-source = "local"
-path = "issues"
-max_candidates = 50
-excerpt_chars = 800
-
-[[phases]]
-id = "selection"
-prompt = "prompts/selection.md"
-output_schema = "schemas/selection.schema.json"
-required_output = true
-max_visits_per_iteration = 1
-
-[phases.transitions]
-selected = "execution"
-no_work = "stop_run"
-
-[[phases]]
-id = "execution"
-prompt = "prompts/execution.md"
-next = "review"
-max_visits_per_iteration = 3
-
-[[phases]]
-id = "review"
-prompt = "prompts/review.md"
-output_schema = "schemas/review.schema.json"
-required_output = true
-max_visits_per_iteration = 3
-
-[phases.harness]
-args = [
-  "exec",
-  "--model", "{{model.name}}",
-  "-c", "model_reasoning_effort=\"{{model.reasoning_level}}\"",
-  "--sandbox", "read-only",
-  "-"
-]
-
-[phases.transitions]
-approved = "closure"
-changes_requested = "execution"
-
-[[phases]]
-id = "closure"
-prompt = "prompts/closure.md"
-output_schema = "schemas/closure.schema.json"
-required_output = true
-max_visits_per_iteration = 1
-
-[phases.harness]
-args = [
-  "exec",
-  "--model", "{{model.name}}",
-  "-c", "model_reasoning_effort=\"{{model.reasoning_level}}\"",
-  "-c", "sandbox_workspace_write.network_access=true",
-  "-"
-]
-
-[phases.transitions]
-closed = "next_iteration"
-failed = "stop_run"
-```
-
-For GitHub sources, init also adds `workflow.final_phase = "pull_request"`, a
-`[git]` block, and a `pull_request` phase (see "Git Lifecycle and the PRD Pull
-Request").
-
-### Config Semantics
-
-- `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.
-- Harness args are declarative and may interpolate config/runtime variables.
-- Per-phase `model` and `harness` blocks override global values when explicitly
-  declared.
-- The initial selection phase is declared in `[[phases]]`, but the runtime treats
-  `workflow.entry_phase` as the selection step and expects the selection result
-  contract.
-- `work_items` supports only `local` and `github` in v0.
-- `work_items.max_candidates` defaults to `50` and caps the inventory sent to
-  the initial selection prompt.
-- `work_items.excerpt_chars` defaults to `800` and bounds candidate excerpts.
-- `workflow.final_phase` (optional) names the **entry phase of a finalization
-  flow** the engine runs after the iteration loop completes normally. It is
-  symmetric to `entry_phase`: the engine starts at `final_phase` and follows each
-  phase's `next`/`transitions` until it reaches a leaf phase (no `next`/no
-  `transitions`, which ends finalization successfully) or `stop_run` (which aborts
-  the run, keeping the worktree for debugging). This lets the finalization be more
-  than one step — e.g. `review` → (`changes_requested`) `revision` → back to
-  `review` → (`approved`) terminal `pull_request`/`closure`. Review/revision loops
-  are bounded by each phase's `max_visits_per_iteration`. A single leaf phase (the
-  default `pull_request`) simply runs once, unchanged. The flow receives run-level
-  state (the completed work items, the run branch); `runState.final_result` holds
-  the last phase's structured result. `next_iteration`/`stop_iteration` are
-  iteration-only targets and are rejected inside the finalization flow. If unset,
-  nothing runs after the loop.
-- `[git]` (optional) drives the engine's generic git lifecycle. `mode` is `off`
-  (default, unchanged behavior), `branch` (a new branch checked out in place), or
-  `worktree` (an isolated worktree per run). `base` defaults to the current
-  branch. `branch_template` interpolates `{{run_id}}`. `worktree_dir` is the
-  gitignored parent of run worktrees. `cleanup` is `always`, `on_success`
-  (default, kept on failure for debugging), or `never`. The branch is always
-  kept; only the worktree directory is removed.
-- 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.
-- The selection phase may return optional `work_item_annotations` for display.
-  Supported kinds are `task`, `plan`, `prd`, and `work`. Unknown or missing
-  kinds are shown as `work`; annotations never affect work item identity or
-  ledger completion.
-- 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.
-- Local keys use `local:<relative-path-under-work-items-path>`.
-- 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
-  and may include optional `selection_groups` for user review. Groups may cover
-  the full available inventory, not only the recommended queue.
-
-### Phase Capabilities (network and permissions)
-
-The engine stays agnostic: it only runs `command + args` per phase. The
-capability of each phase — read-only, write, or write-with-network — is encoded
-in the harness args that `nyxagent init` generates per preset:
-
-| Capability | Phases | Codex args | Claude args |
-| --- | --- | --- | --- |
-| read-only | selection, review, global_review, finalize | `--sandbox read-only` | `-p --permission-mode plan` |
-| write | execution, revision, global_revision | workspace-write (no extra flag) | `-p --dangerously-skip-permissions` |
-| write + network | closure, pull_request | `-c sandbox_workspace_write.network_access=true` | `-p --dangerously-skip-permissions` |
-
-Why the network capability matters: codex's default `workspace-write` sandbox
-keeps outbound network **off**. A `git commit` is local and succeeds, but
-`gh issue close` is a GitHub API call and fails silently. That is why issues
-were committed but never closed. The `write_network` capability re-enables the
-network only for the phases that need it (closure, pull request). Claude has no
-network sandbox; its blocker was the missing `-p` (headless) and permission
-flags, which `write`/`write_network` now provide.
-
-Users can adjust any phase's posture by editing its `[phases.harness] args`.
-
-### Git Lifecycle and the PRD Pull Request
-
-When `[git].mode` is `worktree` (the default for GitHub init), the engine, once
-per run:
-
-1. creates one branch for the whole run (the PRD) from `base`, in an isolated
-   worktree under `worktree_dir`;
-2. runs every iteration (execution → review → revision → closure) with the
-   harness `cwd` set to that worktree, while `.nyxagent` artifacts stay under the
-   project root;
-3. after the loop, runs the `workflow.final_phase` finalization flow in the
-   worktree (a single `pull_request` phase by default, or a multi-step flow such
-   as the generated global review: `global_review` → (`changes_requested`)
-   `global_revision` → back to `global_review` → (`approved`) `pull_request`) to
-   push the branch and open a single pull request;
-4. removes the worktree per `cleanup`, keeping the branch.
-
-Per-work-item closure still closes each GitHub issue (`gh issue close`). The
-pull request is the PRD-level deliverable; it is opened once, at the end, and is
-GitHub-specific. The engine performs only generic git plumbing (branch, worktree,
-cwd); all GitHub semantics live in the `closure.md` and `pull-request.md`
-prompts, so the engine stays harness- and tracker-agnostic.
-
-## Workflow Model
-
-The workflow is phase based.
-
-Each phase has either:
-
-- `next`: a static next target
-- `transitions`: a map from result `outcome` to next target
-
-Reserved next targets:
-
-- `stop_run`
-- `stop_iteration`
-- `next_iteration`
-
-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 run:
-
-```text
-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
-```
-
-## Structured Result Contract
-
-Agents do not write result JSON files directly.
-
-When a phase requires structured output, the harness must return a JSON object
-inside the last `<nyxagent_result>` XML block in stdout:
-
-```xml
-<nyxagent_result>
-{
-  "outcome": "approved",
-  "approved": true,
-  "summary": "Implementation matches the task and tests pass."
-}
-</nyxagent_result>
-```
-
-Engine behavior:
-
-1. Capture stdout and stderr.
-2. Extract the last `<nyxagent_result>...</nyxagent_result>` block.
-3. Parse the block as JSON.
-4. Validate it against `output_schema` when configured.
-5. Write the validated object to `result.json`.
-6. Merge relevant result data into iteration state.
-
-If a phase declares `transitions`, its structured result must contain
-`outcome`.
-
-If multiple result blocks exist, the last block wins.
-
-## Repair
-
-Repair is only for malformed structured results.
-
-If the harness exits with code `0` but the result block is missing, invalid
-JSON, or schema-invalid, NyxAgent launches a repair phase.
-
-The repair prompt receives:
-
-- rendered original prompt
-- stdout and stderr from the failed attempt
-- expected schema
-- validation or parsing error
-
-The repair agent must return only a valid `<nyxagent_result>` block. It must not
-redo the development or mutate the project.
-
-If the harness exits non-zero, this is a phase failure, not a result repair.
-Phase retry behavior can be added later.
-
-## Runtime Prompt
-
-NyxAgent renders a final prompt for each phase by prepending a runtime contract
-to the user prompt.
-
-The runtime contract includes:
-
-- project root
-- run directory
-- iteration directory
-- phase directory
-- current state file
-- phase id
-- configured transitions
-- required structured output contract
-- work item context, when selected
-- work item config from `[work_items]`
-- `available_work_items`
-- `recommended_work_item_queue`
-- `selected_work_item_queue`
-- `work_item_annotations`
-- `seen_work_item_keys`
-- `completed_work_item_keys`
-- `last_completed_work_item`
-
-The user prompt remains focused on domain behavior.
-
-Prompts may use simple interpolation:
-
-```text
-{{project_root}}
-{{run_dir}}
-{{iteration_dir}}
-{{phase_dir}}
-{{state_file}}
-{{recommended_work_item_queue}}
-{{selected_work_item_queue}}
-{{work_item_annotations}}
-{{work_item.key}}
-{{work_item.title}}
-{{model.name}}
-{{model.reasoning_level}}
-```
-
-The template language is intentionally small: dotted path lookup only.
-
-## Artifacts
-
-Each run creates a timestamped directory:
-
-```text
-.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/
-        execution/
-          attempt-001/
-            prompt.md
-            stdout.log
-            stderr.log
-            meta.json
-          result.json
-        review/
-          attempt-001/
-            prompt.md
-            stdout.log
-            stderr.log
-            meta.json
-          repair-001/
-            prompt.md
-            stdout.log
-            stderr.log
-            meta.json
-          result.json
-```
-
-`run.json` records immutable run metadata:
-
-- run id
-- project root
-- started at
-- config path
-- harness preset and command
-- initial Git snapshot when available
-
-`run/state.json` records global current state:
-
-- 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
-- work item annotations returned by the selection agent
-- skipped recommended work item keys
-- selection groups returned for user review
-- seen work item keys
-- completed work item keys
-- last completed work item
-
-`.nyxagent/state.json` records persistent work item completion state:
-
-- completed work item keys
-- last completed work item
-- minimal completion history
-
-`iterations/NNN/state.json` records per-work-item state:
-
-- iteration number
-- work item
-- selected work item queue for the run
-- seen work item keys
-- completed work item keys
-- last completed work item
-- phase results
-- phase visit counts
-- current phase status
-
-`meta.json` for each attempt records:
-
-- rendered command with secrets redacted
-- start and end timestamps
-- duration
-- exit code
-- parse/schema errors when present
-- Git status before and after phase when available
-
-## Git Behavior
-
-NyxAgent does not require a clean worktree in v0.
-
-At run start, if the project is a Git repository, the engine records:
-
-- branch
-- HEAD commit
-- `git status --short`
-
-The engine does not commit. The default workflow reserves commits for the
-`closure` prompt after review approval.
-
-When `[git].mode` is `branch` or `worktree`, the engine additionally manages a
-run-scoped branch (and, for `worktree`, an isolated working directory) as
-described under "Git Lifecycle and the PRD Pull Request". This is opt-in and off
-by default; it performs only generic git plumbing, never GitHub actions.
-
-Default phase policy:
-
-- `selection`: read-only behavior by prompt/harness
-- `execution`: may modify code and run tests, must not commit or close work
-  items
-- `review`: read-only behavior by prompt/harness
-- `closure`: may commit and close or mark done according to project prompt;
-  runs with the network capability so `gh issue close` works
-- `pull_request` (final phase, GitHub PRD only): pushes the run branch and opens
-  one pull request; runs with the network capability
-
-## Default Prompt Policy
-
-Default prompts should be concise but operational.
-
-Selection:
-
-- 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 the most
-  useful grouping the agent can infer
-- optionally include `work_item_annotations` with display kinds `task`, `plan`,
-  `prd`, or `work`
-- return `selected` or `no_work`
-
-Execution:
-
-- work only on the selected item
-- use a red-green-refactor style when practical
-- run targeted validation
-- do not commit
-- do not close the work item
-
-Review:
-
-- stay read-only
-- check alignment with selected work item
-- check tests and validation evidence
-- check architecture/design fit
-- check obvious security or data safety concerns
-- return `approved` or `changes_requested`
-
-Closure:
-
-- run only after approval
-- inspect final diff/status
-- commit when appropriate
-- close or mark done according to work item source and project conventions
-- for GitHub, close the issue explicitly with `gh issue close <number> --repo
-  <owner/repo>` (needs the network capability)
-- return a structured `closed` / `failed` outcome so a failed close stops the run
-  instead of silently marking the item done
-
-Pull request (final phase, GitHub PRD only):
-
-- run once after the iteration loop, on the run branch in the worktree
-- push the branch and open one pull request referencing the addressed issues
-- return `pr_opened` with `pr_url`, or `failed` with what remains
-
-Global review (finalization, optional):
-
-- stay read-only; review the whole run/PRD, not a single item
-- focus on cross-cutting concerns a per-task review cannot see (integration,
-  regressions between items, overall design, gaps vs intent)
-- inspect the combined diff (`git diff {{git.base}}...HEAD` when a branch exists)
-- return `approved` or `changes_requested` (with `required_changes`)
-
-Global revision (finalization, optional):
-
-- apply `phase_results.global_review.required_changes` across affected items
-- **commit** the corrections (no closure phase follows it), so they land in the
-  run branch / pull request
-
-Finalize (finalization terminal leaf, when there is no pull request):
-
-- read-only; make no changes — all work is already implemented, committed, closed
-- summarize the completed work items and confirm the run is complete
-
-## Init Modes
-
-`nyxagent init` asks for:
-
-- harness preset: `codex`, `claude`, or custom
-- model name
-- reasoning level
-- review strategy (see below)
-- max iterations
-- work item source template: `local` or `github`
-
-The **review strategy** is a single choice (`--review-mode each|all|both|none`,
-default `each`; the legacy `--review`/`--no-review` flags map to `each`/`none`):
-
-- `each` — review + correction after **each** task, inside the iteration loop
-  (`execution → review → revision → closure`). This is the default and the
-  previous behavior.
-- `all` — a single **global review + correction** of the whole run after the
-  loop, as a finalization sub-graph: `global_review` → (`changes_requested`)
-  `global_revision` → back to `global_review` → (`approved`) terminal. The
-  terminal is the `pull_request` phase for GitHub (with PR), otherwise a
-  read-only `finalize` leaf (local, or `--no-pull-request`). The loop is bounded
-  by `max_visits_per_iteration = 3`; exhausting it fails the run.
-- `both` — per-task review **and** the final global review.
-- `none` — no review at all (`execution → closure`).
-
-For `local`, init asks for a work item path.
-For `github`, init asks for a repository in `owner/repo` format and, by default,
-wires the pull request finalization flow (`--no-pull-request` to skip). This adds
-a `[git] mode = "worktree"` block, a `pull_request` phase, and
-`workflow.final_phase = "pull_request"`. When a global review is enabled it
-becomes the finalization entry (`workflow.final_phase = "global_review"`) and the
-pull request becomes its approved terminal. Pull requests are GitHub-specific, so
-`local` sources never get a `pull_request` phase; their global review approves
-into the `finalize` leaf instead.
-
-Default path selection:
-
-- use `issues/` if it exists
-- otherwise suggest `.nyxagent/tasks/`
-
-If the chosen local work item path does not exist, init creates the directory but
-does not create sample work items.
-
-### Upgrading an existing config
-
-`nyxagent init --missing` only adds missing template files; it does not rewrite an
-existing `config.toml`. To fix issue closing on a config generated before the
-network capability existed, add a network override to the `closure` phase:
-
-```toml
-[[phases]]
-id = "closure"
-# ... existing keys ...
-
-[phases.harness]
-# codex:
-args = [
-  "exec",
-  "--model", "{{model.name}}",
-  "-c", "model_reasoning_effort=\"{{model.reasoning_level}}\"",
-  "-c", "sandbox_workspace_write.network_access=true",
-  "-"
-]
-# claude:
-# args = ["-p", "--model", "{{model.name}}", "--output-format", "text", "--dangerously-skip-permissions"]
-```
-
-To adopt the pull request flow, add a `[git]` block, a `pull_request` phase, and
-`workflow.final_phase = "pull_request"` (see the sections above), or regenerate
-the config with `nyxagent init`.
-
-## Implementation Stack
-
-Recommended TypeScript stack:
-
-- Node ESM
-- `commander` for CLI commands
-- `@inquirer/prompts` for interactive init
-- `smol-toml` for TOML parsing/writing
-- `zod` for internal config validation
-- `ajv` for JSON Schema validation
-- `execa` for process execution
-- `tsx` for development
-- `tsc` or `tsup` for build
-
-Recommended source layout:
-
-```text
-src/
-  cli.ts
-  commands/
-    init.ts
-    run.ts
-  config/
-    loadConfig.ts
-    schema.ts
-  runtime/
-    renderPrompt.ts
-    runWorkflow.ts
-    runPhase.ts
-    parseResult.ts
-  templates/
-    default/
-```
-
-## Future Work
-
-- `nyxagent resume`
-- `nyxagent import-tasks`
-- additional tracker adapters
-- explicit Git commit adapter
-- stricter artifact redaction
-- richer phase retry policy
-- local runner eject command
-- JSON event stream output
-- human approval gates between phases