@starlein/paperclip-plugin-company-wizard 0.3.19 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "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/accessibility/skills/accessibility-audit.bar.md

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good accessibility audit:
+
+- A `docs/ACCESSIBILITY-AUDIT.md` covering WCAG 2.2 AA across: semantic HTML, keyboard navigation, colour contrast, ARIA usage, images/media, forms, and zoom/responsive behaviour.
+- Each finding has a severity (Critical / Major / Minor), a specific location, and a concrete remediation — Critical and Major findings have follow-up issues created.
+
+Not done:
+
+- A scan dump with no remediation priorities — a raw list of automated-tool violations with no severity ranking and no recommended fixes is not done.
+- An audit that only runs an automated checker without testing keyboard-only navigation or verifying focus indicators manually.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good design system deliverable:
+
+- Defines reusable tokens (spacing, colour, type, radius) and the components built from them, with usage rules and do/don't examples.
+- States how engineers consume it (where tokens live, naming, theming) so implementation matches the spec without guesswork.
+
+Not done:
+
+- Tokens with no usage guidance, or one-off values that bypass the scale.
+- A component gallery with no states (hover, focus, disabled, error) defined.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good architecture plan:
+
+- A `docs/ARCHITECTURE.md` with a system overview (text/ASCII component diagram), data flow through the system, API boundaries (internal and external), deployment model, and key decisions recorded in ADR style with rationale.
+- Decomposed into concrete implementation issues for foundational scaffolding so work can start incrementally.
+
+Not done:
+
+- A diagram with no data flow or failure modes — components drawn without explaining how data moves or what happens when a dependency is unavailable.
+- Decisions recorded without rationale — "we use a monorepo" with no explanation of why that fits the requirements.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+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`.
+- The backlog maintains at least 3 unassigned, ready-to-work issues; if the queue drops below that threshold, new ones are created from the roadmap and the action is recorded in daily notes.
+
+Not done:
+
+- Issues that are not INVEST-shaped — a title with no acceptance criteria, no label, or no project link is not done.
+- Creating duplicate issues without first checking existing open issues, or creating more issues when the goal is already fully decomposed.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good brand identity:
+
+- A `docs/BRAND-IDENTITY.md` with concrete values and rationale for every element: colour palette (hex/RGB values with contrast ratios), typography (typefaces, size scale, weight usage), logo usage rules (clear space, do's and don'ts), iconography style, and tone of voice.
+- If a tech stack exists, a design tokens file (CSS custom properties or JSON) matching the chosen stack, so the identity is immediately usable in code.
+
+Not done:
+
+- A palette with no usage rules — listing hex colours without specifying which is primary, when to use each, or whether they meet WCAG AA contrast is not done.
+- Brand choices without rationale — "we picked blue" with no connection to the target audience, brand attributes, or existing constraints.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good API design:
+
+- A `docs/API-DESIGN.md` with a resource model, full endpoint inventory (method, path, auth requirement), authentication strategy, error-handling conventions (consistent error shape), and pagination approach.
+- Every endpoint has: description, parameter types and constraints, request/response schema, example request/response, and possible error codes — generated from source annotations (OpenAPI/Swagger), not maintained by hand.
+
+Not done:
+
+- Endpoints with no auth or error contract — a list of URLs with no mention of who can call them or what error codes they return is not done.
+- A design that skips input validation at the boundary or uses a different error shape per endpoint.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good CI/CD setup:
+
+- A working pipeline with a CI stage (lint → typecheck → test on every PR and push to main) and a CD stage (deploy on merge to main, smoke tests after deployment), documented in `docs/CI-CD.md` with status badges in the README.
+- Pipelines complete in under 5 minutes (dependency caching in place), action versions pinned to full SHAs, and all secrets stored in GitHub Secrets or equivalent — none in workflow files.
+
+Not done:
+
+- A pipeline with no rollback path — deploying with no documented procedure for reverting a bad release or re-running the previous successful build is not done.
+- A pipeline that breaks main and is not fixed immediately, or one that stores secrets directly in the workflow YAML.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good codebase audit:
+
+- A `docs/CODEBASE-AUDIT.md` with architecture overview (layers, key components, data flow), tech stack summary, tech debt inventory ranked by severity (critical / major / minor), test coverage assessment identifying untested paths, and recommended cleanup priorities.
+- Followed by concrete, scoped follow-up issues — one per fix — for the top cleanup opportunities.
+
+Not done:
+
+- An audit with no prioritised tech-debt list — noting "there is some debt" without ranking it by severity or impact is not done.
+- An audit that describes the code structure without assessing test coverage or identifying actionable cleanup items.

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

@@ -21,6 +21,18 @@ Rules:
 - Under 72 characters
 - Reference issue ID in commit body when applicable
 
+## Repository Hygiene: ignore `.paperclip/`
+
+Paperclip stores per-issue git worktrees and workspace metadata under a `.paperclip/`
+directory inside the repository. This must never be committed.
+
+- When preparing the repository (fresh or existing), make sure `.gitignore` contains a
+  `.paperclip/` line. Add it before the first commit; create `.gitignore` if missing.
+- If `.paperclip/` was already committed, remove it from tracking with
+  `git rm -r --cached .paperclip` and commit the removal.
+- Committing `.paperclip/` pollutes history and can nest isolated worktrees inside the
+  repo, which causes confusing git state for every agent.
+
 ## Direct-to-Main Workflow
 
 1. Pull latest from main

package/templates/modules/github-repo/module.meta.json

@@ -9,7 +9,7 @@
       "priority": "critical",
       "bootstrapPhase": "foundation",
       "labels": ["chore"],
-      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize local workspace with a README or bootstrap commit, add origin, push main, and record the repository URL. For an existing repository, verify the workspace has a reachable remote, current default branch, and starter commit state; escalate to CEO if repo setup is missing instead of silently closing the issue. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
+      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize local workspace with a README or bootstrap commit, add origin, push main, and record the repository URL. For an existing repository, verify the workspace has a reachable remote, current default branch, and starter commit state; escalate to CEO if repo setup is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
     }
   ]
 }

package/templates/modules/market-analysis/skills/market-analysis.bar.md

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good market analysis:
+
+- A `docs/MARKET-ANALYSIS.md` that covers: target market (who the users are and what problem is being solved), a competitor breakdown with each player's strengths and weaknesses, a clear positioning statement with a unique value proposition, and identified market/adoption risks.
+- Each insight is evidence-based and tied to a concrete product decision or follow-up action.
+
+Not done:
+
+- A competitor list with no positioning takeaway — naming five competitors without explaining how the product differentiates or what the strategic response is.
+- Vague assertions ("the market is growing") with no source, no specifics, and no actionable output.

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

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good monitoring setup:
+
+- Health check endpoints (liveness + readiness) for all services, error tracking with full context (request ID, user, stack trace), structured JSON logs with consistent fields (timestamp, level, service, correlation ID), and alert thresholds for key metrics (error rate, latency, uptime), all documented in `docs/MONITORING.md`.
+- Every alert is symptom-based (user impact), actionable, and has a runbook — no alert fires without a documented response.
+
+Not done:
+
+- Alerts with no runbook — an alert that fires with no documented steps for what to check or how to respond is not done.
+- Unstructured log strings, or alerts that fire on internal metric movement with no corresponding user-visible impact.

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

@@ -9,14 +9,15 @@ When this skill is active, you work in feature branches and open PRs instead of
 3. Make your changes, commit with Conventional Commits format
 4. Push branch: `git push -u origin <branch-name>`
 5. Open PR: `gh pr create --title "<type>: <description>" --body "<template>"`
-6. Set the originating issue's `executionPolicy` to gate the merge on review:
+6. Set the originating issue's `executionPolicy` to gate the merge on review, ending with your own merge gate:
    - One `review` stage with the **Code Reviewer** as participant (always).
    - Additional `review` stages for any relevant domain reviewer that exists in the team (UI Designer for UI diffs, UX Researcher for flow changes, QA for logic/test-sensitive changes, DevOps for infra/deploy/dependency changes).
-   - A final `approval` stage with the **Product Owner** as participant (always).
+   - An `approval` stage with the **Product Owner** as participant (always) — the product sign-off.
+   - A final `approval` stage with **yourself (the Engineer)** as participant — the **merge gate**. This stage exists so you are woken *last*, after every reviewer and the Product Owner have cleared, to perform the merge.
    - Resolve each role to its agentId first (look up active agents), then set the policy on the issue. Include the PR link in an issue comment so reviewers can find it.
 7. Move the originating issue to `in_review`.
-8. Wait for the issue to clear its stages. Each reviewer records `approved` or `changes_requested` on their stage; verdicts may be mirrored as PR comments.
-9. When all stages are approved (no `changes_requested` outstanding): `gh pr merge <number> --merge`, then set the issue to `done`.
+8. Wait for the issue to clear its review/approval stages. Each reviewer and the Product Owner records `approved` or `changes_requested`; 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.
+9. When the issue reaches your final **merge gate** stage (you are the current participant and every prior stage is approved): run `gh pr merge <number> --merge`, confirm the merge landed, **then** record `approved` on your stage — that closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never set the issue to `done` with the PR still open.
 
 ## Rules
 
@@ -25,5 +26,6 @@ When this skill is active, you work in feature branches and open PRs instead of
 - Always include `Closes [PREFIX-N]` in the PR body.
 - If a reviewer requests changes, address them, push to the same branch, and re-request review (the stage re-runs).
 - You are the merge owner — never ask reviewers to merge.
+- **Your merge gate must be the last stage.** The Product Owner's `approval` is the product sign-off, not the final stage. If it were last, their verdict would auto-close the issue to `done` and you would never be woken to merge — leaving the PR open on GitHub. Always append your own merge-gate `approval` stage after the Product Owner's, and do the merge there before recording your verdict.
 - Do not create separate child review issues and do not use @-mentions to request review; the executionPolicy stages are the governance signal.
 - Do not wait for GitHub-native approving reviews when all agents share the same GitHub credential; GitHub rejects self-approval. The Paperclip executionPolicy stages are the required signal unless a separate non-author GitHub reviewer credential is explicitly available.

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

@@ -47,13 +47,13 @@ Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
 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), and a final `approval` stage for the Product Owner. Reviewer/approver roles are resolved to agentIds. The PR link is added as an issue comment.
+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.
-8. **Engineer** merges when all stages are approved (no `changes_requested` outstanding), then sets the originating issue to `done`.
+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 Roles
 
@@ -72,6 +72,7 @@ Reviewers may also add a PR comment, but GitHub-native approving reviews require
 - No force pushes
 - Merge using `gh pr merge <number> --merge`
 - 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.
 
 ## Dev Cycle Rules
 

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

@@ -21,9 +21,10 @@
       "assignTo": "engineer",
       "reviewGate": {
         "reviewers": ["code-reviewer"],
-        "approver": "product-owner"
+        "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) and a final approval stage for the Product Owner, with engineer-owned merges once all stages clear. 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: 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."
     }
   ]
 }

package/templates/modules/security-audit/skills/security-review.bar.md

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good security review:
+
+- A `docs/SECURITY-REVIEW.md` with findings that include: severity (Critical / High / Medium / Low), exact file path and line number, the evidence (code snippet or reproduction step), and a specific recommended fix.
+- A dependency report with CVE details from `npm audit` or equivalent. Critical and High findings have follow-up issues created.
+
+Not done:
+
+- A finding with no exploit path, blast radius, or concrete fix — "there may be an injection risk here" without a reproduction path, affected data scope, or remediation is not done.
+- A review that flags secrets exposure as anything lower than Critical.

package/templates/modules/security-audit/skills/threat-model.bar.md

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good threat model:
+
+- A `docs/THREAT-MODEL.md` with a system overview that includes components, data flows, and explicit trust boundaries; STRIDE threats against the identified attack surfaces; a risk rating (Likelihood × Impact) for each threat; and mitigations for every Critical and High risk.
+- Critical and High risks have corresponding follow-up issues with specific remediation tasks.
+
+Not done:
+
+- A threat list with no trust boundaries or blast-radius — threats listed without identifying which components they affect, what data is at risk, or how far an attacker could move laterally.
+- Risk ratings with no mitigations — identifying threats without recommending controls leaves the model unactionable.

package/templates/modules/tech-stack/skills/tech-stack.bar.md

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good tech stack evaluation:
+
+- A `docs/TECH-STACK.md` that lists the chosen technology per layer (language, framework, database, infra) with version, the rationale for each choice, and the alternatives that were considered and rejected.
+- Covers at least: team familiarity, ecosystem maturity, performance trade-offs, and cost for each layer.
+
+Not done:
+
+- A stack pick with no rationale or rejected alternatives — "we'll use Postgres" with nothing else is not done.
+- A decision that ignores team capabilities or requires paid services without creating an approval request.

package/templates/modules/user-testing/skills/user-testing.bar.md

@@ -0,0 +1,11 @@
+## Output / review bar
+
+A good usability finding:
+
+- Names the task, the observation (with a quote or step trace), the severity, and a concrete recommendation.
+- Distinguishes evidence from interpretation, and reproducible issues from one-offs.
+
+Not done:
+
+- "Users were confused" with no task, no repro, and no severity.
+- A pass/fail with no evidence attached.

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

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

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

@@ -0,0 +1,11 @@
+## Domain Lenses
+
+Apply these when reviewing a change. Cite them by name in comments.
+
+- **Correctness first** — does it do what it claims, including the edge cases the author did not mention?
+- **Blast radius** — what else does this change touch, and what breaks if it is wrong?
+- **Readability & maintainability** — will the next agent understand this in six months without the author present?
+- **Test adequacy** — do the tests actually exercise the new behaviour, or just the happy path? A green suite that tests nothing is not coverage.
+- **Security smell** — untrusted input reaching shells/SQL/eval, secrets in the diff, broadened permissions; flag and route to the security owner.
+- **Smallest diff** — does the change do one thing? Unrelated churn hides bugs and bloats review.
+- **Approve the change, not the person** — findings cite the code and the risk, never the author.

package/templates/roles/devops/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/devops/LENSES.md

@@ -0,0 +1,12 @@
+## Domain Lenses
+
+Apply these when building or operating infrastructure. Cite them by name in comments.
+
+- **Error budgets** — reliability is a budget, not a goal of zero; spend it deliberately on change velocity.
+- **MTTR over MTBF** — optimise for fast, safe recovery; a fast rollback beats a rare failure.
+- **Rollback path first** — never ship a change you cannot undo; the rollback is part of the change.
+- **Canary vs full deploy** — expose risk to a small slice first; promote on signal, not on hope.
+- **Observability before launch** — if you cannot see it, you cannot operate it; metrics, logs, and alerts ship with the feature.
+- **Infrastructure as code** — every change is reviewable and versioned; no click-ops in production.
+- **Least-privilege IAM** — no wildcards in production policies; scope and rotate credentials.
+- **Idempotency** — pipelines and scripts must be safe to re-run; partial runs must not corrupt state.

package/templates/roles/engineer/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/product-owner/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/product-owner/LENSES.md

@@ -0,0 +1,11 @@
+## Domain Lenses
+
+Apply these when prioritising and shaping the backlog. Cite them by name in comments.
+
+- **RICE / ICE** — score by Reach, Impact, Confidence, Effort (or Impact, Confidence, Ease) before ranking; do not rank by loudness.
+- **MoSCoW** — separate Must / Should / Could / Won't for the current cut; protect the Musts.
+- **Kano model** — distinguish must-be, performance, and delight; do not trade a basic for a delighter.
+- **Opportunity cost** — saying yes to one item is saying no to another; name what this displaces.
+- **Outcome over output** — measure shipped value against the goal, not the count of issues closed.
+- **INVEST** — issues are Independent, Negotiable, Valuable, Estimable, Small, Testable; split anything that is not.
+- **WSJF** — when sequencing, weigh cost of delay against job size.

package/templates/roles/qa/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/security-engineer/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/security-engineer/LENSES.md

@@ -0,0 +1,16 @@
+## Domain Lenses
+
+Apply these when reviewing or designing. Cite them by name in comments so your reasoning is auditable.
+
+- **STRIDE** — walk Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege against each trust boundary.
+- **OWASP Top 10 (Web)** — broken access control, injection, crypto failures, misconfiguration, vulnerable components, auth failures, SSRF.
+- **OWASP API Top 10** — BOLA/IDOR, broken function-level authz, unrestricted resource consumption, mass assignment.
+- **OWASP LLM/agent Top 10** — prompt injection (direct + indirect), insecure output handling, excessive agency, tool/plugin design. Every tool call is a capability grant.
+- **Least privilege** — grant the narrowest access that works; drop it after use. Deny by default.
+- **Defense in depth** — never rely on one layer; validation + parameterized queries + scoped DB user is the baseline, not paranoia.
+- **Fail closed** — when a check errors, deny. The insecure path must never be the easy path.
+- **Blast radius** — for any finding, state what an attacker gets, whose data, and whether it pivots.
+- **AuthN ≠ AuthZ** — authentication does not imply authorization; check both, every access, every time.
+- **Secrets hygiene** — never in source, logs, URLs, or error messages; use a secrets manager and constant-time comparison.
+- **Supply-chain trust** — pin and audit dependencies; be wary of typosquats and freshly published packages from unknown maintainers.
+- **Disclosure discipline** — never discuss unpatched vulnerabilities or PoCs outside the ticket or a private advisory channel.

package/templates/roles/ui-designer/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/ui-designer/LENSES.md

@@ -0,0 +1,13 @@
+## Domain Lenses
+
+Apply these when producing or reviewing visual and brand work. Cite them by name in comments.
+
+- **Gestalt principles** — proximity, similarity, closure, continuity; group related elements and separate unrelated ones.
+- **Visual hierarchy** — size, weight, colour, and spacing must guide the eye to the most important element first.
+- **Type scale & rhythm** — a consistent modular scale and vertical rhythm; no arbitrary one-off font sizes.
+- **Contrast & WCAG** — text and interactive elements meet contrast minimums; colour is never the only signal.
+- **Design tokens & consistency** — spacing, colour, and radius come from tokens, not magic numbers; reuse before inventing.
+- **Affordance & signifiers** — interactive elements look interactive; the design tells the user what they can do.
+- **Progressive disclosure** — reveal complexity only when needed; default to the simplest useful view.
+- **Brand coherence** — voice, colour, and typography stay consistent with the brand book across every surface.
+- **Render truth** — judge against the rendered surface (a screenshot or live view), not the spec; "looks right in Figma" is not done.

package/templates/roles/ux-researcher/DONE.md

@@ -0,0 +1,10 @@
+## Done criteria
+
+Before you mark an issue done, verify the work — do not hand off on faith:
+
+- Run the smallest check that proves it: the relevant tests, a screenshot, a query, or a re-read of the spec against the result. State which check you ran.
+- Put the evidence in your final comment: what changed, how you verified it, and any residual risk or follow-up that needs its own ticket.
+- Reassign deliberately on completion — to a reviewer, to your manager, or to `done`. Never leave a finished task silently assigned to yourself.
+- If the success condition was not described, pick a sensible one, state it, and check against it before finishing.
+
+You must always update your task with a comment before exiting a heartbeat — even when blocked. If you are blocked, name the blocker, the owner who can unblock it, and your best guess at the fix.

package/templates/roles/ux-researcher/LENSES.md

@@ -0,0 +1,14 @@
+## Domain Lenses
+
+Apply these when evaluating flows and grounding product decisions. Cite them by name in comments.
+
+- **Nielsen's 10 heuristics** — visibility of status, match to the real world, user control, consistency, error prevention, recognition over recall, flexibility, minimalist design, help users recover, documentation.
+- **Jakob's Law** — users spend most of their time on other products; honour established conventions before inventing new ones.
+- **Hick's Law** — decision time grows with the number and complexity of choices; reduce options at decision points.
+- **Fitts's Law** — time to a target depends on its size and distance; primary actions are large and close.
+- **Recognition over Recall** — show options rather than forcing the user to remember them.
+- **Tesler's Law** — irreducible complexity must live somewhere; move it off the user and into the system where possible.
+- **Kano model** — separate must-be, performance, and delight features; do not polish delighters while basics are broken.
+- **Jobs-to-be-Done** — frame findings around the progress the user is trying to make, not demographics.
+- **Evidence over opinion** — a finding without an observation, quote, or metric is a hypothesis; label it as one.
+- **WCAG POUR** — perceivable, operable, understandable, robust; accessibility failures are usability failures.