@aion0/forge 0.5.22 → 0.5.24

package/lib/help-docs/11-workspace.md

@@ -2,253 +2,809 @@
 
 ## Overview
 
-Workspace is a multi-agent orchestration system. You define a team of **Smiths** (agents) with roles, dependencies, and steps. Smiths run as long-lived daemons, communicate via a message bus, and can be controlled manually or automatically.
+Workspace is a multi-agent orchestration system. You define a team of **Smiths** (agents) that coordinate via DAG dependencies, a message bus, and request/response documents. Smiths run as long-lived daemons or can be manually driven from a terminal.
 
-## Concepts
+## Core Concepts
 
 | Term | Description |
 |------|-------------|
-| **Smith** | A long-running agent instance in the workspace |
-| **Agent Profile** | A reusable configuration (CLI type + env vars + model) that can be assigned to any smith |
-| **Message Bus** | Inter-agent communication system with two message categories |
+| **Smith** | A long-running agent in the workspace (Claude Code, Codex, etc.) |
+| **Primary Smith** | The coordinator smith — runs at project root, typically Lead |
 | **Input Node** | User-provided requirements node (append-only history) |
-| **Daemon** | Background execution loop that keeps smiths alive and consuming messages |
+| **DAG** | Directed acyclic graph of agent dependencies (no cycles allowed) |
+| **Request Document** | YAML doc describing a task, flows through status stages |
+| **Topology Cache** | Live in-memory map of all smiths, auto-injected into every task |
+| **Message Bus** | Inter-agent messaging (notifications + direct messages) |
+| **Daemon** | Background loop that keeps smiths alive and consumes messages |
 
-## Three-Layer State Model
+## Two-Layer State Model
 
-Each smith has three independent status layers displayed on the node:
+Each smith has two independent status layers displayed on the node:
 
 | Layer | Values | Description |
 |-------|--------|-------------|
-| **Smith Status** | `down` / `active` | Whether the daemon process is running |
-| **Mode** | `auto` / `manual` | `auto` = daemon-driven, `manual` = user in terminal (purple) |
+| **Smith Status** | `down` / `starting` / `active` | Daemon lifecycle |
 | **Task Status** | `idle` / `running` / `done` / `failed` | Current work status |
 
-- **Mode controls message consumption**: `manual` pauses inbox processing (same as `running`)
-- **Smith Status controls the daemon loop**: `down` stops the message loop entirely
-- **Task Status tracks work**: unaffected by mode changes
+- **Smith Status** is controlled by daemon start/stop
+- **Task Status** tracks individual work execution
+- Session-monitor auto-marks `done` after 20 min of file stability (fallback if Stop hook misses)
+
+## Creating Smiths
+
+### Add Agent Modal
+
+Click **+ Add Agent** in workspace header to open config modal. Fields:
+
+| Field | Description |
+|-------|-------------|
+| **Template** | Quick-select preset (Lead ★, PM, Engineer, QA, Reviewer, UI Designer, Design Evaluator) |
+| **Saved Templates** | User-saved smith configs (if any) |
+| **Icon + Label** | Display on node (emoji icon + agent name) |
+| **Backend** | `cli` (subscription, Claude Code/Codex/Aider) or `api` (API key) |
+| **Agent / Profile** | Which CLI or API profile to use (from Settings) |
+| **Role / System Prompt** | Core instructions, synced to `CLAUDE.md` in workDir |
+| **Plugin Instances** | MCP plugins the agent can use (playwright, shell-command, llm-vision) |
+| **Depends On** | Upstream agents this one depends on (creates DAG edges) |
+| **Work Dir** | Relative path within project where agent runs |
+| **Outputs** | Expected output paths (informational, no longer enforces uniqueness) |
+| **Primary** | Only one per workspace — runs at root, gets fixed session, persistent |
+| **Requires Approval** | User must approve each inbox message before processing |
+| **Terminal Mode** | Keep a tmux+CLI session alive (persistent session) |
+| **Skip Permissions** | Auto-approve tool calls (`--dangerously-skip-permissions`) |
+| **Model** | Override model (claude-sonnet-4-6, claude-opus-4-6, etc.) |
+| **Steps** | Ordered task steps (Label: Prompt) |
+| **Watch** | Autonomous file/git/command monitoring |
+
+### Preset Templates
+
+| Preset | Icon | Role | Notes |
+|--------|------|------|-------|
+| **Lead** ★ | 👑 | Primary coordinator — SOP-driven intake, delegation, gap coverage | **Recommended for Primary smith** |
+| **PM** | 📋 | Product Manager — versioned PRDs, testable acceptance_criteria | Writes to `docs/prd/` |
+| **Architect** | 🏗️ | Breaks requirements into request documents | Uses `create_request` |
+| **Engineer** | 🔨 | Claims requests, implements code | Uses `claim_request` + `update_response` |
+| **QA** | 🧪 | Writes Playwright tests, verifies acceptance_criteria | Uses `update_response(section: qa)` |
+| **Reviewer** | 🔍 | Reviews code quality, security, performance | Uses `update_response(section: review)` |
+| **UI Designer** | 🎨 | Writes UI code, iterates via screenshots | Needs playwright plugin |
+| **Design Evaluator** | 🔍 | Scores UI implementations visually | Needs playwright + llm-vision |
+
+Primary presets (Lead) have orange ★ badge and are recommended when designing workspaces with a coordinator.
+
+## Smith Templates (Save/Load)
+
+### Save a Smith as Template
+
+On any configured smith node, click **💾** button:
+- Enter template name + optional description
+- Stored at `~/.forge/data/smith-templates/<id>.json`
+- Appears in "Saved Templates" section when adding new agents
+
+### Export / Import
+
+- **📤 Export** (in Edit Agent modal): download current config as JSON file
+- **📂 Import from file**: load a JSON template when creating a new agent
+- Share template files across machines/workspaces
+
+API endpoints:
+- `GET /api/smith-templates` — list all
+- `POST /api/smith-templates` — save (body: `{name, icon, description, config}`)
+- `POST /api/smith-templates` with `{action: "delete", id}` — remove
 
 ## Dependencies (DAG)
 
-Dependencies must form a **directed acyclic graph** (DAG). Circular dependencies are rejected when adding or editing agents.
+Dependencies must form a **directed acyclic graph**. Circular deps rejected at add/edit time.
 
 ```
 Input → PM → Engineer → QA → Reviewer
+          ↘________________↗
+             (both notify Reviewer)
 ```
 
-- Upstream agents complete first, then broadcast to downstream
-- Each agent knows its upstream (dependsOn) and the system prevents cycles
+- Upstream completes first, broadcasts to downstream
+- Each agent declares `dependsOn` (upstream agent IDs)
 
-## Message System
+## Request/Response Document System
+
+Structured YAML documents for multi-agent delivery workflows.
+
+### Storage Layout
+
+```
+<project>/.forge/requests/
+├── REQ-20260403-001/
+│   ├── request.yml    # Architect/Lead creates
+│   └── response.yml   # Engineer/Reviewer/QA update
+└── REQ-20260403-002/
+    ├── request.yml
+    └── response.yml
+```
 
-### Two Message Categories
+### Status Lifecycle
 
-| Category | Direction | Behavior | Use Case |
-|----------|-----------|----------|----------|
-| **Notification** | Follows DAG (upstream → downstream) | Auto-broadcast on completion, downstream discards reverse notifications | "I'm done, here's what I did" |
-| **Ticket** | Any direction (ignores DAG) | 1-to-1, independent lifecycle, retry limits | Bug reports, fix requests |
+```
+open → in_progress → review → qa → done
+```
 
-### Notification Messages (Default)
+- **open**: request created, no one claimed yet
+- **in_progress**: Engineer claimed and is implementing
+- **review**: Engineer done, Reviewer should review
+- **qa**: Reviewer approved, QA should test
+- **done**: QA passed
+
+### Request YAML Schema
+
+```yaml
+id: "REQ-20260403-001"
+batch: "delivery-20260403"
+title: "User authentication"
+description: "Detailed description..."
+modules:
+  - name: "auth-service"
+    description: "JWT token generation"
+    acceptance_criteria:
+      - "Login returns access token"
+      - "Expired tokens return 401"
+priority: "high"  # high | medium | low
+status: "open"
+assigned_to: ""
+created_by: "Architect"
+created_at: "2026-04-03T10:00:00Z"
+updated_at: "2026-04-03T10:00:00Z"
+```
 
-When a smith completes:
-- If it was processing an **upstream** message → broadcast to all downstream agents
-- If it was processing a **downstream** message → no broadcast, just mark the message done (sender checks outbox status)
-- Each message carries a `causedBy` field tracing which inbox message triggered it
+### Response YAML Schema
+
+```yaml
+request_id: "REQ-20260403-001"
+status: "done"
+engineer:
+  completed_at: "2026-04-03T11:30:00Z"
+  files_changed: ["src/auth/service.ts"]
+  notes: "Implemented with jose library"
+review:
+  completed_at: "2026-04-03T12:00:00Z"
+  result: "approved"  # approved | changes_requested | rejected
+  findings: []
+qa:
+  completed_at: "2026-04-03T12:30:00Z"
+  result: "passed"  # passed | failed
+  test_files: ["tests/e2e/auth.spec.ts"]
+  findings: []
+```
 
-### Ticket Messages
+### Auto-Notification via DAG
 
-- Created via `create_ticket` API or forge skills
-- Have their own lifecycle: `open → in_progress → fixed → verified → closed`
-- Retry limit (default 3), exceeding marks ticket as failed
-- Not affected by DAG direction — any agent can ticket any agent
+When `create_request` or `update_response` is called, the orchestrator automatically sends notifications to all downstream agents (based on `dependsOn`). Agents don't manually send messages — they operate on the document and downstream smiths are notified.
 
-### CausedBy Chain
+## MCP Tools (for Smiths)
 
-Every outgoing message carries `causedBy` linking to the inbox message that triggered it:
+Agents use these MCP tools (via forge-mcp-server):
 
