@n-dx/rex

@n-dx/rex

This is an internal package of @n-dx/core. Install @n-dx/core instead — it includes this package and registers all CLI commands.

PRD management and implementation workflow CLI. Rex maintains a structured product requirements document as a tree of epics, features, tasks, and subtasks, then exposes that tree to both humans (CLI) and AI agents (MCP server) so work gets tracked from planning through completion.

Install

npm install -g @n-dx/core
# or
pnpm add -g @n-dx/core
# or
yarn global add @n-dx/core

Quick start

rex init myproject
rex add epic myproject --title="Authentication"
# note the ID printed, e.g. abc-123
rex add feature myproject --title="Login UI" --parent=abc-123 --priority=high
rex status myproject
rex next myproject

Commands

rex init [dir]

Create .rex/ in the target directory with skeleton config, empty PRD, execution log, and default workflow.

rex init              # current directory
rex init /path/to/project

Idempotent -- re-running on an existing project is safe.

rex add <level> [dir]

Add an item to the PRD. Level is one of epic, feature, task, subtask.

rex add epic --title="Payments"
rex add feature --title="Checkout Flow" --parent=<epic-id> --priority=high
rex add task --title="Validate card" --parent=<feature-id> --description="Luhn check"

Features require an epic parent, tasks require a feature parent, subtasks require a task parent.

Flags: --title (required), --parent=<id>, --description, --priority=<critical|high|medium|low>, --status=<pending|in_progress|completed|deferred|blocked>, --format=json

Smart add duplicate handling

When you use smart add (rex add "..." or rex add --file=...) and accepted proposal nodes match existing PRD items, rex shows:

Duplicate matches were detected in the selected proposals.
Choose action: c=cancel / m=merge with existing / p=proceed anyway
Duplicate action (c/m/p):

Cancel flow:

rex add "Add OAuth callback handler" .
# Duplicate action (c/m/p): c
# -> Cancelled. No items were created.

Merge flow:

rex add "Improve OAuth callback handling and retry behavior" .
# Duplicate action (c/m/p): m
# -> Matched existing items are updated
# -> Only non-duplicate nodes are created

Proceed anyway flow:

rex add "Add OAuth callback handler" .
# Duplicate action (c/m/p): p
# -> Duplicate nodes are still created
# -> New duplicate-created items persist override metadata

Input safety: empty or invalid duplicate action input defaults to cancel.

Duplicate audit metadata

When you choose p (proceed anyway), each force-created duplicate item gets an overrideMarker object in .rex/prd.json.

When you choose m (merge), matched existing items record mergedProposals entries in .rex/prd.json.

Where this appears:

• rex status tree output shows [override: <reason>] next to items that have overrideMarker.
• rex status --format=json includes:
  • per-item overrideMarker fields on affected items
  • top-level overrideMarkers summary block (totalItems, overrideCreated, normalOrMerged, items)

rex update <id> [dir]

Update an existing item.

rex update <id> --status=completed
rex update <id> --priority=critical --title="New title"

Flags: --status, --priority, --title, --description, --format=json

rex status [dir]

Print the PRD tree with status icons and completion stats.

PRD: My Project

○ Authentication [high] [1/3]
  ○ Login UI [high]
    ● Validate email
    ○ Handle errors
    ○ Password reset
◐ Dashboard [0/2]
  ◐ Charts
  ○ Export

2 completed, 1 in progress, 4 pending — 28% complete (2/7)

Icons: ○ pending, ◐ in progress, ● completed, ◌ deferred, ⊘ blocked.

Flags: --format=json outputs the full PRDDocument.

rex next [dir]

Print the next actionable task. Searches depth-first by priority, skipping completed/deferred/blocked items and items with unresolved blockedBy dependencies.

Authentication → Login UI →
  [task] Validate email (abc-123) [pending] [high]
  Luhn check on card number
  Acceptance criteria:
    - Rejects invalid card numbers
    - Accepts valid Visa/MC/Amex

Flags: --format=json

rex validate [dir]

