@nathapp/nax 0.88.0-canary.2 → 0.89.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +101 -76
- package/dist/nax.js +14578 -12814
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -2,25 +2,26 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://npmjs.com/@nathapp/nax)
|
|
4
4
|
[](https://github.com/nathapp-io/nax/actions)
|
|
5
|
-
[](https://bun.sh)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
8
|
**AI Coding Agent Orchestrator** — loops until done.
|
|
9
9
|
|
|
10
|
-
Give it a spec. It
|
|
10
|
+
Give it a spec. It implements each story, runs the deterministic gates, reviews the work with an LLM, fixes what the review finds, and opens a pull request when the branch is ready.
|
|
11
11
|
|
|
12
12
|
## Why nax
|
|
13
13
|
|
|
14
|
-
nax is an **orchestrator, not an agent** — it doesn't write code itself. It drives whatever coding agent you choose through a disciplined loop until your
|
|
14
|
+
nax is an **orchestrator, not an agent** — it doesn't write code itself. It drives whatever coding agent you choose through a disciplined loop until your gates pass.
|
|
15
15
|
|
|
16
|
-
- **Agent-agnostic** — runs its own in-process native agent by default, or drives Claude Code, Codex, Gemini CLI, OpenCode, or any ACP-compatible agent
|
|
17
|
-
- **
|
|
18
|
-
- **Loop until done** —
|
|
16
|
+
- **Agent-agnostic** — runs its own in-process native agent by default, or drives Claude Code, Codex, Gemini CLI, OpenCode, Pi, or any ACP-compatible agent
|
|
17
|
+
- **Deterministic gates** — lint, typecheck, scoped tests and the full suite decide pass or fail; LLM reviewers do not turn a red gate green
|
|
18
|
+
- **Loop until done** — per-story fix rounds, a whole-branch review with its own fix rounds, and a final gate repair pass, all bounded by config
|
|
19
|
+
- **Story and branch review** — LLM review of each story against its spec and acceptance criteria, then one review of the whole branch before publishing
|
|
20
|
+
- **Advisor** — rules on judgment calls (implementer questions, unresolved findings, pre-flight conflicts) and records every ruling in the run ledger and the PR body, instead of stopping the run
|
|
21
|
+
- **Publishes a PR** — opens a draft PR, waits for CI, and promotes it to ready only when no deterministic reason keeps it draft; nax never merges
|
|
19
22
|
- **Monorepo-ready** — per-package config and per-story working directories
|
|
20
23
|
- **Extensible** — plugin system for routing, review, reporting, and post-run actions
|
|
21
|
-
- **Language-aware** — auto-detects Go, Rust, Python, TypeScript from manifest files; adapts commands
|
|
22
|
-
- **Semantic review** — LLM-based behavioral review against story acceptance criteria; catches stubs, placeholders, and out-of-scope changes
|
|
23
|
-
- **Adversarial review** — LLM-based adversarial code review that probes for input handling, error paths, and abandoned implementations
|
|
24
|
+
- **Language-aware** — auto-detects Go, Rust, Python, TypeScript from manifest files; adapts commands and test structure per language
|
|
24
25
|
- **Context curator** — deterministic post-run analysis that proposes additions/deletions to context.md and rules files, preventing context drift
|
|
25
26
|
- **Guarded agent commands** — agent-authored shell commands run inside an OS sandbox by default, are adjudicated by a per-stage bash approval mode, and can pause for interactive approval that you can remember and later revoke (`nax approvals`)
|
|
26
27
|
|
|
@@ -32,7 +33,7 @@ npm install -g @nathapp/nax
|
|
|
32
33
|
bun install -g @nathapp/nax
|
|
33
34
|
```
|
|
34
35
|
|
|
35
|
-
Requires
|
|
36
|
+
Requires the Bun runtime (nax runs on Bun even when installed through npm; CI pins Bun 1.4.3). Git must be initialized.
|
|
36
37
|
|
|
37
38
|
The default `native` agent needs provider credentials — run `nax auth login <provider>` or, for CI, set the provider's environment variable (a stored credential takes precedence).
|
|
38
39
|
|
|
@@ -52,25 +53,37 @@ nax run -f my-feature
|
|
|
52
53
|
nax run -f my-feature --plan --from spec.md
|
|
53
54
|
```
|
|
54
55
|
|
|
55
|
-
|
|
56
|
+
`nax run` uses workflow mode by default (see [How It Works](#how-it-works)). With a forge configured, it ends with a draft PR, promoted to ready when the deterministic checks pass.
|
|
57
|
+
|
|
58
|
+
See the [documentation index](https://github.com/nathapp-io/nax/blob/main/docs/README.md) for full guides on configuration, workflow mode, monorepo setup, and more.
|
|
56
59
|
|
|
57
60
|
## How It Works
|
|
58
61
|
|
|
62
|
+
nax has two execution modes. **Workflow mode** is the default (`execution.mode: "workflow"`). The **pipeline** mode (`execution.mode: "pipeline"`) is deprecated: it still runs, warns at config load, and will be removed in a future release.
|
|
63
|
+
|
|
64
|
+
### Workflow mode (default)
|
|
65
|
+
|
|
59
66
|
```
|
|
60
|
-
|
|
67
|
+
story: implement → gates → story review → fix rounds → full suite → residual ruling
|
|
68
|
+
feature: repo gates → branch review → branch fix → re-review → adjudicate → final gates → publish
|
|
61
69
|
```
|
|
62
70
|
|
|
63
|
-
1. **
|
|
64
|
-
2. **
|
|
65
|
-
3. **
|
|
66
|
-
4. **
|
|
67
|
-
5. **
|
|
68
|
-
6. **
|
|
69
|
-
7. **
|
|
70
|
-
8. **
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
71
|
+
1. **Pre-flight** *(optional, on by default)* — the advisor checks the PRD for stories that share files and for spec/AC contradictions, before the first story
|
|
72
|
+
2. **Implement** — one implementer session per story writes the tests and code, runs them, and commits
|
|
73
|
+
3. **Gates** — `lint`, `typecheck` and `scoped` tests run after each turn
|
|
74
|
+
4. **Story review** — one LLM review of the story diff against the spec, returning a spec verdict and a quality verdict
|
|
75
|
+
5. **Fix rounds** — open findings go back to the implementer, up to `workflow.maxFixRounds` (default 5); minor findings are deferred to the ledger
|
|
76
|
+
6. **Full suite** — the `full-suite` gate runs once the review passes
|
|
77
|
+
7. **Feature workflow** — after the last story: repo gates, one whole-branch review, up to `workflow.maxBranchFixRounds` (default 2) fix rounds each with a scoped re-review, adjudication, final gates, and up to `workflow.finalGateRepairRounds` (default 1) repair passes
|
|
78
|
+
8. **Publish** — `workflow.publish` (`pr` by default) commits the ledger, pushes, opens or finds a draft PR, waits for CI, and promotes the draft when the deterministic readiness checks pass
|
|
79
|
+
|
|
80
|
+
Stories run one at a time. `--parallel` and story batching are ignored in workflow mode.
|
|
81
|
+
|
|
82
|
+
See [Workflow Mode](https://github.com/nathapp-io/nax/blob/main/docs/guides/workflow-mode.md) for the full loop, end states, publishing modes and config reference, and [ADR-034](https://github.com/nathapp-io/nax/blob/main/docs/adr/ADR-034-workflow-execution-mode.md) for the design.
|
|
83
|
+
|
|
84
|
+
### Pipeline mode (deprecated)
|
|
85
|
+
|
|
86
|
+
Selected with `execution.mode: "pipeline"`. Each story runs through a staged pipeline: acceptance setup, routing, context, execution, verify, review (semantic and adversarial), escalation, and a regression gate after all stories pass. Pipeline mode is frozen; no new features are added to it.
|
|
74
87
|
|
|
75
88
|
---
|
|
76
89
|
|
|
@@ -78,39 +91,42 @@ See [docs/](docs/) for full guides on configuration, test strategies, monorepo s
|
|
|
78
91
|
|
|
79
92
|
| Command | Description |
|
|
80
93
|
|:--------|:-----------|
|
|
81
|
-
| [`nax init`](docs/guides/cli-reference.md#nax-init) | Initialize nax in your project |
|
|
94
|
+
| [`nax init`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-init) | Initialize nax in your project |
|
|
82
95
|
| `nax setup` | Analyze the repo and generate `.nax/config.json` via LLM |
|
|
83
|
-
| [`nax features create`](docs/guides/cli-reference.md#nax-features-create-name) | Scaffold a new feature directory |
|
|
84
|
-
| [`nax features list`](docs/guides/cli-reference.md#nax-features-list) | List all features and story status |
|
|
96
|
+
| [`nax features create`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-features-create-name) | Scaffold a new feature directory |
|
|
97
|
+
| [`nax features list`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-features-list) | List all features and story status |
|
|
85
98
|
| `nax features resolve` | Resolve a feature name and its spec source |
|
|
86
|
-
| [`nax plan`](docs/guides/cli-reference.md#nax-plan--f-name---from-spec) | Generate `prd.json` from a spec file (`--decompose <storyId>` splits an existing story) |
|
|
99
|
+
| [`nax plan`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-plan--f-name---from-spec) | Generate `prd.json` from a spec file (`--decompose <storyId>` splits an existing story) |
|
|
87
100
|
| `nax spec lint` | Check a spec's machine-extracted sections before planning |
|
|
88
|
-
| [`nax run`](docs/guides/cli-reference.md#nax-run--f-name) | Execute the
|
|
101
|
+
| [`nax run`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-run--f-name) | Execute the feature in workflow mode (`--compare` for a multi-agent bake-off, `--schedule` to defer, `--plan` to plan first) |
|
|
89
102
|
| `nax resume` | Resume an interrupted run from its checkpoint |
|
|
90
|
-
| [`nax precheck`](docs/guides/cli-reference.md#nax-precheck--f-name) | Validate project readiness |
|
|
91
|
-
| [`nax status`](docs/guides/cli-reference.md#nax-status--f-name) | Show live run progress |
|
|
92
|
-
| [`nax logs`](docs/guides/cli-reference.md#nax-logs) | Stream or query run logs |
|
|
93
|
-
| [`nax runs`](docs/guides/cli-reference.md#nax-runs) | List recorded run metadata (`nax runs show <run-id>`) |
|
|
103
|
+
| [`nax precheck`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-precheck--f-name) | Validate project readiness |
|
|
104
|
+
| [`nax status`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-status--f-name) | Show live run progress |
|
|
105
|
+
| [`nax logs`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-logs) | Stream or query run logs |
|
|
106
|
+
| [`nax runs`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-runs) | List recorded run metadata (`nax runs show <run-id>`) |
|
|
94
107
|
| `nax replay` | Reconstruct a post-mortem timeline for a previous run |
|
|
95
|
-
| `nax accept` | Override failed acceptance criteria |
|
|
96
|
-
| [`nax unlock`](docs/guides/cli-reference.md#nax-unlock) | Release a stale lock from a crashed nax process |
|
|
97
|
-
| [`nax
|
|
98
|
-
| [`nax
|
|
108
|
+
| `nax accept` | Override failed acceptance criteria (pipeline mode; workflow mode does not run acceptance tests) |
|
|
109
|
+
| [`nax unlock`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-unlock) | Release a stale lock from a crashed nax process |
|
|
110
|
+
| [`nax doctor`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md) | Diagnose the nax installation and environment |
|
|
111
|
+
| [`nax generate`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-generate) | Generate agent context files (`CLAUDE.md`, `AGENTS.md`, …) from `.nax/context.md` |
|
|
112
|
+
| [`nax prompts`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-prompts--f-name) | Assemble or initialize prompts |
|
|
99
113
|
| `nax context` | Inspect context-engine artifacts and feature fragments |
|
|
100
114
|
| `nax rules` | Lint, export, or migrate the canonical rules store (`.nax/rules/`) |
|
|
101
115
|
| `nax detect` | Detect test-file patterns and optionally persist them |
|
|
102
|
-
| [`nax agents`](docs/guides/cli-reference.md#nax-agents) | List available coding agents |
|
|
116
|
+
| [`nax agents`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-agents) | List available coding agents |
|
|
103
117
|
| `nax auth` | Manage provider credentials for the native agent (`login`, `import`, `list`, `rm`) |
|
|
104
|
-
|
|
|
105
|
-
| [`nax
|
|
118
|
+
| `nax sandbox probe` | Check whether the OS sandbox for agent commands works on this machine |
|
|
119
|
+
| [`nax approvals`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-approvals-list) | List or revoke remembered command approvals (`list`, `rm`) |
|
|
120
|
+
| `nax advisor` | Inspect, label, and replay advisor decisions (`list`, `label`, `replay`, `import-finish`) |
|
|
121
|
+
| [`nax trust`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-trust) | Trust or untrust project folders (`list`, `add`, `rm`, `check`) |
|
|
106
122
|
| `nax mcp lock` | Pin configured MCP servers' tool surface to `.nax/mcp-lock.json` |
|
|
107
|
-
| [`nax config`](docs/guides/cli-reference.md#nax-config) | Display the effective merged config (`--explain`, `--diff`); `nax config profile` manages config profiles |
|
|
108
|
-
| [`nax curator`](docs/guides/cli-reference.md#nax-curator-status) | Inspect, commit, or garbage-collect curator proposals |
|
|
123
|
+
| [`nax config`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-config) | Display the effective merged config (`--explain`, `--diff`); `nax config profile` manages config profiles |
|
|
124
|
+
| [`nax curator`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-curator-status) | Inspect, commit, or garbage-collect curator proposals |
|
|
109
125
|
| `nax routing calibrate` | Propose complexity→tier mapping adjustments from run history |
|
|
110
126
|
| `nax plugins list` | List installed plugins |
|
|
111
|
-
| `nax migrate` |
|
|
127
|
+
| `nax migrate` | Recover a project-name collision: `--reclaim <name>` or `--merge <name>` |
|
|
112
128
|
|
|
113
|
-
For full flag details, see the [CLI Reference](docs/guides/cli-reference.md).
|
|
129
|
+
For full flag details, see the [CLI Reference](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md).
|
|
114
130
|
|
|
115
131
|
---
|
|
116
132
|
|
|
@@ -120,17 +136,12 @@ For full flag details, see the [CLI Reference](docs/guides/cli-reference.md).
|
|
|
120
136
|
|
|
121
137
|
```json
|
|
122
138
|
{
|
|
123
|
-
"agent": {
|
|
124
|
-
"protocol": "hybrid", // "acp" | "native" | "hybrid" — which transports are permitted
|
|
125
|
-
"default": "native", // In-process nax-ai agent; or an ACP agent such as "claude"
|
|
126
|
-
"native": {
|
|
127
|
-
"instructionFileName": "AGENTS.md" // Repository instruction basename; e.g. "TEAM.md"
|
|
128
|
-
}
|
|
129
|
-
},
|
|
130
139
|
"execution": {
|
|
140
|
+
"mode": "workflow", // "workflow" (default) | "pipeline" (deprecated)
|
|
131
141
|
"maxIterations": 20, // Note: `nax run -m <n>` overrides this only when the flag is passed
|
|
142
|
+
"costLimit": 30, // USD; past it, the run stops its loops and publishes a draft
|
|
132
143
|
"permissionProfile": "unrestricted", // "unrestricted" | "safe" | "scoped"
|
|
133
|
-
"storyIsolation": "shared", // "shared" | "worktree"
|
|
144
|
+
"storyIsolation": "shared", // "shared" | "worktree" (workflow mode forces "shared")
|
|
134
145
|
"bashApproval": "raw", // "raw" | "gated" | "escalate" — how agent Bash commands are adjudicated
|
|
135
146
|
"sandbox": {
|
|
136
147
|
"enabled": true, // OS sandbox around agent-authored Bash / Exec commands (on by default)
|
|
@@ -142,8 +153,19 @@ For full flag details, see the [CLI Reference](docs/guides/cli-reference.md).
|
|
|
142
153
|
"git": { "verbs": ["log", "diff"] } // Only these subcommands are rewritten
|
|
143
154
|
}
|
|
144
155
|
},
|
|
145
|
-
"
|
|
146
|
-
"
|
|
156
|
+
"workflow": {
|
|
157
|
+
"maxFixRounds": 5, // Per-story fix rounds
|
|
158
|
+
"maxBranchFixRounds": 2, // Feature-level branch fix rounds
|
|
159
|
+
"finalGateRepairRounds": 1, // Repair passes when a branch fix turns a gate red
|
|
160
|
+
"preflight": true, // Advisor pre-flight before the first story
|
|
161
|
+
"publish": "pr" // "pr" | "push" | "none"
|
|
162
|
+
},
|
|
163
|
+
"agent": {
|
|
164
|
+
"protocol": "hybrid", // "acp" | "native" | "hybrid" — which transports are permitted
|
|
165
|
+
"default": "native", // In-process nax-ai agent; or an ACP agent such as "claude"
|
|
166
|
+
"native": {
|
|
167
|
+
"instructionFileName": "AGENTS.md" // Repository instruction basename; e.g. "TEAM.md"
|
|
168
|
+
}
|
|
147
169
|
},
|
|
148
170
|
"routing": {
|
|
149
171
|
"strategy": "keyword" // "keyword" | "llm"
|
|
@@ -168,13 +190,15 @@ For full flag details, see the [CLI Reference](docs/guides/cli-reference.md).
|
|
|
168
190
|
}
|
|
169
191
|
```
|
|
170
192
|
|
|
193
|
+
The `execution.mode` default is `"workflow"`. Setting `"pipeline"` loads with a deprecation warning. In workflow mode the `workflow` block governs the loops; the pipeline-only keys (`acceptance`, `tdd`, `execution.regressionGate`) are not read by the workflow story loop. See [Workflow Mode](https://github.com/nathapp-io/nax/blob/main/docs/guides/workflow-mode.md) for the complete `workflow` reference.
|
|
194
|
+
|
|
171
195
|
`mcp` attaches external Model Context Protocol (MCP) servers as tool providers — nax is a client only, never an MCP server. The server id is the tool-name namespace: the `codebase-memory` server advertises its tools as `codebase-memory__search_graph`, `codebase-memory__trace_path`, and so on. Before any of those tools are grantable, run `nax mcp lock` at the project root: it connects every enabled server once, pins the advertised tool surface (name + input-schema hash) to `.nax/mcp-lock.json`, and that lockfile is committed like `bun.lock`. `stages` is the attachment control — a server's tools attach only to the listed pipeline stages, and an empty list attaches nowhere. MCP tool reach follows the permission profile: `unrestricted` advertises every attached server's tools, `scoped` only what the stage's `Mcp(...)` rules admit, and `safe` none at all. `allowedTools` narrows which locked tools are grantable; omitted means every locked tool is.
|
|
172
196
|
|
|
173
197
|
`execution.commandInterceptor` rewrites the `Git` tool's argv through `rtk` so `log` and `diff` output reaches the model compressed. It is confined to the Git site: user-authored `quality.commands` and `acceptance.command` are never wrapped. It fails open — if the `rtk` binary is missing the call runs as plain git.
|
|
174
198
|
|
|
175
|
-
**Both features are native-agent only.** An ACP agent (`claude`, `codex`, `opencode`, `gemini`) brings its own tools, so nax's `Git` tool is never invoked and no MCP tool is advertised. A project on `"protocol": "acp"` can hold a complete, valid config for both and get zero effect, with no error. The built-in defaults (`agent.protocol: "hybrid"`, `agent.default: "native"`) let both take effect once configured (the interceptor itself is off by default); a config that switches to an ACP agent does not.
|
|
199
|
+
**Both features are native-agent only.** An ACP agent (`claude`, `codex`, `opencode`, `gemini`, `pi`) brings its own tools, so nax's `Git` tool is never invoked and no MCP tool is advertised. A project on `"protocol": "acp"` can hold a complete, valid config for both and get zero effect, with no error. The built-in defaults (`agent.protocol: "hybrid"`, `agent.default: "native"`) let both take effect once configured (the interceptor itself is off by default); a config that switches to an ACP agent does not.
|
|
176
200
|
|
|
177
|
-
See [MCP & Command Interception](docs/guides/mcp-and-interception.md) for setup, verification and troubleshooting, and the [Configuration Guide](docs/guides/configuration.md) for the full schema.
|
|
201
|
+
See [MCP & Command Interception](https://github.com/nathapp-io/nax/blob/main/docs/guides/mcp-and-interception.md) for setup, verification and troubleshooting, and the [Configuration Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/configuration.md) for the full schema.
|
|
178
202
|
|
|
179
203
|
`execution.bashApproval` decides how an agent's Bash command is adjudicated (ADR-030). The default `raw` is a pass-through — no per-segment grant matching or root containment, only a best-effort screen that refuses a parseable command naming a nax-owned file (`.nax/config.json`, a feature `prd.json`, the queue-control files). `gated` matches each segment against the stage's single `Bash(...)` allow rule, and `escalate` turns a denial the gate could not adjudicate into an interactive approval prompt; under either, a stage without a `Bash(...)` rule never gets the tool, and nax warns about such inert stages at run start. Approvals you choose to remember are kept per project and managed with `nax approvals list` / `nax approvals rm`; `execution.approvalTimeout` (default 600000 ms) bounds how long a prompt waits before denying.
|
|
180
204
|
|
|
@@ -182,7 +206,7 @@ See [MCP & Command Interception](docs/guides/mcp-and-interception.md) for setup,
|
|
|
182
206
|
|
|
183
207
|
These settings govern nax's own `Bash` and `RunCommand` tools, so, like MCP and the interceptor, they take effect for the native agent; an ACP agent runs commands under its own tooling.
|
|
184
208
|
|
|
185
|
-
See [Sandbox & Command Safety](docs/guides/sandbox-and-command-safety.md), [Approvals](docs/guides/approvals.md), [The Bash Tool](docs/guides/bash-tool.md) and [Permissions](docs/guides/permissions.md).
|
|
209
|
+
See [Sandbox & Command Safety](https://github.com/nathapp-io/nax/blob/main/docs/guides/sandbox-and-command-safety.md), [Approvals](https://github.com/nathapp-io/nax/blob/main/docs/guides/approvals.md), [The Bash Tool](https://github.com/nathapp-io/nax/blob/main/docs/guides/bash-tool.md) and [Permissions](https://github.com/nathapp-io/nax/blob/main/docs/guides/permissions.md).
|
|
186
210
|
|
|
187
211
|
---
|
|
188
212
|
|
|
@@ -200,11 +224,11 @@ nax trust check --json # machine-readable answer for a script
|
|
|
200
224
|
|
|
201
225
|
Trust is hierarchical and stored once per machine (`~/.nax/trust.json`): an entry for a folder covers that folder and **every folder beneath it**, so trusting a parent covers the clones, worktrees and new projects you create under it later — you do not re-grant trust per checkout. Trusting `/` or your home directory would cover everything you own and is refused unless you pass `--force`. In CI, grant trust once at the top of the job with `nax trust add "$PWD" --yes`, which is a no-op (exit 0) on a cache that already covers the path.
|
|
202
226
|
|
|
203
|
-
See [`nax trust`](docs/guides/cli-reference.md#nax-trust) for the full surface.
|
|
227
|
+
See [`nax trust`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-trust) for the full surface.
|
|
204
228
|
|
|
205
|
-
### Test Strategies
|
|
229
|
+
### Test Strategies (pipeline mode)
|
|
206
230
|
|
|
207
|
-
|
|
231
|
+
In pipeline mode, each story gets a test strategy. `tdd.strategy` (default `"auto"`) selects how strategies are chosen: `auto` picks per story based on complexity and content — security-critical stories always get `three-session-tdd` regardless of complexity. The strategy values are:
|
|
208
232
|
|
|
209
233
|
| Strategy | Sessions | When to use |
|
|
210
234
|
|:---------|:---------|:------------|
|
|
@@ -214,45 +238,47 @@ nax supports five test strategies. When `tdd.strategy` is `"auto"` (default), th
|
|
|
214
238
|
| `test-after` | 1 | Exploratory / prototyping — implement first, add tests after |
|
|
215
239
|
| `no-test` | 0 | Config-only, docs, CI, dependency bumps — requires `noTestJustification` |
|
|
216
240
|
|
|
217
|
-
See [Test Strategies Guide](docs/guides/test-strategies.md) for the
|
|
241
|
+
Workflow mode does not read these strategies: the implementer writes its own tests in one session, and the gates decide the result. See [Test Strategies Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/test-strategies.md) for the pipeline routing decision tree and security override rules.
|
|
218
242
|
|
|
219
243
|
### Story Decomposition
|
|
220
244
|
|
|
221
245
|
An oversized story is split into smaller sub-stories with `nax plan -f <feature> --decompose <storyId>` — a plan-time operation, not a mid-run stage. The precheck story-size gate (`precheck.storySizeGate`) flags stories over its thresholds. The parent is marked `decomposed` and the sub-stories, with dependency ordering, are added to the PRD.
|
|
222
246
|
|
|
223
|
-
See [Story Decomposition Guide](docs/guides/decomposition.md).
|
|
247
|
+
See [Story Decomposition Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/decomposition.md).
|
|
248
|
+
|
|
249
|
+
### Regression Gate (pipeline mode)
|
|
224
250
|
|
|
225
|
-
|
|
251
|
+
In pipeline mode, after all stories pass, nax runs the full test suite once. If it fails, nax maps each failing test file back to the story that introduced it and runs a targeted rectification cycle for that story. A suite timeout is accepted as a pass by default (`execution.regressionGate.acceptOnTimeout`). If failures remain, the affected stories are marked `regression-failed`, the run status becomes `failed`, and the `on-final-regression-fail` hook fires.
|
|
226
252
|
|
|
227
|
-
|
|
253
|
+
In workflow mode the equivalent checks are the `full-suite` gate in each story and the `final-gates` step of the feature workflow.
|
|
228
254
|
|
|
229
|
-
See [Regression Gate Guide](docs/guides/regression-gate.md).
|
|
255
|
+
See [Regression Gate Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/regression-gate.md).
|
|
230
256
|
|
|
231
257
|
### Parallel & Isolated Execution
|
|
232
258
|
|
|
233
|
-
With `--parallel <n
|
|
259
|
+
Parallel execution is a pipeline-mode feature. With `--parallel <n>` in pipeline mode, nax runs up to `n` stories whose dependencies are already satisfied at the same time, each in its own git worktree (`0` = auto, based on CPU cores). Both modes run the regression gate once at the end; only sequential runs attribute a regression to a story and rectify it — in parallel mode it is reported for a human. Workflow mode ignores `--parallel` and runs stories one at a time.
|
|
234
260
|
|
|
235
|
-
Even in sequential mode, stories can be isolated in per-story git worktrees (`execution.storyIsolation: "worktree"`) to prevent cross-story state leakage.
|
|
261
|
+
Even in sequential pipeline mode, stories can be isolated in per-story git worktrees (`execution.storyIsolation: "worktree"`) to prevent cross-story state leakage. Workflow mode forces `storyIsolation` to `shared`.
|
|
236
262
|
|
|
237
|
-
See [Parallel Execution Guide](docs/guides/parallel-execution.md).
|
|
263
|
+
See [Parallel Execution Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/parallel-execution.md).
|
|
238
264
|
|
|
239
265
|
### Monorepo Support
|
|
240
266
|
|
|
241
267
|
Per-package context files, per-package test commands, and per-story working directories are supported. Initialize with `nax init --package packages/api`. Package config files live at `.nax/mono/packages/<pkg>/config.json`.
|
|
242
268
|
|
|
243
|
-
See [Monorepo Guide](docs/guides/monorepo.md).
|
|
269
|
+
See [Monorepo Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/monorepo.md).
|
|
244
270
|
|
|
245
271
|
### Hooks
|
|
246
272
|
|
|
247
273
|
Lifecycle hooks, defined in `.nax/hooks.json` (project) and `~/.nax/hooks.json` (global) — not in `config.json` — fire at key points (`on-start`, `on-story-complete`, `on-all-stories-complete`, `on-complete`, `on-final-regression-fail`, and more). Use them to trigger deployments, send notifications, or integrate with external systems.
|
|
248
274
|
|
|
249
|
-
See [Hooks Guide](docs/guides/hooks.md).
|
|
275
|
+
See [Hooks Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/hooks.md).
|
|
250
276
|
|
|
251
277
|
### Plugins
|
|
252
278
|
|
|
253
279
|
Extensible plugin architecture for prompt optimization, custom routing, code review, and reporting. Plugins live in `.nax/plugins/` (project) or `~/.nax/plugins/` (global). Post-run action plugins (e.g. auto-PR creation) can implement `IPostRunAction` for results-aware post-completion workflows.
|
|
254
280
|
|
|
255
|
-
See [Plugin System](docs/architecture/subsystems.md#23-plugin-system).
|
|
281
|
+
See [Plugin System](https://github.com/nathapp-io/nax/blob/main/docs/architecture/subsystems.md#23-plugin-system).
|
|
256
282
|
|
|
257
283
|
---
|
|
258
284
|
|
|
@@ -268,9 +294,9 @@ The default agent is `native`: nax drives the model in-process over `@nathapp/na
|
|
|
268
294
|
| Codex | `codex-acp` (or `npx @agentclientprotocol/codex-acp`) | Set `agent.default: "codex"` |
|
|
269
295
|
| Gemini CLI | `gemini --acp` | Set `agent.default: "gemini"` |
|
|
270
296
|
| Pi Coding Agent | `pi-acp` (or `npx pi-acp`) | Set `agent.default: "pi"` |
|
|
271
|
-
| Aider | — | Known name with no ACP launcher; it fails at session open |
|
|
297
|
+
| Aider | — | Known name with no ACP launcher; it lists but fails at session open |
|
|
272
298
|
|
|
273
|
-
See [Agents Guide](docs/guides/agents.md) and the [Context Engine Guide](docs/guides/context-engine.md) for agent-portable context configuration.
|
|
299
|
+
See [Agents Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/agents.md) and the [Context Engine Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/context-engine.md) for agent-portable context configuration.
|
|
274
300
|
|
|
275
301
|
---
|
|
276
302
|
|
|
@@ -280,12 +306,11 @@ See [Agents Guide](docs/guides/agents.md) and the [Context Engine Guide](docs/gu
|
|
|
280
306
|
|:--------|:---------|
|
|
281
307
|
| Precheck blocks with "Uncommitted changes detected" | Commit or stash your changes — nax's own runtime files are ignored by the check |
|
|
282
308
|
| HOME env warning | Set HOME to an absolute path — nax warns if it contains `~` |
|
|
283
|
-
| ACP sessions leaking | Upgrade to nax v0.48+ and ensure `.nax/acp-sessions.json` is gitignored |
|
|
284
309
|
| Monorepo packages misclassified | Ensure `.nax/mono/packages/<pkg>/config.json` is set up per package |
|
|
285
|
-
| Agent Bash refused
|
|
286
|
-
| Acceptance tests regenerating every run | Check `acceptance-meta.json` — stale fingerprints indicate outdated story context |
|
|
310
|
+
| Agent Bash refused because the sandbox is unavailable | The OS sandbox is on by default and `raw` Bash requires it. Run `nax sandbox probe` to see why it cannot enforce on this machine, then fix the environment, set the stage's `bashApproval` to `gated`/`escalate`, or set `execution.sandbox.enabled: false` |
|
|
311
|
+
| Acceptance tests regenerating every run (pipeline mode) | Check `acceptance-meta.json` — stale fingerprints indicate outdated story context. Workflow mode does not run acceptance tests |
|
|
287
312
|
|
|
288
|
-
See the [Troubleshooting Guide](docs/guides/troubleshooting.md) for more.
|
|
313
|
+
See the [Troubleshooting Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/troubleshooting.md) for more.
|
|
289
314
|
|
|
290
315
|
---
|
|
291
316
|
|