Waishnav · Waishnav · Jul 5, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/.agents/plan/local-agent-profiles-and-cli-plan.md b/.agents/plan/local-agent-profiles-and-cli-plan.md
@@ -0,0 +1,96 @@
+# Subagent profiles and DevSpace agent CLI plan
+
+## Decision
+
+Subagent profiles describe roles over built-in coding-agent providers.
+DevSpace owns provider invocation and lifecycle. Custom CLI-backed agents,
+provider action objects, and model-visible backend details are out of scope for
+v1.
+
+The model-facing workflow stays small:
+
+```bash
+devspace agents ls
+devspace agents run <profile-or-id> "<prompt>"
+devspace agents show <id>
+```
+
+Profile discovery happens through the compact catalog returned by
+`open_workspace`. `devspace agents ls` lists existing subagent sessions for the
+current workspace; it does not list profile definitions.
+
+## Profile schema
+
+Profiles are discovered from:
+
+- `~/.devspace/agents/*.md`
+- project `.devspace/agents/*.md`
+
+Supported frontmatter fields:
+
+```yaml
+schema: devspace-agent/v1
+name: reviewer
+description: Read-only reviewer for bugs, security risks, and missing tests.
+provider: codex
+model: gpt-5.4
+disabled: false
+```
+
+Supported providers:
+
+- `codex`
+- `claude`
+- `opencode`
+- `pi`
+- `cursor`
+- `copilot`
+
+Removed from v1 profile schema:
+
+- `backend`
+- `command`
+- `mode`
+- `permissions`
+- `actions`
+
+## Provider mapping
+
+DevSpace maps provider ids to native integrations:
+
+- `codex`: Codex SDK
+- `claude`: Claude Code SDK
+- `opencode`: OpenCode SDK
+- `pi`: Pi RPC mode
+- `cursor`: ACP
+- `copilot`: ACP
+
+The adapter registry is the internal seam future MCP tools can reuse if we move
+from skill plus CLI guidance to first-class MCP agent tools.
+
+## Model exposure
+
+`open_workspace` exposes only compact profile metadata:
+
+```json
+{
+  "name": "reviewer",
+  "description": "Read-only reviewer for bugs, security risks, and missing tests.",
+  "provider": "codex",
+  "model": "gpt-5.4"
+}
+```
+
+The profile body, provider protocol, raw provider transcript, and adapter
+details stay outside the default model context.
+
+Shell calls launched through DevSpace receive `DEVSPACE_WORKSPACE_ID` and
+`DEVSPACE_WORKSPACE_ROOT`, so `devspace agents ls` can scope itself without the
+model passing workspace flags.
+
+## Non-goals
+
+- Custom or arbitrary subagent commands.
+- Provider-specific action DSLs.
+- Exposing raw provider transcripts by default.
+- Tracking changed files or tests from provider output.
diff --git a/docs/agent-profile-schema.md b/docs/agent-profile-schema.md
@@ -0,0 +1,143 @@
+# Subagent profile schema
+
+DevSpace agent profiles are user-owned markdown files with YAML
+frontmatter. They describe roles such as reviewer, explorer, or implementer.
+DevSpace owns provider invocation.
+
+Profiles are discovered from:
+
+- `~/.devspace/agents/*.md`
+- `.devspace/agents/*.md`
+
+Packaged files under `examples/agents/` are starter templates only.
+
+## Minimal shape
+
+```md
+---
+schema: devspace-agent/v1
+name: reviewer
+description: Read-only reviewer for bugs, security risks, and missing tests.
+provider: codex
+model: gpt-5.4
+disabled: false
+---
+
+You are a read-only reviewer. Do not edit files.
+Focus on correctness, security, test gaps, and maintainability.
+Cite files and return concise findings.
+```
+
+## Frontmatter fields
+
+### `schema`
+
+Optional schema identifier:
+
+```yaml
+schema: devspace-agent/v1
+```
+
+### `name`
+
+Stable profile identifier shown to the model and accepted by:
+
+```bash
+devspace agents run <name> "<prompt>"
+```
+
+Use lowercase kebab-case names. If omitted, DevSpace uses the filename without
+`.md`.
+
+### `description`
+
+Required short purpose. This is exposed by `open_workspace` so the supervising
+model can choose the right profile.
+
+### `provider`
+
+Required built-in provider id:
+
+```yaml
+provider: codex
+provider: claude
+provider: opencode
+provider: pi
+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
+
+### `model`
+
+Optional provider model id or alias.
+
+```yaml
+model: gpt-5.4
+model: sonnet
+```
+
+### `disabled`
+
+Optional boolean. Disabled profiles are not exposed.
+
+```yaml
+disabled: true
+```
+
+## Markdown body
+
+The body is the profile prompt prefix DevSpace prepends when launching that
+profile. It is not included in `open_workspace` by default.
+
+Recommended body content:
+
+- When to use this profile.
+- Whether the worker should act read-only or may make changes.
+- Output format.
+- Review or testing expectations.
+
+## Model-facing workflow
+
+The Subagent skill teaches only:
+
+```bash
+devspace agents ls
+devspace agents run <profile-or-id> "<prompt>"
+devspace agents show <id>
+```
+
+`open_workspace` exposes compact profile metadata:
+
+```json
+{
+  "name": "reviewer",
+  "description": "Read-only reviewer for bugs, security risks, and missing tests.",
+  "provider": "codex",
+  "model": "gpt-5.4"
+}
+```
+
+`devspace agents ls` lists existing subagent sessions for the current workspace;
+it does not list profile definitions.
+
+The full profile body stays out of the model context until DevSpace launches the
+profile.
+
+## Current non-goals
+
+- Custom or arbitrary CLI-backed agents.
+- 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`.
diff --git a/docs/chatgpt-coding-workflow.md b/docs/chatgpt-coding-workflow.md
@@ -83,12 +83,24 @@ DevSpace discovers standard Agent Skills from:
 
 - `~/.agents/skills`
 - project `.agents/skills`
+- `~/.devspace/skills`
 
 It also keeps compatibility with:
 
+- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
+When Subagents 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 so the model can choose a configured agent
+without seeing provider-specific launch details.
+
+Example profiles are packaged under `examples/agents/` for users who want
+starter templates. Copy or adapt them into one of the active profile directories
+before use.
+
 Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
 
 When `open_workspace` returns matching skills, the model should read the
@@ -99,7 +111,12 @@ Skill paths may be outside the workspace. DevSpace only permits reading:
 - advertised `SKILL.md` files
 - files under a skill directory after that skill's `SKILL.md` has been read
 
-Set `DEVSPACE_SKILLS=0` to hide skills from workspace output.
+Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Set
+`DEVSPACE_SUBAGENTS=1` to expose the experimental subagent catalog and
+`subagent-delegation` skill. That skill teaches the minimal
+`devspace agents ls`, `devspace agents run`, and `devspace agents show`
+workflow. The catalog comes from `open_workspace`; `devspace agents ls` lists
+existing subagent sessions for that workspace.
 
 ## Tool Names
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -92,19 +92,39 @@ sessions.
 | Variable | Purpose |
 | --- | --- |
 | `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_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
 | `DEVSPACE_SKILL_PATHS` | Optional comma-separated additional skill directories. |
 
 DevSpace discovers standard Agent Skills from:
 
 - `~/.agents/skills`
 - project `.agents/skills`
+- `~/.devspace/skills`
 
 It also keeps compatibility with:
 
+- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
+When Subagents 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 so the host model can choose an
+agent without reading provider-specific launch details. `devspace agents ls`
+lists existing subagent sessions for the current workspace, scoped by the
+workspace environment injected into shell commands. The `subagent-delegation`
+skill teaches the model to use only the minimal `devspace agents ls`,
+`devspace agents run`, and `devspace agents show` workflow.
+
+Starter profile templates are available under `examples/agents/`. Copy or adapt
+them into one of the active profile directories before use.
+
 Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
 
 Example:

diff --git a/docs/gotchas.md b/docs/gotchas.md
@@ -197,12 +197,25 @@ DevSpace looks in standard Agent Skills locations:
 
 - `~/.agents/skills`
 - project `.agents/skills`
+- `~/.devspace/skills`
 
 It also checks compatibility and custom paths:
 
+- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
+When `DEVSPACE_SUBAGENTS=1`, DevSpace loads agent profiles from
+`~/.devspace/agents/*.md` and project `.devspace/agents/*.md`, then exposes a
+compact profile catalog through `open_workspace`. The bundled
+`subagent-delegation` skill keeps the model-facing workflow to
+`devspace agents ls`, `devspace agents run`, and `devspace agents show`.
+`devspace agents ls` lists existing subagent sessions, not profile
+definitions.
+
+Packaged agent profile examples under `examples/agents/` are starter templates.
+Copy or adapt them into one of the active profile directories before use.
+
 Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
 
 If a skill appears in `open_workspace`, the model must read that skill's

diff --git a/examples/agents/claude-implementer.md b/examples/agents/claude-implementer.md
@@ -0,0 +1,31 @@
+---
+schema: devspace-agent/v1
+name: claude-implementer
+description: Claude Code profile for larger implementation, refactor, and repair tasks.
+provider: claude
+model: sonnet
+---
+
+You are a local Claude Code implementation worker under supervisor review.
+
+Use this profile for multi-file implementation, careful refactors, and test
+repair loops when the user asked for delegated implementation.
+
+Rules:
+
+- Keep changes focused.
+- Preserve public behavior unless asked.
+- Do not rewrite unrelated code.
+- Run or explain relevant tests.
+- Return a concise final report.
+
+Final report format:
+
+```text
+summary:
+files_changed:
+tests_run:
+risks:
+blockers:
+follow_up_needed:
+```