@starlein/paperclip-plugin-company-wizard 0.4.13 → 0.4.17

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

@@ -5,7 +5,7 @@ You own the company vision. Refine the initial goal into a strategic foundation
 ## Vision Workshop Process
 
 1. Review the company goal and any existing context (market analysis, team composition)
-2. Define and document in `docs/VISION.md`:
+2. Define and document in `../../docs/VISION.md`:
    - **Vision statement**: One sentence describing the desired future state
    - **Mission**: How the company achieves that vision
    - **Success metrics**: 3-5 measurable KPIs with target values and timeframes

package/templates/modules/vision-workshop/agents/ux-researcher/skills/vision-workshop.md

@@ -10,7 +10,7 @@ Coordinate with the CEO on the vision by providing:
 - **Metrics reality check**: Propose user-centered KPIs (retention, task completion, satisfaction)
 - **Non-goals validation**: Are we correctly excluding things users don't need?
 
-Document your research inputs in `docs/VISION.md` under a `## User Research Inputs` section.
+Document your research inputs in `../../docs/VISION.md` under a `## User Research Inputs` section.
 
 ## Rules
 

package/templates/modules/vision-workshop/module.meta.json

@@ -6,7 +6,7 @@
     {
       "title": "Define company vision, success metrics, and strategic milestones",
       "assignTo": "ceo",
-      "description": "Refine the company goal into a clear vision statement, define measurable success metrics, and establish strategic milestones. Document in docs/VISION.md. This becomes the north star for all downstream planning."
+      "description": "Refine the company goal into a clear vision statement, define measurable success metrics, and establish strategic milestones. Document in ../../docs/VISION.md. This becomes the north star for all downstream planning."
     }
   ]
 }

package/templates/modules/website-relaunch/agents/ui-designer/skills/site-audit.md

@@ -54,7 +54,7 @@ Note which visual patterns from the current site should be preserved vs. replace
 
 ## Output
 
-Write the complete audit to `docs/SITE-AUDIT.md` with sections:
+Write the complete audit to `../../docs/SITE-AUDIT.md` with sections:
 1. Page Inventory (table of all URLs with page type and status)
 2. Visual Design Patterns (current color palette, typography, component library)
 3. Content Assessment (quality, structure, and brand voice per page)

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

@@ -28,25 +28,25 @@
   "issues": [
     {
       "title": "Technical site audit",
-      "description": "Crawl the current website and document the technical baseline:\n- Complete page inventory (every URL, status codes)\n- Navigation structure and sitemap\n- Content types per page (text, images, videos, downloads)\n- Tech stack and hosting (framework, CMS, CDN, response headers)\n- SEO baseline (meta tags, structured data, canonical URLs, robots.txt, sitemap.xml)\n- Analytics and tracking scripts\n- Performance baseline (page weight, render-blocking resources)\n\nUse WebFetch or Chrome to access each page. Output: `docs/SITE-AUDIT.md`.",
+      "description": "Crawl the current website and document the technical baseline:\n- Complete page inventory (every URL, status codes)\n- Navigation structure and sitemap\n- Content types per page (text, images, videos, downloads)\n- Tech stack and hosting (framework, CMS, CDN, response headers)\n- SEO baseline (meta tags, structured data, canonical URLs, robots.txt, sitemap.xml)\n- Analytics and tracking scripts\n- Performance baseline (page weight, render-blocking resources)\n\nUse WebFetch or Chrome to access each page. Output: `../../docs/SITE-AUDIT.md`.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Visual and UX audit of current website",
-      "description": "Audit the current website from a design and user experience perspective. Use Chrome to browse the site visually. Follow the `site-audit` skill.\n\nFor each page type, document:\n- **Layout patterns** — grid structure, content zones, visual hierarchy\n- **Design tokens in use** — colors, typography, spacing, component patterns\n- **Content quality** — is copy clear, current, and on-brand? Flag outdated or placeholder content\n- **UX observations** — navigation intuitiveness, user flows, friction points, dead ends\n- **Accessibility** — heading hierarchy, image alt text, color contrast (visual estimate)\n\nFor each page, recommend: **keep** (design is strong), **redesign** (layout needs rethinking), **rewrite** (content is outdated), **merge**, or **drop**.\n\nAppend findings to `docs/SITE-AUDIT.md` under a 'Visual Design & UX' section, or create `docs/DESIGN-AUDIT.md` if the technical audit is already complete.",
+      "description": "Audit the current website from a design and user experience perspective. Use Chrome to browse the site visually. Follow the `site-audit` skill.\n\nFor each page type, document:\n- **Layout patterns** — grid structure, content zones, visual hierarchy\n- **Design tokens in use** — colors, typography, spacing, component patterns\n- **Content quality** — is copy clear, current, and on-brand? Flag outdated or placeholder content\n- **UX observations** — navigation intuitiveness, user flows, friction points, dead ends\n- **Accessibility** — heading hierarchy, image alt text, color contrast (visual estimate)\n\nFor each page, recommend: **keep** (design is strong), **redesign** (layout needs rethinking), **rewrite** (content is outdated), **merge**, or **drop**.\n\nAppend findings to `../../docs/SITE-AUDIT.md` under a 'Visual Design & UX' section, or create `../../docs/DESIGN-AUDIT.md` if the technical audit is already complete.",
       "priority": "high",
       "assignTo": "ui-designer"
     },
     {
       "title": "Content audit of current website",
-      "description": "Crawl every page of the current website and audit the existing content to inform the redesign:\n\nFor each page, document:\n- **Content type** — hero copy, body text, testimonials, FAQs, CTAs, legal, blog posts\n- **Key messages** — what is the page trying to communicate? What value propositions are present?\n- **Content quality** — is the copy clear, current, and on-brand? Flag outdated, placeholder, or thin content\n- **Media assets** — images, videos, downloads — note which are reusable vs need replacement\n- **SEO content** — headings, meta descriptions, alt text — what's working, what's missing\n- **Gaps** — messaging that should exist but doesn't (e.g., missing social proof, no pricing clarity)\n\nFor each page, recommend a migration strategy:\n- **Keep** — content is strong, migrate as-is into the new design\n- **Rewrite** — message is right but copy needs updating for the new design/voice\n- **Merge** — overlapping content across pages, consolidate\n- **Drop** — no longer relevant, redirect or remove\n\nOutput: `docs/CONTENT-AUDIT.md` — this is a key input for the design handoff and content migration milestones.",
+      "description": "Crawl every page of the current website and audit the existing content to inform the redesign:\n\nFor each page, document:\n- **Content type** — hero copy, body text, testimonials, FAQs, CTAs, legal, blog posts\n- **Key messages** — what is the page trying to communicate? What value propositions are present?\n- **Content quality** — is the copy clear, current, and on-brand? Flag outdated, placeholder, or thin content\n- **Media assets** — images, videos, downloads — note which are reusable vs need replacement\n- **SEO content** — headings, meta descriptions, alt text — what's working, what's missing\n- **Gaps** — messaging that should exist but doesn't (e.g., missing social proof, no pricing clarity)\n\nFor each page, recommend a migration strategy:\n- **Keep** — content is strong, migrate as-is into the new design\n- **Rewrite** — message is right but copy needs updating for the new design/voice\n- **Merge** — overlapping content across pages, consolidate\n- **Drop** — no longer relevant, redirect or remove\n\nOutput: `../../docs/CONTENT-AUDIT.md` — this is a key input for the design handoff and content migration milestones.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Create content inventory spreadsheet",
-      "description": "Based on the site audit and content review, create a structured content inventory:\n- Page URL, title, word count, images, last updated\n- Content status from review (keep / rewrite / merge / drop)\n- Content owner (if identifiable)\n- Migration priority: critical (homepage, key landing pages) vs secondary\n\nOutput: `docs/CONTENT-INVENTORY.md`.",
+      "description": "Based on the site audit and content review, create a structured content inventory:\n- Page URL, title, word count, images, last updated\n- Content status from review (keep / rewrite / merge / drop)\n- Content owner (if identifiable)\n- Migration priority: critical (homepage, key landing pages) vs secondary\n\nOutput: `../../docs/CONTENT-INVENTORY.md`.",
       "priority": "high",
       "assignTo": "ceo"
     },
@@ -58,13 +58,13 @@
     },
     {
       "title": "Analyze design assets and create design spec",
-      "description": "Process all design files in the `designs/` directory. Follow the `design-ingestion` skill for the full process.\n\n**How to read design files:**\n- **PDFs:** Use the Read tool with the `pages` parameter (e.g., pages 1–5, then 6–10) to view each page visually. Do NOT use text extraction as primary method — design PDFs are visual artifacts.\n- **PNG/SVG/JPG:** Use the Read tool directly to view each image.\n- **Fallback for precise values:** Use `markitdown` or `docling` (install via pip) to supplement visual analysis with extracted metadata. Use `pdffonts` for embedded font names.\n\n**Extract:**\n1. Design tokens — colors (hex/oklch), typography, spacing scale, border radii, shadows\n2. Component inventory — recurring UI components\n3. Page layouts — grid system, responsive breakpoints\n4. Asset catalog — images, icons, illustrations\n\nOutput: `docs/DESIGN-SPEC.md` with all extracted tokens, components, and layouts.",
+      "description": "Process all design files in the `designs/` directory. Follow the `design-ingestion` skill for the full process.\n\n**How to read design files:**\n- **PDFs:** Use the Read tool with the `pages` parameter (e.g., pages 1–5, then 6–10) to view each page visually. Do NOT use text extraction as primary method — design PDFs are visual artifacts.\n- **PNG/SVG/JPG:** Use the Read tool directly to view each image.\n- **Fallback for precise values:** Use `markitdown` or `docling` (install via pip) to supplement visual analysis with extracted metadata. Use `pdffonts` for embedded font names.\n\n**Extract:**\n1. Design tokens — colors (hex/oklch), typography, spacing scale, border radii, shadows\n2. Component inventory — recurring UI components\n3. Page layouts — grid system, responsive breakpoints\n4. Asset catalog — images, icons, illustrations\n\nOutput: `../../docs/DESIGN-SPEC.md` with all extracted tokens, components, and layouts.",
       "priority": "critical",
       "assignTo": "engineer"
     },
     {
       "title": "Implement core page layouts",
-      "description": "Configure the project for the new design, then build the primary page templates:\n\n**Project setup:**\n- CSS/styling approach (Tailwind, CSS modules, etc.) configured with design tokens from `docs/DESIGN-SPEC.md`\n- Component library structure\n- Framework configuration matching design spec requirements\n\n**Core pages:**\n- Homepage\n- Key landing pages\n- Standard content page layout\n- Navigation (header, footer, mobile menu)\n\nApply design tokens (colors, typography, spacing) from the spec. Ensure responsive behavior matches the design breakpoints.",
+      "description": "Configure the project for the new design, then build the primary page templates:\n\n**Project setup:**\n- CSS/styling approach (Tailwind, CSS modules, etc.) configured with design tokens from `../../docs/DESIGN-SPEC.md`\n- Component library structure\n- Framework configuration matching design spec requirements\n\n**Core pages:**\n- Homepage\n- Key landing pages\n- Standard content page layout\n- Navigation (header, footer, mobile menu)\n\nApply design tokens (colors, typography, spacing) from the spec. Ensure responsive behavior matches the design breakpoints.",
       "priority": "high",
       "assignTo": "engineer"
     },
