agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/delivery/workflow-client-bootstrap/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: workflow-client-bootstrap
+description: WHAT — Interactive interview to capture client delivery context and store it inside the user's
+  ~/.ai-workspace (or similar) as packs + knowledge (no client skills). Use when onboarding a new client
+  project or updating an existing workspace context.
+origin:
+  type: first-party
+---
+# Workflow Client Bootstrap
+
+Use this skill to **create or update** a client-specific delivery context for any project.
+It runs a structured interview and stores the result inside the user’s **workspace**
+(`~/.ai-workspace`, `~/.ai-workspace`, or a workspace-like directory) as **packs + knowledge**
+(not new skills).
+
+**All generated files, PR text, and Jira/ClickUp comments must be in English.**
+
+## When to use
+
+- Onboarding a new client project that needs its own delivery workflow (beyond `workflow-generic-project`)
+- Updating an existing workflow with new lifecycle states, repos, or guardrails
+- Documenting a client's ticket lifecycle so future agent sessions can use correct status transitions
+
+## Do not use when
+
+- The project already has an up-to-date workflow skill and only a ticket or code change is needed
+- The work fits entirely within `workflow-generic-project` without client-specific gates
+
+## Interview process
+
+Read `questions.yaml` (co-located with this skill) before starting. It defines multiple question groups.
+
+| Group | Topics |
+| --- | --- |
+| **Identity** | Client name, slug, ticket system, docs platform, repo host |
+| **Workflow** | Custom ticket statuses, done criteria, base branch, staging/QA gates |
+| **Stack** | Repository list with roles, AGENTS.md presence, validation tools |
+| **Conventions** | Branch naming, PR style, guardrails, Slack channel |
+
+### Workspace root selection (mandatory)
+
+Before asking client questions, resolve the workspace root directory:
+
+1. Look for workspace-like directories (in order):
+   - `~/.ai-workspace`
+   - `~/.ai-workspace`
+   - the current working directory if it looks like a workspace (has `packs/` and `knowledge/`)
+   - other close matches (e.g. `~/*workspace*`) that contain both `packs/` and `knowledge/`
+2. If exactly one plausible workspace is found, select it and print: `Using workspace: <path>`.
+3. If multiple are found, present a numbered list and ask which one to use.
+4. If none are found, explain the expected structure and ask the user for the path to use.
+
+After selecting the path, clearly explain where answers will be stored (see **Storage explanation** below).
+
+### Interview rules
+
+1. Work through the groups **in order**: Identity → Workflow → Stack → Conventions.
+2. Ask **all required questions**. Skip optional ones only if context already answers them.
+3. Apply **conditional questions**: only ask `jira_project_key` if `ticket_system == jira`, etc.
+4. After each group, briefly summarise what you collected and ask for corrections before moving on.
+5. If the user shares a screenshot or diagram of the ticket workflow, extract statuses and transitions from it.
+6. **Never generate files until the full interview is complete and the user has approved the summary.**
+
+## Pre-generation summary (gate)
+
+After the interview, present a structured summary:
+
+```
+Client:          <name>
+Slug:            <slug>
+Ticket system:   <system> (<key prefix if Jira>)
+Docs platform:   <platform>
+Repo host:       <host> / org: <org>
+Base branch:     <branch>
+Done status:     <status>
+Has staging QA:  <yes/no>
+Repos:           <list>
+Validation:      <tools>
+Branch naming:   <convention>
+PR style:        <draft/direct>
+Guardrails:      <list>
+
+Files to generate:
+  packs/clients/<slug>/pack.yaml
+  knowledge/clients/<slug>/reference.md
+  knowledge/clients/<slug>/workflow.md
+  (optional) personas/clients/<slug>.md
+
+Storage location: <workspace-root>/(paths above)
+```
+
+**Stop here and ask: "Does everything look correct? Shall I generate the files?"**
+Do not proceed until the user explicitly confirms.
+
+## File generation (workspace)
+
+Generate files that follow the patterns below. Do **not** hardcode CLI commands inside the generated
+SKILL.md — delegate those to the appropriate tool skills.
+
+### Workspace outputs
+
+Generate these files under the selected workspace root:
+
+- `packs/clients/<slug>/pack.yaml`
+- `knowledge/clients/<slug>/reference.md`
+- `knowledge/clients/<slug>/workflow.md`
+- (optional) `personas/clients/<slug>.md`
+
+### Storage explanation (mandatory)
+
+After selecting the workspace root, clearly explain:
+
+- the chosen workspace directory path
+- which exact files will be written (full paths)
+- that this data is local to the workstation and only becomes shared if the workspace is committed/pushed
+- how to load it later (e.g. via the workspace context loader, or by opening the pack/knowledge files)
+
+## Post-generation steps
+
+1. Write the files under the chosen workspace root.
+2. If the workspace is a git repo and the user wants to share changes, create a commit there (English message) and open a PR as appropriate for that repo.
+3. Otherwise, keep it local and provide the exact paths so the user can back it up or share it later.
+
+## Updating an existing workflow
+
+If the client already has a workflow skill:
+1. Load the existing `SKILL.md` and `reference.md`.
+2. Run only the interview groups relevant to what changed (ask the user which groups to revisit).
+3. Show a diff summary before applying changes.
+4. Follow the same commit/PR flow above.
+
+## Delegation
+
+| Need | Delegate to |
+| --- | --- |
+| Push branch and create draft PR | **github-cli-workflow** or **gitlab-cli-workflow** |
+| Jira ticket operations | External **jira-*** skills |
+| ClickUp ticket operations | **clickup-cli** |
+| Repo discovery | **assistant** |
+
+## Checklist
+
+- [ ] All required interview questions answered
+- [ ] Summary approved by user before file generation
+- [ ] Generated files follow established patterns (use existing bundled skills as structure reference)
+- [ ] `skill-catalog.yaml` updated with both new entries
+- [ ] Agent wrappers created for Claude Code and opencode
+- [ ] Commit and draft PR created; URL shared with user

