@starlein/paperclip-plugin-company-wizard 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
   "repository": "https://github.com/starlein/paperclip-plugin-company-wizard",

package/templates/bootstrap-instructions.md

@@ -19,7 +19,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 2. **Projects** — create with `POST /api/companies/{companyId}/projects` using `{ name, description, goalIds, workspace, executionWorkspacePolicy? }`. Reference goals via `goalIds`; create after all goals exist. Valid project `status` (optional, defaults to `backlog`): `backlog`, `planned`, `in_progress`, `completed`, `cancelled` — **`active` is a goal status, NOT a project status; do not set it on a project.** Create the project workspace as an object, not a raw string. Fresh/new repositories use a local project workspace such as `workspace: { sourceType: "local_path", cwd: "...", defaultRef: "main", setupCommand: "git init -b main", isPrimary: true }` and must initialize Git before work starts; do not attach an `executionWorkspacePolicy` to a fresh local repo (the repo has no base ref yet). Existing repository-backed projects use the workspace refs shown in this bootstrap exactly as rendered; do not rewrite them to `main`, `master`, or add/remove `origin/`. When this bootstrap includes `executionWorkspacePolicy`, send it exactly as rendered; it was included only because Paperclip's experimental isolated-workspaces setting is enabled, and its `workspaceStrategy.baseRef` comes from project/worktree settings. Never inline credentials in repo URLs.
 3. **Labels** — if the bootstrap includes an Issues section, create issue labels first (`POST /api/companies/{companyId}/labels` with `{ name, color }`). Colors must be 6-digit hex strings with a leading `#`.
 4. **Agents** — hire via governance (`POST /api/companies/{companyId}/agent-hires`) using the listed `adapterType`, nested `adapterConfig`, `runtimeConfig`, `capabilities`, and `metadata`. The Company Wizard already created the CEO for this bootstrap issue; reuse/update any existing agent with the same `metadata.templateRole` instead of creating a duplicate.
-5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap.
+5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap. Set workspace isolation explicitly: **top-level issues** (no `parentId`) must include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch; **subtasks** set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace.
 6. **Routines** — reference project and agent. Create the routine first, then add a schedule trigger with `POST /api/routines/{routineId}/triggers` using `{ kind: "schedule", cronExpression: schedule, timezone: "UTC" }`.
 
 **Status + subissue guardrails:**
@@ -27,7 +27,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 - Parent and subissue status are related by intent, not automatically coupled by tooling.
 - Do not auto-mark a parent `done` just because a child changed status.
 - Do not auto-reopen a `done` parent/subissue unless you have an explicit reason and record it in a comment.
-- Do not implicitly reuse a parent workspace for subissues; keep `projectId` explicit and respect the project/issue execution workspace policy. Use isolated workspaces only when Paperclip created one for the issue.
+- Make workspace intent explicit at creation; never rely on implicit inheritance. A top-level issue (no `parentId`) created without `executionWorkspaceSettings` silently adopts the workspace of whatever issue the creator currently has checked out, which serializes work and corrupts branch state. Therefore: top-level issues set `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` (own worktree); subissues set `parentId` and omit `executionWorkspaceSettings` so they deliberately share the parent's workspace (safe because the parent cannot be completed/cleaned up while subissues are open). Keep `projectId` explicit on both.
 
 **Review workflow guardrail:**
 

package/templates/modules/architecture-plan/agents/ui-designer/skills/design-system.md

@@ -13,7 +13,7 @@ You own the visual design system. Establish the foundational patterns that ensur
    - **Brand guidelines**: Logo usage, tone of visual language, iconography style
    - **Responsive breakpoints**: Mobile, tablet, desktop sizing approach
 3. Create implementation issues for the engineer:
-   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 4. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
 
 ## Rules

package/templates/modules/architecture-plan/skills/architecture-plan.md

@@ -13,7 +13,7 @@ You own system architecture. Design the structure that implements the tech stack
    - **Deployment model**: How the system is built, tested, and deployed
    - **Key decisions**: Architectural decisions with rationale (ADR-style)
 3. Create implementation issues for the foundational structure:
-   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 
 ## Rules
 

package/templates/modules/auto-assign/README.md

@@ -1,23 +1,25 @@
 # Module: auto-assign
 
-Adds automatic issue assignment to the CEO heartbeat.
+Adds a low-frequency safety net for issue assignment. Primary dispatch happens at backlog grooming — issues are assigned at creation. This module only catches stragglers.
 
 ## What it adds
 
-- **CEO skill**: Assignment check — when there are idle agents and unassigned issues, the CEO assigns the highest-priority issue to the right agent.
+- **Product Owner skill**: Safety-net assignment check — assigns any still-unassigned backlog items to the best-fit available agent.
+- **CEO fallback skill**: Steps in when the PO is absent or stalled.
 
 ## How it works
 
-On every heartbeat, the CEO checks:
+Primary assignment happens during backlog grooming: the Product Owner creates issues and assigns each to the best-fit agent immediately. The auto-assign routine is a **safety net** that runs every 4 hours to catch anything that slipped through:
+
 1. Are there unassigned issues in `todo` status?
-2. Are there agents in `idle` status who could handle them?
-3. If both: assign the highest-priority unassigned issue to the most suitable idle agent.
+2. Do those issues have enough acceptance criteria and no unresolved blockers?
+3. If yes: assign every suitable straggler to the best-fit available role in one pass — do not drip-feed one issue per routine run.
 
 ## Best for
 
-- Keeping engineers busy without manual assignment
+- Catching assignment misses without relying on manual cleanup
 - Any team size — works with one engineer or many
 
 ## Example
 
-An engineer finishes an issue and goes idle. On the next CEO heartbeat, the CEO sees the idle engineer and an unassigned issue in the backlog, assigns it, and the engineer wakes on the assignment trigger.
+The Product Owner normally assigns issues at creation during backlog grooming. If one slips through unassigned, the safety-net routine assigns it on the next pass and the assignee wakes on the assignment trigger.

package/templates/modules/auto-assign/agents/ceo/heartbeat-section.md

@@ -1,3 +1,5 @@
 ## Auto-Assign Routine Fallback
 
-Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created. This routine is a **safety net** that catches stragglers when the Product Owner hasn't acted.
+
+Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.

package/templates/modules/auto-assign/agents/ceo/skills/auto-assign.fallback.md

@@ -1,18 +1,24 @@
 # Skill: Auto-Assign (Fallback)
 
-The Product Owner primarily handles issue assignment. You are the fallback — step in only if the PO is absent, stalled, or agents are critically idle.
+Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created. This routine is a **safety net** behind that primary path. You step in only if the PO is absent, stalled, or agents are critically idle.
 
 ## Assignment Check (Fallback)
 
 On your heartbeat, after handling your own assignments:
 
-1. Query idle agents: `GET /api/companies/{companyId}/agents`, then filter client-side for those where `status == "idle"`
-2. If agents have been idle with unassigned issues available AND the Product Owner hasn't acted recently:
-   - Assign the highest-priority unassigned issue to the most suitable idle agent
-   - Comment on the issue noting the assignment
-3. If the Product Owner is active, skip this step.
+1. Confirm this is the active routine-run issue and checkout it before mutating the board.
+2. Query unassigned ready issues: `GET /api/companies/{companyId}/issues?status=todo` (filter for unassigned).
+3. If unassigned issues are available AND the Product Owner hasn't acted recently:
+   - Assign every suitable still-unassigned issue to its best-fit available agent (an agent may hold a short queue): `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment.
+   - Clear stragglers in one pass instead of drip-feeding one issue per run.
+4. If the Product Owner is active, skip this step.
+5. Leave a routine-run comment summarizing assigned issue ids and skipped issue ids.
+6. Mark the routine-run issue done when complete.
 
 ## Rules
 
-- This is a safety net. Let the PO own assignment.
-- Only assign when agents would otherwise sit idle.
+- This is a safety net behind backlog grooming's direct assignment. Let the PO own assignment.
+- Clear stragglers in one pass instead of drip-feeding one issue per run.
+- Do not run this from normal heartbeats.
+- Do not self-assign random unassigned work.
+- If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.

package/templates/modules/auto-assign/agents/product-owner/heartbeat-section.md

@@ -1,3 +1,5 @@
 ## Auto-Assign Routine
 
-Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created, not through this routine. This routine is a **safety net** that catches stragglers every 4 hours.
+
+Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.

package/templates/modules/auto-assign/module.meta.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-assign",
-  "description": "Automatically assigns unowned backlog items to available agents. Keeps work flowing without manual dispatch.",
+  "description": "Safety net that assigns any still-unowned backlog items to available agents. Primary dispatch happens at backlog grooming (issues are assigned at creation); this low-frequency routine only catches stragglers.",
   "permissions": [
     "tasks:assign"
   ],
@@ -17,9 +17,9 @@
   "routines": [
     {
       "title": "Auto-assign unassigned issues",
-      "description": "Routine-run checklist: review unassigned todo issues, assign each actionable item to the best available agent based on role/workload, record evidence and next actions on the routine issue, then exit.",
+      "description": "Safety-net routine-run checklist (primary assignment happens at backlog grooming, so this usually finds nothing): review any still-unassigned todo issues, assign each actionable item to its best-fit available agent based on role/workload — clear out all stragglers, not one at a time — record evidence and next actions on the routine issue, then exit.",
       "assignTo": "capability:auto-assign",
-      "schedule": "0 */2 * * *",
+      "schedule": "0 */4 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

package/templates/modules/auto-assign/skills/auto-assign.md

@@ -1,6 +1,6 @@
 # Skill: Auto-Assign
 
-You own issue assignment when you are explicitly assigned an auto-assignment routine run. This is not an every-heartbeat background scan.
+You own issue assignment when you are explicitly assigned an auto-assignment routine run. This is a low-frequency **safety net** behind backlog grooming, which assigns issues at creation — so most runs find nothing to do. This is not an every-heartbeat background scan.
 
 ## When To Use This Skill
 
@@ -13,7 +13,7 @@ Use this only when the current assigned issue/routine is titled like "Auto-assig
 3. Query candidate issues using the board's current issue API for unassigned `todo` work, scoped to the relevant project/goal when the routine has one.
 4. Skip issues that are blocked, awaiting approval/review, missing acceptance criteria, or already have active execution state.
 5. Match issue labels, required skills, project context, and priority to agent role/capabilities.
-6. Assign at most one issue per available agent: `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment explaining why.
+6. Assign every suitable still-unassigned issue to its best-fit available agent (an agent may hold a short queue): `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment explaining why. As a safety net, clear out all stragglers in one pass rather than dispatching one at a time.
 7. Leave a routine-run comment summarizing assigned issue ids, skipped issue ids, and gaps needing Product Owner/CEO attention.
 8. Mark the routine-run issue done when complete.
 

package/templates/modules/backlog/agents/ceo/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine Fallback
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.

package/templates/modules/backlog/agents/ceo/skills/backlog-health.fallback.md

@@ -9,6 +9,7 @@ On your heartbeat, after handling assignments:
 1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
 2. If fewer than 1 unassigned issue remains AND the Product Owner hasn't acted recently:
    - Create 1-2 high-priority issues from the roadmap to keep engineers unblocked
+   - For each top-level issue (no `parentId`), include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so it gets its own worktree; subissues set `parentId` and omit it. Never create a top-level issue without it (it would inherit your checked-out workspace and block parallel work).
    - Attach `labelIds` — fetch available labels via `GET /api/companies/{companyId}/labels`. If no labels exist yet, create the defaults (see `backlog-health` skill for the label table) before creating issues.
    - Comment on the issue tagging the Product Owner to take over backlog grooming
 3. If the Product Owner is active and the backlog has 1+ issues, skip this step.
@@ -18,3 +19,4 @@ On your heartbeat, after handling assignments:
 - This is a safety net, not your primary job. Let the PO own it.
 - Only create issues when engineers would otherwise have nothing to work on.
 - Keep it minimal — just enough to unblock, not a full grooming session.
+- **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. Otherwise PATCH `assigneeAgentId` to the reviewer before or at the same time as the status change.

package/templates/modules/backlog/agents/product-owner/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.

package/templates/modules/backlog/docs/backlog-process.md

@@ -9,10 +9,10 @@ Goal → Roadmap → Issues → Assignment → Execution → Done
 ```
 
 1. **Goal decomposition** — The backlog owner breaks the company goal into milestones, then milestones into actionable issues.
-2. **Issue creation** — New issues enter the backlog via `POST /api/companies/{companyId}/issues` with `title`, `description`, `priority`, `projectId`, `goalId`, and `labelIds`. Top-level backlog issues must always include the active roadmap `projectId`.
-3. **Pipeline health** — The backlog owner monitors unassigned issue count. When fewer than 3 remain, the next batch is generated from the roadmap.
-4. **Assignment** — Issues are left unassigned at creation. Assignment happens separately (auto-assign module or manual).
-5. **Execution** — Agents check out assigned issues, work them, and mark done.
+2. **Issue creation** — New issues enter the backlog via `POST /api/companies/{companyId}/issues` with `title`, `description`, `priority`, `projectId`, `goalId`, and `labelIds`. Top-level backlog issues must always include the active roadmap `projectId`. They must also set workspace isolation explicitly — see **Workspace Isolation** below.
+3. **Pipeline health** — The backlog owner monitors the ready assigned queue. When fewer than about 8 actionable ready issues remain across the active delivery roles, the next small batch is generated from the roadmap.
+4. **Assignment** — Issues are assigned at creation to the best-fit owner. Engineering-ready issues go directly to the Software Engineer (or matching delivery role) so assignment wakeups start work immediately. Leave an issue unassigned only when no suitable owner exists.
+5. **Execution** — Agents check out assigned issues, work them, and hand off deliberately for review or completion.
 
 ## Issue Quality
 
@@ -28,6 +28,39 @@ Every issue should be:
 
 Write acceptance criteria in the issue description. Engineers use these to validate their work before marking done. Keep them concrete and testable.
 
+## Workspace Isolation (required at creation)
+
+Every issue runs in a git execution workspace (worktree/branch). To let issues run in
+parallel without colliding in the same worktree, you must declare the workspace intent
+**when you create the issue** — otherwise the issue silently adopts the workspace of
+whatever issue you currently have checked out, which serializes work and corrupts branch
+state.
+
+- **Top-level issue** (independent work, no `parentId`): always send
+  `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` in the create body. This
+  gives the issue its own worktree and branch.
+- **Sub-issue** (part of a larger parent task): set `"parentId": "<parent-issue-id>"` and
+  do **not** send `executionWorkspaceSettings`. The sub-issue deliberately reuses the
+  parent's workspace (the parent cannot be completed/cleaned up while its sub-issues are
+  still open, so sharing is safe and intended).
+
+**Never** create a top-level issue without `executionWorkspaceSettings`. Doing so makes it
+inherit the creator's currently checked-out workspace and blocks parallel execution.
+
+Example top-level create body:
+
+```json
+{
+  "title": "Build campaign onboarding wizard",
+  "description": "...",
+  "priority": "high",
+  "projectId": "<roadmap-project-id>",
+  "goalId": "<goal-id>",
+  "labelIds": ["<label-id>"],
+  "executionWorkspaceSettings": { "mode": "isolated_workspace" }
+}
+```
+
 ## Sources of Issues
 
 Issues can enter the backlog from multiple sources:
@@ -50,13 +83,17 @@ Re-prioritize when milestones shift or new information arrives. Don't let low-pr
 
 ## Backlog Health Indicators
 
-- **Healthy**: 3+ unassigned issues in `todo`, covering the next logical chunk of work
-- **Thin**: 1-2 unassigned issues — generate more soon
-- **Empty**: 0 unassigned issues — engineers will idle. Generate immediately.
-- **Bloated**: 20+ unassigned issues — stop creating, focus on prioritization and cleanup
+- **Healthy**: about 8 ready assigned issues across active delivery roles, covering the next logical chunk of work
+- **Thin**: fewer than 4 ready assigned issues — generate and assign more soon
+- **Empty**: no ready assigned issues — engineers will idle. Generate and assign immediately.
+- **Bloated**: 20+ ready issues — stop creating, focus on prioritization and cleanup
 
 ## Coordination
 
 - The backlog owner coordinates with the CEO on strategic priorities when unclear.
 - If the goal is fully decomposed and all issues are done or in progress, report completion to the CEO rather than inventing new work.
 - When multiple agents create issues (e.g., from user-testing findings), the backlog owner reviews and re-prioritizes as needed.
+
+## Review Handoff
+
+When an issue is ready for review (moving to `in_review`), it must be assigned to the reviewer. If an executionPolicy with review stages is configured, Paperclip reassigns automatically. Otherwise, the person moving the issue must PATCH `assigneeAgentId` to the reviewer. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.

package/templates/modules/backlog/docs/backlog-template.md

@@ -36,9 +36,10 @@ Add more labels as the project evolves (e.g., `docs`, `design`, `security`). Pic
 
 _Summary of current backlog health. Update on each heartbeat cycle._
 
-- **Unassigned todo issues:** _(count)_
+- **Ready assigned issues:** _(count by owner)_
+- **Unassigned todo issues:** _(count; should normally be 0 except items without a suitable owner)_
 - **In-progress issues:** _(count)_
-- **Health:** _(healthy / thin / empty / bloated — see backlog-process.md)_
+- **Health:** _(healthy / thin / empty / bloated — see docs/backlog-process.md)_
 
 ## Decisions Log
 

package/templates/modules/backlog/module.meta.json

@@ -16,15 +16,15 @@
       "title": "Create roadmap and generate initial backlog",
       "assignTo": "capability:backlog-health",
       "priority": "high",
-      "description": "Review the company goal, create a ROADMAP.md with milestones, then generate an initial backlog of 15-20 actionable issues from it so the team has immediate, parallelizable work. Scope each issue to a single deliverable, set priorities, and link issues to the relevant goal and project. Don't wait for grooming cycles to fill the backlog — seed it now."
+      "description": "Review the company goal, create a ROADMAP.md with milestones, then generate an initial backlog of 15-20 actionable issues from it so the team has immediate, parallelizable work. Scope each issue to a single deliverable, set priorities, and link issues to the relevant goal and project. Assign each engineer-actionable issue to the best-fit agent (e.g., the Software Engineer) as you create it so work starts immediately — don't leave the seed backlog unassigned. Don't wait for grooming cycles to fill the backlog — seed it now."
     }
   ],
   "routines": [
     {
       "title": "Backlog grooming",
-      "description": "Routine-run checklist: inspect roadmap/backlog health, ensure at least 8 actionable ready issues exist, create scoped issues only when capacity is low, link artifacts/goals/projects, summarize changes on the routine issue, then exit.",
+      "description": "Routine-run checklist: inspect roadmap/backlog health, ensure at least 8 actionable ready issues exist, create scoped issues (around 3-6 per pass) and assign each to its best-fit agent when capacity is low, link artifacts/goals/projects, summarize changes on the routine issue, then exit.",
       "assignTo": "capability:backlog-health",
-      "schedule": "0 */4 * * *",
+      "schedule": "0 */2 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

package/templates/modules/backlog/skills/backlog-health.bar.md

@@ -3,7 +3,9 @@
 A good backlog health pass:
 
 - Every issue created is INVEST-shaped: has a clear title, written acceptance criteria in the description, a priority, a label, and is attached to the correct `projectId` and `goalId` — never a top-level issue with `projectId: null`.
-- The backlog maintains at least 3 unassigned, ready-to-work issues; if the queue drops below that threshold, new ones are created from the roadmap and the action is recorded in daily notes.
+- Every issue declares workspace isolation explicitly: top-level issues (no `parentId`) carry `"executionWorkspaceSettings": { "mode": "isolated_workspace" }`; subissues set `parentId` and omit it. A top-level issue created without it is not done — it would inherit the creator's checked-out workspace and block parallel execution.
+- The team keeps a healthy queue of ready, **assigned** work (toward the grooming target of ~8 actionable ready issues); when the assigned ready queue runs low, new issues are created **and assigned** from the roadmap so no agent goes idle between grooming cycles, and the action is recorded in daily notes. Issues are assigned at creation — do not stockpile a pool of unassigned issues.
+- Review handoff: when moving an issue to `in_review`, always reassign it to the reviewer. Without reassignment, `in_review` issues stall with the implementer still assigned.
 
 Not done:
 

package/templates/modules/backlog/skills/backlog-health.md

@@ -28,12 +28,13 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 1. Checkout the assigned backlog/routine issue before mutating the board.
 2. Read the current company goals, roadmap/project context, existing issue documents, and recent decision log entries.
 3. Query existing issues for the relevant project/goal and avoid duplicates.
-4. If the backlog is thin or unclear, create 3-5 small actionable issues via `POST /api/companies/{companyId}/issues`.
+4. If the backlog is thin or unclear, create around 3-6 small actionable issues via `POST /api/companies/{companyId}/issues`.
 5. Each issue must include: `title`, acceptance-oriented `description`, `priority`, `projectId`, `goalId` when known, and `labelIds`.
-6. Use `blockedByIssueIds` for real dependencies instead of free-text blockers.
-7. Leave issues unassigned unless the routine explicitly includes assignment. Assignment happens through the auto-assign routine or manager handoff.
-8. Record generated issue ids and rationale in the routine issue comment; use issue documents for long plans.
-9. Mark the routine-run issue done when complete.
+6. Set workspace isolation explicitly on every issue you create (see Rules): top-level issues send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }`; sub-issues set `parentId` and omit it.
+7. Use `blockedByIssueIds` for real dependencies instead of free-text blockers.
+8. Assign each issue to the best-fit available agent as you create it — engineer-actionable work with clear acceptance criteria goes to the Software Engineer (or the matching role). Direct push-assignment is the primary dispatch path; the assigned queue is the buffer, so do **not** stockpile a pool of unassigned ready work. Leave an issue unassigned only when no suitable owner exists — the low-frequency auto-assign safety net will catch those.
+9. Record generated issue ids and rationale in the routine issue comment; use issue documents for long plans.
+10. Mark the routine-run issue done when complete.
 
 ## Rules
 
@@ -41,6 +42,8 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 - Do not create top-level backlog issues with `projectId: null` when a project exists.
 - Keep issues small and actionable. Each should be completable, tested, and reviewed independently.
 - Split into subissues only when each child can be completed independently; avoid splitting tightly coupled implementation across sibling subissues.
+- **Set workspace isolation explicitly at creation.** Top-level issues (no `parentId`) must send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch. Sub-issues set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace. Never create a top-level issue without it — otherwise it inherits the workspace of whatever issue you currently have checked out and blocks parallel work.
 - Always attach at least one label to every issue you create.
 - If the goal is fully decomposed into issues, do not create more. Report status and next review trigger to the CEO/Product Owner.
 - Work products such as roadmap drafts or decomposition tables belong in issue documents/artifacts, not only comments.
+- **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. If there is no executionPolicy, PATCH the issue's `assigneeAgentId` to the reviewer before or at the same time as the status change. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.

package/templates/modules/competitive-intel/skills/competitive-tracking.md

@@ -16,7 +16,7 @@ You own competitive intelligence. This is a living analysis — profiles evolve
    - **Gaps and opportunities**: Where competitors are weak and we can win
    - **Threats**: Where competitors are strong and we need to defend
 3. Create follow-up issues for strategic decisions informed by competitive insights:
-   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 4. Record summary in your daily notes
 
 ## Rules

package/templates/modules/github-repo/README.md

@@ -10,8 +10,8 @@ Enables the Engineer to work in a GitHub repository.
 
 ## Variants
 
-- **direct-to-base-ref** (default): Engineer commits directly on the default branch. No branches, no PRs. Fast iteration for solo engineer setups.
-- When combined with `pr-review` module: switches to feature-branch workflow automatically.
+- **direct-to-base-ref** (default): Engineer works on a feature branch, then merges to the base branch and pushes. No PRs, no code review gate — the engineer merges their own work and hands off to the Product Owner for acceptance review via `in_review` status reassignment. Fast iteration for solo or small teams.
+- When combined with `pr-review` module: switches to feature-branch + PR workflow with executionPolicy review stages and a non-author merge gate.
 
 ## Best for
 
@@ -21,4 +21,4 @@ Enables the Engineer to work in a GitHub repository.
 
 ## Example
 
-A company building a web app with one engineer. The engineer picks up issues, implements them, commits to the default branch, and marks the issue done. CI runs on push.
+A company building a web app with one engineer. The engineer picks up issues, implements them on feature branches, merges to base, pushes, and reassigns to the Product Owner for acceptance review. CI runs on push.

package/templates/modules/github-repo/agents/engineer/skills/git-workflow.md

@@ -2,17 +2,76 @@
 
 You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md` in the project root.
 
-## Direct-to-Base-Ref Flow
+## PR Self-Merge Flow (no pr-review module)
 
-1. Resolve the base ref from project workspace metadata or the issue's `heartbeat-context`. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from the current shell branch and never rewrite the configured ref to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
-2. Pull/update latest from that base:
+Use this flow when the **pr-review module is not active**. You open a PR and merge it yourself — there is no external review gate, but all changes go through a PR so the branch history is preserved and branch protection is respected.
+
+1. Before the first push on a project, confirm the GitHub credential helper from `docs/git-workflow.md` -> *GitHub Push Authentication* is installed in the primary repository. If `GH_TOKEN` is not injected or the helper cache is empty, stop and escalate instead of attempting unauthenticated pushes.
+2. Resolve the base ref from project workspace metadata or the issue's `heartbeat-context`. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from the current shell branch and never rewrite the configured ref to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
+3. Pull/update latest from that base:
    - external: `git fetch origin`, then integrate from the configured base ref
    - local: update from the configured local branch
-3. Make your changes
-4. Run available checks (lint, typecheck, tests)
-5. Commit using Conventional Commits: `<type>: <description>`
-6. Push to the correct configured base branch
-7. If CI fails, fix immediately
+4. **Create a feature branch** from the base ref: `git checkout -b <branch-name> <base-ref>`. Never commit directly on the base branch. The branch name should reference the issue (e.g., `LEA-5-add-landing-hero`). If you are already on a correctly named feature branch, skip this step.
+5. Verify you are on the feature branch before making changes: `git branch --show-current` must print `<branch-name>`, not the base ref. If it prints the base ref name, you forgot step 4 — create the branch now.
+6. Make your changes
+7. Run available checks (lint, typecheck, tests)
+8. Commit using Conventional Commits: `<type>: <description>`
+9. Verify the current branch one more time, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
+10. Open a pull request against the base ref: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Write the PR body (summary, what changed, how to verify) to a temp file first — never inline `--body "..."`. Register the PR as a Paperclip work product (see *Register the PR as a Work Product* below). Verify the PR base matches the configured base ref before merging.
+11. Merge the PR yourself: `gh pr merge <PR-number> --merge`. After opening the PR, merge it yourself promptly — do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing.
+12. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local). Update the Paperclip work product to `"status": "merged"` via `PATCH /api/work-products/{workProductId}`.
+13. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
+14. If CI fails on the base branch after the merge, fix immediately.
+
+## Branch Protection Setup
+
+Configure branch protection once during initial repository setup (this is part of the "Prepare GitHub repository" foundation issue). Branch protection must require a PR before merging but must NOT require GitHub-native approving reviews — all agents share one GitHub account and cannot formally approve their own PRs (unless the project has distinct non-author GitHub reviewer credentials, in which case `required_approving_review_count` may be raised).
+
+```bash
+gh api repos/{owner}/{repo}/branches/{base}/protection \
+  --method PUT --input - <<'EOF'
+{
+  "required_status_checks": null,
+  "enforce_admins": true,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 0,
+    "dismiss_stale_reviews": false
+  },
+  "restrictions": null
+}
+EOF
+```
+
+Replace `{owner}`, `{repo}`, `{base}` with the actual values. `enforce_admins: true` so the shared admin account cannot bypass the PR requirement with a direct push — with `required_approving_review_count: 0` the admin can still open a PR and merge it with zero approvals, so the self-merge flow keeps working. `restrictions: null` means no push allowlist; the PR gate still applies (do not "fix" it with an empty array, which would block all pushes). If CI is configured (e.g. the ci-cd module is active), replace `"required_status_checks": null` with the CI context string instead of `null`. Escalate to CEO if `GH_TOKEN` does not have admin rights on the repository.
+
+## When PR Review IS Active
+
+If the pr-review module is active, do NOT use the PR Self-Merge Flow. Instead, use the PR Workflow skill (`skills/pr-workflow.md`):
+- **With a Code Reviewer on the team (PR-Gate mode):** Open a PR, set executionPolicy review stages, and let the Code Reviewer (non-author merge gate) land the branch. Never merge your own branch in this mode.
+- **Without a Code Reviewer (PR Self-Merge Flow):** Open a PR via `gh pr create`, but skip executionPolicy stages entirely. Other review roles (qa, product-owner, security-engineer) may leave advisory comments. Merge the PR yourself via `gh pr merge <N> --merge` once CI is green. See `skills/pr-workflow.md` step 12 for the full self-merge path.
+
+## Register the PR as a Work Product
+
+Whenever you open a pull request (via `gh pr create`), immediately register it as a Paperclip work product so it shows up on the issue and the board. Creating the PR on GitHub alone does **not** make it visible in Paperclip.
+
+```
+POST /api/issues/{issueId}/work-products
+Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+{
+  "type": "pull_request",
+  "provider": "github",
+  "externalId": "<PR number, e.g. 132>",
+  "url": "<full PR URL from `gh pr create`>",
+  "title": "<PR title>",
+  "status": "ready_for_review",
+  "isPrimary": true
+}
+```
+
+Notes:
+- `title` and `url` are required; `url` must be the full PR URL.
+- If the issue runs in an isolated execution workspace, also pass `"executionWorkspaceId"` from your `heartbeat-context` so the PR is linked to that worktree.
+- When the PR later merges or closes, update the work product (`PATCH /api/work-products/{workProductId}`) with `"status": "merged"` or `"closed"`.
 
 ## Rules
 
@@ -20,8 +79,12 @@ You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md
 - Keep commits focused — one concern per commit.
 - Never force push to the base branch.
 - Use the configured base ref. For external repos, branch and compare from the configured remote/ref and push/merge back to the matching remote branch.
+- Treat push authentication as repository setup, not as an issue blocker. If `git push` says credentials are missing or invalid, verify the helper and `GH_TOKEN` binding first.
 - If you encounter merge conflicts, resolve them carefully. When in doubt, escalate to the CEO.
 - Reference the issue ID in the commit body (e.g., `Closes YES-5`).
-- Never mark an issue as `done` unless at least one new commit was created for that issue's work and pushed.
+- Never mark an issue as `done` unless at least one new commit was created for that issue's work and has been pushed.
 - Before marking `done`, verify there is no uncommitted work (`git status --short` should be clean).
 - If no repository change is required, do not mark `done` silently: leave an issue comment explaining why no code change was needed and escalate to the CEO for decision.
+- You are always the merge owner when no code-reviewer is present. Open a PR and merge it yourself via `gh pr merge <N> --merge` promptly — do not leave branches dangling unmerged. Never do a direct `git merge` + push to the base branch; always go through a PR so the branch history is preserved and branch protection is respected (typos/comment-only/doc fixes with an issue reference may be committed directly to the base ref only when branch protection allows it — see `docs/git-workflow.md` → *Dev Cycle Rules*).
+- **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing. Verify with `git branch --show-current` before every push.
+- **Never push the base ref as if it were a feature branch.** Before `git push -u origin <branch-name>`, confirm that `git branch --show-current` matches `<branch-name>`. If it prints the base ref name instead, you are on the wrong branch — create or switch to the feature branch first.