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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.13",
+  "version": "0.4.17",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
   "repository": "https://github.com/starlein/paperclip-plugin-company-wizard",

package/templates/bootstrap-instructions.md

@@ -31,7 +31,8 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 
 **Review workflow guardrail:**
 
-- Required PR reviews use the issue's `executionPolicy` review/approval stages, not @-mentions and not separate child review issues. When an engineer opens a PR, set the implementation issue to `in_review` with the resolved execution policy: QA review when present, Security review only for security-relevant changes, Product Owner approval for scope/intent, and a final Code Reviewer merge gate after verification is recorded. **Never list the issue's executor/author as a participant in any stage** — Paperclip excludes the original executor from review/approval, so a stage whose only participant is the author stalls the issue in `in_review` (`422 No eligible approval participant`); the merge gate is therefore a non-author (the Code Reviewer), not the engineer who wrote the code. Each active participant records their decision through the normal issue update route (`approved` by PATCHing toward `done`, `changes_requested` by PATCHing back to `in_progress`), which is the issue-level reviewed/approved audit trail (`reviewed_by` / `approved_by` metadata where Paperclip exposes it). The Code Reviewer merge gate must verify the PR base against the project/worktree base ref shown in `heartbeat-context`, merge before approving, close/archive any isolated worktree when one exists and close-readiness allows it, and only then record final approval. Follow `docs/pr-conventions.md` when the PR review module is active.
+- Required PR reviews use the issue's `executionPolicy` review/approval stages, not @-mentions and not separate child review issues. When an engineer opens a PR, set the implementation issue to `in_review` with the resolved execution policy: QA review when present, Security review only for security-relevant changes, Product Owner approval for scope/intent, and a final Code Reviewer merge gate after verification is recorded. **Never list the issue's executor/author as a participant in any stage** — Paperclip excludes the original executor from review/approval, so a stage whose only participant is the author stalls the issue in `in_review` (`422 No eligible approval participant`); the merge gate is therefore a non-author (the Code Reviewer), not the engineer who wrote the code. Each active participant records their decision through the normal issue update route (`approved` by PATCHing toward `done`, `changes_requested` by PATCHing back to `in_progress`), which is the issue-level reviewed/approved audit trail (`reviewed_by` / `approved_by` metadata where Paperclip exposes it). The Code Reviewer merge gate must verify the PR base against the project/worktree base ref shown in `heartbeat-context`, merge before approving, close/archive any isolated worktree when one exists and close-readiness allows it, and only then record final approval. Follow `../../docs/pr-conventions.md` when the PR review module is active.
+- **One PR ⇒ one issue ⇒ its policy stages. Never fan a single PR out into separate per-role issues linked by `blocks`, and never model the merge as a standalone "Code review and merge PR #N" issue that is `blockedBy` the review issues.** That fan-out strands the merge: once the review issues reach `done`, Paperclip does not reliably re-wake the blocked merge issue (worker heartbeats are off, and the liveness watchdog ignores a `blocked` issue whose blockers are all `done`), so the PR is never merged even when it is green and approved. The review/approval/merge-gate steps are **stages on the one implementation issue** that advance in place — the merge gate is the last stage on that same issue, not a separate blocked issue. If you inherit a stranded fan-out, the CEO stall-detection recovers it (*Stranded blocked*), but do not create it.
 
 **Secrets guardrail:**
 

package/templates/modules/accessibility/agents/engineer/skills/accessibility-audit.fallback.md

@@ -4,11 +4,11 @@ The QA Engineer and UI Designer own accessibility auditing above you. You are th
 
 ## Accessibility Audit (Fallback)
 
-1. If no `docs/ACCESSIBILITY-AUDIT.md` exists and nobody has started:
+1. If no `../../docs/ACCESSIBILITY-AUDIT.md` exists and nobody has started:
    - Check semantic HTML usage in key pages/components
    - Verify form labels and ARIA attributes are correct
    - Run automated accessibility checks if tooling is available
-   - Document in `docs/ACCESSIBILITY-AUDIT.md`
+   - Document in `../../docs/ACCESSIBILITY-AUDIT.md`
    - Tag QA or UI Designer to expand the audit
 2. If QA or UI Designer is active, skip this entirely.
 

package/templates/modules/accessibility/agents/ui-designer/skills/accessibility-audit.fallback.md

@@ -4,11 +4,11 @@ The QA Engineer owns accessibility auditing above you. You are the fallback —
 
 ## Accessibility Audit (Fallback)
 
-1. If no `docs/ACCESSIBILITY-AUDIT.md` exists and QA hasn't started:
+1. If no `../../docs/ACCESSIBILITY-AUDIT.md` exists and QA hasn't started:
    - Review color contrast and visual accessibility of the design system
    - Check that focus states are designed for all interactive components
    - Verify the design system includes accessible component patterns
-   - Document in `docs/ACCESSIBILITY-AUDIT.md`
+   - Document in `../../docs/ACCESSIBILITY-AUDIT.md`
    - Tag QA to expand with keyboard and screen reader testing
 2. If QA is active, skip this entirely.
 

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

