@nyxa/nyx-agent 0.1.0

package/docs/nyxagent-v0-spec.md

@@ -0,0 +1,488 @@
+# 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.
+- Run a configurable phase workflow for up to `max_iterations` 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 built-in GitHub, Jira, Linear, or local task tracker adapter.
+- 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 init` is interactive by default and scriptable through flags.
+
+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
+  prompts/
+    selection.md
+    execution.md
+    review.md
+    closure.md
+    repair-result.md
+  schemas/
+    selection.schema.json
+    review.schema.json
+  runs/
+```
+
+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-codex"
+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-markdown"
+path = "issues"
+
+[[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.model]
+reasoning_level = "high"
+
+[[phases]]
+id = "review"
+prompt = "prompts/review.md"
+output_schema = "schemas/review.schema.json"
+required_output = true
+max_visits_per_iteration = 3
+
+[phases.model]
+reasoning_level = "high"
+
+[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"
+next = "next_iteration"
+max_visits_per_iteration = 1
+```
+
+### Config Semantics
+
+- `workflow.max_iterations` is the maximum number of distinct 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.
+- `work_items` is informative in v0. It is injected into runtime context and
+  used by prompts, not scanned by the engine.
+
+## 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 loop:
+
+```text
+selection -> 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]`
+
+The user prompt remains focused on domain behavior.
+
+Prompts may use simple interpolation:
+
+```text
+{{project_root}}
+{{run_dir}}
+{{iteration_dir}}
+{{phase_dir}}
+{{state_file}}
+{{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
+  iterations/
+    001/
+      state.json
+      phases/
+        selection/
+          attempt-001/
+            prompt.md
+            stdout.log
+            stderr.log
+            meta.json
+          result.json
+        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
+- seen work item keys
+
+`iterations/NNN/state.json` records per-work-item state:
+
+- iteration number
+- 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.
+
+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
+
+## Default Prompt Policy
+
+Default prompts should be concise but operational.
+
+Selection:
+
+- inspect configured work item source
+- choose one work item
+- avoid keys already present in `seen_work_item_keys`
+- 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
+
+## Init Modes
+
+`nyxagent init` asks for:
+
+- harness preset: `codex`, `claude`, or custom
+- model name
+- reasoning level
+- max iterations
+- work item source template: `local-markdown`, `github`, or `custom`
+
+For `local-markdown`, init asks for a task path.
+
+Default path selection:
+
+- use `issues/` if it exists
+- otherwise suggest `.nyxagent/tasks/`
+
+If the chosen local task path does not exist, init may create it and add a
+sample task.
+
+## 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`
+- tracker adapters for GitHub, Jira, Linear, or local frontmatter tasks
+- explicit Git commit adapter
+- stricter artifact redaction
+- richer phase retry policy
+- local runner eject command
+- JSON event stream output
+- human approval gates between phases

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nyxa/nyx-agent",
+  "version": "0.1.0",
+  "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
+  "type": "module",
+  "bin": {
+    "nyxagent": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "tsx --test tests/**/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "ajv": "^8.17.0",
+    "commander": "^14.0.0",
+    "execa": "^9.6.0",
+    "picocolors": "^1.1.0",
+    "smol-toml": "^1.3.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/default/prompts/closure.md

@@ -0,0 +1,11 @@
+Close the selected work item after review approval.
+
+Before committing or closing anything, inspect the current diff and status.
+Confirm the review phase approved the work. Run a lightweight final validation
+when it is cheap and relevant.
+
+Commit only the selected work item changes, using the project conventions for
+commit messages. Then close or mark the work item done according to its source
+and the project conventions.
+
+If closure cannot be completed safely, stop and explain what remains.

package/templates/default/prompts/execution.md

@@ -0,0 +1,11 @@
+Implement the selected work item.
+
+Work only on the selected item from the runtime state. Keep changes focused.
+Use a red-green-refactor loop when practical:
+
+1. Reproduce or cover the expected behavior with a focused test.
+2. Implement the smallest coherent change.
+3. Run targeted validation and tidy the result.
+
+Do not commit. Do not close or mark the work item done. Leave clear validation
+evidence in your final response.

package/templates/default/prompts/repair-result.md

@@ -0,0 +1,29 @@
+The previous phase attempt completed, but NyxAgent could not parse or validate
+its structured result.
+
+Validation error:
+
+```text
+{{validation_error}}
+```
+
+Original phase prompt:
+
+```md
+{{original_prompt}}
+```
+
+Original stdout:
+
+```text
+{{original_stdout}}
+```
+
+Original stderr:
+
+```text
+{{original_stderr}}
+```
+
+Reconstruct the intended structured result from the transcript. Return only the
+final `<nyxagent_result>` block. Do not redo the phase work.

package/templates/default/prompts/review.md

@@ -0,0 +1,18 @@
+Review the implementation for the selected work item.
+
+Stay read-only. Do not modify project files.
+
+Focus on:
+
+- alignment with the selected work item
+- correctness and regression risk
+- tests or validation evidence
+- design and architecture fit
+- security or data-safety concerns
+
+Return one of these outcomes:
+
+- `approved`: the work is ready for closure
+- `changes_requested`: include concrete required changes
+
+Keep the review concise and actionable.

package/templates/default/prompts/selection.md

@@ -0,0 +1,19 @@
+Select exactly one work item for this iteration.
+
+Use the work item configuration from the runtime contract. Prefer open,
+well-scoped work that has not already been selected in this run. Avoid any item
+whose key appears in `seen_work_item_keys`.
+
+If no suitable work item exists, return `no_work`.
+
+Return one of these outcomes:
+
+- `selected`: include a stable `work_item`
+- `no_work`: include a short `reason`
+
+The selected work item must have a stable key. Examples:
+
+- `github:owner/repo#42`
+- `local:issues/TASK-0007.md`
+
+Do not modify project files or task files during selection.

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

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["outcome", "approved", "summary"],
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": ["approved", "changes_requested"]
+    },
+    "approved": {
+      "type": "boolean"
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "required_changes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "approved"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "approved": {
+            "const": true
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "changes_requested"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "approved": {
+            "const": false
+          }
+        },
+        "required": ["required_changes"]
+      }
+    }
+  ],
+  "additionalProperties": true
+}