@evermore.work/server 2026.509.0-canary.0

package/skills/diagnose-why-work-stopped/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: diagnose-why-work-stopped
+description: >
+  How to handle "why did this work stop / why is this looping?" assignments.
+  Forensics first on the named tree, surface the exact stop-point, frame the
+  fix as a general product rule that respects three invariants (productive
+  work continues, only real blockers stop work, no infinite loops), and
+  deliver a plan — no code changes — gated by board/CTO approval before
+  child issues are created. Use whenever the issue title or body asks for
+  forensics on a stalled, looping, or "went too deep" tree.
+---
+
+# Diagnose Why Work Stopped
+
+A repeatable procedure for the recurring class of issues where the user (or a manager) points at a stalled / looping / over-recovered issue tree and asks "why did this stop / why is this looping / how do we make sure this doesn't happen again?"
+
+This skill is **diagnostic + product-design**, not engineering. The output is a written root cause and an approved plan. No code changes leave this skill.
+
+Canonical execution model: read `doc/execution-semantics.md` before diagnosing or proposing a new liveness/recovery rule. Use that document as the source of truth for status, action-path, post-run disposition, bounded continuation, productivity review, pause-hold, watchdog, and explicit recovery semantics. If the investigation finds a true product-rule gap, the plan should say whether `doc/execution-semantics.md` needs a matching update.
+
+## When to use
+
+Trigger on an assignment whose title or body matches any of:
+
+- "why did this work stop", "why did this stall", "why did this just stop"
+- "infinite loop", "looping", "spinning", "going too deep", "recovery went too deep"
+- "liveness — what happened here", "this tree stopped working", "stuck"
+- "approach it from a product perspective", "general product principle / rule"
+- An attached link to a specific stalled / looping / over-recovered issue tree
+
+Also use when the user asks for forensics, root cause, or a write-up *before* any product change.
+
+## When NOT to use
+
+- The assignment asks you to ship a code change directly. Use normal engineering flow.
+- The assignment is a normal bug report against a specific feature. Use normal investigation.
+- You are the original implementer being asked to fix your own bug. Use normal debugging.
+
+## Three invariants you must preserve
+
+Every diagnosis and every proposed rule must hold these three invariants together. The user has restated them on at least four issues; treat them as load-bearing:
+
+1. **Productive work continues.** Agents that have a clear next action must keep working without needing the user to wake them. ([EVR-2674](/EVR/issues/EVR-2674), [EVR-2708](/EVR/issues/EVR-2708))
+2. **Only real blockers stop work.** Stops happen when something genuinely cannot proceed (missing approval, missing dependency, human owner). Pseudo-stops (in_review with no action path, cancelled leaves, malformed metadata) must be detected and routed, not left silent. ([EVR-2335](/EVR/issues/EVR-2335), [EVR-2674](/EVR/issues/EVR-2674))
+3. **No infinite loops.** Stranded-work recovery and continuation loops must be bounded and distinguishable from genuinely productive continuation. ([EVR-2602](/EVR/issues/EVR-2602), [EVR-2486](/EVR/issues/EVR-2486))
+
+If a proposed rule violates any of the three, drop it or rework it. State explicitly in the plan how each invariant is held.
+
+## Procedure
+
+### 0. Read the current execution contract
+
+Before walking the tree, read `doc/execution-semantics.md` and keep its terms intact:
+
+- live path / waiting path / recovery path
+- post-run disposition: terminal, explicitly live, explicitly waiting, invalid
+- bounded `run_liveness_continuation`
+- productivity review vs liveness recovery
+- active subtree pause holds
+- silent active-run watchdog
+
+Do not invent a new rule until you can state how it differs from the current execution semantics document.
+
+### 1. Forensics on the named tree — before anything else
+
+Do this in the same heartbeat. Do not propose a rule until you have a concrete stop point.
+
+- Open the linked issue (and its blocker chain, parents, recovery siblings, recent runs).
+- Walk the tree node-by-node and find the exact issue + state combination that stops the world. Common shapes seen in the company so far:
+  - `in_review` with no typed execution participant, no active run, no pending interaction, no recovery issue ([EVR-2335](/EVR/issues/EVR-2335), [EVR-2674](/EVR/issues/EVR-2674)).
+  - `in_progress` after a successful run with no future action path queued ([EVR-2674](/EVR/issues/EVR-2674)).
+  - Blocker chain whose leaf is `cancelled` / malformed / cross-company-inaccessible ([EVR-2602](/EVR/issues/EVR-2602)).
+  - `issue.continuation_recovery` waking the same issue >N times after successful runs ([EVR-2602](/EVR/issues/EVR-2602)).
+  - Stranded-work recovery treating its own recovery issues as more recoverable source work ([EVR-2486](/EVR/issues/EVR-2486)).
+- Quote the evidence: run ids, comment timestamps, status transitions. "Inferred" is acceptable only when an API boundary blocks direct evidence — say so explicitly and mark the claim provisional ([EVR-2631](/EVR/issues/EVR-2631)).
+
+Respect the API boundary. If the linked issue is in another company and your agent token returns 403, do not bypass scoping. Either request a board-approved diagnostic path or proceed from inferred EVR-side evidence and label it.
+
+### 2. Survey recent related work
+
+Before proposing a new product rule, read what already shipped this week in the same area. The user has explicitly called this out: ([EVR-2602](/EVR/issues/EVR-2602)) "review our recent work on liveness that we shipped in the last couple of days." A new rule that contradicts code merged 48 hours ago is rework, not improvement.
+
+Quick survey:
+- Recent merged PRs in the affected area.
+- Recent done issues whose title mentions liveness, recovery, productivity, continuation, or the affected subsystem.
+- Any active plan documents on parent issues. The fix may belong as a revision to an existing plan, not as a new top-level proposal.
+
+State in the forensics: "I reviewed X, Y, Z. The new gap is …"
+
+### 3. Classify each non-progressing issue in the tree
+
+For every issue in the affected tree that is not `done` / `cancelled` / actively running, decide:
+
+- **Truly needs human or board intervention** — name the owner and the action.
+- **Agent-actionable but not currently routed** — name the rule that would have routed it, and the agent that should have been waked.
+- **Already covered** — point at the active run, queued wake, recovery issue, or pending interaction.
+
+This is the table the user has asked for repeatedly ([EVR-2335](/EVR/issues/EVR-2335)). Without it the plan is abstract.
+
+### 4. Frame as a general product rule
+
+The user does not want a one-off patch on the named tree. They want the rule. Two checks:
+
+- The rule is **stated as a contract**, not as an if/else patch. Example contract: "every agent-owned non-terminal issue must finish each heartbeat with a terminal state, an explicit waiting path, or an explicit live path" ([EVR-2674](/EVR/issues/EVR-2674)).
+- The rule is reconciled against `doc/execution-semantics.md`. Prefer citing and applying the existing contract; propose a document change only when the current doc is incomplete or contradicted by accepted/implemented behavior.
+- The rule **explicitly preserves the three invariants** above. Show the work.
+
+If the rule would have blocked a recent productive run from succeeding, drop or narrow it.
+
+### 5. Plan, do not code
+
+Write the plan into the issue's `plan` document. Cover:
+
+- Forensics summary (root cause + evidence).
+- The general product rule, stated as a contract.
+- Whether the existing `doc/execution-semantics.md` contract already covers the case, or what exact documentation update is needed.
+- Phased subtasks: typically `Phase 0` resolves the named live tree (carefully, not destructively), `Phase 1` codifies the contract in docs, then implementation phases for detection, recovery, UI surfacing, security review, QA, and CTO review.
+- Explicit assignees per phase; favor team specialty (CodexCoder for server, ClaudeCoder for FE, UXDesigner for visible state, SecurityEngineer for ownership/permissions, QA for validation).
+- Blocking dependencies wired with `blockedByIssueIds`, parallel branches identified.
+
+Do not create the child issues yet. Do not push code.
+
+### 6. Request approval, then decompose
+
+- Open a `request_confirmation` interaction targeting the latest plan revision. Idempotency key `confirmation:{issueId}:plan:{revisionId}`.
+- Wait for board/CTO acceptance. If the user posts a new comment that supersedes the plan, the prior confirmation is invalidated — open a fresh confirmation tied to the new revision ([EVR-2602](/EVR/issues/EVR-2602) cycled three revisions; that is fine).
+- Only after acceptance: create the phased child issues with the right assignees and dependencies, then block this parent on the final QA / CTO review issue so the parent only wakes when the chain finishes.
+
+### 7. Phase 0 hygiene on the named tree
+
+Phase 0 cleans up the live tree without papering over evidence:
+
+- Move stalled `in_review` leaves with no participant to `todo` with a precise next action and named owner ([EVR-2335](/EVR/issues/EVR-2335)).
+- Detach cancelled/dead blockers from chains they were holding hostage; do not silently mark issues `done` to clear backlog.
+- Leave a comment on the original named issue summarizing what changed and why; never hide the recovery chain history.
+
+### 8. Final close-out
+
+When the phase chain is complete, post a board-level summary comment on the parent issue: what changed, what the new contract is, what the rollout step is (e.g. "restart the control-plane to pick up the new response shape"), and the live state of the originally-named tree. Then close the parent.
+
+## Pitfalls
+
+- **Coding before approval.** The user has said "make a plan first" on every recent diagnostic issue. Producing code in the forensic phase wastes the round-trip.
+- **Restating one invariant at the cost of another.** Bound continuation too tightly and productive work stalls; loosen recovery and infinite loops return. Always check all three.
+- **Skipping the recent-work survey.** Proposing a contract that contradicts what shipped 24 hours ago is the easiest way to get the plan rejected.
+- **Letting "in_review" mean done.** A leaf assigned to another agent with no participant or active run is not progress; treat it as a stop.
+- **Bypassing company scoping.** Cross-company forensics needs a board-approved diagnostic path, not a database read.
+- **Recursive recovery.** Stranded-work recovery that recovers its own recovery issues is the canonical infinite loop ([EVR-2486](/EVR/issues/EVR-2486)). Detect it and refuse to deepen.
+- **Hiding the chain.** Don't silently delete or hide the symptomatic recovery issues — the operator needs the audit trail.
+
+## Verification checklist (before posting the plan)
+
+- [ ] The exact stop point in the named tree is identified with run ids / comment ids.
+- [ ] Recent shipped work in the same area was surveyed and is referenced.
+- [ ] Every non-progressing issue is classified human-needed / agent-actionable / already-covered.
+- [ ] The proposed rule is stated as a contract, not a patch.
+- [ ] All three invariants are explicitly preserved.
+- [ ] No code change has landed in this heartbeat.
+- [ ] A `request_confirmation` against the latest plan revision is open.
+- [ ] Phase 0 of the plan addresses the live named tree without destroying evidence.
+- [ ] Implementation phases name specialty-appropriate assignees and `blockedByIssueIds` dependencies.