@@ -16,7 +16,7 @@
     {
       "title": "Conduct initial accessibility audit",
       "assignTo": "capability:accessibility-audit",
-      "description": "Audit the project for WCAG 2.2 compliance: check semantic HTML, keyboard navigation, color contrast, ARIA usage, and screen reader compatibility. Document findings and remediation plan in docs/ACCESSIBILITY-AUDIT.md."
+      "description": "Audit the project for WCAG 2.2 compliance: check semantic HTML, keyboard navigation, color contrast, ARIA usage, and screen reader compatibility. Document findings and remediation plan in ../../docs/ACCESSIBILITY-AUDIT.md."
     }
   ]
 }

package/templates/modules/accessibility/skills/accessibility-audit.bar.md

@@ -2,7 +2,7 @@
 
 A good accessibility audit:
 
-- A `docs/ACCESSIBILITY-AUDIT.md` covering WCAG 2.2 AA across: semantic HTML, keyboard navigation, colour contrast, ARIA usage, images/media, forms, and zoom/responsive behaviour.
+- A `../../docs/ACCESSIBILITY-AUDIT.md` covering WCAG 2.2 AA across: semantic HTML, keyboard navigation, colour contrast, ARIA usage, images/media, forms, and zoom/responsive behaviour.
 - Each finding has a severity (Critical / Major / Minor), a specific location, and a concrete remediation — Critical and Major findings have follow-up issues created.
 
 Not done:

package/templates/modules/accessibility/skills/accessibility-audit.md

@@ -5,7 +5,7 @@ You own accessibility compliance. This ensures the product is usable by everyone
 ## Accessibility Audit Process
 
 1. Review the project for WCAG 2.2 compliance at Level AA (minimum).
-2. Check and document in `docs/ACCESSIBILITY-AUDIT.md`:
+2. Check and document in `../../docs/ACCESSIBILITY-AUDIT.md`:
    - **Semantic HTML**: Correct heading hierarchy, landmark regions, form labels
    - **Keyboard navigation**: All interactive elements focusable and operable, logical tab order, visible focus indicators
    - **Color and contrast**: Minimum 4.5:1 for normal text, 3:1 for large text, no color-only information

package/templates/modules/architecture-plan/agents/ceo/skills/architecture-plan.bar.md

@@ -1,11 +1,11 @@
 ## Architecture Plan — Done Bar (CEO Fallback)
 
 **Done:**
-- `docs/ARCHITECTURE.md` exists with at least: a brief system overview (what the system does, its main components), the primary data flows, and a clear note that this is a CEO-generated placeholder pending engineer review.
+- `../../docs/ARCHITECTURE.md` exists with at least: a brief system overview (what the system does, its main components), the primary data flows, and a clear note that this is a CEO-generated placeholder pending engineer review.
 - A follow-up issue exists, assigned to an engineer or the architecture-plan capability, to complete the full architecture document.
 
 **Not done:**
-- No `docs/ARCHITECTURE.md` exists at all.
+- No `../../docs/ARCHITECTURE.md` exists at all.
 - The document exists but contains no actionable overview (placeholder text only).
 - No follow-up issue was created for the engineer to complete the work.
 

package/templates/modules/architecture-plan/agents/ceo/skills/architecture-plan.fallback.md

@@ -4,9 +4,9 @@ The Engineer primarily owns system architecture. You are the fallback — step i
 
 ## Architecture Plan (Fallback)
 
-1. If no `docs/ARCHITECTURE.md` exists and no engineer has started:
+1. If no `../../docs/ARCHITECTURE.md` exists and no engineer has started:
    - Sketch a minimal architecture based on the tech stack and project goals
-   - Document in `docs/ARCHITECTURE.md`
+   - Document in `../../docs/ARCHITECTURE.md`
    - Create an issue for the engineer to review and expand
 2. If an engineer is active, skip this entirely.
 

package/templates/modules/architecture-plan/agents/engineer/skills/design-system.fallback.md

@@ -4,10 +4,10 @@ The UI Designer primarily owns the design system. You are the fallback — set u
 
 ## Design System (Fallback)
 
-1. If no `docs/DESIGN-SYSTEM.md` exists and no UI Designer has started:
+1. If no `../../docs/DESIGN-SYSTEM.md` exists and no UI Designer has started:
    - Choose a sensible default palette (e.g., Tailwind defaults or a minimal custom set)
    - Define basic typography and spacing scales
-   - Document in `docs/DESIGN-SYSTEM.md`
+   - Document in `../../docs/DESIGN-SYSTEM.md`
    - Create an issue for a UI Designer to review and expand if one is hired later
 2. If a UI Designer is active, skip this entirely.
 

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

@@ -4,7 +4,7 @@ When the architecture plan is being created, contribute the UI/frontend perspect
 
 ## UI Architecture Contributions
 
-1. Check that `docs/ARCHITECTURE.md` exists. If it does not exist yet, the engineer's architecture-plan task has not completed — leave an issue comment ("Waiting for engineer to complete docs/ARCHITECTURE.md before adding UI layer") and do not close this issue yet. Check back on your next heartbeat.
+1. Check that `../../docs/ARCHITECTURE.md` exists. If it does not exist yet, the engineer's architecture-plan task has not completed — leave an issue comment ("Waiting for engineer to complete ../../docs/ARCHITECTURE.md before adding UI layer") and do not close this issue yet. Check back on your next heartbeat.
 
 If an Engineer is defining the architecture, coordinate with them on:
 - **Frontend component structure**: Page layout, shared components, routing
