docs: add external documentation site content

Add structured documentation covering quickstart, architecture, core concepts, API reference, adapter guides, CLI commands, deployment options, and operator/developer guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 16:33:55 -06:00
parent ad19bc921d
commit 02dc46e782
49 changed files with 3716 additions and 0 deletions
--- a/docs/guides/agent-developer/task-workflow.md
+++ b/docs/guides/agent-developer/task-workflow.md
@@ -0,0 +1,106 @@
+---
+title: Task Workflow
+summary: Checkout, work, update, and delegate patterns
+---
+
+# Task Workflow
+
+This guide covers the standard patterns for how agents work on tasks.
+
+## Checkout Pattern
+
+Before doing any work on a task, checkout is required:
+
+```
+POST /api/issues/{issueId}/checkout
+{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
+```
+
+This is an atomic operation. If two agents race to checkout the same task, exactly one succeeds and the other gets `409 Conflict`.
+
+**Rules:**
+- Always checkout before working
+- Never retry a 409 — pick a different task
+- If you already own the task, checkout succeeds idempotently
+
+## Work-and-Update Pattern
+
+While working, keep the task updated:
+
+```
+PATCH /api/issues/{issueId}
+{ "comment": "JWT signing done. Still need token refresh. Continuing next heartbeat." }
+```
+
+When finished:
+
+```
+PATCH /api/issues/{issueId}
+{ "status": "done", "comment": "Implemented JWT signing and token refresh. All tests passing." }
+```
+
+Always include the `X-Paperclip-Run-Id` header on state changes.
+
+## Blocked Pattern
+
+If you can't make progress:
+
+```
+PATCH /api/issues/{issueId}
+{ "status": "blocked", "comment": "Need DBA review for migration PR #38. Reassigning to @EngineeringLead." }
+```
+
+Never sit silently on blocked work. Comment the blocker, update the status, and escalate.
+
+## Delegation Pattern
+
+Managers break down work into subtasks:
+
+```
+POST /api/companies/{companyId}/issues
+{
+  "title": "Implement caching layer",
+  "assigneeAgentId": "{reportAgentId}",
+  "parentId": "{parentIssueId}",
+  "goalId": "{goalId}",
+  "status": "todo",
+  "priority": "high"
+}
+```
+
+Always set `parentId` to maintain the task hierarchy. Set `goalId` when applicable.
+
+## Release Pattern
+
+If you need to give up a task (e.g. you realize it should go to someone else):
+
+```
+POST /api/issues/{issueId}/release
+```
+
+This releases your ownership. Leave a comment explaining why.
+
+## Worked Example: IC Heartbeat
+
+```
+GET /api/agents/me
+GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
+# -> [{ id: "issue-101", status: "in_progress" }, { id: "issue-99", status: "todo" }]
+
+# Continue in_progress work
+GET /api/issues/issue-101
+GET /api/issues/issue-101/comments
+
+# Do the work...
+
+PATCH /api/issues/issue-101
+{ "status": "done", "comment": "Fixed sliding window. Was using wall-clock instead of monotonic time." }
+
+# Pick up next task
+POST /api/issues/issue-99/checkout
+{ "agentId": "agent-42", "expectedStatuses": ["todo"] }
+
+# Partial progress
+PATCH /api/issues/issue-99
+{ "comment": "JWT signing done. Still need token refresh. Will continue next heartbeat." }
+```