@nathapp/nax 0.51.0 → 0.51.2

package/README.md

@@ -33,15 +33,20 @@ nax run -f my-feature --plan --from spec.md
 ## How It Works
 
 ```
-analyze → route → execute → verify → (loop until all stories pass) → regression gate
+(plan →) acceptance setup → route → execute → verify → (escalate) → regression gate → acceptance
 ```
 
-1. **Analyze** each user story — classify complexity, select test strategy
-2. **Route** to the right model tier (cheap → standard → premium)
-3. **Execute** an agent session (Claude Code by default)
-4. **Verify** tests pass; escalate model tier on failure
-5. **Loop** until all stories are complete or a cost/iteration limit is hit
-6. **Regression gate** — deferred full-suite verification after all stories pass
+1. **Plan** *(optional)* — `nax run --plan` generates a `prd.json` from a spec file using an LLM
+2. **Acceptance setup** *(pre-run)* — generate acceptance tests and assert RED (tests must fail before implementation)
+3. **Route** — classify story complexity and select model tier (fast → balanced → powerful)
+4. **Context** — gather relevant code, tests, and project standards
+5. **Execute** — run an agent session (Claude Code, Codex, Gemini CLI, or ACP)
+6. **Verify** — run scoped tests; if failing, **rectify** before escalating
+7. **Review** — lint + typecheck; if failing, **autofix** before escalating
+8. **Escalate** — on repeated failure, retry with a higher model tier
+9. **Loop** — repeat steps 3–8 per story until all pass or a cost/iteration limit is hit
+10. **Regression gate** — deferred full-suite run after all stories pass
+11. **Acceptance** *(post-run)* — run the generated acceptance tests against the completed feature
 
 ---
 
@@ -49,7 +54,7 @@ analyze → route → execute → verify → (loop until all stories pass) → r
 
 ### `nax init`
 
-Initialize nax in your project. Creates the `nax/` folder structure.
+Initialize nax in your project. Creates the `.nax/` folder structure.
 
 ```bash
 nax init
@@ -57,7 +62,7 @@ nax init
 
 Creates:
 ```
-nax/
+.nax/
 ├── config.json       # Project-level config
 └── features/         # One folder per feature
 ```
@@ -68,7 +73,7 @@ nax/
 nax init --package packages/api
 ```
 
-Creates `packages/api/nax/context.md` for per-package agent context.
+Creates `.nax/mono/packages/api/context.md` for per-package agent context.
 
 ---
 
@@ -80,7 +85,7 @@ Scaffold a new feature.
 nax features create user-auth
 ```
 
-Creates `nax/features/user-auth/prd.json` — edit this file to define your user stories.
+Creates `.nax/features/user-auth/spec.md` — fill in the overview, user stories, and acceptance criteria, then run `nax plan` to generate `prd.json`.
 
 ### `nax features list`
 
@@ -135,7 +140,7 @@ nax run -f my-feature
 | Flag | Description |
 |:-----|:------------|
 | `-f, --feature <name>` | Feature name |
-| `-a, --agent <name>` | Force a specific agent (`claude`, `opencode`, `codex`, etc.) |
+| `-a, --agent <name>` | Force a specific agent (`claude`, `opencode`, `codex`, etc.). Only applies when `agent.protocol = "cli"` — ignored when using ACP protocol. |
 | `--plan` | Run plan phase first (requires `--from`) |
 | `--from <spec-path>` | Spec file for `--plan` |
 | `--one-shot` | Skip interactive Q&A during planning (ACP only) |
@@ -201,21 +206,28 @@ nax status -f my-feature
 
 ---
 
-### `nax logs -f <name>`
+### `nax logs`
 
-Stream logs from the current or last run.
+Stream logs from the current or last run. Run from your project directory.
 
 ```bash
-nax logs -f my-feature
+# List all recorded runs
+nax logs --list
 
-# Follow in real-time
-nax logs -f my-feature --follow
+# Follow current run in real-time
+nax logs --follow
 
 # Filter by story
-nax logs -f my-feature --story US-003
+nax logs --story US-003
 
