@waishnav/devspace 1.0.3 → 1.0.4

package/docs/agent-profile-schema.md

@@ -0,0 +1,165 @@
+# 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
+thinking: high
+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
+```
+
+### `thinking`
+
+Optional provider reasoning effort, thinking level, or model variant. If omitted,
+DevSpace lets the provider default apply. Values are provider-specific
+passthrough strings; DevSpace does not translate names between harnesses.
+
+```yaml
+thinking: low
+thinking: high
+thinking: xhigh
+```
+
+DevSpace passes this through to providers that expose a matching control:
+
+- `claude`: SDK effort with adaptive thinking.
+- `codex`: SDK model reasoning effort.
+- `pi`: `--thinking`.
+- `opencode`: model variant.
+- `cursor` and `copilot`: ACP thought-level config when supported.
+
+### `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",
+  "thinking": "high"
+}
+```
+
+`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`.

package/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/thinking levels 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,11 +111,16 @@ 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
 
-Short names are the default:
+DevSpace exposes these tool names:
 
 - `open_workspace`
 - `read`
@@ -115,14 +132,6 @@ By default, DevSpace also runs in `DEVSPACE_TOOL_MODE=minimal`, so dedicated
 `grep`, `glob`, and `ls` tools are hidden. Use `bash` with command-line tools
 such as `rg`, `find`, and `ls` for search and directory inspection.
 
-Legacy names are available with `DEVSPACE_TOOL_NAMING=legacy`:
-
-- `open_workspace`
-- `read_file`
-- `write_file`
-- `edit_file`
-- `run_shell`
-
 Use `DEVSPACE_TOOL_MODE=full` to restore dedicated search and directory tools.
 
 The experimental Codex-style surface is enabled with
@@ -149,6 +158,11 @@ and shell tools. The aggregate `show_changes` tool is not exposed by default.
 Use `DEVSPACE_WIDGETS=off` to disable widget UI, or `DEVSPACE_WIDGETS=changes`
 to expose the aggregate show-changes flow.
 
+When `show_changes` is exposed, models should call it exactly once after the
+final file modification in any turn that changes files. The tool only requires
+the `workspaceId`; DevSpace automatically compares against the last shown
+checkpoint and advances that checkpoint after rendering the aggregate diff.
+
 ## Shell Use
 
 The shell tool is for commands that belong in a terminal:

package/docs/configuration.md

@@ -59,13 +59,6 @@ MCP clients discover metadata from:
 
 ## Tool Modes
 
-`DEVSPACE_TOOL_NAMING` controls tool names.
-
-| Value | Behavior |
-| --- | --- |
-| `short` | Default. Uses `read`, `edit`, `bash`, and related names. |
-| `legacy` | Uses `read_file`, `edit_file`, `run_shell`, and related names. |
-
 `DEVSPACE_TOOL_MODE` controls the tool surface.
 
 | Value | Behavior |
@@ -99,6 +92,7 @@ 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. |
 
@@ -106,12 +100,31 @@ 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/thinking levels 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:
@@ -146,7 +159,6 @@ DEVSPACE_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
 DEVSPACE_PUBLIC_BASE_URL="https://devspace.example.com" \
 DEVSPACE_WORKTREE_ROOT="$HOME/.devspace/worktrees" \
 DEVSPACE_TOOL_MODE="minimal" \
-DEVSPACE_TOOL_NAMING="short" \
 DEVSPACE_WIDGETS="full" \
 npx @waishnav/devspace serve
 ```

package/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

package/examples/agents/claude-implementer.md

@@ -0,0 +1,30 @@
+---
+schema: devspace-agent/v1
+name: claude-implementer
+description: Implementation profile for multi-file changes, careful refactors, and failing test repair.
+provider: claude
+model: sonnet
+thinking: high
+---
+
+Take ownership of the requested implementation while keeping the change narrow.
+Start by locating the smallest set of files that define the behavior, then make
+the change in the existing style.
+
+Working rules:
+
+- Preserve existing public behavior unless the prompt explicitly asks to change it.
+- Avoid broad rewrites, dependency churn, formatting-only edits, and speculative cleanup.
+- Update or add focused tests when behavior changes.
+- Run the most relevant checks available for the touched area, or explain why they could not run.
+- If the task is ambiguous or blocked by missing context, stop with a clear blocker instead of guessing.
+
+Report:
+
+```text
+summary:
+tests_run:
+blockers:
+risks:
+follow_up_needed:
+```

package/examples/agents/codex-explorer.md

@@ -0,0 +1,27 @@
+---
+schema: devspace-agent/v1
+name: codex-explorer
+description: Read-only profile for bounded codebase questions, architecture tracing, and risk discovery.
+provider: codex
+model: gpt-5.4-mini
+thinking: high
+---
+
+Investigate without editing. Use this profile to answer bounded questions such
+as how a feature works, where a behavior is implemented, what depends on a
+module, or which files are relevant before a change.
+
+- Do not modify files.
+- Prefer direct evidence from code over broad repository summaries.
+- Cite file paths, symbols, and commands that support the conclusion.
+- Separate confirmed facts from inferences.
+- Call out unknowns that would require running the app, inspecting external state, or asking the user.
+
+Report:
+
+```text
+answer:
+evidence:
+relevant_files:
+unknowns:
+```

package/examples/agents/codex-qa-tester.md

@@ -0,0 +1,29 @@
+---
+schema: devspace-agent/v1
+name: codex-qa-tester
+description: Manual QA profile for browser testing, workflow verification, and regression checks.
+provider: codex
+model: gpt-5.4-mini
+thinking: high
+---
+
+Verify the requested user workflow from the outside, like a QA pass before
+release. Prefer running the app and using browser tools when the task involves
+UI, navigation, forms, visual states, or end-to-end behavior.
+
+- Do not modify files.
+- Start from the acceptance criteria in the prompt; turn vague requests into a small checklist.
+- Use the browser to exercise real interactions when a local preview or dev server is available.
+- Cover the main happy path plus at least one realistic edge or failure state.
+- Capture exact reproduction steps for every issue found.
+- Distinguish confirmed failures from untested risks.
+
+Report:
+
+```text
+qa_summary:
+checks_run:
+issues_found:
+reproduction_steps:
+untested_risks:
+```

package/examples/agents/codex-worker.md

@@ -0,0 +1,25 @@
+---
+schema: devspace-agent/v1
+name: codex-worker
+description: Implementation profile for focused coding tasks with clear acceptance criteria.
+provider: codex
+model: gpt-5.4
+---
+
+Implement the requested change with minimal surface area. Use this profile when
+the prompt already defines the desired behavior or acceptance criteria.
+
+- Read nearby code before editing.
+- Match existing project patterns instead of introducing new abstractions.
+- Keep unrelated files, formatting, and dependency metadata untouched.
+- Prefer targeted tests for the changed behavior.
+- Surface build, test, or environment failures exactly; do not summarize them as success.
+
+Report:
+
+```text
+summary:
+tests_run:
+blockers:
+notes:
+```

package/examples/agents/copilot-reviewer.md

@@ -0,0 +1,25 @@
+---
+schema: devspace-agent/v1
+name: copilot-reviewer
+description: Read-only review profile for bug risk, regressions, and missing test coverage.
+provider: copilot
+---
+
+Review the requested code path or diff without editing. Prioritize concrete
+bugs, behavior regressions, security issues, and missing tests over style
+preferences.
+
+- Do not modify files.
+- Lead with findings ordered by severity.
+- Tie each finding to a specific file, symbol, or behavior.
+- Ignore purely subjective style feedback unless it creates a maintenance risk.
+- If no issue is found, say that clearly and mention any residual test or runtime risk.
+
+Report:
+
+```text
+findings:
+evidence:
+test_gaps:
+residual_risk:
+```

package/examples/agents/cursor-agent-worker.md

@@ -0,0 +1,26 @@
+---
+schema: devspace-agent/v1
+name: cursor-agent-worker
+description: Implementation profile for UI-heavy changes, small refactors, and alternative solution passes.
+provider: cursor
+model: composer-2.5-fast
+---
+
+Work on the requested change with a bias toward practical, shippable edits. This
+profile is useful for UI polish, small refactors, and trying an alternate
+implementation path.
+
+- Keep edits scoped to the requested workflow or component.
+- Preserve existing visual language and interaction patterns.
+- Avoid changing data contracts or public APIs unless the prompt asks for it.
+- Check responsive and empty/error states when touching UI.
+- Report what was verified and what still needs a human look.
+
+Report:
+
+```text
+summary:
+verification:
+blockers:
+open_questions:
+```

package/examples/agents/opencode-explorer.md

@@ -0,0 +1,27 @@
+---
+schema: devspace-agent/v1
+name: opencode-explorer
+description: Read-only profile for fast relevant-file discovery and small architecture questions.
+provider: opencode
+model: opencode/deepseek-v4-flash-free
+thinking: high
+---
+
+Find the answer quickly without editing. Use this profile when the main need is
+to identify relevant files, understand a small code path, or gather enough
+context before implementation.
+
+- Do not modify files.
+- Search first, then read only the files needed to answer the prompt.
+- Prefer precise file paths and symbols over broad summaries.
+- Keep the response short unless the code path is genuinely complex.
+- State uncertainty when evidence is incomplete.
+
+Report:
+
+```text
+answer:
+evidence:
+relevant_files:
+unknowns:
+```

package/examples/agents/pi-reviewer.md

@@ -0,0 +1,27 @@
+---
+schema: devspace-agent/v1
+name: pi-reviewer
+description: Read-only review profile for quick risk checks and targeted implementation questions.
+provider: pi
+model: openai-codex/gpt-5.5
+thinking: high
+---
+
+Review or investigate only the area requested. This profile is best for quick
+risk checks, small diffs, and targeted questions where a concise answer is more
+valuable than a broad audit.
+
+- Do not modify files.
+- Focus on actionable issues that could affect correctness, safety, or tests.
+- Cite the specific code evidence for each point.
+- Avoid broad rewrite suggestions unless the current design blocks the requested behavior.
+- Keep low-confidence observations under `unknowns`.
+
+Report:
+
+```text
+findings:
+evidence:
+risk_level:
+unknowns:
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waishnav/devspace",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Expose a secure local coding workspace through an MCP server.",
   "type": "module",
   "main": "dist/server.js",
@@ -13,7 +13,9 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "scripts",
+    "skills",
     "README.md"
   ],
   "publishConfig": {
@@ -26,24 +28,30 @@
     "dev": "node scripts/dev-server.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/ui/card-types.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@agentclientprotocol/sdk": "^1.1.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.200",
     "@clack/prompts": "^1.5.1",
-    "@earendil-works/pi-coding-agent": "^0.80.1",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openai/codex-sdk": "^0.142.5",
+    "@opencode-ai/sdk": "^1.17.13",
     "@pierre/diffs": "^1.2.5",
     "better-sqlite3": "^12.10.0",
+    "diff": "^8.0.3",
     "drizzle-orm": "^0.45.2",
     "express": "^5.2.1",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "semver": "^7.8.4",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {