DevNexus

DevNexus is a generic development orchestration core.

It owns project and work tracking, local work items, agent launch configuration, execution metadata, verification records, credential-aware forge integration, and publication handoff across language ecosystems.

A DevNexus project is a managed orchestration context containing one or more components. A component is the unit that points at a source root, optional Git remote, worktree root, work-item service, verification hints, publication hints, and relationships to other components. Component arity can be one or many; a project with one component follows the same model as a project with several components.

DevNexus is not the work-planning agent. It should not decide which work item to implement, supervise the implementation, or plan parallel worktrees itself. A user drives DevNexus by configuring projects, schedules, launch policies, and agent commands. A user can be a human or an agent acting under human instruction. DevNexus executes that infrastructure and schedule by launching a configured agent such as Codex or Claude in a prepared project context. The launched agent chooses the work item or items, creates and coordinates Git worktrees when useful, verifies the result, and reports commits, publication, blockers, and notes back through DevNexus-owned records. DevNexus can relaunch the agent while eligible work remains when the user has configured that behavior.

For example, a human can tell Codex to use DevNexus to work on a project until no eligible issue remains. In that flow, Codex is the user of DevNexus under human instruction; DevNexus supplies the configured launch gates, schedule, component context, relaunch loop, and run records.

Language, runtime, framework, and toolchain-specific behavior belongs in extensions. DevNexus provides the core contracts and extension hooks without depending on any specific specialization.

Project CLI

The package ships a generic dev-nexus CLI for initializing a DevNexus home and managing generic project roots:

dev-nexus home init <home-path>
dev-nexus project create <name> --home <home-path>
dev-nexus project import <source-root> --home <home-path> --name <name>
dev-nexus project list --home <home-path>
dev-nexus project status <project-id-or-root> --home <home-path>
dev-nexus project status <project-root>
dev-nexus project mcp refresh <project-root> --agent codex --agent claude
dev-nexus project tracker configure <project> --home <home-path> --provider local
dev-nexus project tracker link <project> --home <home-path> --tracker-project-id <id>
dev-nexus mcp-stdio

Commands that need a registry use --home; when it is omitted they fall back to DEV_NEXUS_HOME and then the default user home path. project status can also inspect an initialized project root directly without a home registry, which is useful for local smoke checks and generated worktrees.

Project Template Shape

The generic project scaffold separates project-owned support state from component source and local runtime records. A new or refreshed project writes a generated .dev-nexus/README.md that describes the active layout in the same terms used by the code:

Area	Typical paths	Owner
Component configuration	dev-nexus.project.json, component sourceRoot paths	User-authored source
Project state	.dev-nexus/README.md, component worktree roots under <worktreesRoot>/<component-id>/	Generated support or local runtime
Target state	automation.target.statePath, defaulting to .dev-nexus/automation/target-state.md	User-authored target memory, not overwritten by refresh
Skills	.dev-nexus/skills/, optional .agents/skills/ or .claude/skills/ projections	Generated from curated or extension skill definitions
Agent MCP projection	.codex/config.toml, .mcp.json, or configured agent target paths	Generated from mcp.agentTargets

Component worktree roots are component-scoped even when a project has one component, so arity one uses the same <worktreesRoot>/<component-id>/ shape as larger projects. Scaffold refreshes create missing component worktree directories and seed a missing target-state file when automation is configured, but existing target state is preserved.

Migration notes treat historical staging roots as migration-only evidence. Production templates should not inherit source-specific paths, tracker ids, component names, or launch commands from those roots. Generated support state may be refreshed by DevNexus, user-authored state records durable project intent, and local runtime state covers locks, ledgers, local tracker files, agent launch records, and generated worktrees.

MCP Server

DevNexus exposes a generic stdio Model Context Protocol (MCP) server for agents:

dev-nexus mcp-stdio

Agent configuration should register that command as a project-local MCP server when the agent needs direct DevNexus tools. The first native server slice intentionally covers the core self-use loop: read project status, read automation readiness and target context, and create/list/get/update/comment work items through the configured work tracker. It can also record caller-reported target cycle facts so the next launch can reason from durable state instead of chat memory, then build a factual target report from those records. It does not choose work or launch subagents itself; those decisions remain with the human or launched coordinator agent.

The native MCP tools are:

project_status
automation_status
eligible_work
agent_profiles
target_cycle_list
target_cycle_record
target_report
work_item_create
work_item_list
work_item_get
work_item_update
work_item_comment
work_item_set_status

Work-item tools accept componentId when a project has multiple component trackers. Omitting it preserves the compatibility behavior and uses the primary component.

Projects can still use the CLI for the same boundaries. The MCP server exists so agents can use DevNexus directly without depending on a specialization adapter for generic project orchestration.

Project-local agent configuration can be generated with:

dev-nexus project mcp refresh <project-root> --agent codex

or through project configuration:

{
  "mcp": {
    "agentTargets": [
      { "agent": "codex" },
      { "agent": "claude", "sourceControl": "source" }
    ]
  }
}

The Codex target writes or updates .codex/config.toml with a dev_nexus stdio server. The Claude target writes or updates project .mcp.json. Generated support config is excluded from Git by default; set sourceControl to source when the project should commit the agent MCP configuration.

Project Components

dev-nexus.project.json stores components as a first-class list. Each component has a stable id, display name, role, kind, source root, worktree root, optional work tracking configuration, optional verification and publication hints, and explicit relationships to other components.

The primary component is the compatibility anchor for legacy commands that can operate on only one component. New automation and project status surfaces expose all configured components, including each component's source root and whether that root exists. Components with work tracking also expose raw provider capability flags and an action-oriented workTrackingCapabilityReport so a coordinator agent can see whether a component tracker can list, create, get, update, comment, manage labels, manage assignees, use milestones, use a board, or update board status before choosing a workflow. boardStatus means a configured board or workflow status field can be synchronized; a provider can still update neutral item status without claiming board-status support. Component worktrees default under <project worktreesRoot>/<component-id> so arity one is not a special directory case.

Launched agents should treat each component as an independent source and tracking boundary. The launch context reports the component sourceRoot, worktreesRoot, Git defaults, relationships, and tracker capability flags so an agent can decide whether to work in the active checkout or create its own component worktree. When an agent takes work across components, it should keep branches and generated worktrees component-scoped, check for unrelated dirty state before editing, and report per-component progress through that component's work-item service. In agent_launch mode DevNexus does not create those implementation worktrees for the agent.

For parallel implementation work, coordinators should pick one component-owned work item, inspect that component's sourceRoot for unrelated dirty state, and then either work in that checkout or prepare a generated Git worktree under that component's worktreesRoot. Prepared worktree records carry the component id, source root, component worktrees root, generated worktree path, branch, base ref, and owning work item id/title. A generated path is valid only when it resolves inside the component worktreesRoot; path-like worktree names are rejected so a parallel branch cannot escape into another component's tree. Agents should write or update worktree execution metadata in the generated worktree as verification, commit, and publication facts become known.

Work tracking is component-scoped. Older project-level workTracking remains accepted for legacy configs and is normalized onto the generated primary component, but explicit multi-component configs should put the work-item service on the component that owns those items. A component can use a local store, GitHub Issues, GitHub Projects, GitLab issues, Jira, or another configured provider as those adapters become available.

CLI work-item commands accept --component <component-id> for component-owned trackers and default to the primary component when the option is omitted.

Example:

{
  "version": 1,
  "id": "example-suite",
  "name": "Example Suite",
  "repo": {
    "kind": "local",
    "remoteUrl": null,
    "defaultBranch": null
  },
  "components": [
    {
      "id": "core",
      "name": "Core",
      "kind": "git",
      "role": "primary",
      "remoteUrl": "git@example.invalid:example/core.git",
      "defaultBranch": "main",
      "sourceRoot": "components/core",
      "workTracking": {
        "provider": "github",
        "repository": {
          "owner": "example",
          "name": "core"
        }
      },
      "relationships": []
    },
    {
      "id": "addon",
      "name": "Addon",
      "kind": "git",
      "role": "addon",
      "remoteUrl": "git@example.invalid:example/addon.git",
      "defaultBranch": "main",
      "sourceRoot": "components/addon",
      "workTracking": {
        "provider": "jira",
        "host": "example.atlassian.net",
        "projectKey": "ADDON"
      },
      "relationships": [
        {
          "kind": "extends",
          "componentId": "core"
        }
      ]
    }
  ],
  "worktreesRoot": "worktrees",
  "kanban": {
    "provider": "vibe-kanban",
    "projectId": null
  }
}

Automation Foundation

Projects can opt into generic agent-launch automation through dev-nexus.project.json. The core schema covers user-configured launch gates, verification hints, run ledgers, stale-aware locks, retry backoff, safety policy, and publication policy. These APIs model launch state and record what the agent reports; execution adapters decide how to start agents and tools for a project.

The configured automation selector is a user-authored launch gate and context filter. It can decide whether the user's configured conditions for launching an agent are met, but it is not a mandate for DevNexus to choose the task. The launched agent must inspect the tracker context, choose the work item or items to take, decide whether parallel Git worktrees are useful, and supervise implementation through verification and publication.

automation.mode: "agent_launch" uses the launch-only boundary. DevNexus checks the selector as an eligibility gate, writes an agent context file under the project .dev-nexus/automation state directory, starts the configured agent command, and records the result reported by the agent. The agent receives DEV_NEXUS_AGENT_CONTEXT_FILE and DEV_NEXUS_AGENT_RESULT_FILE. A successful agent command must write valid JSON to that result path before exiting; otherwise DevNexus records the launch as failed. The required fields are status and summary. Optional fields are commitIds, verification, publicationDecision, and error. The context also carries a result contract with the exact result file path, required fields, optional fields, allowed launch statuses, verification statuses, and publication decision types. The same required and optional field lists are exposed in DEV_NEXUS_AGENT_RESULT_REQUIRED_FIELDS and DEV_NEXUS_AGENT_RESULT_OPTIONAL_FIELDS.

{
  "status": "completed",
  "summary": "Agent reported completion",
  "commitIds": [],
  "verification": [],
  "publicationDecision": {
    "type": "direct_integration",
    "remote": "origin",
    "targetBranch": "main",
    "reason": "Published verified source change."
  },
  "error": null
}

The agent context includes components and componentEligibleWorkItems. DevNexus groups eligible work items by component and does not collapse that grouping into a decision. The launched agent can then decide which component work items to take, how many subagents to launch, what model and reasoning profile each subagent should use, and how to report progress back to each component's work-item service.

The same context also includes the configured automation target and agent policy. automation.target carries the user-requested objective, the project-relative target-state Markdown file, optional cycle and work-item bounds, and the stop condition for no remaining eligible work. Agents should keep that target-state file concise: retain current direction, active decisions, blockers, and near-term risks, and drop stale detail as the target evolves. automation.agent.maxConcurrentSubagents caps parallel subagent work, and automation.agent.profiles names the executor/model/version or variant/reasoning or intelligence/safety profiles that a launched agent may assign to subagents. automation.agent.coordinatorProfileId may name one of those profiles as the coordinator launch profile. A profile can carry command and args; DevNexus uses that executable template when no raw automation.agent.command or CLI --command override is provided. A coordinator profile must be launch-capable: its intendedUse must be coordinator or any, and it must include a command when it is selected by coordinatorProfileId. intendedUse defaults to any for existing profile configs. Profile safety overrides the project automation safety posture for that profile only; otherwise profiles inherit automation.safety. The profile and subagent cap settings still describe infrastructure policy. DevNexus exposes the normalized policy to the launched coordinator, but the coordinator remains responsible for reading the context, choosing work, assigning subagent profiles, and reporting facts back to DevNexus.

automation.target.cycleLedgerPath stores the target cycle ledger, defaulting to .dev-nexus/automation/target-cycles.json. A launched coordinator agent can record started, dispatched, completed, blocked, failed, or skipped cycle facts through target_cycle_record or the CLI. These records are factual caller reports: DevNexus stores the run id, target id, component work item refs, per-item progress states, agent profile ids, bounded notes, blockers, and summary, but it still does not decide which work should be selected or supervise subagents. Work item progress states can be selected, dispatched, in_progress, completed, blocked, or skipped; item and cycle notes are capped at 1000 characters each so the durable ledger stays concise. automation status reads the same ledger and exposes cycle counts plus the latest cycle.

target_report and automation target-report build read-only factual JSON from the target context, target cycle ledger, automation run ledger, recorded work item refs, blockers, and notes. The report status is derived from the latest recorded target cycle when present, otherwise the latest automation run. The report also includes a relaunchDecision field with one of relaunch, stop, wait, report_blocked, report_failed, or not_ready, based on the latest recorded cycle status, recorded eligible work count, target stop policy, and relaunch policy. It is intended for final user reporting and relaunch decisions by a human or coordinator agent. It avoids live external tracker calls, may read configured local work-item stores to fill missing titles/statuses, and does not infer hidden work state. Component progress, active blockers, commits, verification records, and publication decisions are summarized only from durable cycle/run facts and locally recorded work-item state.

runNexusAutomationOnce remains available for older local command smokes that prepare one generated worktree and run automation.executor.command. That selected-work path is interim. New automation work should prefer runNexusAutomationAgentLaunchOnce: DevNexus prepares safe context, starts the configured agent when the user-requested or scheduled launch policy fires, can relaunch while eligible work remains when the user has configured that behavior, and records the agent's reported result.

Generated worktrees can declare setup-only dependency links through automation.setup.dependencyLinks. Each link copies no package data and runs no installer; it only links an existing reviewed path from the active component source root into the generated worktree and records the target in the worktree Git exclude file. Required links are checked during read-only status so unsafe or missing dependencies block before worktree creation.

Dependency-link setup also treats the component worktrees root as a safety boundary when provided: the target worktree path must remain inside that root before any link is created. This keeps shared dependencies scoped to the component worktree that the coordinator selected.

The package also ships a generic dev-nexus CLI for the same boundary:

dev-nexus automation eligible-work <project-root> --json
dev-nexus automation agent-profiles <project-root> --json
dev-nexus automation target-report <project-root> --json
dev-nexus work-item update <project-root> local-1 --component core --status in_progress
dev-nexus work-item comment <project-root> local-1 --component core --body "Started focused verification."
dev-nexus automation target-cycle record <project-root> --status completed --work-item core:local-1 --eligible-work-items 0
dev-nexus automation target-cycle record <project-root> --status dispatched --work-item core:local-1 --work-item-status dispatched --work-item-agent-profile codex-local --work-item-note "Subagent launched."
dev-nexus work-item create <project-root> --title "Implement task" --status ready --label automation
dev-nexus work-item list <project-root> --status ready
dev-nexus work-item get <project-root> local-1
dev-nexus work-item update <project-root> local-1 --status in_progress
dev-nexus work-item comment <project-root> local-1 --body "Started focused verification."
dev-nexus automation status <project-root>
dev-nexus automation enqueue <project-root> --title "Implement task"
dev-nexus automation target-cycle record <project-root> --status dispatched --work-item primary:local-1
dev-nexus automation target-cycle list <project-root>
dev-nexus automation target-report <project-root> --json
dev-nexus automation run-once <project-root> --command "codex exec <prompt-or-script>"
dev-nexus automation schedule <project-root> --command "codex exec <prompt-or-script>" --max-runs 1

For automation target-cycle record, --work-item-status, --work-item-agent-profile, and --work-item-note apply to the most recent --work-item argument. They record what the coordinator reports; DevNexus does not assign profiles, launch implementation subagents, or supervise their work.

For a low-token coordinator cycle, start with automation eligible-work --json and automation agent-profiles --json, then use component-scoped work-item and target-cycle commands to record the work the coordinator chose. The full automation status --json remains available when the agent needs the complete target context.

Projects can also store the shell command under automation.agent.command for agent-launch mode or automation.executor.command for the older generated worktree executor mode. For agent-launch mode, projects may instead set automation.agent.coordinatorProfileId to a profile with command and args. automation run-once and automation schedule may omit --command when the relevant command source is configured. Command-line options still override the configured command and timeout.

Profile selection is infrastructure policy, not work supervision. A coordinator may use automation.agent.profiles and automation.agent.maxConcurrentSubagents to decide how many subagents to run and which executor/model/safety profile each one should receive, but DevNexus does not select the work item batch or supervise subagent execution.

Manual work-item commands accept --component <component-id> for component-owned work-item services. Omitting it targets the primary component for compatibility. Agent-launch automation reads eligible work across all configured component services.

automation status is read-only. It reports whether automation is disabled, locked, in retry backoff, blocked by preflight, idle, or ready to launch an agent under the user-configured launch policy before any worktree or tracker mutation happens.

automation enqueue creates a work item that matches the configured automation launch filter. It derives the default status, labels, and assignees from automation.selector, lets callers add extra labels or assignees, and refuses inputs that would be invisible to the configured agent-launch loop.

automation run-once runs the configured command with DEV_NEXUS_* environment variables for project context and writes the retained run ledger. In agent-launch mode, no work item is selected and no generated worktree is prepared by DevNexus; the target command launches an agent with enough context to make its own work-selection and supervision decisions.

automation schedule repeatedly checks the same read-only status boundary and dispatches automation run-once only when the project is ready. It honors project automation.schedule.intervalMs, waits until active locks or retry backoff expire, and supports --max-ticks or --max-runs for bounded local smokes and supervised runners.

Curated Skills

DevNexus keeps reviewed skill definitions under its managed project support directory, .dev-nexus/skills, as DevNexus-owned state. That directory is not the agent-facing install location. Projects can also configure skills.agentTargets so DevNexus projects selected skills into agent-native directories:

• codex -> .agents/skills/<skill-id>/SKILL.md
• claude -> .claude/skills/<skill-id>/SKILL.md

This keeps DevNexus responsible for curated, pinned skill material while the configured agents load skills from the locations they actually understand. The default core pack includes:

• diagnose
• tdd for Test-Driven Development (TDD)
• handoff
• triage
• architecture-review
• setup-agent-skills
• grill-with-docs
• to-issues
• to-prd for Product Requirements Document (PRD) synthesis
• prototype
• zoom-out
• architecture-deepening

Curated skills must use explicit terminology. Acronyms such as Product Requirements Document (PRD), Architecture Decision Record (ADR), human-in-the-loop (HITL), and autonomous agent-ready (AFK) must be expanded where they appear so generated guidance is understandable without external context.

For DevNexus dogfooding, to-issues is the intended bridge from a target plan to tracker-backed execution. A human or launched agent can use the skill to split the current target plan into component-owned issues, mark which issues are autonomous agent-ready (AFK), and then let DevNexus relaunch agents while eligible work remains under the configured target and subagent caps.