@starlein/paperclip-plugin-company-wizard 0.3.18 → 0.3.20

package/package.json

@@ -1,22 +1,9 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "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",
-  "scripts": {
-    "build": "node ./esbuild.config.mjs",
-    "build:rollup": "rollup -c",
-    "dev": "node ./esbuild.config.mjs --watch",
-    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
-    "test": "vitest run --config ./vitest.config.ts",
-    "test:logic": "node --test src/logic/*.test.js src/api/*.test.js",
-    "typecheck": "tsc --noEmit",
-    "build:prod": "NODE_ENV=production node ./esbuild.config.mjs",
-    "publish:npm": "npm publish --access public",
-    "prepublishOnly": "pnpm build:prod",
-    "prepare": "husky"
-  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -40,7 +27,10 @@
     "plugin",
     "workspace"
   ],
-  "author": "@lx-0 <https://github.com/lx-0>",
+  "author": "Sascha Pietrowski <sp@speednetwork.de>",
+  "contributors": [
+    "Yesterday AI (original @yesterday-ai/paperclip-plugin-company-wizard — template system, assembly logic, API client)"
+  ],
   "license": "MIT",
   "dependencies": {
     "class-variance-authority": "^0.7.1",
@@ -74,5 +64,16 @@
     "@paperclipai/shared": ">=2026.529.0",
     "react": ">=18",
     "react-dom": ">=18"
+  },
+  "scripts": {
+    "build": "node ./esbuild.config.mjs",
+    "build:rollup": "rollup -c",
+    "dev": "node ./esbuild.config.mjs --watch",
+    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:logic": "node --test src/logic/*.test.js src/api/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "build:prod": "NODE_ENV=production node ./esbuild.config.mjs",
+    "publish:npm": "npm publish --access public"
   }
-}
+}

package/templates/ai-wizard/interview-system.md

@@ -1,4 +1,4 @@
-You are the Clipper AI Wizard — an expert at assembling AI agent teams. You're enthusiastic but concise. Clipper bootstraps AI-agent company workspaces from composable templates.
+You are the Company Wizard — an expert at assembling AI agent teams. You're enthusiastic but concise. Company Wizard bootstraps AI-agent company workspaces from composable templates.
 
 You are conducting a guided interview to understand what company to set up.
 

package/templates/ai-wizard/single-shot-system.md

@@ -1,4 +1,4 @@
-You are the Clipper AI Wizard. Clipper bootstraps AI-agent company workspaces from composable templates.
+You are the Company Wizard. Company Wizard bootstraps AI-agent company workspaces from composable templates.
 
 Given a natural language description of what the user wants to build, you select the best configuration.
 

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/docs/architecture-template.md

@@ -35,4 +35,4 @@ _APIs between components._
 | _..._    | _..._   | _..._     |
 
 ---
-_Generated by Clipper. Fill in during architecture-plan task._
+_Generated by Company Wizard. Fill in during architecture-plan task._

package/templates/modules/architecture-plan/docs/design-system-template.md

@@ -58,4 +58,4 @@ _Logo usage, iconography, visual tone_
 | desktop | _1024px_ | _..._ |
 
 ---
-_Generated by Clipper. Fill in during design-system task._
+_Generated by Company Wizard. Fill in during design-system task._

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/docs/brand-identity-template.md

@@ -40,4 +40,4 @@ _Communication style, vocabulary preferences, and brand personality traits._
 _Examples of on-brand vs. off-brand language._
 
 ---
-_Generated by Clipper. Fill in during brand-identity task._
+_Generated by Company Wizard. Fill in during brand-identity task._

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/market-analysis/docs/market-analysis-template.md

@@ -29,4 +29,4 @@
 _Strategic recommendations based on the analysis above._
 
 ---
-_Generated by Clipper. Fill in during market-analysis task._
+_Generated by Company Wizard. Fill in during market-analysis task._

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/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/docs/tech-stack-template.md

@@ -25,4 +25,4 @@ _What was considered and rejected, and why._
 | _..._   | _..._   | _..._   |
 
 ---
-_Generated by Clipper. Fill in during tech-stack task._
+_Generated by Company Wizard. Fill in during tech-stack task._

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/docs/user-testing-template.md

@@ -34,4 +34,4 @@ _Prioritized recommendations based on findings above._
 - [ ] _Issue title — severity, linked finding #_
 
 ---
-_Generated by Clipper. Fill in during user-testing task._
+_Generated by Company Wizard. Fill in during user-testing task._

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/modules/vision-workshop/docs/vision-template.md

@@ -25,4 +25,4 @@ _How the company achieves that vision._
 - _What the company explicitly does NOT do_
 
 ---
-_Generated by Clipper. Fill in during vision-workshop task._
+_Generated by Company Wizard. Fill in during vision-workshop task._

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.