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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.3.24",
+  "version": "0.4.1",
   "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/ai-wizard/config-format.md

@@ -7,7 +7,7 @@ Respond with ONLY a JSON object (no markdown fences):
     { "title": "Additional business/product/technical goal if needed", "description": "Concrete success criteria. Do not omit user-specific goals just because a preset/module also has template goals." }
   ],
   "projects": [
-    { "name": "Project name", "description": "Concrete project description — what is being built and key technical details.", "goals": ["Goal titles linked to this project"], "workspace": { "sourceType": "local_path", "defaultRef": "main", "setupCommand": "git init -b main", "isPrimary": true }, "executionWorkspacePolicy": { "defaultMode": "isolated_workspace", "workspaceStrategy": { "type": "git_worktree", "baseRef": "main" } } }
+    { "name": "Project name", "description": "Concrete project description — what is being built and key technical details.", "goals": ["Goal titles linked to this project"], "workspace": { "sourceType": "local_path", "defaultRef": "main", "setupCommand": "git init -b main", "isPrimary": true } }
   ],
   "preset": "preset-name",
   "modules": ["all-modules-to-activate-including-preset-ones"],
@@ -17,10 +17,10 @@ Respond with ONLY a JSON object (no markdown fences):
 
 Rules:
 - modules should list ALL modules to activate (including preset ones).
-- goals should list the user's concrete objectives. Preset/module template goals are added later by the wizard; do not replace the user's goal with a generic preset goal such as "Build a REST API" unless that is truly the whole objective.
+- goals should list the user's concrete objectives. The first goal must be outcome-first/product-first: title the primary deliverable or operating outcome, not a supporting constraint. Preserve constraints in the description under "Constraints / quality bars" unless the constraint is explicitly the main project. When the brief lists secondary facts as sub-goals, keep their weight lower unless they are true independent workstreams. Preset/module template goals are added later by the wizard; do not replace the user's goal with a generic preset goal unless that is truly the whole objective.
 - projects should link to the relevant goal titles in `goals`. Include enough project detail for agents to start work. The primary project MUST say whether Paperclip should create a fresh local Git repository or use an external repo:
-  - Fresh/new repo: use `workspace.sourceType: "local_path"`, `workspace.defaultRef: "main"`, `workspace.setupCommand: "git init -b main"`, and `workspace.isPrimary: true`.
-  - Existing external repo (GitHub/GitLab/etc.): use `workspace.sourceType: "git_repo"`, include `repoUrl`, `repoRef`/`defaultRef` when known (default `origin/main`), and prefer isolated git worktrees via `executionWorkspacePolicy`.
+  - Fresh/new repo: use `workspace.sourceType: "local_path"`, `workspace.defaultRef: "main"` unless another initial branch was requested, `workspace.setupCommand: "git init -b <defaultRef>"`, and `workspace.isPrimary: true`. Do not include `executionWorkspacePolicy`.
+  - Existing external repo (GitHub/GitLab/etc.): use `workspace.sourceType: "git_repo"`, include `repoUrl`, and include `repoRef`/`defaultRef` exactly when the user or repository context provides one. Do not force a branch name or remote prefix. Do not include `executionWorkspacePolicy`; isolated worktrees are applied later only when Paperclip's experimental isolated-workspaces setting is enabled.
   - Do not put credentials or tokens in repository URLs or project text.
 - roles should list ALL non-base roles the company needs (including preset ones). Engineer is NOT a base role — include it if the project involves code.
 - Be pragmatic — don't over-engineer. Match the config to the actual needs described.

package/templates/ai-wizard/interview-system.md

@@ -48,9 +48,9 @@ Don't ask about things already clear from the initial description. Skip to what'
 The user's interview answers are the primary source of context for the company. When generating the configuration:
 
 - **`companyDescription`**: Write a comprehensive 2-4 paragraph description that captures EVERYTHING learned during the interview — what the company does, what it's building, who it's for, key technical decisions, constraints, priorities, and any special context. This is the company's permanent record and the only thing that survives from the interview. Be thorough. Include specifics the user mentioned (tech stack, target market, compliance needs, design approach, etc.). Do NOT summarize into a single vague sentence.