@@ -76,7 +76,7 @@
     },
     {
       "title": "Migrate content from old site",
-      "description": "Using the content inventory (`docs/CONTENT-INVENTORY.md`), migrate content to the new site:\n- Transfer text content, updating formatting for the new design\n- Download and optimize images from the old site\n- Preserve SEO-critical content (headings, meta descriptions, alt text)\n- Flag content marked for rewrite and create issues for each\n\nVerify no content is lost by cross-referencing the inventory.",
+      "description": "Using the content inventory (`../../docs/CONTENT-INVENTORY.md`), migrate content to the new site:\n- Transfer text content, updating formatting for the new design\n- Download and optimize images from the old site\n- Preserve SEO-critical content (headings, meta descriptions, alt text)\n- Flag content marked for rewrite and create issues for each\n\nVerify no content is lost by cross-referencing the inventory.",
       "priority": "high",
       "assignTo": "engineer"
     },

package/templates/modules/website-relaunch/skills/design-ingestion.md

@@ -102,7 +102,7 @@ For each distinct page design:
 
 ## Output
 
-Write the complete specification to `docs/DESIGN-SPEC.md` with sections:
+Write the complete specification to `../../docs/DESIGN-SPEC.md` with sections:
 1. Design Tokens (colors, typography, spacing, etc.)
 2. Component Library (each component with description and states)
 3. Page Layouts (each page with structure and responsive notes)

