@waishnav/devspace 1.0.2 → 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

@@ -79,11 +79,29 @@ new context during later tool calls.
 
 Skills are enabled by default for coding-agent workflows.
 
-DevSpace discovers skills from:
+DevSpace discovers standard Agent Skills from:
 
-- `DEVSPACE_AGENT_DIR`, which defaults to `~/.codex`
-- project `.pi/skills`
-- optional paths from `DEVSPACE_SKILL_PATHS`
+- `~/.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
 advertised `SKILL.md` before following that skill.
@@ -93,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`
@@ -109,15 +132,21 @@ 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`:
+Use `DEVSPACE_TOOL_MODE=full` to restore dedicated search and directory tools.
+
+The experimental Codex-style surface is enabled with
+`DEVSPACE_TOOL_MODE=codex`. It exposes:
 
 - `open_workspace`
-- `read_file`
-- `write_file`
-- `edit_file`
-- `run_shell`
+- `read`
+- `apply_patch`
+- `exec_command`
+- `write_stdin`
 
-Use `DEVSPACE_TOOL_MODE=full` to restore dedicated search and directory tools.
+In this mode, `write`, `edit`, `bash`, `grep`, `glob`, and `ls` are not
+registered. `exec_command` returns a process session ID when a command is still
+running after its yield window. Use `write_stdin` to poll it, send input, resize
+a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.
 
 ## Show Changes
 
@@ -129,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,19 +59,23 @@ MCP clients discover metadata from:
 
 ## Tool Modes
 
-`DEVSPACE_TOOL_NAMING` controls tool names.
+`DEVSPACE_TOOL_MODE` controls the tool surface.
 
 | Value | Behavior |
 | --- | --- |
-| `short` | Default. Uses `read`, `edit`, `bash`, and related names. |
-| `legacy` | Uses `read_file`, `edit_file`, `run_shell`, and related names. |
+| `minimal` | Default. Exposes `open_workspace`, `read`, `write`, `edit`, and `bash`. Clients use `bash` with tools such as `rg`, `find`, and `ls` for inspection. |
+| `full` | Exposes the minimal tools plus dedicated `grep`, `glob`, and `ls` tools. |
+| `codex` | Experimental. Exposes `open_workspace`, `read`, `apply_patch`, `exec_command`, and `write_stdin`. Existing mutation and shell tools are hidden. |
 
-`DEVSPACE_TOOL_MODE` controls the tool surface.
+`DEVSPACE_MINIMAL_TOOLS` remains a backward-compatible alias when
+`DEVSPACE_TOOL_MODE` is unset: `1` selects `minimal` and `0` selects `full`.
+The `codex` mode must be selected through `DEVSPACE_TOOL_MODE` and always uses
+its fixed short tool names regardless of `DEVSPACE_TOOL_NAMING`.
 
-| Value | Behavior |
-| --- | --- |
-| `minimal` | Default. Disables dedicated search and list tools. Clients use the shell tool with `rg`, `grep`, `find`, `ls`, or `tree` for inspection. |
-| `full` | Enables dedicated `grep`, `glob`, and `ls` tools. |
+Codex-mode commands run without a PTY by default. Set `tty: true` on
+`exec_command` for interactive terminal programs. PTY support uses the optional
+`node-pty` dependency; `write_stdin` can send input, poll output, and resize PTY
+sessions.
 
 ## Widgets
 
@@ -88,13 +92,45 @@ MCP clients discover metadata from:
 | Variable | Purpose |
 | --- | --- |
 | `DEVSPACE_SKILLS` | Set to `0` to hide skills. Enabled by default. |
-| `DEVSPACE_AGENT_DIR` | Defaults to `~/.codex`. |
-| `DEVSPACE_SKILL_PATHS` | Optional comma-separated skill directories. |
+| `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/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:
 
 ```bash
-DEVSPACE_SKILL_PATHS="$HOME/.codex/skills,$HOME/.claude/skills" \
+DEVSPACE_SKILL_PATHS="$HOME/.claude/skills,$HOME/company/skills" \
 npx @waishnav/devspace serve
 ```
 
@@ -123,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

@@ -15,7 +15,7 @@ If you installed globally, confirm npm's global bin directory is on `PATH`.
 
 ## Unsupported Node Version
 
-DevSpace requires Node `>=20.12 <27`.
+DevSpace requires Node `>=22.19 <27`.
 
 Check:
 
@@ -193,11 +193,30 @@ Skills are enabled by default. Check:
 DEVSPACE_SKILLS=1 npx @waishnav/devspace serve
 ```
 
-DevSpace looks in:
+DevSpace looks in standard Agent Skills locations:
 
-- `DEVSPACE_AGENT_DIR`, defaulting to `~/.codex`
-- project `.pi/skills`
-- `DEVSPACE_SKILL_PATHS`
+- `~/.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
 `SKILL.md` before reading other files inside the skill directory.

package/docs/setup.md

@@ -5,7 +5,7 @@ projects through DevSpace.
 
 ## Requirements
 
-- Node `>=20.12 <27`; Node 22 LTS is recommended
+- Node `>=22.19 <27`
 - npm
 - Git
 - Bash, including Git Bash or WSL on Windows

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:
+```