diff --git a/docs/agent-profile-schema.md b/docs/agent-profile-schema.md
new file mode 100644
index 0000000..4d52fd5
--- /dev/null
+++ b/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. |
diff --git a/examples/agents/README.md b/examples/agents/README.md
new file mode 100644
index 0000000..90559a5
--- /dev/null
+++ b/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.
+
diff --git a/examples/agents/claude-implementer.md b/examples/agents/claude-implementer.md
new file mode 100644
index 0000000..eb15371
--- /dev/null
+++ b/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:
+```
+
diff --git a/examples/agents/codex-explorer.md b/examples/agents/codex-explorer.md
new file mode 100644
index 0000000..961d53a
--- /dev/null
+++ b/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:
+```
+
diff --git a/examples/agents/codex-worker.md b/examples/agents/codex-worker.md
new file mode 100644
index 0000000..17c1fa7
--- /dev/null
+++ b/examples/agents/codex-worker.md
@@ -0,0 +1,103 @@
+---
+schema: devspace-agent/v1
+name: codex-worker
+description: Codex implementation worker for focused, user-approved coding tasks.
+provider: codex
+backend: cli
+
+capabilities:
+  read: true
+  write: true
+  shell: true
+  background: true
+  resume: true
+
+workspace:
+  default: current
+  isolation: user_decides
+  writeMode: allowed
+
+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: git_diff
+
+safety:
+  requireExplicitUserIntent: true
+  allowWrites: true
+  requireDiffReview: true
+  requireTestsOrExplanation: true
+---
+
+Use this agent when ChatGPT has already planned a focused implementation and
+the user wants Codex to execute it locally.
+
+Good tasks:
+
+- Implement a small feature from a clear plan.
+- Fix a bug with known reproduction steps.
+- Add tests for an existing code path.
+- Apply review comments.
+
+Worker prompt style:
+
+```text
+You are a local implementation worker under ChatGPT supervision.
+
+Goal:
+<goal>
+
+Plan:
+<numbered implementation plan>
+
+Constraints:
+<constraints>
+
+Files to focus:
+<files>
+
+Tests to run:
+<tests>
+
+Rules:
+- Keep changes focused.
+- Follow existing project style.
+- Avoid unrelated refactors.
+- Report failures clearly.
+- Return a final report.
+
+Final report format:
+summary:
+files_changed:
+tests_run:
+blockers:
+follow_up_needed:
+```
+
diff --git a/examples/agents/copilot-reviewer.md b/examples/agents/copilot-reviewer.md
new file mode 100644
index 0000000..21ccaec
--- /dev/null
+++ b/examples/agents/copilot-reviewer.md
@@ -0,0 +1,93 @@
+---
+schema: devspace-agent/v1
+name: copilot-reviewer
+description: GitHub Copilot CLI reviewer for read-only code questions and review passes.
+provider: copilot
+backend: cli
+
+capabilities:
+  read: true
+  write: false
+  shell: false
+  background: true
+  resume: true
+
+workspace:
+  default: current
+  isolation: none
+  writeMode: read_only
+
+actions:
+  start:
+    command: copilot
+    args:
+      - -p
+      - "<prompt>"
+      - --output-format
+      - json
+    background: true
+    output: json
+
+  followup:
+    strategy: resume_command
+    command: copilot
+    args:
+      - -p
+      - "<prompt>"
+      - --resume
+      - "<externalSessionId>"
+      - --output-format
+      - json
+
+  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 GitHub Copilot-powered second opinion,
+review, or codebase answer.
+
+Good tasks:
+
+- Review changed files.
+- Find likely bug sources.
+- Explain repository structure.
+- Suggest tests.
+
+Worker prompt style:
+
+```text
+You are a read-only Copilot reviewer under ChatGPT supervision.
+
+Question:
+<question>
+
+Scope:
+<scope>
+
+Rules:
+- Stay in review and explanation mode.
+- Cite exact files and symbols.
+- Return concise findings.
+- Separate facts from guesses.
+
+Final report format:
+answer:
+findings:
+evidence:
+relevant_files:
+confidence:
+unknowns:
+```
+
diff --git a/examples/agents/cursor-agent-worker.md b/examples/agents/cursor-agent-worker.md
new file mode 100644
index 0000000..cfa5fe8
--- /dev/null
+++ b/examples/agents/cursor-agent-worker.md
@@ -0,0 +1,62 @@
+---
+schema: devspace-agent/v1
+name: cursor-agent-worker
+description: Cursor Agent worker for fast implementation or review using local Cursor CLI.
+provider: cursor
+backend: cli
+
+capabilities:
+  read: true
+  write: true
+  shell: true
+  background: true
+  resume: false
+
+workspace:
+  default: current
+  isolation: user_decides
+  writeMode: allowed
+
+actions:
+  start:
+    command: "<cursor-agent-cli>"
+    args:
+      - "<print-mode-flag>"
+      - "<json-output-flag>"
+      - "<prompt>"
+    background: true
+    output: stream-json
+
+  followup:
+    strategy: fresh_prompt_with_context
+
+  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 user wants Cursor's local agent or model to quickly
+execute or inspect a task.
+
+Good tasks:
+
+- Fast implementation pass.
+- UI/UX-oriented code review.
+- Alternative implementation idea.
+- Lightweight refactor.
+
+Because this profile uses `fresh_prompt_with_context`, include the previous
+worker summary and review findings when sending follow-up work.
+
diff --git a/examples/agents/opencode-explorer.md b/examples/agents/opencode-explorer.md
new file mode 100644
index 0000000..9aceeb4
--- /dev/null
+++ b/examples/agents/opencode-explorer.md
@@ -0,0 +1,58 @@
+---
+schema: devspace-agent/v1
+name: opencode-explorer
+description: OpenCode read-only explorer for fast codebase lookup and bounded questions.
+provider: opencode
+backend: cli
+
+capabilities:
+  read: true
+  write: false
+  shell: false
+  background: true
+  resume: true
+
+workspace:
+  default: current
+  isolation: none
+  writeMode: read_only
+
+actions:
+  start:
+    command: "<opencode-cli>"
+    args:
+      - "<json-mode-flag>"
+      - "<workspace-flag>"
+      - "<workspace>"
+      - "<prompt>"
+    background: true
+    output: json
+
+  followup:
+    strategy: fresh_prompt_with_context
+
+  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 for fast, read-only codebase exploration.
+
+Good tasks:
+
+- Find relevant files.
+- Explain a subsystem.
+- Identify test coverage gaps.
+- Compare possible implementation locations.
+
diff --git a/examples/agents/pi-reviewer.md b/examples/agents/pi-reviewer.md
new file mode 100644
index 0000000..f65feb2
--- /dev/null
+++ b/examples/agents/pi-reviewer.md
@@ -0,0 +1,91 @@
+---
+schema: devspace-agent/v1
+name: pi-reviewer
+description: Pi read-only reviewer for quick code review and targeted questions.
+provider: pi
+backend: cli
+
+capabilities:
+  read: true
+  write: false
+  shell: false
+  background: true
+  resume: true
+
+workspace:
+  default: current
+  isolation: none
+  writeMode: read_only
+
+actions:
+  start:
+    command: pi
+    args:
+      - -p
+      - --mode
+      - json
+      - "<prompt>"
+    background: true
+    output: json
+
+  followup:
+    strategy: resume_command
+    command: pi
+    args:
+      - -p
+      - --mode
+      - json
+      - --session-id
+      - "<externalSessionId>"
+      - "<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 for lightweight review and targeted read-only investigation.
+
+Good tasks:
+
+- Review a diff.
+- Find possible bugs.
+- Explain a small subsystem.
+- Check whether tests cover an edge case.
+
+Worker prompt style:
+
+```text
+You are a read-only local code reviewer.
+
+Question:
+<question>
+
+Scope:
+<scope>
+
+Rules:
+- Stay in review mode.
+- Cite evidence.
+- Focus on actionable findings.
+- Avoid broad rewrites.
+
+Final report format:
+findings:
+evidence:
+risk_level:
+recommended_next_steps:
+unknowns:
+```
+
diff --git a/package.json b/package.json
index e16711b..48a2165 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "scripts",
     "README.md"
   ],