@starlein/paperclip-plugin-company-wizard 0.4.6 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.6",
+  "version": "0.4.9",
   "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

@@ -19,7 +19,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 2. **Projects** — create with `POST /api/companies/{companyId}/projects` using `{ name, description, goalIds, workspace, executionWorkspacePolicy? }`. Reference goals via `goalIds`; create after all goals exist. Valid project `status` (optional, defaults to `backlog`): `backlog`, `planned`, `in_progress`, `completed`, `cancelled` — **`active` is a goal status, NOT a project status; do not set it on a project.** Create the project workspace as an object, not a raw string. Fresh/new repositories use a local project workspace such as `workspace: { sourceType: "local_path", cwd: "...", defaultRef: "main", setupCommand: "git init -b main", isPrimary: true }` and must initialize Git before work starts; do not attach an `executionWorkspacePolicy` to a fresh local repo (the repo has no base ref yet). Existing repository-backed projects use the workspace refs shown in this bootstrap exactly as rendered; do not rewrite them to `main`, `master`, or add/remove `origin/`. When this bootstrap includes `executionWorkspacePolicy`, send it exactly as rendered; it was included only because Paperclip's experimental isolated-workspaces setting is enabled, and its `workspaceStrategy.baseRef` comes from project/worktree settings. Never inline credentials in repo URLs.
 3. **Labels** — if the bootstrap includes an Issues section, create issue labels first (`POST /api/companies/{companyId}/labels` with `{ name, color }`). Colors must be 6-digit hex strings with a leading `#`.
 4. **Agents** — hire via governance (`POST /api/companies/{companyId}/agent-hires`) using the listed `adapterType`, nested `adapterConfig`, `runtimeConfig`, `capabilities`, and `metadata`. The Company Wizard already created the CEO for this bootstrap issue; reuse/update any existing agent with the same `metadata.templateRole` instead of creating a duplicate.
-5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap.
+5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap. Set workspace isolation explicitly: **top-level issues** (no `parentId`) must include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch; **subtasks** set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace.
 6. **Routines** — reference project and agent. Create the routine first, then add a schedule trigger with `POST /api/routines/{routineId}/triggers` using `{ kind: "schedule", cronExpression: schedule, timezone: "UTC" }`.
 
 **Status + subissue guardrails:**
@@ -27,7 +27,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 - Parent and subissue status are related by intent, not automatically coupled by tooling.
 - Do not auto-mark a parent `done` just because a child changed status.
 - Do not auto-reopen a `done` parent/subissue unless you have an explicit reason and record it in a comment.
-- Do not implicitly reuse a parent workspace for subissues; keep `projectId` explicit and respect the project/issue execution workspace policy. Use isolated workspaces only when Paperclip created one for the issue.
+- Make workspace intent explicit at creation; never rely on implicit inheritance. A top-level issue (no `parentId`) created without `executionWorkspaceSettings` silently adopts the workspace of whatever issue the creator currently has checked out, which serializes work and corrupts branch state. Therefore: top-level issues set `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` (own worktree); subissues set `parentId` and omit `executionWorkspaceSettings` so they deliberately share the parent's workspace (safe because the parent cannot be completed/cleaned up while subissues are open). Keep `projectId` explicit on both.
 
 **Review workflow guardrail:**
 

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

@@ -0,0 +1,17 @@
+## 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.
+- 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.
+- The document exists but contains no actionable overview (placeholder text only).
+- No follow-up issue was created for the engineer to complete the work.
+
+**Not required from the CEO fallback:**
+- Full API boundary diagrams
+- ADR-style decision log
+- Deployment topology
+- Data model details
+(These are requirements for the engineer primary — not for the CEO safety-net run.)

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

@@ -4,6 +4,8 @@ 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.
+
 If an Engineer is defining the architecture, coordinate with them on:
 - **Frontend component structure**: Page layout, shared components, routing
 - **Design token integration**: How the design system connects to the codebase

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

