@starlein/paperclip-plugin-company-wizard 0.2.4 → 0.3.18

package/package.json

@@ -1,11 +1,9 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.2.4",
+  "version": "0.3.18",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org"
-  },
+  "repository": "https://github.com/starlein/paperclip-plugin-company-wizard",
   "scripts": {
     "build": "node ./esbuild.config.mjs",
     "build:rollup": "rollup -c",
@@ -14,10 +12,15 @@
     "test": "vitest run --config ./vitest.config.ts",
     "test:logic": "node --test src/logic/*.test.js src/api/*.test.js",
     "typecheck": "tsc --noEmit",
+    "build:prod": "NODE_ENV=production node ./esbuild.config.mjs",
     "publish:npm": "npm publish --access public",
-    "prepublishOnly": "pnpm build",
+    "prepublishOnly": "pnpm build:prod",
     "prepare": "husky"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "lint-staged": {
     "src/**/*.{ts,tsx,js,jsx}": [
       "prettier --write"
@@ -46,8 +49,8 @@
     "tailwind-merge": "^3.4.1"
   },
   "devDependencies": {
-    "@paperclipai/plugin-sdk": "file:../paperclip/packages/plugins/sdk",
-    "@paperclipai/shared": "file:../paperclip/packages/shared",
+    "@paperclipai/plugin-sdk": "^2026.529.0",
+    "@paperclipai/shared": "^2026.529.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-typescript": "^12.1.2",
     "@tailwindcss/postcss": "^4.0.7",
@@ -67,6 +70,8 @@
     "vitest": "^3.0.5"
   },
   "peerDependencies": {
+    "@paperclipai/plugin-sdk": ">=2026.529.0",
+    "@paperclipai/shared": ">=2026.529.0",
     "react": ">=18",
     "react-dom": ">=18"
   }

package/templates/ai-wizard/config-format.md

@@ -2,10 +2,13 @@ Respond with ONLY a JSON object (no markdown fences):
 {
   "name": "CompanyName",
   "companyDescription": "Comprehensive 2-4 paragraph description of what this company does, what it is building, who it is for, key technical decisions, priorities, constraints, and any special context. This is the company's permanent record — be thorough and specific.",
-  "goal": "Goal title — what the team should accomplish first",
-  "goalDescription": "Detailed paragraph: scope, success criteria, key constraints and context.",
-  "project": "Project name",
-  "projectDescription": "Concrete project description — what is being built and key technical details.",
+  "goals": [
+    { "title": "Top-level company goal", "description": "Detailed paragraph: scope, success criteria, key constraints and context." },
+    { "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" } } }
+  ],
   "preset": "preset-name",
   "modules": ["all-modules-to-activate-including-preset-ones"],
   "roles": ["all-non-base-roles-needed-including-preset-ones-engineer-is-not-base"],
@@ -14,6 +17,11 @@ 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.
+- 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`.
+  - 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.
 - If the user mentions speed/MVP/prototype, lean toward fast or rad.

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

@@ -39,7 +39,7 @@ Across your 3 questions, try to cover as many of these as the user's initial des
 3. **Quality vs speed** — Ship fast, iterate? Or production-grade, high quality from the start?
 4. **Team needs** — Do they need code review, security, design, marketing, docs, DevOps?
 5. **Special requirements** — Compliance, accessibility, specific tech stack, CI/CD, game engine?
-6. **Repository** — Is there an existing repo? What language/framework?
+6. **Repository** — Should Paperclip create a new Git repository/workspace, or should the agents use an existing external repo such as GitHub/GitLab? If external, ask for URL and branch/ref; never ask for tokens.
 
 Don't ask about things already clear from the initial description. Skip to what's missing.
 
@@ -50,7 +50,7 @@ The user's interview answers are the primary source of context for the company.
 - **`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.
+- **`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`.
 
 RECOMMENDATION (plain text, before the JSON):
 - One paragraph explaining your reasoning: why this preset, why these modules, why these roles.
@@ -64,4 +64,5 @@ Then output the JSON:
 - `modules` should list ALL modules to activate (including preset ones).
 - `roles` should list ALL non-base roles the company needs. This includes roles that come with the preset. The system does not auto-add preset roles — you must list them explicitly.
 - If the project involves building software, `engineer` MUST be in `roles`.
+- The primary project MUST state whether it uses a fresh local Git repository or an external Git repository. Do not put credentials or tokens in repository fields.
 - Be pragmatic — don't over-engineer. Match the config to actual needs.

package/templates/ai-wizard/messages.json

@@ -2,5 +2,5 @@
   "interviewStart": "Here's what I want to build:\n\n{{DESCRIPTION}}\n\nStart the interview. Ask your first question.",
   "summaryRequest": "Now summarize what you understood about my company and needs. Keep it brief.",
   "iterateRequest": "Not quite right. Let me clarify. Ask 3 more follow-up questions to get a better understanding.",
-  "recommendationRequest": "Great. Now generate your recommendation. Explain your reasoning first (which preset and why, which extra modules and roles and why), then output the JSON configuration. Remember: include ALL non-base roles the company needs in the roles array (engineer is NOT a base role — list it if this project involves code). Write a thorough companyDescription that captures everything we discussed."
+  "recommendationRequest": "Great. Now generate your recommendation. Explain your reasoning first (which preset and why, which extra modules and roles and why), then output the JSON configuration. Remember: include ALL non-base roles the company needs in the roles array (engineer is NOT a base role — list it if this project involves code). Write a thorough companyDescription that captures everything we discussed. The primary project must explicitly choose repository setup: either a fresh local Git repository or an external Git repository such as GitHub. Never include credentials or tokens in repository fields."
 }

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