-# Filter by level
-nax logs -f my-feature --level error
+# Filter by log level
+nax logs --level error
+
+# Select a specific run by ID
+nax logs --run <runId>
+
+# Raw JSONL output (for scripting)
+nax logs --json
 ```
 
 ---
@@ -255,7 +267,7 @@ Output sections:
 
 ### `nax generate`
 
-Generate agent config files from `nax/context.md`. Supports Claude Code, OpenCode, Codex, Cursor, Windsurf, Aider, and Gemini.
+Generate agent config files from `.nax/context.md`. Supports Claude Code, OpenCode, Codex, Cursor, Windsurf, Aider, and Gemini.
 
 ```bash
 nax generate
@@ -265,7 +277,7 @@ nax generate
 
 | Flag | Description |
 |:-----|:------------|
-| `-c, --context <path>` | Context file path (default: `nax/context.md`) |
+| `-c, --context <path>` | Context file path (default: `.nax/context.md`) |
 | `-o, --output <dir>` | Output directory (default: project root) |
 | `-a, --agent <name>` | Generate for a specific agent only (`claude`, `opencode`, `cursor`, `windsurf`, `aider`, `codex`, `gemini`) |
 | `--dry-run` | Preview without writing files |
@@ -287,7 +299,7 @@ nax generate
 
 **Workflow:**
 
-1. Create `nax/context.md` — describe your project's architecture, conventions, and coding standards
+1. Create `.nax/context.md` — describe your project's architecture, conventions, and coding standards
 2. Run `nax generate` — writes agent config files to the project root (and per-package if configured)
 3. Commit the generated files — your agents will automatically pick them up
 
@@ -301,7 +313,7 @@ nax generate --package packages/api
 nax generate --all-packages
 ```
 
-Each package can have its own `nax/context.md` at `<package>/nax/context.md` for package-specific agent instructions.
+Each package can have its own context file at `.nax/mono/<package>/context.md` for package-specific agent instructions (created via `nax init --package <package>`).
 
 ---
 
@@ -317,7 +329,7 @@ nax prompts -f my-feature
 
 | Flag | Description |
 |:-----|:------------|
-| `--init` | Export default role templates to `nax/templates/` for customization |
+| `--init` | Export default role templates to `.nax/templates/` for customization |
 | `--role <role>` | Show prompt for a specific role (`implementer`, `test-writer`, `verifier`, `tdd-simple`) |
 
 After running `--init`, edit the templates and nax will use them automatically via `prompts.overrides` config.
@@ -354,12 +366,19 @@ nax agents
 
 ---
 
-### `nax config --explain`
+### `nax config`
 
-Display the effective merged configuration with inline explanations for every field.
+Display the effective merged configuration (global + project layers).
 
 ```bash
-nax config -f my-feature --explain
+# Show merged config
+nax config
+
+# Show with field descriptions
+nax config --explain
+
+# Show only fields where project overrides global
+nax config --diff
 ```
 
 ---
@@ -371,7 +390,7 @@ Config is layered — project overrides global:
 | File | Scope |
 |:-----|:------|
 | `~/.nax/config.json` | Global (all projects) |
-| `nax/config.json` | Project-level override |
+| `.nax/config.json` | Project-level override |
 
 **Key options:**
 
@@ -414,7 +433,7 @@ Review commands (`lint`, `typecheck`) are executed directly via `Bun.spawn` —
 }
 ```
 ```json
-// nax/config.json
+// .nax/config.json
 "quality": {
   "commands": {
     "typecheck": "bun run build-and-check"
@@ -442,13 +461,15 @@ Use `testScoped` to define the exact scoped test command with a `{{files}}` plac
 
 If `testScoped` is not configured, nax falls back to a heuristic that replaces the last path-like token in the `test` command. **Recommended:** always configure `testScoped` explicitly to avoid surprises.
 
-**TDD strategy options:**
+**TDD strategy options:** <a name="tdd-strategy-options"></a>
 
 | Value | Behaviour |
 |:------|:----------|
-| `auto` | nax decides based on complexity and tags |
-| `lite` | Prefer `three-session-tdd-lite` for complex stories |
-| `strict` | Always use full `three-session-tdd` for complex stories |
+| `auto` | nax decides based on complexity and tags — simple→`tdd-simple`, security/public-api→`three-session-tdd`, else→`three-session-tdd-lite` |
+| `strict` | Always use `three-session-tdd` (strictest — all stories) |
+| `lite` | Always use `three-session-tdd-lite` |
+| `simple` | Always use `tdd-simple` (1 session) |
+| `off` | No TDD — tests written after implementation (`test-after`) |
 
 ---
 
@@ -462,12 +483,12 @@ Customize the instructions sent to each agent role for your project's specific n
 
 ```bash
 nax prompts --init              # Create default templates