@@ -5,16 +5,17 @@ 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. 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)
    - **Component patterns**: Buttons, inputs, cards, modals, navigation — describe states and variants
    - **Brand guidelines**: Logo usage, tone of visual language, iconography style
    - **Responsive breakpoints**: Mobile, tablet, desktop sizing approach
-3. Create implementation issues for the engineer:
-   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable).
-4. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
+4. Create implementation issues for the engineer:
+   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. 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.
+5. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
 
 ## Rules
 

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

@@ -13,7 +13,7 @@ You own system architecture. Design the structure that implements the tech stack
    - **Deployment model**: How the system is built, tested, and deployed
    - **Key decisions**: Architectural decisions with rationale (ADR-style)
 3. Create implementation issues for the foundational structure:
-   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. 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.
 
 ## Rules
 

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

@@ -0,0 +1,25 @@
+# Skill: Design System (Engineer Primary)
+
+You are establishing the project's design system foundations when no UI Designer is available. Your output should be practical and hand-off-ready — define the minimum tokens and patterns needed for consistent development, and document them so a UI Designer can refine them later.
+
+## 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.
+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.
+   - **Spacing**: a 4px base grid — common values: 4, 8, 12, 16, 24, 32, 48, 64px.
+5. Define 3–5 core component patterns (button, input, card, navigation item) with their states (default, hover, active, disabled, error). Document as usage rules, not full component code.
+6. Write token definitions as CSS custom properties or the equivalent for the project's framework.
+7. Mark the document as **provisional** — created by engineer as primary; a UI Designer should review and extend.
+8. Create a follow-up issue: "Review and extend design system" assigned to the UI Designer if one is ever added to the team.
+9. Mark this issue done.
+
+## Rules
+
+- 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.

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

@@ -2,4 +2,4 @@
 
 Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created. This routine is a **safety net** that catches stragglers when the Product Owner hasn't acted.
 
-Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.

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

@@ -2,4 +2,4 @@
 
 Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created, not through this routine. This routine is a **safety net** that catches stragglers every 4 hours.
 
-Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.

package/templates/modules/backlog/agents/ceo/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine Fallback
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.

package/templates/modules/backlog/agents/ceo/skills/backlog-health.fallback.md

@@ -9,6 +9,7 @@ On your heartbeat, after handling assignments:
 1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
 2. If fewer than 1 unassigned issue remains AND the Product Owner hasn't acted recently:
    - Create 1-2 high-priority issues from the roadmap to keep engineers unblocked
+   - For each top-level issue (no `parentId`), include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so it gets its own worktree; subissues set `parentId` and omit it. Never create a top-level issue without it (it would inherit your checked-out workspace and block parallel work).
    - Attach `labelIds` — fetch available labels via `GET /api/companies/{companyId}/labels`. If no labels exist yet, create the defaults (see `backlog-health` skill for the label table) before creating issues.
    - Comment on the issue tagging the Product Owner to take over backlog grooming
 3. If the Product Owner is active and the backlog has 1+ issues, skip this step.
@@ -18,3 +19,4 @@ On your heartbeat, after handling assignments:
 - This is a safety net, not your primary job. Let the PO own it.
 - Only create issues when engineers would otherwise have nothing to work on.
 - Keep it minimal — just enough to unblock, not a full grooming session.
+- **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. Otherwise PATCH `assigneeAgentId` to the reviewer before or at the same time as the status change.

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

@@ -1,3 +1,3 @@
 ## Backlog Health Routine
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.

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

@@ -9,7 +9,7 @@ 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`.
+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.
 5. **Execution** — Agents check out assigned issues, work them, and hand off deliberately for review or completion.
@@ -28,6 +28,39 @@ Every issue should be:
 
 Write acceptance criteria in the issue description. Engineers use these to validate their work before marking done. Keep them concrete and testable.
 
+## 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.
+
+- **Top-level issue** (independent work, no `parentId`): always 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.
+
+Example top-level create body:
+
+```json
+{
+  "title": "Build campaign onboarding wizard",
+  "description": "...",
+  "priority": "high",
+  "projectId": "<roadmap-project-id>",
+  "goalId": "<goal-id>",
+  "labelIds": ["<label-id>"],
+  "executionWorkspaceSettings": { "mode": "isolated_workspace" }
+}
+```
+
 ## Sources of Issues
 
 Issues can enter the backlog from multiple sources:
@@ -60,3 +93,7 @@ Re-prioritize when milestones shift or new information arrives. Don't let low-pr
 - The backlog owner coordinates with the CEO on strategic priorities when unclear.
 - If the goal is fully decomposed and all issues are done or in progress, report completion to the CEO rather than inventing new work.
 - When multiple agents create issues (e.g., from user-testing findings), the backlog owner reviews and re-prioritizes as needed.
+
+## 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.

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 backlog-process.md)_
+- **Health:** _(healthy / thin / empty / bloated — see docs/backlog-process.md)_
 
 ## Decisions Log
 

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

@@ -24,7 +24,7 @@
       "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.",
       "assignTo": "capability:backlog-health",
-      "schedule": "0 */4 * * *",
+      "schedule": "0 */2 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

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

@@ -3,7 +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.
 
 Not done:
 

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

@@ -30,10 +30,11 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 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. Use `blockedByIssueIds` for real dependencies instead of free-text blockers.
-7. 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.
-8. Record generated issue ids and rationale in the routine issue comment; use issue documents for long plans.
-9. Mark the routine-run issue done when complete.
+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.
 
 ## Rules
 
@@ -41,6 +42,8 @@ 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.
 - Always attach at least one label to every issue you create.
 - 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.

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

@@ -9,11 +9,11 @@ The UI Designer and CMO both own brand identity above you. You are the last-reso
    - 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**
-   - Create an issue for the designer or CMO to review and expand the brand guidelines
-2. If a designer or CMO is active, skip this entirely.
+   - 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.
 
 ## Rules
 
 - This is a safety net. Choose sensible defaults, not optimal solutions.
-- Mark everything as provisional — the designer owns the final brand.
-- Let the designer or CMO refine and expand the actual brand identity.
+- Mark everything as provisional — the ui-designer owns the final brand.
+- Let the ui-designer or CMO refine and expand the actual brand identity.

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

@@ -15,7 +15,7 @@ You own the company's visual identity and brand guidelines. Define a cohesive br
    - **Iconography**: Style, stroke weight, grid alignment
    - **Tone of voice**: Communication style, vocabulary, personality
 3. Document everything in `docs/BRAND-IDENTITY.md`:
-   - Use the brand-identity-template as a starting point
+   - 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:

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`
+   - 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,3 +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.

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

@@ -13,8 +13,19 @@ 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. Add status badges to the project README
-5. Document the full pipeline in `docs/CI-CD.md`
+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`
+
+## Ongoing Health Checks
+
+When assigned a "CI pipeline health check" routine-run issue:
+
+1. Review the last 7 days of pipeline runs. Check: average duration trend (flag if >20% slower), flake rate per job (flag jobs failing >5% of runs), failure rate on the default branch.
+2. If the default branch is red (failing), this is P0 — do not mark the routine done until fixed or escalated.
+3. Check for unpinned action versions added since last check; pin them.
+4. Leave a summary comment on the issue (run counts, any flaky/slow jobs, any fixes applied), then mark the routine issue done.
 
 ## Rules
 

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

@@ -17,3 +17,13 @@ The Engineer primarily owns codebase auditing and health. You are the fallback
 - Skip deep code analysis — that requires engineering expertise.
 - Don't create cleanup issues — leave that to the Engineer's thorough audit.
 - Let the Engineer own the ongoing health checks and refactoring work.
+
+## 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:
+
+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).
+5. Mark the issue done.

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

@@ -0,0 +1,19 @@
+# Skill: Competitive Tracking (Product Owner Fallback)
+
+A specialist in competitive intelligence (Customer Success or CMO) is handling primary competitive tracking. Your role is to surface product-roadmap implications from their findings and ensure competitor insights feed into the backlog.
+
+## 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.
+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.
+5. Mark the issue done.
+
+## Rules
+
+- Do not duplicate the competitor research already done by the primary agent — read their output and add product perspective.
+- If COMPETITIVE-INTEL.md does not exist yet, do not create it — wait for the primary agent. Leave an issue comment noting the dependency and mark done if the issue was routine-triggered.
+- Coordinate with CMO or Customer Success before making any public-facing positioning changes.

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

@@ -0,0 +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").
+- 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).

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

@@ -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).
+   - `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.
 4. Record summary in your daily notes
 
 ## Rules

package/templates/modules/dependency-management/module.meta.json

@@ -21,5 +21,14 @@
       "assignTo": "capability:dependency-audit",
       "description": "Audit all project dependencies for outdated versions, known vulnerabilities, and deprecated packages. Document findings and create a prioritized upgrade plan."
     }
+  ],
+  "routines": [
+    {
+      "name": "Dependency audit",
+      "description": "Scan for new vulnerabilities and outdated packages, apply safe patch updates.",
+      "assignTo": "capability:dependency-audit",
+      "schedule": "0 2 * * 1",
+      "concurrencyPolicy": "forbid"
+    }
   ]
 }

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

@@ -27,12 +27,15 @@ You are responsible for keeping the project's dependencies healthy, secure, and
 6. **Execute safe upgrades** — Apply patch and minor updates directly when tests pass.
 7. **Create issues** for major version upgrades or migrations that require dedicated work.
 
-## Ongoing
+## Ongoing Audits (Routine-Triggered)
 
-On each heartbeat when `docs/DEPENDENCY-AUDIT.md` exists:
-1. Run vulnerability scan — if new CVEs appear, create issues immediately.
-2. Check for newly outdated dependencies — update the audit doc.
-3. Apply safe patch updates and verify tests pass.
+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.
+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/documentation/skills/project-docs.bar.md

@@ -0,0 +1,13 @@
+## Project Documentation — Done Bar
+
+**Done:**
+- All documentation targets specified in the issue have been created or updated.
+- Setup instructions have been verified: every command listed in README.md or setup guides has been run at least once and produces the expected result.
+- API documentation matches the current implementation — no documented endpoints or parameters that no longer exist, no undocumented endpoints that do.
+- No content is duplicated across files — each fact appears in exactly one place; other files reference it rather than copying.
+- Internal links (cross-references between docs) are valid — no broken anchors or references to non-existent files.
+
+**Not done:**
+- Setup instructions are untested ("this should work" documentation).
+- API docs were not updated after a breaking change.
+- A section is marked "TODO" or "coming soon" without a follow-up issue.

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

@@ -0,0 +1,13 @@
+## Game Design — Done Bar
+
+**Done:**
+- `docs/GDD.md` (Game Design Document) exists and covers all required sections: Overview, Core Loop, Game Mechanics, Progression System, Technical Constraints, and Art Direction.
+- Tuning parameters are externalized: every balance-critical value (player speed, damage, cooldown, score multipliers) is defined as a named parameter with its default value and valid range documented in the GDD (format: `parameter_name: default (range: min–max)`). No magic numbers hardcoded in engine scripts without a GDD reference.
+- A playtest loop is defined: the GDD specifies at minimum one measurable success criterion per core loop iteration (e.g., "average session length > 8 minutes", "level 1 completion rate > 70%").
+- Art and audio direction are present: the GDD includes a visual style reference (mood board description or reference images) and an audio/music direction note.
+
+**Not done:**
+- Tuning values are hardcoded in source files with no GDD parameter reference.
+- The core game loop has no session-level layer (the player has no reason to return after one play session).
+- Art or audio direction is absent ("TBD" does not count).
+- The GDD exists but is a skeleton with no actual design decisions filled in.