@nyxa/nyx-agent 0.4.1 → 0.6.0

package/README.md

@@ -1,16 +1,65 @@
 # NyxAgent
 
-NyxAgent is a small TypeScript CLI that runs coding-agent phases with fresh
-context for each phase.
+NyxAgent is a small TypeScript CLI that runs a fixed coding-agent pipeline, one
+GitHub issue at a time, each phase with fresh context.
 
-Current commands:
+## Pipeline
+
+For every run NyxAgent:
+
+1. **Selects** open GitHub issues to work on (read-only).
+2. For each selected issue, in an isolated git **worktree**:
+   - **implements** it (the agent — the only customizable prompt),
+   - optionally **reviews** and **revises** it (bounded loop),
+   - **commits** the change (the engine, deterministically).
+3. Optionally runs a **global review** across the whole run.
+4. **Pushes** the run branch and **opens one pull request** (the engine).
+
+The agent only implements, reviews, and revises. Every git/gh side effect —
+commit, push, pull request — is performed by the engine, so closing the loop
+never depends on the model. Issues are closed by GitHub when the PR merges
+(`Closes #n` in the PR body); the human merges the PR.
+
+The workflow shape is fixed (not configurable). Only `.nyxagent/prompts/execution.md`
+is editable.
+
+## Commands
 
 ```bash
-nyxagent init
-nyxagent init --missing
-nyxagent run
-nyxagent update
+nyxagent init                 # create .nyxagent/config.json (interactive)
+nyxagent run                  # run the pipeline
+nyxagent run --harness claude # override the configured harness for one run
+nyxagent update               # self-update to the latest published version
+```
+
+## Configuration
+
+`nyxagent init` writes `.nyxagent/config.json`:
+
+```json
+{
+  "harness": "codex",
+  "model": "gpt-5.5",
+  "reasoning_effort": "medium",
+  "review": "each",
+  "review_max_attempts": 4,
+  "tracker": { "type": "github", "repo": "owner/repo" },
+  "base_branch": "main",
+  "max_iterations": 5
+}
 ```
 
-See [docs/nyxagent-v0-spec.md](docs/nyxagent-v0-spec.md) for the v0 design.
-# nyxagent
+- `harness`: `codex` or `claude` (override per run with `--harness`).
+- `review`: `each` (per task), `all` (global only), `both`, or `none`.
+- `review_max_attempts`: review+revise rounds per stage before the run fails (default 4).
+- `base_branch`: optional; defaults to the current branch at run time.
+
+If a run fails review after exhausting its attempts but has already produced
+commits, NyxAgent pushes the branch and opens a **draft** pull request with the
+unresolved feedback, so the work is never stranded on an orphaned branch.
+
+## Requirements
+
+- A git repository with a GitHub remote.
+- The `gh` CLI authenticated for the configured repository.
+- The selected harness CLI (`codex` or `claude`) on `PATH`.

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/** CLI entry point: declares the `init`, `run`, and `update` commands and dispatches them. */
 import { Command } from "commander";
 import { createRequire } from "node:module";
 import pc from "picocolors";
@@ -10,32 +11,28 @@ const packageJson = require("../package.json");
 const program = new Command();
 program
     .name("nyxagent")
-    .description("Run coding-agent workflows with fresh context per phase.")
+    .description("Run a fixed coding-agent pipeline with fresh context per phase.")
     .version(packageJson.version);
 program
     .command("init")
-    .description("Create a .nyxagent project configuration")
-    .option("--missing", "only add missing template files")
-    .option("--harness <preset>", "harness preset: codex, claude, or custom")
+    .description("Create a .nyxagent/config.json project configuration")
+    .option("--harness <name>", "default harness: codex or claude")
     .option("--model <name>", "model name")
-    .option("--reasoning-level <level>", "default harness-neutral reasoning level")
+    .option("--reasoning-effort <level>", "reasoning effort (default: medium)")
+    .option("--review <mode>", "review strategy: each, all, both, or none")
+    .option("--review-attempts <count>", "max review attempts per stage (default: 4)")
+    .option("--repo <owner/repo>", "GitHub repository")
+    .option("--base-branch <branch>", "base branch (default: current branch)")
     .option("--max-iterations <count>", "maximum work items per run")
-    .option("--work-items-source <source>", "work item source template: local or github")
-    .option("--work-items-path <path>", "local markdown work item directory")
-    .option("--work-items-repository <owner/repo>", "GitHub work item repository")
-    .option("--implementation-skill <name>", "implementation skill to reference in the execution prompt")
-    .option("--review", "include a review phase (alias for --review-mode each)")
-    .option("--no-review", "skip the review phase (alias for --review-mode none)")
-    .option("--review-mode <mode>", "review strategy: each, all, both, or none")
-    .option("--pull-request", "close the PRD with a pull request (GitHub work items)")
-    .option("--no-pull-request", "skip the pull request finalization phase")
+    .option("--force", "overwrite an existing config")
     .action(async (options) => {
     await initCommand(options);
 });
 program
     .command("run")
-    .description("Run the configured NyxAgent workflow")
-    .option("--config <path>", "config path, defaults to .nyxagent/config.toml")
+    .description("Run the NyxAgent pipeline")
+    .option("--config <path>", "config path (default: .nyxagent/config.json)")
+    .option("--harness <name>", "override the configured harness: codex or claude")
     .action(async (options) => {
     await runCommand(options);
 });