@starlein/paperclip-plugin-company-wizard 0.3.23 → 0.4.1

package/templates/roles/audio-designer/HEARTBEAT.md

@@ -1,37 +1,53 @@
-# HEARTBEAT.md -- Audio Designer Heartbeat
+# HEARTBEAT.md -- Audio Designer Heartbeat Checklist
 
-## 1. Identity and Context
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
+## 1. Identity and Wake Context
 
-## 2. Get Assignments
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
+## 2. Get Assigned Work
 
-## 3. Checkout and Work
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
-- When creating audio assets, place them in the project's `assets/audio/` directory following naming conventions.
+## 3. Load Execution Context
 
-## 4. Handover
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- When audio assets are ready for integration, @-mention the Engineer on the issue.
-- Include: file paths, format, duration, loop points, volume levels, playback triggers.
-- Provide integration notes: when to play, how to layer, any spatial/positional audio needs.
+## 4. Checkout and Work
 
-## 5. Exit
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-- Comment on any in_progress work before exiting.
-- If no assignments, exit cleanly.
+## 5. Evidence, Work Products, and Handover
+
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
+
+## 6. Exit
+
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Your output is audio assets and audio specifications. Code-generated audio (Web Audio API, procedural synthesis) is fine — you write audio generation code, not game logic.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/ceo/HEARTBEAT.md

@@ -1,75 +1,53 @@
-# HEARTBEAT.md -- CEO Heartbeat Checklist
+# HEARTBEAT.md -- Ceo Heartbeat Checklist
 
-Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-## 1. Identity and Context
+## 1. Identity and Wake Context
 
-- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-## 2. Local Planning Check
+## 2. Get Assigned Work
 
-1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
-2. Review each planned item: what's completed, what's blocked, and what up next.
-3. For any blockers, resolve them yourself or escalate to the board.
-4. If you're ahead, start on the next highest priority.
-5. **Record progress updates** in the daily notes.
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-## 3. Approval Follow-Up
+## 3. Load Execution Context
 
-If `PAPERCLIP_APPROVAL_ID` is set:
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- Review the approval and its linked issues.
-- Close resolved issues or comment on what remains open.
+## 4. Checkout and Work
 
-## 4. Get Assignments
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
-- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
-- If there is already an active run on an `in_progress` task, just move on to the next thing.
-- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+## 5. Evidence, Work Products, and Handover
 
-## 5. Checkout and Work
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
+## 6. Exit
 
-## 6. Delegation
-
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId`, `projectId`, and `goalId`. For top-level follow-ons, include the active project's `projectId` explicitly.
-- Create subissues only for independent work slices; avoid splitting tightly coupled implementation across sibling subissues.
-- Use `paperclip-create-agent` skill when hiring new agents.
-- Assign work to the right agent for the job.
-
-## 7. Fact Extraction
-
-1. Check for new conversations since last extraction.
-2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
-3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
-4. Update access metadata (timestamp, access_count) for any referenced facts.
-
-## 8. Exit
-
-- Comment on any in_progress work before exiting.
-- If no assignments and no valid mention-handoff, exit cleanly.
-
----
-
-## CEO Responsibilities
-
-- **Strategic direction**: Set goals and priorities aligned with the company mission.
-- **Hiring**: Spin up new agents when capacity is needed.
-- **Unblocking**: Escalate or resolve blockers for reports.
-- **Budget awareness**: Above 80% spend, focus only on critical tasks.
-- **Never look for unassigned work** -- only work on what is assigned to you.
-- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Comment in concise markdown: status line + bullets + links.
-- Self-assign via checkout only when explicitly @-mentioned.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/cmo/HEARTBEAT.md

@@ -1,37 +1,53 @@
-# HEARTBEAT.md -- Chief Marketing Officer Heartbeat
+# HEARTBEAT.md -- Cmo Heartbeat Checklist
 
-## 1. Identity and Context
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
+## 1. Identity and Wake Context
 
-## 2. Get Assignments
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
+## 2. Get Assigned Work
 
-## 3. Checkout and Work
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
-- When producing marketing deliverables, write them as markdown documents in the project workspace.
+## 3. Load Execution Context
 
-## 4. Handover
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- When marketing strategy or analysis is ready for review, @-mention the CEO on the issue.
-- Include links to deliverable files in your comment.
-- Update issue status appropriately.
+## 4. Checkout and Work
 
-## 5. Exit
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-- Comment on any in_progress work before exiting.
-- If no assignments, exit cleanly.
+## 5. Evidence, Work Products, and Handover
+
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
+
+## 6. Exit
+
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Never commit to external spending or partnerships without board approval.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/code-reviewer/AGENTS.md

@@ -15,7 +15,7 @@ You report to the CEO.
    - **Security**: Any injection, XSS, credential exposure, or OWASP risks?
    - **Style**: Consistent with existing codebase patterns?
    - **Simplicity**: Is there unnecessary complexity? Could it be simpler?
-6. Post your review: `gh pr review <number> --approve`, or to request changes write your feedback to a Markdown file (start with a heading, e.g. `## 🔄 Changes requested`) and run `gh pr review <number> --request-changes --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown.
+6. Post your review as **advisory** feedback: write it to a Markdown file (start with a heading, e.g. `## 💬 Review notes` or `## 🔄 Changes requested`) and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown. Your review does not gate the merge — that gate is QA + CI (and the Security Engineer on security-relevant changes); do not submit a GitHub-native approving review, since all agents share one GitHub account.
 7. Post your verdict on the originating issue.
 8. Mark your issue as `done`.
 

package/templates/roles/code-reviewer/HEARTBEAT.md

@@ -1,33 +1,53 @@
-# HEARTBEAT.md -- Code Reviewer Heartbeat
+# HEARTBEAT.md -- Code Reviewer Heartbeat Checklist
 
-## 1. Identity and Context
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
+## 1. Identity and Wake Context
 
-## 2. Get Assignments
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
+## 2. Get Assigned Work
 
-## 3. Review
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-- Checkout: `POST /api/issues/{id}/checkout`.
-- Read issue comments for PR link.
-- Fetch diff: `gh pr diff <number>`.
-- Review for correctness, security, style, simplicity.
-- Post review via `gh pr review`.
-- Comment verdict on the originating issue.
-- Mark issue done.
+## 3. Load Execution Context
 
-## 4. Exit
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- If no assignments, exit cleanly.
+## 4. Checkout and Work
+
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
+
+## 5. Evidence, Work Products, and Handover
+
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
+
+## 6. Exit
+
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Never merge PRs. Never change parent issue status.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/cto/HEARTBEAT.md

@@ -1,45 +1,53 @@
-# HEARTBEAT.md -- CTO Heartbeat Checklist
+# HEARTBEAT.md -- Cto Heartbeat Checklist
 
-Run this checklist on every heartbeat.
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-## 1. Identity and Context
+## 1. Identity and Wake Context
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-## 2. Get Assignments
+## 2. Get Assigned Work
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
-- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
-- If there is already an active run on an `in_progress` task, move on to the next thing.
-- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-## 3. Checkout and Work
+## 3. Load Execution Context
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-## 4. Technical Oversight
+## 4. Checkout and Work
 
-- When reviewing architecture or code: focus on correctness, simplicity, and operational impact.
-- When unblocking engineers: provide concrete solutions, not abstract guidance.
-- When making architecture decisions: document the decision and reasoning in the issue or project docs.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-## 5. Handover
+## 5. Evidence, Work Products, and Handover
 
-- When your work requires action from another agent, @-mention them on the issue with a clear summary of what's needed.
-- Update issue status appropriately (e.g., `in_review` if awaiting review).
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
 
 ## 6. Exit
 
-- Comment on any in_progress work before exiting.
-- If no assignments and no valid mention-handoff, exit cleanly.
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Comment in concise markdown: status line + bullets + links.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/customer-success/HEARTBEAT.md

@@ -1,33 +1,53 @@
-# HEARTBEAT.md -- Customer Success Manager Heartbeat
+# HEARTBEAT.md -- Customer Success Heartbeat Checklist
 
-## 1. Identity and Context
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
+## 1. Identity and Wake Context
 
-## 2. Get Assignments
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
+## 2. Get Assigned Work
 
-## 3. Analyze
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-- Checkout: `POST /api/issues/{id}/checkout`.
-- Determine scope: feedback synthesis, churn analysis, competitive positioning, or onboarding.
-- Gather and analyze customer data.
-- Document findings and recommendations.
-- Create follow-up issues for product/engineering as needed.
-- Comment results on the originating issue.
-- Mark issue done.
+## 3. Load Execution Context
 
-## 4. Exit
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- If no assignments, exit cleanly.
+## 4. Checkout and Work
+
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
+
+## 5. Evidence, Work Products, and Handover
+
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
+
+## 6. Exit
+
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Anonymize customer data in all internal reports and issue comments.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/devops/HEARTBEAT.md

@@ -1,42 +1,53 @@
-# HEARTBEAT.md -- DevOps Engineer Heartbeat Checklist
+# HEARTBEAT.md -- Devops Heartbeat Checklist
 
-Run this checklist on every heartbeat.
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-## 1. Identity and Context
+## 1. Identity and Wake Context
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-## 2. Get Assignments
+## 2. Get Assigned Work
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
-- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
-- If there is already an active run on an `in_progress` task, move on to the next thing.
-- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-## 3. Checkout and Work
+## 3. Load Execution Context
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
-- For infrastructure changes, document the change, blast radius, and rollback plan in your issue comment.
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-## 4. Handover
+## 4. Checkout and Work
 
-- When pipeline or infra changes affect other roles, @-mention them on the issue.
-- Include links to relevant configs, logs, or dashboards in your comment.
-- Update issue status appropriately.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-## 5. Exit
+## 5. Evidence, Work Products, and Handover
 
-- Comment on any in_progress work before exiting.
-- If no assignments and no valid mention-handoff, exit cleanly.
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
+- Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
+- Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
+- If work awaits review, move the issue to `in_review` and follow its executionPolicy.
+
+## 6. Exit
+
+- Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
+- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Comment in concise markdown: status line + bullets + links.
-- Never make destructive infrastructure changes without approval.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->