Waishnav · Waishnav · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/README.md b/README.md
@@ -184,6 +184,7 @@ devspace doctor
 
 - [Setup Guide](https://github.com/Waishnav/devspace/blob/main/docs/setup.md)
 - [ChatGPT Coding Workflow](https://github.com/Waishnav/devspace/blob/main/docs/chatgpt-coding-workflow.md)
+- [Subagents and Dynamic Workflows](https://github.com/Waishnav/devspace/blob/main/docs/dynamic-workflows.md)
 - [Configuration Reference](https://github.com/Waishnav/devspace/blob/main/docs/configuration.md)
 - [Native File Download](https://github.com/Waishnav/devspace/blob/main/docs/artifact-exchange.md)
 - [Security Model](https://github.com/Waishnav/devspace/blob/main/docs/security.md)

diff --git a/docs/agent-profile-schema.md b/docs/agent-profile-schema.md
@@ -145,16 +145,40 @@ Recommended body content:
 
 ## Model-facing workflow
 
-The Subagent skill teaches only:
+The Subagent skill uses the default compact XML fragments:
 
 ```bash
-devspace agents ls --json
-devspace agents targets --json
-devspace agents run <profile-or-provider> "<prompt>" --json
-devspace agents continue <id> "<prompt>" --json
-devspace agents show <id> --json
+devspace agents targets
+devspace agents ls
+devspace agents run <profile-or-provider> "<prompt>"
+devspace agents continue <id> "<prompt>"
+devspace agents show <id>
+devspace agents wait <id>...
 ```
 
+The commands do not add a document-level wrapper. `targets`, `ls`, and `wait`
+print one fragment per item and print nothing for an empty list. This keeps the
+model-facing result small:
+
+```xml
+<provider name="codex" model="gpt-5.4" effort="high"/>
+<profile name="reviewer" provider="codex">Read-only code review.</profile>
+<agent id="agt_123" status="running"/>
+<agent id="agt_123" status="completed">Review complete.</agent>
+<agent id="agt_456" status="failed" code="PROVIDER_EXECUTION_ERROR" retryable="true">Provider disconnected.</agent>
+<error code="AGENT_NOT_FOUND" retryable="false" agent-id="agt_missing">Subagent not found.</error>
+```
+
+`show` returns an immediate snapshot. `wait` accepts one or more agent IDs and
+waits for all of their current work. It does not stream fragments as individual
+agents finish. With `--timeout <seconds>`, it returns each unique agent in
+first-seen order and marks unfinished work with `status="running"
+wait="timeout"`.
+
+`--json` remains available for scripts that need it, but the bundled skill does
+not request it. Internal turn records, prompts, provider session IDs, workspace
+paths, and timestamps are absent from both output formats.
+
 `open_workspace` exposes compact profile metadata:
 
 ```json

diff --git a/docs/chatgpt-coding-workflow.md b/docs/chatgpt-coding-workflow.md
@@ -144,7 +144,8 @@ Set `skills.enabled` to `false` to hide skills from workspace output. Enable
 Subagents and choose providers through `devspace init` or the persisted provider
 configuration. The bundled `subagents` skill teaches the minimal
 `devspace agents targets`, `devspace agents ls`, `devspace agents run`,
-`devspace agents continue`, and `devspace agents show` workflow. The catalog
+`devspace agents continue`, `devspace agents show`, and `devspace agents wait`
+workflow. The catalog
 comes from `open_workspace`; `devspace agents ls` lists existing subagent
 sessions for that workspace.
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -115,6 +115,11 @@ Subagent providers are explicit. Omitted providers are disabled:
         "enabled": true,
         "model": "gpt-5.4",
         "effort": "high",
+        "command": "/opt/devspace/bin/codex-wrapper",
+        "env": {
+          "CODEX_HOME": "/home/alice/.codex-work",
+          "OPENAI_BASE_URL": "https://api.example.com/v1",
+        },
       },
       {
         "id": "claude",
@@ -130,10 +135,26 @@ Profiles are loaded from `~/.devspace/agents/*.md` and project
 `.devspace/agents/*.md`. `devspace agents targets` prints the configured targets
 available in the current workspace.
 
-Provider executable discovery remains process-scoped. The supported overrides
-are `CODEX_COMMAND`, `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`,
-`COPILOT_COMMAND`, `GROK_COMMAND`, and `GROK_AGENT_PROFILE`. DevSpace does not
-persist provider credentials.
+`command` names one executable. DevSpace does not split shell arguments, so use
+a wrapper executable when startup needs fixed arguments. `env` maps environment
+variable names to literal string values and preserves empty strings. DevSpace
+does not expand `$NAME` references in these values.
+
+Codex, Claude, Cursor, Copilot, and Grok accept `command` and `env`. OpenCode and
+Pi are embedded, so their provider entries reject both fields. The daemon
+inherits its startup environment, then overlays the provider's `env`. An
+explicit `command` wins over both the inherited command override and a command
+override placed in `env`.
+
+Existing process-level overrides remain supported: `CODEX_COMMAND`,
+`CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, `COPILOT_COMMAND`,
+`GROK_COMMAND`, and `GROK_AGENT_PROFILE`. Provider configuration takes
+precedence where the same value is set in both places.
+
+DevSpace writes `config.jsonc` with mode `0600`, but provider environment values
+are still plain text on disk. Keep the file out of version control. Leave
+credentials in the process environment if you do not want DevSpace to persist
+them.
 
 ## Native artifact download
 

diff --git a/docs/dynamic-workflows.md b/docs/dynamic-workflows.md
@@ -0,0 +1,95 @@
+# Subagents And Dynamic Workflows
+
+DevSpace exposes one agent execution layer through its CLI. Coding harnesses
+such as Codex, Pi, OpenCode, or Cursor can call it directly. ChatGPT and Claude
+can call the same commands through DevSpace's ordinary shell or process tools.
+There are no dedicated subagent or workflow-execution MCP tools.
+
+## Setup
+
+Run `devspace init` and enable agent tooling. Setup probes the supported
+providers, asks which ones DevSpace may use, and prints installation commands
+for two Coding Agent skills:
+
+- `subagents` for one bounded delegation and later follow-ups
+- `dynamic-workflows` for programmed multi-agent orchestration
+
+Provider selection is stored as provider objects under `subagents` in
+`~/.devspace/config.jsonc`. Runtime availability is checked again before a
+provider is shown or used. MCP workspaces load the bundled copies when
+subagents are enabled.
+
+## Project Scope
+
+Run agent commands from the intended project. When an MCP host invokes the CLI,
+DevSpace injects the opened workspace identity. In a standalone harness,
+DevSpace discovers the current Git repository or project directory. Lists,
+lookups, continuations, status checks, and cancellations stay inside that
+scope.
+
+## Direct Subagents
+
+```bash
+devspace agents targets --json
+devspace agents run <profile-or-provider> "<brief>" --json
+devspace agents show <id> --json
+devspace agents continue <id> "<follow-up>" --json
+devspace agents stop <id> --json
+devspace agents ls --json
+```
+
+Use a direct subagent for one focused implementation, investigation, review, or
+verification task. Profiles can supply role instructions and provider/model
+defaults. The child runs independently and returns an id that the orchestrator
+polls or continues.
+
+## Dynamic Workflows
+
+```bash
+devspace workflow run --name <name> --json
+devspace workflow run --file <script.js> --arg key=value --json
+devspace workflow status <run-id> --json
+devspace workflow calls <run-id> --json
+devspace workflow call <run-id> <call-index> --json
+devspace workflow cancel <run-id> --json
+devspace workflow ls --json
+devspace workflow tui [run-id]
+```
+
+Named scripts live in `.devspace/workflows/<name>.js`. A script can combine
+`agent`, `parallel`, `pipeline`, `phase`, `log`, and one-level nested
+`workflow` calls. Agent calls can request structured JSON or an isolated Git
+worktree.
+
+Agent harnesses should prefer `--json`, retain the returned id, and poll status.
+This avoids coupling a long workflow lifetime to one tool-call timeout.
+`--follow` remains available for interactive terminals with long-running
+process support.
+
+`workflow tui` opens a project-scoped, read-only Navigator. Without a run id it
+starts on the workflow list; with a run id it opens that run directly. Opening a
+run shows its declared phases beside the agent calls in the selected phase.
+Calls without a declared phase are grouped under `Other`. Terminals narrower
+than 80 columns show one pane at a time, with `Tab` switching panes. Opening a
+call exposes normalized activity, prompt, result, worktree details, and provider
+metadata. Use arrow keys (or `j`/`k`) to navigate, `Tab` to switch panes or
+inspector sections, `Enter` to open, `Esc` to go back, and `q` to quit.
+
+Elapsed time is derived from persisted call timestamps. Token counts are
+best-effort provider observations: a running call may show a partial snapshot,
+while a completed call shows its final provider-reported total. Providers that
+cannot report a value remain visibly unavailable instead of being estimated.
+Replayed calls do not contribute tokens to the current run.
+
+Failed and cancelled workflows are terminal. `workflow run --resume <run-id>`
+creates a new run, reuses the unchanged successful prefix when safe, and
+continues live from the first failed or changed call.
+
+## MCP Boundary
+
+`open_workspace` exposes the current compact subagent profile and provider
+catalog from the core agent system. It does not include active workflow runs,
+workflow phases, session identifiers, or internal counters. Hosts inspect
+those only when needed through `devspace workflow` commands. This keeps the
+host as the orchestrator without adding a second workflow-specific MCP or
+dashboard surface.
diff --git a/docs/gotchas.md b/docs/gotchas.md
@@ -218,7 +218,7 @@ When Subagents are enabled, DevSpace loads agent profiles from
 compact profile catalog through `open_workspace`. The bundled
 `subagents` skill keeps the model-facing workflow to
 `devspace agents targets`, `devspace agents ls`, `devspace agents run`,
-`devspace agents continue`, and `devspace agents show`.
+`devspace agents continue`, `devspace agents show`, and `devspace agents wait`.
 Those commands automatically manage the internal local agent daemon; `devspace
 serve` is not a prerequisite.
 `devspace agents ls` lists existing subagent sessions, not profile
@@ -229,6 +229,7 @@ For a Coding Agent, run the installation command printed by
 
 ```bash
 npx skills add Waishnav/devspace --skill subagents --global
+npx skills add Waishnav/devspace --skill dynamic-workflows --global
 ```
 
 The Skills CLI handles agent discovery and installation. DevSpace setup does

diff --git a/docs/local-agent-daemon.md b/docs/local-agent-daemon.md
@@ -5,7 +5,7 @@ by the MCP server and not by an individual CLI invocation. The daemon is an
 internal implementation detail: the normal workflow remains:
 
 ```text
-devspace agents run/continue/show/ls
+devspace agents targets/run/continue/show/wait/ls
           │
           ▼
     devspace-agentd
@@ -58,15 +58,24 @@ devspace agents daemon stop
 devspace agents daemon logs
 ```
 
-Agent commands accept `--json` when a machine-readable response is needed.
-They emit one compact JSON value. `run` and `continue` return only the logical
-agent ID and status, `ls` returns session summaries, and `show` returns the
-response or structured failure for one agent. Internal workspace paths,
-provider session IDs, timestamps, and prior responses are not included in list
-or receipt output. Immediate failures are emitted as
-`{ error: { code, message, retryable, ... } }` with a non-zero exit code.
-Successful `daemon status` and `daemon stop` output the daemon status object,
-and successful `daemon logs` output is `{ "logs": "<text>" }`.
+The client and daemon compare an internal revision of the provider
+configuration. A client replaces an idle daemon when that configuration has
+changed. It never stops a daemon with active work; the client returns the
+retryable `DAEMON_CONFIG_CHANGED` error until that work finishes. The revision
+is not included in status, logs, or agent command output.
+
+Model-facing agent commands emit compact XML fragments by default. Lists use
+one fragment per item without a root wrapper, and empty lists print nothing.
+`run` and `continue` return only the logical agent ID and status. `show` returns
+an immediate snapshot. `wait` blocks for one or more agents and can return a
+complete ordered snapshot at a caller-supplied timeout. It does not stream
+individual completions.
+
+Internal turns, prompts, workspace paths, provider session IDs, timestamps, and
+prior responses are not included. Immediate failures use an `<error>` fragment
+and a non-zero exit code. `--json` remains available for compatibility and
+scripts. Daemon diagnostic commands keep their existing text and JSON output;
+they do not use the model-facing XML format.
 
 Agent identity is explicit at the client boundary. `agents run` starts a new
 logical agent from a profile or provider; `agents continue <id>` continues an

diff --git a/docs/setup.md b/docs/setup.md
@@ -62,11 +62,13 @@ If you selected Coding Agents, setup prints:
 
 ```bash
 npx skills add Waishnav/devspace --skill subagents --global
+npx skills add Waishnav/devspace --skill dynamic-workflows --global
 ```
 
-The Skills CLI asks which installed Coding Agents should receive the skill.
-The skill uses `devspace agents targets`, `run`, `continue`, `show`, and `ls`.
-These commands do not require `devspace serve`.
+The Skills CLI asks which installed Coding Agents should receive each skill.
+The subagent skill uses `devspace agents targets`, `run`, `continue`, `show`,
+`wait`, `stop`, and `ls`. The workflow skill adds the durable `devspace workflow`
+runner and Navigator. These commands do not require `devspace serve`.
 
 ### Connect ChatGPT
 

diff --git a/package.json b/package.json
@@ -30,6 +30,7 @@
     "build": "pnpm clean && pnpm build:app && tsc -p tsconfig.build.json",
     "build:app": "vite build",
     "dev": "tsx watch --clear-screen=false src/cli.ts serve",
+    "dev:tui-fixture": "tsx scripts/workflow-tui-fixture.ts",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "prepack": "pnpm build",
     "schema:config": "tsx scripts/generate-config-schema.ts",
@@ -50,13 +51,15 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "^1.17.13",
     "@pierre/diffs": "^1.2.5",
+    "ajv": "^8.20.0",
     "better-result": "^2.10.0",
     "better-sqlite3": "^12.10.0",
     "cross-spawn": "^7.0.6",
     "diff": "^8.0.3",
     "drizzle-orm": "^0.45.2",
     "express": "^5.2.1",
     "jsonc-parser": "^3.3.1",
+    "json-schema-to-ts": "^3.1.1",
     "lucide": "^1.24.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/schema/v1/devspace.schema.json b/schema/v1/devspace.schema.json
@@ -192,6 +192,21 @@
               "effort": {
                 "type": "string",
                 "minLength": 1
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "env": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                },
+                "additionalProperties": {
+                  "type": "string"
+                }
               }
             },
             "required": [