-- **`goal`**: A clear, actionable goal title (what the team should accomplish first).
-- **`goalDescription`**: A detailed paragraph explaining the goal — scope, success criteria, constraints. Reference specifics from the interview.
-- **`project`** and **`projectDescription`**: Name the main project and describe it concretely. The project must explicitly state repository setup. If the user chose an external repo, use `workspace.sourceType: "git_repo"` with `repoUrl`, `repoRef`/`defaultRef`, and isolated git worktrees. If no external repo was provided, use a fresh local Git repository with `workspace.sourceType: "local_path"`, `workspace.defaultRef: "main"`, `workspace.setupCommand: "git init -b main"`, and `workspace.isPrimary: true`.
+- **`goal`**: A clear, actionable, outcome-first goal title (what the team should accomplish first). Lead with the primary deliverable or operating outcome, not a supporting constraint.
+- **`goalDescription`**: A detailed paragraph explaining the goal — scope, success criteria, constraints. Reference specifics from the interview. Put compliance/security/accessibility/performance constraints under "Constraints / quality bars" unless the user explicitly made one of them the primary project. If the brief mixes a main outcome with side facts, make the main outcome the top-level goal and keep side facts as acceptance criteria, risks, or true independent sub-goals.
+- **`project`** and **`projectDescription`**: Name the main project and describe it concretely. The project must explicitly state repository setup. If the user chose an external repo, use `workspace.sourceType: "git_repo"` with `repoUrl`, plus `repoRef`/`defaultRef` exactly when the user or repository context provides one; do not force a branch name or remote prefix. If no external repo was provided, use a fresh local Git repository with `workspace.sourceType: "local_path"`, `workspace.defaultRef: "main"` unless another initial branch was requested, `workspace.setupCommand: "git init -b <defaultRef>"`, and `workspace.isPrimary: true`. Do not include `executionWorkspacePolicy`; the assembler applies isolated worktrees only when Paperclip's experimental isolated-workspaces setting is enabled and a usable project base ref exists.
 
 RECOMMENDATION (plain text, before the JSON):
 - One paragraph explaining your reasoning: why this preset, why these modules, why these roles.

package/templates/ai-wizard/single-shot-system.md

@@ -33,11 +33,11 @@ Given a natural language description of what the user wants to build, you select
 4. List ALL non-base roles the company needs. This includes roles from the preset. If the project involves software, include `engineer`.
 5. Suggest a company name (PascalCase-friendly, short, memorable) if not obvious from the description.
 6. Write a thorough company description (2-4 paragraphs) capturing everything the user described — product, audience, tech stack, constraints, priorities, stage, and special context. This is the company's permanent record.
-7. Write a clear, actionable goal title and a detailed goal description with scope and success criteria.
+7. Write a clear, actionable, outcome-first goal title and a detailed goal description with scope and success criteria. The title/opening must name the primary deliverable or operating outcome, not a supporting constraint. Keep compliance/security/accessibility/performance constraints in the description under "Constraints / quality bars" unless the user explicitly made that constraint the main project. If the brief mixes a main outcome with side facts, make the main outcome the top-level goal and keep side facts as acceptance criteria, risks, or true independent sub-goals.
 8. Name and describe the main project concretely.
 9. Always decide the repository setup for the primary project:
-   - If the user gives an existing GitHub/GitLab/remote Git repo, set `workspace.sourceType: "git_repo"`, include `repoUrl`, set `repoRef`/`defaultRef` when known (default to `origin/main`), and use `executionWorkspacePolicy.defaultMode: "isolated_workspace"` with a `git_worktree` strategy.
-   - If no external repository is given, assume Paperclip should create a fresh local Git repository. Set `workspace.sourceType: "local_path"`, `workspace.defaultRef: "main"`, `workspace.setupCommand: "git init -b main"`, and `workspace.isPrimary: true`.
+   - If the user gives an existing GitHub/GitLab/remote Git repo, set `workspace.sourceType: "git_repo"`, include `repoUrl`, and set `repoRef`/`defaultRef` exactly when the user or repository context provides one. Do not force a branch name or remote prefix; Paperclip's project/worktree settings decide the worktree base ref.
+   - If no external repository is given, assume Paperclip should create a fresh local Git repository. Set `workspace.sourceType: "local_path"`, `workspace.defaultRef: "main"` unless the user requested another initial branch, `workspace.setupCommand: "git init -b <defaultRef>"`, and `workspace.isPrimary: true`. Do not include `executionWorkspacePolicy`; the assembler applies isolated worktrees only when Paperclip's experimental isolated-workspaces setting is enabled and a usable project base ref exists.
    - Never include credentials or tokens in repository URLs or project text.
 
 First write one paragraph explaining your reasoning: why this preset, why these modules, why these roles.