@@ -12,7 +12,7 @@ If an Engineer is defining the architecture, coordinate with them on:
 - **Asset pipeline**: Images, icons, fonts — how they're managed and optimized
 - **Responsive strategy**: How layouts adapt across breakpoints
 
-Document your UI architecture notes in `docs/ARCHITECTURE.md` under a `## UI Architecture` section.
+Document your UI architecture notes in `../../docs/ARCHITECTURE.md` under a `## UI Architecture` section.
 
 ## Rules
 

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

@@ -5,8 +5,8 @@ You own the visual design system. Establish the foundational patterns that ensur
 ## Design System Process
 
 1. Review the company goal, brand context, and target audience
-2. If `docs/BRAND-IDENTITY.md` exists, use it as the authoritative source for color palette, typography, and brand voice. Do not invent a palette that contradicts established brand identity.
-3. Define and document in `docs/DESIGN-SYSTEM.md`:
+2. If `../../docs/BRAND-IDENTITY.md` exists, use it as the authoritative source for color palette, typography, and brand voice. Do not invent a palette that contradicts established brand identity.
+3. Define and document in `../../docs/DESIGN-SYSTEM.md`:
    - **Color palette**: Primary, secondary, accent, semantic (success, error, warning), neutrals
    - **Typography**: Font families, scale (heading/body/caption sizes), weights, line heights
    - **Spacing**: Base unit and scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)

package/templates/modules/architecture-plan/module.meta.json

@@ -26,12 +26,12 @@
     {
       "title": "Design initial system architecture",
       "assignTo": "capability:architecture-plan",
-      "description": "Based on the tech stack decisions, design the system architecture: component structure, data flow, API boundaries, and deployment model. Document in docs/ARCHITECTURE.md."
+      "description": "Based on the tech stack decisions, design the system architecture: component structure, data flow, API boundaries, and deployment model. Document in ../../docs/ARCHITECTURE.md."
     },
     {
       "title": "Define design system and visual language",
       "assignTo": "capability:design-system",
-      "description": "Establish the visual foundation: color palette, typography, spacing scale, component patterns, and brand guidelines. Document in docs/DESIGN-SYSTEM.md."
+      "description": "Establish the visual foundation: color palette, typography, spacing scale, component patterns, and brand guidelines. Document in ../../docs/DESIGN-SYSTEM.md."
     }
   ]
 }

package/templates/modules/architecture-plan/skills/architecture-plan.bar.md

@@ -2,7 +2,7 @@
 
 A good architecture plan:
 
-- A `docs/ARCHITECTURE.md` with a system overview (text/ASCII component diagram), data flow through the system, API boundaries (internal and external), deployment model, and key decisions recorded in ADR style with rationale.
+- A `../../docs/ARCHITECTURE.md` with a system overview (text/ASCII component diagram), data flow through the system, API boundaries (internal and external), deployment model, and key decisions recorded in ADR style with rationale.
 - Decomposed into concrete implementation issues for foundational scaffolding so work can start incrementally.
 
 Not done:

package/templates/modules/architecture-plan/skills/architecture-plan.md

@@ -4,8 +4,8 @@ You own system architecture. Design the structure that implements the tech stack
 
 ## Architecture Planning Process
 
-1. If `docs/TECH-STACK.md` exists, review it alongside the project requirements. Otherwise, gather tech stack context from the codebase and project docs.
-2. Design and document in `docs/ARCHITECTURE.md`:
+1. If `../../docs/TECH-STACK.md` exists, review it alongside the project requirements. Otherwise, gather tech stack context from the codebase and project docs.
+2. Design and document in `../../docs/ARCHITECTURE.md`:
    - **System overview**: High-level component diagram (describe in text/ASCII)
    - **Component structure**: Modules, services, or packages and their responsibilities
    - **Data flow**: How data moves through the system

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

@@ -4,9 +4,9 @@ You are establishing the project's design system foundations when no UI Designer
 
 ## Steps
 
-1. Read `docs/TECH-STACK.md` if it exists to understand the frontend framework and styling approach.
-2. Read `docs/BRAND-IDENTITY.md` if it exists for color palette, typography, and brand direction.
-3. If `docs/DESIGN-SYSTEM.md` does not exist, create it using `docs/design-system-template.md` as a starting point.
+1. Read `../../docs/TECH-STACK.md` if it exists to understand the frontend framework and styling approach.
+2. Read `../../docs/BRAND-IDENTITY.md` if it exists for color palette, typography, and brand direction.
+3. If `../../docs/DESIGN-SYSTEM.md` does not exist, create it using `../../docs/design-system-template.md` as a starting point.
 4. Define the minimum viable token set:
    - **Colors**: primary, secondary, background, surface, text, error/warning/success. Use the brand palette if available, otherwise choose accessible defaults (WCAG AA contrast ratio ≥ 4.5:1 for text).
    - **Typography**: 2–3 font sizes (body, heading, small), font family (system stack if no brand font specified), line heights.
