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

package/templates/modules/pr-review/agents/ux-researcher/skills/ux-review.md

@@ -14,16 +14,14 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 
 ## How to Review
 
-1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
+1. When a PR changes user-facing behavior, interactions, or flows, review it for the UX concerns below.
 2. Focus only on UX and usability concerns — leave code logic to Code Reviewer and visuals to UI Designer.
-3. Record your verdict through the normal issue update route for your review stage:
-   - **approved** if usability is sound
-   - **changes_requested** with specific, actionable feedback 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*.
+3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment 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*.
+4. If you find a concern that should block the merge (e.g. a flow that traps users in a dead end), flag it explicitly in the comment and name who should act on it — QA, the Security Engineer, or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
 
 ## Rules
 
 - Ground feedback in user impact — "users might miss this because..." beats "I don't like this".
 - If `docs/USER-TESTING.md` exists, reference its findings where relevant. If it doesn't exist yet, ground feedback in the PR and existing app patterns instead.
-- Approve changes that don't affect user-facing behavior without comment.
+- Comment only on changes that affect user-facing behavior.
 - If the change introduces a new interaction pattern, flag it for consistency tracking.

package/templates/modules/pr-review/docs/pr-conventions.md

@@ -68,8 +68,8 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 3. **Engineer** sets the originating issue's `executionPolicy` stages, in order:
    - a `review` stage for **QA** when a QA agent is on the team (test adequacy / running the tests),
    - a `review` stage for the **Security Engineer** *only when the change is security-relevant* (auth, secrets, input boundaries, crypto, dependencies, infra exposure),
-   - an `approval` stage for the **Product Owner** (intent, scope, acceptance),
-   - a final `approval` stage for the **Code Reviewer** as the merge gate (a non-author — Paperclip excludes the issue's executor from every stage).
+   - an `approval` stage for the **Product Owner** when one is on the team (intent, scope, acceptance),
+   - a final `approval` stage for the **Code Reviewer** as the merge gate (a non-author — Paperclip excludes the issue's executor from every stage). When no Code Reviewer is on the team, do not set executionPolicy stages at all — use the PR Self-Merge Flow (the engineer opens the PR and merges via `gh pr merge <N> --merge`); other review roles may leave advisory comments but do not block.
    Resolve each role to its agentId. **Never list the issue's executor (the engineer who authored the work) as a participant in any stage** — the runtime excludes the original executor, so such a stage has no eligible participant and the issue stalls (`422 No eligible approval participant`).
 4. **Engineer** sets the issue to `in_review`.
 5. **QA** (when present) reviews and records `approved`/`changes_requested` through the normal issue update route with executed evidence (see *Merge Rules*), preserving the issue-level review audit trail.
@@ -82,8 +82,8 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 
 - **QA** (`review` stage, when present): the substantive gate. Test coverage, regression risk, and validation — backed by tests that actually ran.
 - **Security Engineer** (`review` stage, only when the change is security-relevant): probes the diff for injection, auth, secrets, crypto, dependency, and exposure issues.
-- **Product Owner** (`approval` stage): intent alignment, scope discipline, acceptance criteria.
-- **Code Reviewer** (`approval` stage, last): the merge gate and hard-gate backstop — a non-author who verifies and lands the PR. See *Merge Rules*.
+- **Product Owner** (`approval` stage, when present): intent alignment, scope discipline, acceptance criteria.
+- **Code Reviewer** (`approval` stage, last, when present): the merge gate and hard-gate backstop — a non-author who verifies and lands the PR. See *Merge Rules*. When no Code Reviewer is present, the engineer self-merges via `gh pr merge <N> --merge` and no executionPolicy stages are set.
 - **Domain reviewers** (advisory): optional, non-blocking comments on correctness, clarity, design, accessibility, UX. They never gate the merge.
 
 ## Merge Rules

package/templates/modules/pr-review/module.meta.json

@@ -25,7 +25,7 @@
         "approver": "product-owner",
         "mergeGate": "code-reviewer"
       },
-      "description": "Document and verify the PR workflow via the issue's executionPolicy. The merge gate is executed verification: with CI, builds must be green before merge; without CI, the merge-gate agent runs the test suite/build and pastes the output before merging. Stages: a review stage for QA when present, a review stage for the Security Engineer only on security-relevant changes, an approval stage for the Product Owner, and a final approval stage for the Code Reviewer as the merge gate (a non-author woken last to merge the PR before recording approval, which closes the issue). Never list the issue's executor/author as a participant in any stage — Paperclip excludes the original executor, so a stage whose only participant is the author has no eligible participant and the issue stalls (`422 No eligible approval participant is configured for this issue`); this is why the merge gate is the Code Reviewer (or another non-author), not the engineer. The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. Other domain reviewers add advisory, non-blocking comments. Optional branch protection may disable direct pushes, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
+      "description": "Document and verify the PR workflow via the issue's executionPolicy. The merge gate is executed verification: with CI, builds must be green before merge; without CI, the merge-gate agent runs the test suite/build and pastes the output before merging. Stages: a review stage for QA when present, a review stage for the Security Engineer only on security-relevant changes, an approval stage for the Product Owner when present, and a final approval stage for the Code Reviewer as the merge gate (a non-author woken last to merge the PR before recording approval, which closes the issue). Never list the issue's executor/author as a participant in any stage — Paperclip excludes the original executor, so a stage whose only participant is the author has no eligible participant and the issue stalls (`422 No eligible approval participant is configured for this issue`); this is why the merge gate is the Code Reviewer (a non-author), not the engineer. The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. Other domain reviewers add advisory, non-blocking comments. Optional branch protection may disable direct pushes, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials. When no code-reviewer role is present in the company, use PR-Self-Merge mode instead: the engineer opens the PR normally but skips executionPolicy stages entirely and merges via `gh pr merge <N> --merge` themselves. Other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR but do not block the merge. Never set up executionPolicy stages when there is no eligible non-author merge gate — the issue will stall with `422 No eligible approval participant`."
     }
   ]
 }