Check PRD integrity: schema validation, version check, DAG validation (duplicate IDs, self-references, orphan blockedBy, cycles).

rex validate myproject

Exits with code 1 on failure. --format=json for structured output.

rex recommend [dir]

Get SourceVision-based recommendations. Requires a .sourcevision/ directory from a prior SourceVision analysis.

rex recommend myproject
rex recommend --accept myproject   # add recommendations to PRD

Flags: --accept, --format=json

rex analyze [dir]

Scan the project's test files, documentation, and SourceVision data to propose PRD items. Reconciles against existing items to avoid duplicates.

rex analyze myproject              # full scan
rex analyze --lite myproject       # filename-only, skip content parsing
rex analyze --accept myproject     # add proposals to PRD
rex analyze --format=json myproject

Scanners:

• Tests -- finds *.test.*, *.spec.*, __tests__/ files. Full mode parses describe/it/test blocks. Lite mode uses filenames only.
• Docs -- finds *.md, *.txt, *.json, *.yaml. Extracts headings, bullets, title/name fields.
• SourceVision -- reads .sourcevision/zones.json, inventory.json, imports.json.

Flags: --lite, --accept, --format=json

rex mcp [dir]

Start an MCP (Model Context Protocol) server on stdio. This is how AI agents interact with rex programmatically.

MCP server

The MCP server exposes seventeen tools and three resources.

Tools

Tool	Description
get_prd_status	PRD title, overall stats, per-epic breakdown
get_next_task	Next actionable task with parent chain
update_task_status	Change item status (id, status)
add_item	Create a new PRD item with full metadata
get_item	Get item details and parent chain by ID
edit_item	Edit item content (title, description, priority, tags)
move_item	Reparent an item in the PRD tree
merge_items	Consolidate duplicate sibling items
get_recommendations	SourceVision-based recommendations
verify_criteria	Map acceptance criteria to test files
reorganize	Detect and fix structural issues
health	PRD structure health score
facets	List configured facets with distribution
sync_with_remote	Sync with a remote adapter (e.g. Notion)
get_token_usage	Roll up hench run token totals per PRD item
append_log	Write to the execution log
get_capabilities	Schema version, adapter info, feature flags

Resources

URI	Content
rex://prd	Full PRDDocument as JSON
rex://workflow	Workflow instructions (markdown)
rex://log	Last 50 execution log entries

Data model

Items form a tree: epic > feature > task > subtask. Each item has:

Field	Type	Required
id	string (UUID)	yes
title	string	yes
status	pending | in_progress | completed | failing | deferred | blocked | deleted	yes
level	epic | feature | task | subtask	yes
description	string	no
acceptanceCriteria	string[]	no
priority	critical | high | medium | low	no
tags	string[]	no
source	string	no
blockedBy	string[] (item IDs)	no
branch	string	no
sourceFile	string	no
children	PRDItem[]	no

The PRD document wraps items in:

{
  "schema": "rex/v1",
  "title": "Project Name",
  "items": [ ... ]
}

See docs/prd-markdown-schema.md for the full list of rex/v1 fields (timestamps, work intervals, token usage, resolution metadata, structured requirements, provenance markers, and passthrough).

Storage

The PRD lives in .rex/prd_tree/ — a folder tree of plain Markdown files, one directory per epic/feature/task, each containing an index.md. Subtasks are sections inside their parent task's index.md.

This is the sole writable PRD surface. No rex command, MCP tool, or rex update writes prd.md or prd.json; earlier versions dual-wrote a .rex/prd.md + .rex/prd.json pair, and that is no longer the case.

Each index.md carries YAML front-matter with the item's structured fields and a generated child table:

---
id: "021e305b-d4d2-43cf-b90d-137dd203f1de"
level: "epic"
title: "CLI & Developer Tools"
status: "completed"
source: "smart-add"
---

## Children

| Title | Status |
|-------|--------|
| [Pre-Execution Confirmation Prompt](./pre-execution-confirmation-4899a4/index.md) | completed |

Because every item is plain Markdown, git diff, blame, and code review work without custom tooling. Hand-editing is supported — keep the id field intact.

