@starlein/paperclip-plugin-company-wizard 0.5.0 → 0.6.2

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

@@ -10,8 +10,8 @@ Goal → Roadmap → Issues → Assignment → Execution → Done
 
 1. **Goal decomposition** — The backlog owner breaks the company goal into milestones, then milestones into actionable issues.
 2. **Issue creation** — New issues enter the backlog via `POST /api/companies/{companyId}/issues` with `title`, `description`, `priority`, `projectId`, `goalId`, and `labelIds`. Top-level backlog issues must always include the active roadmap `projectId`. They must also set workspace isolation explicitly — see **Workspace Isolation** below.
-3. **Pipeline health** — The backlog owner monitors the ready assigned queue. When fewer than about 8 actionable ready issues remain across the active delivery roles, the next small batch is generated from the roadmap.
-4. **Assignment** — Issues are assigned at creation to the best-fit owner. Engineering-ready issues go directly to the Software Engineer (or matching delivery role) so assignment wakeups start work immediately. Leave an issue unassigned only when no suitable owner exists.
+3. **Pipeline health** — The backlog owner monitors implementation and review ownership. Open PR count is a queue-health signal, not a hard cap on independent work.
+4. **Assignment** — Assign acceptance-ready issues to available owners. Keep every open PR tied to a named owner and next action, and prioritize stale/conflicting PR repair without freezing unrelated implementation.
 5. **Execution** — Agents check out assigned issues, work them, and hand off deliberately for review or completion.
 
 ## Issue Quality
@@ -30,22 +30,37 @@ Write acceptance criteria in the issue description. Engineers use these to valid
 
 ## Workspace Isolation (required at creation)
 
-Every issue runs in a git execution workspace (worktree/branch). To let issues run in
-parallel without colliding in the same worktree, you must declare the workspace intent
-**when you create the issue** — otherwise the issue silently adopts the workspace of
-whatever issue you currently have checked out, which serializes work and corrupts branch
-state.
+Repository implementation issues need explicit workspace intent **when you create the
+issue**. When isolated workspaces are enabled and configured for the project, request
+an independent workspace to prevent accidental checkout sharing. The API can inherit
+the current agent run's issue workspace when no workspace selection is supplied; child
+issues can also inherit from their parent within the same project. This is conditional,
+not proof that every issue runs in a git worktree. Project-detached API-only routines
+need no repository workspace.
 
-- **Top-level issue** (independent work, no `parentId`): always send
+- **Top-level implementation issue** (independent work, no `parentId`): when isolation is available, send
   `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` in the create body. This
-  gives the issue its own worktree and branch.
-- **Sub-issue** (part of a larger parent task): set `"parentId": "<parent-issue-id>"` and
-  do **not** send `executionWorkspaceSettings`. The sub-issue deliberately reuses the
-  parent's workspace (the parent cannot be completed/cleaned up while its sub-issues are
-  still open, so sharing is safe and intended).
-
-**Never** create a top-level issue without `executionWorkspaceSettings`. Doing so makes it
-inherit the creator's currently checked-out workspace and blocks parallel execution.
+  requests the project's configured isolated strategy (which may be a git worktree).
+- **Implementation sub-issue** (part of a larger parent task): set `"parentId": "<parent-issue-id>"` and
+  also send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` when isolation is available.
+  Hierarchy does not imply checkout sharing. Only when the task explicitly requires the
+  same code change should you send `inheritExecutionWorkspaceFromIssueId` with the source
+  issue's internal id and omit conflicting workspace settings.
+
+If isolated workspaces are disabled or the repository has no valid initial commit yet,
+follow the rendered project policy and initialize the repository first. Do not claim
+that requesting isolation overrides an instance feature gate. Read back the issue and
+runtime workspace before starting concurrent repository writes.
+
+### Why this still matters when the project shares one workspace
+
+The Company Wizard supplies `sharedWorkspaceConcurrency: "serialize"` for shared project
+workspaces. Current Paperclip applies this policy only when the instance's experimental
+isolated-workspaces feature and project policy are enabled. When effective, shared runs
+queue behind the current holder. When disabled, the saved policy is not an active lock;
+avoid parallel writes to that checkout and use the bootstrap warning to arrange safe
+workspace setup. Independent isolated workspaces permit parallel work only after their
+configured strategy and repository are runnable.
 
 Example top-level create body:
 
@@ -83,10 +98,10 @@ Re-prioritize when milestones shift or new information arrives. Don't let low-pr
 
 ## Backlog Health Indicators
 
-- **Healthy**: about 8 ready assigned issues across active delivery roles, covering the next logical chunk of work
-- **Thin**: fewer than 4 ready assigned issues — generate and assign more soon
-- **Empty**: no ready assigned issues — engineers will idle. Generate and assign immediately.
-- **Bloated**: 20+ ready issues — stop creating, focus on prioritization and cleanup
+- **Healthy**: active work and open PRs have named owners, current heads, and concrete next actions
+- **Thin**: available agents have no acceptance-ready work — prepare and assign a small next issue
+- **Needs queue attention**: stale, conflicting, red, or ownerless PRs exist — route repairs while independent implementation continues
+- **Bloated**: work lacks owners or actionable acceptance criteria — consolidate or reprioritize it without imposing a numeric repository cap
 
 ## Coordination
 
@@ -96,4 +111,4 @@ Re-prioritize when milestones shift or new information arrives. Don't let low-pr
 
 ## Review Handoff
 
-When an issue is ready for review (moving to `in_review`), it must be assigned to the reviewer. If an executionPolicy with review stages is configured, Paperclip reassigns automatically. Otherwise, the person moving the issue must PATCH `assigneeAgentId` to the reviewer. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.
+Move an issue to `in_review` only when a runtime-recognized action path exists: an active non-author `executionPolicy` stage or a first-class human interaction/approval. Paperclip reassigns automatically for an executionPolicy stage. Agent reassignment by itself is not a valid no-policy review path; without a recognized path, keep the issue `in_progress` for a concrete handoff or complete the direct/self-merge flow.

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

@@ -24,22 +24,23 @@ These categories must exist as Paperclip labels. Create them via `POST /api/comp
 
 | Label | Color | Use for |
 |:------|:------|:--------|