package/templates/modules/website-relaunch/skills/site-audit.md

@@ -43,7 +43,7 @@ Flag any external integrations (forms, payment, chat widgets) that need replacem
 
 ## Output
 
-Write the complete audit to `docs/SITE-AUDIT.md` with sections:
+Write the complete audit to `../../docs/SITE-AUDIT.md` with sections:
 1. Page Inventory (table of all URLs with metadata)
 2. Site Structure (navigation, information architecture)
 3. Technical Stack (framework, hosting, integrations)

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

@@ -59,19 +59,19 @@
   "issues": [
     {
       "title": "Create Game Design Document",
-      "description": "Define the game's complete design. Follow the GDD template in docs/gdd-template.md.\n\nMust include: concept pitch, core mechanic (input → action → feedback → consequence), three-layer game loop, progression system, win/lose conditions, controls, art direction, audio direction, and all tuning parameters.\n\nOutput: docs/GDD.md",
+      "description": "Define the game's complete design. Follow the GDD template in ../../docs/gdd-template.md.\n\nMust include: concept pitch, core mechanic (input → action → feedback → consequence), three-layer game loop, progression system, win/lose conditions, controls, art direction, audio direction, and all tuning parameters.\n\nOutput: ../../docs/GDD.md",
       "priority": "critical",
       "assignTo": "game-designer"
     },
     {
       "title": "Choose game engine and set up project",
-      "description": "Based on the GDD requirements (genre, platform, art style), evaluate and select a game engine or framework. Options to consider:\n- **Web:** Phaser, PixiJS, Three.js, Kaboom.js, vanilla Canvas/WebGL\n- **Cross-platform:** Godot, Unity, Love2D, Defold\n- **Minimal:** Custom engine if the game is simple enough\n\nSet up the project structure, build pipeline, and basic game loop scaffold. Document the choice in docs/TECH-STACK.md.",
+      "description": "Based on the GDD requirements (genre, platform, art style), evaluate and select a game engine or framework. Options to consider:\n- **Web:** Phaser, PixiJS, Three.js, Kaboom.js, vanilla Canvas/WebGL\n- **Cross-platform:** Godot, Unity, Love2D, Defold\n- **Minimal:** Custom engine if the game is simple enough\n\nSet up the project structure, build pipeline, and basic game loop scaffold. Document the choice in ../../docs/TECH-STACK.md.",
       "priority": "critical",
       "assignTo": "engineer"
     },
     {
       "title": "Define art style guide",
-      "description": "Based on the GDD art direction, create a concrete art style guide:\n- Sprite/asset dimensions and resolution\n- Color palette (exact hex values, limited palette if pixel art)\n- Color language: what colors mean in gameplay (player, enemy, pickup, hazard, background)\n- Animation conventions: frame counts, frame rates, style\n- Asset naming conventions and directory structure\n- Reference images or generated style samples\n\nOutput: docs/ART-STYLE-GUIDE.md and sample assets in assets/reference/",
+      "description": "Based on the GDD art direction, create a concrete art style guide:\n- Sprite/asset dimensions and resolution\n- Color palette (exact hex values, limited palette if pixel art)\n- Color language: what colors mean in gameplay (player, enemy, pickup, hazard, background)\n- Animation conventions: frame counts, frame rates, style\n- Asset naming conventions and directory structure\n- Reference images or generated style samples\n\nOutput: ../../docs/ART-STYLE-GUIDE.md and sample assets in assets/reference/",
       "priority": "high",
       "assignTo": "game-artist"
     },
@@ -95,7 +95,7 @@
     },
     {
       "title": "First playtest and balancing pass",
-      "description": "Play the prototype and document findings:\n- Is the core mechanic fun? Does it feel good?\n- Are controls responsive? Any input lag or awkwardness?\n- Difficulty: too easy, too hard, or unclear?\n- What's missing that would make it fun? What should be cut?\n- Tuning parameter adjustments needed\n\nOutput: docs/PLAYTEST-RESULTS.md with specific findings and recommended changes.",
+      "description": "Play the prototype and document findings:\n- Is the core mechanic fun? Does it feel good?\n- Are controls responsive? Any input lag or awkwardness?\n- Difficulty: too easy, too hard, or unclear?\n- What's missing that would make it fun? What should be cut?\n- Tuning parameter adjustments needed\n\nOutput: ../../docs/PLAYTEST-RESULTS.md with specific findings and recommended changes.",
       "priority": "high",
       "assignTo": "game-designer"
     },