@@ -35,6 +35,10 @@ Given a natural language description of what the user wants to build, you select
 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.
 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`.
+   - 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

@@ -2,6 +2,8 @@ This is your bootstrap task. Create all the Paperclip objects listed below **in
 
 Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains objects to create via the Paperclip API.
 
+**The endpoints and payload shapes you need are listed in this file and in the `paperclip` skill. Do NOT read or grep the Paperclip server source (e.g. `server/src/routes/*`, `packages/shared/src/validators/*`) to reverse-engineer request schemas — the field names, references, and valid enum values below are authoritative. If a create call is rejected, fix it from the documented enums here, not by inspecting source.**
+
 **How to read the metadata:**
 
 - Direct values like `level: company` or `priority: high` → use as-is in the API call
@@ -13,8 +15,8 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 
 **Creation order** (respects dependencies):
 
-1. **Goals** — top-level first, then sub-goals. Sub-goals have `parentId: → "Parent Title"` — create the parent first, then use its ID
-2. **Projects** — reference goals via `goalIds`. Create after all goals exist. For Paperclip v2026.403.0, create the project workspace as an object: `workspace: { sourceType: "local_path", cwd: "...", isPrimary: true }`, not as a raw string.
+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.
 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,4 +29,12 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 - 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.
 
+**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.
+
+**Secrets guardrail:**
+
+- Never embed tokens, API keys, banking/SEPA credentials, provider keys, or connection strings in this file, in issue text, or in `adapterConfig`. Provision them as Paperclip company secrets and reference them via `secret_ref` / project `env`. If any secret was pasted in plaintext, rotate it.
+
 **After bootstrap**: keep labels current. When creating new issues in heartbeat cycles, always include explicit `projectId` on every issue, keep subissue parent links explicit, and attach appropriate `labelIds`.

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

@@ -2,7 +2,7 @@
 
 Only if the Product Owner is absent or stalled:
 
-1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+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.

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

@@ -6,7 +6,7 @@ The Product Owner primarily handles issue assignment. You are the fallback — s
 
 On your heartbeat, after handling your own assignments:
 
-1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+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

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

@@ -2,7 +2,7 @@
 
 After handling your own assignments:
 
-1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+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.

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

@@ -19,7 +19,7 @@
       "title": "Auto-assign unassigned issues",
       "description": "Find unassigned todo issues and assign to the best available agent based on role and workload.",
       "assignTo": "capability:auto-assign",
-      "schedule": "0 9,13 * * 1-5",
+      "schedule": "0 */2 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

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

@@ -6,7 +6,7 @@ You own issue assignment. Match issues to the right agents based on skills and a
 
 Run this on every heartbeat, after handling your own assignments.
 
-1. Query idle agents: `GET /api/companies/{companyId}/agents?status=idle`
+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

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

