Workflow

The core n-dx loop: analyze your codebase, build a PRD from findings and ideas, execute tasks with an autonomous agent, repeat.

1. Analyze

ndx analyze .

Runs SourceVision static analysis: file inventory, import graph, zone detection (Louvain community detection), and React component catalog. Outputs to .sourcevision/:

• CONTEXT.md and llms.txt — AI-readable codebase summaries
• zones.json — architectural zone map with cohesion/coupling metrics
• inventory.json — file inventory with classifications
• Findings — anti-patterns, suggestions, architectural observations

2. Recommend

ndx recommend .                      # show findings
ndx recommend --accept .             # add all to PRD
ndx recommend --acknowledge=1,2 .    # skip specific findings
ndx recommend --actionable-only .    # only concrete problems

Translates SourceVision findings into PRD tasks. The --actionable-only flag filters to finding types that represent concrete problems: anti-pattern, suggestion, and move-file. This excludes non-actionable observations (metrics, patterns, relationships).

3. Add Ideas

ndx add "Add SSO support with Google and Okta" .
ndx add --file=ideas.txt .
ndx add "Add retries" --parent=<item-id> .

Smart add uses an LLM to decompose descriptions into structured epic/feature/task proposals. If duplicates are detected against existing PRD items:

• Cancel — write nothing
• Merge — update matched items, add only non-duplicates
• Proceed — create duplicates with override markers for auditing

4. Plan (Full Pipeline)

ndx plan .                  # analyze + generate proposals (interactive)
ndx plan --accept .         # analyze + auto-accept
ndx plan --file=spec.md .   # import from a document (skips analysis)

Combines analysis and proposal generation in one step. Use analyze + recommend for more control over each stage.

Baseline Detection

When scanning an existing codebase for the first time (empty PRD + existing code), the LLM automatically detects this as a baseline scan and marks:

• Completed — functionality that already exists in the code
• Pending — gaps, improvements, and missing features to build

This prevents a wall of "pending" tasks for code that's already implemented.

5. Execute

ndx work --auto .                          # highest-priority task
ndx work --auto --iterations=4 .           # 4 tasks sequentially
ndx work --epic="Auth System" --auto .     # scope to an epic
ndx work --task=abc123 .                   # specific task by ID

Hench picks a task, builds a brief with codebase context (relevant files, acceptance criteria, related code), runs an LLM tool-use loop to implement it, then records the run in .hench/runs/.

6. Self-Heal

ndx self-heal 3 .

Iterative improvement loop that runs N cycles of:

1. Re-analyze the codebase (ndx analyze)
2. Accept new actionable recommendations (ndx recommend --accept --actionable-only)
3. Execute tasks (ndx work --auto)
4. Acknowledge completed findings

See Self-Heal Loop for details on fuzzy acknowledgment and finding lifecycle.

7. Monitor

ndx status .                 # PRD tree with completion stats
ndx start .                  # web dashboard + MCP server
ndx start --background .     # daemon mode
ndx usage .                  # token usage analytics

Repeat

The typical development loop:

analyze → recommend → work → status → repeat

Or use self-heal to automate the entire cycle.

Skills used in this guide

Each skill below maps to a step in this loop. Edit the linked file in your project to customize that step's behavior in your assistant session.

Skill	Source	Role in this guide
/ndx-plan	.agents/skills/ndx-plan/SKILL.md	Steps 2–4: translates SourceVision findings into PRD proposals and accepts them
/ndx-capture	.agents/skills/ndx-capture/SKILL.md	Step 3: decomposes freeform ideas into structured PRD items with parent placement
/ndx-work	.agents/skills/ndx-work/SKILL.md	Step 5: picks the next task and drives an LLM tool-use loop to implement it
/ndx-status	.agents/skills/ndx-status/SKILL.md	Step 7: shows combined PRD completion, zone health, and next recommended action
/ndx-reshape	.agents/skills/ndx-reshape/SKILL.md	Structural cleanup: reparents, merges, and rebalances the PRD tree when hierarchy drifts

Related guides that share these skills: Spec-Driven Development, Codebase Onboarding, Run While You Sleep, Self-Heal Loop.

For the full skill inventory and customization guidance, see the Skills Reference.

See it on a real project

n-dx runs this loop on itself. Two artifacts in the repository show both ends of it:

• prd.md — the hand-written spec that seeded the project
• .rex/prd_tree/ — the live tree the agent reads from and writes back to

The PRD storage layout guide walks through how one becomes the other, and which commands and MCP tools you use to interact with the result.