Skip to content

feat(init): onboard CLI agent tooling #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Waishnav wants to merge 4 commits into from
Closed

feat(init): onboard CLI agent tooling #169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5c13ea0
feat(init): configure and install CLI workflow skills
Waishnav Aug 9, 2026
76495f9
docs: document CLI-only agent workflows
Waishnav Aug 9, 2026
fc52980
fix(init): report workflow provider availability
Waishnav Aug 9, 2026
f89c220
fix(server): report workflow provider availability
Waishnav Aug 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions docs/agent-profile-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,15 +68,9 @@ provider: cursor
provider: copilot
```

Unsupported or custom providers are rejected. DevSpace maps providers to their
native integration:

- `codex`: Codex SDK
- `claude`: Claude Code SDK
- `opencode`: OpenCode SDK
- `pi`: Pi RPC mode
- `cursor`: ACP
- `copilot`: ACP
Unsupported or custom providers are rejected. Use a provider name reported by
`devspace agents targets`; availability depends on the local tools installed on
the machine.

### `model`

Expand Down Expand Up @@ -134,20 +128,26 @@ Recommended body content:
The Subagent skill teaches only:

```bash
devspace agents targets
devspace agents ls
devspace agents run <profile-or-id> "<prompt>"
devspace agents show <id>
```

`open_workspace` exposes compact profile metadata:
`open_workspace` exposes compact profile metadata. Provider entries contain only
the provider name; profiles retain their configured defaults because those are
the model's selection inputs:

```json
{
"name": "reviewer",
"description": "Read-only reviewer for bugs, security risks, and missing tests.",
"provider": "codex",
"model": "gpt-5.4",
"effort": "high"
"agentProviders": [{ "name": "codex" }],
"agents": [{
"name": "reviewer",
"description": "Read-only reviewer for bugs, security risks, and missing tests.",
"provider": "codex",
"model": "gpt-5.4",
"effort": "high"
}]
}
```

Expand All @@ -163,5 +163,5 @@ profile.
- Inferring changed files, tests, or diffs from worker output.
- Exposing raw provider transcripts by default.
- Teaching the model provider-specific CLIs.
- First-class MCP agent tools. Future tools should wrap the same provider
adapter registry used by `devspace agents`.
- MCP agent and workflow execution tools. Use the CLI from a shell-capable
harness; MCP remains the workspace/file/shell surface.
40 changes: 20 additions & 20 deletions docs/chatgpt-coding-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,16 +87,17 @@ DevSpace discovers standard Agent Skills from:

It also includes:

- the package-managed `subagents` skill when the Subagents capability is enabled
- the package-managed `dynamic-workflows` skill when the Dynamic Workflows capability is enabled
- the bundled `subagents` skill when the Subagents capability is enabled
- the bundled `dynamic-workflows` skill when the Dynamic Workflows capability is enabled
- `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
- additional paths from `DEVSPACE_SKILL_PATHS`

When Subagents are enabled, DevSpace discovers agent profiles
When Subagents or Dynamic Workflows are enabled, DevSpace discovers agent profiles
from `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`.
`open_workspace` exposes a compact catalog with profile names, descriptions,
providers, and optional models/effort levels so the model can choose a configured agent
without seeing provider-specific launch details.
`open_workspace` exposes a compact catalog with profile names, descriptions, and
optional model/effort defaults so the model can choose a configured agent
without seeing provider-specific launch details. Provider entries contain only
their names, and unavailable providers or dependent profiles are omitted.

Example profiles are packaged under `examples/agents/` for users who want
starter templates. Copy or adapt them into one of the active profile directories
Expand All @@ -119,10 +120,16 @@ host or discover it with `devspace agents targets`. `devspace agents ls` lists
existing subagent sessions for the current workspace.

Set `DEVSPACE_WORKFLOWS=1` to enable Dynamic Workflows independently. When the
variable is omitted, Dynamic Workflows follows the effective Subagents setting,
including persisted config and any environment override. Disabled features are
omitted from the `open_workspace` schema and response rather than returned as
empty capability arrays.
variable is omitted, Dynamic Workflows follows the effective Subagents setting
for backwards compatibility. Disabled features are omitted from the
`open_workspace` schema and response rather than returned as empty capability
arrays.

Subagents and Dynamic Workflows execute through the DevSpace CLI. The bundled
skills installed by `devspace init` describe the commands and are available to
ChatGPT, Claude, and coding harnesses that can run shell commands. MCP does not
register separate agent or workflow execution tools; use its ordinary `bash`
tool when the host needs to invoke a CLI command.
Comment on lines +128 to +132

@coderabbitai coderabbitai Bot Aug 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document the shell tool for codex mode.

The text requires the ordinary bash tool, but Lines 159-162 state that codex mode hides bash and exposes exec_command. Tell users to use bash in the standard modes and exec_command in codex mode.