@@ -15,15 +15,16 @@
     {
       "title": "Create roadmap and generate initial backlog",
       "assignTo": "capability:backlog-health",
-      "description": "Review the company goal, create a ROADMAP.md with milestones, then generate the first batch of actionable issues from it."
+      "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."
     }
   ],
   "routines": [
     {
       "title": "Backlog grooming",
-      "description": "Ensure backlog has at least 3 actionable unassigned issues. If running low, generate new issues from the roadmap.",
+      "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.",
       "assignTo": "capability:backlog-health",
-      "schedule": "0 10 * * 1,3,5",
+      "schedule": "0 */4 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

package/templates/modules/build-api/module.meta.json

@@ -75,6 +75,7 @@
       "title": "API health check",
       "description": "Verify the API health endpoint responds correctly and monitor uptime.",
       "schedule": "*/15 * * * *",
+      "concurrencyPolicy": "skip_if_active",
       "assignTo": "engineer"
     },
     {

package/templates/modules/ci-cd/module.meta.json

@@ -99,7 +99,8 @@
       "title": "CI pipeline health check",
       "description": "Review recent CI runs for failures, flaky tests, and slow builds. Flag regressions and report pipeline health status.",
       "assignTo": "capability:ci-cd",
-      "schedule": "0 9 * * 1-5"
+      "schedule": "0 */6 * * *",
+      "concurrencyPolicy": "skip_if_active"
     }
   ]
 }

package/templates/modules/game-design/module.meta.json

@@ -10,6 +10,24 @@
         "ceo"
       ],
       "fallbackSkill": "game-design.fallback"
