Skip to content

Commit 2da956f

Browse files
WaishnavWaishnav
authored
Merge pull request #50 from Waishnav/codex/local-agent-examples
subagents premitives using local agents and their profiles
2 parents a5b7816 + 9c79713 commit 2da956f

43 files changed

Lines changed: 3783 additions & 35 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/plan/local-agent-profiles-and-cli-plan.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Subagent profiles and DevSpace agent CLI plan
2+
3+
## Decision
4+
5+
Subagent profiles describe roles over built-in coding-agent providers.
6+
DevSpace owns provider invocation and lifecycle. Custom CLI-backed agents,
7+
provider action objects, and model-visible backend details are out of scope for
8+
v1.
9+
10+
The model-facing workflow stays small:
11+
12+
```bash
13+
devspace agents ls
14+
devspace agents run <profile-or-id> "<prompt>"
15+
devspace agents show <id>
16+
```
17+
18+
Profile discovery happens through the compact catalog returned by
19+
`open_workspace`. `devspace agents ls` lists existing subagent sessions for the
20+
current workspace; it does not list profile definitions.
21+
22+
## Profile schema
23+
24+
Profiles are discovered from:
25+
26+
- `~/.devspace/agents/*.md`
27+
- project `.devspace/agents/*.md`
28+
29+
Supported frontmatter fields:
30+
31+
```yaml
32+
schema: devspace-agent/v1
33+
name: reviewer
34+
description: Read-only reviewer for bugs, security risks, and missing tests.
35+
provider: codex
36+
model: gpt-5.4
37+
disabled: false
38+
```
39+
40+
Supported providers:
41+
42+
- `codex`
43+
- `claude`
44+
- `opencode`
45+
- `pi`
46+
- `cursor`
47+
- `copilot`
48+
49+
Removed from v1 profile schema:
50+
51+
- `backend`
52+
- `command`
53+
- `mode`
54+
- `permissions`
55+
- `actions`
56+
57+
## Provider mapping
58+
59+
DevSpace maps provider ids to native integrations:
60+
61+
- `codex`: Codex SDK
62+
- `claude`: Claude Code SDK
63+
- `opencode`: OpenCode SDK
64+
- `pi`: Pi RPC mode
65+
- `cursor`: ACP
66+
- `copilot`: ACP
67+
68+
The adapter registry is the internal seam future MCP tools can reuse if we move
69+
from skill plus CLI guidance to first-class MCP agent tools.
70+
71+
## Model exposure
72+
73+
`open_workspace` exposes only compact profile metadata:
74+
75+
```json
76+
{
77+
"name": "reviewer",
78+
"description": "Read-only reviewer for bugs, security risks, and missing tests.",
79+
"provider": "codex",
80+
"model": "gpt-5.4"
81+
}
82+
```
83+
84+
The profile body, provider protocol, raw provider transcript, and adapter
85+
details stay outside the default model context.
86+
87+
Shell calls launched through DevSpace receive `DEVSPACE_WORKSPACE_ID` and
88+
`DEVSPACE_WORKSPACE_ROOT`, so `devspace agents ls` can scope itself without the
89+
model passing workspace flags.
90+
91+
## Non-goals
92+
93+
- Custom or arbitrary subagent commands.
94+
- Provider-specific action DSLs.
95+
- Exposing raw provider transcripts by default.
96+
- Tracking changed files or tests from provider output.

‎docs/agent-profile-schema.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Subagent profile schema
2+
3+
DevSpace agent profiles are user-owned markdown files with YAML
4+
frontmatter. They describe roles such as reviewer, explorer, or implementer.
5+
DevSpace owns provider invocation.
6+
7+
Profiles are discovered from:
8+
9+
- `~/.devspace/agents/*.md`
10+
- `.devspace/agents/*.md`
11+
12+
Packaged files under `examples/agents/` are starter templates only.
13+
14+
## Minimal shape
15+
16+
```md
17+
---
18+
schema: devspace-agent/v1
19+
name: reviewer
20+
description: Read-only reviewer for bugs, security risks, and missing tests.
21+
provider: codex
22+
model: gpt-5.4
23+
disabled: false
24+
---
25+
26+
You are a read-only reviewer. Do not edit files.
27+
Focus on correctness, security, test gaps, and maintainability.
28+
Cite files and return concise findings.
29+
```
30+
31+
## Frontmatter fields
32+
33+
### `schema`
34+
35+
Optional schema identifier:
36+
37+
```yaml
38+
schema: devspace-agent/v1
39+
```
40+
41+
### `name`
42+
43+
Stable profile identifier shown to the model and accepted by:
44+
45+
```bash
46+
devspace agents run <name> "<prompt>"
47+
```
48+
49+
Use lowercase kebab-case names. If omitted, DevSpace uses the filename without
50+
`.md`.
51+
52+
### `description`
53+
54+
Required short purpose. This is exposed by `open_workspace` so the supervising
55+
model can choose the right profile.
56+
57+
### `provider`
58+
59+
Required built-in provider id:
60+
61+
```yaml
62+
provider: codex
63+
provider: claude
64+
provider: opencode
65+
provider: pi
66+
provider: cursor
67+
provider: copilot
68+
```
69+
70+
Unsupported or custom providers are rejected. DevSpace maps providers to their
71+
native integration:
72+
73+
- `codex`: Codex SDK
74+
- `claude`: Claude Code SDK
75+
- `opencode`: OpenCode SDK
76+
- `pi`: Pi RPC mode
77+
- `cursor`: ACP
78+
- `copilot`: ACP
79+
80+
### `model`
81+
82+
Optional provider model id or alias.
83+
84+
```yaml
85+
model: gpt-5.4
86+
model: sonnet
87+
```
88+
89+
### `disabled`
90+
91+
Optional boolean. Disabled profiles are not exposed.
92+
93+
```yaml
94+
disabled: true
95+
```
96+
97+
## Markdown body
98+
99+
The body is the profile prompt prefix DevSpace prepends when launching that
100+
profile. It is not included in `open_workspace` by default.
101+
102+
Recommended body content:
103+
104+
- When to use this profile.
105+
- Whether the worker should act read-only or may make changes.
106+
- Output format.
107+
- Review or testing expectations.
108+
109+
## Model-facing workflow
110+
111+
The Subagent skill teaches only:
112+
113+
```bash
114+
devspace agents ls
115+
devspace agents run <profile-or-id> "<prompt>"
116+
devspace agents show <id>
117+
```
118+
119+
`open_workspace` exposes compact profile metadata:
120+
121+
```json
122+
{
123+
"name": "reviewer",
124+
"description": "Read-only reviewer for bugs, security risks, and missing tests.",
125+
"provider": "codex",
126+
"model": "gpt-5.4"
127+
}
128+
```
129+
130+
`devspace agents ls` lists existing subagent sessions for the current workspace;
131+
it does not list profile definitions.
132+
133+
The full profile body stays out of the model context until DevSpace launches the
134+
profile.
135+
136+
## Current non-goals
137+
138+
- Custom or arbitrary CLI-backed agents.
139+
- Inferring changed files, tests, or diffs from worker output.
140+
- Exposing raw provider transcripts by default.
141+
- Teaching the model provider-specific CLIs.
142+
- First-class MCP agent tools. Future tools should wrap the same provider
143+
adapter registry used by `devspace agents`.

‎docs/chatgpt-coding-workflow.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,12 +83,24 @@ DevSpace discovers standard Agent Skills from:
8383

8484
- `~/.agents/skills`
8585
- project `.agents/skills`
86+
- `~/.devspace/skills`
8687

8788
It also keeps compatibility with:
8889

90+
- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
8991
- `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
9092
- additional paths from `DEVSPACE_SKILL_PATHS`
9193

94+
When Subagents are enabled, DevSpace discovers agent profiles
95+
from `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`.
96+
`open_workspace` exposes a compact catalog with profile names, descriptions,
97+
providers, and optional models so the model can choose a configured agent
98+
without seeing provider-specific launch details.
99+
100+
Example profiles are packaged under `examples/agents/` for users who want
101+
starter templates. Copy or adapt them into one of the active profile directories
102+
before use.
103+
92104
Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
93105

94106
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:
99111
- advertised `SKILL.md` files
100112
- files under a skill directory after that skill's `SKILL.md` has been read
101113

102-
Set `DEVSPACE_SKILLS=0` to hide skills from workspace output.
114+
Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Set
115+
`DEVSPACE_SUBAGENTS=1` to expose the experimental subagent catalog and
116+
`subagent-delegation` skill. That skill teaches the minimal
117+
`devspace agents ls`, `devspace agents run`, and `devspace agents show`
118+
workflow. The catalog comes from `open_workspace`; `devspace agents ls` lists
119+
existing subagent sessions for that workspace.
103120

104121
## Tool Names
105122

‎docs/configuration.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,19 +92,39 @@ sessions.
9292
| Variable | Purpose |
9393
| --- | --- |
9494
| `DEVSPACE_SKILLS` | Set to `0` to hide skills. Enabled by default. |
95+
| `DEVSPACE_SUBAGENTS` | Set to `1` to expose configured agent profiles as Subagents. Experimental and disabled by default. |
9596
| `DEVSPACE_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
9697
| `DEVSPACE_SKILL_PATHS` | Optional comma-separated additional skill directories. |
9798

9899
DevSpace discovers standard Agent Skills from:
99100

100101
- `~/.agents/skills`
101102
- project `.agents/skills`
103+
- `~/.devspace/skills`
102104

103105
It also keeps compatibility with:
104106

107+
- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
105108
- `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
106109
- additional paths from `DEVSPACE_SKILL_PATHS`
107110

111+
When Subagents are enabled, DevSpace discovers agent profiles
112+
from:
113+
114+
- `~/.devspace/agents/*.md`
115+
- project `.devspace/agents/*.md`
116+
117+
`open_workspace` returns a compact catalog containing profile names,
118+
descriptions, providers, and optional models so the host model can choose an
119+
agent without reading provider-specific launch details. `devspace agents ls`
120+
lists existing subagent sessions for the current workspace, scoped by the
121+
workspace environment injected into shell commands. The `subagent-delegation`
122+
skill teaches the model to use only the minimal `devspace agents ls`,
123+
`devspace agents run`, and `devspace agents show` workflow.
124+
125+
Starter profile templates are available under `examples/agents/`. Copy or adapt
126+
them into one of the active profile directories before use.
127+
108128
Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
109129

110130
Example:

‎docs/gotchas.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,12 +197,25 @@ DevSpace looks in standard Agent Skills locations:
197197

198198
- `~/.agents/skills`
199199
- project `.agents/skills`
200+
- `~/.devspace/skills`
200201

201202
It also checks compatibility and custom paths:
202203

204+
- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
203205
- `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
204206
- additional paths from `DEVSPACE_SKILL_PATHS`
205207

208+
When `DEVSPACE_SUBAGENTS=1`, DevSpace loads agent profiles from
209+
`~/.devspace/agents/*.md` and project `.devspace/agents/*.md`, then exposes a
210+
compact profile catalog through `open_workspace`. The bundled
211+
`subagent-delegation` skill keeps the model-facing workflow to
212+
`devspace agents ls`, `devspace agents run`, and `devspace agents show`.
213+
`devspace agents ls` lists existing subagent sessions, not profile
214+
definitions.
215+
216+
Packaged agent profile examples under `examples/agents/` are starter templates.
217+
Copy or adapt them into one of the active profile directories before use.
218+
206219
Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
207220

208221
If a skill appears in `open_workspace`, the model must read that skill's

‎examples/agents/claude-implementer.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
schema: devspace-agent/v1
3+
name: claude-implementer
4+
description: Claude Code profile for larger implementation, refactor, and repair tasks.
5+
provider: claude
6+
model: sonnet
7+
---
8+
9+
You are a local Claude Code implementation worker under supervisor review.
10+
11+
Use this profile for multi-file implementation, careful refactors, and test
12+
repair loops when the user asked for delegated implementation.
13+
14+
Rules:
15+
16+
- Keep changes focused.
17+
- Preserve public behavior unless asked.
18+
- Do not rewrite unrelated code.
19+
- Run or explain relevant tests.
20+
- Return a concise final report.
21+
22+
Final report format:
23+
24+
```text
25+
summary:
26+
files_changed:
27+
tests_run:
28+
risks:
29+
blockers:
30+
follow_up_needed:
31+
```

0 commit comments

Comments
 (0)