-| feature | `0075ca` | New user-facing capability |
-| bug | `d73a4a` | Defect or regression |
-| chore | `7057ff` | Refactoring, cleanup, dependency updates |
-| spike | `006b75` | Research or investigation with a time-box |
-| blocked | `e4e669` | Cannot proceed, needs unblocking |
+| feature | `#0075ca` | New user-facing capability |
+| bug | `#d73a4a` | Defect or regression |
+| chore | `#7057ff` | Refactoring, cleanup, dependency updates |
+| spike | `#006b75` | Research or investigation with a time-box |
+| blocked | `#e4e669` | Cannot proceed, needs unblocking |
 
 Add more labels as the project evolves (e.g., `docs`, `design`, `security`). Pick distinct hex colors. Fetch existing labels: `GET /api/companies/{companyId}/labels`.
 
 ## Backlog Snapshot
 
-_Summary of current backlog health. Update on each heartbeat cycle._
+_Summary of current backlog health. Update during an assigned backlog-planning or grooming run._
 
-- **Ready assigned issues:** _(count by owner)_
-- **Unassigned todo issues:** _(count; should normally be 0 except items without a suitable owner)_
+- **Active implementation issues:** _(count by owner; include next action)_
+- **Open implementation PRs:** _(count by repository; include owner and merge state)_
+- **Prioritized inactive issues:** _(next roadmap work waiting for genuine delivery capacity)_
 - **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/backlog/module.meta.json

@@ -16,13 +16,13 @@
       "title": "Create roadmap and generate initial backlog",
       "assignTo": "capability:backlog-health",
       "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. Assign each engineer-actionable issue to the best-fit agent (e.g., the Software Engineer) as you create it so work starts immediately — don't leave the seed backlog unassigned. Don't wait for grooming cycles to fill the backlog — seed it now."
+      "description": "Review the company goal, create a ROADMAP.md with milestones, then prepare the next 3-5 acceptance-ready issues. Open PR count is advisory and must not freeze independent implementation. Assign work to available owners while keeping every open PR tied to an owner and next action. Scope each issue to one deliverable, link it to the relevant goal/project, and give every implementation issue (including subissues) an isolated workspace unless explicit same-change reuse is required."
     }
   ],
   "routines": [
     {
       "title": "Backlog grooming",
-      "description": "Routine-run checklist: inspect roadmap/backlog health, ensure at least 8 actionable ready issues exist, create scoped issues (around 3-6 per pass) and assign each to its best-fit agent when capacity is low, link artifacts/goals/projects, summarize changes on the routine issue, then exit.",
+      "description": "Routine-run checklist: inspect roadmap plus implementation/review ownership, create the next 1-3 scoped issues, assign work that has an available owner and review path, link artifacts/goals/projects, summarize queue evidence and changes on the routine issue, then exit. Open PR count is a prioritization signal, not an assignment cap.",
       "assignTo": "capability:backlog-health",
       "schedule": "0 */2 * * *",
       "priority": "medium",

package/templates/modules/backlog/skills/backlog-health.bar.md

@@ -3,9 +3,9 @@
 A good backlog health pass:
 
 - Every issue created is INVEST-shaped: has a clear title, written acceptance criteria in the description, a priority, a label, and is attached to the correct `projectId` and `goalId` — never a top-level issue with `projectId: null`.
-- Every issue declares workspace isolation explicitly: top-level issues (no `parentId`) carry `"executionWorkspaceSettings": { "mode": "isolated_workspace" }`; subissues set `parentId` and omit it. A top-level issue created without it is not done — it would inherit the creator's checked-out workspace and block parallel execution.
-- The team keeps a healthy queue of ready, **assigned** work (toward the grooming target of ~8 actionable ready issues); when the assigned ready queue runs low, new issues are created **and assigned** from the roadmap so no agent goes idle between grooming cycles, and the action is recorded in daily notes. Issues are assigned at creation — do not stockpile a pool of unassigned issues.
-- Review handoff: when moving an issue to `in_review`, always reassign it to the reviewer. Without reassignment, `in_review` issues stall with the implementer still assigned.
+- Every repository implementation issue declares workspace intent explicitly: top-level issues and subissues request `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` when the instance feature, project policy, and initialized repository support it; otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse is exceptional and explicit via `inheritExecutionWorkspaceFromIssueId`. API-only routines stay project-detached.
+- Open PR count is advisory, not a dispatch freeze. Assign independent acceptance-ready work to available owners while every PR retains a named owner and concrete next action.
+- Review handoff: `in_review` has a runtime-recognized non-author executionPolicy stage or first-class human interaction/approval. Agent reassignment alone is not a no-policy review path.
 
 Not done:
 

package/templates/modules/backlog/skills/backlog-health.md

@@ -15,11 +15,11 @@ Before creating your first batch of issues, set up labels for the company:
 
 | Label | Color | Use for |
 |:------|:------|:--------|
-| feature | `0075ca` | New user-facing capability |
-| bug | `d73a4a` | Defects and regressions |
-| chore | `7057ff` | Refactoring, cleanup, dependency updates |
-| spike | `006b75` | Research or investigation with a time-box |
-| blocked | `e4e669` | Cannot proceed, needs unblocking |
+| feature | `#0075ca` | New user-facing capability |
+| bug | `#d73a4a` | Defects and regressions |
+| chore | `#7057ff` | Refactoring, cleanup, dependency updates |
+| spike | `#006b75` | Research or investigation with a time-box |
+| blocked | `#e4e669` | Cannot proceed, needs unblocking |
 
 Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `security`). Pick distinct hex colors.
 
@@ -28,13 +28,14 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 1. Checkout the assigned backlog/routine issue in Paperclip before mutating the board. This is API-only control-plane work; do not create or enter a repository worktree for the grooming run.
 2. Read the current company goals, roadmap/project context, existing issue documents, and recent decision log entries.
 3. Query existing issues for the relevant project/goal and avoid duplicates.
-4. If the backlog is thin or unclear, create around 3-6 small actionable issues via `POST /api/companies/{companyId}/issues`.
-5. Each issue must include: `title`, acceptance-oriented `description`, `priority`, `projectId`, `goalId` when known, and `labelIds`.
-6. Set workspace isolation explicitly on every issue you create (see Rules): top-level issues send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }`; sub-issues set `parentId` and omit it.
-7. Use `blockedByIssueIds` for real dependencies instead of free-text blockers.
-8. Assign each issue to the best-fit available agent as you create it — engineer-actionable work with clear acceptance criteria goes to the Software Engineer (or the matching role). Direct push-assignment is the primary dispatch path; the assigned queue is the buffer, so do **not** stockpile a pool of unassigned ready work. Leave an issue unassigned only when no suitable owner exists — the low-frequency auto-assign safety net will catch those.
-9. Record generated issue ids and rationale in the routine issue comment; use issue documents for long plans.
-10. Mark the routine-run issue done when complete.
+4. Check delivery ownership before creating work: open implementation PRs per repository, active implementation issues per agent, and the current review owner. Open PR count is advisory and must not freeze unrelated acceptance-ready work.
+5. If the next work is unclear, create the next 1-3 small actionable issues via `POST /api/companies/{companyId}/issues`.
+6. Each issue must include: `title`, acceptance-oriented `description`, `priority`, `projectId`, `goalId` when known, and `labelIds`.
+7. Set workspace isolation explicitly on every implementation issue, including subissues (see Rules).
+8. Use `blockedByIssueIds` for real dependencies instead of free-text blockers. Never create dependencies merely because other PRs are open.
+9. Assign acceptance-ready work to available owners. Use queue state to prioritize stale/conflicting PR repair without withholding unrelated implementation.
+10. Record generated/assigned issue ids, current queue evidence, and rationale in the routine issue comment; use issue documents for long plans.
+11. Mark the routine-run issue done when complete.
 
 ## Rules
 
@@ -42,10 +43,10 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 - Do not create top-level backlog issues with `projectId: null` when a project exists.
 - Keep issues small and actionable. Each should be completable, tested, and reviewed independently.
 - Split into subissues only when each child can be completed independently; avoid splitting tightly coupled implementation across sibling subissues.
-- **Set workspace isolation explicitly at creation.** Top-level issues (no `parentId`) must send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch. Sub-issues set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace. Never create a top-level issue without it — otherwise it inherits the workspace of whatever issue you currently have checked out and blocks parallel work.
+- **Set workspace intent explicitly at creation.** For repository implementation, including subissues, request `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` when the instance feature, project policy, and initialized repository support isolation. The actual workspace uses the configured strategy; do not promise a git worktree for every project. `parentId` is hierarchy, not workspace consent. Reuse another issue's checkout only when explicitly required by the task, using `inheritExecutionWorkspaceFromIssueId` with the source issue's internal id. If isolation is unavailable, follow the rendered bootstrap/project policy and avoid concurrent writes to a shared checkout; requesting isolation does not bypass the instance feature gate. API-only routines stay project-detached.
 - Always attach at least one label to every issue you create.
-- **Attach a task watchdog to every top-level issue you create.** Send `"watchdog": { "agentId": "<CEO agent id>", "instructions": "If this issue's work stalls (runs end without it reaching done, a review is misrouted, or a dependent merge is stranded), re-evaluate and recover: verify blockers and executionPolicy gates, reassign to the right owner with an explicit next action, or escalate. Do not archive or delete any execution workspace." }`. This is native, event-driven stall recovery — Paperclip wakes the watchdog agent when the issue's subtree stops without completing, so you no longer rely only on the periodic stall-detection routine. Use the CEO agent id (resolve it from your `heartbeat-context` or `GET /api/companies/{companyId}/agents`); omit the watchdog only for throwaway sub-issues that reuse a parent's workspace.
+- Do not attach a universal task watchdog or create watchdog/queue-drain wrapper issues. Use the issue's real owner, first-class blockers, executionPolicy, interactions, and normal wake paths. Add a watchdog only when the issue explicitly documents a bounded recovery requirement that those paths cannot cover.
 - If the goal is fully decomposed into issues, do not create more. Report status and next review trigger to the CEO/Product Owner.
 - Work products such as roadmap drafts or decomposition tables belong in issue documents/artifacts, not only comments.
-- **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. If there is no executionPolicy, PATCH the issue's `assigneeAgentId` to the reviewer before or at the same time as the status change. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.
+- **Review handoff:** Use `in_review` only with a runtime-recognized path: an active non-author `executionPolicy` stage or a first-class human interaction/approval. Agent reassignment alone is not a valid no-policy review path. Without such a path, keep the issue `in_progress` for a concrete agent handoff or finish the direct/self-merge flow.
 - **Backlog grooming is intentionally project-detached and must not use a git worktree.** Perform the run through Paperclip APIs only. Setting `projectId` and isolated `executionWorkspaceSettings` on the *work issues you create* is correct; that does not attach the grooming run itself to their project or worktrees. Do not clone, branch, run `git worktree add`, or try to repair the routine by attaching it to a project.

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` (paths in this skill are relative to your working directory, the company workspace).
 
 ## 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
 