+    },
+    {
+      "skill": "level-design",
+      "owners": [
+        "level-designer",
+        "game-designer",
+        "engineer"
+      ],
+      "fallbackSkill": "level-design.fallback"
+    },
+    {
+      "skill": "audio-design",
+      "owners": [
+        "audio-designer",
+        "game-designer",
+        "engineer"
+      ],
+      "fallbackSkill": "audio-design.fallback"
     }
   ],
   "issues": [

package/templates/modules/game-design/skills/audio-design.fallback.md

@@ -0,0 +1,16 @@
+# Skill: Audio Design (Fallback)
+
+The Audio Designer primarily owns the game's audio. You are the fallback — step in only if no audio designer is present and the game has no usable sound.
+
+## Audio Design (Fallback)
+
+1. If `docs/GDD.md` exists but there is no audio and no audio designer is active:
+   - Add placeholder sounds for the gameplay-critical events first (player action, hit, pickup, success, failure) so feedback is legible.
+   - Note the intended character of each sound in `docs/AUDIO-DIRECTION.md` and mark it **provisional**.
+   - Keep volumes in config, not hardcoded.
+2. If an audio designer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Placeholder feedback sounds beat silence; mood and music can wait.
+- Don't produce final audio or design the full soundscape — leave that to the Audio Designer.

package/templates/modules/game-design/skills/audio-design.md

@@ -0,0 +1,28 @@
+# Skill: Audio Design
+
+You own the game's audio: sound effects, music, ambient soundscapes, and the systems that play them. You turn the audio direction in `docs/GDD.md` into concrete, production-quality audio.
+
+## Audio Design Document
+
+Create and maintain `docs/AUDIO-DIRECTION.md`. It must cover:
+
+1. **Audio vision** — The feeling the audio should evoke and reference tracks/games. One paragraph.
+2. **Music** — Themes per context (menu, gameplay, boss, victory, defeat), tempo/mood, and whether audio is adaptive (layers/stems that respond to state).
+3. **SFX taxonomy** — The full list of events that need a sound (player actions, UI, enemies, environment, feedback) with intended character for each (punchy, soft, organic, synthetic).
+4. **Ambience** — Background beds per area/level and how they transition.
+5. **Mix guidance** — Priority of layers, ducking rules (e.g. dialogue over music), and target loudness so nothing clips or buries gameplay cues.
+6. **Asset pipeline** — Where audio files live, naming convention, format, and how they're wired into the engine.
+
+## Production Work
+
+1. Produce audio with AI generation tools, code-based synthesis, or processing pipelines — whatever the tech stack supports.
+2. Replace any placeholder/programmer sounds the engineer added with production audio.
+3. Keep every gameplay-critical action audibly distinct — the player should recognize what happened without looking.
+4. On each heartbeat, if `docs/GDD.md` exists, check for new mechanics or events that lack audio and create issues to cover them.
+
+## Rules
+
+- Function before flourish: feedback sounds (hit, pickup, error) matter more than mood pieces. Do them first.
+- Respect the mix — audio that fights gameplay cues is worse than silence.
+- Parameterize volumes and keep them in config, never hardcoded.
+- Don't redefine the art or game direction; audio serves the experience defined in the GDD.

package/templates/modules/game-design/skills/level-design.fallback.md

@@ -0,0 +1,17 @@
+# Skill: Level Design (Fallback)
+
+The Level Designer primarily owns level layout and pacing. You are the fallback — step in only if no level designer is present and levels are blocking progress.
+
+## Level Design (Fallback)
+
+1. If `docs/GDD.md` exists but no level structure has been defined and no level designer is active:
+   - Sketch a minimal progression in `docs/LEVEL-DESIGN.md`: an ordered list of levels/areas and the one mechanic or challenge each introduces.
+   - Set a rough difficulty curve (easy → hard) and place checkpoints generously.
+   - Mark the document as **provisional** — it needs a dedicated level-design pass.
+2. If a level designer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Define enough structure that the team can build and test, no more.
+- Teach before you test: introduce each mechanic in a safe space first.
+- Don't tune detailed difficulty or pacing — leave that to the Level Designer.

package/templates/modules/game-design/skills/level-design.md

@@ -0,0 +1,29 @@
+# Skill: Level Design
+
+You own the layout, pacing, and difficulty progression of the game's playable spaces. You translate the mechanics defined in `docs/GDD.md` into concrete levels the player moves through.
+
+## Level Design Document
+
+Create and maintain `docs/LEVEL-DESIGN.md`. It must cover:
+
+1. **Progression map** — The order players experience levels/areas, and what each one introduces (a new mechanic, enemy, or twist). Nothing should appear before it's taught.
+2. **Difficulty curve** — How challenge ramps across the game. Mark intended spikes (boss, finale) and recovery beats (safe rooms, low-stakes sections).
+3. **Pacing** — Alternation of tension and release: action vs. exploration vs. puzzle vs. rest. Avoid long stretches of one texture.
+4. **Per-level beats** — For each level: goal, critical path, optional content, the one moment it's built around, and the skill it tests.
+5. **Spatial language** — How layout teaches without text: sightlines, lighting, landmarks, affordances that signal "go here" or "danger".
+6. **Tuning hooks** — Level-specific parameters (enemy counts, time limits, checkpoint spacing) referenced by name, defaults in the GDD.
+
+## Ongoing Design Work
+
+On each heartbeat when `docs/GDD.md` exists:
+
+1. If `docs/PLAYTEST-RESULTS.md` exists, look for levels where players got stuck, lost, or bored, and where the difficulty curve broke.
+2. Adjust layout, checkpoint placement, or pacing — change one variable at a time so cause and effect stay legible.
+3. Create issues for new levels, reworks, or difficulty passes, each tied to a specific player-experience problem.
+
+## Rules
+
+- Teach before you test. Introduce a mechanic in a safe space before demanding mastery.
+- A level should be built around one memorable moment — find it, then make the rest serve it.
+- Respect the GDD: levels express the game's mechanics, they don't invent new ones. If a level needs a new mechanic, raise it with the Game Designer.
+- Pace deliberately. Constant intensity is exhausting; constant calm is dull.

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

@@ -6,6 +6,7 @@ Enables the Engineer to work in a GitHub repository.
 
 - **Shared docs**: `docs/git-workflow.md` — commit conventions, branch rules
 - **Engineer skill**: Git workflow instructions for working in a repo
+- **Foundation issue**: `Prepare GitHub repository` is marked critical and ordered before normal implementation work. The assignee verifies an already-provisioned git workspace/remote or creates and pushes the repository before closing it.
 
 ## Variants
 

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

@@ -4,9 +4,12 @@
   "capabilities": [],
   "issues": [
     {
-      "title": "Initialize GitHub repository",
+      "title": "Prepare GitHub repository",
       "assignTo": "engineer",
-      "description": "Create the GitHub repository, initialize with README, push initial commit to main, and set up branch protection if using PR workflow."
+      "priority": "critical",
+      "bootstrapPhase": "foundation",
+      "labels": ["chore"],
+      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize local workspace with a README or bootstrap commit, add origin, push main, and record the repository URL. For an existing repository, verify the workspace has a reachable remote, current default branch, and starter commit state; escalate to CEO if repo setup is missing instead of silently closing the issue. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
     }
   ]
 }

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

@@ -18,18 +18,18 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 
 1. Engineer creates a feature branch (`<prefix>-<N>/<short-description>`)
 2. Engineer opens a PR with Conventional Commits title and issue reference
-3. Engineer @-mentions Code Reviewer and Product Owner on the issue (plus other reviewers if present and relevant)
+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 required reviewers approve and no domain blockers remain
+10. Engineer merges when all stages are approved (no `changes_requested` outstanding)
 
 ## Handover mechanism
 
