constella 0.1.0

package/skills/process/product-discovery/SKILL.md

@@ -0,0 +1,53 @@
+# Skill — product-discovery
+
+**Trigger:** A new product, feature, or initiative is proposed and the problem space, the users, or "is this worth building" is still uncertain — i.e. before any spec or mock exists.
+
+Produces an evidence-backed problem statement plus the user-needs and constraints that justify (or kill) the work, so the team commits to building the right thing.
+
+## When to use
+- New work was just born (DM @ada / `/planner New Work`) and the requestor described a *desired outcome*, not a validated problem.
+- There are many unknowns, stakeholders are not aligned on the goal, a new market/regulation/strategy shift triggered the request, or a chronic problem keeps recurring.
+- You are tempted to jump straight to a mock or schema but cannot yet name *who* hurts, *what* they are trying to accomplish, and *what evidence* says so.
+
+## When NOT to use
+- The problem is already validated and documented (a discovery artifact or prior spec already states the user, the job, and the evidence) — go to `idea-to-product` or `requirements-to-specs`.
+- The change is a bug fix, a small refactor, or a 1:1 reproduction of an approved mock (Constella parity work) where the "right thing" is already fixed.
+- The work is purely internal/technical with no end-user-facing behavior to validate.
+
+## Required context & inputs
+- The raw request and who asked for it (the requestor / stakeholder).
+- The org's `.claude/CLAUDE.md` (declared product, stack, existing personas/journeys).
+- Any existing research, analytics, support tickets, or prior solutions attempted for this problem.
+- Access to (or a documented stand-in for) the target users.
+
+## Procedure
+Discovery is the **Discover → Define** half of the Double Diamond: diverge to explore the problem space, then converge on one evidenced problem statement (see Related). Run it as a bounded phase, not open-ended research.
+
+1. **Frame the inquiry.** Write the open questions discovery must answer ("Who experiences this? What are they trying to get done? How often / how costly? What have they tried?"). Timebox the phase explicitly.
+2. **Interview stakeholders.** Capture the business objective, constraints, success metric, and every solution already attempted (so you do not re-propose a known failure).
+3. **Run exploratory user research.** Use interviews, field/diary studies, or a short survey to learn the problem space firsthand. Talk to real users (or the closest available proxy); record verbatim pains, not feature requests.
+4. **Synthesize (converge).** Affinity-map the findings. Cluster pains into a small set of user-needs statements. Separate *observed evidence* from *assumption* — flag every assumption as a risk to validate.
+5. **Write the problem statement.** One paragraph: the user, the job/outcome they cannot achieve today, the evidence, and the cost of leaving it unsolved. It must be falsifiable.
+6. **Test the three lenses.** Confirm a solution would be **desirable** (users want it), **viable** (the org can sustain it), and **feasible** (buildable on the current stack). If any lens fails, say so.
+7. **Produce light artifacts only as needed:** persona(s), a journey map or service blueprint of the current painful experience, and a high-level concept — *not* a finished design.
+8. **Recommend go / pivot / no-go** with the evidence that drives the recommendation.
+
+## Output format
+- A `discovery.md` (in the work item's planning folder) containing: open questions, stakeholder notes, research method + participants, synthesized user-needs, the **problem statement**, assumptions-as-risks, the desirability/viability/feasibility verdict, and a go/pivot/no-go recommendation.
+- Optional supporting artifacts (persona, current-state journey map) linked from `discovery.md`.
+
+## Quality & validation rules
+- The problem statement names a real user and a real job, and is backed by at least one piece of gathered evidence (interview quote, datum, ticket) — never by assumption alone.
+- Every assumption is listed as a risk with how it would be validated. Done = no un-flagged assumptions masquerading as fact.
+- Discovery answered its open questions or explicitly states which remain open and why. The phase has a recorded end; it is not still "in progress" when a recommendation is made.
+- No solution detail (screens, schemas, endpoints) leaked into discovery output.
+
+## Failure handling
+- **Cannot reach users / no evidence available:** do not fabricate findings. Record the gap, mark the related needs as unvalidated assumptions, and lower the recommendation confidence.
+- **Findings contradict the original request:** reframe the problem (hand off to `problem-framing`) and report the conflict to the requestor rather than forcing the original solution.
+- **Discovery keeps expanding:** stop at the timebox, ship the strongest evidenced problem statement you have, and list remaining unknowns as follow-up.
+- Record blockers and the decision trail in `discovery.md` so the next phase inherits the reasoning.
+
+## Related
+- Sources: https://www.nngroup.com/articles/discovery-phase/ ; Double Diamond — https://www.designcouncil.org.uk/our-resources/the-double-diamond/
+- Skills: ../problem-framing, ../idea-to-product, ../mocks-and-screen-flows

package/skills/process/readme-generation/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: readme-generation
+description: Generate a beautiful, non-generic project README — capsule-render banner, shields badges derived from the real stack, emoji section headers, a tech-stack table, ASCII architecture, getting-started, configuration, commands, roadmap, contributing and license. Consult whenever creating or rewriting a project README.
+domain: process
+category: process
+tags:
+  - readme
+  - documentation
+  - shields
+  - capsule-render
+  - markdown
+  - open-source
+official_sources:
+  - https://shields.io/
+  - https://github.com/Ileriayo/markdown-badges
+  - https://github.com/othneildrew/Best-README-Template
+verified: 2026-06-16
+---
+
+## Overview
+
+A README is the front door of a project. It must be **specific to THIS project** — never a generic
+"Scaffolded by X" stub. This skill is the standard for authoring (or rewriting) a README that is
+beautiful, complete, and immediately useful to a newcomer.
+
+## When to use
+
+- A project was just scaffolded and its `README.md` is generic or thin.
+- The stack, mission, or scope changed and the README is now stale.
+- The operator asks to "improve the README" or "make the docs look professional".
+
+## Quality bar (a great README has ALL of these)
+
+1. **Banner** — a `capsule-render` waving header with the project name + one-line mission, colored
+   to the project's own palette (not a default).
+2. **Badge row** — `shields.io` badges for each defining stack item (language, runtime, framework,
+   database, …) using the real brand logo + color, plus license + a "built with" badge.
+3. **Table of Contents** — anchor links to every section.
+4. **Emoji section headers** (`## 🎯 About`, `## 🧩 Tech Stack`, …) — scannable and consistent.
+5. **About** — the mission as a blockquote + the concrete objective; what the project does and why.
+6. **Tech Stack table** — Layer → Technology, ideally with each tech's devicon.
+7. **Architecture** — a compact ASCII diagram filled with the REAL stack (client → server → data).
+8. **Getting Started** — real, copy-pasteable install + run commands for the actual runtime
+   (npm/bun/deno/pip/cargo/go), prerequisites, and the `.env` setup step.
+9. **Configuration** — a table of environment variables (name · description · required) + a note
+   that secrets never get hard-coded.
+10. **Commands** — dev / build / test / lint for the real toolchain.
+11. **Project Structure** — a tree of the top-level directories with one-line purposes.
+12. **Roadmap** — a checklist (done/now/next) — optionally a progress badge.
+13. **Contributing** — branch/PR/test expectations, link to code standards.
+14. **License** — name + link, matched by a badge.
+15. **Footer** — a closing `capsule-render` wave or a small credit line.
+
+## Procedure
+
+1. **Read the project facts.** Get the company/mission/objective and the chosen stack from
+   `.claude/CLAUDE.md` (and `workspace.stack`). Never invent a stack — use what's configured.
+2. **Pick a palette** from the project identity (deterministic from the name) for the banner +
+   accents, so the README has its own look.
+3. **Derive badges** from each stack value (see the Badge cookbook). One badge per defining pick.
+4. **Write each section** in the order of the Quality bar. Fill the architecture diagram and the
+   commands from the actual runtime — no placeholders, no lorem ipsum.
+5. **Verify**: every TOC link resolves to a real `## ` anchor; every badge/logo slug is valid;
+   relative links (`./DOCS`, `./LICENSE`) point at files that exist; no empty sections remain.
+6. **Write** to `README.md`. Keep it deterministic and re-renderable.
+
+## Badge cookbook
+
+- **Shields static badge:**
+  `https://img.shields.io/badge/<LABEL>-<HEXCOLOR>?style=for-the-badge&logo=<simple-icons-slug>&logoColor=white`
+  - Escape the label: `-` → `--`, `_` → `__`, space → `_`.
+  - `<simple-icons-slug>` comes from https://simpleicons.org (e.g. `typescript`, `nodedotjs`,
+    `postgresql`, `react`, `tailwindcss`, `docker`). If unknown, omit `&logo=`.
+- **Capsule-render banner:**
+  `https://capsule-render.vercel.app/api?type=waving&height=200&color=0:<HEX1>,100:<HEX2>&text=<URL-ENCODED-NAME>&fontColor=ffffff&fontSize=64&desc=<URL-ENCODED-TAGLINE>&descSize=16&descColor=ffffff`
+- **Devicon (for the stack table):**
+  `https://cdn.jsdelivr.net/gh/devicons/devicon/icons/<slug>/<slug>-original.svg` — embed via
+  `<img src="…" width="18" />`. Fall back to plain text if the slug doesn't exist.
+
+## Anti-patterns (never do)
+
+- A generic 3-line README (`# Name\n\nMission\n\nScaffolded by …`).
+- Lorem ipsum, TODO placeholders, or empty sections.
+- Badges for technologies not actually in the stack, or broken logo slugs (renders an ugly grey box).
+- Hard-coded secrets, internal URLs, or real tokens anywhere in the README.
+- Inventing install commands that don't match the runtime.
+
+## Related
+
+- [[clean-code]] · [[git-workflow]] · [[authoring-agent-skills]]

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