agent_toolkit/data/skills/delivery/workflow-client-bootstrap/questions.yaml

@@ -0,0 +1,165 @@
+# workflow-client-bootstrap — interview question bank
+# Each block is an interview group. The agent MUST ask all required questions
+# and may skip optional ones if context already answers them.
+
+version: 2
+
+groups:
+  - id: workspace
+    label: "Workspace Root (where data will be stored)"
+    description: "Select the workspace directory (e.g. ~/.ai-workspace) and explain storage paths."
+    questions:
+      - id: workspace_root_override
+        required: false
+        prompt: >-
+          (Optional) If you want to explicitly set the workspace root path, paste it now.
+          Otherwise leave blank and I will auto-detect candidates (e.g. ~/.ai-workspace, ~/.ai-workspace, current dir).
+
+  - id: identity
+    label: "Project Identity"
+    description: "Establish client name, slug, and tooling stack."
+    questions:
+      - id: client_name
+        required: true
+        prompt: "What is the client or project name? (e.g. Acme Payments, Example Corp)"
+
+      - id: client_slug
+        required: true
+        prompt: "What short slug should be used for naming? Use lowercase-kebab-case (e.g. `acme-payments`). This becomes the directory name under packs/clients/ and knowledge/clients/."
+
+      - id: ticket_system
+        required: true
+        prompt: "Which ticket system does this project use?"
+        options: [jira, clickup, linear, github-issues, none, other]
+
+      - id: jira_project_key
+        required: false
+        condition: "ticket_system == jira"
+        prompt: "What is the Jira project key prefix? (e.g. PROJ, ABC)"
+
+      - id: docs_platform
+        required: true
+        prompt: "Which documentation platform does this project use?"
+        options: [confluence, notion, github-wiki, none, other]
+
+      - id: repo_host
+        required: true
+        prompt: "Where are the code repositories hosted?"
+        options: [github, gitlab, bitbucket, other]
+
+      - id: repo_org
+        required: true
+        prompt: "What is the GitHub / GitLab organization or group name? (e.g. my-client-org)"
+
+      - id: account_name
+        required: false
+        prompt: "Optional: Is there an account/engagement name you want to group this client under? (e.g. Internal, Acme)."
+
+  - id: workflow
+    label: "Ticket Lifecycle & Delivery Workflow"
+    description: "Understand the client's Jira/ClickUp workflow and delivery gates."
+    questions:
+      - id: has_custom_workflow
+        required: true
+        prompt: "Does the ticket system have a custom status workflow (beyond the default To Do / In Progress / Done)? Answer yes or no."
+        options: [yes, no]
+
+      - id: custom_statuses
+        required: false
+        condition: "has_custom_workflow == yes"
+        prompt: "List all ticket statuses in order, from creation to done. Include any blocked or failed states. (You can paste a list or describe them.)"
+
+      - id: done_status
+        required: true
+        prompt: "What status means a ticket is fully done and accepted? (e.g. Accepted, Done, Closed)"
+
+      - id: base_branch
+        required: true
+        prompt: "What is the base branch for all feature work? (e.g. main, develop, master)"
+
+      - id: branching_model
+        required: true
+        prompt: "What branching model does this client use?"
+        options: [single-branch-main, gitflow-develop, staging-and-prod-branches, release-branches, other]
+
+      - id: has_staging
+        required: true
+        prompt: "Does the project have a staging environment with a QA gate before production? Answer yes or no."
+        options: [yes, no]
+
+      - id: has_preprod_pr
+        required: false
+        condition: "has_staging == yes"
+        prompt: "Is there a separate pre-prod PR review step before the production release? Answer yes or no."
+        options: [yes, no]
+
+      - id: deploy_method
+        required: true
+        prompt: "How are changes deployed to production? (e.g. CI/CD auto-deploy on merge, manual trigger, scheduled pipeline)"
+
+      - id: environments
+        required: false
+        prompt: "List known environments and their purpose (e.g. dev, staging, prod; or ANALYTICS_STAGING vs ANALYTICS). Answer none if not applicable."
+
+  - id: stack
+    label: "Repositories & Technical Stack"
+    description: "Capture repos and any validation tools specific to this client."
+    questions:
+      - id: repos
+        required: true
+        prompt: "List the main repositories for this project, one per line. Format: `<repo-name> — <role>` (e.g. `dbt-project-main — primary dbt project`, `api-service — backend REST API`)."
+
+      - id: has_agents_md
+        required: true
+        prompt: "Do the repositories use an AGENTS.md (or CLAUDE.md) as the agent contract? Answer yes, no, or varies."
+        options: [yes, no, varies]
+
+      - id: validation_tools
+        required: true
+        prompt: "Which technical validation tools does this project require before merging? (e.g. dbt parse/test, Snowflake queries, pytest, Cypress, eslint, none)"
+
+      - id: secrets_and_credentials
+        required: false
+        prompt: "Where do credentials live (vault, 1Password, env vars)? Any strict rules to follow?"
+
+      - id: ci_system
+        required: false
+        prompt: "What CI system runs validation (GitHub Actions, GitLab CI, CircleCI, none, other)?"
+
+      - id: data_artifacts_policy
+        required: false
+        prompt: "Are there any data artifacts (CSVs, exports) that must NEVER be committed? Describe the policy or answer none."
+
+  - id: conventions
+    label: "Conventions & Guardrails"
+    description: "Branch naming, PR style, and any client-specific restrictions."
+    questions:
+      - id: branch_naming
+        required: true
+        prompt: "What is the branch naming convention? Leave blank to use the agent-toolkit default: `<username>/<ticket-id>-<short-slug>`."
+
+      - id: pr_style
+        required: true
+        prompt: "Should PRs start as drafts or go directly to review?"
+        options: [draft, direct]
+
+      - id: pr_template
+        required: false
+        prompt: "Does the repo have a PR template at `.github/PULL_REQUEST_TEMPLATE.md` or similar? Answer yes, no, or unknown."
+
+      - id: slack_channel
+        required: false
+        prompt: "Is there a primary Slack channel for communication with this client or team? (e.g. #acme-engineering)"
+
+      - id: guardrails
+        required: false
+        prompt: "Are there any special guardrails or restrictions for this client? (e.g. never commit credentials, no force-push, secrets in specific vault). Answer none if not applicable."
+
+      - id: storage_visibility
+        required: true
+        prompt: "Should the generated workspace files be local-only, or committed to the workspace repo for sharing?"
+        options: [local-only, commit-to-workspace]
+
+      - id: extra_notes
+        required: false
+        prompt: "Any additional context the workflow should capture? (e.g. time zone constraints, review SLAs, specific tooling notes)"

agent_toolkit/data/skills/delivery/workflow-generic-project/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: workflow-generic-project
+description: 'WHAT — Generic client delivery: Jira or ClickUp, full repo context, human gates, English
+  traceability on tickets, draft PR via delegated forge skills. Use workspace packs for client/account
+  overlays.'
+origin:
+  type: first-party
+---
+# Workflow — Generic Project (WHAT)
+
+**All skill instructions, ticket comments, and PR text must be in English.**
+
+This workflow supports client delivery phases and gates. Apply any client/account constraints by loading the appropriate workspace pack first.
+
+## Mode selection (mandatory)
+
+- Use **this skill** for client delivery phases and gates.
+- If the task is in a specific client/account context, load the corresponding workspace pack overlay first.
+- If unclear → **ask** which engagement context to use before proceeding.
+
+## Delegation (HOW lives in tool skills)
+
+| Need | Delegate to |
+| --- | --- |
+| ClickUp tasks, comments, status | **clickup-cli** |
+| Jira issue ops, comments, dev links | External **jira-*** skills (e.g. via **jira-assistant** router; CLI: `jira-as`) per repo docs |
+| Confluence pages, search | External **confluence-*** skills (e.g. via **confluence-assistant** router; CLI: `confluence-as`) per repo docs |
+| Planning and estimation | **planning** |
+| Default development workflow / validation fallback | **development-workflow** |
+| Work item structure and templates | **work-item**, **epic**, **user-story**, **task**, **bug**, **incident** |
+| Meetings, decisions, agreements, spikes | **meeting-minutes**, **decision-log**, **agreement**, **spike** |
+| Project assessments, evidence maps, technical/management unit scorecards | **project-assessment**, **project-assessment-evidence**, **technical-unit-assessment**, **management-unit-assessment** |
+| PRD / TRD / ADR structure (templates) | **prd**, **trd**, **adr** (WHAT; see local template references inside each skill) |
+| Where to save a deliverable + human review | **output-handshake** (WHAT; always before final deliverables and PR/MR text) |
+| Default PR body when the repo has no template | **pr-fallback** (WHAT) then **github-cli-workflow** (HOW) |
+| Draft PR on GitHub after push | **github-cli-workflow** |
+| Draft MR on GitLab after push | **gitlab-cli-workflow** |
+| Repository discovery and conflicts | **assistant** |
+
+Do **not** paste forge or ticket CLI sequences here; open the tool skill and follow it.
+
+## Principles
+
+1. **Context:** Pull Jira, ClickUp, Confluence, and linked docs the task references; treat them as source of truth with the codebase (**assistant** inspection order).
+2. **Repo standards:** Follow `AGENTS.md`, CONTRIBUTING, PR templates, and documented Docker or devcontainer flows.
+3. **Human in the loop:** Confirm understanding and plan **before** substantial implementation; get explicit approval **before** finalizing PR text; escalate when context is missing.
+4. **Validation first:** Align on acceptance criteria and approach before deep implementation.
+5. **Traceability:** Add concise English comments on the **original** ticket for plan approval, meaningful milestones, and PR link—no duplicate full PR bodies in tickets.
+
+## Phases (gates)
+
+1. **Intake:** Identify ticket IDs and engagement context; retrieve linked docs via appropriate skills.
+2. **Discovery:** Analyze repo per **assistant**; note CI, templates, dev environments.
+3. **Plan:** Written plan → **stop for user approval.** No implementation until approved.
+4. **Plan traceability:** After plan approval, post a short ticket comment (delegate comment mechanism to **clickup-cli**, **jira-*** or **confluence-*** as applicable).
+5. **Implement:** Work in logical commits per repo conventions; self-review.
+6. **Push and draft PR/MR:** Push branch, then invoke **github-cli-workflow** or **gitlab-cli-workflow** for a **draft**; confirm title/body with the user.
+7. **Close loop:** Post final short ticket comment with PR link (via same ticket skills as above).
+
+## Branch naming (intent)
+
+Prefer **`<short-username>/<WORK_ITEM_ID>-<short-slug>`** (lowercase). Resolve username per repo or user preference; base branch per repo default (**main**, **develop**, etc.).
+
+## Session override
+
+If the user requests **local-only** work: skip push/PR automation; note limitations in ticket updates if still posting.
+
+## Safety
+
+- Never commit secrets; no force-push to shared defaults unless the user explicitly requests recovery steps.
+
+## Checklist
+
+- [ ] Engagement context (if any) confirmed
+- [ ] Work item + doc context retrieved
+- [ ] Plan approved before code; ticket comment after plan approval
+- [ ] Repo standards (template, devcontainer) respected
+- [ ] Draft PR/MR via **github-cli-workflow** or **gitlab-cli-workflow** (or documented fallback)
+- [ ] Final traceability comment with PR link when applicable

agent_toolkit/data/skills/design/design-assessment/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: design-assessment
+description: WHAT - Evidence-based design-unit assessment orchestrated by project-assessment. Evaluates visual hierarchy, UX friction, interaction, a11y, responsiveness, design-system compliance, and distinctiveness with severity/confidence evidence citations. Reuses project-assessment-evidence semantics — no second framework.
+origin:
+  type: first-party
+---
+
+# Design Assessment (WHAT)
+
+Assess a product's interface as a **design unit** delegated by `project-assessment`. Use this skill when the user asks for a design audit, visual review, UX assessment, accessibility evaluation, design-system compliance check, or distinctive-identity review.
+
+**Router contract (ADR-0002 Option A):** `project-assessment` collects evidence via `project-assessment-evidence`, then delegates to this skill alongside `technical-unit-assessment` / `management-unit-assessment` when UI/design is in scope. This skill is also directly invokable for single-page or multi-screen UI audits. It **reuses** the single evidence framework — do not re-ask evidence already in the map.
+
+## Default guardrails
+
+1. Apply **`project-assessment-evidence`** before scoring. If calling via `project-assessment`, reuse its evidence map — do not duplicate intake questions.
+2. Apply **`output-handshake`** before producing any final design assessment report, scorecard, or roadmap.
+3. **Never assign a maturity score without evidence.** If evidence is missing, mark the indicator as **Not assessed** or score with **Low confidence** and state the assumption. Never emit fake precision like `72/100` — use rating bands + severity/confidence.
+4. **Screenshots must not capture secrets.** Observe-only, L1. Redact private data. Keep sensitive details out of reusable artifacts.
+5. **Generic-template risk (distinctiveness)** must be context-aware — `rounded cards = bad` is not a rule. Evaluate whether the aesthetic is distinctive for *this* product's subject and tone, not via a checklist.
+6. **Vision fallback:** This skill is `vision-required` for full visual critique. If the harness cannot render screenshots/recordings, perform a text-only heuristic review (code, tokens, a11y attributes) and flag each finding with **Low confidence — vision unavailable**.
+
+## Design-unit intake
+
+Ask before scoring (or reuse from router evidence map):
+
+- **Product & purpose:** product name, audience, single job the page/ flow does
+- **Scope:** screens/flows/components in scope, Figma files / variables, Storybook, Tailwind/config, design-system entry points
+- **Repositories & assets:** app repo(s), component library, token files, asset locations
+- **Systems of record for design evidence:** Figma, Storybook, WCAG reports, performance reports, screenshots, recordings, product analytics, UX research
+- **Assessment period & audience:** who will act on findings
+- **Decision ownership:** who validates subjective visual judgments
+
+Evidence sources already covered by `project-assessment-evidence` include: `design files, UX research, accessibility reports, performance reports, screenshots, recordings, product analytics` — ask where each lives instead of assuming.
+
+## Orchestration workflow
+
+```
+UNDERSTAND PRODUCT → DISCOVER DESIGN SYSTEM → INSPECT APP → CAPTURE SCREENS/STATES
+  → VISUAL REVIEW → UX REVIEW → A11Y → RESPONSIVE → DESIGN-SYSTEM CONSISTENCY
+  → DISTINCTIVENESS → PERF → FIGMA COMPARE → PRIORITIZED FINDINGS → ROADMAP
+```
+
+### Phase 1 — Understand & Discover
+
+1. **Understand product:** audience, job-to-be-done, tone, constraints (framework, performance, a11y target WCAG 2.2 AA). Ask the user if not in evidence map.
+2. **Discover design system:** locate tokens (Figma variables, Style Dictionary, Tailwind config, CSS variables), component library (Storybook), Figma Dev Mode specs. Record freshness and owner per `project-assessment-evidence` quality rules (Direct/Indirect/Stale/Missing).
+
+### Phase 2 — Inspect & Capture
+
+3. **Inspect app:** verify app builds and routes enumerated in scope; enumerate states (empty, loading, error, dense, mobile).
+4. **Capture screens/states:** use `playwright-cli` (or Chrome DevTools) to screenshot each screen/state at breakpoints (mobile, tablet, desktop). If capturing elsewhere, delegate to `browser` reviewer. Record capture metadata (viewport, theme, date) as evidence.
+
+### Phase 3 — Parallel review (vision where possible)
+
+Fan out where the harness supports subagents — shared evidence map is authority; sequential fallback is always valid:
+
+| Reviewer | Delegates to | Focus |
+|----------|--------------|-------|
+| Visual / hierarchy | `frontend-design-review` | Layout, typography, color, motion, three pillars (Frictionless / Quality Craft / Trustworthy), design-system compliance vs Figma tokens |
+| UX friction | `web-design-guidelines` + heuristic | Interaction path ≤3 steps, single primary action, progressive disclosure, onboarding |
+| A11y | `accessibility` / `frontend-design-review` (a11y modifier) | Keyboard, screen reader, contrast (WCAG 2.2 A = Grade C, AA = Grade B), 200% zoom, light/dark/high-contrast |
+| Responsive | `playwright-cli` + `frontend-design-review` | Reflow, token usage not hardcoded values, variants/states |
+| Design-system consistency | `figma` / `figma-implement-design` + tokens | Token usage, spacing vs Figma Dev Mode, deviations with rationale |
+| Distinctiveness | `frontend-design` + `frontend-design-review` (creative mode) | Aesthetic direction distinctive for this subject, avoids generic AI template |
+| Performance (UI) | `playwright-cli` / Chrome DevTools | Load, reflow, motion cost (CSS-only preferred) — citation not synthetic score |
+
+**Swarm mapping (advisory):** `design-assessment: a11y-reviewer || visual-reviewer || browser-perf-reviewer || design-system-reviewer` (shared evidence map). Sequential execution produces identical findings — only slower.
+
+For each finding see **Scorecard & findings** below.
+
+### Phase 4 — Figma compare
+
+5. Compare implementation side-by-side with Figma using Dev Mode specs: spacing, typography, color, variants. Document deviations with link and whether design approval exists.
+
+### Phase 5 — Findings & Roadmap
+
+6. **Prioritize findings** by `severity × user impact × effort` with confidence. Separate confirmed vs assumed vs missing-evidence.
+7. **Roadmap:** group by `quick win / next sprint / needs design`. Do not create tickets or update docs without explicit user approval — delegate ticket creation to the relevant ticket skill after approval.
+8. **Output handshake** before final artifact.
+
+## Scorecard & findings (no fake precision)
+
+Use the 1–5 scale from `technical-unit-assessment` `references/indicator-groups.md` **only where an indicator has evidence**. Score 3 = defined/partially mature. Record confidence per score (High/Medium/Low/Not assessed) and evidence link. Do not average unrelated indicators without explaining weighting.
+
+Prefer **severity bands** for actionable review output (from `frontend-design-review`):
+
+- **Blocking** — must fix before merge/release (user task broken, WCAG failure, design-system violation)
+- **Major** — should fix (measurable UX friction, generic aesthetic without direction)
+- **Minor** — consider for refinement
+
+### Design indicators (1–5, Not assessed if missing evidence)
+
+| Indicator | What to observe (evidence) |
+|-----------|----------------------------|
+| Visual identity / distinctiveness | Typography pair, palette with CSS variables, spatial composition, motion; distinctive for *this* subject, not a template |
+| Hierarchy & layout | Information structure, primary action per view, progressive disclosure, spacing vs tokens |
+| UX friction / interaction | Task completion steps, navigation entry/exit, onboarding, error messages actionable |
+| Consistency | Component reuse, token usage, variants/states match Figma |
+| A11y | Contrast, keyboard, screen reader, ARIA, 200% zoom, theme testing |
+| Responsiveness | Breakpoints, reflow, no hardcoded values |
+| Design-system compliance | Matches Figma specs, no deviation without rationale |
+| Performance (UI) | Motion orchestrated, not scattered; CSS-only preferred where possible |
+
+### Per-finding record
+
+Every finding must cite:
+
+- **Observation** — what you saw (screen/region, code line `file:line`, token mismatch, screenshot anchor)
+- **Impact** — user/task consequence
+- **Effort** — S/M/L
+- **Confidence** — High/Medium/Low (downgrade to Low if vision unavailable)
+- **Affected screens / components**
+- **Recommended fix** — design-system link or token reference or Figma link
+- **Evidence** — link to screenshot, Figma node, WCAG run, Storybook entry
+- **Severity** — Blocking / Major / Minor
+
+See `references/design-scorecard-template.md` for the full template. Mark **Not assessed** when screenshot/code unavailable rather than inventing a rating.
+
+## Delegation table
+
+| Need | Skill |
+|------|-------|
+| Evidence intake (single framework) | `project-assessment-evidence` |
+| Multi-unit routing (technical/mgmt/design) | `project-assessment` |
+| Procedural visual critique (three pillars, checklist) | `frontend-design-review` (delegate of this skill — Visual Review phase) |
+| Web Interface Guidelines rules (a11y, focus, forms, animation) | `web-design-guidelines` (frozen `references/web-interface-guidelines.md`) |
+| Screenshot & browser states | `playwright-cli` / Chrome DevTools |
+| Figma variables / Dev Mode compare | `figma` / `figma-implement-design` / `figma-create-design-system-rules` |
+| Distinctive visual direction | `frontend-design` |
+| Repository discovery | `assistant` |
+| Final output gate | `output-handshake` |
+| Parallel large-product review | `swarm` (optional; sequential fallback valid) |
+
+## Security & compatibility
+
+- No mutation; observe-only. Screenshots must not capture secrets — coordinate capture scope.
+- Portable: no tool-specific paths (uses local `references/` and evidence map).
+- Swarm optional; vision gracefully degrades to text-only heuristic with lower confidence.
+
+## References
+
+- `references/design-scorecard-template.md` — design-unit scorecard + findings template (this skill)
+- `project-assessment` — router and scope (delegates to this skill)
+- `project-assessment-evidence` — evidence map and source-by-source intake (single framework)
+- `technical-unit-assessment` + `references/indicator-groups.md` — 1–5 scale, confidence, Not assessed, output-handshake contract
+- `frontend-design-review` — pillar assessment and review-output format (delegate)
+- `web-design-guidelines` — Web Interface Guidelines frozen reference
+- `playwright-cli` / `figma` — capture and compare
+