package/templates/modules/security-audit/skills/threat-model.md

@@ -12,7 +12,7 @@ You own threat modeling for the project. This identifies security risks before t
    - **Risk ratings**: Likelihood x Impact = Risk (Critical/High/Medium/Low)
    - **Mitigations**: Recommended controls for each threat
 3. Create follow-up issues for Critical and High risks:
-   - `POST /api/companies/{companyId}/issues` with specific remediation tasks. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with specific remediation tasks. 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/stall-detection/agents/ceo/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Stall Detection Routine
 
-Do not scan for stalled work during a normal heartbeat. When you are assigned a routine-run issue titled like "Stall detection", use `skills/stall-detection.md`, then summarize findings on the routine issue and exit.
+Do not scan for stalled work during a normal heartbeat. When you are assigned a routine-run issue titled like "Stall detection", use `$AGENT_HOME/skills/stall-detection.md`, then summarize findings on the routine issue and exit.

package/templates/modules/tech-stack/skills/tech-stack.md

@@ -15,7 +15,7 @@ You own technology decisions. Evaluate options and document choices that align w
    - **Trade-offs**: What was considered and rejected, and why
    - **Dependencies**: Key libraries and their purposes
 4. Create setup issues if needed:
-   - `POST /api/companies/{companyId}/issues` for initial project scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for initial project 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.
 
 ## Rules
 

package/templates/modules/triage/skills/issue-triage.md

@@ -16,7 +16,7 @@ Use this only when the current assigned issue/routine asks for GitHub issue tria
    - Set priority P0-P3; P0 maps to urgent Paperclip priority.
    - Apply labels with `gh issue edit <number> --add-label "<type>,<priority>"`.
    - Respond to the reporter with acknowledgement, follow-up questions, or a polite close reason.
-   - For actionable issues, create a corresponding Paperclip issue via `POST /api/companies/{companyId}/issues`. Include GitHub issue URL/number, active `projectId`, and `goalId` / `parentId` when applicable.
+   - For actionable issues, create a corresponding Paperclip issue via `POST /api/companies/{companyId}/issues`. Include GitHub issue URL/number, 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. Link bidirectionally: GitHub comment references the Paperclip issue, Paperclip issue references GitHub.
 5. Summarize triage results on the assigned triage issue/routine and mark it done.
 

package/templates/modules/user-testing/agents/qa/skills/user-testing.md

@@ -18,7 +18,7 @@ You are the QA engineer and user-facing quality is your core domain. You own tes
    - **Major**: Significant friction or confusion
    - **Minor**: Cosmetic or low-impact usability issues
 7. Create follow-up issues for critical and major findings:
-   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. 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.
 8. Record summary in your daily notes
 
 ## Rules

package/templates/modules/user-testing/skills/user-testing.md

@@ -16,7 +16,7 @@ You own usability evaluations and user testing. This ensures the product meets r
    - **Major**: Significant friction or confusion
    - **Minor**: Cosmetic or low-impact usability issues
 6. Create follow-up issues for critical and major findings:
-   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. 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.
 7. Record summary in your daily notes
 
 ## Rules

package/templates/modules/vision-workshop/agents/ceo/skills/vision-workshop.md

@@ -12,7 +12,7 @@ You own the company vision. Refine the initial goal into a strategic foundation
    - **Strategic milestones**: Ordered list of milestones that lead to the vision
    - **Non-goals**: What the company explicitly does NOT do (prevents scope creep)
 3. Create issues for the first milestone's deliverables:
-   - `POST /api/companies/{companyId}/issues` with milestone context. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with milestone context. 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. Share the vision doc with the team via daily notes
 
 ## Rules

package/templates/presets/repo-maintenance/preset.meta.json

@@ -35,7 +35,7 @@
           "id": "process-setup",
           "title": "Process Setup",
           "level": "team",
-          "description": "Establish PR review, issue triage, and release workflows. Done when branch protection configured, PR conventions documented, issue labels created, release process documented."
+          "description": "Establish PR review, issue triage, and release workflows. Done when PR workflow documented (branch requires PRs, no approval gate), issue labels created, release process documented."
         },
         {
           "id": "initial-sweep",
@@ -66,8 +66,8 @@
       "assignTo": "engineer"
     },
     {
-      "title": "Configure branch protection and PR workflow",
-      "description": "Set up branch protection on the default branch, require PR reviews, configure review conventions. Document in docs/pr-conventions.md.",
+      "title": "Configure PR workflow and branch protection",
+      "description": "Configure the PR workflow and set up branch protection on the default branch. Branch protection must require a PR before merging (no direct pushes to the base branch — set enforce_admins: true so the shared admin account cannot bypass the PR rule), but must NOT require GitHub-native approving reviews — all agents share one GitHub account and cannot formally approve their own PRs; the review gate lives in Paperclip's executionPolicy, not in GitHub. Use the exact gh api heredoc command from the git-workflow skill → Branch Protection Setup: `gh api repos/{owner}/{repo}/branches/{base}/protection --method PUT --input - <<'EOF'` with payload {\"required_status_checks\": null, \"enforce_admins\": true, \"required_pull_request_reviews\": {\"required_approving_review_count\": 0, \"dismiss_stale_reviews\": false}, \"restrictions\": null}. With required_approving_review_count: 0 the shared account can still open a PR and merge it with zero approvals, so the self-merge flow keeps working. Document PR conventions in docs/pr-conventions.md.",
       "priority": "high",
       "assignTo": "engineer"
     },

package/templates/roles/audio-designer/role.meta.json

@@ -7,8 +7,11 @@
   "description": "Owns audio production: sound effects, music, ambient soundscapes, and audio systems design. Creates audio using AI generation tools, code-based synthesis, and audio processing pipelines.",
   "reportsTo": "ceo",
   "enhances": [
-    "Takes over audio asset creation from Engineer (placeholder sounds → production audio)",
+    "Takes over audio asset creation from Engineer (placeholder sounds \u2192 production audio)",
     "Takes over audio direction definition from Game Designer",
     "Adds audio consistency review pass when pr-review module is active"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }

package/templates/roles/cmo/role.meta.json

@@ -12,6 +12,7 @@
     "Adds marketing review pass (with pr-review module)"
   ],
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

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

@@ -15,16 +15,16 @@ You report to the CEO.
    - **Security**: Any injection, XSS, credential exposure, or OWASP risks?
    - **Style**: Consistent with existing codebase patterns?
    - **Simplicity**: Is there unnecessary complexity? Could it be simpler?
-6. Post your review as **advisory** feedback: write it to a Markdown file (start with a heading, e.g. `## 💬 Review notes` or `## 🔄 Changes requested`) and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown. Your review does not gate the merge — that gate is QA + CI (and the Security Engineer on security-relevant changes); do not submit a GitHub-native approving review, since all agents share one GitHub account.
+6. Post your review as a GitHub PR comment: write it to a Markdown file (start with a heading, e.g. `## 💬 Review notes` or `## 🔄 Changes requested`) and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown. Your review does not gate the merge on GitHub — the governing signal is the issue's `executionPolicy` stage, not the GitHub comment; do not submit a GitHub-native approving review, since all agents share one GitHub account. Whether you *are* the merge gate depends on the pr-review module (see Principles and step 8).
 7. Post your verdict on the originating issue.
-8. Mark your issue as `done`.
+8. **When the pr-review module is active**, you are the non-author merge gate: satisfy the hard verification gate (green CI or pasted test/build output), merge the PR via `gh pr merge <N> --merge`, archive any isolated worktree, then record `approved` on your approval stage — the executionPolicy closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open. **Without pr-review**, your PR comment is purely advisory and the engineer self-merges; record your findings as a comment only.
 
 ## Principles
 
 - Be direct. Approve when good enough — don't bikeshed.
 - Flag security issues as blocking. Everything else is a suggestion unless it's clearly wrong.
 - Ask before guessing. If intent is unclear, ask on the issue rather than assuming.
-- Never merge PRs. That's the engineer's job.
+- When the pr-review module is active, you are the non-author merge gate: after all prior stages approve, satisfy the hard verification gate (green CI or pasted test/build output), then merge via `gh pr merge <N> --merge`, archive any isolated worktree, and record `approved` to close the issue. Without pr-review, the engineer self-merges.
 
 ## Safety Considerations
 

package/templates/roles/code-reviewer/role.meta.json

@@ -8,5 +8,8 @@
   "reportsTo": "ceo",
   "enhances": [
     "Adds code-quality review pass when pr-review module is active"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }

package/templates/roles/cto/role.meta.json

@@ -13,6 +13,7 @@
   ],
   "adapter": {
     "model": "claude-opus-4-6",
-    "effort": "high"
+    "effort": "high",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/customer-success/role.meta.json

@@ -12,6 +12,7 @@
     "Adds customer-impact review pass when pr-review module is active"
   ],
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/devops/role.meta.json

@@ -12,6 +12,7 @@
     "Adds infrastructure review pass (with pr-review module)"
   ],
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/engineer/role.meta.json

@@ -8,6 +8,7 @@
   "description": "Implements features, fixes bugs, writes tests, manages git workflow.",
   "reportsTo": "ceo",
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/game-artist/role.meta.json

@@ -7,8 +7,11 @@
   "description": "Owns visual art production: sprites, textures, tilesets, UI elements, and visual effects. Generates assets using AI image generation tools and code-based approaches (SVG, procedural generation, pixel art scripts).",
   "reportsTo": "ceo",
   "enhances": [
-    "Takes over art asset creation from Engineer (placeholder art → production art)",
+    "Takes over art asset creation from Engineer (placeholder art \u2192 production art)",
     "Takes over art style guide definition from Game Designer",
     "Adds visual consistency review pass when pr-review module is active"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }

package/templates/roles/game-designer/role.meta.json

@@ -10,5 +10,8 @@
     "Takes over game-design from Engineer/CEO (they become fallback)",
     "Takes over user-testing with playtesting focus (engagement, fun, difficulty)",
     "Adds gameplay review pass when pr-review module is active"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }

package/templates/roles/level-designer/role.meta.json

@@ -9,5 +9,8 @@
   "enhances": [
     "Takes over level-specific design from Game Designer/Engineer",
     "Contributes difficulty curve and pacing data to game balancing"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }

package/templates/roles/product-owner/role.meta.json

@@ -10,5 +10,8 @@
     "Takes over backlog health from CEO (CEO becomes fallback)",
     "Takes over auto-assign from CEO (CEO becomes fallback)",
     "Adds product-alignment review pass when pr-review module is active"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }

package/templates/roles/qa/role.meta.json

@@ -12,6 +12,7 @@
     "Contributes test coverage requirements to architecture-plan"
   ],
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/security-engineer/role.meta.json

@@ -12,6 +12,7 @@
     "Contributes threat model to architecture-plan"
   ],
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/technical-writer/role.meta.json

@@ -11,6 +11,7 @@
     "Adds documentation review pass when pr-review module is active"
   ],
   "adapter": {
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "auto"
   }
 }

package/templates/roles/ui-designer/role.meta.json

@@ -7,7 +7,8 @@
   "description": "Owns visual identity, UI design systems, and brand consistency. Creates design specs that engineers implement.",
   "reportsTo": "ceo",
   "adapter": {
-    "chrome": true
+    "chrome": true,
+    "thinkingLevel": "auto"
   },
   "enhances": [
     "Takes over architecture-plan visual/UI layer from Engineer (Engineer becomes fallback for UI architecture)",

package/templates/roles/ux-researcher/role.meta.json

@@ -10,5 +10,8 @@
     "Takes over market-analysis user research section from Product Owner/CEO",
     "Takes over vision-workshop success metrics validation from CEO",
     "Adds UX review pass when pr-review module is active"
-  ]
+  ],
+  "adapter": {
+    "thinkingLevel": "auto"
+  }
 }