@starlein/paperclip-plugin-company-wizard 0.3.22 → 0.3.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "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",
@@ -28,7 +28,9 @@
   },
   "files": [
     "dist/",
-    "templates/"
+    "templates/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
   ],
   "paperclipPlugin": {
     "manifest": "./dist/manifest.js",

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

@@ -1,30 +1,25 @@
-# Skill: Code Review
+# Skill: Code Review (advisory)
 
-You review PRs for correctness, security, code quality, and simplicity. You are a required reviewer — you are the participant of a `review` stage on the PR's issue, and your verdict gates the merge.
+You provide an **advisory, non-binding** code review. You are *not a merge gate*: the merge is gated by executed verification — green CI, or QA running the tests (see `docs/pr-conventions.md`). Your value is a second pair of eyes on correctness, clarity, and simplicity that automated checks miss.
 
-## Review Checklist
+## What to look for
 
-1. **Correctness** — Does the code do what it claims? Are edge cases handled? Does the logic match the intent described in the PR?
-2. **Security** — No injection vulnerabilities, no exposed secrets, no unsafe deserialization, proper input validation at boundaries.
-3. **Code style** — Consistent with project conventions. Naming is clear and descriptive. No dead code or commented-out blocks.
-4. **Simplicity** — Is the solution the simplest that works? Are abstractions justified? Could anything be removed without losing functionality?
-5. **Error handling** — Are failures handled gracefully? Are errors logged with context? Do error messages help debugging?
-6. **Performance** — No obvious N+1 queries, unbounded loops, or unnecessary allocations. Flag only clear issues, not micro-optimizations.
-7. **Test coverage** — Are new code paths tested? Are tests meaningful (test behavior, not implementation)?
+1. **Correctness** — Does the code do what the PR claims? Are edge cases handled? Does the logic match the stated intent?
+2. **Simplicity** — Is this the simplest solution that works? Could anything be removed without losing functionality?
+3. **Clarity** — Naming, structure, comments. Will the next reader understand this?
+4. **Security smells** — Obvious injection, exposed secrets, missing validation at boundaries. Defer deep security review to the Security Engineer when the change is security-relevant.
+5. **Dead code** — Commented-out blocks, unused branches.
 
-## How to Review
+## How to comment
 
-1. When you are the active participant of a review stage on an issue with a PR link, review the PR diff (check out locally if useful).
-2. Record your verdict on your review stage:
-   - **approved** if the code meets quality standards
-   - **changes_requested** with specific, actionable feedback if not
-3. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+1. When the PR has a review stage assigned to you, read the diff (check it out locally if useful).
+2. Post your feedback as a GitHub PR comment via a Markdown file: open with a heading (`## 💬 Review notes`), then specific, actionable points, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — `\n` stays literal in a double-quoted shell string. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. If you are a participant on an advisory review stage, record your notes there too — but understand it does not gate the merge.
 
 ## Rules
 
 - Be constructive — suggest alternatives, don't just criticize.
-- Focus on substance over style. Auto-formatters handle style.
-- "Looks good" is not a review. Be specific about what you verified.
-- Block on correctness, security, and clear bugs. Suggest on style and optimization.
-- If a PR is too large to review effectively, request it be split.
-- Your review stage verdict is the governance signal. Do not block only because GitHub rejects formal review submission from the shared PR-author credential — GitHub-native approval is optional unless a distinct non-author reviewer credential is explicitly available.
+- Focus on substance over style; auto-formatters handle style.
+- "Looks good" is not useful feedback. Point at what you actually examined.
+- Raise correctness or security concerns clearly so QA / the Security Engineer / the Engineer can act on them before merge.
+- You do not gate the merge. If something must block, it belongs to QA (tests), the Security Engineer (security-relevant), or CI.

package/templates/modules/pr-review/agents/qa/skills/qa-review.md

@@ -1,29 +1,50 @@
 # Skill: QA Review
 
-You review PRs for test coverage, edge cases, and regression risk. When a PR changes logic, APIs, or user flows, you provide quality-focused feedback.
+You are the **substantive review gate** for pull requests. Review is by *doing*, not by reading: your verdict must rest on tests that actually ran. "Looks good" is not a review.
 
-## Review Checklist
+## Two modes
 
-1. **Test coverage** — Are new code paths covered by tests? Are edge cases tested?
-2. **Regression risk** — Could this change break existing functionality? Are affected areas covered by existing tests?
-3. **Error handling** — Are failure modes handled? Are error paths tested?
-4. **Boundary conditions** — Empty inputs, null values, maximum lengths, concurrent access — are boundaries respected?
-5. **Data validation** — Is user input validated at system boundaries? Are API contracts enforced?
-6. **Test quality** — Do tests assert behavior, not implementation? Are they maintainable and readable?
-7. **Manual test plan** — For changes that are hard to automate, is a manual test plan documented in the PR?
+**CI is configured (hard gate = CI):**
+Your job is to ensure the tests *mean something*. Green CI on a change with no real coverage is worthless. Verify:
+- New code paths and edge cases are covered by tests that CI runs.
+- Tests assert behavior, not implementation.
+- Regression risk is covered.
+- The CI build job is green, not only the test job.
+Record `approved` only when CI is green AND coverage is adequate. If coverage is inadequate, record `changes_requested` with the specific missing test cases — even if CI is green.
 
-## How to Review
+**No CI configured (you are the gate):**
+There is no machine arbiter, so you run it. Check out the branch, run the full test suite and the build locally, and paste the **real command output** into your stage-record verdict. A verdict without execution output is invalid.
 
-1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
-2. Focus on test coverage, regression risk, and validation strategy.
-3. Record your verdict on your review stage:
-   - **approved** if quality is adequate
-   - **changes_requested** with specific gaps and suggested test cases if not
-4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+Replace `<branch>` with the PR branch name and substitute your project's actual test and build commands:
+
+```bash
+git fetch origin && git checkout <branch>
+<the project's test command>   # e.g. pnpm test, pytest, go test ./...
+<the project's build command>  # e.g. pnpm build
+```
+
+Record `approved` only if the suite and build pass and coverage is adequate; otherwise `changes_requested` with the failing output and the gaps.
+
+## Review checklist
+
+1. **Test coverage** — new code paths and edge cases covered?
+2. **Regression risk** — could this break existing behavior? Is the affected area covered?
+3. **Error handling** — failure modes handled and tested?
+4. **Boundary conditions** — empty/null/max/concurrent inputs respected?
+5. **Data validation** — input validated at boundaries; API contracts enforced?
+6. **Test quality** — tests assert behavior; readable and maintainable?
+7. **Manual test plan** — for hard-to-automate changes, is a manual plan documented in the PR?
+
+## How to record your verdict
+
+1. You are the active participant of a `review` stage on the issue carrying the PR link.
+2. Record on your stage: `approved` (with the evidence — commands + results) or `changes_requested` (with specific gaps and suggested test cases).
+3. Optionally mirror the verdict as a GitHub PR comment via a Markdown file: open with a heading (`## ✅ Approved` / `## 🔄 Changes requested`), then details, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 
+- A verdict that does not cite executed verification (CI green, or your pasted test/build output) is invalid.
 - Be constructive — suggest specific test cases, don't just say "needs more tests".
-- Flag untested critical paths as blockers. Flag untested non-critical paths as suggestions.
-- Approve trivial changes (docs, comments, config) without comment.
-- If CI is missing or broken, flag it — tests that don't run don't count.
+- Flag untested critical paths as blockers; untested non-critical paths as suggestions.
+- Approve trivial changes (docs, comments, config) without ceremony.
+- If CI is missing or broken, that is a blocker — tests that don't run don't count.

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

@@ -0,0 +1,27 @@
+# Skill: PR Security Review
+
+You review a **specific PR's diff** for security-relevant changes. You are added as a `review` stage **only when the change touches** authentication, authorization, secrets, input boundaries, cryptography, dependencies, or infrastructure exposure — i.e. when it is security-relevant. (For broader threat modeling, see your `security-review` skill from the security-audit module, if present.)
+
+Review is by *probing*, not by reading. Your verdict must state what you actually checked.
+
+## What to probe
+
+1. **Input boundaries** — Is all external input validated and encoded? Any injection surface (SQL, command, path, template)?
+2. **AuthN/AuthZ** — Are new endpoints/actions access-controlled? Any privilege escalation or missing ownership check?
+3. **Secrets** — No secrets in code, logs, or error messages. Secret handling uses the established mechanism.
+4. **Crypto** — No home-grown crypto; correct, current algorithms and key handling.
+5. **Dependencies** — New/updated deps: known vulnerabilities? Is the source trustworthy?
+6. **Data exposure** — Does the change leak data in responses, logs, or errors beyond what's intended?
+
+## How to record your verdict
+
+1. You are the active participant of a `review` stage on the issue carrying the PR link.
+2. State **what you probed and how** (e.g. "checked the new `/upload` endpoint for path traversal with `../` inputs; validated the content-type allowlist"). A verdict without concrete checks is invalid.
+3. Record `approved` (with the checks performed) or `changes_requested` (with the specific finding, its impact, and a remediation).
+4. Optionally mirror as a GitHub PR comment via a Markdown file (`## ✅ Approved` / `## 🔄 Changes requested`), run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+
+## Rules
+
+- Block on exploitable issues (injection, auth bypass, secret exposure). Suggest on defense-in-depth hardening.
+- Be specific: name the input, the path, the impact. "Looks secure" is not a review.
+- If the change is not actually security-relevant, say so briefly and approve — don't manufacture findings.

package/templates/modules/pr-review/docs/pr-conventions.md

@@ -51,7 +51,6 @@ EOF
 
 gh pr create  --title "<type>: <description>" --body-file /tmp/pr-body.md
 gh pr comment <number> --body-file /tmp/pr-body.md
-gh pr review  <number> --request-changes --body-file /tmp/pr-body.md
 ```
 
 Every PR comment opens with a Markdown heading stating the verdict (`## ✅ Approved`, `## 🔄 Changes requested`, or `## 💬 Review notes`), followed by a short summary and bullet points or code blocks.
@@ -62,35 +61,45 @@ Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
 
 ## Review Workflow
 
-Review runs through the issue's native `executionPolicy` (stages), not separate child issues:
-
-1. **Engineer** opens the PR on GitHub.
-2. **Engineer** sets the originating issue's `executionPolicy`: a `review` stage for the Code Reviewer, optional `review` stages for relevant domain reviewers (UI Designer / UX Researcher / QA / DevOps), an `approval` stage for the Product Owner (product sign-off), and a final `approval` stage for the **Engineer** as the merge gate. Reviewer/approver/merge-owner roles are resolved to agentIds. The PR link is added as an issue comment.
-3. **Engineer** sets the originating issue to `in_review`.
-4. **Code Reviewer** reviews for correctness, security, code style, simplicity and records `approved` / `changes_requested` on the review stage.
-5. **Domain reviewers** (when present as stages) review their concern and record their verdict.
-6. **Product Owner** reviews for intent match, scope discipline, acceptance criteria, and records the final `approval` verdict.
-7. Verdicts are recorded on the stages and may be mirrored as PR comments (always via `--body-file`; see *Posting PR Bodies & Comments*).
-8. **Engineer** owns the final `approval` stage (merge gate): once every reviewer and the Product Owner has approved, the engineer is woken last, merges the PR, confirms the merge landed, and only then records `approved` — which closes the originating issue to `done`. The merge must happen before the issue is `done`.
+Review runs through the issue's native `executionPolicy` (stages), not separate child issues. The gate is **executed verification, not opinion**.
+
+1. **Engineer** opens the PR on GitHub and adds the PR link as an issue comment.
+2. **Engineer** sets the originating issue's `executionPolicy` stages, in order:
+   - a `review` stage for **QA** when a QA agent is on the team (test adequacy / running the tests),
+   - a `review` stage for the **Security Engineer** *only when the change is security-relevant* (auth, secrets, input boundaries, crypto, dependencies, infra exposure),
+   - an `approval` stage for the **Product Owner** (intent, scope, acceptance),
+   - a final `approval` stage for the **Engineer** as the merge gate.
+   Resolve each role to its agentId.
+3. **Engineer** sets the issue to `in_review`.
+4. **QA** (when present) reviews and records `approved`/`changes_requested` with executed evidence (see *Merge Rules*).
+5. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.
+6. **Code Reviewer** and other domain reviewers may add **advisory, non-blocking** PR comments. They do not gate the merge.
+7. **Product Owner** reviews for intent match, scope discipline, and acceptance criteria, and records the `approval` verdict.
+8. **Engineer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the engineer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR, confirms the merge landed, and only then records `approved` — which closes the issue to `done`. The merge must happen before the issue is `done`.
 
 ## Review Roles
 
-- **Code Reviewer** (`review` stage): Correctness, security, style, simplicity.
-- **Domain reviewers** (`review` stages, when relevant): UI Designer (visual/brand/accessibility), UX Researcher (flows/usability), QA (coverage/regression), DevOps (infra/security/rollback).
-- **Product Owner** (`approval` stage): Intent alignment, scope discipline, acceptance criteria — the final sign-off.
-
-Reviewers may also add a PR comment, but GitHub-native approving reviews require distinct non-author GitHub credentials and are optional.
+- **QA** (`review` stage, when present): the substantive gate. Test coverage, regression risk, and validation — backed by tests that actually ran.
+- **Security Engineer** (`review` stage, only when the change is security-relevant): probes the diff for injection, auth, secrets, crypto, dependency, and exposure issues.
+- **Product Owner** (`approval` stage): intent alignment, scope discipline, acceptance criteria.
+- **Engineer** (`approval` stage, last): the merge gate and hard-gate backstop — see *Merge Rules*.
+- **Code Reviewer / domain reviewers** (advisory): optional, non-blocking comments on correctness, clarity, design, accessibility, UX. They never gate the merge.
 
 ## Merge Rules
 
-- Code Reviewer `review` stage and Product Owner `approval` stage must be approved (required)
-- Other reviewers provide advisory feedback — blocking only for their domain-critical issues (e.g., security for DevOps, accessibility for UI Designer)
-- CI must pass
-- Do not configure GitHub branch protection to require approving reviews unless the project has distinct non-author GitHub reviewer credentials; all agents using one GitHub account cannot formally approve their own PRs
-- No force pushes
-- Merge using `gh pr merge <number> --merge`
-- Engineer is the merge owner — reviewers never merge
+The hard gate is **executed verification**, enforced on the Engineer's merge-gate stage and independent of which reviewers are present:
+
+- **With CI:** CI (lint/test/build) must be **green** before the Engineer merges. This is machine-verified and cannot be skipped.
+- **Without CI:** the Engineer must run the full test suite and build locally and paste the real output into the merge-gate verdict before merging. (When QA is present, QA already produced this evidence; the Engineer confirms it.)
+- A verdict that does not cite executed verification — green CI, or pasted test/build output — is not valid.
+- The Product Owner's `approval` stage must be approved.
+- QA's `review` stage (when present) and the Security Engineer's `review` stage (when added) must be approved.
+- The Code Reviewer and other domain reviewers are advisory — blocking only when they escalate a concern that QA, the Security Engineer, or the Engineer then acts on.
+- No force pushes.
+- Merge using `gh pr merge <number> --merge`.
+- The Engineer is the merge owner — reviewers never merge.
 - The engineer's merge gate must be the **last** `approval` stage. If the Product Owner's approval were last, it would auto-close the issue to `done` and the merge would be skipped, leaving the PR open on GitHub.
+- Do not configure GitHub branch protection to require approving reviews unless the project has distinct non-author GitHub reviewer credentials; all agents using one GitHub account cannot formally approve their own PRs.
 
 ## Dev Cycle Rules
 

package/templates/modules/pr-review/module.meta.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-review",
-  "description": "Coordinates pull request reviews through the issue's native executionPolicy (review/approval stages) instead of separate child issues. Reviewers may mirror verdicts as PR comments, but GitHub-native approvals require distinct non-author GitHub credentials.",
+  "description": "Coordinates substantive PR review through the issue's native executionPolicy. The merge gate is executed verification — green CI, or the engineer running the tests/build and pasting the output — not opinion. QA is the substantive reviewer when present; the Security Engineer reviews only security-relevant changes; the Code Reviewer is advisory.",
   "requires": [
     "github-repo"
   ],
@@ -11,6 +11,7 @@
     "ui-designer",
     "ux-researcher",
     "qa",
+    "security-engineer",
     "devops"
   ],
   "capabilities": [],
