Add local agent profile examples

docs/agent-profile-schema.md

@@ -0,0 +1,115 @@
+# DevSpace agent profile schema
+
+DevSpace agent profiles are a draft format for describing local coding-agent
+CLIs in a way that can later be validated, rendered to the model, and migrated
+to protocol-backed backends such as ACP.
+
+This page documents copyable templates only. DevSpace does not currently parse
+or load `~/.devspace/agents/*.md` profiles.
+
+## File format
+
+Profiles are Markdown files with YAML front matter. The front matter is intended
+for DevSpace. The Markdown body is intended for the model and the user.
+
+## Top-level fields
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `schema` | Yes | Schema identifier. Use `devspace-agent/v1`. |
+| `name` | Yes | Stable profile name, usually matching the file basename. |
+| `description` | Yes | One-sentence purpose shown in future agent catalogs. |
+| `provider` | Yes | Provider key, such as `codex`, `claude`, `opencode`, `cursor`, `pi`, or `copilot`. |
+| `backend` | Yes | Backend type. Current examples use `cli`; future profiles may use `acp_stdio`. |
+| `capabilities` | Yes | Conservative capability flags. |
+| `workspace` | Yes | Default workspace and isolation behavior. |
+| `actions` | Yes | Lifecycle commands or DevSpace-managed lifecycle strategies. |
+| `safety` | Yes | Guardrails the model should preserve when delegating work. |
+
+## Capability fields
+
+| Field | Description |
+| --- | --- |
+| `read` | Agent can inspect files. |
+| `write` | Agent can edit files. |
+| `shell` | Agent can run project commands. |
+| `background` | Agent can run as a long-lived or pollable process. |
+| `resume` | Agent supports continuing an existing external session. |
+
+Capabilities should describe what the profile allows, not every capability the
+underlying CLI may have. Prefer conservative defaults for examples.
+
+## Workspace fields
+
+| Field | Values | Description |
+| --- | --- | --- |
+| `default` | `current` | Start from the current DevSpace workspace by default. |
+| `isolation` | `none`, `user_decides`, `worktree`, `temp` | How isolated the task should be before delegation. |
+| `writeMode` | `read_only`, `allowed` | Whether this profile is allowed to write files. |
+
+Use the least isolated environment that safely matches the task. Read-only
+exploration can usually run in the current workspace. Risky, parallel, or
+competing implementations should use a branch or worktree.
+
+## Actions
+
+Actions describe lifecycle behavior. CLI actions should use `command` plus an
+`args` array rather than a free-form shell string.
+
+```yaml
+actions:
+  start:
+    command: codex
+    args:
+      - "exec"
+      - "--json"
+      - "-C"
+      - "<workspace>"
+      - "<prompt>"
+    background: true
+    output: jsonl
+
+  read:
+    strategy: devspace_process_poll
+
+  cancel:
+    strategy: devspace_process_signal
+    signal: SIGINT
+
+  diff:
+    strategy: git_diff
+```
+
+Argument arrays are easier to validate, escape, log, and migrate to another
+backend than shell strings.
+
+## Placeholders
+
+| Placeholder | Meaning |
+| --- | --- |
+| `<workspace>` | Absolute path of the selected workspace or worktree. |
+| `<prompt>` | Delegation prompt generated by the supervising model. |
+| `<externalSessionId>` | Session identifier returned by the local agent CLI. |
+
+Future implementations should reject unknown placeholders by default.
+
+## Strategy values
+
+| Strategy | Description |
+| --- | --- |
+| `resume_command` | Run another CLI command to continue an existing agent session. |
+| `fresh_prompt_with_context` | Start a fresh prompt that includes prior summaries and review context. |
+| `devspace_process_poll` | Poll a DevSpace-managed process session for output. |
+| `devspace_process_signal` | Send a signal to a DevSpace-managed process session. |
+| `git_diff` | Inspect changed files with Git after the agent completes. |
+| `none` | The action is intentionally unavailable. |
+
+## Safety fields
+
+| Field | Description |
+| --- | --- |
+| `requireExplicitUserIntent` | Delegate only when the user asks for a local agent, named agent, parallel work, or second opinion. |
+| `allowWrites` | Whether this profile may modify files. Should match `capabilities.write`. |
+| `requireReviewBeforeFinal` | Supervising model should review the agent's answer before presenting it as final. |
+| `requireDiffReview` | Supervising model should inspect the resulting diff before accepting implementation work. |
+| `requireTestsOrExplanation` | Worker should run relevant checks or explain why checks were skipped. |

examples/agents/README.md

@@ -0,0 +1,15 @@
+# Local agent profile examples
+
+These files are starter templates for future DevSpace local-agent profiles.
+They are examples only and are not loaded from this directory.
+
+To experiment with a profile, copy it into:
+
+```text
+~/.devspace/agents/
+```
+
+Then adjust the commands and flags for your local setup.
+
+See `docs/agent-profile-schema.md` for the draft schema.
+

examples/agents/claude-implementer.md

@@ -0,0 +1,107 @@
+---
+schema: devspace-agent/v1
+name: claude-implementer
+description: Claude Code implementation worker for larger edits, refactors, and follow-up loops.
+provider: claude
+backend: cli
+
+capabilities:
+  read: true
+  write: true
+  shell: true
+  background: true
+  resume: true
+
+workspace:
+  default: current
+  isolation: user_decides
+  writeMode: allowed
+
+actions:
+  start:
+    command: claude
+    args:
+      - -p
+      - --output-format
+      - stream-json
+      - "<prompt>"
+    background: true
+    output: stream-json
+
+  followup:
+    strategy: resume_command
+    command: claude
+    args:
+      - --resume
+      - "<externalSessionId>"
+      - -p
+      - --output-format
+      - stream-json
+      - "<prompt>"
+
+  list:
+    command: claude
+    args:
+      - agents
+      - --json
+
+  read:
+    strategy: devspace_process_poll
+
+  cancel:
+    strategy: devspace_process_signal
+    signal: SIGINT
+
+  diff:
+    strategy: git_diff
+
+safety:
+  requireExplicitUserIntent: true
+  allowWrites: true
+  requireDiffReview: true
+  requireTestsOrExplanation: true
+---
+
+Use this agent when the task benefits from a stronger implementation worker.
+
+Good tasks:
+
+- Multi-file implementation.
+- Refactor with clear boundaries.
+- Test repair loop.
+- Apply detailed review comments.
+- Continue an already-started implementation.
+
+Worker prompt style:
+
+```text
+You are a local Claude Code implementation worker under ChatGPT supervision.
+
+Goal:
+<goal>
+
+Context:
+<repo/module/context>
+
+Plan:
+<numbered plan>
+
+Constraints:
+<constraints>
+
+Rules:
+- Keep changes focused.
+- Avoid unrelated rewrites.
+- Preserve public behavior unless asked.
+- Run or explain relevant tests.
+- Return a concise final report.
+
+Final report format:
+summary:
+files_changed:
+tests_run:
+risks:
+blockers:
+follow_up_needed:
+```
+

examples/agents/codex-explorer.md

@@ -0,0 +1,92 @@
+---
+schema: devspace-agent/v1
+name: codex-explorer
+description: Read-only Codex agent for bounded codebase questions and architecture exploration.
+provider: codex
+backend: cli
+
+capabilities:
+  read: true
+  write: false
+  shell: false
+  background: true
+  resume: true
+
+workspace:
+  default: current
+  isolation: none
+  writeMode: read_only
+
+actions:
+  start:
+    command: codex
+    args:
+      - "exec"
+      - "--json"
+      - "-C"
+      - "<workspace>"
+      - "<prompt>"
+    background: true
+    output: jsonl
+
+  followup:
+    strategy: resume_command
+    command: codex
+    args:
+      - "exec"
+      - resume
+      - "<externalSessionId>"
+      - "--json"
+      - "<prompt>"
+
+  read:
+    strategy: devspace_process_poll
+
+  cancel:
+    strategy: devspace_process_signal
+    signal: SIGINT
+
+  diff:
+    strategy: none
+
+safety:
+  requireExplicitUserIntent: true
+  allowWrites: false
+  requireReviewBeforeFinal: true
+---
+
+Use this agent when the user wants a bounded read-only investigation, second
+opinion, or explanation of a code path.
+
+Good tasks:
+
+- Find where a feature is implemented.
+- Explain an architecture boundary.
+- Review a module.
+- Identify likely files for a future change.
+
+Worker prompt style:
+
+```text
+You are a read-only codebase explorer.
+
+Question:
+<question>
+
+Scope:
+<files/directories/modules>
+
+Rules:
+- Stay in review and explanation mode.
+- Cite file paths and symbols.
+- Separate facts from guesses.
+- Keep the answer concise.
+
+Final report format:
+answer:
+evidence:
+relevant_files:
+confidence:
+unknowns:
+```
+