@@ -21,5 +21,5 @@ You are establishing the project's design system foundations when no UI Designer
 
 - Keep it practical over perfect. Consistent tokens are more valuable than a comprehensive design system.
 - Do not create visual assets (icons, illustrations) — document where placeholders should go.
-- Reference `docs/ARCHITECTURE.md` for the component hierarchy if it exists.
-- If `docs/DESIGN-SYSTEM.md` already exists (a UI Designer ran first), review it for engineering feasibility and add implementation notes — do not overwrite their work.
+- Reference `../../docs/ARCHITECTURE.md` for the component hierarchy if it exists.
+- If `../../docs/DESIGN-SYSTEM.md` already exists (a UI Designer ran first), review it for engineering feasibility and add implementation notes — do not overwrite their work.

package/templates/modules/backlog/docs/backlog-template.md

@@ -39,7 +39,7 @@ _Summary of current backlog health. Update on each heartbeat cycle._
 - **Ready assigned issues:** _(count by owner)_
 - **Unassigned todo issues:** _(count; should normally be 0 except items without a suitable owner)_
 - **In-progress issues:** _(count)_
-- **Health:** _(healthy / thin / empty / bloated — see docs/backlog-process.md)_
+- **Health:** _(healthy / thin / empty / bloated — see ../../docs/backlog-process.md)_
 
 ## Decisions Log
 

package/templates/modules/brand-identity/agents/ceo/skills/brand-identity.fallback.md

@@ -4,11 +4,11 @@ The UI Designer and CMO both own brand identity above you. You are the last-reso
 
 ## Brand Identity (Fallback)
 
-1. If no `docs/BRAND-IDENTITY.md` exists and no designer has started:
+1. If no `../../docs/BRAND-IDENTITY.md` exists and no designer has started:
    - Set up a minimal brand placeholder with basic defaults
    - Choose a neutral color palette (1 primary, 1 accent, 1 neutral)
    - Pick a safe, widely available font pairing (e.g., Inter + system serif)
-   - Document in `docs/BRAND-IDENTITY.md` and mark all choices as **provisional**
+   - Document in `../../docs/BRAND-IDENTITY.md` and mark all choices as **provisional**
    - Create an issue for the ui-designer or CMO to review and expand the brand guidelines
 2. If a ui-designer or CMO is active, skip this entirely.
 

package/templates/modules/brand-identity/agents/cmo/skills/brand-identity.fallback.md

@@ -4,11 +4,11 @@ The UI Designer primarily owns brand identity and visual guidelines. You are the
 
 ## Brand Identity (Fallback)
 
-1. If no `docs/BRAND-IDENTITY.md` exists and no designer has started:
+1. If no `../../docs/BRAND-IDENTITY.md` exists and no designer has started:
    - Define brand positioning: mission statement, target audience, key differentiators
    - Establish tone of voice and communication guidelines
    - Set up a minimal color palette and typography recommendation
-   - Document in `docs/BRAND-IDENTITY.md` and mark visual choices as **provisional**
+   - Document in `../../docs/BRAND-IDENTITY.md` and mark visual choices as **provisional**
    - Create an issue for the designer to refine visual identity
 2. If a designer is active, skip this entirely.
 

package/templates/modules/brand-identity/module.meta.json

@@ -16,7 +16,7 @@
     {
       "title": "Define brand identity and visual guidelines",
       "assignTo": "capability:brand-identity",
-      "description": "Create the brand book: logo usage, color palette, typography, iconography, and tone-of-voice guidelines. Document everything in docs/BRAND-IDENTITY.md."
+      "description": "Create the brand book: logo usage, color palette, typography, iconography, and tone-of-voice guidelines. Document everything in ../../docs/BRAND-IDENTITY.md."
     }
   ]
 }

package/templates/modules/brand-identity/skills/brand-identity.bar.md

@@ -2,7 +2,7 @@
 
 A good brand identity:
 
-- A `docs/BRAND-IDENTITY.md` with concrete values and rationale for every element: colour palette (hex/RGB values with contrast ratios), typography (typefaces, size scale, weight usage), logo usage rules (clear space, do's and don'ts), iconography style, and tone of voice.
+- A `../../docs/BRAND-IDENTITY.md` with concrete values and rationale for every element: colour palette (hex/RGB values with contrast ratios), typography (typefaces, size scale, weight usage), logo usage rules (clear space, do's and don'ts), iconography style, and tone of voice.
 - If a tech stack exists, a design tokens file (CSS custom properties or JSON) matching the chosen stack, so the identity is immediately usable in code.
 
 Not done:

package/templates/modules/brand-identity/skills/brand-identity.md

@@ -14,12 +14,12 @@ You own the company's visual identity and brand guidelines. Define a cohesive br
    - **Logo usage**: Clear space, minimum size, do's and don'ts
    - **Iconography**: Style, stroke weight, grid alignment
    - **Tone of voice**: Communication style, vocabulary, personality
-3. Document everything in `docs/BRAND-IDENTITY.md`:
-   - Use `docs/brand-identity-template.md` as a starting point
+3. Document everything in `../../docs/BRAND-IDENTITY.md`:
+   - Use `../../docs/brand-identity-template.md` as a starting point
    - Fill in all sections with concrete values and rationale
    - Include visual examples or references where possible
 4. Create initial design tokens if a tech stack exists:
-   - If `docs/TECH-STACK.md` is present, produce a tokens file (CSS custom properties or JSON) matching the chosen stack
+   - If `../../docs/TECH-STACK.md` is present, produce a tokens file (CSS custom properties or JSON) matching the chosen stack
    - Reference the design-system module if the architecture-plan module exists
 
 ## Rules

package/templates/modules/build-api/skills/api-design.bar.md

@@ -2,7 +2,7 @@
 
 A good API design:
 
-- A `docs/API-DESIGN.md` with a resource model, full endpoint inventory (method, path, auth requirement), authentication strategy, error-handling conventions (consistent error shape), and pagination approach.
+- A `../../docs/API-DESIGN.md` with a resource model, full endpoint inventory (method, path, auth requirement), authentication strategy, error-handling conventions (consistent error shape), and pagination approach.
 - Every endpoint has: description, parameter types and constraints, request/response schema, example request/response, and possible error codes — generated from source annotations (OpenAPI/Swagger), not maintained by hand.
 
 Not done:

package/templates/modules/build-api/skills/api-design.md

@@ -35,7 +35,7 @@ When designing the data model:
 
 ## Output Artifacts
 
-Document your API design decisions in `docs/API-DESIGN.md`:
+Document your API design decisions in `../../docs/API-DESIGN.md`:
 - Resource model (entities and relationships)
 - Endpoint inventory (method, path, description, auth requirement)
 - Authentication strategy

package/templates/modules/ci-cd/agents/devops/skills/ci-cd.md

@@ -15,7 +15,7 @@ You are the DevOps engineer and CI/CD is your core domain. You own the full pipe
    - Run smoke tests after deployment
 4. Add status badges to the project README
 5. Set up infrastructure-as-code for pipeline resources (runners, caches, secrets)
-6. Document the full pipeline in `docs/CI-CD.md`
+6. Document the full pipeline in `../../docs/CI-CD.md`
 
 ## Rules
 

package/templates/modules/ci-cd/agents/engineer/skills/ci-cd.fallback.md

@@ -7,7 +7,7 @@ The DevOps engineer primarily owns CI/CD pipelines. You are the fallback — ste
 1. If no CI workflow exists and DevOps hasn't started:
    - Create a basic CI workflow: lint + test on PRs, build on push to the default branch
    - Use standard caching and pinned action versions
-   - Document the setup in `docs/CI-CD.md` and mark the setup as **provisional** — a devops agent should review and complete the production configuration.
+   - Document the setup in `../../docs/CI-CD.md` and mark the setup as **provisional** — a devops agent should review and complete the production configuration.
    - Mark the pipeline as **provisional** — it needs DevOps review for CD, caching optimization, and security hardening
 2. If DevOps is active, skip this entirely.
 
@@ -16,4 +16,4 @@ The DevOps engineer primarily owns CI/CD pipelines. You are the fallback — ste
 - This is a safety net. Set up the basics — lint, test, build.
 - Skip CD (deployment) — that requires infrastructure knowledge best left to DevOps.
 - Let DevOps own pipeline optimization, deployment, and ongoing maintenance.
-- Reference `docs/CI-CD.md` for all configuration details so the devops agent can pick up where you left off.
+- Reference `../../docs/CI-CD.md` for all configuration details so the devops agent can pick up where you left off.

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