agent_toolkit/data/skills/design/design-assessment/references/design-scorecard-template.md

@@ -0,0 +1,78 @@
+# Design Assessment Scorecard Template
+
+**Product:** [name]  **Period:** [dates]  **Assessor:** [name]  
+**Purpose:** [baseline / periodic / due-diligence]  **Audience:** [who acts]  
+**Evidence map:** [link to project-assessment-evidence artifact]  **Figma:** [link]  **Storybook:** [link]
+
+> Uses 1–5 scale from `technical-unit-assessment` `references/indicator-groups.md` (3 = defined). Confidence High/Medium/Low/Not assessed. Never score without evidence — use Not assessed. Findings use Blocking/Major/Minor.
+
+## Evidence summary (from evidence map)
+
+| Source | Location | Freshness | Strength (Direct/Indirect/Stale/Missing) | Confidence | Indicators |
+|--------|----------|-----------|------------------------------------------|------------|------------|
+| Figma  | [link]   | [date]    | Direct                                   | High       | Visual identity, Consistency |
+| Screenshots (Playwright) | [path] | [date] | Direct | High | Hierarchy, A11y, Responsive |
+| WCAG report | [tool] | [date] | Indirect | Medium | A11y |
+| Performance trace | [path] | [date] | Indirect | Medium | Performance (UI) |
+
+## Design-unit scorecard (1–5, Not assessed if missing evidence)
+
+| Indicator | Score | Confidence | Evidence | Notes |
+|-----------|-------|------------|----------|-------|
+| Visual identity / distinctiveness | 3 / Not assessed | High / Low | [Figma node, screenshot] | [why] |
+| Hierarchy & layout |  |  |  |  |
+| UX friction / interaction |  |  |  |  |
+| Consistency |  |  |  |  |
+| A11y |  |  |  | WCAG 2.2 A = 3 (Grade C), AA = 4 (Grade B) |
+| Responsiveness |  |  |  |  |
+| Design-system compliance |  |  |  |  |
+| Performance (UI) |  |  |  |  |
+
+**Overall:** [narrative, not averaged — explain weighting if combining]
+
+## Findings (severity-ranked, evidence-cited)
+
+### Blocking (must fix before merge/release)
+
+1. **[Pillar/Indicator] Title**
+   - **Observation:** [screen/region, file:line, token mismatch, screenshot anchor]
+   - **Impact:** [user/task consequence]
+   - **Effort:** S/M/L  **Severity:** Blocking  **Confidence:** High/Medium/Low
+   - **Affected:** [screens/components]
+   - **Recommended fix:** [design-system link, token, Figma node]
+   - **Evidence:** [screenshot, Figma, WCAG run]
+
+### Major (should fix)
+
+1. ...
+
+### Minor (consider)
+
+1. ...
+
+### Not assessed (missing evidence)
+
+| Indicator | Reason | What would enable assessment |
+|-----------|--------|------------------------------|
+| [e.g. A11y — screen reader] | No recording / report | Provide NVDA/JAWS run |
+
+## Missing evidence register
+
+| Indicator | Evidence needed | Location if exists | Owner |
+|-----------|-----------------|--------------------|-------|
+|  |  |  |  |
+
+## Roadmap
+
+| Priority | Finding | Effort | Owner | Evidence link |
+|----------|---------|--------|-------|---------------|
+| Quick win |  | S |  |  |
+| Next sprint |  | M |  |  |
+| Needs design |  | L |  |  |
+
+## Output handshake
+
+- **Destination:** [path/URL where artifact lives]
+- **Reviewer:** [who approves]
+- **Confirmed:** [date]
+