package/templates/bootstrap-instructions.md

@@ -16,7 +16,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 **Creation order** (respects dependencies):
 
 1. **Goals** — create with `POST /api/companies/{companyId}/goals` using `{ title, description, level, parentId? }`. Top-level first, then sub-goals: sub-goals have `parentId: → "Parent Title"`, so create the parent first and use its ID. Valid `level`: `company`, `team`, `agent`, `task`. Valid `status` (optional, defaults to `planned`): `planned`, `active`, `achieved`, `cancelled`.
-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 `workspace: { sourceType: "git_repo", repoUrl: "...", repoRef: "origin/main", defaultRef: "origin/main", isPrimary: true }` and may include `executionWorkspacePolicy` for isolated worktrees. Never inline credentials in repo URLs.
+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.
@@ -27,11 +27,11 @@ 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 use isolated checkouts/workspaces unless explicit instructions request shared workspace use.
+- 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.
 
 **Review workflow guardrail:**
 
-- Required PR reviews are tracked as explicit assigned child issues, not @-mentions. When an engineer opens a PR, set the implementation issue to `in_review` and create review child issues assigned to Code Reviewer and Product Owner, plus Security/QA/UI/DevOps child issues when that domain is materially affected. Reviewers close only their own child issue; the engineer owns merge and parent closure. Follow `docs/pr-conventions.md` when the PR review module is active.
+- Required PR reviews use the issue's `executionPolicy` review/approval stages, not @-mentions and not separate child review issues. When an engineer opens a PR, set the implementation issue to `in_review` with the resolved execution policy: QA review when present, Security review only for security-relevant changes, Product Owner approval for scope/intent, and a final Engineer merge gate after verification is recorded. Each active participant records their decision through the normal issue update route (`approved` by PATCHing toward `done`, `changes_requested` by PATCHing back to `in_progress`), which is the issue-level reviewed/approved audit trail (`reviewed_by` / `approved_by` metadata where Paperclip exposes it). The Engineer merge gate must verify the PR base against the project/worktree base ref shown in `heartbeat-context`, merge before approving, close/archive any isolated worktree when one exists and close-readiness allows it, and only then record final approval. Follow `docs/pr-conventions.md` when the PR review module is active.
 
 **Secrets guardrail:**
 

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

@@ -14,7 +14,7 @@ You own the visual design system. Establish the foundational patterns that ensur
    - **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).
-4. @-mention the Engineer when the system is ready for implementation
+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/auto-assign/agents/ceo/heartbeat-section.md

@@ -1,9 +1,3 @@
-## Assignment Check (Fallback)
+## Auto-Assign Routine Fallback
 
-Only if the Product Owner is absent or stalled:
-
-1. Query idle agents: `GET /api/companies/{companyId}/agents`, then filter client-side for those where `status == "idle"`
-2. If agents are idle with unassigned issues AND PO 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 PO is active, skip this step.
+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/product-owner/heartbeat-section.md

@@ -1,10 +1,3 @@
-## Assignment Check
+## Auto-Assign Routine
 
-After handling your own assignments:
-
-1. Query idle agents: `GET /api/companies/{companyId}/agents`, then filter client-side for those where `status == "idle"`
-2. Query unassigned todo issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
-3. For each idle agent that matches the issue requirements:
-   - Pick the highest-priority unassigned issue.
-   - Assign it: `PATCH /api/issues/{id}` with `assigneeAgentId`.
-4. Record assignments in daily notes.
+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