@@ -113,7 +113,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.",
+      "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": "level-designer"
     },
@@ -131,7 +131,7 @@
     },
     {
       "title": "Final balancing and bug fixing",
-      "description": "Play through the entire game and:\n- Adjust difficulty curve based on full playthrough\n- Fix all gameplay bugs\n- Tune all parameters for satisfying progression\n- Verify no soft-locks or unwinnable states\n- Check edge cases: max score, empty inventory, rapid inputs\n\nUpdate docs/GDD.md with final tuning values.",
+      "description": "Play through the entire game and:\n- Adjust difficulty curve based on full playthrough\n- Fix all gameplay bugs\n- Tune all parameters for satisfying progression\n- Verify no soft-locks or unwinnable states\n- Check edge cases: max score, empty inventory, rapid inputs\n\nUpdate ../../docs/GDD.md with final tuning values.",
       "priority": "high",
       "assignTo": "game-designer"
     },

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

@@ -29,7 +29,7 @@
           "id": "repo-onboarding",
           "title": "Repo Onboarding",
           "level": "team",
-          "description": "Understand the existing codebase and document its current state. Done when docs/CODEBASE-AUDIT.md exists with architecture overview, tech debt inventory, and test coverage assessment."
+          "description": "Understand the existing codebase and document its current state. Done when ../../docs/CODEBASE-AUDIT.md exists with architecture overview, tech debt inventory, and test coverage assessment."
         },
         {
           "id": "process-setup",
@@ -55,19 +55,19 @@
   "issues": [
     {
       "title": "Audit codebase and document architecture",
-      "description": "Read the existing codebase, map architecture, identify tech debt hotspots and test coverage gaps. Document in docs/CODEBASE-AUDIT.md.",
+      "description": "Read the existing codebase, map architecture, identify tech debt hotspots and test coverage gaps. Document in ../../docs/CODEBASE-AUDIT.md.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Run initial dependency audit",
-      "description": "Audit all dependencies for outdated versions and known vulnerabilities. Document in docs/DEPENDENCY-AUDIT.md. Apply safe patch updates.",
+      "description": "Audit all dependencies for outdated versions and known vulnerabilities. Document in ../../docs/DEPENDENCY-AUDIT.md. Apply safe patch updates.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "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.",
+      "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"
     },
@@ -79,7 +79,7 @@
     },
     {
       "title": "Document or establish release process",
-      "description": "Review current release workflow. If none exists, establish semver + changelog. Document in docs/RELEASE-PROCESS.md.",
+      "description": "Review current release workflow. If none exists, establish semver + changelog. Document in ../../docs/RELEASE-PROCESS.md.",
       "priority": "medium",
       "assignTo": "engineer"
     },

package/templates/roles/cmo/AGENTS.md

@@ -21,7 +21,7 @@ You report to the CEO.
 
 ## Collaboration and Handoffs
 
-- Brand guidelines or messaging changes → notify the UI Designer and CEO; update `docs/BRAND-IDENTITY.md`.
+- Brand guidelines or messaging changes → notify the UI Designer and CEO; update `../../docs/BRAND-IDENTITY.md`.
 - Launch plans requiring engineering work → create issues for the engineer with clear acceptance criteria and timeline.
 - Market analysis or competitive intel findings → share summary with CEO and Product Owner via issue comment.
 - Content needing legal review or board approval → escalate before publishing.

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

@@ -17,7 +17,7 @@ You report to the CEO.
    - **Simplicity**: Is there unnecessary complexity? Could it be simpler?
 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. **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. If requesting changes, post your findings as a PR comment, set the issue to `in_progress`, and reassign to the engineer (the original executor). Do not record `approved` until the concern is resolved.
+8. **When the pr-review module is active**, you are the non-author merge gate: satisfy the hard verification gate — **always run and paste your own lint/test/build output** (authoritative); a green CI is an *additional* requirement only when this company runs its own CI/CD (`ci-cd` module active). A pre-existing repo check the company never configured is advisory, not a gate — never block a merge solely on it. Then 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. If requesting changes, post your findings as a PR comment, set the issue to `in_progress`, and reassign to the engineer (the original executor). Do not record `approved` until the concern is resolved.
 
 ## Principles
 

package/templates/roles/cto/AGENTS.md

@@ -18,19 +18,19 @@ You report to the CEO.
 - Claim one issue at a time. Set it to `in_progress` when starting.
 - Your primary work products are decisions, documents, and unblocking — not direct code changes. Prefer creating well-scoped issues for engineers over editing code yourself.
 - If a technical decision has significant cost or risk implications, bring it to the CEO before acting.
-- Never approve a technology choice that contradicts the current `docs/TECH-STACK.md` without explicitly updating the document and creating a migration issue.
+- Never approve a technology choice that contradicts the current `../../docs/TECH-STACK.md` without explicitly updating the document and creating a migration issue.
 
 ## Collaboration and Handoffs
 
-- Architecture decisions → document in `docs/ARCHITECTURE.md`; create follow-up issues for the engineer to implement.
-- Tech stack changes → update `docs/TECH-STACK.md` and notify affected agents via issue comment.
+- Architecture decisions → document in `../../docs/ARCHITECTURE.md`; create follow-up issues for the engineer to implement.
+- Tech stack changes → update `../../docs/TECH-STACK.md` and notify affected agents via issue comment.
 - Engineer is blocked on a technical decision → claim the blocking issue, make the decision with a rationale comment, then reassign to the engineer.
 - Security-relevant architecture decisions → loop in the Security Engineer before closing.
 - Hiring or team structure changes → escalate to CEO; the CTO does not unilaterally hire.
 
 ## Done Bar
 
-- Decision is documented (in `docs/ARCHITECTURE.md`, `docs/TECH-STACK.md`, or an issue comment as appropriate).
+- Decision is documented (in `../../docs/ARCHITECTURE.md`, `../../docs/TECH-STACK.md`, or an issue comment as appropriate).
 - Relevant agents have been notified of anything they need to act on.
 - If the decision created follow-up work, at least one follow-up issue exists and is assigned.
 

package/templates/roles/devops/AGENTS.md

@@ -23,7 +23,7 @@ You report to the CEO.
 
 - Infrastructure changes that expose new security surfaces → loop in the Security Engineer before closing the issue.
 - Pipeline failures blocking engineer deployments → escalate to CEO immediately with the failure log.
-- New services or environments added → update `docs/CI-CD.md` and `docs/MONITORING.md` so engineers know how to deploy and observe.
+- New services or environments added → update `../../docs/CI-CD.md` and `../../docs/MONITORING.md` so engineers know how to deploy and observe.
 - If a change requires engineer-side config updates (env vars, secrets, build commands), create a follow-up issue assigned to the engineer before closing your issue.
 
 ## Done Bar

package/templates/roles/engineer/HEARTBEAT.md

@@ -35,7 +35,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 - Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
 - Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
 - Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
-- Before moving work to `in_review`, verify a review path exists. If a Code Reviewer is on the team, set the `executionPolicy` stages (at least one non-author stage) **before** moving to `in_review` — an `in_review` issue with `executionPolicy: null` has no eligible participant and stalls forever (`422 No eligible approval participant`). The **first** stage must be a non-author stage: never list yourself (the issue's assignee/executor — whoever did the work) as a participant in any stage. The runtime excludes the original executor from every stage, so a first stage listing only you has no eligible participant and the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) — even if later stages have non-author participants. After moving to `in_review`, `GET /api/issues/{id}` (the list endpoint omits `executionPolicy`) and confirm `stages[0].participants` is not just you; if it is, `PATCH /api/issues/{id}` `{"executionPolicy":null}` to return to `in_progress`, then re-set stages with a non-author first stage. If no Code Reviewer is on the team, do not move to `in_review` at all: open the PR and merge it yourself via `gh pr merge <N> --merge` in the same heartbeat (self-merge path), then mark `done`. If you find an issue already `in_review` with `executionPolicy: null` or an author-only first stage, it is a stall — recover by nulling the policy (`PATCH {"executionPolicy":null}` → `in_progress`), then either set `executionPolicy` stages with a non-author first stage (Code Reviewer present) or self-merge the PR (no Code Reviewer). Never leave finished work in `in_review` assigned to yourself.
+- **Review path applies only when the pr-review module is active.** Without pr-review there is no PR review flow and no `in_review` step — you follow the Direct-to-Base Flow in `skills/git-workflow.md` (verify locally, commit, push to the base ref; open a PR only if branch protection rejects the direct push). The rest of this bullet applies only when pr-review is active. Before moving work to `in_review`, verify a review path exists. If a Code Reviewer is on the team, set the `executionPolicy` stages (at least one non-author stage) **before** moving to `in_review` — an `in_review` issue with `executionPolicy: null` has no eligible participant and stalls forever (`422 No eligible approval participant`). The **first** stage must be a non-author stage: never list yourself (the issue's assignee/executor — whoever did the work) as a participant in any stage. The runtime excludes the original executor from every stage, so a first stage listing only you has no eligible participant and the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) — even if later stages have non-author participants. After moving to `in_review`, `GET /api/issues/{id}` (the list endpoint omits `executionPolicy`) and confirm `stages[0].participants` is not just you; if it is, `PATCH /api/issues/{id}` `{"executionPolicy":null}` to return to `in_progress`, then re-set stages with a non-author first stage. If no Code Reviewer is on the team, do not move to `in_review` at all: open the PR and merge it yourself via `gh pr merge <N> --merge` in the same heartbeat (self-merge path), then mark `done`. If you find an issue already `in_review` with `executionPolicy: null` or an author-only first stage, it is a stall — recover by nulling the policy (`PATCH {"executionPolicy":null}` → `in_progress`), then either set `executionPolicy` stages with a non-author first stage (Code Reviewer present) or self-merge the PR (no Code Reviewer). Never leave finished work in `in_review` assigned to yourself.
 
 ## 6. Exit
 

package/templates/roles/ux-researcher/AGENTS.md

@@ -28,7 +28,7 @@ You report to the CEO.
 
 ## Done Bar
 
-- Research output is documented in `docs/` (e.g., `docs/USER-RESEARCH.md`, `docs/USER-TESTING.md`) or the appropriate template file.
+- Research output is documented in `docs/` (e.g., `../../docs/USER-RESEARCH.md`, `../../docs/USER-TESTING.md`) or the appropriate template file.
 - Key findings have been communicated to at least the Product Owner (via issue comment or follow-up issue).
 - Recommendations are concrete and actionable — not just observations.