From 2e8c3b65d8e5b02d2096cc23589a4e225be1e0bd Mon Sep 17 00:00:00 2001
From: eleven_qy <64311644+alph-cmky@users.noreply.github.com>
Date: Fri, 29 May 2026 18:06:34 +0800
Subject: [PATCH] docs: add basic agent workspace example

---
 docs/development/task-backlog.md              |  8 +--
 examples/basic-agent-workspace/README.md      | 36 +++++++++++
 .../agents/reviewer.json                      | 19 ++++++
 .../workflows/review-flow.json                | 61 +++++++++++++++++++
 4 files changed, 120 insertions(+), 4 deletions(-)
 create mode 100644 examples/basic-agent-workspace/README.md
 create mode 100644 examples/basic-agent-workspace/agents/reviewer.json
 create mode 100644 examples/basic-agent-workspace/workflows/review-flow.json

diff --git a/docs/development/task-backlog.md b/docs/development/task-backlog.md
index 5f5cfce..10fdc04 100644
--- a/docs/development/task-backlog.md
+++ b/docs/development/task-backlog.md
@@ -554,10 +554,10 @@ Status markers:
 
 **Tasks:**
 
-- [ ] Add one code reviewer agent.
-- [ ] Add one review workflow with Start, Agent, Human Approval, and End.
-- [ ] Document how to run the demo locally.
-- [ ] Commit with message `docs: add basic agent workspace example`.
+- [x] Add one code reviewer agent.
+- [x] Add one review workflow with Start, Agent, Human Approval, and End.
+- [x] Document how to run the demo locally.
+- [x] Commit with message `docs: add basic agent workspace example`.
 
 **Acceptance Criteria:**
 
diff --git a/examples/basic-agent-workspace/README.md b/examples/basic-agent-workspace/README.md
new file mode 100644
index 0000000..d111e65
--- /dev/null
+++ b/examples/basic-agent-workspace/README.md
@@ -0,0 +1,36 @@
+# Basic Agent Workspace
+
+This example shows a small local-first AgentDeck workspace with one reviewer agent and one review workflow. It is meant to be inspected directly from the repository before a user creates their own workspace.
+
+## Contents
+
+- `agents/reviewer.json`: a read-only code reviewer agent.
+- `workflows/review-flow.json`: a review workflow with Start, Agent, Human Approval, and End nodes.
+
+## Local Inspection
+
+From the repository root:
+
+```bash
+cat examples/basic-agent-workspace/agents/reviewer.json
+cat examples/basic-agent-workspace/workflows/review-flow.json
+```
+
+To check the example while developing:
+
+```bash
+pnpm lint
+pnpm format
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## Demo Flow
+
+1. A user asks for a review of the current diff.
+2. The `reviewer` agent reads repository context and summarizes risks.
+3. The workflow pauses for a maintainer approval decision before any follow-up action.
+4. The run ends after the approval step records the decision.
+
+The reviewer agent intentionally defaults to read-only permissions. It can inspect code and produce review notes, but it cannot write files, install dependencies, run arbitrary commands, commit, or push.
diff --git a/examples/basic-agent-workspace/agents/reviewer.json b/examples/basic-agent-workspace/agents/reviewer.json
new file mode 100644
index 0000000..2c236d6
--- /dev/null
+++ b/examples/basic-agent-workspace/agents/reviewer.json
@@ -0,0 +1,19 @@
+{
+  "id": "reviewer",
+  "name": "Code Reviewer",
+  "description": "Reviews local code changes for regressions, security risks, and missing tests.",
+  "prompt": "Review the current diff. Prioritize correctness, security-sensitive behavior, missing tests, and changes that could break existing workflows. Keep findings concise and reference files or workflow nodes when possible.",
+  "model": "gpt-5",
+  "tools": ["repo.read", "git.diff", "workflow.inspect"],
+  "permissions": {
+    "read": true,
+    "write": false,
+    "install": false,
+    "arbitraryCommands": false,
+    "commit": false,
+    "push": false
+  },
+  "memoryScope": "workspace",
+  "runtimePreference": "codex",
+  "workspaceRoot": "/absolute/path/to/your/project"
+}
diff --git a/examples/basic-agent-workspace/workflows/review-flow.json b/examples/basic-agent-workspace/workflows/review-flow.json
new file mode 100644
index 0000000..c1490be
--- /dev/null
+++ b/examples/basic-agent-workspace/workflows/review-flow.json
@@ -0,0 +1,61 @@
+{
+  "id": "review-flow",
+  "name": "Review Flow",
+  "version": 1,
+  "status": "draft",
+  "variables": {
+    "reviewScope": "current diff",
+    "approvalRole": "maintainer"
+  },
+  "permissions": {
+    "read": true,
+    "write": false,
+    "install": false,
+    "arbitraryCommands": false,
+    "commit": false,
+    "push": false
+  },
+  "nodes": [
+    {
+      "id": "start",
+      "type": "start",
+      "label": "Start"
+    },
+    {
+      "id": "agent-review",
+      "type": "agent",
+      "label": "Review current diff",
+      "agentId": "reviewer"
+    },
+    {
+      "id": "human-approval",
+      "type": "humanApproval",
+      "label": "Maintainer approval",
+      "approverRole": "maintainer"
+    },
+    {
+      "id": "end",
+      "type": "end",
+      "label": "End"
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge-start-review",
+      "from": "start",
+      "to": "agent-review"
+    },
+    {
+      "id": "edge-review-approval",
+      "from": "agent-review",
+      "to": "human-approval"
+    },
+    {
+      "id": "edge-approval-end",
+      "from": "human-approval",
+      "to": "end"
+    }
+  ],
+  "createdAt": "2026-05-29T00:00:00.000Z",
+  "updatedAt": "2026-05-29T00:00:00.000Z"
+}