As per coding guidelines: “Verify the actual user-consumption path, including ... real MCP hosts ... tool surfaces, widgets, and rendered artifacts.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/chatgpt-coding-workflow.md` around lines 128 - 132, Update the workflow
documentation around the DevSpace CLI guidance to distinguish tool usage by
mode: instruct standard modes and MCP hosts to invoke commands with bash, while
instructing codex mode users to use exec_command because bash is hidden there.
Keep the existing CLI and skill-availability explanation intact.

Source: Coding guidelines


## Tool Names

Expand Down Expand Up @@ -158,16 +165,9 @@ a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.

By default, `DEVSPACE_WIDGETS=full`.

In that mode, DevSpace attaches widget UI to the exposed workspace, workflow,
file, edit, and shell tools. The `open_workspace` dropdown presents the opened
root, loaded skills and instructions, available agent providers/profiles, and
currently active workflows for that workspace.

Dynamic Workflow views are read-only. They refresh through app-only MCP tools
and show observed phases, agent calls, replay state, worktree isolation, errors,
and recent activity. When the host supports MCP Apps fullscreen display mode,
the card offers an **Open dashboard** presentation control. It does not add
cancel, resume, apply, or cleanup actions.
In that mode, DevSpace attaches widget UI to the exposed workspace, file, edit,
and shell tools. The `open_workspace` dropdown presents the opened root, loaded
skills and instructions, and compact agent/workflow summaries when enabled.

The aggregate `show_changes` tool is not exposed by default.

Expand Down
25 changes: 14 additions & 11 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ sessions.
| --- | --- |
| `DEVSPACE_SKILLS` | Set to `0` to hide skills. Enabled by default. |
| `DEVSPACE_SUBAGENTS` | Set to `1` to expose configured agent profiles as Subagents. Experimental and disabled by default. |
| `DEVSPACE_WORKFLOWS` | Experimental Dynamic Workflows gate. When unset, it follows the effective Subagents setting, including persisted config and any environment override. |
| `DEVSPACE_WORKFLOWS` | Set to `1` to enable Dynamic Workflows independently. When unset, it follows the effective Subagents setting for backwards compatibility. |
| `DEVSPACE_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
| `DEVSPACE_SKILL_PATHS` | Optional comma-separated additional skill directories. |

Expand All @@ -105,33 +105,36 @@ DevSpace discovers standard Agent Skills from:

It also includes:

- the package-managed `subagents` skill when the Subagents capability is enabled
- the package-managed `dynamic-workflows` skill when the Dynamic Workflows capability is enabled
- the bundled `subagents` skill when the Subagents capability is enabled
- the bundled `dynamic-workflows` skill when the Dynamic Workflows capability is enabled
- `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
- additional paths from `DEVSPACE_SKILL_PATHS`

User and project skills with the same name take precedence over bundled skills.
DevSpace does not copy bundled skills into `~/.devspace/skills` during setup.
`devspace init` asks about Subagents and Dynamic Workflows separately and
installs enabled skills into `~/.devspace/skills` (or the configured
`DEVSPACE_CONFIG_DIR/skills`). A user-owned directory is preserved; only a
directory previously marked as DevSpace-managed is updated.

When Subagents are enabled, DevSpace discovers agent profiles
When Subagents or Dynamic Workflows are enabled, DevSpace discovers agent profiles
from:

- `~/.devspace/agents/*.md`
- project `.devspace/agents/*.md`

`open_workspace` returns a compact catalog containing profile names,
descriptions, providers, and optional models/effort levels so the host model can choose an
agent without reading provider-specific launch details. `devspace agents ls`
descriptions, and optional model/effort defaults so the host model can choose an
agent without reading provider-specific launch details. Provider entries contain
only their names. `devspace agents ls`
lists existing subagent sessions for the current workspace, scoped by the
workspace environment injected into shell commands. The `subagents`
skill teaches the model to discover targets with `devspace agents targets`,
then use the minimal `devspace agents run`, `devspace agents show`, and
`devspace agents ls` workflow.

Provider availability is detected at runtime. DevSpace does not persist probe
timestamps, availability snapshots, or an experimental provider enable-list in
`config.json`. Final provider policy and onboarding are deferred until the
Subagents and Dynamic Workflows features are finalized.
Provider availability is detected at runtime. Unavailable providers and profiles
that depend on them are omitted from `open_workspace` and `devspace agents
targets`. The enabled feature switches are persisted in `config.json`.
Comment on lines +108 to +137

@coderabbitai coderabbitai Bot Aug 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Remove the stale workflow-widget contract.

The current documentation says that MCP does not expose separate workflow execution tools, but Line 86 still says that DEVSPACE_WIDGETS=full attaches UI to workflow tools and live workflow dashboards. Update that widget description so users do not expect tools that are no longer registered.

As per coding guidelines: “Verify the actual user-consumption path, including ... tool surfaces, widgets, and rendered artifacts.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/configuration.md` around lines 108 - 137, Update the
DEVSPACE_WIDGETS=full documentation near the workflow widget description to
remove references to attaching UI to workflow execution tools and live workflow
dashboards. Ensure the description matches the current MCP tool surface, which
does not expose separate workflow execution tools, while preserving any
still-supported widget behavior.

Source: Coding guidelines


Starter profile templates are available under `examples/agents/`. Copy or adapt
them into one of the active profile directories before use.
Expand Down
Loading
Loading