@@ -18,7 +18,7 @@
     {
       "title": "Set up CI/CD pipeline",
       "assignTo": "capability:ci-cd",
-      "description": "Configure continuous integration (lint, test, build) and deployment pipeline. Document the setup in docs/CI-CD.md. Use GitHub Actions or equivalent."
+      "description": "Configure continuous integration (lint, test, build) and deployment pipeline. Document the setup in ../../docs/CI-CD.md. Use GitHub Actions or equivalent."
     },
     {
       "title": "Add linter and configure lint rules",

package/templates/modules/ci-cd/skills/ci-cd.bar.md

@@ -2,7 +2,7 @@
 
 A good CI/CD setup:
 
-- A working pipeline with a CI stage (lint → typecheck → test on every PR and push to the default branch) and a CD stage (deploy on merge to the default branch, smoke tests after deployment), documented in `docs/CI-CD.md` with status badges in the README.
+- A working pipeline with a CI stage (lint → typecheck → test on every PR and push to the default branch) and a CD stage (deploy on merge to the default branch, smoke tests after deployment), documented in `../../docs/CI-CD.md` with status badges in the README.
 - Pipelines complete in under 5 minutes (dependency caching in place), action versions pinned to full SHAs, and all secrets stored in GitHub Secrets or equivalent — none in workflow files.
 
 Not done:

package/templates/modules/ci-cd/skills/ci-cd.md

@@ -1,6 +1,6 @@
 # Skill: CI/CD Pipeline
 
-You manage continuous integration and deployment pipelines. Follow the conventions in `docs/CI-CD.md` in the project root.
+You manage continuous integration and deployment pipelines. Follow the conventions in `../../docs/CI-CD.md` in the project root.
 
 ## Setup Steps
 
@@ -13,10 +13,10 @@ You manage continuous integration and deployment pipelines. Follow the conventio
    - Trigger on merge to the default branch
    - Deploy to the target environment
    - Run smoke tests after deployment
-4. Pin every third-party action to a full commit SHA (`uses: actions/checkout@<sha>`, not `@v4`). SHA pinning prevents supply-chain attacks from a compromised action version tag. Record the pinned SHAs in `docs/CI-CD.md` → *Pinned Action SHAs*.
-5. Document the rollback procedure in `docs/CI-CD.md` → *Rollback*: how to revert a failed deploy (e.g., `git revert` + redeploy, or infra rollback command), how to verify the rollback succeeded, and the recovery SLA. A pipeline with no documented rollback path is not done.
+4. Pin every third-party action to a full commit SHA (`uses: actions/checkout@<sha>`, not `@v4`). SHA pinning prevents supply-chain attacks from a compromised action version tag. Record the pinned SHAs in `../../docs/CI-CD.md` → *Pinned Action SHAs*.
+5. Document the rollback procedure in `../../docs/CI-CD.md` → *Rollback*: how to revert a failed deploy (e.g., `git revert` + redeploy, or infra rollback command), how to verify the rollback succeeded, and the recovery SLA. A pipeline with no documented rollback path is not done.
 6. Add status badges to the project README
-7. Document the full pipeline in `docs/CI-CD.md`
+7. Document the full pipeline in `../../docs/CI-CD.md`
 
 ## Ongoing Health Checks
 

package/templates/modules/codebase-onboarding/agents/ceo/skills/codebase-audit.fallback.md

@@ -4,9 +4,9 @@ The Engineer primarily owns codebase auditing and health. You are the fallback
 
 ## Codebase Audit (Fallback)
 
-1. If no `docs/CODEBASE-AUDIT.md` exists and the Engineer hasn't started:
+1. If no `../../docs/CODEBASE-AUDIT.md` exists and the Engineer hasn't started:
    - Read the project structure and key configuration files
-   - Write a high-level architecture overview in `docs/CODEBASE-AUDIT.md`
+   - Write a high-level architecture overview in `../../docs/CODEBASE-AUDIT.md`
    - List obvious tech debt items visible from a surface-level read
    - Mark the document as **provisional** — it needs a thorough engineering review
 2. If the Engineer is active, skip this entirely.
@@ -20,10 +20,10 @@ The Engineer primarily owns codebase auditing and health. You are the fallback
 
 ## Health Check Refresh (follow-up runs)
 
-When `docs/CODEBASE-AUDIT.md` already exists (a prior audit was completed) and you are assigned a follow-up health check:
+When `../../docs/CODEBASE-AUDIT.md` already exists (a prior audit was completed) and you are assigned a follow-up health check:
 
-1. Read the existing `docs/CODEBASE-AUDIT.md`.
+1. Read the existing `../../docs/CODEBASE-AUDIT.md`.
 2. Run a quick surface scan: `find . -name "*.js" -o -name "*.ts" | head -30` to sense if new files or directories have appeared since the last audit date.
 3. Note any obviously new areas (new top-level directories, new dependency groups) not present in the existing document.
-4. Add a dated `## Health Check — <date>` section to `docs/CODEBASE-AUDIT.md` listing: files reviewed, new areas identified, and a note that deep analysis was not performed (this is a CEO fallback — escalate to an engineer for full re-audit if significant new areas were found).
+4. Add a dated `## Health Check — <date>` section to `../../docs/CODEBASE-AUDIT.md` listing: files reviewed, new areas identified, and a note that deep analysis was not performed (this is a CEO fallback — escalate to an engineer for full re-audit if significant new areas were found).
 5. Mark the issue done.

package/templates/modules/codebase-onboarding/module.meta.json

@@ -18,7 +18,7 @@
     {
       "title": "Audit codebase and document architecture",
       "assignTo": "capability:codebase-audit",
-      "description": "Read the existing codebase, map the architecture, identify tech debt hotspots and test coverage gaps. Document findings in docs/CODEBASE-AUDIT.md. Create follow-up issues for cleanup opportunities."
+      "description": "Read the existing codebase, map the architecture, identify tech debt hotspots and test coverage gaps. Document findings in ../../docs/CODEBASE-AUDIT.md. Create follow-up issues for cleanup opportunities."
     }
   ]
 }

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

@@ -2,7 +2,7 @@
 
 A good codebase audit:
 
-- A `docs/CODEBASE-AUDIT.md` with architecture overview (layers, key components, data flow), tech stack summary, tech debt inventory ranked by severity (critical / major / minor), test coverage assessment identifying untested paths, and recommended cleanup priorities.
+- A `../../docs/CODEBASE-AUDIT.md` with architecture overview (layers, key components, data flow), tech stack summary, tech debt inventory ranked by severity (critical / major / minor), test coverage assessment identifying untested paths, and recommended cleanup priorities.
 - Followed by concrete, scoped follow-up issues — one per fix — for the top cleanup opportunities.
 
 Not done:

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

@@ -8,7 +8,7 @@ Use this when assigned a codebase-audit issue, codebase-health routine, or expli
 
 ## Initial Audit
 