@@ -0,0 +1,53 @@
+# Skill — requirements-to-specs
+
+**Trigger:** Requirements exist (from discovery, a slice, or stakeholder input) and must become testable specs with explicit acceptance criteria — before they are decomposed into issues or implemented.
+
+Produces user stories with testable acceptance criteria (the "Confirmation" of each story) so every requirement has an unambiguous, verifiable definition of done.
+
+## When to use
+- You have requirements/needs and must turn them into something a team can build *and verify*.
+- A requirement is stated vaguely ("users should be able to manage their data") and needs concrete, testable conditions.
+- Before `specs-to-issues`, so each issue inherits clear acceptance criteria.
+
+## When NOT to use
+- The problem/slice is not yet validated — go to `product-discovery` / `idea-to-product`.
+- Acceptance criteria already exist and are testable — go straight to `specs-to-issues`.
+- It is exploratory research with no commitment to build.
+
+## Required context & inputs
+- The validated requirements / `mvp-slice.md` and problem statement.
+- The wireflow + behavior annotations (`screen-flows.md`) and `architecture.md` if they exist.
+- The org's `.claude/CLAUDE.md` conventions and (for Constella) the canonical `Spec.html` PAGES `beh:`/`cmp:` parity definitions.
+
+## Procedure
+Capture requirements lightweightly as **user stories** and confirm each with **acceptance criteria** — the conditions a story must satisfy to be complete, written as clear, concise, testable statements (Atlassian; the 3 C's = Card, Conversation, Confirmation — see Related).
+
+1. **Express each requirement as a user story.** Use the template: *"As a [persona], I want to [action], so that [benefit/outcome]."* Keep it user-centric and solution-light.
+2. **Hold the conversation.** Note the open questions and assumptions for each story; resolve them with the product owner. The card is a placeholder for this conversation, not a full spec.
+3. **Write acceptance criteria (the Confirmation).** For each story, list the conditions that must be true for it to be done. Prefer:
+   - **Scenario-oriented (Given/When/Then)** for behavior with clear pre-conditions, actions, and outcomes; and/or
+   - **Rule-oriented checklists** for constraints, validations, and states.
+4. **Make criteria testable.** Each criterion must be objectively pass/fail — no "fast", "intuitive", or "nice". State concrete values, states, and error cases.
+5. **Cover non-happy paths.** Add criteria for empty/error/permission/validation states surfaced in the wireflow.
+6. **Add non-functional acceptance** where relevant (performance budget, accessibility, security, and — for Constella — visual + structural parity to the baseline at the spec'd viewport).
+7. **Check sizing.** A story should be small enough to build and verify within one increment; if its criteria sprawl, split it (defer the split mechanics to `specs-to-issues`/`breaking-work-into-sprints`).
+8. **Get sign-off** on the criteria from whoever validates "done."
+
+## Output format
+- A `specs.md` (in the work item's planning folder): one section per user story (`As a … I want to … so that …`) followed by its acceptance criteria as Given/When/Then scenarios and/or a checklist, plus any non-functional criteria and a link to the relevant wireflow node.
+
+## Quality & validation rules
+- Every requirement maps to at least one story, and every story has at least one acceptance criterion.
+- Every acceptance criterion is testable (objectively pass/fail) — a tester or automated check could confirm it without judgment calls.
+- Non-happy-path and applicable non-functional criteria are present, not just the happy path.
+- Criteria are solution-aware but not over-prescriptive of implementation. Done = each story's "done" is unambiguous and signed off, and (for Constella) parity criteria reference the canonical `Spec.html` behavior/component definitions.
+
+## Failure handling
+- **A requirement cannot be made testable:** it is too vague — loop back to the product owner / `problem-framing` to sharpen it; do not write a criterion you cannot verify.
+- **Criteria reveal hidden complexity:** split the story and flag scope growth to planning.
+- **Conflict between stories' criteria:** record the conflict and resolve before issues are created.
+- Log unresolved questions per story in `specs.md` so they block, rather than silently leak into, implementation.
+
+## Related
+- Sources: https://www.atlassian.com/agile/project-management/user-stories ; https://www.atlassian.com/work-management/project-management/acceptance-criteria ; Given/When/Then (Gherkin) — https://cucumber.io/docs/gherkin/reference/
+- Skills: ../idea-to-product, ../mocks-and-screen-flows, ../specs-to-issues, ../breaking-work-into-sprints

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`