-# Edit nax/templates/*.md
+# Edit .nax/templates/*.md
 nax prompts --export test-writer # Preview a role's prompt
 nax run -f my-feature           # Uses your custom prompts
 ```
 
-**Full guide:** See [Prompt Customization Guide](docs/prompt-customization.md) for detailed instructions, role reference, and best practices.
+**Full guide:** See [Prompt Customization Guide](docs/guides/prompt-customization.md) for detailed instructions, role reference, and best practices.
 
 ---
 
@@ -477,12 +498,13 @@ nax selects a test strategy per story based on complexity and tags:
 
 | Strategy | Sessions | When | Description |
 |:---------|:---------|:-----|:------------|
-| `test-after` | 1 | Refactors, deletions, config, docs | Single session, no TDD discipline |
+| `no-test` | 1 | Config, docs, CI, pure refactors with no behavior change | No tests written or run — requires `noTestJustification` in prd.json |
+| `test-after` | 1 | Refactors, deletions | Single session, tests written after implementation |
 | `tdd-simple` | 1 | Simple stories | Single session with TDD prompt (red-green-refactor) |
 | `three-session-tdd-lite` | 3 | Medium stories | Three sessions, relaxed isolation rules |
 | `three-session-tdd` | 3 | Complex/security stories | Three sessions, strict file isolation |
 
-Configure the default TDD behavior in `nax/config.json`:
+Configure the default TDD behavior in `.nax/config.json`:
 
 ```json
 {
@@ -492,11 +514,7 @@ Configure the default TDD behavior in `nax/config.json`:
 }
 ```
 
-| Value | Behaviour |
-|:------|:----------|
-| `auto` | nax decides based on complexity and tags (default) |
-| `lite` | Prefer `three-session-tdd-lite` for complex stories |
-| `strict` | Always use full `three-session-tdd` for complex stories |
+See [TDD strategy options](#tdd-strategy-options) for all values.
 
 ---
 
@@ -544,7 +562,7 @@ Configured under `quality.testing` — supports **per-package override** in mono
 
 > **Tip:** `externalBoundaries` and `mockGuidance` complement `context.md`. nax provides the rule ("mock all I/O"), while `context.md` provides project-specific knowledge ("use `ioredis-mock` for Redis"). Use both for best results.
 
-> **Monorepo:** Each package can override `quality.testing` in its own `packages/<name>/nax/config.json`. For example, `packages/api` can specify Redis boundaries while `packages/web` specifies HTTP-only.
+> **Monorepo:** Each package can override `quality.testing` in its own `.nax/mono/<package>/config.json`. For example, `packages/api` can specify Redis boundaries while `apps/web` specifies HTTP-only.
 
 > **Opt-out:** Set `quality.testing.hermetic: false` if your project requires real integration calls (e.g. live database tests against a local dev container).
 
@@ -552,34 +570,41 @@ Configured under `quality.testing` — supports **per-package override** in mono
 
 ## Story Decomposition
 
-When a story is too large (complex/expert with >6 acceptance criteria), nax can automatically decompose it into smaller sub-stories. This runs during the routing stage.
+Story decomposition is **opt-in** — disabled by default. Enable it by adding a `decompose` block to `.nax/config.json`.
 
-**Trigger:** The `story-oversized` interaction trigger fires when a story exceeds the configured thresholds. You can approve decomposition, skip the story, or continue as-is.
-
-**How it works:**
-
-1. The `DecomposeBuilder` constructs a prompt with the target story, sibling stories (to prevent overlap), and codebase context
-2. An LLM generates sub-stories with IDs, titles, descriptions, acceptance criteria, and dependency ordering
-3. Post-decompose validators check:
-   - **Overlap** — sub-stories must not duplicate scope of existing stories
-   - **Coverage** — sub-stories must cover all parent acceptance criteria
-   - **Complexity** — each sub-story must be simpler than the parent
-   - **Dependencies** — dependency graph must be acyclic with valid references
-4. The parent story is replaced in the PRD with the validated sub-stories
+When enabled, nax checks during the routing stage whether a story is oversized (complex/expert complexity with more ACs than `maxAcceptanceCriteria`). If so, an LLM breaks it into smaller sub-stories and replaces the original in the PRD.
 
 **Configuration:**
 
 ```json
 {
   "decompose": {
-    "enabled": true,
-    "maxSubStories": 5,
-    "minAcceptanceCriteria": 6,
-    "complexityThreshold": ["complex", "expert"]
+    "trigger": "auto",
+    "maxAcceptanceCriteria": 6,
+    "maxSubstories": 5,
+    "maxSubstoryComplexity": "medium",
+    "maxRetries": 2,
+    "model": "balanced"
   }
 }
 ```
 
+**Trigger modes:**
+
+| Value | Behaviour |
+|:------|:----------|
+| `auto` | Decompose automatically — no confirmation prompt |
+| `confirm` | Show interaction prompt — you approve, skip, or continue as-is |
+| `disabled` | Never decompose — log a warning if story is oversized |
+
+> **Note:** `storySizeGate` (under `precheck`) is a separate pre-run guard that warns if stories exceed size limits before execution starts. Decomposition happens during routing, mid-run.
+
+**How it works:**
+
+1. An LLM generates sub-stories with IDs, titles, descriptions, acceptance criteria, and dependency ordering
+2. Post-decompose validators check overlap, coverage, complexity, and dependency ordering
+3. The parent story is replaced in the PRD with the validated sub-stories
+
 ---
 
 ## Regression Gate
@@ -601,8 +626,8 @@ After all stories pass their individual verification, nax can run a deferred ful
 | Mode | Behaviour |
 |:-----|:----------|
 | `disabled` | No regression gate |
-| `per-story` | Full suite after each story (expensive) |
-| `deferred` | Full suite once after all stories pass (recommended) |
+| `per-story` | Full suite after each story — higher cost and slower if stories fail regression |
+| `deferred` | Full suite once after all stories pass (recommended) — **default** |
 
 If the regression gate detects failures, nax maps them to the responsible story via git blame and attempts automated rectification. If rectification fails, affected stories are marked as `regression-failed`.
 
@@ -646,7 +671,9 @@ nax run -f my-feature --parallel 3
 
 ## Agents
 
-nax supports multiple coding agents. By default it uses Claude Code via the ACP protocol.
+nax supports multiple coding agents via the [Agent Client Protocol (ACP)](https://github.com/openclaw/acpx). **ACP protocol is recommended** — it provides persistent sessions, structured cost/token reporting, and works with all supported agents.
+
+> **CLI protocol** (`agent.protocol: "cli"`) is supported for Claude Code only and is being gradually deprecated in favour of ACP. New projects should use ACP.
 
 ```bash
 # List installed agents and their capabilities
