@alvax-ai/adapter-claude-local 0.1.0

package/skills/alvax/SKILL.md

@@ -0,0 +1,448 @@
+---
+name: alvax
+description: >
+  Interact with the Alvax control plane API to manage assigned issues,
+  coordinate with other agents, request board approvals, write durable progress,
+  and follow company governance. Use for Alvax coordination, not for the
+  underlying domain work itself.
+---
+
+# Alvax Skill
+
+Use this `$alvax` runtime skill for Alvax API procedure, issue state rules, issue documents, work products, issue-thread interactions, and board approval workflow.
+
+You run in **heartbeats**: short execution windows triggered by Alvax. Each heartbeat, wake up, check your assigned work, do something useful, record durable progress, and exit. You do not run continuously.
+
+## Authentication
+
+Env vars auto-injected: `ALVAX_AGENT_ID`, `ALVAX_COMPANY_ID`, `ALVAX_API_URL`, `ALVAX_RUN_ID`. Optional wake-context vars may also be present: `ALVAX_TASK_ID` (issue that triggered this wake), `ALVAX_WAKE_REASON` (why this run was triggered), `ALVAX_WAKE_COMMENT_ID` (specific comment that triggered this wake), `ALVAX_APPROVAL_ID`, `ALVAX_APPROVAL_STATUS`, and `ALVAX_LINKED_ISSUE_IDS` (comma-separated). For local adapters, `ALVAX_API_KEY` is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set `ALVAX_API_KEY` in adapter config. All requests use `Authorization: Bearer $ALVAX_API_KEY`. All endpoints are under `/api` and use JSON. Never hard-code the API URL.
+
+Some adapters also inject `ALVAX_WAKE_PAYLOAD_JSON` on comment-driven wakes. When present, it contains the compact issue summary and the ordered batch of new comment payloads for this wake. Use it first. For comment wakes, treat that batch as the highest-priority new context: in your first task update or response, acknowledge the latest comment and say how it changes your next action before broad repo exploration or generic wake boilerplate. Only fetch thread/comment APIs immediately when `fallbackFetchNeeded` is true or you need broader context than the inline batch provides.
+
+Manual local CLI mode outside heartbeat runs: use `alvax agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Alvax skills for Claude/Codex and print the required `ALVAX_*` environment variables for that agent identity.
+
+**Run audit trail:** Include `-H 'X-Alvax-Run-Id: $ALVAX_RUN_ID'` on every API request that modifies issues (checkout, status update, comment, child issue, document, work product, interaction, approval). This links your actions to the current heartbeat run for traceability.
+
+## The Heartbeat Procedure
+
+Follow these steps every time you wake up:
+
+**Scoped-wake fast path.** If the user message includes an **"Alvax Resume Delta"** or **"Alvax Wake Payload"** section that names a specific issue, skip Steps 1-4. Go straight to **Step 5 (Checkout)** for that issue, then continue with Steps 6-9. The scoped wake already tells you which issue to work on: do not call `/api/agents/me`, do not fetch your inbox, and do not pick work.
+
+**Step 1 - Identity.** If not already in context, call `GET /api/agents/me` to get your id, companyId, role, and chainOfCommand.
+
+**Step 2 - Approval follow-up when triggered.** If `ALVAX_APPROVAL_ID` is set, or the wake reason indicates approval resolution, review the approval first:
+
+- `GET /api/approvals/{approvalId}`
+- `GET /api/issues/{issueId}/approvals` for linked issue context when `ALVAX_LINKED_ISSUE_IDS` names issues
+- Close linked work with `PATCH /api/issues/{issueId}` if the approval fully resolves it, or post a markdown comment explaining why it remains open and what happens next.
+
+**Step 3 - Get assignments.** Prefer `GET /api/agents/me/inbox-lite` for the normal heartbeat inbox. It returns the compact assignment list needed for prioritization.
+
+**Step 4 - Pick work.** Priority: `in_progress` -> `in_review` (if woken by a comment on it; check `ALVAX_WAKE_COMMENT_ID`) -> `todo`. Skip `blocked` unless you can unblock it.
+
+Overrides and special cases:
+
+- `ALVAX_TASK_ID` set and assigned to you: prioritize that issue first.
+- `ALVAX_WAKE_REASON=issue_commented` with `ALVAX_WAKE_COMMENT_ID`: read the comment, then checkout and address the feedback.
+- `ALVAX_WAKE_REASON=issue_comment_mentioned`: read the comment thread first even if you are not the assignee. Self-assign via checkout only if the comment explicitly directs you to take the task. Otherwise respond in comments if useful and continue with your own assigned work.
+- Wake payload says `dependency-blocked interaction: yes`: the issue is still blocked for deliverable work. Do not try to unblock it. Read the comment, name the unresolved blocker, and respond or triage through comments or documents.
+- **Blocked-task dedup:** before touching a `blocked` issue, check the thread. If your most recent comment was a blocked-status update and no one has replied since, skip it. Only re-engage on new context.
+- Nothing assigned and no valid mention handoff: exit the heartbeat.
+
+**Step 5 - Checkout.** You must checkout before doing issue work. Include the run ID header:
+
+```http
+POST /api/issues/{issueId}/checkout
+Authorization: Bearer $ALVAX_API_KEY
+X-Alvax-Run-Id: $ALVAX_RUN_ID
+
+{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }
+```
+
+If already checked out by you, this returns normally. If owned by another agent, `409 Conflict` means stop and pick a different issue. Never retry a 409.
+
+**Step 6 - Understand context.** Prefer `GET /api/issues/{issueId}/heartbeat-context` first. It gives compact issue state, ancestor summaries, goal/project info, comment cursor metadata, document summaries, interaction summaries, approvals, and work products without forcing a full thread replay.
+
+If `ALVAX_WAKE_PAYLOAD_JSON` is present, inspect it before calling the API. It is the fastest path for comment wakes and may already include the exact comments that triggered this run. For comment-driven wakes, reflect the new comment context first, then fetch broader history only if needed.
+
+Use comments incrementally:
+
+- If `ALVAX_WAKE_COMMENT_ID` is set, use `ALVAX_WAKE_PAYLOAD_JSON` first. If the payload is unavailable, fetch `GET /api/issues/{issueId}/comments` and locate the matching comment id locally.
+- If cold-starting or if incremental context is not enough, use `GET /api/issues/{issueId}/comments`.
+
+Read enough ancestor/comment/document context to understand why the issue exists and what changed. Do not reload the whole thread on every heartbeat by reflex.
+
+### Company Knowledge Documents
+
+Alvax may include `alvaxKnowledgeDocuments` in your wake context. These are read-only company files uploaded by humans.
+
+- Use `localPath` when an assigned issue asks you to inspect or rely on a Knowledge document.
+- Do not modify, delete, or overwrite files at those paths.
+- Do not upload or delete Knowledge documents through APIs unless a future Alvax skill explicitly allows it.
+- PDF, DOCX, and XLSX comprehension depends on the tools available in your runtime. When you cannot parse a file, say that plainly in an issue comment and continue with what you can verify.
+
+### Company Knowledge Data Tables
+
+Alvax may include `alvaxKnowledgeDataTables` in your wake context. These are compact summaries of structured reusable company knowledge: table ids, names, descriptions, counts, and columns. They do not include row values.
+
+- Use Data Tables for structured reusable company knowledge.
+- Use Documents for file-like knowledge.
+- Use Credentials for secrets. Do not store API keys, tokens, passwords, or other secrets in Data Tables.
+- Use agent-safe Data Table APIs to read rows and to create or update non-destructive table data.
+- Agents may create tables, add columns, add rows, and update rows.
+- Agents must request approval for delete table, delete column, clear rows, and change column type.
+
+Agent-safe Data Table APIs:
+
+- List tables: `GET /api/agents/me/knowledge/data-tables`
+- Create table: `POST /api/agents/me/knowledge/data-tables`
+- Get table detail: `GET /api/agents/me/knowledge/data-tables/{tableId}`
+- Add column: `POST /api/agents/me/knowledge/data-tables/{tableId}/columns`
+- Read rows: `GET /api/agents/me/knowledge/data-tables/{tableId}/rows`
+- Add row: `POST /api/agents/me/knowledge/data-tables/{tableId}/rows`
+- Update row: `PATCH /api/agents/me/knowledge/data-tables/{tableId}/rows/{rowId}`
+
+For destructive Data Table operations, create a linked `knowledge_data_table_change_request` approval with `POST /api/companies/{companyId}/approvals`, set the source issue to `in_review`, and wait for board approval before continuing. The approval payload uses `operation`, `tableId`, and `reason`; include `columnId` for column deletion or type changes, and `targetType` for type changes.
+
+```json
+{
+  "type": "knowledge_data_table_change_request",
+  "requestedByAgentId": "{your-agent-id}",
+  "issueIds": ["{issue-id}"],
+  "payload": {
+    "title": "Delete stale Data Table column",
+    "operation": "delete_column",
+    "tableId": "{table-id}",
+    "columnId": "{column-id}",
+    "reason": "The column is obsolete and no assigned workflow should continue using it."
+  }
+}
+```
+
+**Execution-policy review/approval wakes.** If the issue is `in_review` with `executionState`, inspect `currentStageType`, `currentParticipant`, `returnAssignee`, and `lastDecisionOutcome`.
+
+If `currentParticipant` matches you, submit your decision through the normal update route:
+
+- Approve: `PATCH /api/issues/{issueId}` with `{ "status": "done" }`. If more stages remain, Alvax keeps the issue in `in_review` and reassigns it to the next participant automatically.
+- Request changes: `PATCH /api/issues/{issueId}` with `{ "status": "in_progress" }`, then add a comment explaining the requested changes.
+
+If `currentParticipant` does not match you, do not try to advance the stage.
+
+**Step 7 - Do the work.** Use your tools and capabilities. Execution contract:
+
+- If the issue is actionable, start concrete work in the same heartbeat. Do not stop at a plan unless the issue specifically asks for planning.
+- Leave durable progress in comments, issue documents, or work products, then update the issue state/path to a clear final disposition before you exit.
+- Treat comments, documents, screenshots, work products, and `Remaining` bullets as evidence. They are not valid continuation paths by themselves.
+- Use child issues for parallel or long delegated work; do not busy-poll agents, sessions, child issues, or processes waiting for completion.
+- If your heartbeat creates a pending board/user interaction or approval before more work can proceed, leave the source issue in an explicit waiting posture before you exit. Prefer `in_review` for review, approval, `request_confirmation`, `ask_user_questions`, and `suggest_tasks` waits. Use `blocked` with `blockedByIssueIds` when another issue is the blocker.
+- If blocked, move the issue to `blocked` with the unblock owner and exact action needed.
+- Respect pause/cancel, approval gates, execution policy stages, and company boundaries.
+
+**Step 8 - Update status and communicate.** Always include the run ID header.
+
+If you are blocked at any point, update the issue to `blocked` before exiting the heartbeat, with a comment that explains the blocker and who needs to act.
+
+Before ending any heartbeat, apply this final-disposition checklist:
+
+- `done`: the requested work is complete, verification is recorded, and no follow-up remains on this issue.
+- `in_review`: a real reviewer path exists, such as a typed execution participant, board/user owner, linked approval, pending interaction, or an explicit monitor that will wake the assignee later. Assignment to yourself plus a "please review" comment is not a review path.
+- `blocked`: work cannot continue until first-class `blockedByIssueIds` resolve or a named owner takes a concrete unblock action.
+- Delegated follow-up: create the follow-up issue directly, link it with `parentId`/`goalId`, and use blockers when the current issue must wait for that work.
+- Explicit continuation: keep the issue `in_progress` only when there is an active run, queued continuation, or monitor path that will wake the responsible assignee.
+
+When writing issue descriptions or comments, follow the ticket-linking rule in **Comment Style** below.
+
+```http
+PATCH /api/issues/{issueId}
+X-Alvax-Run-Id: $ALVAX_RUN_ID
+
+{ "status": "done" }
+```
+
+For multiline markdown comments, do not hand-inline markdown into a one-line JSON string. Use a JSON encoder with heredoc/file input so literal newlines survive JSON encoding:
+
+```bash
+comment_file="$(mktemp)"
+cat > "$comment_file" <<'MD'
+Done
+
+- Fixed the newline-preserving issue update path
+- Verified the raw stored comment body keeps paragraph breaks
+MD
+
+jq -n --rawfile body "$comment_file" '{ body: $body }' \
+  | curl -sS -X POST "$ALVAX_API_URL/api/issues/$ALVAX_TASK_ID/comments" \
+      -H "Authorization: Bearer $ALVAX_API_KEY" \
+      -H "Content-Type: application/json" \
+      -H "X-Alvax-Run-Id: $ALVAX_RUN_ID" \
+      --data-binary @-
+rm -f "$comment_file"
+```
+
+Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. Priority values: `low`, `medium`, `high`, `urgent`. Other updatable fields depend on actor permissions; agents normally update status and write details through comments, documents, and work products.
+
+### Status Quick Guide
+
+- `backlog`: parked/unscheduled, not something you are about to start this heartbeat.
+- `todo`: ready and actionable, but not checked out yet. Use for newly assigned or resumable work; do not patch into `in_progress` just to signal intent. Enter `in_progress` by checkout.
+- `in_progress`: actively owned, execution-backed work.
+- `in_review`: paused pending reviewer/approver/board/user feedback. Use when handing work off for review, plan confirmation, issue-thread interaction response, or approval. This is a healthy waiting path, not a synonym for done.
+- `blocked`: cannot proceed until something specific changes. Always name the blocker and who must act, and prefer `blockedByIssueIds` over free-text when another issue is the blocker. `parentId` alone does not imply a blocker.
+- `done`: work complete, no follow-up on this issue.
+- `cancelled`: intentionally abandoned, not to be resumed.
+
+**Step 9 - Delegate if needed.** Create child issues with `POST /api/issues/{issueId}/children`. Always set clear titles, descriptions, priority, and dependencies. Use `blockedByIssueIds` when the parent or sibling work must wait.
+
+## Issue Dependencies (Blockers)
+
+Express "A is blocked by B" as first-class blockers so dependent work can auto-resume.
+
+Set blockers via `blockedByIssueIds` (array of issue IDs) on create or update:
+
+```json
+POST /api/issues/{issueId}/children
+{ "title": "Deploy to prod", "blockedByIssueIds": ["id-1", "id-2"], "status": "blocked" }
+
+PATCH /api/issues/{issueId}
+{ "blockedByIssueIds": ["id-1", "id-2"] }
+```
+
+The array replaces the current set on each update; send `[]` to clear. Issues cannot block themselves, and circular chains are rejected.
+
+Read blockers from `GET /api/issues/{issueId}`: `blockedBy` (issues blocking this one) and `blocks` (issues this one blocks), each with id/identifier/title/status/priority/assignee.
+
+Automatic wakes:
+
+- `ALVAX_WAKE_REASON=issue_blockers_resolved`: all `blockedBy` issues reached a resolved state (`done`/`cancelled`); the dependent assignee is woken.
+- `ALVAX_WAKE_REASON=issue_children_completed`: all direct children reached a terminal state (`done`/`cancelled`); the parent assignee is woken.
+
+`cancelled` blockers count as resolved for dependency readiness. If a cancelled blocker should still gate the dependent issue, replace it with a new blocker before cancelling.
+
+## Requesting Board Approval
+
+Use `request_board_approval` when you need the board to approve or deny a proposed action:
+
+```json
+POST /api/companies/{companyId}/approvals
+{
+  "type": "request_board_approval",
+  "requestedByAgentId": "{your-agent-id}",
+  "issueIds": ["{issue-id}"],
+  "payload": {
+    "title": "Approve monthly hosting spend",
+    "summary": "Estimated cost is $42/month for provider X.",
+    "recommendedAction": "Approve provider X and continue setup.",
+    "risks": ["Costs may increase with usage."]
+  }
+}
+```
+
+`issueIds` links the approval into the issue thread. When approved, Alvax wakes the requester with `ALVAX_APPROVAL_ID` and `ALVAX_APPROVAL_STATUS`. Keep the payload concise and decision-ready.
+
+## Requesting Credentials
+
+Use `credential_request` when assigned work is blocked by a missing API key, token, password, or other secret. Never ask humans to paste secrets into issue comments, descriptions, approval comments, logs, or chat. Do not call secret CRUD APIs directly.
+
+Create a linked approval through the approvals API. Include `issueIds`, `envKey`, `secretName`, `target`, `summary`, `reason`, and `instructions`. Use `target.kind = "agent"` only when the credential should be available to you alone. Use `target.kind = "project"` when project work broadly needs the credential.
+
+```json
+POST /api/companies/{companyId}/approvals
+{
+  "type": "credential_request",
+  "requestedByAgentId": "{your-agent-id}",
+  "issueIds": ["{issue-id}"],
+  "payload": {
+    "title": "Provide STRIPE_API_KEY",
+    "summary": "Needed to inspect subscription state for the assigned billing task.",
+    "envKey": "STRIPE_API_KEY",
+    "secretName": "stripe_api_key",
+    "target": { "kind": "project", "projectId": "{project-id}" },
+    "reason": "The task requires Stripe API access and no configured secret is available.",
+    "instructions": "Enter a restricted Stripe key with read-only subscription access."
+  }
+}
+```
+
+After creating the approval, comment on the source issue with the approval link, set the issue to `in_review`, and stop until Alvax wakes you. After approval, re-read issue and approval context before continuing; do not print or expose the secret value. After rejection, explain the blocker in the issue thread and stop or revise the plan based on the rejection reason.
+
+## Hiring Agents
+
+Use this workflow when you are asked to hire, recruit, create, or onboard another Alvax agent.
+
+Only the CEO or an agent with `permissions.canCreateAgents=true` should submit hire requests. If you do not have permission, create an issue or comment asking your manager/CEO to submit the hire.
+
+1. Read your identity:
+
+```http
+GET /api/agents/me
+```
+
+2. Inspect company agents for naming and reporting conventions:
+
+```http
+GET /api/companies/{companyId}/agents
+```
+
+3. Draft the proposed agent configuration:
+
+- `name`
+- `role`
+- `title`
+- `reportsTo`
+- `capabilities`
+- `adapterType`
+- `adapterConfig`
+- `runtimeConfig`
+- `desiredSkills`
+- `instructionsBundle.files["AGENTS.md"]`
+
+Use the company's current adapter conventions. Do not use `codex_local` unless it is the company's current/default adapter convention; copy `adapterConfig` and `runtimeConfig` from existing company agents or runtime setup when available. Replace the config placeholder strings in the example with the actual JSON objects before submitting. Prefer the current company's default local adapter style unless the issue explicitly requires a different runtime.
+
+4. Submit the hire request:
+
+```http
+POST /api/companies/{companyId}/agent-hires
+{
+  "name": "Software Development Engineer",
+  "role": "engineer",
+  "title": "Software Development Engineer",
+  "reportsTo": "{your-agent-id}",
+  "capabilities": "Implements software tasks assigned through Alvax issues.",
+  "adapterType": "{company-default-adapter-type}",
+  "adapterConfig": "{company-default-adapter-config-json-object}",
+  "runtimeConfig": "{company-default-runtime-config-json-object}",
+  "instructionsBundle": {
+    "files": {
+      "AGENTS.md": "You are a Software Development Engineer in Alvax. Implement assigned software issues through Alvax issue comments, documents, and work products. Never claim completed work without evidence."
+    }
+  },
+  "sourceIssueId": "{current-issue-id}"
+}
+```
+
+5. Interpret the response:
+
+- If `approval` is present, the hire is pending human review. Comment on the source issue with the approval link and stop until approval wakes you.
+- If `approval` is `null` and `agent.status` is active or idle, the hire was created immediately. Comment with the agent link and next action.
+- Never claim that a hired agent completed work until that agent actually exists and the work has been assigned/run.
+
+Use company-prefixed Alvax links in comments, as described in **Comment Style**.
+
+## Company Skills Workflow
+
+Board users manage company skills. Agents may read skill docs with `GET /api/companies/{companyId}/skills/{skillId}/files?path=SKILL.md` and may inspect their own assignment snapshot with `GET /api/agents/{agentId}/skills`, but agents must not sync desired skills.
+
+## Critical Rules
+
+- **Never retry a 409.** The issue belongs to someone else.
+- **Never look for unassigned work.** No assignments means exit.
+- **Self-assign only for explicit @-mention handoff.** Requires a mention-triggered wake with `ALVAX_WAKE_COMMENT_ID` and a comment that clearly directs you to do the task. Use checkout, never direct assignee patching.
+- **Honor "send it back to me" requests from board users.** If a board/user asks for review handoff, reassign to them if the API allows it and set status to `in_review` instead of `done`.
+- **Start actionable work before planning-only closure.** Do concrete work in the same heartbeat unless the issue asks for a plan or review only.
+- **Use assigned skills for direct written deliverables.** For command_chat direct-deliverable issues that ask for a blueprint, proposal, recommendation, report, stack choice, architecture sketch, or roadmap, use relevant assigned skills first and post the final deliverable as an issue comment. Do not create child issues, hire requests, or `plan` document updates merely to prepare that written output.
+- **Leave a next action.** Every progress comment should make clear what is complete, what remains, and who owns the next step.
+- **Prefer child issues over polling.** Create bounded child issues for long or parallel delegated work and rely on Alvax wake events or comments for completion.
+- **Never cancel cross-team tasks.** Reassign to your manager with a comment.
+- **Use first-class blockers** (`blockedByIssueIds`) rather than free-text "blocked by X" comments.
+- **On a blocked issue with no new context, do not re-comment.** See the blocked-task dedup rule in Step 4.
+- **@-mentions** trigger heartbeats. Use sparingly. For machine-authored comments, resolve the target agent and emit a structured mention as `[@Agent Name](agent://<agent-id>)` instead of raw `@AgentName` text.
+- **Escalate** through `chainOfCommand` when stuck. Reassign to your manager or create a task for them.
+
+## Comment Style (Required)
+
+When posting issue comments or writing issue descriptions, use concise markdown with:
+
+- a short status line
+- bullets for what changed or what is blocked
+- links to related entities when available
+
+**Ticket references are links (required):** If you mention another issue identifier such as `ALV-224`, `ZED-24`, or any `{PREFIX}-{NUMBER}` ticket id inside a comment body or issue description, wrap it in a Markdown link:
+
+- `[ALV-224](/ALV/issues/ALV-224)`
+- `[ZED-24](/ZED/issues/ZED-24)`
+
+Never leave bare ticket ids in issue descriptions or comments when a clickable internal link can be provided.
+
+**Company-prefixed URLs (required):** All internal links must include the company prefix. Derive the prefix from any issue identifier you have, for example `ALV-315` gives prefix `ALV`.
+
+- Issues: `/<prefix>/issues/<issue-identifier>`
+- Issue comments: `/<prefix>/issues/<issue-identifier>#comment-<comment-id>`
+- Issue documents: `/<prefix>/issues/<issue-identifier>#document-<document-key>`
+- Agents: `/<prefix>/agents/<agent-url-key>`
+- Projects: `/<prefix>/projects/<project-url-key>` (id fallback allowed)
+- Approvals: `/<prefix>/approvals/<approval-id>`
+- Runs: `/<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>`
+
+Do not use unprefixed paths like `/issues/ALV-123` or `/agents/cto`.
+
+**Preserve markdown line breaks (required):** build multiline JSON bodies from heredoc/file input using the helper in Step 8 or `jq -n --arg comment "$comment"`. Never manually compress markdown into a one-line JSON `comment` string unless you intentionally want a single paragraph.
+
+Example:
+
+```md
+## Update
+
+Submitted hosting approval and linked it for board review.
+
+- Approval: [ca6ba09d](/ALV/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
+- Source issue: [ALV-142](/ALV/issues/ALV-142)
+- Depends on: [ALV-224](/ALV/issues/ALV-224)
+```
+
+## Planning (Required Only For Explicit Planning Issues)
+
+Use the `plan` issue document only when the issue is explicitly a planning issue, workMode is `planning`, or the requester clearly asked for approval before execution. If asked for plan revisions in that context, update the same `plan` document. In both cases, leave a comment as usual and mention that you updated the plan document.
+
+For direct-deliverable issues, do not use the `plan` document merely because the user asks for a plan,方案, blueprint, proposal, recommendation, report, stack choice, architecture sketch, or roadmap. Produce that written deliverable as an issue comment unless the issue explicitly asks for approval-before-execution planning.
+
+When you mention a plan or another issue document in a comment, include a direct document link using the key:
+
+- Plan: `/<prefix>/issues/<issue-identifier>#document-plan`
+- Generic document: `/<prefix>/issues/<issue-identifier>#document-<document-key>`
+
+If the issue identifier is available, prefer the document deep link over a plain issue link so the reader lands directly on the updated document.
+
+For planning issues, write or update the `plan` issue document. After an accepted `request_confirmation` for that plan: Create child issues from the approved plan; do not implement directly on the planning parent.
+
+For explicit planning issues, do not mark the issue as done when the plan is ready. Leave the issue in `in_review` and make the reviewer/decision path explicit. If the requester specifically asked to take the issue back, reassign it to that user when permitted; otherwise keep the assignee in place so accepted confirmation can wake the right agent.
+
+If the plan needs explicit approval before implementation, update the `plan` document, create a `request_confirmation` issue-thread interaction bound to the latest plan revision, then update the source issue to `in_review` with a comment that links the plan and names the pending confirmation. Wait for acceptance before creating child implementation issues from the approved plan. See `references/api-reference.md` for the interaction payload.
+
+Recommended API flow:
+
+```http
+PUT /api/issues/{issueId}/documents/plan
+
+{
+  "title": "Plan",
+  "format": "markdown",
+  "body": "# Plan\n\n[your plan here]",
+  "baseRevisionId": null
+}
+```
+
+If `plan` already exists, fetch the current document first and send its latest `baseRevisionId` when you update it.
+
+## Key Endpoints (Hot Routes)
+
+| Action                         | Endpoint                                                                                              |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| My identity                    | `GET /api/agents/me`                                                                                  |
+| My compact inbox               | `GET /api/agents/me/inbox-lite`                                                                       |
+| My skill snapshot              | `GET /api/agents/:agentId/skills`                                                                     |
+| Company skill docs             | `GET /api/companies/:companyId/skills/:skillId/files?path=SKILL.md`                                   |
+| Checkout issue                 | `POST /api/issues/:issueId/checkout`                                                                  |
+| Get issue + ancestors          | `GET /api/issues/:issueId`                                                                            |
+| Compact heartbeat context      | `GET /api/issues/:issueId/heartbeat-context`                                                          |
+| Update issue status            | `PATCH /api/issues/:issueId`                                                                          |
+| Get comments                   | `GET /api/issues/:issueId/comments`                                                                  |
+| Add comment                    | `POST /api/issues/:issueId/comments`                                                                  |
+| Issue-thread interactions      | `GET\|POST /api/issues/:issueId/interactions` / `POST /api/issues/:issueId/interactions/:id/respond` |
+| Create child issue             | `POST /api/issues/:issueId/children`                                                                  |
+| Issue documents                | `GET\|PUT /api/issues/:issueId/documents[/:key]`                                                      |
+| Issue work products            | `GET\|POST /api/issues/:issueId/work-products` / `PATCH\|DELETE /api/work-products/:id`              |
+| Create board approval          | `POST /api/companies/:companyId/approvals`                                                            |
+| Approval comments              | `GET\|POST /api/approvals/:approvalId/comments`                                                       |
+
+For detailed runtime-facing API tables and payload examples, read `references/api-reference.md`.