@@ -20,11 +21,11 @@
       "bootstrapPhase": "foundation",
       "assignTo": "engineer",
       "reviewGate": {
-        "reviewers": ["code-reviewer"],
+        "reviewers": ["qa"],
         "approver": "product-owner",
         "mergeGate": "engineer"
       },
-      "description": "Document and verify the PR workflow: feature branches, PR links, and review via the issue's executionPolicy — a review stage for the Code Reviewer (plus relevant domain reviewers), an approval stage for the Product Owner, and a final approval stage for the Engineer as the merge gate (the engineer is woken last to merge the PR before recording approval, which closes the issue). The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. Optional branch protection may disable direct pushes or require CI, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
+      "description": "Document and verify the PR workflow via the issue's executionPolicy. The merge gate is executed verification: with CI, builds must be green before merge; without CI, the engineer runs the test suite/build and pastes the output before merging. Stages: a review stage for QA when present, a review stage for the Security Engineer only on security-relevant changes, an approval stage for the Product Owner, and a final approval stage for the Engineer as the merge gate (woken last to merge the PR before recording approval, which closes the issue). The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. The Code Reviewer and other domain reviewers add advisory, non-blocking comments. Optional branch protection may disable direct pushes, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
     }
   ]
 }

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

@@ -15,7 +15,7 @@ You report to the CEO.
    - **Security**: Any injection, XSS, credential exposure, or OWASP risks?
    - **Style**: Consistent with existing codebase patterns?
    - **Simplicity**: Is there unnecessary complexity? Could it be simpler?
-6. Post your review: `gh pr review <number> --approve`, or to request changes write your feedback to a Markdown file (start with a heading, e.g. `## 🔄 Changes requested`) and run `gh pr review <number> --request-changes --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown.
+6. Post your review as **advisory** feedback: write it to a Markdown file (start with a heading, e.g. `## 💬 Review notes` or `## 🔄 Changes requested`) and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown. Your review does not gate the merge — that gate is QA + CI (and the Security Engineer on security-relevant changes); do not submit a GitHub-native approving review, since all agents share one GitHub account.
 7. Post your verdict on the originating issue.
 8. Mark your issue as `done`.
 

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

@@ -16,7 +16,7 @@
 - Read issue comments for PR link.
 - Fetch diff: `gh pr diff <number>`.
 - Review for correctness, security, style, simplicity.
-- Post review via `gh pr review`.
+- Post advisory feedback via `gh pr comment <number> --body-file <file>` (your review does not gate the merge — QA + CI do).
 - Comment verdict on the originating issue.
 - Mark issue done.