@@ -655,21 +682,16 @@ nax agents
 
 **Supported agents:**
 
-| Agent | Protocol | Notes |
-|:------|:---------|:------|
-| `claude` | ACP (default) | Claude Code via acpx |
-| `opencode` | ACP | OpenCode via acpx |
-| `codex` | ACP | Codex via acpx |
-| `cursor` | ACP | Cursor via acpx |
-| `windsurf` | ACP | Windsurf via acpx |
-| `aider` | ACP | Aider via acpx |
-| `gemini` | ACP | Gemini CLI via acpx |
+| Agent | CLI mode |
+|:------|:---------|
+| `claude` | ✅ Stable |
+| All others (`codex`, `gemini`, `opencode`, `cursor`, `copilot`, `kilo`, `qwen`, `kimi`, `iflow`, `droid`, `kiro`, and more) | 🧪 Experimental |
 
-**ACP protocol (default):**
+nax connects to agents via [acpx](https://github.com/openclaw/acpx). All agents run as persistent ACP sessions — nax sends prompts and receives structured JSON-RPC responses including token counts and exact USD cost per session. For the full list of supported agents and their ACP startup commands, see the [acpx agent docs](https://github.com/openclaw/acpx#agents).
 
-nax uses [acpx](https://github.com/nathapp/acpx) as the ACP transport. All agents run as persistent sessions — nax sends prompts and receives structured JSON-RPC responses including token counts and exact USD cost per session.
+> **Note:** When `agent.protocol` is set to `"acp"`, the `--agent` CLI flag has no effect — all execution routes through the ACP adapter regardless of agent name.
 
-> **Known issue — `acpx` ≤ 0.3.1:** The `--model` flag is not supported. Model selection via `execution.model` or per-package `model` overrides has no effect when using acpx as the ACP transport. This is a limitation in the underlying `@zed-industries/claude-agent-acp` adapter, which ignores runtime model requests and always uses the model configured in Claude Code settings. A fix is being tracked in [openclaw/acpx#49](https://github.com/openclaw/acpx/issues/49). As a workaround, set your preferred model directly in Claude Code settings before running nax.
+> **Known issue — `acpx` ≤ 0.3.1:** The `--model` flag is not supported. Model selection via `execution.model` or per-package `model` overrides has no effect. As a temporary workaround, use the [nathapp-io/acpx](https://github.com/nathapp-io/acpx) fork which adds `--model` support. Upstream fix is tracked in [openclaw/acpx#49](https://github.com/openclaw/acpx/issues/49).
 
 **Configuring agents:**
 
@@ -683,10 +705,11 @@ nax uses [acpx](https://github.com/nathapp/acpx) as the ACP transport. All agent
 }
 ```
 
-**Force a specific agent at runtime:**
+**Force a specific agent at runtime (CLI protocol only):**
 
 ```bash
-nax run -f my-feature --agent opencode
+# Only applies when agent.protocol = "cli" (Claude Code only — other agents experimental)
+nax run -f my-feature --agent claude
 ```
 
 ---
@@ -708,27 +731,27 @@ nax init --package packages/web
 
 ### Per-Package Config
 
-Each package can override specific config fields by placing a `nax/config.json` inside the package directory:
+Each package's config and context are stored centrally under the root `.nax/mono/` directory:
 
 ```
 repo-root/
-├── nax/
-│   └── config.json          # root config
-├── packages/
-│   ├── api/
-│   │   └── nax/
-│   │       ├── config.json  # overrides for api package
-│   │       └── context.md   # agent context for api
-│   └── web/
-│       └── nax/
-│           ├── config.json  # overrides for web package
-│           └── context.md   # agent context for web
+├── .nax/
+│   ├── config.json                    # root config
+│   └── mono/
+│       ├── packages/
+│       │   └── api/
+│       │       ├── config.json        # overrides for packages/api
+│       │       └── context.md        # agent context for packages/api
+│       └── apps/
+│           └── api/
+│               ├── config.json        # overrides for apps/api
+│               └── context.md        # agent context for apps/api
 ```
 
 **Overridable fields per package:** `execution`, `review`, `acceptance`, `quality`, `context`
 
 ```json
-// packages/api/nax/config.json
+// .nax/mono/packages/api/config.json
 {
   "quality": {
     "commands": {
@@ -764,7 +787,7 @@ When `nax plan` generates stories for a monorepo, it auto-discovers packages fro
 - `turbo.json` → `packages` field
 - `package.json` → `workspaces`
 - `pnpm-workspace.yaml` → `packages`
-- Existing `*/nax/context.md` files
+- Existing `.nax/mono/*/context.md` files
 
 ### Generate Agent Files for All Packages
 
@@ -772,7 +795,7 @@ When `nax plan` generates stories for a monorepo, it auto-discovers packages fro
 nax generate --all-packages
 ```
 
-Generates a `CLAUDE.md` (or agent-specific file) in each discovered package directory, using the package's own `nax/context.md` if present.
+Generates a `CLAUDE.md` (or agent-specific file) in each discovered package directory, using the package's own `.nax/mono/<package>/context.md` if present.
 
 ---
 
@@ -780,7 +803,7 @@ Generates a `CLAUDE.md` (or agent-specific file) in each discovered package dire
 
 Integrate notifications, CI triggers, or custom scripts via lifecycle hooks.
 
-**Project hooks** (`nax/hooks.json`):
+**Project hooks** (`.nax/hooks.json`):
 
 ```json
 {
@@ -883,7 +906,7 @@ nax can pause execution and prompt you for decisions at critical points. Configu
 | `max-retries` | 🟡 Yellow | `skip` | Story exhausted all retry attempts — skip and continue? |
 | `pre-merge` | 🟡 Yellow | `escalate` | Checkpoint before merging to main branch |
 | `human-review` | 🟡 Yellow | `skip` | Human review required on critical failure |
-| `story-oversized` | 🟡 Yellow | `continue` | Story too complex — decompose into sub-stories? |
+| `story-oversized` | 🟡 Yellow | `continue` | Story too complex — decompose into sub-stories? (only fires when `decompose.trigger = "confirm"`) |
 | `story-ambiguity` | 🟢 Green | `continue` | Story requirements unclear — continue with best effort? |
 | `review-gate` | 🟢 Green | `continue` | Code review checkpoint before proceeding |
 
@@ -913,7 +936,7 @@ nax can pause execution and prompt you for decisions at critical points. Configu
 
 Extend nax with custom reviewers, reporters, or integrations.
 
-**Project plugins** (`nax/config.json`):
+**Project plugins** (`.nax/config.json`):
 
 ```json
 {
@@ -976,35 +999,85 @@ nax precheck -f my-feature
 
 **Run stopped mid-way**
 
-nax saves progress in `nax/features/<name>/prd.json`. Re-run with the same command — completed stories are skipped automatically.
+nax saves progress in `.nax/features/<name>/prd.json`. Re-run with the same command — completed stories are skipped automatically.
 
 ---
 
 ## PRD Format
 
-User stories are defined in `nax/features/<name>/prd.json`:
+User stories are defined in `.nax/features/<name>/prd.json`. Typically generated by `nax plan` — but you can write it by hand.
 
 ```json
 {
+  "project": "my-app",
   "feature": "user-auth",
+  "branchName": "feat/user-auth",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "updatedAt": "2026-01-01T00:00:00.000Z",
   "userStories": [
     {
       "id": "US-001",
       "title": "Add login endpoint",
-      "description": "POST /auth/login with email/password",
+      "description": "POST /auth/login accepts email + password, returns signed JWT on success",
       "acceptanceCriteria": [
-        "Returns JWT on success",
-        "Returns 401 on invalid credentials"
+        "Returns 200 + JWT on valid credentials",
+        "Returns 401 on invalid credentials",
+        "Rate-limits to 5 attempts per minute"
       ],
-      "complexity": "medium",
       "tags": ["auth", "security"],
-      "status": "pending"
+      "dependencies": [],
+      "status": "pending",
+      "passes": false,
+      "attempts": 0,
+      "escalations": [],
+      "contextFiles": ["src/auth/types.ts"],
+      "expectedFiles": ["src/auth/login.ts", "test/auth/login.test.ts"]
+    },
+    {
+      "id": "US-002",
+      "title": "Update changelog",
+      "description": "Add v1.0 entry to CHANGELOG.md",
+      "acceptanceCriteria": ["CHANGELOG.md has v1.0 section"],
+      "tags": ["docs"],
+      "dependencies": [],
+      "status": "pending",
+      "passes": false,
+      "attempts": 0,
+      "escalations": [],
+      "routing": {
+        "complexity": "simple",
+        "testStrategy": "no-test",
+        "noTestJustification": "Docs-only change — no executable code",
+        "reasoning": "Pure documentation update"
+      }
     }
   ]
 }
 ```
 
-> **Note:** Use `"status": "passed"` (not `"done"`) to manually mark a story complete.
+**Key fields:**
+
+| Field | Required | Description |
+|:------|:---------|:------------|
+| `id` | ✅ | Story ID — must be unique (e.g. `US-001`) |
+| `title` | ✅ | Short story title |
+| `description` | ✅ | What needs to be built |
+| `acceptanceCriteria` | ✅ | Testable outcomes — used for acceptance tests |
+| `tags` | ✅ | Routing hints that influence complexity classification and test strategy selection. Security tags (`auth`, `security`, `jwt`, `oauth`, `rbac`, etc.) and public-API tags (`public-api`, `endpoint`, `sdk`, etc.) force `three-session-tdd`. UI/integration tags (`ui`, `layout`, `cli`, `integration`) prefer `three-session-tdd-lite`. |
+| `dependencies` | ✅ | Story IDs that must pass before this one runs |
+| `status` | ✅ | `pending` \| `in-progress` \| `passed` \| `failed` \| `skipped` \| `blocked` \| `paused` |
+| `passes` | ✅ | `true` once all ACs pass — set by nax, not manually |
+| `attempts` | ✅ | Retry counter — set by nax |
+| `escalations` | ✅ | Escalation history — set by nax |
+| `contextFiles` | optional | Files pre-loaded into agent prompt |
+| `expectedFiles` | optional | Files that must exist after execution (pre-flight gate) |
+| `workdir` | optional | Package subdirectory for monorepo stories (e.g. `packages/api`) |
+| `routing` | optional | Pre-set routing — skip LLM classification if provided |
+| `routing.testStrategy` | optional | Override test strategy (e.g. `no-test`, `tdd-simple`). Only honored when `routing.contentHash` is absent — omit `contentHash` to prevent the LLM classifier from overriding your manual value. |
+| `routing.noTestJustification` | required if `no-test` | Explain why no tests are needed |
+| `storyPoints` | optional | Estimate (default: 1) |
+
+> **Tip:** Use `"status": "passed"` to manually skip a story that's already done.
 
 ---
 

package/dist/nax.js

@@ -3321,7 +3321,8 @@ Decompose this spec into user stories. For each story, provide:
 9. reasoning: Why this complexity level
 10. estimatedLOC: Estimated lines of code to change
 11. risks: Array of implementation risks
-12. testStrategy: "test-after" | "tdd-simple" | "three-session-tdd" | "three-session-tdd-lite"
+12. testStrategy: "no-test" | "test-after" | "tdd-simple" | "three-session-tdd" | "three-session-tdd-lite"
+13. noTestJustification: string (REQUIRED when testStrategy is "no-test" \u2014 explain why tests are unnecessary)
 
 ${COMPLEXITY_GUIDE}
 
@@ -21122,7 +21123,7 @@ async function loadConfigForWorkdir(rootConfigPath, packageDir) {
     return rootConfig;
   }
   const repoRoot = dirname2(rootNaxDir);
-  const packageConfigPath = join7(repoRoot, PROJECT_NAX_DIR, "packages", packageDir, "config.json");
+  const packageConfigPath = join7(repoRoot, PROJECT_NAX_DIR, "mono", packageDir, "config.json");
   const packageOverride = await loadJsonFile(packageConfigPath, "config");
   if (!packageOverride) {
     return rootConfig;
@@ -22398,7 +22399,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.51.0",
+    version: "0.51.2",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -22470,8 +22471,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("bcb69c6"))
-        return "bcb69c6";
+      if (/^[0-9a-f]{6,10}$/.test("7f71f43"))
+        return "7f71f43";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -30553,7 +30554,7 @@ function generatePackageContextTemplate(packagePath) {
 }
 async function initPackage(repoRoot, packagePath, force = false) {
   const logger = getLogger();
-  const naxDir = join31(repoRoot, ".nax", "packages", packagePath);
+  const naxDir = join31(repoRoot, ".nax", "mono", packagePath);
   const contextPath = join31(naxDir, "context.md");
   if (existsSync20(contextPath) && !force) {
     logger.info("init", "Package context.md already exists (use --force to overwrite)", { path: contextPath });
@@ -67582,10 +67583,10 @@ async function generateAll(options, config2, agentFilter) {
 async function discoverPackages(repoRoot) {
   const packages = [];
   const seen = new Set;
-  for (const pattern of [".nax/packages/*/context.md", ".nax/packages/*/*/context.md"]) {
+  for (const pattern of [".nax/mono/*/context.md", ".nax/mono/*/*/context.md"]) {
     const glob = new Bun.Glob(pattern);
     for await (const match of glob.scan({ cwd: repoRoot, dot: true })) {
-      const pkgRelative = match.replace(/^\.nax\/packages\//, "").replace(/\/context\.md$/, "");
+      const pkgRelative = match.replace(/^\.nax\/mono\//, "").replace(/\/context\.md$/, "");
       const pkgAbsolute = join11(repoRoot, pkgRelative);
       if (!seen.has(pkgAbsolute)) {
         seen.add(pkgAbsolute);
@@ -68192,7 +68193,8 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "tdd-simple | three-session-tdd-lite | three-session-tdd | test-after",
+        "testStrategy": "no-test | tdd-simple | three-session-tdd-lite | three-session-tdd | test-after",
+        "noTestJustification": "string \u2014 REQUIRED when testStrategy is no-test, explains why tests are unnecessary",
         "reasoning": "string \u2014 brief classification rationale"
       },
       "escalations": [],
@@ -69569,10 +69571,10 @@ async function generateCommand(options) {
     if (dryRun) {
       console.log(source_default.yellow("\u26A0 Dry run \u2014 no files will be written"));
     }
-    console.log(source_default.blue("\u2192 Discovering packages with .nax/packages/*/context.md..."));
+    console.log(source_default.blue("\u2192 Discovering packages with .nax/mono/*/context.md..."));
     const packages = await discoverPackages(workdir);
     if (packages.length === 0) {
-      console.log(source_default.yellow("  No packages found (no .nax/packages/*/context.md or .nax/packages/*/*/context.md)"));
+      console.log(source_default.yellow("  No packages found (no .nax/mono/*/context.md or .nax/mono/*/*/context.md)"));
       return;
     }
     console.log(source_default.blue(`\u2192 Generating agent files for ${packages.length} package(s)...`));
@@ -78850,26 +78852,34 @@ features.command("create <name>").description("Create a new feature").option("-d
 
 ## Overview
 
-## Requirements
+<!-- One paragraph describing what this feature does and why it's needed. -->
 
-## Acceptance Criteria
-`);
-  await Bun.write(join53(featureDir, "plan.md"), `# Plan: ${name}
+## Background / Context
 
-## Architecture
+<!-- Optional: relevant background, existing behaviour, or constraints. -->
 
-## Phases
+## User Stories
 
-## Dependencies
-`);
-  await Bun.write(join53(featureDir, "tasks.md"), `# Tasks: ${name}
+<!-- Describe what users need. Each story becomes a unit of work for nax.
+     Be specific \u2014 the more detail here, the better the generated plan. -->
 
-## US-001: [Title]
+- As a [user], I want to [goal] so that [benefit].
 
-### Description
+## Technical Requirements
 
-### Acceptance Criteria
-- [ ] Criterion 1
+<!-- Optional: specific technical constraints, patterns to follow, APIs to use, etc. -->
+
+## Acceptance Criteria
+
+<!-- These are parsed by nax to generate acceptance tests.
+     Use clear, testable statements. Each criterion = one AC test. -->
+
+- [ ] [Describe observable outcome 1]
+- [ ] [Describe observable outcome 2]
+
+## Out of Scope
+
+<!-- What this feature explicitly does NOT cover. -->
 `);
   await Bun.write(join53(featureDir, "progress.txt"), `# Progress: ${name}
 
@@ -78880,11 +78890,9 @@ Created: ${new Date().toISOString()}
   console.log(source_default.green(`\u2705 Created feature: ${name}`));
   console.log(source_default.dim(`   ${featureDir}/`));
   console.log(source_default.dim("   \u251C\u2500\u2500 spec.md"));
-  console.log(source_default.dim("   \u251C\u2500\u2500 plan.md"));
-  console.log(source_default.dim("   \u251C\u2500\u2500 tasks.md"));
   console.log(source_default.dim("   \u2514\u2500\u2500 progress.txt"));
   console.log(source_default.dim(`
-Next: Edit spec.md and tasks.md, then: nax plan -f ${name} --from spec.md --auto`));
+Next: Edit spec.md, then: nax plan -f ${name} --from spec.md --auto`));
 });
 features.command("list").description("List all features").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
   let workdir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.51.0",
+  "version": "0.51.2",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {