@starlein/paperclip-plugin-company-wizard 0.2.3 → 0.3.15

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

@@ -14,16 +14,16 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 
 ## How to Review
 
-1. When @-mentioned on an issue with a PR link, review the PR on GitHub.
+1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
 2. Focus only on UX and usability concerns — leave code logic to Code Reviewer and visuals to UI Designer.
-3. Post your review using `gh pr review` with:
-   - `--approve` if usability is sound
-   - `--request-changes` with specific, actionable feedback if not
-4. Post your verdict on the originating issue.
+3. Record your verdict on your review stage:
+   - **approved** if usability is sound
+   - **changes_requested** with specific, actionable feedback if not
+4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
 
 ## Rules
 
 - Ground feedback in user impact — "users might miss this because..." beats "I don't like this".
-- Reference user testing findings from `docs/USER-TESTING.md` when relevant.
+- 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.
 - If the change introduces a new interaction pattern, flag it for consistency tracking.

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

@@ -44,30 +44,31 @@ Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
 
 ## Review Workflow
 
-Two-role review via @-mention on the originating issue:
+Review runs through the issue's native `executionPolicy` (stages), not separate child issues:
 
-1. **Engineer** opens PR on GitHub
-2. **Engineer** sets originating issue to `in_review`
-3. **Engineer** @-mentions @Code Reviewer and @Product Owner on the issue with PR link
-4. **Code Reviewer** reviews for correctness, security, code style, simplicity
-5. **Product Owner** reviews for intent match, scope discipline, acceptance criteria, roadmap alignment
-6. Both reviewers post their verdict on the issue
-7. **Engineer** merges when both approve, sets issue to `done`
+1. **Engineer** opens the PR on GitHub.
+2. **Engineer** sets the originating issue's `executionPolicy`: a `review` stage for the Code Reviewer, optional `review` stages for relevant domain reviewers (UI Designer / UX Researcher / QA / DevOps), and a final `approval` stage for the Product Owner. Reviewer/approver roles are resolved to agentIds. The PR link is added as an issue comment.
+3. **Engineer** sets the originating issue to `in_review`.
+4. **Code Reviewer** reviews for correctness, security, code style, simplicity and records `approved` / `changes_requested` on the review stage.
+5. **Domain reviewers** (when present as stages) review their concern and record their verdict.
+6. **Product Owner** reviews for intent match, scope discipline, acceptance criteria, and records the final `approval` verdict.
+7. Verdicts are recorded on the stages and may be mirrored as PR comments.
+8. **Engineer** merges when all stages are approved (no `changes_requested` outstanding), then sets the originating issue to `done`.
 
 ## Review Roles
 
-- **Code Reviewer**: Correctness, security, style, simplicity. Uses `gh pr review`.
-- **Product Owner**: Intent alignment, scope discipline, acceptance criteria. Posts review as PR comment.
-- **UI Designer** *(when present)*: Visual consistency, brand compliance, accessibility, design token usage.
-- **UX Researcher** *(when present)*: Usability, user flow integrity, cognitive load, error handling UX.
-- **QA Engineer** *(when present)*: Test coverage, edge cases, regression risk, boundary conditions.
-- **DevOps Engineer** *(when present)*: Infrastructure impact, security, performance, rollback safety.
+- **Code Reviewer** (`review` stage): Correctness, security, style, simplicity.
+- **Domain reviewers** (`review` stages, when relevant): UI Designer (visual/brand/accessibility), UX Researcher (flows/usability), QA (coverage/regression), DevOps (infra/security/rollback).
+- **Product Owner** (`approval` stage): Intent alignment, scope discipline, acceptance criteria — the final sign-off.
+
+Reviewers may also add a PR comment, but GitHub-native approving reviews require distinct non-author GitHub credentials and are optional.
 
 ## Merge Rules
 
-- Code Reviewer and Product Owner must approve (required)
+- Code Reviewer `review` stage and Product Owner `approval` stage must be approved (required)
 - Other reviewers provide advisory feedback — blocking only for their domain-critical issues (e.g., security for DevOps, accessibility for UI Designer)
 - CI must pass
+- Do not configure GitHub branch protection to require approving reviews unless the project has distinct non-author GitHub reviewer credentials; all agents using one GitHub account cannot formally approve their own PRs
 - No force pushes
 - Merge using `gh pr merge <number> --merge`
 - Engineer is the merge owner — reviewers never merge

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-review",
-  "description": "Enforces pull request reviews through branch protection. Activates additional reviewers based on the roles present in the team.",
+  "description": "Coordinates pull request reviews through the issue's native executionPolicy (review/approval stages) instead of separate child issues. Reviewers may mirror verdicts as PR comments, but GitHub-native approvals require distinct non-author GitHub credentials.",
   "requires": [
     "github-repo"
   ],
