DX-APP Agent-Driven Development Guide

Overview

DX-APP supports DEEPX agent-driven development (dx-agent-dev) for building standalone inference applications on DEEPX NPU accelerators. Instead of manually writing boilerplate, you describe what you want in natural language and a network of specialized agents generates production-ready inference code, validates it, and reports results.

This guide covers the agent architecture, available skills, the validation framework, and troubleshooting for dx_app standalone inference development.

---

Agent Architecture

Six agents collaborate to build, validate, and manage dx_app inference applications.

Agent	Description	Routes To
dx-app-builder	Master router — classifies request type and dispatches to specialist agent	dx-python-builder dx-cpp-builder dx-benchmark-builder dx-model-manager
dx-python-builder	Builds Python inference apps in 4 variants: sync, async, sync_cpp_postprocess, async_cpp_postprocess (Sub-agent — invoked by dx-app-builder)	—
dx-cpp-builder	Builds C++ inference apps using the InferenceEngine API (Sub-agent — invoked by dx-app-builder)	—
dx-benchmark-builder	Benchmarks and profiles inference performance on target hardware (Sub-agent — invoked by dx-app-builder)	—
dx-model-manager	Downloads, registers, and manages .dxnn compiled models (Sub-agent — invoked by dx-app-builder)	—
dx-validator	Validates generated app code and .deepx/ framework integrity	—

Routing Flow

User Request
    │
    ▼
dx-app-builder  (classifies intent)
    │
    ├──► dx-python-builder    (Python inference app)
    ├──► dx-cpp-builder       (C++ inference app)
    ├──► dx-benchmark-builder (performance profiling)
    └──► dx-model-manager     (model operations)
            │
            ▼
      dx-validator  (called automatically after generation)

---

Skills

Skills encapsulate reusable workflows that agents invoke during code generation.

General SWE Process

Skill	Description
dx-swe-brainstorm	Brainstorm and plan before any code generation
dx-swe-tdd	Test-driven development — validate each file immediately after creation
dx-swe-verify	Verify before claiming completion — evidence before assertions
dx-swe-writing-plans	Write structured implementation plans before touching code
dx-swe-executing-plans	Execute a written implementation plan with review checkpoints
dx-swe-debugging	Systematic debugging — diagnose before proposing fixes
dx-swe-parallel-agents	Dispatch 2+ independent tasks to parallel agents
dx-swe-subagent-dev	Execute implementation plans with independent sub-agents
dx-swe-receiving-review	Receive and process code review feedback with technical rigor
dx-swe-requesting-review	Request code review to verify work meets requirements
dx-skill-router	Route tasks to the appropriate skill automatically

DEEPX Build

Skill	Description
dx-agent-app-build-python	Build a Python inference app in any of the 4 variants using the IFactory pattern
dx-agent-app-build-cpp	Build a C++ inference app with the InferenceEngine runtime API
dx-agent-app-build-async	Build an async high-performance app with pipelined pre/infer/post stages
dx-agent-app-model-management	Download .dxnn models from the registry and configure model paths
dx-agent-app-validate	Run the 5-level validation pyramid against generated code

---

Supported AI Tools

dx_app agent-driven development works with four AI coding tools. Each auto-loads the knowledge base through its own configuration.

Tool	Config Files	Agents Available
Claude Code	CLAUDE.md	All 6 agents via context routing
GitHub Copilot	.github/copilot-instructions.md 6 agents in .github/agents/ 17 skills in .github/skills/ 4 instructions in .github/instructions/	@dx-app-builder, @dx-python-builder, @dx-cpp-builder, @dx-benchmark-builder, @dx-model-manager, @dx-validator
Cursor	.cursor/rules/dx-app.mdc (always) 6 agent rules + 17 skill rules python-example.mdc, cpp-example.mdc, tests.mdc (27 total)	Free-form with auto-applied rules
OpenCode	AGENTS.md, opencode.json 6 agents in .opencode/agents/ 17 skills in .deepx/skills/	@dx-app-builder or /dx-agent-app-build-python

Copilot File-Specific Instructions

When editing files matching these globs, Copilot automatically injects context-specific instructions:

Glob Pattern	Injected Instruction	Content
src/python_example/**	python-example.instructions.md	IFactory pattern, SyncRunner/AsyncRunner usage, 4-variant naming
src/cpp_example/**	cpp-example.instructions.md	C++14 standard, RAII patterns, InferenceEngine API
src/postprocess/**	postprocess.instructions.md	Postprocessing conventions, pybind bindings
tests/**	tests.instructions.md	pytest patterns, fixtures, NPU markers

OpenCode Skills (Slash Commands)

General SWE Process

Slash Command	Description
/dx-swe-brainstorm	Brainstorm and plan before code generation
/dx-swe-tdd	Test-driven development with incremental validation
/dx-swe-verify	Verify completion with evidence before assertions
/dx-swe-writing-plans	Write structured implementation plans
/dx-swe-executing-plans	Execute implementation plans with review checkpoints
/dx-swe-debugging	Systematic debugging — diagnose before fixing
/dx-swe-parallel-agents	Dispatch independent tasks to parallel agents
/dx-swe-subagent-dev	Execute plans with independent sub-agents
/dx-swe-receiving-review	Receive code review feedback with technical rigor
/dx-swe-requesting-review	Request code review to verify work
/dx-skill-router	Route tasks to the appropriate skill

DEEPX Build

Slash Command	Description
/dx-agent-app-build-python	Step-by-step Python app generation with IFactory
/dx-agent-app-build-cpp	C++ app with InferenceEngine
/dx-agent-app-build-async	Async high-performance app
/dx-agent-app-model-management	Model download and registry
/dx-agent-app-validate	Run the 5-level validation pyramid

Platform File Loading Reference

Each AI coding agent auto-loads different configuration files at the dx_app level.

Auto-Loaded Files

File	Auto-loaded by	Loading
.github/copilot-instructions.md	Copilot Chat/CLI	Auto
CLAUDE.md	Claude Code	Auto
AGENTS.md + opencode.json	OpenCode	Auto
AGENTS.md + .codex/skills/dx-codex-identity/SKILL.md	Codex CLI	Auto
.cursor/rules/dx-app.mdc	Cursor	Auto
.cursor/rules/python-example.mdc	Cursor	Auto (glob)
.cursor/rules/cpp-example.mdc	Cursor	Auto (glob)
.cursor/rules/tests.mdc	Cursor	Auto (glob)

Agent Files (Manual @mention)

Agent	Copilot (@mention)	OpenCode (@mention)	Claude Code (.claude/agents/)
dx-app-builder	.github/agents/ dx-app-builder.agent.md	.opencode/agents/ dx-app-builder.md	.claude/agents/ dx-app-builder.md
dx-python-builder	.github/agents/ dx-python-builder.agent.md	.opencode/agents/ dx-python-builder.md	.claude/agents/ dx-python-builder.md
dx-cpp-builder	.github/agents/ dx-cpp-builder.agent.md	.opencode/agents/ dx-cpp-builder.md	.claude/agents/ dx-cpp-builder.md
dx-benchmark-builder	.github/agents/ dx-benchmark-builder.agent.md	.opencode/agents/ dx-benchmark-builder.md	.claude/agents/ dx-benchmark-builder.md
dx-model-manager	.github/agents/ dx-model-manager.agent.md	.opencode/agents/ dx-model-manager.md	.claude/agents/ dx-model-manager.md
dx-validator	.github/agents/ dx-validator.agent.md	.opencode/agents/ dx-validator.md	.claude/agents/ dx-validator.md

Copilot File-Specific Instructions

File	Scope
.github/instructions/python-example.instructions.md	Python example files
.github/instructions/cpp-example.instructions.md	C++ example files
.github/instructions/postprocess.instructions.md	Postprocess files
.github/instructions/tests.instructions.md	Test files

Skill Files (All Platforms — /slash-command)

Skill	File
/dx-swe-brainstorm	.deepx/skills/dx-swe-brainstorm/SKILL.md
/dx-agent-app-build-async	.deepx/skills/dx-agent-app-build-async/SKILL.md
/dx-agent-app-build-cpp	.deepx/skills/dx-agent-app-build-cpp/SKILL.md
/dx-agent-app-build-python	.deepx/skills/dx-agent-app-build-python/SKILL.md
/dx-swe-parallel-agents	.deepx/skills/dx-swe-parallel-agents/SKILL.md
/dx-swe-executing-plans	.deepx/skills/dx-swe-executing-plans/SKILL.md
/dx-agent-app-model-management	.deepx/skills/dx-agent-app-model-management/SKILL.md
/dx-swe-receiving-review	.deepx/skills/dx-swe-receiving-review/SKILL.md
/dx-swe-requesting-review	.deepx/skills/dx-swe-requesting-review/SKILL.md
/dx-skill-router	.deepx/skills/dx-skill-router/SKILL.md
/dx-swe-subagent-dev	.deepx/skills/dx-swe-subagent-dev/SKILL.md
/dx-swe-debugging	.deepx/skills/dx-swe-debugging/SKILL.md
/dx-swe-tdd	.deepx/skills/dx-swe-tdd/SKILL.md
/dx-agent-app-validate	.deepx/skills/dx-validate/SKILL.md
/dx-swe-verify	.deepx/skills/dx-swe-verify/SKILL.md
/dx-swe-writing-plans	.deepx/skills/dx-swe-writing-plans/SKILL.md

Shared Knowledge Base (.deepx/)

The .deepx/ directory is the canonical source of truth for all agent knowledge. Platform-specific files (.github/, .cursor/, .opencode/) are generated from .deepx/ by dx-agent-gen generate --repo dx-runtime/dx_app. It is NOT auto-loaded — agents and skills reference specific files as needed during task execution.

Directory	Files	Description
.deepx/agents/	6 files (dx-app-builder.md, dx-python-builder.md, dx-cpp-builder.md, dx-benchmark-builder.md, dx-model-manager.md, dx-validator.md)	Authoritative agent definitions
.deepx/skills/	17 directories	Detailed skill workflows (one SKILL.md per directory)
.deepx/templates/	Template files	Code generation templates
.deepx/knowledge/	Knowledge files	Domain-specific reference material
.deepx/toolsets/	5 files	API references and schema documentation
.deepx/instructions/	6 files	Coding standards and workflow rules
.deepx/memory/	5 files	Persistent knowledge — pitfalls and session memory
.deepx/contextual-rules/	4 files	Context-dependent rules activated by task type

---

User Scenarios

Scenario 1: Build a Python Detection App

Prompt:

"Build a yolo26n person detection app using Python"

Tool	How to Use
Claude Code	Type the prompt directly. CLAUDE.md routes to dx-agent-app-build-python skill. Asks 2-3 questions (variant, task type, model), generates files in dx-agent-dev/<session_id>/ (or src/... if explicitly requested), and validates.
GitHub Copilot	@dx-app-builder followed by the prompt. Routes to dx-python-builder, generates all 4 variants, runs dx-validator.
Cursor	Type the prompt directly. dx-app.mdc (always loaded) provides context. python-example.mdc activates for src/python_example/ files.
OpenCode	@dx-app-builder followed by the prompt, or /dx-agent-app-build-python skill directly.

Scenario 2: Build a C++ App

Prompt:

"Build a C++ inference app for yolo26n using InferenceEngine"

Tool	How to Use
Claude Code	Type the prompt directly. Routes to dx-agent-app-build-cpp skill.
GitHub Copilot	@dx-cpp-builder followed by the prompt.
Cursor	Type the prompt directly. cpp-example.mdc activates for src/cpp_example/ files, injecting C++14 and RAII conventions.
OpenCode	@dx-app-builder followed by the prompt, or /dx-agent-app-build-cpp skill directly.

Scenario 3: Download and Register a Model

Prompt:

"Download yolo26n model for DX-M1"

Tool	How to Use
Claude Code	@dx-model-manager followed by the prompt.
GitHub Copilot	@dx-model-manager followed by the prompt.
Cursor	Type the prompt directly.
OpenCode	@dx-model-manager followed by the prompt, or /dx-agent-app-model-management skill.

Scenario 4: Validate Generated Code

Prompt:

"Validate the detection app I just created"

Tool	How to Use
Claude Code	@dx-validator followed by the prompt.
GitHub Copilot	@dx-validator followed by the prompt.
Cursor	Type the prompt directly.
OpenCode	@dx-validator followed by the prompt, or run manually: python .deepx/scripts/validate_app.py src/python_example/object_detection/yolo26n/

Scenario 5: Build a Pose Estimation App

Prompt:

"Build a pose estimation app with yolo26n-pose"

Tool	How to Use
Claude Code	Type the prompt directly. Routes to dx-agent-app-build-python skill with pose_estimation task type. Generates keypoint visualization and skeleton drawing logic.
GitHub Copilot	@dx-app-builder followed by the prompt. Routes to dx-python-builder with pose-specific postprocessing.
Cursor	Type the prompt directly. python-example.mdc activates for generated files in src/python_example/pose_estimation/.
OpenCode	@dx-app-builder followed by the prompt, or /dx-agent-app-build-python skill directly.

Scenario 6: Build an Instance Segmentation App

Prompt:

"Build an instance segmentation app with yolo26n-seg"

Tool	How to Use
Claude Code	Type the prompt directly. Routes to dx-agent-app-build-python skill with instance_segmentation task type. Generates mask overlay visualization.
GitHub Copilot	@dx-app-builder followed by the prompt. Routes to dx-python-builder with segmentation-specific postprocessing.
Cursor	Type the prompt directly. python-example.mdc activates for generated files in src/python_example/instance_segmentation/.
OpenCode	@dx-app-builder followed by the prompt, or /dx-agent-app-build-python skill directly.

Scenario 7: Build a Classification App

Prompt:

"Build an image classification app with EfficientNet-B0"

Tool	How to Use
Claude Code	Type the prompt directly. Routes to dx-agent-app-build-python skill with classification task type. Generates top-K label prediction logic.
GitHub Copilot	@dx-app-builder followed by the prompt. Routes to dx-python-builder with classification postprocessing (softmax + top-K).
Cursor	Type the prompt directly. python-example.mdc activates for generated files in src/python_example/classification/.
OpenCode	@dx-app-builder followed by the prompt, or /dx-agent-app-build-python skill directly.

Scenario 8: Build an Async High-Performance App

Prompt:

"Build an async high-performance detection app with yolo26n"

Tool	How to Use
Claude Code	Type the prompt directly. Routes to dx-agent-app-build-async skill. Generates pipelined pre/infer/post stages with queue-based parallelism.
GitHub Copilot	@dx-app-builder followed by the prompt. Routes to dx-python-builder with async variant focus.
Cursor	Type the prompt directly. python-example.mdc activates for generated async files.
OpenCode	@dx-app-builder followed by the prompt, or /dx-agent-app-build-async skill directly.

---

Quick Start

Request a person detection app in natural language:

@dx-app-builder "Build a Python person detection app using yolo26n"

The agent will:

1. Ask clarifying questions — variant (sync / async), model precision, task type (detection, classification, segmentation, etc.)
2. Present a build plan — list of files to generate, model to download, config to write
3. Route to dx-python-builder — the specialist agent takes over
4. Generate files in dx-agent-dev/<session_id>/ (or src/ if explicitly requested)
5. Validate and report — dx-validator runs checks and prints a summary

Mandatory Questions (HARD-GATE)

When using @dx-app-builder, the agent enforces 3 mandatory questions before generating any code:

1. Language/variant: Python (sync / async / cpp_postprocess / async_cpp_postprocess) or C++?
2. AI task: detection, classification, segmentation, pose, etc.
3. Model: Specific model name (e.g., yolo26n) or auto-recommend

These questions are non-skippable — even if your prompt provides enough context, the agent will confirm each decision explicitly before proceeding.

---

What Gets Created

By default, agent-generated code is placed in the dx-agent-dev/ isolation directory to prevent conflicts with existing source code.

Default Output (dx-agent-dev/)

dx-agent-dev/<session_id>/
├── README.md              # Session metadata and run instructions
├── session.json           # Machine-readable session config
├── setup.sh               # Environment setup script (mandatory)
├── run.sh                 # App launch script (mandatory)
├── session.log            # Agent session log (mandatory)
└── src/python_example/{task}/{model}/
    ├── __init__.py
    ├── config.json
    ├── {model}_factory.py
    ├── {model}_sync.py
    ├── {model}_async.py
    ├── {model}_sync_cpp_postprocess.py
    └── {model}_async_cpp_postprocess.py

Session ID format: YYYYMMDD-HHMMSS_<agent>_<model>_<task> where <agent> is claude, copilot, cursor, or opencode (e.g., 20260403-143022_claude_yolo26n_detection).

Production Output (src/)

When you explicitly request production placement, files are written directly to src/python_example/{task}/{model}/ — the standard source tree.

File Descriptions

File	Purpose
config.json	Model path, task type, input dimensions, label map
{model}_factory.py	Implements IFactory — the 5-method interface for pre/post processing
{model}_sync.py	Synchronous single-threaded inference entry point
{model}_async.py	Asynchronous pipelined inference entry point
{model}_sync_cpp_postprocess.py	Sync inference with C++ post-processing via pybind
{model}_async_cpp_postprocess.py	Async inference with C++ post-processing via pybind

NOTE

setup.sh, run.sh, and session.log are mandatory artifacts in every session output directory

---

5-Level Validation Pyramid

dx-validator applies checks in ascending order of cost. Each level gates the next.

        ▲
       /5\       Performance benchmarks (FPS targets)
      /───\
     / 4   \     NPU integration tests (requires hardware)
    /───────\
   /   3     \   Smoke tests (--help, module import)
  /───────────\
 /     2       \ Config validation (model paths, task types)
/───────────────\
       1         Static checks (imports, naming, structure)

Level	What It Checks	Requires Hardware
1 — Static	Absolute imports, naming conventions, file structure, IFactory methods	No
2 — Config	config.json schema, .dxnn model path resolution, valid task types	No
3 — Smoke	--help flag runs without error, modules import cleanly	No
4 — NPU Integration	End-to-end inference on a sample image with NPU present	Yes
5 — Performance	FPS meets target thresholds for the model and accelerator	Yes

---

Validation Commands

 # Static checks (11 checks across Level 1 and Level 2)
python .deepx/scripts/validate_app.py src/python_example/{task}/{model}/

 # Include smoke tests (Levels 1–3)
python .deepx/scripts/validate_app.py src/python_example/{task}/{model}/ --smoke-test

 # Framework integrity — verify .deepx/ directory structure
python .deepx/scripts/validate_framework.py

---

Knowledge Base Structure

Agent knowledge lives in the .deepx/ directory at the dx_app project root.

Directory	Count	Contents
agents/	6	Agent definitions and routing rules
skills/	17	Skill workflow directories (one SKILL.md each)
templates/	—	Code generation templates
knowledge/	—	Domain-specific reference material
toolsets/	5	API references (InferenceEngine, IFactory, dxrt-cli, model registry, pybind helpers)
memory/	5	Persistent knowledge (common pitfalls, platform API notes, optimization patterns, camera/display notes, model config cache)
contextual-rules/	4	Coding standards, import rules, naming conventions, directory layout rules
prompts/	4	System prompts for each specialist agent
scripts/	2	validate_app.py, validate_framework.py

NOTE

Platform files (.github/, .cursor/, .opencode/, CLAUDE.md, AGENTS.md) are generated by dx-agent-gen generate --repo dx-runtime/dx_app. Do not edit them directly. Edit .deepx/ source files and re-run the generator. A pre-commit hook runs dx-agent-gen automatically.

Agents read from these directories at task start. Memory files are updated when new patterns or fixes are discovered during development.

---

Session Sentinels

Agents output fixed markers at the start and end of each task for automated testing:

Marker	When
[DX-AGENT-DEV: START]	First line of the agent's response
[DX-AGENT-DEV: DONE (output-dir: <relative_path>)]	Last line after all work is complete. <relative_path> is the session output directory relative to the project root. If no files were generated, omit the (output-dir: ...) part.

Sub-agents invoked via handoff do not output sentinels — only the top-level agent does.

Rules:

1. CRITICAL — Output [DX-AGENT-DEV: START] as the absolute first line of the first response, before any other text. This is non-negotiable even if the user says to proceed autonomously.
2. Output [DX-AGENT-DEV: DONE (output-dir: <path>)] as the very last line after all work, validation, and file generation is complete.
3. If you are a sub-agent invoked via handoff/routing, do NOT output sentinels — only the top-level agent outputs them.
4. If the user sends multiple prompts in a session, output START/DONE for each prompt.
5. The output-dir in DONE must be the relative path from the project root to the session output directory.
6. Never output DONE after only producing planning artifacts (specs, plans, design documents). DONE means all deliverables are produced — implementation code, scripts, configs, and validation results.

---

Troubleshooting

• Problem: Agent writes relative imports (from .factory import ...)
  Cause: Default LLM behavior
  Solution: Use absolute imports only.
  Example: from dx_app.python_example.detection.yolo26n.yolo26n_factory import ...

• Problem: Factory class missing methods
  Cause: Incomplete IFactory implementation
  Solution: Implement all 5 required methods:
  create_preprocessor, create_postprocessor, create_label_map, create_input_config, create_visualizer

• Problem: Model not found at runtime
  Cause: .dxnn file path not registered
  Solution: Query model_registry.json via dx-model-manager to download and register the model.

• Problem: NPU not available / device error
  Cause: Accelerator not detected by driver
  Solution: Run dxrt-cli -s to check device status and verify the DEEPX kernel module is loaded.

• Problem: validate_app.py fails immediately
  Cause: Python path or venv not configured
  Solution: Activate the dx_app virtual environment and ensure PYTHONPATH includes the project root.

---

Further Reading

• DX-APP Project Overview
• DX-APP Python Example Usage Guide
• DX-APP C++ Example Usage Guide
• DX-APP Example Source Structure