• Normative schema: docs/architecture/prd-folder-tree-schema.md
• User guide: docs/guide/prd-storage.md
• Worked example: this repo's own .rex/prd_tree/

Legacy migration

Projects created before the folder tree may still have .rex/prd.md (flat Markdown, the rex/v1 schema documented in docs/prd-markdown-schema.md) or .rex/prd.json. Convert with:

rex migrate-to-folder-tree .

The command reads prd.md, falls back to branch-scoped prd_*_*.md files and then prd.json, writes the tree, and offers to delete the legacy sources. It is idempotent — re-running on an already-migrated project is a no-op. Every PRD-touching command also calls ensureLegacyPrdMigrated() on entry, so an un-migrated project is converted on first use rather than failing.

Project structure

.rex/
  config.json           Project configuration
  prd_tree/             PRD folder tree (sole writable PRD surface)
  archive.json          Pruned/reshaped item archive
  execution-log.jsonl   Append-only structured log (current)
  execution-log.1.jsonl Rotated backup (older entries)
  workflow.md           Agent workflow instructions

Execution log rotation

The execution log (execution-log.jsonl) uses automatic size-based rotation to prevent unbounded growth.

Parameter	Value	Notes
Max file size	1 MB (1,048,576 bytes)	Checked before each append
Max file count	2	Current log + one backup
Rotation trigger	Pre-append size check	If current log >= 1 MB, rotate before writing
Max entry detail	2,000 characters	Longer detail fields are truncated with ...

How rotation works:

• Before each appendLog call, the current log file size is checked.
• If it exceeds 1 MB, execution-log.jsonl is renamed to execution-log.1.jsonl (overwriting any previous backup).
• The new entry is then written to a fresh execution-log.jsonl.

Which file is authoritative?

execution-log.jsonl is always the current, authoritative log. It contains the most recent entries and is the only file read by readLog() and the rex://log MCP resource. execution-log.1.jsonl is a backup of older entries kept for manual inspection only — it is not read by any rex API.

These values are hardcoded in FileStore (src/store/file-adapter.ts), not configurable via config.json.

Commit Message Trailers

When hench (the autonomous agent) commits work on a PRD task, it appends structured git trailers to the commit message that link the commit back to the PRD context. These trailers are compatible with git interpret-trailers and render as clickable links on GitHub.

Trailer format

feat: update authentication flow

N-DX-Status: task-abc-123 in_progress → completed
N-DX: claude/claude-opus-4-7 · run 550e8400-e29b-41d4-a716-446655440000
N-DX-Item: https://dashboard.example.com/#/rex/item/task-abc-123

Trailers

Trailer	Purpose	When present
N-DX-Status	Task status transition (if status changed)	When the commit marks a task as completed
N-DX	Authorship audit: vendor, model, and run ID	Always (identifies the agent that created the commit)
N-DX-Item	Dashboard permalink to the PRD task	Always (when task ID is available)

N-DX-Item URL configuration

The dashboard base URL for the N-DX-Item trailer is resolved from .n-dx.json:

{
  "web": {
    "publicUrl": "https://dashboard.example.com"
  }
}

When web.publicUrl is not configured, defaults to http://localhost:3117 (the standard local development server URL).

The full URL is constructed as: <publicUrl>/#/rex/item/<taskId>

Handling misconfigured or unreachable URLs

If web.publicUrl is misconfigured or unreachable:

• The N-DX-Item trailer is still emitted with the configured URL
• A warning is logged, but the commit is not blocked
• Reviewers can manually visit the dashboard if needed

Default workflow

Rex ships with an opinionated workflow for AI agents:

• Validate the project, fix and commit if broken
• get_next_task -- if nothing, report complete and exit
• Read full task context
• Implement with TDD: failing test, green, refactor
• Run validation and tests
• update_task_status to mark complete
• append_log with decisions and issues
• Commit
• Exit after one task

One task per execution, no exceptions.

Development

npm install
npm run build       # tsc
npm test            # vitest
npm run dev         # tsc --watch
npm run validate    # typecheck + test

License

ISC