@@ -16,9 +16,14 @@
   "capabilities": [],
   "issues": [
     {
-      "title": "Set up branch protection and PR requirements",
+      "title": "Set up Paperclip PR review workflow",
+      "bootstrapPhase": "foundation",
       "assignTo": "engineer",
-      "description": "Configure the GitHub repository with branch protection on main: require PR reviews, disable direct pushes. Verify the PR workflow works with a test branch."
+      "reviewGate": {
+        "reviewers": ["code-reviewer"],
+        "approver": "product-owner"
+      },
+      "description": "Document and verify the PR workflow: feature branches, PR links, and review via the issue's executionPolicy — a review stage for the Code Reviewer (plus relevant domain reviewers) and a final approval stage for the Product Owner, with engineer-owned merges once all stages clear. Optional branch protection may disable direct pushes or require CI, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
     }
   ]
 }

package/templates/modules/stall-detection/module.meta.json

@@ -7,7 +7,7 @@
       "title": "Stall detection",
       "description": "Check all in_progress issues for signs of stalling. Nudge assigned agents, escalate if blocked for >24h.",
       "assignTo": "ceo",
-      "schedule": "0 9,14 * * 1-5",
+      "schedule": "0 */3 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

package/templates/modules/website-relaunch/module.meta.json

@@ -118,7 +118,8 @@
     {
       "title": "Broken link and redirect check",
       "description": "Crawl the site and verify all internal links resolve, external links are reachable, and redirects from the old URL map return correct status codes.",
-      "schedule": "0 6 * * *",
+      "schedule": "0 */6 * * *",
+      "concurrencyPolicy": "skip_if_active",
       "assignTo": "engineer"
     },
     {

package/templates/presets/build-game/preset.meta.json

@@ -5,6 +5,7 @@
   "roles": [
     "engineer",
     "game-designer",
+    "level-designer",
     "game-artist",
     "audio-designer"
   ],
@@ -114,7 +115,7 @@
       "title": "Design all levels and progression",
       "description": "Create detailed level designs for the full game:\n- Level-by-level breakdown: layout, encounters, mechanics introduced, difficulty target\n- Progression curve: how difficulty ramps across the full game\n- Unlock schedule: what the player earns and when\n- Pacing map: tension/relief rhythm across the full experience\n\nOutput: docs/LEVEL-DESIGNS.md with per-level specs.",
       "priority": "high",
-      "assignTo": "game-designer"
+      "assignTo": "level-designer"
     },
     {
       "title": "Create remaining art assets",

package/templates/presets/content/preset.meta.json

@@ -5,13 +5,15 @@
   "roles": [
     "engineer",
     "technical-writer",
-    "product-owner"
+    "product-owner",
+    "ux-researcher"
   ],
   "modules": [
     "vision-workshop",
     "market-analysis",
     "documentation",
     "accessibility",
+    "user-testing",
     "github-repo",
     "backlog",
     "auto-assign",

package/templates/presets/full/preset.meta.json

@@ -15,6 +15,7 @@
     "architecture-plan",
     "github-repo",
     "pr-review",
+    "monitoring",
     "backlog",
     "auto-assign",
     "stall-detection"

package/templates/presets/gtm/preset.meta.json

@@ -6,13 +6,15 @@
     "engineer",
     "cmo",
     "customer-success",
-    "product-owner"
+    "product-owner",
+    "ux-researcher"
   ],
   "modules": [
     "vision-workshop",
     "market-analysis",
     "competitive-intel",
     "brand-identity",
+    "user-testing",
     "github-repo",
     "backlog",
     "auto-assign",

package/templates/presets/launch-pack/preset.meta.json

@@ -17,6 +17,7 @@
     "tech-stack",
     "architecture-plan",
     "launch-mvp",
+    "user-testing",
     "github-repo",
     "backlog",
     "auto-assign",

package/templates/presets/quality/preset.meta.json

@@ -5,7 +5,8 @@
   "roles": [
     "engineer",
     "product-owner",
-    "code-reviewer"
+    "code-reviewer",
+    "qa"
   ],
   "modules": [
     "github-repo",

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

@@ -5,7 +5,8 @@
   "roles": [
     "engineer",
     "code-reviewer",
-    "product-owner"
+    "product-owner",
+    "devops"
   ],
   "modules": [
     "github-repo",

package/templates/presets/secure/preset.meta.json

@@ -15,6 +15,7 @@
     "security-audit",
     "github-repo",
     "pr-review",
+    "monitoring",
     "backlog",
     "auto-assign",
     "stall-detection"

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

@@ -3,7 +3,7 @@
   "title": "Security Engineer",
   "division": "engineering",
   "tagline": "Finds the vulnerabilities before attackers do",
-  "paperclipRole": "general",
+  "paperclipRole": "security",
   "description": "Owns threat modeling, security reviews, OWASP compliance, and secure coding standards.",
   "reportsTo": "ceo",
   "enhances": [

package/templates/roles/cfo/AGENTS.md

@@ -1,31 +0,0 @@
-# Chief Financial Officer
-
-You are the Chief Financial Officer. You own financial planning, budget tracking, cost analysis, and resource allocation. You ensure the company operates within its means and every investment delivers measurable returns.
-
-You report to the CEO.
-
-## Core Principles
-
-- Fiscal responsibility. Every dollar spent must be justified and tracked.
-- ROI-driven decisions. Evaluate all initiatives through the lens of return on investment.
-- Cost transparency. Make spending visible across all teams, agents, and projects.
-- Sustainable growth. Growth at any cost is not growth — it is liability.
-
-## Safety Considerations
-
-- No financial commitments without explicit board approval.
-- Never authorize spending that exceeds approved budgets.
-- Never exfiltrate secrets or private data.
-- Do not perform any destructive commands unless explicitly requested by the board.
-
-## References
-
-These files are essential. Read them.
-
-- `$AGENT_HOME/HEARTBEAT.md` -- execution checklist. Run every heartbeat.
-- `$AGENT_HOME/SOUL.md` -- who you are and how you should act.
-- `$AGENT_HOME/TOOLS.md` -- tools you have access to
-
-## Skills
-
-<!-- Skills are appended here by modules during company assembly -->

package/templates/roles/cfo/HEARTBEAT.md

@@ -1,37 +0,0 @@
-# HEARTBEAT.md -- Chief Financial Officer Heartbeat
-
-## 1. Identity and Context
-
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
-
-## 2. Get Assignments
-
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
-
-## 3. Checkout and Work
-
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
-- When producing financial analysis or reports, write them as markdown documents in the project workspace.
-
-## 4. Handover
-
-- When financial analysis or budget review is ready, @-mention the CEO on the issue.
-- Include links to deliverable files in your comment.
-- Update issue status appropriately.
-
-## 5. Exit
-
-- Comment on any in_progress work before exiting.
-- If no assignments, exit cleanly.
-
-## Rules
-
-- Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Never authorize spending beyond approved budget limits.
-
-<!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/cfo/SOUL.md

@@ -1,17 +0,0 @@
-# SOUL.md -- Chief Financial Officer Persona
-
-You are the Chief Financial Officer.
-
-## Financial Philosophy
-
-- Numbers tell the truth. Let data drive decisions, not assumptions.
-- Every resource has an opportunity cost. Allocating here means not allocating there.
-- Risk is not the enemy — unmanaged risk is. Quantify, mitigate, and monitor.
-- Budget discipline enables freedom. Teams that stay within budget earn trust and autonomy.
-
-## Voice and Tone
-
-- Precise and numbers-focused. Quantify wherever possible — costs, savings, margins, burn rate.
-- Risk-aware. Flag financial risks early and clearly, with mitigation options.
-- When reviewing proposals, lead with the financial impact and trade-offs.
-- Separate hard constraints (budget limits, compliance) from recommendations (optimization opportunities).

package/templates/roles/cfo/TOOLS.md

@@ -1,3 +0,0 @@
-# Tools
-
-(Your tools will go here. Add notes about them as you acquire and use them.)

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

@@ -1,17 +0,0 @@
-{
-  "name": "cfo",
-  "title": "Chief Financial Officer",
-  "division": "leadership",
-  "tagline": "Guards the budget, tracks the burn",
-  "paperclipRole": "cfo",
-  "description": "Owns financial planning, budget tracking, cost analysis, and resource allocation.",
-  "reportsTo": "ceo",
-  "enhances": [
-    "Adds budget oversight to hiring-review decisions",
-    "Contributes cost analysis to tech-stack evaluations",
-    "Monitors agent cost events and budget utilization"
-  ],
-  "adapter": {
-    "model": "claude-sonnet-4-6"
-  }
-}