-Run this when `docs/CODEBASE-AUDIT.md` does not yet exist.
+Run this when `../../docs/CODEBASE-AUDIT.md` does not yet exist.
 
 1. Map the project structure — identify key directories, entry points, and architectural layers.
 2. Read configuration files (package.json, tsconfig, Dockerfile, CI configs) to understand the tech stack and build pipeline.
@@ -16,7 +16,7 @@ Run this when `docs/CODEBASE-AUDIT.md` does not yet exist.
 4. Assess test coverage — untested paths, missing tests, weak assertions.
 5. Identify tech debt — dead code, unused exports, complex functions, inconsistent patterns, duplicated logic.
 6. Check for code quality issues — long files, deep nesting, too many parameters, missing boundary error handling.
-7. Document findings in `docs/CODEBASE-AUDIT.md` or an issue document/work product:
+7. Document findings in `../../docs/CODEBASE-AUDIT.md` or an issue document/work product:
    - architecture overview
    - tech stack summary
    - tech debt inventory ranked by severity

package/templates/modules/competitive-intel/agents/ceo/skills/competitive-tracking.fallback.md

@@ -4,10 +4,10 @@ The Customer Success Manager, CMO, and Product Owner own competitive intelligenc
 
 ## Competitive Tracking (Fallback)
 
-1. If no `docs/COMPETITIVE-LANDSCAPE.md` exists and nobody has started:
+1. If no `../../docs/COMPETITIVE-LANDSCAPE.md` exists and nobody has started:
    - Identify the top 2-3 competitors based on the company goal
    - Write a brief comparison: what they do, how we differ
-   - Document in `docs/COMPETITIVE-LANDSCAPE.md`
+   - Document in `../../docs/COMPETITIVE-LANDSCAPE.md`
    - Tag the Customer Success Manager, CMO, or Product Owner to expand
 2. If any of the above roles are active, skip this entirely.
 

package/templates/modules/competitive-intel/agents/cmo/skills/competitive-tracking.fallback.md

@@ -4,9 +4,9 @@ The Customer Success Manager owns competitive intelligence above you. You are th
 
 ## Competitive Tracking (Fallback)
 
-1. If no `docs/COMPETITIVE-LANDSCAPE.md` exists and the Customer Success Manager hasn't started:
+1. If no `../../docs/COMPETITIVE-LANDSCAPE.md` exists and the Customer Success Manager hasn't started:
    - Research competitors from a marketing perspective: positioning, messaging, content strategy
-   - Document in `docs/COMPETITIVE-LANDSCAPE.md`
+   - Document in `../../docs/COMPETITIVE-LANDSCAPE.md`
    - Focus on differentiation opportunities for go-to-market
    - Tag the Customer Success Manager to expand with customer-facing insights
 2. If the Customer Success Manager is active, skip this entirely.

package/templates/modules/competitive-intel/agents/customer-success/skills/competitive-tracking.md

@@ -4,8 +4,8 @@ You own competitive intelligence from the customer perspective. You hear what cu
 
 ## Competitive Tracking Process
 
-1. Review the company goal and existing market analysis — if `docs/MARKET-ANALYSIS.md` exists, use it as context.
-2. Research and document in `docs/COMPETITIVE-LANDSCAPE.md`:
+1. Review the company goal and existing market analysis — if `../../docs/MARKET-ANALYSIS.md` exists, use it as context.
+2. Research and document in `../../docs/COMPETITIVE-LANDSCAPE.md`:
    - **Competitor profiles**: For each key competitor (3-5), document:
      - Product overview and target audience
      - What customers say about switching to/from them

package/templates/modules/competitive-intel/agents/product-owner/skills/competitive-tracking.fallback.md

@@ -4,12 +4,12 @@ A specialist in competitive intelligence (Customer Success or CMO) is handling p
 
 ## Steps
 
-1. Read `docs/COMPETITIVE-INTEL.md` if it exists. If it does not, check back after the primary competitive-tracking agent has completed their initial audit.
+1. Read `../../docs/COMPETITIVE-INTEL.md` if it exists. If it does not, check back after the primary competitive-tracking agent has completed their initial audit.
 2. Review recent competitor changes for product-roadmap implications:
    - New features from competitors that close a gap with your product → create a backlog issue "Evaluate [feature] parity with [competitor]" with the relevant section from COMPETITIVE-INTEL.md.
    - Competitor pricing or positioning shifts that affect your value proposition → add a comment to the relevant goal or create an issue for CEO/CMO review.
 3. Update the product backlog with any priority changes driven by competitive pressure (coordinate with CEO before reprioritising existing high-priority items).
-4. Add a `## Product Implications` section to `docs/COMPETITIVE-INTEL.md` if it doesn't already exist, noting your recommendations.
+4. Add a `## Product Implications` section to `../../docs/COMPETITIVE-INTEL.md` if it doesn't already exist, noting your recommendations.
 5. Mark the issue done.
 
 ## Rules

package/templates/modules/competitive-intel/module.meta.json

@@ -17,7 +17,7 @@
     {
       "title": "Build initial competitive landscape",
       "assignTo": "capability:competitive-tracking",
-      "description": "Research key competitors: their positioning, strengths, weaknesses, pricing, and recent moves. Document a living competitive landscape in docs/COMPETITIVE-LANDSCAPE.md with actionable differentiation insights."
+      "description": "Research key competitors: their positioning, strengths, weaknesses, pricing, and recent moves. Document a living competitive landscape in ../../docs/COMPETITIVE-LANDSCAPE.md with actionable differentiation insights."
     }
   ]
 }