@@ -17,7 +17,7 @@
   "routines": [
     {
       "title": "Auto-assign unassigned issues",
-      "description": "Find unassigned todo issues and assign to the best available agent based on role and workload.",
+      "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.",
       "assignTo": "capability:auto-assign",
       "schedule": "0 */2 * * *",
       "priority": "medium",

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

@@ -1,23 +1,26 @@
 # Skill: Auto-Assign
 
-You own issue assignment. Match issues to the right agents based on skills and availability.
+You own issue assignment when you are explicitly assigned an auto-assignment routine run. This is not an every-heartbeat background scan.
 
-## Assignment Check
+## When To Use This Skill
+
+Use this only when the current assigned issue/routine is titled like "Auto-assign unassigned issues" or explicitly asks you to rebalance assignments. Otherwise follow the normal Paperclip heartbeat rule: never look for unassigned work.
 
-Run this on every heartbeat, after handling your own assignments.
+## Assignment Check
 
-1. Query idle agents: `GET /api/companies/{companyId}/agents`, then filter client-side for those where `status == "idle"`
-2. Query unassigned todo issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
-3. For each idle agent that matches the issue requirements:
-   - Pick the highest-priority unassigned issue
-   - Assign it: `PATCH /api/issues/{id}` with `assigneeAgentId`
-   - The agent will wake on the assignment trigger
-4. Record assignments in your daily notes.
+1. Confirm this is the active routine-run issue and checkout it before mutating the board.
+2. Query available agents: `GET /api/companies/{companyId}/agents` and consider only active agents that are idle/available and within budget.
+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.
+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.
 
 ## Rules
 
-- Match issues to agents by role/capabilities. Don't assign code tasks to non-engineering agents.
-- Assign one issue at a time per agent. Don't overload.
-- If no suitable match exists, leave the issue unassigned and note it.
-- Respect agent budget. Don't assign to agents near their budget limit.
-- Prioritize unblocking over optimization — a good-enough assignment now beats a perfect one later.
+- Do not run this from normal heartbeats.
+- Do not self-assign random unassigned work.
+- Do not assign code tasks to non-engineering agents or security-sensitive work without security coverage.
+- Respect budgets, pause/cancel states, approval gates, `blockedByIssueIds`, and executionPolicy.
+- If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.

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

@@ -1,10 +1,3 @@
-## Backlog Health Check (Fallback)
+## Backlog Health Routine Fallback
 
-Only if the Product Owner is absent or stalled:
-
-1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
-2. If fewer than 1 unassigned issue AND PO hasn't acted recently:
-   - Create 1-2 high-priority issues from the roadmap to keep engineers unblocked.
-   - Attach `labelIds` — fetch via `GET /api/companies/{companyId}/labels`. If none exist, create defaults first (see `backlog-health` skill).
-   - Tag the PO to take over backlog grooming.
-3. If the PO is active and backlog has 1+ issues, skip this step.
+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.

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

@@ -1,15 +1,3 @@
-## Backlog Health Check
+## Backlog Health Routine
 
-After handling your own assignments:
-
-1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
-2. If fewer than 3 unassigned issues remain:
-   - Review the company goal and current progress.
-   - Identify the next logical chunk of work from the roadmap.
-   - Create 3-5 new issues via `POST /api/companies/{companyId}/issues`, making sure each payload includes the correct `projectId`.
-   - Each issue needs: `title`, `description`, `priority`, `projectId`, `goalId`, `labelIds`.
-   - Use the active roadmap project's `projectId`. Do not leave top-level backlog issues projectless.
-   - Fetch labels once per session: `GET /api/companies/{companyId}/labels`. If none exist, create them first (see `backlog-health` skill).
-   - Write clear acceptance criteria. Leave issues unassigned.
-   - Only create subissues for independently deliverable slices. Do not split tightly coupled implementation across sibling subissues.
-3. Record what you generated in daily notes.
+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.

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

@@ -22,7 +22,7 @@
   "routines": [
     {
       "title": "Backlog grooming",
-      "description": "Ensure the backlog keeps at least 8 actionable unassigned issues ready. If running low, generate new issues from the roadmap so agents never idle waiting for work.",
+      "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.",
       "assignTo": "capability:backlog-health",
       "schedule": "0 */4 * * *",
       "priority": "medium",

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

@@ -1,6 +1,10 @@
 # Skill: Backlog Health
 
-You own the product backlog pipeline.
+You own the product backlog pipeline when you are explicitly assigned a backlog-grooming routine run or backlog-planning issue. This is not an every-heartbeat background scan.
+
+## When To Use This Skill
+
+Use this only when the current assigned issue/routine is titled like "Backlog grooming", "Backlog health", "Create roadmap", or explicitly asks you to decompose product work. Otherwise follow your normal assigned work.
 
 ## Label Setup
 
@@ -21,27 +25,22 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 
 ## Backlog Health Check
 
-Run this on every heartbeat, after handling your own assignments.
-
-1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
-2. If fewer than 3 unassigned issues remain:
-   - Review the company goal and current progress
-   - Identify the next logical chunk of work from the roadmap
-   - Create 3-5 new issues via `POST /api/companies/{companyId}/issues`, making sure each payload includes the correct `projectId`
-   - Each issue must have: `title`, `description`, `priority`, `projectId`, `goalId`, `labelIds`
-   - Use the current roadmap project's `projectId`; never create top-level backlog issues with `projectId: null`
-   - Fetch label IDs once per session: `GET /api/companies/{companyId}/labels`
-   - Write clear acceptance criteria in the description
-   - Leave issues unassigned — assignment happens separately
-3. Record what you generated in your daily notes.
+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`.
+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.
 
 ## Rules
 
-- Don't create duplicate issues. Check existing issues before creating new ones.
-- Keep issues small and actionable. Each should be completable in a single agent session.
-- Split into subissues only when each child can be completed, tested, and merged independently in its own isolated workspace.
-- Do not split tightly coupled implementation work across sibling subissues (same core code path/file cluster changed together). Keep coupled work in one issue, or sequence it explicitly so later work starts only after the prerequisite issue is done.
-- Set priority based on roadmap order and dependencies.
+- Do not run this from normal heartbeats.
+- 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.
 - Always attach at least one label to every issue you create.
-- If the goal is fully decomposed into issues, don't create more. Report to the CEO instead.
-- Coordinate with the CEO on strategic priorities when unclear.
+- 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.

package/templates/modules/codebase-onboarding/skills/codebase-audit.md

@@ -1,6 +1,10 @@
 # Skill: Codebase Audit
 
-You are responsible for understanding the existing codebase and maintaining its health over time. This skill has two modes: initial audit (first run) and ongoing health checks (subsequent heartbeats).
+You are responsible for understanding the existing codebase and maintaining its health over time. This skill has two modes: initial audit and assigned follow-up health checks.
+
+## When To Use This Skill
+
+Use this when assigned a codebase-audit issue, codebase-health routine, or explicit cleanup/planning task. Do not refactor opportunistically during unrelated heartbeats.
 
 ## Initial Audit
 
@@ -8,38 +12,33 @@ Run this when `docs/CODEBASE-AUDIT.md` does not yet exist.
 
 1. Map the project structure — identify key directories, entry points, and architectural layers.
 2. Read configuration files (package.json, tsconfig, Dockerfile, CI configs) to understand the tech stack and build pipeline.
-3. Identify the dependency graph — which modules depend on which, where are the coupling hotspots.
-4. Assess test coverage — find untested code paths, missing test files, or weak assertions.
-5. Identify tech debt — dead code, unused exports, overly complex functions, inconsistent patterns, duplicated logic.
-6. Check for code quality issues — long files, deep nesting, functions with too many parameters, missing error handling at boundaries.
-7. Document everything in `docs/CODEBASE-AUDIT.md`:
-   - Architecture overview (layers, key components, data flow)
-   - Tech stack summary
-   - Tech debt inventory (ranked by severity: critical, major, minor)
-   - Test coverage assessment
-   - Recommended cleanup priorities
-8. Create follow-up issues for the top cleanup opportunities (one issue per fix, small and actionable).
-
-## Ongoing Health Checks
-
-Run this on every heartbeat when `docs/CODEBASE-AUDIT.md` already exists.
-
-1. Check recent commits for newly introduced complexity or tech debt.
-2. Look for refactoring opportunities in code you or other agents have touched.
-3. When fewer than 3 open cleanup issues remain, identify the next batch from the audit.
-4. Execute small cleanup tasks directly when the fix is obvious and low-risk:
-   - Remove dead code and unused imports
-   - Fix inconsistent naming or formatting
-   - Simplify overly complex conditionals
-   - Extract duplicated logic into shared utilities
+3. Identify the dependency graph — modules, coupling hotspots, and risky boundaries.
+4. Assess test coverage — untested paths, missing tests, weak assertions.
+5. Identify tech debt — dead code, unused exports, complex functions, inconsistent patterns, duplicated logic.
+6. Check for code quality issues — long files, deep nesting, too many parameters, missing boundary error handling.
+7. Document findings in `docs/CODEBASE-AUDIT.md` or an issue document/work product:
+   - architecture overview
+   - tech stack summary
+   - tech debt inventory ranked by severity
+   - test coverage assessment
+   - recommended cleanup priorities
+8. Create follow-up issues for top cleanup opportunities; keep each issue small, scoped, project-linked, and acceptance-driven.
+
+## Assigned Health Checks
+
+When assigned an audit refresh/health-check issue:
+
+1. Read the existing audit document and recent relevant changes.
+2. Look for newly introduced complexity or tech debt in touched areas.
+3. Update the audit only when architecture or debt landscape changed materially.
+4. Execute small cleanup tasks only when the issue explicitly asks for implementation and the fix is low-risk.
 5. For larger refactors, create issues with clear scope and rationale instead of acting immediately.
-6. Update `docs/CODEBASE-AUDIT.md` when the architecture or tech debt landscape changes significantly.
+6. Record verification and attach the updated audit as a work product/document when user-inspectable.
 
 ## Rules
 
 - Read before you write. Understand the intent of existing code before changing it.
-- Small, focused changes. Each cleanup PR should do one thing. Never combine unrelated fixes.
-- Don't refactor code that is actively being worked on by another agent — check issue assignments first.
+- Small, focused changes. Never combine unrelated cleanups.
+- Do not refactor code actively owned by another agent; inspect assignments and execution state first.
 - Preserve behavior. Cleanup must not change functionality. Run tests after every change.
-- Prioritize by impact — fix things that slow down the team or cause bugs, not cosmetic issues.
-- If `docs/CODEBASE-AUDIT.md` exists, review it before starting. Don't duplicate findings.
+- Prioritize by impact — fix things that slow the team or cause bugs, not cosmetic churn.

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

@@ -4,18 +4,22 @@ You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md
 
 ## Direct-to-Main Flow
 
-1. Pull latest: `git pull origin main`
-2. Make your changes
-3. Run available checks (lint, typecheck, tests)
-4. Commit using Conventional Commits: `<type>: <description>`
-5. Push to main: `git push origin main`
-6. If CI fails, fix immediately
+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/*`.
+2. 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
 
 ## Rules
 
 - Always pull before starting work to avoid conflicts.
 - Keep commits focused — one concern per commit.
-- Never force push to main.
+- 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.
 - 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.

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

@@ -35,12 +35,15 @@ directory inside the repository. This must never be committed.
 
 ## Direct-to-Main Workflow
 
-1. Pull latest from main
-2. Make changes
-3. Run tests/linting locally if available
-4. Commit with conventional commit message
-5. Push to main
-6. Verify CI passes (if configured)
+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.
+2. Pull/fetch latest from that base before editing.
+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)
 
 ## What Requires a Commit
 
@@ -55,6 +58,7 @@ directory inside the repository. This must never be committed.
 
 - Never mark an issue as `done` unless at least one new commit exists for that issue's work and has been pushed.
 - Before marking `done`, ensure the working tree is clean (`git status --short` shows no pending changes).
+- If Paperclip created an isolated execution workspace for this issue, close/archive it after the commit/PR has landed and before marking `done`. If cleanup is blocked or fails, leave the issue open with the exact cleanup blocker. If the issue is in the shared project workspace, do not invent isolated-worktree cleanup.
 - If no repository change is required, do not silently close as `done`: add an issue comment explaining why no code change was needed and escalate to the CEO for explicit decision.
 
 ## CI

package/templates/modules/hiring-review/skills/hiring-review.md

@@ -1,24 +1,48 @@
 # Skill: Hiring Review
 
-You own team composition analysis. Evaluate whether the current team can deliver on the company goal, and propose hires when gaps exist.
+You own team composition analysis and governed hiring proposals. Use the current Paperclip `paperclip-create-agent` workflow; never create agents directly from this skill.
+
+## When To Use This Skill
+
+Use this only when assigned a hiring-plan, capacity review, team-design, or board-request issue. Do not scan for hiring opportunities on every heartbeat.
 
 ## Hiring Review Process
 
-1. Query current agents: `GET /api/companies/{companyId}/agents`
-2. Review the company goal and project scope
-3. For each identified gap:
-   - Define the role (use Paperclip role enum: engineer, pm, qa, designer, researcher, devops, general)
-   - Write a justification: what capability is missing and why it matters
-   - Suggest adapter configuration (model, effort level)
-   - Create a board approval request via `POST /api/companies/{companyId}/approvals` with:
-     - `type: "hire"`
-     - `title`: role name and purpose
-     - `description`: justification and config suggestion
-4. Document the team assessment in your daily notes
+1. Read the assigned issue and its linked documents, especially `hiring-plan` and `decision-log` if present.
+2. Query current agents: `GET /api/companies/{companyId}/agents`.
+3. Compare current roles/capabilities to the company goal, active roadmap, queued work, and stalled/blocked issues.
+4. For each potential gap, first ask whether an existing agent can own it with a skill/process update. Do not propose duplicate hires.
+5. If a new agent is justified, draft the hire using the `paperclip-create-agent` flow:
+   - Choose an exact template when available, adjacent template when close, otherwise generic.
+   - Build an `instructionsBundle` with `AGENTS.md` as entry file plus any supporting instruction files.
+   - Include `desiredSkills`, role/title, capabilities, metadata, adapterType/adapterConfig, permissions, and runtimeConfig.
+   - Keep `runtimeConfig.heartbeat.enabled` false by default unless the board explicitly wants an always-on manager.
+   - Link the originating issue with `sourceIssueId` or `sourceIssueIds`.
+6. Review the draft against the draft-review checklist before submitting:
+   - clear mission and reporting line
+   - concrete wake/heartbeat behavior
+   - task-management and work-product rules
+   - cross-agent escalation paths
+   - security/secrets constraints
+   - adapter/tool assumptions explicitly stated
+7. Submit through the governed endpoint: `POST /api/companies/{companyId}/agent-hires`.
+8. If the response includes an approval, comment on the source issue with the approval id and wait for board approval. Do not auto-approve from this skill.
+9. Record the decision and rationale in the decision log when one exists.
+
+## Output Format
+
+Post a concise issue comment:
+
+- `Assessment:` current coverage and gap.
+- `Recommendation:` hire / no-hire / update existing agent.
+- `Draft:` role, desiredSkills, sourceIssueId, template basis, adapter/runtime assumptions.
+- `Checklist:` pass/fail notes from the draft-review checklist.
+- `Next action:` who must approve or what work proceeds next.
 
 ## Rules
 
-- Don't propose hires for capabilities already covered by existing roles.
-- Consider whether an existing agent could take on additional responsibilities before hiring.
-- Prioritize roles that unblock the most work.
-- Each hire proposal must go through board approval — never create agents directly.
+- Each hire proposal must go through `/agent-hires` and board approval when the company requires it.
+- Do not use the legacy approvals endpoint or legacy hire approval payload shape.
+- Do not propose hires for capabilities already covered by existing roles unless load/capacity evidence justifies it.
+- Prefer small, specific roles over vague generalists when the gap is durable and recurring.
+- Work products such as candidate drafts, comparison matrices, or long hiring plans belong in issue documents/artifacts, not only comments.

package/templates/modules/market-analysis/agents/ux-researcher/skills/market-analysis.md

@@ -13,7 +13,7 @@ You own market research with a focus on user needs and behavior. This is your co
    - **Risks**: Adoption barriers, user switching costs, behavioral resistance
 3. Create follow-up issues for deeper research if needed:
    - `POST /api/companies/{companyId}/issues` for user interview plans, usability benchmarks. Include the active `projectId` (and `goalId` / `parentId` when applicable).
-4. Share findings with the team — @-mention Product Owner and CEO on key insights
+4. Share findings by updating the assigned issue/document and assigning concrete follow-up actions to the Product Owner and CEO when needed; do not rely on generic @-mentions.
 
 ## Rules
 

package/templates/modules/pr-review/README.md

@@ -4,8 +4,8 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 
 ## What it adds
 
-- **Core roles**: Code Reviewer, Product Owner (required reviewers)
-- **Extended roles** *(when present)*: UI Designer (design review), UX Researcher (UX review), QA (quality review), DevOps (infra review)
+- **Core roles**: Product Owner (approval) and Engineer (final merge gate)
+- **Extended roles** *(when present)*: QA (substantive review), Security Engineer (security-relevant review), Code Reviewer/UI/UX/DevOps advisory or domain review when explicitly configured
 - **Shared docs**: `docs/pr-conventions.md` — PR format, review workflow, merge rules
 - **Engineer skill**: Feature-branch + PR workflow (overrides direct-to-main from `github-repo`)
 - **Reviewer skills**: Review checklists for each reviewer role
@@ -16,20 +16,20 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 
 ## How it works
 
-1. Engineer creates a feature branch (`<prefix>-<N>/<short-description>`)
-2. Engineer opens a PR with Conventional Commits title and issue reference
-3. Engineer sets the originating issue's `executionPolicy`: a `review` stage for the Code Reviewer, optional `review` stages for relevant domain reviewers, and a final `approval` stage for the Product Owner (roles resolved to agentIds); the PR link is added as an issue comment
-4. Code Reviewer reviews for correctness, security, style, simplicity
-5. Product Owner reviews for intent alignment, scope discipline, acceptance criteria
-6. UI Designer reviews for visual consistency, brand compliance *(when present)*
-7. UX Researcher reviews for usability and user flow integrity *(when present)*
-8. QA reviews for test coverage, edge cases, regression risk *(when present)*
-9. DevOps reviews for infrastructure impact, security, performance *(when present)*
-10. Engineer merges when all stages are approved (no `changes_requested` outstanding)
+1. Engineer resolves the project/worktree base ref first from `heartbeat-context` / project workspace metadata and uses it exactly as configured
+2. Engineer creates a feature branch (`<prefix>-<N>/<short-description>`) from that base
+3. Engineer opens a PR with Conventional Commits title, issue reference, and the matching base branch
+4. Engineer sets the originating issue's `executionPolicy`: review stages for QA/domain reviewers as needed, an approval stage for the Product Owner, and a final Engineer merge-gate approval stage (roles resolved to agentIds); the PR link is added as an issue comment
+5. QA reviews with executed evidence when present
+6. Security Engineer reviews security-relevant changes when present
+7. Product Owner reviews for intent alignment, scope discipline, acceptance criteria
+8. Code Reviewer and domain reviewers may add advisory PR comments unless explicitly added as executionPolicy participants
+9. DevOps reviews infrastructure impact when explicitly added as a stage
+10. Engineer merges when all stages are approved (no `changes_requested` outstanding), confirms the PR landed on the correct base, closes/archives any isolated worktree that Paperclip created, and only then records the final approval / closes the issue
 
 ## Handover mechanism
 
-The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` verdict, optionally mirrored as a GitHub PR comment. If a reviewer doesn't wake, the CEO's stall-detection (if enabled) will catch it.
+The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` decision through the normal issue update route; Paperclip stores the reviewer/approver audit trail on the issue (`reviewed_by` / `approved_by` metadata where exposed). The decision may be mirrored as a GitHub PR comment. Do not create separate review subissues. If a reviewer doesn't wake, the CEO's stall-detection (if enabled) will catch it.
 
 ## Best for
 

package/templates/modules/pr-review/agents/devops/skills/infra-review.md

@@ -16,7 +16,7 @@ You review PRs for infrastructure impact, performance, security, and operational
 
 1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
 2. Focus on infrastructure, deployment, runtime security, observability, and rollback risk.
-3. Record your verdict on your review stage:
+3. Record your verdict through the normal issue update route for your review stage:
    - **approved** if operationally sound
    - **changes_requested** with specific concerns if not
 4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.