@starlein/paperclip-plugin-company-wizard 0.4.5-a → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.5a",
+  "version": "0.4.6",
   "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/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 `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 `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/docs/backlog-process.md

@@ -10,9 +10,9 @@ 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.
+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
 
@@ -50,10 +50,10 @@ 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
 

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

@@ -36,7 +36,8 @@ 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)_
 

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

@@ -16,13 +16,13 @@
       "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 * * *",
       "priority": "medium",

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

@@ -3,7 +3,7 @@
 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.
+- 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.
 
 Not done:
 

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

@@ -28,10 +28,10 @@ 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.
+7. 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.
 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.
 

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

@@ -4,15 +4,29 @@ You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md
 
 ## Direct-to-Base-Ref Flow
 
-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** — i.e., there is no Code Reviewer role and no executionPolicy review stages. In this flow, you commit and merge directly; there is no external review gate.
+
+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. Make your changes
+5. Run available checks (lint, typecheck, tests)
+6. Commit using Conventional Commits: `<type>: <description>`
+7. Push your branch: `git push -u origin <branch-name>`
+8. Merge to base and push:
+   - `git checkout <base-ref>` (the same resolved base branch from step 2)
+   - `git merge <branch-name> --no-edit`
+   - Resolve any conflicts (favor your changes; if uncertain, escalate to the CEO)
+   - `git push origin <base-ref>`
+9. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local)
+10. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
+11. If CI fails on the base branch after the merge, fix immediately.
+
+## When PR Review IS Active
+
+If the pr-review module is active and you have a Code Reviewer role on the team, do NOT use the Direct-to-Base-Ref Flow. Instead, use the PR Workflow skill (`skills/pr-workflow.md`) — open a PR, set executionPolicy review stages, and let the merge gate land the branch. Never merge your own branch when a PR review workflow is in place.
 
 ## Rules
 
@@ -20,8 +34,10 @@ 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.
+- When working without a PR review flow, you are the merge owner. Merge your branch to base promptly after pushing — do not leave branches dangling unmerged.

package/templates/modules/github-repo/docs/git-workflow.md

@@ -33,8 +33,56 @@ directory inside the repository. This must never be committed.
 - Committing `.paperclip/` pollutes history and can nest isolated worktrees inside the
   repo, which causes confusing git state for every agent.
 
+## GitHub Push Authentication
+
+Paperclip injects the project secret `GH_TOKEN` into agent runs when the project env maps
+`GH_TOKEN` to the secret. Git does not use that variable automatically, and some sandboxed
+push subprocesses can drop environment variables exactly when Git asks its credential
+helper for credentials. Every GitHub-backed project must install a repository-local
+credential helper during foundation setup before the first push.
+
+Run this from the primary project workspace, never from inside an issue worktree:
+
+```bash
+git_common_dir="$(git rev-parse --git-common-dir)"
+helper="$git_common_dir/paperclip-gh-credential-helper.sh"
+cache="$git_common_dir/paperclip-gh-token-cache"
+
+cat > "$helper" <<'EOF'
+#!/bin/sh
+cache="$(dirname "$0")/paperclip-gh-token-cache"
+if [ -n "$GH_TOKEN" ]; then
+  ( umask 077; printf '%s' "$GH_TOKEN" > "$cache" ) 2>/dev/null
+fi
+if [ "$1" = "get" ]; then
+  token="$GH_TOKEN"
+  [ -z "$token" ] && [ -r "$cache" ] && token="$(cat "$cache" 2>/dev/null)"
+  [ -n "$token" ] && printf 'username=x-access-token\npassword=%s\n' "$token"
+fi
+exit 0
+EOF
+
+chmod 700 "$helper"
+[ -n "$GH_TOKEN" ] && ( umask 077; printf '%s' "$GH_TOKEN" > "$cache" )
+chmod 600 "$cache" 2>/dev/null || true
+git config --local credential.helper "$helper"
+```
+
+Rules:
+- Do not print, commit, or paste the token. The helper cache lives under Git's private
+  common directory, not in the worktree.
+- If `GH_TOKEN` is empty during setup, stop and ask the CEO/board to bind a writable
+  GitHub token as the project secret before continuing.
+- Re-run the setup after rotating the secret; the cache refreshes whenever `GH_TOKEN`
+  is present in a later agent run.
+- Verify the helper without exposing the token: `git config --local --get credential.helper`
+  should print the helper path, and `test -s "$(git rev-parse --git-common-dir)/paperclip-gh-token-cache"`
+  should succeed after a run where `GH_TOKEN` was injected.
+
 ## Direct-to-Base-Ref Workflow
 
+Use this workflow when the **pr-review module is not active** (no Code Reviewer role, no executionPolicy review stages). When PR review is active, use the PR workflow from `docs/pr-conventions.md` instead.
+
 1. Resolve the configured base ref from project workspace metadata or the issue's `heartbeat-context` before touching Git. Do not infer it from the current shell branch and do not rewrite it to `main`, `master`, or `origin/*`.
    - External repos: use the project/worktree `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as configured.
    - Fresh/local repos: use the configured local branch.
@@ -43,8 +91,17 @@ directory inside the repository. This must never be committed.
 3. Make changes
 4. Run tests/linting locally if available
 5. Commit with conventional commit message
-6. Push to the matching configured base branch
-7. Verify CI passes (if configured)
+6. Push your feature branch: `git push -u origin <branch-name>`
+7. Merge to base and push:
+   ```
+   git checkout <base-ref>
+   git merge <branch-name> --no-edit
+   git push origin <base-ref>
+   ```
+   Resolve any merge conflicts (favor your changes; if uncertain, escalate).
+8. Delete the feature branch: `git push origin --delete <branch-name>` and `git branch -d <branch-name>`
+9. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context`.
+10. Verify CI passes on the base branch (if configured). If CI fails, fix immediately.
 
 ## Resolving the default branch
 

package/templates/modules/github-repo/module.meta.json

@@ -9,7 +9,7 @@
       "priority": "critical",
       "bootstrapPhase": "foundation",
       "labels": ["chore"],
-      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize the local workspace with a README or bootstrap commit, add origin, push the default branch (`main` for a fresh repo), and record the repository URL. For an existing repository, verify the workspace has a reachable remote and a starter commit state, then determine the repository's default branch and confirm it is recorded as the project workspace `defaultRef`/`repoRef` so isolated worktrees branch from the correct base. The default branch is whatever `origin/HEAD` points at — name-agnostic (`main`, `master`, `trunk`, etc.); use it exactly as the remote advertises it (`git ls-remote --symref origin HEAD`). Only if the remote advertises no default HEAD, fall back to `main`, then `master`. Never assume `main` for an existing repo. Escalate to CEO if repo setup is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
+      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize the local workspace with a README or bootstrap commit, add origin, push the default branch (`main` for a fresh repo), and record the repository URL. For an existing repository, verify the workspace has a reachable remote and a starter commit state, then determine the repository's default branch and confirm it is recorded as the project workspace `defaultRef`/`repoRef` so isolated worktrees branch from the correct base. The default branch is whatever `origin/HEAD` points at — name-agnostic (`main`, `master`, `trunk`, etc.); use it exactly as the remote advertises it (`git ls-remote --symref origin HEAD`). Only if the remote advertises no default HEAD, fall back to `main`, then `master`. Never assume `main` for an existing repo. Install the Paperclip GitHub credential helper from `docs/git-workflow.md` before the first push so `git push` uses the injected `GH_TOKEN` project secret even when sandboxed subprocesses strip environment variables at credential-lookup time. Escalate to CEO if repo setup or `GH_TOKEN` is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
     }
   ]
 }

package/templates/roles/engineer/AGENTS.md

@@ -11,6 +11,7 @@ You implement coding tasks end-to-end: write and edit code, debug issues, add fo
 ## Working Rules
 
 - Work only on issues assigned to you or explicitly handed to you in comments.
+- If you have no assigned actionable work and there are unassigned `todo` issues that clearly match engineering, claim the highest-priority ready issue yourself, set it `in_progress`, and start in the same heartbeat. This is a fallback behind Product Owner push-assignment, not permission to reshuffle work owned by others.
 - 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 blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
 - Make sure you know the success condition for each task. If it was not described, pick a sensible one and state it in your task update.
 - Run the smallest verification that proves the change. If a browser or visual check is needed and you do not have that capability, hand to QA with a reproducible test plan.
@@ -19,6 +20,7 @@ You implement coding tasks end-to-end: write and edit code, debug issues, add fo
 
 ## Collaboration and Handoffs
 
+- If the PR-review module or an issue `executionPolicy` is active, follow that review/approval flow exactly. Otherwise, when implementation is ready for review, move the issue to `in_review`, assign it to the Product Owner in the same heartbeat, and leave a comment with the change summary, verification, branch/commit details, and any risks. Never leave finished work in `in_review` assigned to yourself.
 - UX-facing changes -> route to the UI/UX designer for visual quality and flow review.
 - Security-sensitive changes (auth, crypto, secrets, permissions, adapter/tool access) -> route to the Security Engineer before merge.
 - Browser validation or user-facing verification -> route to QA with exact steps and expected results.

package/templates/roles/engineer/HEARTBEAT.md

@@ -35,7 +35,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 - 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.
+- If work awaits review, move the issue to `in_review`. When no executionPolicy is active, reassign to the Product Owner for acceptance review — never leave finished work in `in_review` assigned to yourself. When an executionPolicy is active, follow its review/approval stages.
 
 ## 6. Exit
 

package/templates/roles/product-owner/AGENTS.md

@@ -9,6 +9,7 @@ You own product intent, backlog health, acceptance criteria, prioritization, and
 ## Working Rules
 
 - Work only on issues assigned to you or explicitly handed to you in comments.
+- If an issue is assigned to you in `in_review` and no formal executionPolicy participant is waiting, review it immediately against the acceptance criteria, branch/commit/PR evidence, and recorded verification. If it passes, comment with the acceptance decision and set it `done`; if it does not pass, set it back to `in_progress`, assign it to the Engineer, and list the exact required changes.
 - 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 blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
 - Keep issues small, acceptance-driven, project-scoped, and linked to goals when available.
 - Use first-class blockers (`blockedByIssueIds`) for dependencies instead of free-text "blocked by" notes.
@@ -18,7 +19,7 @@ You own product intent, backlog health, acceptance criteria, prioritization, and
 ## Collaboration and Handoffs
 
 - Product ambiguity -> clarify options and recommend one.
-- Engineering implementation -> assign the Engineer with acceptance criteria and project/goal context.
+- Engineering implementation -> assign the Engineer directly with acceptance criteria and project/goal context. Do not leave ready engineering work unassigned for a later sweep.
 - UX-visible scope -> involve the UI/UX designer.
 - Security-sensitive scope -> involve the Security Engineer.
 - Browser/user-facing verification -> involve QA.

package/templates/roles/product-owner/HEARTBEAT.md

@@ -35,7 +35,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 - 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.
+- If an issue is assigned to you in `in_review` and no formal executionPolicy participant is waiting, review it immediately against the acceptance criteria. If it passes, comment with the acceptance decision and set it `done`; if it does not pass, set it back to `in_progress`, assign it to the Engineer, and list the exact required changes.
 
 ## 6. Exit