-```json
-{
-  "from": "qa-123",
-  "to": "reviewer-456",
-  "action": "upstream_complete",
-  "causedBy": {
-    "messageId": "msg-789",
-    "from": "engineer-111",
-    "to": "qa-123"
-  }
-}
+### Topology & Status
+
+| Tool | Description |
+|------|-------------|
+| `get_agents` | Live workspace topology — all agents, roles, DAG flow, status, missing standard roles |
+| `get_status` | Live status snapshot of all agents (smith+task status) |
+| `get_inbox` | Pending/failed inbox messages for current agent |
+
+### Request Documents
+
+| Tool | Description |
+|------|-------------|
+| `create_request` | Create a new request document (auto-notifies downstream) |
+| `claim_request` | Atomically claim an open request (prevents duplicate work) |
+| `list_requests` | List requests, filter by `batch` or `status` |
+| `get_request` | Read full request + response content |
+| `update_response` | Update response section (engineer/review/qa), auto-advances status |
+
+### Communication
+
+| Tool | Description |
+|------|-------------|
+| `send_message` | Send a direct message to another agent |
+| `mark_message_done` | Mark a processed message as done |
+| `check_outbox` | Check delivery status of sent messages |
+
+### Other
+
+| Tool | Description |
+|------|-------------|
+| `run_plugin` | Execute a plugin action (e.g., Playwright test/screenshot) |
+| `sync_progress` | Report work progress to workspace |
+| `trigger_pipeline` | Trigger a pipeline from a smith |
+| `get_pipeline_status` | Check pipeline run status |
+
+## Topology Cache (Auto-Injected Context)
+
+Every task execution automatically includes a **Workspace Team** section in the agent's context:
+
+```
+## Workspace Team
+Flow: Lead → Engineer → QA → Reviewer
+Missing: architect, pm
+- 👑 Lead ← you [active/running]: Lead Coordinator — Primary agent...
+- 🔨 Engineer [active/idle]: Senior Software Engineer — You design...
+- 🧪 QA [active/idle]: QA Engineer — You ensure quality...
+- 🔍 Reviewer [active/idle]: Senior Code Reviewer — You review...
 ```
 
-This enables:
-- **Loop prevention**: Notifications from downstream are silently discarded
-- **Outbox tracking**: Sender can verify their message was processed
-- **Audit trail**: Every message traces back to its trigger
+- **Rebuilt on every agent change** (add/remove/update/status change)
+- **Auto-injected** via `buildUpstreamContext` — agents don't need to call `get_agents` at start
+- **Missing roles hint** — shows which standard roles are absent (so Lead knows to cover gaps)
+- Agents can still call `get_agents` for detailed mid-task status
+
+## Lead / Primary Smith
+
+The **Lead** preset is designed as a Primary coordinator:
 
-### Message Receive Rules
+- Runs at project root (`workDir: ./`)
+- `persistentSession: true` — always has a terminal
+- `primary: true` — fixed session ID, gets ★ badge on node
+- Orange border + ★ in preset picker (recommended for primary role)
 
-When a message arrives at an agent's inbox:
+### Lead SOP
 
-1. **Tickets** → always accepted (with retry limit check)
-2. **Notification with causedBy matching own outbox** → accepted (response to my request)
-3. **Notification from downstream agent** → silently discarded (prevents reverse flow)
-4. **Notification from upstream or no causedBy** → accepted (normal DAG flow)
+1. **Intake**: Read Workspace Team, classify requirement, route by team composition
+2. **Delegate**: `create_request` for each module with testable `acceptance_criteria`
+3. **Cover Gaps**: If a role is missing (no Engineer/QA/Reviewer), handle it yourself
+4. **Monitor**: `get_status` + `list_requests` to unblock stuck agents
+5. **Quality Gate**: Verify all requests done/approved/passed before declaring complete
 
-### Message Status Flow
+### Gap Coverage
 
-`pending` → `running` → `done` / `failed`
+| Missing Role | Lead Does |
+|--------------|-----------|
+| PM/Architect | Break requirements into modules with acceptance_criteria |
+| Engineer | Implement code, update_response(section: engineer) |
+| QA | Write/run tests, update_response(section: qa) |
+| Reviewer | Review code for quality/security, update_response(section: review) |
 
-- Only one message processed at a time per agent
-- `currentMessageId` persisted in agent state for crash recovery
+## Message Bus
 
-## Manual Mode
+Two message categories:
 
-Click the **⌨️** button on any smith to open a terminal:
-- Mode switches to `manual` (purple indicator on node)
-- Inbox message processing pauses (messages stay pending)
-- A tmux session opens with CLI + profile env + forge env vars (`FORGE_AGENT_ID`, `FORGE_WORKSPACE_ID`, `FORGE_PORT`)
-- Forge Skills auto-installed for inter-agent communication
-- Close terminal → mode returns to `auto`, pending messages resume processing
+| Category | Direction | Use Case |
+|----------|-----------|----------|
+| **Notification** | DAG-based (upstream → downstream) | "I'm done, here's what I did" |
+| **Direct Message** | Any direction | Questions, bug reports, coordination |
 
-### Forge Skills in Terminal
+### Notification Flow
 
-| Skill | Description |
+- When agent completes, system broadcasts `task_complete` to all downstream agents
+- Downstream uses `causedBy` field to trace which inbox message triggered their run
+- Messages from downstream → discarded (prevents reverse loops)
+
+### Inbox Management
+
+Each smith has an inbox panel with:
+- **Inbox tab**: incoming messages with status (pending/running/done/failed)
+- **Outbox tab**: sent messages with delivery status
+- **Batch operations**: select all completed → bulk delete, or abort all pending
+
+## Plugins (MCP Plugin System)
+
+Smiths can use MCP plugins for extended capabilities.
+
+### Built-in Plugin Types
+
+| Plugin | Description |
+|--------|-------------|
+| `playwright` | Browser automation — test, screenshot, navigate |
+| `shell-command` | Execute custom shell commands |
+| `llm-vision` | Send screenshots to LLM for visual evaluation |
+
+### Using Plugins in a Smith
+
+1. In Settings → Plugins, install plugin definitions
+2. Create plugin instances (configure endpoints, credentials)
+3. In Add Agent modal, select which instances this smith can access
+4. Smith calls `run_plugin(plugin: "<instance-id>", action: "<action>", params: {...})`
+
+### Recommended Plugins per Preset
+
+- **QA**: `playwright` (e2e testing)
+- **UI Designer**: `playwright` + `shell-command` (screenshots)
+- **Design Evaluator**: `playwright` + `llm-vision` (visual scoring)
+- **Lead**: `playwright` + `shell-command` (fallback for any role)
+
+## Terminal Mode (Manual)
+
+Click **⌨️** on any smith to open a terminal session:
+
+- tmux session opens with CLI + env vars (`FORGE_AGENT_ID`, `FORGE_WORKSPACE_ID`, `FORGE_PORT`)
+- Forge Skills available: `/forge-send`, `/forge-inbox`, `/forge-status`, `/forge-workspace-sync`
+- Session Picker: choose new session, continue existing, or browse all Claude sessions
+- Close terminal → smith returns to auto mode, pending messages resume
+
+## Watch (Autonomous Monitoring)
+
+Agents can monitor file/git/command changes without message-driven triggers.
+
+### Configuration
+
+| Field | Description |
 |-------|-------------|
-| `/forge-send` | Send a message to another smith (blocked if replying to current sender — use for NEW issues only) |
-| `/forge-inbox` | Check incoming messages |
-| `/forge-status` | Check all smiths' status |
-| `/forge-workspace-sync` | Sync progress back to workspace |
+| **Interval** | Check frequency in seconds (min 10, default 60) |
+| **Debounce** | Minimum seconds between alerts (default 10) |
+| **Targets** | What to watch (multiple allowed) |
+| **On Change** | Action: `log`, `analyze`, `approve`, or `send_message` |
 
-**Note**: When processing a message from another agent, do NOT use `/forge-send` to reply — the system auto-delivers results via `markMessageDone`. Only use `/forge-send` for new issues to other agents.
+### Target Types
+
+| Type | Description |
+|------|-------------|
+| `Directory` | File mtime changes in a project folder |
+| `Git` | New commits via HEAD hash comparison |
+| `Agent Output` | Another agent's declared output paths |
+| `Agent Log` | Another agent's log file with optional keyword filter |
+| `Session Output` | Claude session tail output |
+| `Command` | Run a shell command, detect output changes |
+| `Agent Status` | Another agent's smithStatus/taskStatus changes |
 
-## Inbox Management
+### Watch Actions
 
-Each smith has an inbox panel with two tabs:
+| Action | Behavior |
+|--------|----------|
+| `Log` | Write alert to agent log (no token cost) |
+| `Analyze` | Auto-wake agent to analyze changes (costs tokens) |
+| `Approve` | Create pending approval, user decides |
+| `Send Message` | Send alert to specified agent |
 
-### Inbox Tab
-- Messages received from other smiths
-- Status badges: pending (yellow), running (blue), done (green), failed (red)
-- Ticket messages have purple border + TICKET badge + lifecycle status
-- CausedBy trace shows which agent triggered the message
+## Mascot Animations (Visual Flair)
 
-### Outbox Tab
-- Messages sent by this smith
-- Track delivery status and responses
+Each smith can display an animated companion character next to its node.
 
-### Batch Operations
-- **Select all completed** → batch delete done/failed messages
-- **Abort all pending (N)** → cancel all pending messages at once
-- Checkbox selection on individual done/failed messages
+**Themes**: Stick figure, Cat, Dog, Pig, Emoji, Off (default)
+
+- Theme picker in workspace header
+- Animates based on smith state (idle/running/done/failed/sleeping)
+- Persists to localStorage (`forge.mascotTheme`)
+- Done state plays celebration 2x then settles quietly
 
 ## Controls
 
 | Action | Description |
 |--------|-------------|
-| **Start** | Launch daemon, begin executing all agents |
-| **Stop** | Stop daemon, kill all workers |
-| **Pause** | Pause a specific smith (stops consuming messages) |
-| **Resume** | Resume a paused smith |
-| **Retry** | Retry a failed smith |
-| **Reset** | Reset smith to idle, clear history |
-| **Open Terminal** | Switch to manual mode, open floating terminal |
-| **Close Terminal** | Return to auto mode, resume message processing |
+| **Start Daemon** | Launch all smiths, begin consuming messages |
+| **Stop Daemon** | Stop all smiths, kill workers |
+| **Run All** | Trigger all runnable agents once |
+| **Run** | Trigger specific agent |
+| **Pause/Resume** | Pause/resume message consumption for one agent |
+| **Mark Done/Failed/Idle** | Manually set task status |
+| **Retry** | Re-run a failed agent from checkpoint |
+| **Open Terminal** | Enter manual mode with tmux session |
+| **Remove** | Delete agent (cascades — cleans dangling dependsOn) |
 
 ## Workspace API
 
+### HTTP Endpoints
+
 ```bash
 # List workspaces
 curl http://localhost:8403/api/workspace
 
