constellai 0.3.0

package/skills/process/research-official-docs/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: research-official-docs
+description: Research trusted documentation on the web (WebSearch/WebFetch) and capture what you learn into the knowledge base — use when you need authoritative, current API/library/framework/security details before deciding or building.
+domain: process
+category: research
+tags: [research, web, documentation, official-sources, rag, knowledge]
+official_sources:
+  - https://developer.mozilla.org/
+  - https://web.dev/
+verified: 2026-06-21
+---
+
+# Research official documentation
+
+When you are unsure about an API, a framework's idiom, a config, a version difference, or a security/best
+practice for this project's stack — **look it up against trusted sources instead of guessing**, then record
+what you learned so the whole team reuses it. You have the `WebSearch` and `WebFetch` tools (when web
+research is enabled for this workspace).
+
+## When to use
+- You need exact, current details (an API signature, a config option, a breaking change, a CVE/mitigation).
+- A decision or implementation hinges on how a library/framework actually works in THIS stack's version.
+- The Knowledge section didn't already answer it (don't re-research what the KB already holds).
+
+Don't over-research: only when it changes a real decision or prevents a wrong implementation.
+
+## Source priority (most to least trusted)
+1. **Official documentation** for the exact library/framework + version (e.g. the framework's own docs site).
+2. **Official repositories** — the project's own README, examples, CHANGELOG, release notes.
+3. **Recognized technical references** — MDN, web.dev, OWASP, language/standard specs.
+4. **Community best practices** from reputable maintainers/foundations.
+5. **Trusted examples** — official samples, well-known reference implementations.
+6. **Official downloads / registries** (npm, PyPI, the vendor's releases) for versions + integrity.
+7. **Up-to-date references** — prefer the newest that matches the project's pinned versions.
+
+Avoid: random blogs, outdated Q&A, content farms, AI-generated SEO pages, anything unversioned or that
+contradicts the official source.
+
+## How
+1. `WebSearch` to find the **official** page for the exact topic + the project's version.
+2. `WebFetch` the official page and read the relevant part. Prefer the version the project pins.
+3. **Validate**: for anything correctness- or security-critical, confirm against the official source — never
+   trust a single secondary source. If sources disagree, the official one wins; note the discrepancy.
+
+## Capture what you learned (so it lands in the RAG and is reused)
+After you confirm something useful, record it durably so the next agent doesn't re-research it. Emit:
+
+`[[REMEMBER type=doc: <concise fact or snippet> — applies to <where in this project> (source: <official url>)]]`
+
+Always include the **source URL** and **how it applies to this project**. Keep it factual and concise. The
+system stores it in the knowledge base with its source + context, and retrieval surfaces it to the team on
+later tasks — so the system's intelligence grows as it researches, validates and builds.
+
+## If you don't have the WebFetch tool (local model)
+Ask the system to fetch + cache an official page for you: emit `[[RESEARCH: <official-doc url>]]`. The server
+fetches it (only **allowlisted official-doc domains** — your stack's `official_sources` + trusted references
+like MDN/web.dev/OWASP) and stores it in the knowledge base, so it's available to the team (and to you on the
+next step) via retrieval. Prefer the exact official URL for your stack and version.

package/skills/process/review-code-perf-security/SKILL.md

@@ -0,0 +1,65 @@
+# Skill — review-code-perf-security
+
+**Trigger:** A change/PR is ready for review and needs a structured assessment covering correctness/design, performance, and security before it merges.
+
+Produces a review that decides whether the change improves overall code health, with findings categorized and each tied to an actionable fix.
+
+## When to use
+- Reviewing a teammate's or agent's PR before merge.
+- A change touches performance-sensitive paths or security-relevant code (auth, input handling, data access).
+- You are the second pair of eyes required by the team's "someone other than the author" rule.
+
+## When NOT to use
+- *Designing* security up front — that's `process/security-by-design` (pre-implementation), this is review (post-implementation).
+- Authoring tests — use `process/testing-before-done`; here you only check that adequate tests exist.
+- Trivial auto-formatted changes with no logic (let tooling handle style).
+
+## Required context & inputs
+- The diff/CL and its description (what it does and why).
+- The acceptance criteria the change claims to satisfy.
+- The threat model and test plan for the area, if they exist (`process/security-by-design`, `process/testing-before-done`).
+- The project's style guide and the org's stack conventions (from `.claude/CLAUDE.md`).
+
+## Procedure
+1. **Apply the standard of review (Google).** A reviewer is "someone other than the author" examining the code. The bar: **approve once the change definitely improves the overall code health of the system, even if it isn't perfect.** Do not block a healthy improvement in pursuit of perfection; do not approve something that degrades code health.
+2. **Review across the eight dimensions (Google "What to look for").** Walk the diff against each:
+   - **Design** — does the change belong here and integrate well with the system?
+   - **Functionality** — does it do what the author intends, and is that good for users/callers? Consider edge cases and concurrency.
+   - **Complexity** — is it as simple as possible? Reject over-engineering and code harder to read than necessary.
+   - **Tests** — are there correct, well-designed automated tests at the right level (cross-check `process/testing-before-done`)?
+   - **Naming** — are names clear and precise?
+   - **Comments** — do comments explain *why*, and are they necessary and clear?
+   - **Style** — does it follow the project's style guide? (Style nits are non-blocking; prefix them `Nit:`.)
+   - **Documentation** — are relevant docs updated/added/removed to match?
+3. **Review performance explicitly.** Inspect hot paths and data access: algorithmic complexity, N+1 queries, unnecessary allocations/copies, missing pagination or indexes, blocking I/O on critical paths, and unbounded growth. Flag concrete regressions, not speculative micro-optimizations — require evidence (a benchmark or a clear complexity argument) before demanding a change.
+4. **Review security (OWASP Code Review Guide).** Manual security review still has a prominent place in the SDLC — scanners alone are insufficient. Check the high-risk areas: input validation (treat all external input as hostile), authentication and session handling, authorization/access control on every server-side entry point (least privilege, deny by default), output encoding, error/exception handling that fails securely and doesn't leak internals, secrets handling, and dependency safety. Map findings to the threat model where one exists.
+5. **Categorize and phrase every finding.** Tag each as **Blocking** (must fix before merge — correctness, security, data loss, perf regression) or **Non-blocking** (`Nit:` / `Optional:` / `FYI:`). State the location, the problem, and a concrete fix. Be courteous and objective — comment on the code, not the author.
+6. **Decide.** Approve if the change improves code health and has no blocking findings; request changes if blocking findings remain; if blocked on a judgment call, escalate per team norms rather than stalling. Respond promptly so you don't become the bottleneck.
+
+## Output format
+- A review (PR comments or a `review.md`) containing:
+  - A verdict: approve / request changes, with the one-line code-health justification.
+  - Findings grouped by category (Design/Functionality/Complexity/Tests/Naming/Comments/Style/Docs, plus Performance and Security), each as `Location — problem — fix — Blocking|Nit|Optional`.
+- Inline comments anchored to the relevant diff lines where the platform supports it.
+
+## Quality & validation rules
+- The reviewer is not the author of the code under review.
+- The verdict is justified by overall code-health improvement, not perfection.
+- Every dimension in step 2 was considered (even if "no issues").
+- Performance findings are concrete (complexity argument or benchmark), not speculative.
+- Security review covered input validation, authn, authz/least-privilege, error handling, and dependencies; findings map to the threat model where present.
+- Each finding has a location, a problem, a fix, and a Blocking/Non-blocking tag; pure style is marked `Nit:` and never blocks alone.
+- Tests were checked for existence and correct level, not assumed.
+
+## Failure handling
+- **No tests in the change** → blocking finding; request tests at the appropriate pyramid level (per `process/testing-before-done`).
+- **Security concern without a threat model** → flag it and recommend running `process/security-by-design` for that area before merge.
+- **Author disagrees on a judgment call** → discuss with rationale; if unresolved, escalate per team norms rather than rubber-stamping or stonewalling.
+- **Diff too large to review well** → request it be split into smaller, reviewable CLs; an unreviewable change can't be approved responsibly.
+- **Perf concern is speculative** → ask for a benchmark rather than blocking on a guess.
+
+## Related
+- Sources:
+  - Google code review (standard + what to look for) — https://google.github.io/eng-practices/review/
+  - OWASP Code Review Guide — https://owasp.org/www-project-code-review-guide/
+- Skills: `process/security-by-design`, `process/testing-before-done`, `process/adr-technical-decisions`

package/skills/process/security-by-design/SKILL.md

@@ -0,0 +1,68 @@
+# Skill — security-by-design
+
+**Trigger:** A new system, service, feature, or significant design change is being planned and its security posture must be analyzed *before* implementation — including threat modeling and least-privilege design.
+
+Produces a threat model (answers to the four threat-modeling questions) and a set of proactive controls and least-privilege decisions baked into the design.
+
+## When to use
+- Designing anything that handles user data, authentication, money, or external input.
+- Adding a trust boundary (new API, integration, multi-tenant feature, file upload).
+- Before writing code for an architecturally significant component.
+
+## When NOT to use
+- A cosmetic or internal-only change with no new trust boundary and no sensitive data.
+- A pure security *review of already-written code* — use `process/review-code-perf-security`.
+- Incident response on a live breach (this skill is preventive, not reactive).
+
+## Required context & inputs
+- The system/feature design: the C4 Context and Container views if available (from `process/app-planning`).
+- The data it handles and the data's sensitivity (PII, secrets, payment, health).
+- The trust boundaries: where data crosses from less-trusted to more-trusted zones.
+- The org's stack and runtime isolation model (from `.claude/CLAUDE.md`).
+
+## Procedure
+1. **Answer Q1 — "What are we working on?"** Document the system in scope: its components, data flows, users, dependencies, assumptions, and — critically — its **trust boundaries** (every point where data or control crosses a privilege level). A data-flow diagram or the C4 Container view is the input here.
+2. **Answer Q2 — "What can go wrong?"** Systematically enumerate threats against each element and data flow. Use a structured methodology (STRIDE is the common default: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege; OWASP is methodology-neutral so PASTA/LINDDUN/attack trees are also valid). Capture misuse cases and design assumptions that, if false, become vulnerabilities.
+3. **Answer Q3 — "What are we going to do about it?"** For each credible threat, decide a response: mitigate, eliminate, transfer, or accept. Map mitigations to the **OWASP Top 10 Proactive Controls (2024)**, designing each relevant control into the system from the start:
+   - **C1 Implement Access Control** — enforce least privilege; deny by default; check authorization on every request server-side.
+   - **C2 Use Cryptography to Protect Data** — protect data in transit and at rest.
+   - **C3 Validate all Input & Handle Exceptions** — treat all external input as hostile; fail securely.
+   - **C4 Address Security from the Start** — this skill itself.
+   - **C5 Secure By Default Configurations.**
+   - **C6 Keep your Components Secure** (dependencies/SCA).
+   - **C7 Secure Digital Identities** (authentication, session, MFA).
+   - **C8 Leverage Browser Security Features.**
+   - **C9 Implement Security Logging and Monitoring.**
+   - **C10 Stop Server Side Request Forgery.**
+4. **Apply least privilege concretely (C1).** For every actor, service account, token, and component, grant the minimum permissions needed and nothing more. Default to deny. Scope credentials to the narrowest resource and lifetime. Honor the runtime's isolation model (e.g. the org's FS jail / per-org runtime root) — do not design around it.
+5. **Answer Q4 — "Did we do a good job?"** Review the model for completeness against the data flows, record every decision and accepted risk with its rationale, and define follow-up tests that prove the mitigations work (hand these to `process/testing-before-done`).
+6. **Make it continuous.** Threat modeling is applied throughout development at practical granularity — revisit the model when the design changes, a new trust boundary appears, or assumptions from Q1 are invalidated.
+
+## Output format
+- A `threat-model.md` in the workspace structured around the four questions:
+  - Q1: scope, data-flow/Container diagram, trust boundaries, assumptions.
+  - Q2: threat list (per element, with the methodology used, e.g. STRIDE category).
+  - Q3: mitigations mapped to Proactive Controls C1-C10, with each threat → response.
+  - Q4: residual/accepted risks (with rationale), and the security tests to be written.
+- Least-privilege matrix: `Actor/Component | Resource | Permission granted | Justification`.
+
+## Quality & validation rules
+- All four questions are explicitly answered; a model missing Q3 or Q4 is incomplete.
+- Every trust boundary from Q1 has at least one corresponding threat considered in Q2.
+- Every credible threat in Q2 has an explicit response in Q3 (mitigate/eliminate/transfer/accept) — none left undecided.
+- Access control (C1) is enforced server-side and defaults to deny; no permission is granted without a justification in the matrix.
+- Sensitive data is covered by C2 (crypto in transit and at rest).
+- Accepted risks are recorded with rationale, not silently dropped.
+- Mitigations produce concrete test cases handed to the testing process.
+
+## Failure handling
+- **A threat has no feasible mitigation** → record it as an accepted risk with explicit rationale and sign-off, and add monitoring (C9) to detect exploitation.
+- **Trust boundaries are unclear** → stop and clarify the data flows with the team; you cannot model threats over an undefined boundary.
+- **Design conflicts with least privilege** → treat that as a finding; redesign to scope down permissions rather than widening them for convenience.
+- **Model goes stale after a design change** → re-run Q1-Q4 for the changed area; an outdated threat model is a false sense of security.
+
+## Related
+- Sources:
+  - Threat modeling (four questions, STRIDE) — https://owasp.org/www-project-threat-modeling/
+  - Proactive Controls (C1-C10, 2024) — https://owasp.org/www-project-proactive-controls/
+- Skills: `process/app-planning`, `process/testing-before-done`, `process/review-code-perf-security`

package/skills/process/specs-to-issues/SKILL.md

@@ -0,0 +1,53 @@
+# Skill — specs-to-issues
+
+**Trigger:** Specs with acceptance criteria exist and must be decomposed into well-formed, trackable tracker issues — before work is scheduled or started.
+
+Produces a set of independent, vertically-sliced issues (each with a clear title, context, acceptance criteria, and metadata) that the team can pick up, build, and close.
+
+## When to use
+- Specs/user stories are ready and need to become units of work in the tracker (GitHub Issues, Jira).
+- A large story (epic) must be broken into stories small enough to deliver.
+- Before sprint planning, so the backlog contains well-formed, estimable items.
+
+## When NOT to use
+- The specs/acceptance criteria do not yet exist or are untestable — go to `requirements-to-specs`.
+- Slicing into time-boxed delivery increments — that is `breaking-work-into-sprints` (this skill produces the items; that skill schedules them).
+- Trivial one-line fixes where an issue would be ceremony (still record them, but skip decomposition).
+
+## Required context & inputs
+- The `specs.md` (stories + acceptance criteria) and any `architecture.md` / `screen-flows.md`.
+- The tracker in use and the org's issue templates/labels/milestones conventions (from `.claude/CLAUDE.md` or the repo).
+- Existing related issues (to avoid duplicates and to set dependencies).
+
+## Procedure
+Issues track "bug reports, new features and ideas, and anything else you need to write down" (GitHub). Decompose specs into the **story → epic → initiative** hierarchy where needed: stories are small sprint-sized items, epics group related stories, initiatives group epics (Atlassian — see Related).
+
+1. **Classify the work.** Decide whether each spec is a single story, or an **epic** to be split into stories. Group large bodies of epics under an **initiative** if the org tracks that level.
+2. **Slice vertically.** Each issue should deliver a thin end-to-end piece of user-visible value (or a deployable internal capability), not a horizontal layer ("all the CSS"). Aim for INVEST-style items: independent, negotiable, valuable, estimable, small, testable.
+3. **Write a clear title.** Imperative and specific ("Add wishlist save button to product page"), scannable in a list.
+4. **Write the body** from a template: **Context/why** (link the story + problem), **Acceptance criteria** (copy the testable criteria from `specs.md`, as a checklist), **Out of scope**, and **Links** (wireflow node, ADR, related issues).
+5. **Add a task list** for multi-step issues so progress is trackable; convert items to **sub-issues** when they are independently workable.
+6. **Set metadata.** Assign type/labels, a milestone, and project/board placement; declare **dependencies/blocking** relationships between issues.
+7. **Use issue templates/forms** so every issue carries the required fields and contributors open meaningful issues.
+8. **De-duplicate and link.** Search existing issues; link or close duplicates; reference related/blocking issues so the graph is navigable.
+9. **Confirm each issue is estimable and small** enough to fit one increment; if not, split again.
+
+## Output format
+- One tracker issue per unit of work, each with: imperative title; body containing context, acceptance-criteria checklist, out-of-scope, and links; labels/type, milestone, project, and dependency links. Epics link to their child stories; initiatives link to their epics.
+- A short `issues.md` (in the planning folder) listing the created issue IDs/links and the epic→story map, for traceability back to `specs.md`.
+
+## Quality & validation rules
+- Every story in `specs.md` is represented by at least one issue; no acceptance criterion is dropped.
+- Each issue is independently understandable (context + criteria + links) without reading external chat, and is small/estimable enough for one increment.
+- Slices are vertical (deliver value), not horizontal (layers). Dependencies are explicit, not implicit.
+- Titles are imperative and specific; templates/required fields are populated. Done = a team member could pick any issue and know exactly what "done" means.
+
+## Failure handling
+- **An issue is too big to estimate:** split it; if it cannot be split without losing value, mark it an epic and decompose.
+- **Acceptance criteria missing or untestable:** stop and return to `requirements-to-specs`; do not create an unverifiable issue.
+- **Duplicate found:** link/close rather than create; reconcile scope.
+- Record the spec→issue mapping in `issues.md` so traceability survives if issues are reorganized.
+
+## Related
+- Sources: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues ; https://www.atlassian.com/agile/project-management/user-stories ; https://www.atlassian.com/agile/project-management/epics-stories-themes
+- Skills: ../requirements-to-specs, ../breaking-work-into-sprints, ../architecture-before-code

package/skills/process/testing-before-done/SKILL.md

@@ -0,0 +1,61 @@
+# Skill — testing-before-done
+
+**Trigger:** A feature or change is being planned, and "done" must be defined as "tested" — the test strategy is decided *before* implementation, not after.
+
+Produces a test plan shaped by the Test Pyramid (the right tests at the right levels) and a definition of done that gates merge on those tests passing.
+
+## When to use
+- Starting any non-trivial feature where correctness matters.
+- Defining or revising what "done" means for a team or workstream.
+- A bug was found by a high-level/manual test and you need to lock it down at the right level.
+
+## When NOT to use
+- A throwaway spike or prototype explicitly marked as not production-bound.
+- The change is purely a config/copy tweak with no behavior change (still verify, but a full pyramid is overkill).
+- Security-specific test design — derive those cases from `process/security-by-design` and feed them in here.
+
+## Required context & inputs
+- The feature's acceptance criteria / user stories (from `process/app-planning`).
+- The architecture: which units, services/APIs, and UI flows exist (C4 Container/Component views).
+- The org's stack and existing test tooling/runner (from `.claude/CLAUDE.md` and the repo).
+- Any security mitigations that need proof (from `process/security-by-design`).
+
+## Procedure
+1. **Define "done" before coding.** State explicitly: a change is done only when its tests exist, run in CI, and pass. Write this into the plan so it gates merge — testing is not an afterthought phase.
+2. **Shape the suite as a pyramid (Fowler/Cohn).** Plan many fast, cheap **unit tests** at the base; fewer **service/integration tests** in the middle (exercise the API/service layer below the UI — "subcutaneous" tests); and very few **UI/end-to-end tests** at the top. The rule: many more low-level unit tests than broad GUI tests.
+3. **Assign each acceptance criterion to a level.** For each behavior, choose the *lowest* level that can meaningfully test it:
+   - Pure logic / a single function or class → unit test.
+   - Interaction across components or a service contract → integration/service test.
+   - A full critical user journey end-to-end → one UI/E2E test (reserve these for the handful of journeys that must never break).
+4. **Justify every high-level test.** UI/E2E tests are brittle, expensive to write, slow to run, and prone to non-determinism. Only add one when the journey can't be covered lower down. If you're tempted to add many, that's a signal to push coverage down the pyramid.
+5. **Set the bug-fix protocol.** When a high-level or manual test exposes a bug, first replicate it with a **unit test**, then fix it. High-level tests are a second line of defense — they catch gaps the unit tests missed, and each gap becomes a new low-level test.
+6. **Plan for determinism and speed.** Identify flaky risk (timing, network, shared state) and design isolation/mocks so the base of the pyramid stays fast and trustworthy — a non-deterministic suite erodes trust and gets ignored.
+7. **Write tests alongside (or before) the code.** Tests are part of the deliverable, authored with the implementation, not bolted on after. They run in CI on every change.
+
+## Output format
+- A `test-plan.md` (or the plan's testing section) in the workspace containing:
+  - The definition of done (tests exist + pass in CI gates merge).
+  - A coverage table: `Acceptance criterion | Test level | Why this level | Test name/file`.
+  - The pyramid shape target (rough ratio of unit : integration : E2E for this feature).
+  - The list of critical journeys getting an E2E test (kept short, each justified).
+- Security-derived test cases from `process/security-by-design`, slotted into the table at their level.
+
+## Quality & validation rules
+- "Done = tested and green in CI" is written down and gates merge.
+- Every acceptance criterion maps to at least one planned test.
+- The suite is bottom-heavy: unit tests outnumber integration tests, which outnumber E2E tests.
+- Each behavior is tested at the lowest level that can verify it; nothing pushed to E2E that a unit test could cover.
+- Every E2E/UI test has a one-line justification for why it can't live lower.
+- The bug-fix protocol (replicate with a unit test, then fix) is part of the team's definition.
+- Tests are deterministic — known flaky vectors are isolated or mocked.
+
+## Failure handling
+- **A behavior seems testable only via the UI** → re-examine the architecture for a service/API seam (subcutaneous test) before accepting an E2E test.
+- **The suite is slow/flaky** → move coverage down the pyramid and isolate non-determinism; do not paper over flakiness with retries as a permanent fix.
+- **A bug recurs** → it lacked a low-level test; add the unit test that reproduces it before re-fixing.
+- **Pressure to ship untested** → that change is not done by definition; record the gap as explicit, accepted test debt with an owner rather than silently calling it complete.
+
+## Related
+- Sources:
+  - Test Pyramid — https://martinfowler.com/bliki/TestPyramid.html
+- Skills: `process/app-planning`, `process/security-by-design`, `process/review-code-perf-security`

package/skills/process/validating-ux-navigation/SKILL.md

@@ -0,0 +1,63 @@
+# Skill — validating-ux-navigation
+
+**Trigger:** A new app, feature area, or redesign needs its information architecture (IA), navigation, and user flows validated *before* the UI is finalized in code.
+
+Produces a validated IA + navigation design backed by evidence from a structured usability test, with a prioritized list of problems found.
+
+## When to use
+- Designing or restructuring how content/features are organized and how users move between them.
+- A flow exists but users get lost, can't find features, or abandon a task.
+- Before committing navigation markup, to avoid costly structural rework later.
+
+## When NOT to use
+- Pure visual styling with no structural/flow change (use design/component skills instead).
+- The information architecture is already validated and only copy is changing.
+- You cannot recruit even a handful of representative users and the change is low-risk — at minimum do an expert heuristic review instead, and say so.
+
+## Required context & inputs
+- The content inventory: every page/screen/feature the product offers.
+- The primary user roles and their top tasks (what they come to accomplish).
+- The current or proposed navigation components (global nav, breadcrumbs, filters, footer).
+- Access to 5+ representative users per distinct user group for testing.
+
+## Procedure
+1. **Separate IA from navigation (NN/g distinction).** Treat them as two layers: **IA** is the underlying organization, structure, and naming of content (lives in spreadsheets/diagrams, invisible to users); **navigation** is the visible UI (global nav, breadcrumbs, filters, footers) — "the tip of the iceberg" sitting on top of the IA. Validate the IA *first*; navigation design follows from it.
+2. **Build the IA.** Run the four NN/g IA activities:
+   - **Content inventory** — locate and list all existing content/features.
+   - **Content audit** — judge each item's usefulness, accuracy, and effectiveness; drop dead weight.
+   - **Information grouping** — group content by user-centered relationships (how users think, not the org chart).
+   - **Taxonomy development** — define standardized, user-tested labels and naming.
+3. **Map the user flows.** For each top task, lay out the step-by-step path through the IA the user must take. Flag steps with ambiguous labels, dead ends, or excessive depth.
+4. **Design navigation from the IA.** Choose navigation components that expose the grouping from step 2. Navigation must reflect the IA, not fight it.
+5. **Plan the usability test (Day 1).** Pick 3-5 representative tasks phrased as goals ("find and X"), not instructions. Recruit ~5 participants per user group — five participants uncover the majority of the most common problems. Decide qualitative (discover problems) vs. quantitative (benchmark success rate / time-on-task); for pre-launch validation, run qualitative.
+6. **Conduct the test (Day 2).** A facilitator gives one task at a time and observes behavior and listens for feedback. The facilitator must **not** lead, hint, or rescue the participant — stay neutral so the data stays valid; ask follow-up questions only to clarify, after the attempt.
+7. **Analyze and recommend (Day 3).** Cluster observed problems by where they occur in the IA/flow, rank by severity (how many users hit it × how badly it blocks the task), and propose specific IA/navigation/label fixes.
+8. **Iterate.** Revise the IA or navigation for high-severity issues and, for risky changes, re-test with a fresh set of ~5 users.
+
+## Output format
+- A `ux-validation.md` in the workspace containing:
+  - The IA artifact: content inventory + the grouped taxonomy (sitemap/tree).
+  - Flow diagrams for the top tasks.
+  - The test plan: tasks, participant profile and count, qual/quant choice.
+  - Findings table: `Problem | Location in IA/flow | Users affected | Severity | Recommended fix`.
+- Navigation spec derived from the validated IA (component list + labels).
+
+## Quality & validation rules
+- IA is defined and audited *before* navigation is finalized (step 1 ordering is mandatory).
+- Every navigation label traces to a taxonomy term from the IA — no orphan labels.
+- The test used ≥5 participants per user group and tasks phrased as goals, not click-by-click instructions.
+- The facilitator did not lead participants; findings reflect observed behavior, not the team's opinions.
+- Every reported problem has a severity and a concrete fix; "users were confused" with no location/fix is not a finding.
+- High-severity fixes are re-tested before being declared resolved.
+
+## Failure handling
+- **Can't recruit 5 users** → run with the most you can get plus an expert heuristic review, and label confidence as reduced; do not present thin results as definitive.
+- **Test reveals the IA grouping is wrong** → return to step 2 (regroup), do not patch with navigation tweaks over a broken structure.
+- **Facilitator bias suspected** → discard tainted sessions and re-run with neutral facilitation rather than reporting compromised data.
+- **No clear top tasks** → stop and define them with stakeholders; you cannot validate flows for undefined goals.
+
+## Related
+- Sources:
+  - IA vs. navigation — https://www.nngroup.com/articles/ia-vs-navigation/
+  - Usability testing 101 — https://www.nngroup.com/articles/usability-testing-101/
+- Skills: `process/app-planning`

package/skills/references/ai-attachments-ui/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ai-attachments-ui
+description: Attachment UI patterns for AI chat using AI Elements' Attachments component; consult when showing files/sources in prompts and messages.
+domain: reference
+category: reference
+tags: [ai-elements, attachments, file-upload, ai-ui, shadcn, react]
+official_sources:
+  - https://elements.ai-sdk.dev/components/attachments
+  - https://github.com/vercel/ai-elements
+verified: 2026-06-16
+---
+
+# AI Attachments UI
+
+## Overview
+The Attachments component from Vercel's AI Elements provides a unified way to display file attachments and source documents in AI chat UIs, with grid, inline, and list layout variants. It is a set of composable sub-components that render previews, file info, and a remove control, and it accepts AI SDK `FileUIPart` / `SourceDocumentUIPart` data. Read this when building file-upload affordances in a prompt input or showing attached/source files inside messages.
+
+## Official sources
+- Docs: https://elements.ai-sdk.dev/components/attachments
+- Repo: https://github.com/vercel/ai-elements
+- Setup: https://elements.ai-sdk.dev/docs/setup
+
+## Install / setup
+```bash
+npx ai-elements@latest add attachments
+```
+Requires shadcn/ui initialized and Tailwind CSS Variables mode (per AI Elements setup).
+
+## Core concepts
+- `<Attachments />` is the container and takes a `variant` of `"grid" | "inline" | "list"` to control layout.
+- `<Attachment />` wraps a single item and accepts `data` (a `FileUIPart` or `SourceDocumentUIPart` with an id) plus an `onRemove` callback.
+- Composable sub-parts: `<AttachmentPreview />` (image/video/icon), `<AttachmentInfo />` (filename + media type), `<AttachmentRemove />` (remove button), `<AttachmentHoverCard />` (hover preview), `<AttachmentEmpty />` (empty state).
+- `AttachmentInfo` exposes `showMediaType`, and `AttachmentRemove` accepts a custom `label` for accessibility.
+- Designed to map directly over AI SDK file/source-document parts, so it pairs naturally with Prompt Input and Message.
+
+## Best practices
+- Choose the layout `variant` to match context: `grid` for galleries, `inline` for compact prompt-bar chips, `list` for detailed/source views.
+- Provide an accessible `label` on `AttachmentRemove` so screen-reader users understand the remove action.
+- Render attachments by mapping AI SDK `FileUIPart` data rather than inventing a parallel attachment shape.
+- Use `AttachmentEmpty` to communicate the empty state instead of rendering nothing.
+
+## Common pitfalls
+- Passing data without a stable `id` → each attachment's `data` should carry an id so list rendering and removal stay correct.
+- Building custom remove buttons → use `AttachmentRemove` with `onRemove` so behavior and a11y are handled.
+- Forgetting media-type cues → enable `showMediaType` / previews so users can tell files apart at a glance.
+
+## Examples
+```tsx
+<Attachments variant="grid">
+  {files.map((file) => (
+    <Attachment key={file.id} data={file} onRemove={() => remove(file.id)}>
+      <AttachmentPreview />
+      <AttachmentInfo showMediaType />
+      <AttachmentRemove label="Remove attachment" />
+    </Attachment>
+  ))}
+</Attachments>
+```
+
+## Further reading
+- Prompt Input component: https://elements.ai-sdk.dev/
+- AI SDK docs: https://ai-sdk.dev/
+
+## Related skills
+- ../vercel-ai-sdk-elements — the parent AI Elements library
+- ../ai-tool-ui-patterns — rendering tool results in chat

package/skills/references/ai-in-browser-webllm/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ai-in-browser-webllm
+description: Run LLMs fully in-browser/locally with WebLLM via WebGPU; consult for client-side inference, offline AI, and OpenAI-style chat without a server.
+domain: reference
+category: reference
+tags: [webllm, llm, webgpu, in-browser, mlc, local-inference]
+official_sources:
+  - https://webllm.mlc.ai/docs/
+  - https://github.com/mlc-ai/web-llm
+verified: 2026-06-16
+---
+
+# WebLLM — In-Browser LLM Inference
+
+## Overview
+WebLLM is a high-performance, in-browser LLM inference engine from the MLC project. It runs open models (Llama 3, Phi 3, Gemma, Mistral, Qwen, and more) entirely on the client using WebGPU for hardware acceleration, with no server-side processing. It exposes an OpenAI-compatible API (streaming, JSON mode), making it useful for privacy-preserving, offline-capable, or zero-backend AI features. Read this when you need client-side inference in a web app.
+
+## Official sources
+- Docs: https://webllm.mlc.ai/docs/
+- Repo: https://github.com/mlc-ai/web-llm
+- Getting started: https://webllm.mlc.ai/docs/user/get_started.html
+
+## Install / setup
+```bash
+npm install @mlc-ai/web-llm
+```
+yarn and pnpm equivalents are documented:
+```bash
+yarn add @mlc-ai/web-llm
+pnpm install @mlc-ai/web-llm
+```
+
+## Core concepts
+- `MLCEngine` is the core interface for model loading, chat completions, and embeddings; create it with the `CreateMLCEngine` factory or `new MLCEngine()` then `engine.reload(model)`.
+- Models load asynchronously; pass an `initProgressCallback` to surface download/compile progress to users (first load can be large).
+- WebGPU is the acceleration backend — runs entirely in-browser with no server support required.
+- OpenAI-compatible chat completion API, including streaming and structured JSON-mode output.
+- Built-in model registry plus support for custom MLC-format models compiled via MLC LLM.
+- Cache backends for model weights: Cache API, IndexedDB, OPFS, and Cross-Origin Storage; optional SRI integrity verification.
+
+## Best practices
+- Offload generation to a Web Worker or Service Worker so heavy compute does not block the main UI thread (documented in Advanced Use Cases).
+- Reuse a single loaded engine instance and persist weights in a cache backend to avoid re-downloading on every visit.
+- Always wire `initProgressCallback` so users see progress during the first (potentially large) model download.
+- Pick the smallest model that meets quality needs; in-browser memory and download size are real constraints.
+
+## Common pitfalls
+- Assuming it works everywhere → WebGPU support is required; gate the feature and provide a fallback when the browser/device lacks it.
+- Loading the model on the main thread → use a Web Worker / Service Worker to keep the UI responsive.
+- Treating first load as instant → weights must download and compile; cache them and show progress.
+
+## Examples
+```javascript
+import { CreateMLCEngine } from "@mlc-ai/web-llm";
+
+const engine = await CreateMLCEngine(
+  "Llama-3.1-8B-Instruct-q4f32_1-MLC",
+  { initProgressCallback: (p) => console.log(p) }
+);
+
+const reply = await engine.chat.completions.create({
+  messages: [{ role: "user", content: "Hello!" }],
+});
+console.log(reply.choices[0].message.content);
+```
+
+## Further reading
+- Basic Usage: https://webllm.mlc.ai/docs/user/basic_usage.html
+- API Reference: https://webllm.mlc.ai/docs/user/api_reference.html
+- Advanced Use Cases (Web Worker): https://webllm.mlc.ai/docs/user/advanced_usage.html
+
+## Related skills
+- ../vercel-ai-sdk-elements — UI components for AI-native apps
+- ../ai-tool-ui-patterns — rendering tool-call results in chat UIs

package/skills/references/ai-tool-ui-patterns/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ai-tool-ui-patterns
+description: UI patterns for AI tool-calls and results — turn tool JSON into typed, validated components; consult when rendering tool outputs in chat.
+domain: reference
+category: reference
+tags: [tool-ui, ai-ui, tool-calling, zod, shadcn, assistant-ui]
+official_sources:
+  - https://www.tool-ui.com/docs/overview
+  - https://github.com/assistant-ui/tool-ui
+verified: 2026-06-16
+---
+
+# AI Tool UI Patterns
+
+## Overview
+When a model calls a tool, most apps dump raw JSON into the conversation. Tool UI (by the assistant-ui project) is an open-source component library where each component turns a specific kind of tool output — a card, table, option list, chart, approval, form, or media card — into real, interactive UI so users can understand and act without leaving the chat. It is JSON-native, typed (Zod schemas), accessible, and built on Tailwind, Radix, and shadcn/ui. Read this when designing how tool-call results render and how users approve or respond to them.
+
+## Official sources
+- Docs: https://www.tool-ui.com/docs/overview
+- Repo: https://github.com/assistant-ui/tool-ui
+- Quick start: https://www.tool-ui.com/docs/quick-start
+
+## Install / setup
+```bash
+npx shadcn@latest add @tool-ui/link-preview
+```
+Components use the shadcn copy/paste model — they live in your codebase with no dependency lock-in; swap `link-preview` for any component name.
+
+## Core concepts
+- Each component maps one kind of tool output to UI (table, chart, option list, approval, form, media card), instead of showing raw JSON.
+- Copy/paste model (like shadcn/ui): components live in your repo, so there is no dependency lock-in.
+- Every component ships a colocated `schema.ts` Zod schema; tool output is validated, rendered when valid, and fails safely when not.
+- A three-part flow: backend tool defines input/output via AI SDK + Zod, the schema validates on server and client, and a frontend `toolkit` maps tool names to components.
+- Built on Tailwind, Radix, and shadcn/ui, so it inherits accessible primitives and your theme.
+
+## Best practices
+- Validate tool output against the component's Zod schema on both server and client before rendering.
+- Maintain a `toolkit` mapping of backend tool names to frontend components so the runtime can pick the right renderer.
+- Prefer interactive surfaces (approvals, forms) over read-only JSON dumps for actions the user must take.
+- Since components are copied into your repo, version and customize them deliberately rather than expecting upstream updates.
+
+## Common pitfalls
+- Rendering unvalidated tool JSON → parse against the Zod schema and fail safely when it does not match.
+- Hard-coding which component renders a tool → use the `toolkit` name→component map so new tools are easy to wire.
+- Treating it like an installed npm package → it is copy/paste; you own the code and its updates.
+
+## Examples
+```ts
+// Register tools -> components so the runtime knows what to render.
+const toolkit = {
+  getMetrics: MetricsTable,
+  deployPlan: ApprovalCard,
+  linkPreview: LinkPreview,
+};
+```
+
+## Further reading
+- Quick start: https://www.tool-ui.com/docs/quick-start
+- assistant-ui project: https://github.com/assistant-ui
+
+## Related skills
+- ../vercel-ai-sdk-elements — AI Elements (includes a Tool component)
+- ../ai-attachments-ui — attachment UI patterns