-@-mention on the originating issue. 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` verdict, optionally mirrored as a GitHub PR comment. If a reviewer doesn't wake, the CEO's stall-detection (if enabled) will catch it.
 
 ## Best for
 
@@ -39,5 +39,5 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 
 ## Known limitations
 
-- All agents sharing one GitHub account means GitHub-native approval flow doesn't work. Review governance happens through Paperclip, not GitHub branch protection.
-- Agent-to-agent @-mentions may not always trigger wakes reliably. Pair with `stall-detection` module.
+- All agents sharing one GitHub account means GitHub-native approval flow doesn't work. Review governance happens through the issue's executionPolicy stages, not GitHub-required approving reviews.
+- If a review stage's participant is not picked up, the CEO's stall-detection (if enabled) should catch it.

package/templates/modules/pr-review/agents/code-reviewer/skills/code-review.md

@@ -1,6 +1,6 @@
 # Skill: Code Review
 
-You review PRs for correctness, security, code quality, and simplicity. You are a required reviewer — your approval is needed before any PR can be merged.
+You review PRs for correctness, security, code quality, and simplicity. You are a required reviewer — you are the participant of a `review` stage on the PR's issue, and your verdict gates the merge.
 
 ## Review Checklist
 
@@ -14,11 +14,11 @@ You review PRs for correctness, security, code quality, and simplicity. You are
 
 ## How to Review
 
-1. When @-mentioned on an issue with a PR link, review the PR on GitHub.
-2. Use `gh pr review` with:
-   - `--approve` if the code meets quality standards
-   - `--request-changes` with specific, actionable feedback if not
-3. Post your verdict on the originating issue.
+1. When you are the active participant of a review stage on an issue with a PR link, review the PR diff (check out locally if useful).
+2. Record your verdict on your review stage:
+   - **approved** if the code meets quality standards
+   - **changes_requested** with specific, actionable feedback if not
+3. Optionally mirror the same verdict as a GitHub PR comment for visibility.
 
 ## Rules
 
@@ -27,3 +27,4 @@ You review PRs for correctness, security, code quality, and simplicity. You are
 - "Looks good" is not a review. Be specific about what you verified.
 - Block on correctness, security, and clear bugs. Suggest on style and optimization.
 - If a PR is too large to review effectively, request it be split.
+- Your review stage verdict is the governance signal. Do not block only because GitHub rejects formal review submission from the shared PR-author credential — GitHub-native approval is optional unless a distinct non-author reviewer credential is explicitly available.

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

@@ -14,12 +14,12 @@ You review PRs for infrastructure impact, performance, security, and operational
 
 ## How to Review
 
-1. When @-mentioned on an issue with a PR link, review the PR on GitHub.
-2. Focus only on infrastructure and operational concerns — leave business logic to Code Reviewer.
-3. Post your review using `gh pr review` with:
-   - `--approve` if operationally sound
-   - `--request-changes` with specific concerns if not
-4. Post your verdict on the originating issue.
+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:
+   - **approved** if operationally sound
+   - **changes_requested** with specific concerns if not
+4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
 
 ## Rules
 

package/templates/modules/pr-review/agents/engineer/skills/pr-workflow.md

@@ -9,16 +9,21 @@ When this skill is active, you work in feature branches and open PRs instead of
 3. Make your changes, commit with Conventional Commits format
 4. Push branch: `git push -u origin <branch-name>`
 5. Open PR: `gh pr create --title "<type>: <description>" --body "<template>"`
-6. Set originating issue to `in_review`
-7. @-mention @Code Reviewer and @Product Owner on the issue with the PR link (also @UI Designer, @UX Researcher, @QA, @DevOps if present and relevant)
-8. Wait for reviews
-9. When Code Reviewer and Product Owner both approve (and no domain blockers from other reviewers): `gh pr merge <number> --merge`
-10. Set issue to `done`
+6. Set the originating issue's `executionPolicy` to gate the merge on review:
+   - One `review` stage with the **Code Reviewer** as participant (always).
+   - Additional `review` stages for any relevant domain reviewer that exists in the team (UI Designer for UI diffs, UX Researcher for flow changes, QA for logic/test-sensitive changes, DevOps for infra/deploy/dependency changes).
+   - A final `approval` stage with the **Product Owner** as participant (always).
+   - Resolve each role to its agentId first (look up active agents), then set the policy on the issue. Include the PR link in an issue comment so reviewers can find it.
+7. Move the originating issue to `in_review`.
+8. Wait for the issue to clear its stages. Each reviewer records `approved` or `changes_requested` on their stage; verdicts may be mirrored as PR comments.
+9. When all stages are approved (no `changes_requested` outstanding): `gh pr merge <number> --merge`, then set the issue to `done`.
 
 ## Rules
 
 - Never commit directly to main (except typos/comment-only/doc fixes with issue reference).
 - One PR per issue. Keep changes focused.
 - Always include `Closes [PREFIX-N]` in the PR body.
-- If reviewers request changes, address them and push to the same branch.
+- If a reviewer requests changes, address them, push to the same branch, and re-request review (the stage re-runs).
 - You are the merge owner — never ask reviewers to merge.
+- Do not create separate child review issues and do not use @-mentions to request review; the executionPolicy stages are the governance signal.
+- Do not wait for GitHub-native approving reviews when all agents share the same GitHub credential; GitHub rejects self-approval. The Paperclip executionPolicy stages are the required signal unless a separate non-author GitHub reviewer credential is explicitly available.

package/templates/modules/pr-review/agents/product-owner/skills/product-review.md

@@ -1,6 +1,6 @@
 # Skill: Product Review
 
-You review PRs for intent alignment, scope discipline, and acceptance criteria. You are a required reviewer — your approval is needed before any PR can be merged.
+You review PRs for intent alignment, scope discipline, and acceptance criteria. You are the final approver — you are the participant of the `approval` stage on the PR's issue, and your sign-off is the last gate before merge.
 
 ## Review Checklist
 
@@ -13,11 +13,11 @@ You review PRs for intent alignment, scope discipline, and acceptance criteria.
 
 ## How to Review
 
-1. When @-mentioned on an issue with a PR link, review the PR on GitHub.
-2. Post your review as a PR comment with:
-   - **Approve** if the change meets product requirements
-   - **Request changes** with specific feedback tied to acceptance criteria
-3. Post your verdict on the originating issue.
+1. When you are the active participant of the approval stage on an issue with a PR link, review the PR against the originating issue.
+2. Record your verdict on your approval stage:
+   - **approved** if the change meets product requirements
+   - **changes_requested** with specific feedback tied to acceptance criteria
+3. Optionally mirror the same verdict as a GitHub PR comment for visibility.
 
 ## Rules
 
@@ -25,3 +25,4 @@ You review PRs for intent alignment, scope discipline, and acceptance criteria.
 - Every PR should trace back to an issue. If it doesn't, ask why.
 - Reject scope creep firmly but constructively — suggest filing a separate issue.
 - If acceptance criteria are ambiguous, clarify them before approving.
+- Your approval stage verdict is the final governance signal. Do not block only because GitHub rejects formal review submission from the shared PR-author credential — GitHub-native approval is optional unless a distinct non-author reviewer credential is explicitly available.

package/templates/modules/pr-review/agents/qa/skills/qa-review.md

@@ -14,12 +14,12 @@ You review PRs for test coverage, edge cases, and regression risk. When a PR cha
 
 ## How to Review
 
-1. When @-mentioned on an issue with a PR link, review the PR on GitHub.
-2. Focus only on quality and test coverage — leave code style to Code Reviewer and UX to the researcher.
-3. Post your review using `gh pr review` with:
-   - `--approve` if quality is adequate
-   - `--request-changes` with specific gaps and suggested test cases if not
-4. Post your verdict on the originating issue.
+1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
+2. Focus on test coverage, regression risk, and validation strategy.
+3. Record your verdict on your review stage:
+   - **approved** if quality is adequate
+   - **changes_requested** with specific gaps and suggested test cases if not
+4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
 
 ## Rules
 

package/templates/modules/pr-review/agents/ui-designer/skills/design-review.md

@@ -14,12 +14,12 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 ## How to Review
 
-1. When @-mentioned on an issue with a PR link, review the PR on GitHub.
-2. Focus only on design and visual concerns — leave code logic to Code Reviewer.
-3. Post your review using `gh pr review` with:
-   - `--approve` if visually sound
-   - `--request-changes` with specific, actionable feedback if not
-4. Post your verdict on the originating issue.
+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 visual/design concerns — leave code logic to Code Reviewer and product scope to Product Owner.
+3. Record your verdict on your review stage:
+   - **approved** if visually sound
+   - **changes_requested** with specific, actionable feedback if not
+4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
 
 ## Rules