-# Get workspace state
-curl http://localhost:8403/api/workspace/<id>
+# Find by project path
+curl "http://localhost:8403/api/workspace?projectPath=/path/to/project"
 
-# Agent operations
-curl -X POST http://localhost:8403/api/workspace/<id>/agents \
-  -H 'Content-Type: application/json' \
-  -d '{"action":"start"}'                                        # start daemon
-  -d '{"action":"stop"}'                                         # stop daemon
-  -d '{"action":"run", "agentId":"engineer-123"}'                # run one smith
-  -d '{"action":"open_terminal", "agentId":"engineer-123"}'      # manual mode
-  -d '{"action":"close_terminal", "agentId":"engineer-123"}'     # back to auto
-  -d '{"action":"reset", "agentId":"engineer-123"}'              # reset to idle
-
-# Smith API (via workspace daemon)
-curl -X POST http://localhost:8403/api/workspace/<id>/smith \
+# Export workspace as template
+curl "http://localhost:8403/api/workspace?export=<workspaceId>"
+
+# Import template
+curl -X POST http://localhost:8403/api/workspace \
   -H 'Content-Type: application/json' \
-  -d '{"action":"send","agentId":"$ID","to":"QA","msgAction":"review","content":"Please check"}'
-  -d '{"action":"inbox","agentId":"$ID"}'
-  -d '{"action":"status","agentId":"$ID"}'
-  -d '{"action":"create_ticket","agentId":"$FROM","targetId":"$TO","content":"Bug found"}'
-  -d '{"action":"update_ticket","messageId":"$ID","ticketStatus":"fixed"}'
+  -d '{"projectPath":"...","projectName":"...","template":{...}}'
+
+# Delete workspace
+curl -X DELETE "http://localhost:8403/api/workspace?id=<workspaceId>"
+```
+
+### Agent Operations
+
+```bash
+POST /api/workspace/<id>/agents
+{
+  "action": "add",           # create agent
+  "config": {...}
+}
+{
+  "action": "update",        # update agent
+  "agentId": "...",
+  "config": {...}
+}
+{
+  "action": "remove",        # remove agent
+  "agentId": "..."
+}
+{
+  "action": "start_daemon"   # start all smiths
+}
+{
+  "action": "stop_daemon"    # stop all smiths
+}
+{
+  "action": "run",           # trigger one agent
+  "agentId": "..."
+}
+{
+  "action": "mark_done",     # manual status
+  "agentId": "...",
+  "notify": true             # also send downstream notifications
+}
+```
 
-# Stream real-time events (SSE)
+### Streaming Events (SSE)
+
+```bash
 curl http://localhost:8403/api/workspace/<id>/stream
 ```
 
-## Watch (Autonomous Monitoring)
+Events: `agents_changed`, `task_status`, `smith_status`, `log`, `bus_message`, `workspace_complete`, `watch_alert`.
 
-Agents can autonomously monitor file changes, git commits, or custom commands without relying on messages.
+## Timeouts & Session Monitor
 
-### Configuration
+A background session monitor polls each agent's Claude session file:
 
-In the agent config modal, enable Watch and configure:
-- **Interval**: Check frequency in seconds (min 10, default 60)
-- **Targets**: What to monitor
-  - `Directory` — select from project folders, detect file mtime changes
-  - `Git` — detect new commits via HEAD hash comparison
-  - `Agent Output` — monitor another agent's declared output paths
-  - `Command` — run a shell command, detect output changes
-- **On Change**: Action when changes detected
-  - `Log` — write to agent log only (default, no token cost)
-  - `Analyze` — auto-wake agent to analyze changes (costs tokens)
-  - `Approve` — create pending approval, user decides whether to trigger
+| Threshold | Behavior |
+|-----------|----------|
+| **File change** | → `running` (mtime/size changed) |
+| **19 min stable** | Check for `result` entry in session file → mark `done` if found |
+| **20 min stable** | Force `done` (fallback if Stop hook missed) |
 
-### Watch Behavior
+The Stop hook (installed in `~/.claude/settings.json`) triggers `done` immediately when Claude Code finishes a turn.
 
-- First check builds a baseline (no alert)
-- Subsequent checks compare timestamps — only files modified since last check are reported
-- No-change heartbeats log to console only (not to files)
-- Change alerts write to `logs.jsonl` and appear in Log panel
-- Watch never sends bus messages — report only, no auto-triggering other agents
+## Persistence
 
-## Agent Logs
+- **Workspace state**: `~/.forge/workspaces/<id>/state.json` (atomic writes, auto-save every 10s)
+- **Agent logs**: `~/.forge/workspaces/<id>/agents/<agentId>/logs.jsonl` (append-only)
+- **Smith templates**: `~/.forge/data/smith-templates/*.json`
+- **Request documents**: `<project>/.forge/requests/REQ-*/` (request.yml + response.yml)
+- **Agent context**: `<project>/<workDir>/.forge/agent-context.json` (read by Stop hook)
 
-Each agent has a persistent log file (`logs.jsonl`) that survives daemon restarts and agent re-execution.
+## Complete WorkspaceAgentConfig Schema
 
-- **Log panel**: Click the log button on any agent node to view
-- **Persistent**: Logs are append-only, not cleared on reset or re-run
-- **Clear**: Use the "Clear" button in the Log panel header to manually wipe logs
-- **Content**: Execution output, watch alerts, bus message receipts, system events
+Use this exact JSON structure when calling `POST /api/workspace/<id>/agents` with `action: "add"` or `action: "update"`.
 
-## Forge Skills (Terminal Communication)
+```json
+{
+  "id": "engineer-1775268642253",
+  "label": "Engineer",
+  "icon": "🔨",
+  "type": "agent",
+  "primary": false,
+  "backend": "cli",
+  "agentId": "claude",
+  "provider": null,
+  "model": null,
+  "dependsOn": ["input-1775268600000", "pm-1775268620946"],
+  "workDir": "./src",
+  "outputs": ["src/", "docs/architecture/"],
+  "steps": [
+    { "id": "claim", "label": "Find & Claim", "prompt": "Read Workspace Team..." },
+    { "id": "design", "label": "Design", "prompt": "get_request for details..." },
+    { "id": "implement", "label": "Implement", "prompt": "Implement per design..." },
+    { "id": "report", "label": "Report Done", "prompt": "update_response..." }
+  ],
+  "role": "Senior Software Engineer. Context auto-includes Workspace Team...",
+  "persistentSession": true,
+  "skipPermissions": true,
+  "requiresApproval": false,
+  "plugins": ["playwright-main"],
+  "watch": {
+    "enabled": false,
+    "interval": 60,
+    "targets": [],
+    "action": "log",
+    "prompt": "",
+    "sendTo": ""
+  }
+}
+```
 
-When in manual mode, agents have forge env vars injected (`FORGE_AGENT_ID`, `FORGE_WORKSPACE_ID`, `FORGE_PORT`) and can use:
+### Field Reference
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | string | yes (for update/remove) | auto | Format: `{label-lower}-{timestamp}` |
+| `label` | string | yes | — | Display name, must be unique in workspace |
+| `icon` | string | yes | `🤖` | Emoji icon |
+| `type` | string | yes | `agent` | `agent` or `input` |
+| `primary` | boolean | no | false | Only one per workspace, workDir forced to `./` |
+| `backend` | string | yes | `cli` | `cli` (subscription) or `api` (api key) |
+| `agentId` | string | cli only | `claude` | Agent ID from Settings → Agents (e.g. `claude`, `codex`, `aider`) |
+| `provider` | string | api only | — | e.g. `anthropic` |
+| `model` | string | no | — | Model override (e.g. `claude-sonnet-4-6`) |
+| `dependsOn` | string[] | yes | `[]` | Upstream agent IDs (DAG edges) |
+| `workDir` | string | yes | `./` | Relative path from project root, must be unique |
+| `outputs` | string[] | yes | `[]` | Expected output paths (informational) |
+| `steps` | object[] | yes | `[]` | `{id, label, prompt}[]` |
+| `role` | string | yes | — | System prompt, synced to `CLAUDE.md` in workDir |
+| `persistentSession` | boolean | no | false | Keep tmux+CLI alive (required for primary) |
+| `skipPermissions` | boolean | no | true | `--dangerously-skip-permissions` for Claude Code |
+| `requiresApproval` | boolean | no | false | User approves each inbox message |
+| `plugins` | string[] | no | — | Plugin instance IDs |
+| `watch` | object | no | — | Watch config (see Watch section) |
+
+### Watch Config Schema
 
-| Skill | Description |
-|-------|-------------|
-| `/forge-send` | Send a message to another smith |
-| `/forge-inbox` | Check incoming messages |
-| `/forge-status` | Check all smiths' status |
-| `/forge-workspace-sync` | Sync progress back to workspace |
+```json
+{
+  "enabled": true,
+  "interval": 60,
+  "targets": [
+    { "type": "directory", "path": "src/", "debounce": 10 },
+    { "type": "git", "debounce": 10 },
+    { "type": "agent_status", "path": "engineer-1234", "pattern": "done" },
+    { "type": "command", "cmd": "npm test", "debounce": 10 },
+    { "type": "agent_log", "path": "qa-5678", "pattern": "error" },
+    { "type": "agent_output", "path": "pm-9012" },
+    { "type": "session", "path": "engineer-1234" }
+  ],
+  "action": "log",
+  "prompt": "Analyze and report",
+  "sendTo": "engineer-1234"
+}
+```
 
-**Send protection**: If an agent is currently processing a message from another agent, `/forge-send` to that agent is blocked (returns `skipped: true`). Results are delivered automatically via the message system. Only use `/forge-send` for new issues to other agents.
+- `action` values: `log` | `analyze` | `approve` | `send_message`
+- `sendTo` is required only when `action: "send_message"`
 
-## Persistence
+## Complete Recipes
+
+### Authentication (Required for API Calls)
+
+```bash
+# Ask user for admin password, then:
+TOKEN=$(curl -s -X POST http://localhost:8403/api/auth/verify \
+  -H "Content-Type: application/json" \
+  -d '{"password":"USER_PASSWORD"}' | python3 -c "import sys,json; print(json.load(sys.stdin).get('token',''))")
+
+# Use token in all subsequent requests:
+# curl -H "X-Forge-Token: $TOKEN" ...
+```
+
+### Recipe 1: Create Workspace + Add Lead + Start Daemon
+
+```bash
+# 1. Create workspace
+WS=$(curl -s -X POST http://localhost:8403/api/workspace \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d '{"projectPath":"/Users/me/projects/my-app","projectName":"my-app"}' \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+
+# 2. Add Input node (where user requirements go)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d '{
+    "action": "add",
+    "config": {
+      "id": "input-'$(date +%s%N)'",
+      "label": "Requirements",
+      "icon": "📝",
+      "type": "input",
+      "backend": "cli",
+      "dependsOn": [],
+      "outputs": [],
+      "steps": [],
+      "role": "",
+      "content": "",
+      "entries": []
+    }
+  }'
+
+# 3. Add Lead (Primary coordinator)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d '{
+    "action": "add",
+    "config": {
+      "id": "lead-'$(date +%s%N)'",
+      "label": "Lead",
+      "icon": "👑",
+      "type": "agent",
+      "primary": true,
+      "backend": "cli",
+      "agentId": "claude",
+      "dependsOn": [],
+      "workDir": "./",
+      "outputs": ["docs/lead/"],
+      "persistentSession": true,
+      "skipPermissions": true,
+      "plugins": [],
+      "role": "You are the Lead — primary coordinator...",
+      "steps": [
+        {"id": "intake", "label": "Intake", "prompt": "Read Workspace Team..."},
+        {"id": "delegate", "label": "Delegate", "prompt": "create_request for each task..."},
+        {"id": "monitor", "label": "Monitor", "prompt": "get_status + list_requests..."}
+      ]
+    }
+  }'
+
+# 4. Start daemon
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d '{"action": "start_daemon"}'
+```
+
+### Recipe 2: Add a Full Dev Team (Lead + Engineer + QA + Reviewer)
+
+```bash
+TS=$(date +%s%N)
+INPUT_ID="input-$TS"
+LEAD_ID="lead-$TS"
+ENG_ID="engineer-$TS"
+QA_ID="qa-$TS"
+REV_ID="reviewer-$TS"
+
+# Input
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"add\",\"config\":{\"id\":\"$INPUT_ID\",\"label\":\"Requirements\",\"icon\":\"📝\",\"type\":\"input\",\"backend\":\"cli\",\"dependsOn\":[],\"outputs\":[],\"steps\":[],\"role\":\"\",\"content\":\"\",\"entries\":[]}}"
+
+# Lead (depends on Input)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"add\",\"config\":{\"id\":\"$LEAD_ID\",\"label\":\"Lead\",\"icon\":\"👑\",\"type\":\"agent\",\"primary\":true,\"backend\":\"cli\",\"agentId\":\"claude\",\"dependsOn\":[\"$INPUT_ID\"],\"workDir\":\"./\",\"outputs\":[\"docs/lead/\"],\"persistentSession\":true,\"skipPermissions\":true,\"role\":\"Lead coordinator\",\"steps\":[{\"id\":\"plan\",\"label\":\"Plan\",\"prompt\":\"Coordinate the team\"}]}}"
+
+# Engineer (depends on Lead)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"add\",\"config\":{\"id\":\"$ENG_ID\",\"label\":\"Engineer\",\"icon\":\"🔨\",\"type\":\"agent\",\"backend\":\"cli\",\"agentId\":\"claude\",\"dependsOn\":[\"$LEAD_ID\"],\"workDir\":\"./src\",\"outputs\":[\"src/\"],\"persistentSession\":true,\"skipPermissions\":true,\"role\":\"Engineer\",\"steps\":[{\"id\":\"impl\",\"label\":\"Implement\",\"prompt\":\"Write code\"}]}}"
+
+# QA (depends on Engineer)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"add\",\"config\":{\"id\":\"$QA_ID\",\"label\":\"QA\",\"icon\":\"🧪\",\"type\":\"agent\",\"backend\":\"cli\",\"agentId\":\"claude\",\"dependsOn\":[\"$ENG_ID\"],\"workDir\":\"./qa\",\"outputs\":[\"tests/\"],\"persistentSession\":true,\"skipPermissions\":true,\"plugins\":[\"playwright-main\"],\"role\":\"QA\",\"steps\":[{\"id\":\"test\",\"label\":\"Test\",\"prompt\":\"Write and run tests\"}]}}"
+
+# Reviewer (depends on Engineer + QA)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"add\",\"config\":{\"id\":\"$REV_ID\",\"label\":\"Reviewer\",\"icon\":\"🔍\",\"type\":\"agent\",\"backend\":\"cli\",\"agentId\":\"claude\",\"dependsOn\":[\"$ENG_ID\",\"$QA_ID\"],\"workDir\":\"./review\",\"outputs\":[\"docs/review/\"],\"persistentSession\":true,\"skipPermissions\":true,\"role\":\"Reviewer\",\"steps\":[{\"id\":\"review\",\"label\":\"Review\",\"prompt\":\"Review code\"}]}}"
+```
+
+### Recipe 3: Submit Input and Run
+
+```bash
+# Send requirement text to Input node
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"complete_input\",\"agentId\":\"$INPUT_ID\",\"content\":\"Build a login page with email/password.\"}"
+
+# Trigger Lead to start
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"run\",\"agentId\":\"$LEAD_ID\"}"
+```
+
+### Recipe 4: Save a Smith as Template + Import Later
+
+```bash
+# Save current agent config as template
+curl -s -X POST http://localhost:8403/api/smith-templates \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d '{
+    "name": "My Engineer",
+    "icon": "🔨",
+    "description": "Custom engineer with TDD preference",
+    "config": {
+      "label": "Engineer",
+      "icon": "🔨",
+      "backend": "cli",
+      "agentId": "claude",
+      "workDir": "./src",
+      "outputs": ["src/"],
+      "role": "Engineer with TDD approach...",
+      "steps": [...],
+      "persistentSession": true,
+      "plugins": ["playwright-main"]
+    }
+  }'
+
+# List templates
+curl -s http://localhost:8403/api/smith-templates -H "X-Forge-Token: $TOKEN"
+
+# When adding agent, reuse saved template's config field
+```
+
+### Recipe 5: Configure Watch on an Agent
+
+```bash
+# Update agent to watch the src/ directory and analyze on changes
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{
+    \"action\":\"update\",
+    \"agentId\":\"$REV_ID\",
+    \"config\": {
+      \"id\":\"$REV_ID\",
+      \"label\":\"Reviewer\",
+      ... (all existing fields)
+      \"watch\": {
+        \"enabled\": true,
+        \"interval\": 60,
+        \"targets\": [
+          {\"type\":\"directory\",\"path\":\"src/\",\"debounce\":10}
+        ],
+        \"action\": \"analyze\",
+        \"prompt\": \"Review recent changes for quality issues\"
+      }
+    }
+  }"
+```
+
+### Recipe 6: Install a Plugin Instance
+
+```bash
+# List available plugin definitions
+curl -s http://localhost:8403/api/plugins -H "X-Forge-Token: $TOKEN"
+
+# Install a plugin instance (e.g., playwright)
+curl -s -X POST http://localhost:8403/api/plugins \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d '{
+    "action": "install",
+    "id": "playwright",
+    "config": {
+      "instanceName": "playwright-main"
+    }
+  }'
+
+# List installed instances
+curl -s "http://localhost:8403/api/plugins?installed=true" -H "X-Forge-Token: $TOKEN"
+```
+
+### Recipe 7: Query Workspace State
+
+```bash
+# List all workspaces
+curl -s http://localhost:8403/api/workspace -H "X-Forge-Token: $TOKEN"
+
+# Get full workspace state (agents + states + bus)
+curl -s "http://localhost:8403/api/workspace?projectPath=/Users/me/projects/my-app" \
+  -H "X-Forge-Token: $TOKEN"
+
+# Get live agent list
+curl -s "http://localhost:8403/api/workspace/$WS/agents" -H "X-Forge-Token: $TOKEN"
+
+# Stream SSE events (runs forever, use Ctrl+C to stop)
+curl -N "http://localhost:8403/api/workspace/$WS/stream" -H "X-Forge-Token: $TOKEN"
+```
+
+### Recipe 8: Remove Agent / Workspace
+
+```bash
+# Remove an agent (non-primary only)
+curl -s -X POST "http://localhost:8403/api/workspace/$WS/agents" \
+  -H "Content-Type: application/json" -H "X-Forge-Token: $TOKEN" \
+  -d "{\"action\":\"remove\",\"agentId\":\"$REV_ID\"}"
+
+# Delete entire workspace
+curl -s -X DELETE "http://localhost:8403/api/workspace?id=$WS" \
+  -H "X-Forge-Token: $TOKEN"
+```
+
+## Common Pitfalls
 
-- Workspace state: `~/.forge/workspaces/<id>/state.json`
-- Agent logs: `~/.forge/workspaces/<id>/agents/<agentId>/logs.jsonl`
-- Auto-saved every 10 seconds
-- Atomic writes (temp file → rename) for crash safety
-- Synchronous save on daemon shutdown
-- `currentMessageId` persisted per agent for crash recovery
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| "Work directory conflict" | Two agents use same `workDir` | Each non-input smith must have unique workDir |
+| "Cycle detected in dependencies" | `dependsOn` creates a loop | Review DAG, break the cycle |
+| "Primary already set" | Trying to add 2nd primary smith | Only one primary per workspace |
+| Daemon won't start | No primary agent, or config errors | Check logs at `~/.forge/data/forge.log` |
+| Agent stuck in `running` | Stop hook didn't fire | 20-min auto timeout will kick in; or manual mark_done |
+| Hook not firing | `.forge/agent-context.json` missing | Restart daemon to re-inject |
+| `agentId` not found | CLI/profile deleted from Settings | Update agent config with valid agentId |
 
 ## Tips
 
-1. **Dependencies must be a DAG** — no circular dependencies allowed
-2. **Start with Input nodes** — define requirements before adding agent smiths
-3. **Use profiles** for agents that need custom API endpoints or models
-4. **Notifications flow downstream** — upstream agents won't receive downstream broadcasts
-5. **Use tickets for bugs** — tickets ignore DAG direction, have retry limits
-6. **Open Terminal** for manual intervention — mode switches to manual, inbox pauses
-7. **Use Watch for monitoring** — detect file changes without message overhead (set action to `log` to avoid token costs)
-8. **Check Log panel** for execution history and watch alerts — logs persist across restarts
-9. **Batch operations** — select all completed messages for bulk delete, or abort all pending at once
+1. **Start with a Lead** — add Lead first as Primary, then add specialists (Engineer, QA, etc.)
+2. **Dependencies must be DAG** — no cycles allowed
+3. **Use request documents** — don't rely on loose `send_message` for delegation
+4. **Trust the topology** — agents auto-see the team in their context, no redundant `get_agents` calls needed
+5. **Let Lead cover gaps** — don't add roles you don't need, Lead handles missing ones
+6. **Use Watch for passive monitoring** — avoid token costs with `action: log`
+7. **Save useful smiths as templates** — 💾 button → reusable across workspaces
+8. **Use Terminal mode** for debugging — interact with a smith directly
+9. **Check session logs** if a smith seems stuck — `~/.claude/projects/<encoded-path>/<sessionId>.jsonl`
+10. **20-min timeout is a safety net** — if Stop hook fires normally, task is marked done immediately