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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.7",
+  "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/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:
+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.
-4. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
+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/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/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/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.

package/templates/modules/github-repo/agents/engineer/skills/git-workflow.md

@@ -17,11 +17,12 @@ Use this flow when the **pr-review module is not active**. You open a PR and mer
 7. Run available checks (lint, typecheck, tests)
 8. Commit using Conventional Commits: `<type>: <description>`
 9. Verify the current branch one more time, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-10. Open a pull request against the base ref: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Write the PR body (summary, what changed, how to verify) to a temp file first — never inline `--body "..."`. Register the PR as a Paperclip work product (see *Register the PR as a Work Product* below). Verify the PR base matches the configured base ref before merging.
-11. Merge the PR yourself: `gh pr merge <PR-number> --merge`. After opening the PR, merge it yourself promptly — do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing.
-12. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local). Update the Paperclip work product to `"status": "merged"` via `PATCH /api/work-products/{workProductId}`.
-13. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
-14. If CI fails on the base branch after the merge, fix immediately.
+10. Open a pull request against the base ref: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body to a temp file first — never inline `--body "..."`. Register the PR as a Paperclip work product (see *Register the PR as a Work Product* below). Verify the PR base matches the configured base ref before merging.
+11. Before merging, check that the PR is not conflicting: `gh pr view <PR-number> --json mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING` or `mergeStateStatus` is `DIRTY`, resolve the conflict before merging — see *Resolving merge conflicts* below.
+12. Merge the PR yourself: `gh pr merge <PR-number> --merge`. After opening the PR, merge it yourself promptly — do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing.
+13. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local). Update the Paperclip work product to `"status": "merged"` via `PATCH /api/work-products/{workProductId}`.
+14. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
+15. If CI fails on the base branch after the merge, fix immediately.
 
 ## Branch Protection Setup
 
@@ -80,11 +81,25 @@ Notes:
 - Never force push to the base branch.
 - Use the configured base ref. For external repos, branch and compare from the configured remote/ref and push/merge back to the matching remote branch.
 - Treat push authentication as repository setup, not as an issue blocker. If `git push` says credentials are missing or invalid, verify the helper and `GH_TOKEN` binding first.
-- If you encounter merge conflicts, resolve them carefully. When in doubt, escalate to the CEO.
+- If `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`, resolve the conflict before retrying — see *Resolving merge conflicts* below. Never leave a PR in an unresolved conflicting state without either fixing it or leaving an explicit issue comment with the blocker.
 - Reference the issue ID in the commit body (e.g., `Closes YES-5`).
 - Never mark an issue as `done` unless at least one new commit was created for that issue's work and has been pushed.
 - Before marking `done`, verify there is no uncommitted work (`git status --short` should be clean).
 - If no repository change is required, do not mark `done` silently: leave an issue comment explaining why no code change was needed and escalate to the CEO for decision.
 - You are always the merge owner when no code-reviewer is present. Open a PR and merge it yourself via `gh pr merge <N> --merge` promptly — do not leave branches dangling unmerged. Never do a direct `git merge` + push to the base branch; always go through a PR so the branch history is preserved and branch protection is respected (typos/comment-only/doc fixes with an issue reference may be committed directly to the base ref only when branch protection allows it — see `docs/git-workflow.md` → *Dev Cycle Rules*).
 - **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing. Verify with `git branch --show-current` before every push.
-- **Never push the base ref as if it were a feature branch.** Before `git push -u origin <branch-name>`, confirm that `git branch --show-current` matches `<branch-name>`. If it prints the base ref name instead, you are on the wrong branch — create or switch to the feature branch first.
+- **Never push the base ref as if it were a feature branch.** Before `git push -u origin <branch-name>`, confirm that `git branch --show-current` matches `<branch-name>`. If it prints the base ref name instead, you are on the wrong branch — create or switch to the feature branch first.
+
+## Resolving merge conflicts
+
+When `gh pr merge` fails or `gh pr view <N> --json mergeable,mergeStateStatus` returns `CONFLICTING` / `DIRTY`:
+
+1. `git fetch origin`
+2. `git checkout <branch-name>`
+3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve each conflict marker, then `git rebase --continue`.
+4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+5. `git push --force-with-lease origin <branch-name>` — never `--force`, use `--force-with-lease` to avoid overwriting concurrent pushes.
+6. Verify the conflict is gone: `gh pr view <N> --json mergeable` should return `MERGEABLE`.
+7. Retry the merge: `gh pr merge <N> --merge`.
+
+If the conflict is too complex to resolve safely (e.g., a large structural conflict with another in-flight PR), leave an issue comment describing the exact conflict and escalate to the CEO for prioritization before abandoning the branch.