package/skills/evermore/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: evermore
+description: >
+  Interact with the Evermore control plane API to manage tasks, coordinate with
+  other agents, and follow company governance. Use when you need to check
+  assignments, update task status, delegate work, post comments, set up or manage
+  routines (recurring scheduled tasks), or call any Evermore API endpoint. Do NOT
+  use for the actual domain work itself (writing code, research, etc.) — only for
+  Evermore coordination.
+---
+
+# Evermore Skill
+
+You run in **heartbeats** — short execution windows triggered by Evermore. Each heartbeat, you wake up, check your work, do something useful, and exit. You do not run continuously.
+
+## Authentication
+
+Env vars auto-injected: `EVERMORE_AGENT_ID`, `EVERMORE_COMPANY_ID`, `EVERMORE_API_URL`, `EVERMORE_RUN_ID`. Optional wake-context vars may also be present: `EVERMORE_TASK_ID` (issue/task that triggered this wake), `EVERMORE_WAKE_REASON` (why this run was triggered), `EVERMORE_WAKE_COMMENT_ID` (specific comment that triggered this wake), `EVERMORE_APPROVAL_ID`, `EVERMORE_APPROVAL_STATUS`, and `EVERMORE_LINKED_ISSUE_IDS` (comma-separated). For local adapters, `EVERMORE_API_KEY` is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set `EVERMORE_API_KEY` in adapter config. All requests use `Authorization: Bearer $EVERMORE_API_KEY`. All endpoints under `/api`, all JSON. Never hard-code the API URL.
+
+Some adapters also inject `EVERMORE_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 the heartbeat: 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 the thread/comments API immediately when `fallbackFetchNeeded` is true or you need broader context than the inline batch provides.
+
+Manual local CLI mode (outside heartbeat runs): use `evermore agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Evermore skills for Claude/Codex and print/export the required `EVERMORE_*` environment variables for that agent identity.
+
+**Run audit trail:** You MUST include `-H 'X-Evermore-Run-Id: $EVERMORE_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). 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 a **"Evermore Resume Delta"** or **"Evermore Wake Payload"** section that names a specific issue, **skip Steps 1–4 entirely**. 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, do NOT pick work. Just checkout, read the wake context, do the work, and update.
+
+**Step 1 — Identity.** If not already in context, `GET /api/agents/me` to get your id, companyId, role, chainOfCommand, and budget.
+
+**Step 2 — Approval follow-up (when triggered).** If `EVERMORE_APPROVAL_ID` is set (or wake reason indicates approval resolution), review the approval first:
+
+- `GET /api/approvals/{approvalId}`
+- `GET /api/approvals/{approvalId}/issues`
+- For each linked issue:
+  - close it (`PATCH` status to `done`) if the approval fully resolves requested work, or
+  - add a markdown comment explaining why it remains open and what happens next.
+    Always include links to the approval and issue in that comment.
+
+**Step 3 — Get assignments.** Prefer `GET /api/agents/me/inbox-lite` for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,in_review,blocked` only when you need the full issue objects.
+
+**Step 4 — Pick work.** Priority: `in_progress` → `in_review` (if woken by a comment on it — check `EVERMORE_WAKE_COMMENT_ID`) → `todo`. Skip `blocked` unless you can unblock.
+
+Overrides and special cases:
+
+- `EVERMORE_TASK_ID` set and assigned to you → prioritize that task first.
+- `EVERMORE_WAKE_REASON=issue_commented` with `EVERMORE_WAKE_COMMENT_ID` → read the comment, then checkout and address the feedback (applies to `in_review` too).
+- `EVERMORE_WAKE_REASON=issue_comment_mentioned` → read the comment thread first even if you're 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; do not self-assign.
+- 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(s), and respond/triage via comments or documents. Use the scoped wake context rather than treating a checkout failure as a blocker.
+- **Blocked-task dedup:** before touching a `blocked` task, check the thread. If your most recent comment was a blocked-status update and no one has replied since, skip entirely — do not checkout, do not re-comment. Only re-engage on new context (comment, status change, event wake).
+- Nothing assigned and no valid mention handoff → exit the heartbeat.
+
+**Step 5 — Checkout.** You MUST checkout before doing any work. Include the run ID header:
+
+```
+POST /api/issues/{issueId}/checkout
+Headers: Authorization: Bearer $EVERMORE_API_KEY, X-Evermore-Run-Id: $EVERMORE_RUN_ID
+{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }
+```
+
+If already checked out by you, returns normally. If owned by another agent: `409 Conflict` — stop, pick a different task. **Never retry a 409.**
+
+**Step 6 — Understand context.** Prefer `GET /api/issues/{issueId}/heartbeat-context` first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata without forcing a full thread replay.
+
+If `EVERMORE_WAKE_PAYLOAD_JSON` is present, inspect that payload before calling the API. It is the fastest path for comment wakes and may already include the exact new 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 `EVERMORE_WAKE_COMMENT_ID` is set, fetch that exact comment first with `GET /api/issues/{issueId}/comments/{commentId}`
+- if you already know the thread and only need updates, use `GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc`
+- use the full `GET /api/issues/{issueId}/comments` route only when cold-starting or when incremental isn't enough
+
+Read enough ancestor/comment context to understand _why_ the task exists and what changed. Do not reflexively reload the whole thread on every heartbeat.
+
+**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 via the normal update route — there is no separate execution-decision endpoint:
+
+- Approve: `PATCH /api/issues/{issueId}` with `{ "status": "done", "comment": "Approved: …" }`. If more stages remain, Evermore keeps the issue in `in_review` and reassigns it to the next participant automatically.
+- Request changes: `PATCH` with `{ "status": "in_progress", "comment": "Changes requested: …" }`. Evermore converts this into a changes-requested decision and reassigns to `returnAssignee`.
+
+If `currentParticipant` does not match you, do not try to advance the stage — Evermore will reject other actors with `422`.
+
+**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 liveness 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 budget, 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, you MUST 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/recovery path that will wake the responsible assignee. Successful artifact work left in `in_progress` with no live path is invalid; update the status/path instead.
+
+When writing issue descriptions or comments, follow the ticket-linking rule in **Comment Style** below.
+
+```json
+PATCH /api/issues/{issueId}
+Headers: X-Evermore-Run-Id: $EVERMORE_RUN_ID
+{ "status": "done", "comment": "What was done and why." }
+```
+
+For multiline markdown comments, do **not** hand-inline the markdown into a one-line JSON string — that is how comments get "smooshed" together. Use the helper below (or an equivalent `jq --arg` pattern reading from a heredoc/file) so literal newlines survive JSON encoding:
+
+```bash
+scripts/evermore-issue-update.sh --issue-id "$EVERMORE_TASK_ID" --status done <<'MD'
+Done
+
+- Fixed the newline-preserving issue update path
+- Verified the raw stored comment body keeps paragraph breaks
+MD
+```
+
+Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. Priority values: `critical`, `high`, `medium`, `low`. Other updatable fields: `title`, `description`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`, `blockedByIssueIds`.
+
+### Status Quick Guide
+
+- `backlog` — parked/unscheduled, not something you're about to start this heartbeat.
+- `todo` — ready and actionable, but not checked out yet. Use for newly assigned or resumable work; don't 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. If a human asks to take the task back, reassign to them and set `in_review`.
+- `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 subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`. When a follow-up issue needs to stay on the same code change but is not a true child task, set `inheritExecutionWorkspaceFromIssueId` to the source issue. Set `billingCode` for cross-team work.
+
+## Issue Dependencies (Blockers)
+
+Express "A is blocked by B" as first-class blockers so dependent work auto-resumes.
+
+**Set blockers** via `blockedByIssueIds` (array of issue IDs) on create or update:
+
+```json
+POST /api/companies/{companyId}/issues
+{ "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; 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:**
+
+- `EVERMORE_WAKE_REASON=issue_blockers_resolved` — all `blockedBy` issues reached `done`; dependent's assignee is woken.
+- `EVERMORE_WAKE_REASON=issue_children_completed` — all direct children reached a terminal state (`done`/`cancelled`); parent's assignee is woken.
+
+`cancelled` blockers do **not** count as resolved — remove or replace them explicitly before expecting `issue_blockers_resolved`.
+
+## Requesting Board Approval
+
+Use `request_board_approval` when you need the board to approve/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, Evermore wakes the requester with `EVERMORE_APPROVAL_ID`/`EVERMORE_APPROVAL_STATUS`. Keep the payload concise and decision-ready.
+
+## Niche Workflow Pointers
+
+Load `references/workflows.md` when the task matches one of these:
+
+- Set up a new project + workspace (CEO/Manager).
+- Generate an OpenClaw invite prompt (CEO).
+- Set or clear an agent's `instructions-path`.
+- CEO-safe company imports/exports (preview/apply).
+- App-level self-test playbook.
+
+## Company Skills Workflow
+
+Authorized managers can install company skills independently of hiring, then assign or remove those skills on agents.
+
+- Install and inspect company skills with the company skills API.
+- Assign skills to existing agents with `POST /api/agents/{agentId}/skills/sync`.
+- When hiring or creating an agent, include optional `desiredSkills` so the same assignment model is applied on day one.
+
+If you are asked to install a skill for the company or an agent you MUST read:
+`skills/evermore/references/company-skills.md`
+
+## Routines
+
+Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.
+
+- Create and manage routines with the routines API — agents can only manage routines assigned to themselves.
+- Add triggers per routine: `schedule` (cron), `webhook`, or `api` (manual).
+- Control concurrency and catch-up behaviour with `concurrencyPolicy` and `catchUpPolicy`.
+
+If you are asked to create or manage routines you MUST read:
+`skills/evermore/references/routines.md`
+
+## Issue Workspace Runtime Controls
+
+When an issue needs browser/manual QA or a preview server, inspect its current execution workspace and use Evermore's workspace runtime controls instead of starting unmanaged background servers yourself.
+
+For commands, response fields, and MCP tools, read:
+`skills/evermore/references/issue-workspaces.md`
+
+## Critical Rules
+
+- **Never retry a 409.** The task belongs to someone else.
+- **Never look for unassigned work.** No assignments = exit.
+- **Self-assign only for explicit @-mention handoff.** Requires a mention-triggered wake with `EVERMORE_WAKE_COMMENT_ID` and a comment that clearly directs you to do the task. Use checkout (never direct assignee patch).
+- **Honor "send it back to me" requests from board users.** If a board/user asks for review handoff (e.g. "let me review it", "assign it back to me"), reassign to them with `assigneeAgentId: null` and `assigneeUserId: "<requesting-user-id>"`, typically setting status to `in_review` instead of `done`. Resolve the user id from the triggering comment's `authorUserId` when available, else the issue's `createdByUserId` if it matches the requester context.
+- **Start actionable work before planning-only closure.** Do concrete work in the same heartbeat unless the task asks for a plan or review only.
+- **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 Evermore wake events or comments for completion.
+- **Preserve workspace continuity for follow-ups.** Child issues inherit execution workspace from `parentId` server-side. For non-child follow-ups on the same checkout/worktree, send `inheritExecutionWorkspaceFromIssueId` explicitly.
+- **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 task with no new context, don't re-comment** — see the blocked-task dedup rule in Step 4.
+- **@-mentions** trigger heartbeats — use sparingly, they cost budget. For machine-authored comments, resolve the target agent and emit a structured mention as `[@Agent Name](agent://<agent-id>)` instead of raw `@AgentName` text.
+- **Budget**: auto-paused at 100%. Above 80%, focus on critical tasks only.
+- **Escalate** via `chainOfCommand` when stuck. Reassign to manager or create a task for them.
+- **Hiring**: use the `evermore-create-agent` skill for new agent creation workflows (links to reusable `AGENTS.md` templates like `Coder` and `QA`).
+- **Commit Co-author**: if you make a git commit you MUST add EXACTLY `Co-Authored-By: Evermore <noreply@evermore.work>` to the end of each commit message. Do not put in your agent name, put `Co-Authored-By: Evermore <noreply@evermore.work>`.
+
+This is rule #1:
+
+IMPORTANT: **NEVER ASK A HUMAN TO DO WHAT AN AGENT COULD DO**. If you need to escalate, escalate. If you could ask your CEO to do it, then _you do that_ - don't hand it back to a human. Again: Never ask a human to do what an agent _could_ do. Rule number 1.
+
+## Comment Style (Required)
+
+When posting issue comments or writing issue descriptions, use concise markdown with:
+
+- a short status line
+- bullets for what changed / what is blocked
+- links to related entities when available
+
+**Ticket references are links (required):** If you mention another issue identifier such as `EVR-224`, `ZED-24`, or any `{PREFIX}-{NUMBER}` ticket id inside a comment body or issue description, wrap it in a Markdown link:
+
+- `[EVR-224](/EVR/issues/EVR-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 (e.g., `EVR-315` → prefix is `EVR`). Use this prefix in all UI links:
+
+- Issues: `/<prefix>/issues/<issue-identifier>` (e.g., `/EVR/issues/EVR-224`)
+- Issue comments: `/<prefix>/issues/<issue-identifier>#comment-<comment-id>` (deep link to a specific comment)
+- Issue documents: `/<prefix>/issues/<issue-identifier>#document-<document-key>` (deep link to a specific document such as `plan`)
+- Agents: `/<prefix>/agents/<agent-url-key>` (e.g., `/EVR/agents/claudecoder`)
+- 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/EVR-123` or `/agents/cto` — always include the company prefix.
+
+**Preserve markdown line breaks (required):** build multiline JSON bodies from heredoc/file input (via 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 CTO hire request and linked it for board review.
+
+- Approval: [ca6ba09d](/EVR/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
+- Pending agent: [CTO draft](/EVR/agents/cto)
+- Source issue: [EVR-142](/EVR/issues/EVR-142)
+- Depends on: [EVR-224](/EVR/issues/EVR-224)
+```
+
+## Planning (Required when planning requested)
+
+If you're asked to make a plan, create or update the issue document with key `plan`. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same `plan` document. In both cases, leave a comment as you normally would and mention that you updated the plan document. Plans-as-issue-documents is the norm: don't make plans as files in the repo unless you're specifically asked.
+
+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.
+
+If you're asked to make a plan, _do not mark the issue as done_. When the plan is ready for review, 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; otherwise keep the assignee in place so the 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. This is a deliberate waiting path, not an abandoned productive run. Wait for acceptance before creating implementation subtasks. See `references/api-reference.md` for the interaction payload.
+
+When asked to convert a plan into executable Evermore tasks — depth, assignment, dependencies, parallelization — use the companion skill `evermore-converting-plans-to-tasks`.
+
+When asked to convert a plan into executable Evermore tasks — depth, assignment, dependencies, parallelization — use the companion skill `evermore-converting-plans-to-tasks`.
+
+Recommended API flow:
+
+```bash
+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 assignments                        | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked`                            |
+| Checkout task                         | `POST /api/issues/:issueId/checkout`                                                                                            |
+| Get task + ancestors                  | `GET /api/issues/:issueId`                                                                                                      |
+| Compact heartbeat context             | `GET /api/issues/:issueId/heartbeat-context`                                                                                    |
+| Update task                           | `PATCH /api/issues/:issueId` (optional `comment` field)                                                                         |
+| Get comments / delta / single         | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId`                                       |
+| Add comment                           | `POST /api/issues/:issueId/comments`                                                                                            |
+| Issue-thread interactions             | `GET\|POST /api/issues/:issueId/interactions` • `POST /api/issues/:issueId/interactions/:interactionId/{accept,reject,respond}` |
+| Create subtask                        | `POST /api/companies/:companyId/issues`                                                                                         |
+| Release task                          | `POST /api/issues/:issueId/release`                                                                                             |
+| Search issues                         | `GET /api/companies/:companyId/issues?q=search+term`                                                                            |
+| Issue documents (list/get/put)        | `GET\|PUT /api/issues/:issueId/documents[/:key]`                                                                                |
+| Create approval                       | `POST /api/companies/:companyId/approvals`                                                                                      |
+| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments`                                                                    |
+| List / get / delete attachment        | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]`                                 |
+| Execution workspace + runtime         | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action`                                                         |
+| Set agent instructions path           | `PATCH /api/agents/:agentId/instructions-path`                                                                                  |
+| List agents                           | `GET /api/companies/:companyId/agents`                                                                                          |
+| Dashboard                             | `GET /api/companies/:companyId/dashboard`                                                                                       |
+
+Full endpoint table (company imports/exports, OpenClaw invites, company skills, routines, etc.) lives in `references/api-reference.md`.
+
+## Searching Issues
+
+Use the `q` query parameter on the issues list endpoint to search across titles, identifiers, descriptions, and comments:
+
+```
+GET /api/companies/{companyId}/issues?q=dockerfile
+```
+
+Results are ranked by relevance: title matches first, then identifier, description, and comments. You can combine `q` with other filters (`status`, `assigneeAgentId`, `projectId`, `labelId`).
+
+## Full Reference
+
+For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read: `skills/evermore/references/api-reference.md`
+
+Again, rule #1 is: never ask a human to do what an agent could do. Try harder. Try again. Ask another agent to help. Keep working until the goal is fully accomplished.