package/templates/modules/competitive-intel/skills/competitive-tracking.bar.md

@@ -1,11 +1,11 @@
 ## Competitive Tracking — Done Bar
 
 **Done:**
-- `docs/COMPETITIVE-INTEL.md` exists with a profile for each tracked competitor that includes: product positioning, key differentiators, pricing model (if public), and a specific takeaway for your product ("what this means for us").
+- `../../docs/COMPETITIVE-INTEL.md` exists with a profile for each tracked competitor that includes: product positioning, key differentiators, pricing model (if public), and a specific takeaway for your product ("what this means for us").
 - Differentiation opportunities are explicitly named — not just competitor feature lists, but concrete gaps or advantages your product has or could develop.
 - Each competitor profile was updated within the last tracking cycle (not stale from a previous run).
 
 **Not done:**
 - Competitor profiles are feature lists with no positioning takeaway.
 - "Differentiation opportunities" section is absent or contains only generic observations ("we should improve UX").
-- `docs/COMPETITIVE-INTEL.md` was not updated this run (routine ran but no document was touched).
+- `../../docs/COMPETITIVE-INTEL.md` was not updated this run (routine ran but no document was touched).

package/templates/modules/competitive-intel/skills/competitive-tracking.md

@@ -4,8 +4,8 @@ You own competitive intelligence. This is a living analysis — profiles evolve
 
 ## Competitive Tracking Process
 
-1. Review the company goal and existing market analysis — if `docs/MARKET-ANALYSIS.md` exists, use it as context. Otherwise, start from the project description.
-2. Research and document in `docs/COMPETITIVE-LANDSCAPE.md`:
+1. Review the company goal and existing market analysis — if `../../docs/MARKET-ANALYSIS.md` exists, use it as context. Otherwise, start from the project description.
+2. Research and document in `../../docs/COMPETITIVE-LANDSCAPE.md`:
    - **Competitor profiles**: For each key competitor (3-5), document:
      - Product overview and target audience
      - Positioning and messaging

package/templates/modules/dependency-management/agents/engineer/skills/dependency-audit.fallback.md

@@ -4,10 +4,10 @@ DevOps or Security Engineer primarily owns dependency management. You are the fa
 
 ## Dependency Audit (Fallback)
 
-1. If no `docs/DEPENDENCY-AUDIT.md` exists and no one else has started:
+1. If no `../../docs/DEPENDENCY-AUDIT.md` exists and no one else has started:
    - Run the package manager's built-in audit command (`npm audit`, `pip-audit`, etc.)
    - Apply safe patch-level updates that don't break tests
-   - Document current dependency state in `docs/DEPENDENCY-AUDIT.md`
+   - Document current dependency state in `../../docs/DEPENDENCY-AUDIT.md`
    - Mark the document as **provisional** — it needs a security/ops review for CVE prioritization
 2. If DevOps or Security Engineer is active, skip this entirely.
 

package/templates/modules/dependency-management/skills/dependency-audit.md

@@ -20,7 +20,7 @@ You are responsible for keeping the project's dependencies healthy, secure, and
    - Can it be updated in-place (patch/minor bump)?
    - Does it require migration work (major version, breaking changes)?
    - Are there alternatives if the dependency is abandoned?
-5. **Document** findings in `docs/DEPENDENCY-AUDIT.md`:
+5. **Document** findings in `../../docs/DEPENDENCY-AUDIT.md`:
    - Summary table of dependencies by status (current, outdated, vulnerable, deprecated)
    - Prioritized upgrade plan with estimated effort
    - Lock file hygiene notes
@@ -34,7 +34,7 @@ When assigned a "Dependency audit" routine-run issue:
 1. Run the vulnerability scan: `npm audit --json` (or equivalent for the project's package manager). Flag any new Critical or High CVEs not present in the last audit.
 2. Check for newly outdated dependencies: compare current versions against the latest. Flag anything more than one major version behind.
 3. Apply safe patch updates (semver patch-only, no breaking changes): update, run the test suite, commit if green.
-4. Update `docs/DEPENDENCY-AUDIT.md` with the new scan date, any new findings, and any updates applied.
+4. Update `../../docs/DEPENDENCY-AUDIT.md` with the new scan date, any new findings, and any updates applied.
 5. Mark the routine issue done. If Critical CVEs were found that cannot be patched, create a separate high-priority issue for each and escalate to CEO.
 
 ## Rules

package/templates/modules/game-design/agents/ceo/skills/game-design.fallback.md

@@ -4,7 +4,7 @@ The Game Designer or Engineer primarily owns the game design. You are the fallba
 
 ## Game Design (Fallback)
 
-1. If no `docs/GDD.md` exists and no one else has started:
+1. If no `../../docs/GDD.md` exists and no one else has started:
    - Write a minimal Game Design Document covering: concept pitch, core mechanic, basic game loop, target platform
    - List obvious design questions that need answers (progression, win conditions, art style)
    - Mark the document as **provisional** — it needs a thorough design review