package/templates/modules/github-repo/docs/git-workflow.md

@@ -94,7 +94,7 @@ Use this flow when the **pr-review module is not active** (no Code Reviewer role
 6. Run tests/linting locally if available
 7. Commit with conventional commit message
 8. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-9. Open a pull request against the base ref: write the PR body to a temp file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal (see *Posting PR Bodies & Comments* in `docs/pr-conventions.md`). Verify the PR base matches the configured base ref before merging.
+9. Open a pull request against the base ref: write the PR body to a temp file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal (see *Posting PR Bodies & Comments* in `docs/pr-conventions.md`). `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured ref `origin/main` → `--base main`; configured ref `main` → `--base main`). GitHub does not recognise remote-tracking names. Verify the PR base matches the configured base ref before merging.
 10. Merge the PR yourself: `gh pr merge <PR-number> --merge`. Do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing. Never do a direct `git merge` + push to the base branch; always go through a PR.
 11. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local).
 12. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context` after the merge is pushed.
@@ -145,6 +145,22 @@ For a brand-new local repository there is no remote yet, so initialize on `main`
 - **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing any changes. If you are resuming work on an existing issue, `git branch --show-current` should already show the feature branch name.
 - **Verify your branch before pushing.** Before running `git push -u origin <branch-name>`, confirm that `git branch --show-current` prints the feature branch name — not the base ref. If it prints the base ref, you are on the wrong branch: stop and create/switch to the feature branch first. Pushing the base ref as a feature branch corrupts upstream tracking and causes incorrect branch divergence reports.
 
+## Resolving merge conflicts
+
+When `gh pr merge` fails or `gh pr view <N> --json mergeable,mergeStateStatus` reports `CONFLICTING` / `DIRTY`:
+
+1. `git fetch origin`
+2. `git checkout <branch-name>`
+3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref first (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve each conflict marker, then `git rebase --continue`.
+4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+5. `git push --force-with-lease origin <branch-name>` — use `--force-with-lease`, never bare `--force`.
+6. Verify the conflict is resolved: `gh pr view <N> --json mergeable` should now return `MERGEABLE`.
+7. Retry: `gh pr merge <N> --merge`.
+
+Never leave a PR sitting in a conflicting state without either resolving it or leaving an explicit issue comment with the exact blocker. A dirty PR that is never merged or explicitly closed stalls the entire chain indefinitely.
+
+If the conflict is too complex to resolve safely (large structural conflict with another in-flight PR), comment on the issue with the exact conflict description and escalate to the CEO.
+
 ## CI
 
 If the project has CI configured (e.g., GitHub Actions), always verify your push passes CI. If CI fails, fix it immediately — a broken base ref blocks everyone.

package/templates/modules/market-analysis/docs/market-analysis-template.md

@@ -6,6 +6,23 @@
 - **Problem**: _What problem are we solving?_
 - **Market size**: _How big is the opportunity?_
 
+## User Segments
+
+### Primary Users
+- **Segment name**: [name]
+- **Description**: [who they are]
+- **Key needs**: [what they need from the product]
+- **Pain points**: [what frustrates them today]
+
+### Secondary Users
+- **Segment name**: [name]
+- **Description**: [who they are]
+- **Key needs**: [what they need from the product]
+- **Relationship to primary**: [how they interact with the primary user's workflow]
+
+### Edge Cases
+- [User groups or scenarios that the product must handle but that aren't core users]
+
 ## Competitive Landscape
 
 | Competitor | Strengths | Weaknesses | Differentiation |

package/templates/modules/monitoring/agents/engineer/skills/monitoring.fallback.md

@@ -5,7 +5,7 @@ The DevOps engineer primarily owns monitoring and observability. You are the fal
 ## Monitoring (Fallback)
 
 1. If no `docs/MONITORING.md` exists and DevOps hasn't started:
-   - Add basic health check endpoints (liveness probe returning 200)
+   - Add basic health check endpoints (liveness and readiness probes returning 200)
    - Set up structured JSON logging with timestamp, level, and service fields
    - Document the setup in `docs/MONITORING.md`
    - Mark the strategy as **provisional** — it needs DevOps review for alerting, dashboards, and SLOs

package/templates/modules/monitoring/skills/monitoring.md

@@ -9,7 +9,8 @@ You are responsible for setting up observability, alerting, and health checks fo
 3. Configure error tracking — capture unhandled exceptions with context (request ID, user, stack trace).
 4. Set up structured logging — all log output must be machine-parseable JSON with consistent fields.
 5. Define alert thresholds for key metrics (error rate, latency, uptime, resource usage).
-6. Document the full observability strategy in `docs/MONITORING.md`.
+6. Set up a basic operational dashboard (in the monitoring tool configured for this project) showing: request rate, error rate, latency (p50/p99), and the key health indicators defined above. Document the dashboard URL/name in `docs/MONITORING.md`.
+7. Document the full observability strategy in `docs/MONITORING.md`.
 
 ## Rules
 
@@ -18,3 +19,4 @@ You are responsible for setting up observability, alerting, and health checks fo
 - Log structured JSON — never log unstructured strings. Include timestamp, level, service, and correlation ID.
 - Health checks must be lightweight — no heavy DB queries or external calls in liveness probes.
 - Keep dashboards focused — one dashboard per concern (e.g., API latency, error rates, infrastructure).
+- Every alert definition must link to a runbook in `docs/` explaining: what triggered it, what to check first, and how to respond. No alert should fire without a runbook.

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

@@ -18,11 +18,25 @@ Paperclip's runtime **excludes the issue's original executor (the author) from e
 
 ## Merging
 
-1. Merge with `gh pr merge <number> --merge`. No force pushes.
-2. Confirm the merge landed on the correct base.
-3. If Paperclip created an isolated execution workspace for the issue, read its id from `heartbeat-context`, call close-readiness, and archive it after the merge and once the tree is clean. If cleanup is blocked or fails, do **not** record approval — leave the issue open with the exact blocker. If the issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
-4. **Only after the merge and cleanup succeed**, record `approved` (PATCH toward `done`) with a comment citing the executed verification and the merge confirmation. That closes the issue.
-5. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open.
+1. Before merging, check whether the PR branch is up to date with the base: `gh pr view <number> --json mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING` or `mergeStateStatus` is `DIRTY`, **do not attempt to merge** — go to *Merge conflicts* below first.
+2. Merge with `gh pr merge <number> --merge`. No force pushes.
+3. Confirm the merge landed on the correct base.
+4. If Paperclip created an isolated execution workspace for the issue, read its id from `heartbeat-context`, call close-readiness, and archive it after the merge and once the tree is clean. If cleanup is blocked or fails, do **not** record approval — leave the issue open with the exact blocker. If the issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
+5. **Only after the merge and cleanup succeed**, record `approved` (PATCH toward `done`) with a comment citing the executed verification and the merge confirmation. That closes the issue.
+6. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open.
+
+## Merge conflicts
+
+When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`:
+
+1. Record `changes_requested` on the issue immediately (do not leave it in `in_review` indefinitely) with a comment: "PR has merge conflicts with the base branch — returning to engineer to rebase."
+2. The issue routes back to the engineer (`returnAssignee`). The engineer must:
+   - `git fetch origin && git checkout <branch-name>`
+   - `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name (strip any `origin/` prefix from the configured base ref — e.g., configured `origin/main` → `git rebase origin/main`)
+   - Resolve all conflicts, run checks, commit
+   - `git push --force-with-lease origin <branch-name>`
+   - Leave an issue comment confirming the rebase, then move the issue back to `in_review`
+3. The issue re-enters the approval chain and returns to you. Re-run the hard verification gate before merging.
 
 ## When something is wrong
 

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

@@ -12,7 +12,7 @@ When this skill is active, you work in feature branches and open PRs instead of
 4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print your branch name, not the base ref. If it prints the base ref name, you forgot step 3 — create the branch now.
 5. Make your changes, commit with Conventional Commits format
 6. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-7. Open PR against the same resolved base: derive the GitHub base branch from the configured ref (for example, strip the remote prefix only when the ref is remote-tracking), write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (see *Posting PR Bodies & Comments*).
+7. Open PR against the same resolved base: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
 8. **Register the PR as a Paperclip work product** so it is visible on the issue and board (creating it on GitHub alone does not surface it in Paperclip):
    ```
    POST /api/issues/{issueId}/work-products
@@ -28,7 +28,7 @@ When this skill is active, you work in feature branches and open PRs instead of
    }
    ```
    `title` and `url` are required (`url` must be the full PR URL). If the issue runs in an isolated worktree, also pass `"executionWorkspaceId"` from `heartbeat-context`. When the PR later merges, update it with `PATCH /api/work-products/{id}` and `"status": "merged"`.
-9. **Only if a code-reviewer is present on the team:** Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate. If no code-reviewer is assigned to this company, skip steps 9–11 entirely and go directly to the self-merge path at step 12. Setting up executionPolicy stages without an eligible non-author merge gate will stall the issue permanently (`422 No eligible approval participant`).
+9. **Only if a code-reviewer is present on the team:** Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate. **Set executionPolicy stages before moving the issue to `in_review` (step 10) — changing stages after the issue has already entered review is not supported.** If no code-reviewer is assigned to this company, skip steps 9–11 entirely and go directly to the self-merge path at step 12. Setting up executionPolicy stages without an eligible non-author merge gate will stall the issue permanently (`422 No eligible approval participant`).
    - One `review` stage with **QA** when a QA agent exists (test adequacy / executed verification).
    - One `review` stage with the **Security Engineer** only when the change is security-relevant (auth, secrets, input boundaries, crypto, dependencies, infra exposure).
    - Domain reviewers (UI Designer, UX Researcher, DevOps) are advisory — they post PR comments and may flag a concern for QA, the Security Engineer, or the merge gate to act on. They are never themselves a review stage.
@@ -39,8 +39,24 @@ When this skill is active, you work in feature branches and open PRs instead of
 10. Move the originating issue to `in_review`.
 11. Wait for the issue to clear its review/approval stages. Each reviewer and the Product Owner records `approved` by PATCHing the issue toward `done`, or `changes_requested` by PATCHing it back to `in_progress`; Paperclip stores the reviewer/approver decision metadata on the issue. Verdicts may be mirrored as PR comments. A `changes_requested` routes the issue back to you — address it, push to the same branch, and that stage re-runs.
 12. **Merging the PR — two paths:**
-    - **Code Reviewer present (PR-Gate mode):** You do not merge your own PR. The Code Reviewer (the non-author merge gate) lands it after every prior stage approves, satisfies the hard verification gate (green CI or pasted test/build output), and records the final `approved` that closes the issue to `done`. Your job is to respond to `changes_requested`: when a stage routes the issue back to you, address the feedback, push to the same branch, and the stage re-runs.
-    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 9–11. Merge the PR yourself: `gh pr merge <N> --merge` once CI is green (or you have pasted test/build output if no CI). All other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR, but none block the merge — there are no executionPolicy stages. Update the Paperclip work product to `"status": "merged"` and archive any isolated worktree.
+    - **Code Reviewer present (PR-Gate mode):** You do not merge your own PR. The Code Reviewer (the non-author merge gate) lands it after every prior stage approves, satisfies the hard verification gate (green CI or pasted test/build output), and records the final `approved` that closes the issue to `done`. Your job is to respond to `changes_requested`: when a stage routes the issue back to you, address the feedback, push to the same branch, and the stage re-runs. If `changes_requested` is due to a merge conflict (the Code Reviewer will say so), see *Resolving merge conflicts* below.
+    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 9–11. Before merging, check `gh pr view <N> --json mergeable,mergeStateStatus` — if the PR is `CONFLICTING` or `DIRTY`, resolve the conflict first (see *Resolving merge conflicts* below). Then merge: `gh pr merge <N> --merge` once CI is green (or you have pasted test/build output if no CI). All other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR, but none block the merge — there are no executionPolicy stages. Update the Paperclip work product to `"status": "merged"` and archive any isolated worktree.
+
+## Resolving merge conflicts
+
+When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`:
+
+1. `git fetch origin`
+2. `git checkout <branch-name>`
+3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve all conflicts, then `git rebase --continue`.
+4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+5. `git push --force-with-lease origin <branch-name>`
+6. Confirm the PR is no longer conflicting: `gh pr view <N> --json mergeable` should return `MERGEABLE`.
+7. Leave an issue comment noting the rebase, then continue with the merge step.
+
+Never leave a PR with unresolved conflicts without either resolving them or explicitly routing the issue back (`changes_requested`) with a comment explaining the blocker. A dirty PR sitting in `in_review` stalls the entire chain.
+
+If the conflict is too complex to resolve safely (large structural conflict with another in-flight PR), leave an issue comment with the exact conflict description and escalate to the CEO for prioritization.
 
 ## Rules
 

package/templates/modules/release-management/agents/ceo/skills/release-process.fallback.md

@@ -0,0 +1,20 @@
+# Skill: Release Process (CEO Fallback)
+
+You are acting as a fallback for this capability because neither a devops agent nor an engineer is currently on the team. **Do not execute releases** — your role is to ensure release conventions are documented and a proper release owner is hired.
+
+## What you should do
+
+1. Check if `docs/RELEASE-PROCESS.md` exists. If not, create it with:
+   - Versioning convention (SemVer: `MAJOR.MINOR.PATCH`)
+   - Branch and tagging strategy (e.g., tag `vX.Y.Z` on the default branch after each release)
+   - Changelog format: Conventional Commits → CHANGELOG.md grouping
+   - Note: "This document was created by the CEO as a placeholder. A devops or engineer agent should implement and automate the release pipeline."
+2. Check if the project has a CHANGELOG.md. If not, create one with a `## Unreleased` section listing the current commits since the last tag (use `git log --oneline`).
+3. Create a follow-up issue: "Implement automated release pipeline" assigned to `capability:ci-cd` or directly to an engineer, linking to `docs/RELEASE-PROCESS.md`.
+4. Mark this issue done. **Do not push tags, create GitHub releases, or modify version files** — those actions require a devops or engineer agent.
+
+## Rules
+
+- Never execute `git push --tags`, `gh release create`, or version-file bumps without a devops or engineer agent present.
+- Your output is documentation and a follow-up issue — not an executed release.
+- If an urgent release is needed, escalate to the board.

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

@@ -21,5 +21,14 @@
       "assignTo": "capability:release-process",
       "description": "Review the current release workflow. If one exists, document it in docs/RELEASE-PROCESS.md. If not, establish a semver + changelog workflow with tagging conventions."
     }
+  ],
+  "routines": [
+    {
+      "name": "Release readiness check",
+      "description": "Check for unreleased changes and cut a release if warranted.",
+      "assignTo": "capability:release-process",
+      "schedule": "0 9 * * 1",
+      "concurrencyPolicy": "forbid"
+    }
   ]
 }

package/templates/modules/release-management/skills/release-process.md

@@ -29,12 +29,14 @@ You are responsible for managing the release lifecycle — versioning, changelog
    - Create the release commit and tag
    - Create a GitHub Release with notes: `gh release create vX.Y.Z --notes "..."`
 
-## Ongoing
+## Ongoing Release Readiness (Routine-Triggered)
 
-On each heartbeat:
-1. Check if unreleased changes have accumulated — review commits since last tag.
-2. If significant changes exist without a release, flag it or initiate a release.
-3. Ensure CHANGELOG.md stays up to date with merged work.
+When assigned a "Release readiness check" routine-run issue:
+
+1. Check if unreleased changes have accumulated since the last release: `git log <last-tag>..HEAD --oneline`. If no unreleased commits, mark done.
+2. Review `docs/CHANGELOG.md` or commit log for breaking changes, new features, or bug fixes that warrant a version bump.
+3. Run the full test suite and build. If failing, create a blocking issue and escalate before continuing.
+4. If a release is warranted, follow the release steps in the *Setup* section of this skill to cut the release. Otherwise leave a comment noting the check result and mark the routine issue done.
 
 ## Rules
 

package/templates/modules/triage/agents/ceo/skills/issue-triage.fallback.md

@@ -4,11 +4,11 @@ The Product Owner or Engineer primarily owns issue triage. You are the fallback
 
 ## Issue Triage (Fallback)
 
-1. Check for untriaged GitHub issues: `gh issue list --state open --label ""`
+1. Check for untriaged GitHub issues: `gh issue list --state open --label "" --json number,title,body,labels,createdAt`
 2. If issues are piling up without responses:
    - Classify each as bug, feature, question, or invalid
    - Respond with a brief acknowledgment
-   - Create Paperclip tasks for actionable items with priority set
+   - Create Paperclip tasks for actionable items with priority set. When creating Paperclip issues from triaged GitHub items, include `executionWorkspaceSettings: { mode: 'isolated_workspace' }` in the issue creation payload.
    - Close duplicates and invalid issues with explanation
 3. If the Product Owner or Engineer is active and triaging, skip this entirely.