@@ -35,3 +35,5 @@ When assigned a "CI pipeline health check" routine-run issue:
 - Pin action versions to full SHAs, not tags, for security.
 - Never store secrets in workflow files — use GitHub Secrets or equivalent.
 - If CI breaks the default branch, fix it immediately — a red default branch blocks everyone.
+- Repair CI, stale bases, conflicts, branch protection, packaging, and deployment mechanics on the existing originating issue and PR. Do not open a replacement PR or a queue-drain/release-wrapper issue to escape an operational blocker.
+- Do not poll ordinary Paperclip review stages, PR-capacity waits, or workspace cleanup. Rely on their owner/blocker/wake path. Use a bounded external-service monitor only for a named transition such as a running CI job, no more often than every 15 minutes unless the issue defines a tighter SLA, with attempt/timeout bounds and comments only on state changes or the terminal checkpoint.

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
@@ -16,7 +16,7 @@ You own competitive intelligence. This is a living analysis — profiles evolve
    - **Gaps and opportunities**: Where competitors are weak and we can win
    - **Threats**: Where competitors are strong and we need to defend
 3. Create follow-up issues for strategic decisions informed by competitive insights:
-   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include `projectId` plus `goalId` / `parentId` when applicable, and set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 4. Record summary in your daily notes
 
 ## Rules

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.