constella 0.1.0

package/skills/meta/progressive-disclosure/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: progressive-disclosure
+description: Keep SKILL.md short and push depth into on-demand reference files so agents load only what each task needs. Consult when a skill grows large.
+domain: meta
+category: meta
+tags: [progressive-disclosure, agent-skills, context-window, reference-files, token-budget]
+official_sources:
+  - https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+  - https://github.com/anthropics/skills
+verified: 2026-06-16
+---
+
+# Progressive Disclosure
+
+## Overview
+Progressive disclosure is the design principle behind Agent Skills: an agent loads information in stages as a task calls for it, rather than consuming the whole skill up front. A short `SKILL.md` acts like a table of contents that points to deeper reference files, scripts, and assets, which are read or executed only on demand. Read this when a skill is getting long, its body exceeds the recommended budget, or you want bundled reference material to stay out of context until needed.
+
+## Official sources
+- Docs (best practices, "Progressive disclosure patterns"): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+- Docs (overview, "How Skills work"): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Open spec ("Progressive disclosure"): https://agentskills.io/specification
+- Repo (official examples): https://github.com/anthropics/skills
+
+## Core concepts
+- **Three loading levels.** Level 1: metadata (`name` + `description`, ~100 tokens) loaded at startup for every skill. Level 2: the `SKILL.md` body, loaded when the skill triggers. Level 3: bundled files in `scripts/`, `references/`, `assets/`, loaded only when actually accessed.
+- **The context window is a shared public good.** Once `SKILL.md` is loaded, every token competes with conversation history and other skills' metadata — conciseness still matters even though bundled files are free until read (best-practices, "Concise is key").
+- **Bundled content has no context penalty until used.** A skill can ship comprehensive API docs, large datasets, or many examples; files consume zero tokens until the agent reads them (overview, "Level 3").
+- **Scripts execute without entering context.** Running `validate.py` via bash brings only its output into context, not the source — cheaper and more reliable than regenerating equivalent code.
+- **`SKILL.md` is a navigation hub.** Treat it like an onboarding guide's table of contents that links to the right detailed file for each branch of the task.
+
+## Best practices
+- Keep the `SKILL.md` body under 500 lines; split content into separate files as you approach the limit (best-practices, "Token budgets").
+- Keep file references one level deep from `SKILL.md` so the agent reads complete files instead of partial `head -100` previews (best-practices, "Avoid deeply nested references").
+- Organize reference files by domain (`reference/finance.md`, `reference/sales.md`) so a query about one domain never pulls in unrelated context (best-practices, "Pattern 2: Domain-specific organization").
+- Add a table of contents to any reference file longer than ~100 lines so the agent can see its full scope even when previewing (best-practices, "Structure longer reference files").
+- Use forward slashes in all paths so references resolve across platforms (best-practices, "Anti-patterns to avoid").
+
+## Common pitfalls
+- Cramming every detail into `SKILL.md` → move advanced/edge-case material into linked reference files that load only when relevant.
+- Deeply nested reference chains (`SKILL.md` → `advanced.md` → `details.md`) → the agent may read referenced-from-referenced files only partially; keep all links one level deep from `SKILL.md`.
+- Over-explaining things the agent already knows → trim it; padding `SKILL.md` raises token cost without adding signal (best-practices, "Default assumption: Claude is already very smart").
+
+## Examples
+```markdown
+# BigQuery Data Analysis
+
+## Available datasets
+- Finance: revenue, ARR, billing — see reference/finance.md
+- Sales: opportunities, pipeline — see reference/sales.md
+- Product: API usage, adoption — see reference/product.md
+
+## Quick search
+Find metrics with grep:
+
+    grep -i "revenue" reference/finance.md
+```
+The body stays tiny; `reference/finance.md` is read only when a query is about finance, leaving the other reference files at zero token cost.
+
+## Further reading
+- Overview, "Three types of Skill content, three levels of loading": https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Best-practices authoring checklist: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+
+## Related skills
+- ../authoring-agent-skills — the overall skill folder + SKILL.md format
+- ../skill-frontmatter-spec — the metadata fields loaded at Level 1

package/skills/meta/skill-frontmatter-spec/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: skill-frontmatter-spec
+description: SKILL.md YAML frontmatter fields (name, description, license, compatibility, metadata, allowed-tools) and constraints. Consult when writing frontmatter.
+domain: meta
+category: meta
+tags: [frontmatter, yaml, agent-skills, skill-md, spec]
+official_sources:
+  - https://agentskills.io/specification
+  - https://github.com/agentskills/agentskills
+verified: 2026-06-16
+---
+
+# SKILL.md Frontmatter Spec
+
+## Overview
+Every Agent Skill begins with YAML frontmatter at the top of its `SKILL.md`. Two fields are required (`name`, `description`); the open Agent Skills specification also defines optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and clients may add their own (unknown fields are ignored for forward compatibility). Read this when authoring frontmatter, debugging why a skill fails validation, or aligning frontmatter conventions across repos like anthropics/skills, vercel-labs/agent-skills, and remotion-dev/skills.
+
+## Official sources
+- Spec (full frontmatter table + per-field rules): https://agentskills.io/specification
+- Spec repo + `skills-ref` validator: https://github.com/agentskills/agentskills
+- Anthropic field requirements (overview, "Skill structure"): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Example skills using this frontmatter: https://github.com/anthropics/skills · https://github.com/vercel-labs/agent-skills · https://github.com/remotion-dev/skills
+
+## Core concepts
+- **`name` (required).** 1–64 chars, lowercase letters/numbers/hyphens only (`^[a-z0-9]+(-[a-z0-9]+)*$`), no leading/trailing or consecutive hyphens, and must match the parent directory name. Anthropic's docs additionally forbid the reserved words `anthropic` and `claude` and any XML tags.
+- **`description` (required).** 1–1024 chars, non-empty, no XML tags; should state what the skill does and when to use it, with discovery keywords. It is loaded into the system prompt at startup, so it drives skill selection.
+- **`license` (optional).** A license name or a reference to a bundled license file; keep it short (spec, `license` field).
+- **`compatibility` (optional).** Up to 500 chars describing environment needs (intended product, required system packages, network access). Most skills omit it (spec, `compatibility` field).
+- **`metadata` (optional).** An arbitrary string-to-string map for client-specific data such as `author` and `version`; use reasonably unique keys to avoid conflicts (spec, `metadata` field).
+- **`allowed-tools` (optional, experimental).** A space-separated string of pre-approved tools, e.g. `Bash(git:*) Bash(jq:*) Read`; support varies by agent implementation (spec, `allowed-tools` field).
+
+## Best practices
+- Make the `name` exactly match the skill's directory name — the spec requires it and validators enforce it.
+- Validate frontmatter with the reference tool before shipping: `skills-ref validate ./my-skill` (spec, "Validation").
+- Quote ambiguous YAML scalars (e.g. `version: "1.0"`) so they are not parsed as numbers (spec `metadata` example uses quotes).
+- Treat the `description` as a discovery surface: front-load distinctive keywords and the triggering context, since it is the metadata loaded for every skill at startup (Anthropic best-practices, "Writing effective descriptions").
+- Only add `compatibility` when the skill genuinely has environment requirements; leaving it off keeps metadata lean (spec note: "Most skills do not need the `compatibility` field").
+
+## Common pitfalls
+- Uppercase, leading/trailing, or consecutive hyphens in `name` (`PDF-Processing`, `-pdf`, `pdf--processing`) → use lowercase, single-hyphen-separated tokens matching the regex.
+- `name` that differs from the folder name → rename one so they match, or validation fails.
+- Putting custom keys at the top level of the frontmatter → nest non-spec data under `metadata` so it is treated as client metadata rather than an unknown/ignored field.
+- Embedding XML tags or exceeding length limits in `name`/`description` → both fields reject XML tags, and they cap at 64 and 1024 characters respectively.
+
+## Examples
+```yaml
+---
+name: pdf-processing
+description: Extract PDF text, fill forms, merge files. Use when handling PDFs, forms, or document extraction.
+license: Apache-2.0
+compatibility: Requires Python 3.14+ and uv
+metadata:
+  author: example-org
+  version: "1.0"
+allowed-tools: Bash(git:*) Read
+---
+```
+
+## Further reading
+- Full specification with valid/invalid examples per field: https://agentskills.io/specification
+- Anthropic frontmatter requirements + description guidance: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+
+## Related skills
+- ../authoring-agent-skills — the skill folder + SKILL.md format the frontmatter belongs to
+- ../progressive-disclosure — how the frontmatter metadata enables on-demand loading

package/skills/process/adr-technical-decisions/SKILL.md

@@ -0,0 +1,59 @@
+# Skill — adr-technical-decisions
+
+**Trigger:** An architecturally significant technical decision is being made (stack choice, data model, integration approach, cross-cutting pattern) and must be recorded as an Architecture Decision Record before or as it is committed.
+
+Produces a single immutable ADR file capturing the decision, its context, and its consequences, added to the project's decision log.
+
+## When to use
+- Choosing a load-bearing technology, library, protocol, or pattern.
+- Making a trade-off whose rationale future maintainers will need (and would otherwise guess at).
+- Reversing or superseding an earlier architectural decision.
+
+## When NOT to use
+- A reversible, low-impact implementation detail with no real trade-off (just do it; a comment suffices).
+- The decision isn't made yet and you're still prioritizing options — use `process/prioritization-moscow-rice` first, then record the outcome here.
+- General planning (use `process/app-planning`); an ADR records *one* decision, not a whole plan.
+
+## Required context & inputs
+- The decision being made and the forces/constraints driving it.
+- The alternatives considered and why they were or weren't chosen.
+- The existing ADR directory and the next sequence number (check `docs/adr/` or the org's convention).
+- The org's stack and constraints (from `.claude/CLAUDE.md`).
+
+## Procedure
+1. **Confirm it's architecturally significant.** An ADR documents "a justified design choice that addresses a functional or non-functional requirement that is architecturally significant." If the choice is trivial or easily reversed, don't spend an ADR on it.
+2. **Locate the decision log.** Find the ADR directory (commonly `docs/adr/` or `doc/architecture/decisions/`). All ADRs together form the project's **decision log** — the chronological record of architectural choices. If none exists, create the directory and start the sequence at `0001`.
+3. **Assign a sequential number and title.** Number ADRs monotonically (`0001`, `0002`, …) so order is preserved. Title it as a short noun phrase naming the decision (e.g. "0007 — Use Drizzle for the ORM").
+4. **Write the ADR using the standard sections** (Nygard format):
+   - **Title** — the numbered short phrase.
+   - **Status** — one of: proposed, accepted, deprecated, or superseded by ADR-NNNN.
+   - **Context** — the forces at play: the problem, constraints, and assumptions that make this decision necessary. State alternatives considered.
+   - **Decision** — the choice made, stated in active voice ("We will …").
+   - **Consequences** — what becomes easier *and* harder as a result; the trade-offs accepted, including downsides.
+5. **Keep ADRs immutable.** Once accepted, do not edit the substance of an ADR. If the decision changes, write a **new** ADR and mark the old one `superseded by ADR-NNNN`; mark the new one `supersedes ADR-MMMM`. The log preserves history — never rewrite it.
+6. **Set the status correctly.** Use `proposed` while under discussion, flip to `accepted` when committed. Reflect lifecycle changes via new ADRs, not edits.
+7. **Link from the work.** Reference the ADR from the plan, the relevant C4 view, and ideally the code/PR that implements it, so the rationale is discoverable from the artifact.
+
+## Output format
+- A markdown file `docs/adr/NNNN-<slug>.md` (4-digit number) in the project, containing exactly the sections: Title, Status, Context, Decision, Consequences.
+- The decision log is the ordered set of these files; optionally an index/README listing them with status.
+
+## Quality & validation rules
+- The file has all five sections; an ADR missing Context or Consequences is incomplete.
+- Status is one of the valid lifecycle values and accurate.
+- Context names the alternatives considered and the constraints — not just the winner.
+- Consequences honestly state the downsides/trade-offs, not only benefits.
+- The number is unique and sequential; no gaps reused, no duplicates.
+- Superseded decisions are linked in both directions (old ↔ new); accepted ADRs are never edited in substance.
+
+## Failure handling
+- **Decision later proves wrong** → write a new ADR that supersedes it; never delete or silently edit the original — the wrong turn is part of the record.
+- **Can't articulate consequences** → the decision may be premature; gather more context or spike before recording it as accepted.
+- **No ADR directory or convention** → create `docs/adr/` and seed it with `0001` (e.g. "Record architecture decisions in ADRs") to establish the practice.
+- **Two ADRs grabbed the same number** → renumber the later one and update any links; numbers must stay unique.
+
+## Related
+- Sources:
+  - ADR home / definition — https://adr.github.io/
+  - ADR templates & examples — https://github.com/joelparkerhenderson/architecture-decision-record
+- Skills: `process/app-planning`, `process/prioritization-moscow-rice`

package/skills/process/app-planning/SKILL.md

@@ -0,0 +1,63 @@
+# Skill — app-planning
+
+**Trigger:** A new app, service, or major feature area is being started and needs an end-to-end plan — scope, architecture, and milestones — *before* code is written.
+
+Produces a planning document that defines what is being built (scope), how it is structured (C4 architecture views), and how it will be delivered (agile backlog and milestones).
+
+## When to use
+- Kicking off a greenfield app or a substantial new module.
+- The work is large enough to span multiple sprints and needs a shared mental model across the team/agents.
+- Stakeholders need to agree on scope and sequence before implementation starts.
+
+## When NOT to use
+- A bounded change to existing code with an obvious shape (just implement it).
+- The plan exists and only one technical decision is open — use `process/adr-technical-decisions`.
+- You only need a priority order for an existing backlog — use `process/prioritization-moscow-rice`.
+
+## When NOT to use (continued)
+- UX/IA validation of an existing flow — use `process/validating-ux-navigation`.
+
+## Required context & inputs
+- The product goal and target users (who, and what outcome).
+- The org's declared stack, runtime layout, and constraints (from `.claude/CLAUDE.md`).
+- Known external systems the app must integrate with (auth, payment, data sources).
+- Any non-functional requirements: scale, latency, compliance, offline support.
+
+## Procedure
+1. **State scope as outcomes.** Write the problem statement and 3-7 concrete user outcomes. Explicitly list what is *out* of scope for v1 to prevent creep (mirror the MoSCoW "Won't have this time" bucket).
+2. **Identify users and external systems.** Enumerate the people/roles (actors) and the external software systems the app talks to. This is the raw material for the C4 System Context view.
+3. **Draw the C4 System Context view (Level 1).** One diagram: your software system in the middle, the people and external systems around it, and the relationships between them. This is the "big picture" — keep it free of technology detail.
+4. **Draw the C4 Container view (Level 2).** Decompose your system into containers — separately runnable/deployable units (web app, API, database, worker, SPA, mobile app). Show the technology choice per container and how containers communicate. This is where the stack is committed.
+5. **Draw the C4 Component view (Level 3) for the risky containers only.** For each container with non-trivial internal structure, show its major components and responsibilities. Skip containers that are simple CRUD. (Level 4 / Code is generated from the IDE — do not hand-draw it.)
+6. **Define the agile work hierarchy.** Translate scope into the Atlassian hierarchy: group outcomes into **epics** (large bodies of work toward one goal), break each epic into **user stories** sized to fit in a single sprint. Stories that would take weeks become their own epic. The set of epics/stories is the product backlog.
+7. **Prioritize the backlog.** Apply `process/prioritization-moscow-rice` to order stories and define the v1 cut line.
+8. **Sequence into milestones.** Group stories into milestones/iterations along a roadmap, each milestone delivering a coherent, demonstrable increment. Sequence by dependency and priority, front-loading the riskiest architectural assumptions to validate them early.
+9. **Plan the cross-cutting work up front.** Before milestone 1, ensure the plan includes: a threat model entry point (`process/security-by-design`), a test strategy (`process/testing-before-done`), and ADRs for the load-bearing stack/architecture choices made in steps 4-5.
+
+## Output format
+- A `PLAN.md` (or equivalent planning doc) in the workspace containing:
+  - Scope: problem statement, in-scope outcomes, explicit out-of-scope list.
+  - Architecture: C4 Context and Container views (as diagrams or structured text), plus Component views for complex containers.
+  - Stack: the technology committed per container, each with a link to its ADR.
+  - Delivery: epics → stories backlog, prioritized, grouped into milestones on a roadmap.
+- Diagrams may live in `examples/` or be embedded; reference them from `PLAN.md`.
+
+## Quality & validation rules
+- Every in-scope outcome maps to at least one epic; every epic to at least one story; no orphan stories.
+- The C4 views are consistent: every container in Level 2 traces to a system in Level 1; every component in Level 3 lives inside a Level 2 container.
+- Each container's technology choice is named (no "TBD" on load-bearing choices) and the choice with trade-offs is backed by an ADR.
+- Every user story is small enough to fit one sprint; anything larger is promoted to an epic.
+- Milestone 1 exercises the highest-risk architectural assumption, not just the easiest work.
+- Out-of-scope list is non-empty (a plan with nothing excluded is under-scoped).
+
+## Failure handling
+- **Scope keeps growing** → freeze v1 scope, move new asks to "Won't have this time," and revisit after the first milestone.
+- **A container's tech choice is contested** → spike it or open an ADR; do not let the diagram hide an unresolved decision.
+- **Stories won't fit a sprint** → split them; if a story can't be split, it's an epic — re-decompose.
+- **No external systems identified** → re-check; almost every app has auth/data/observability dependencies. An empty Context view usually means the analysis is incomplete.
+
+## Related
+- Sources:
+  - C4 model — https://c4model.com/
+  - Agile (epics/stories/backlog) — https://www.atlassian.com/agile/project-management/epics-stories-themes
+- Skills: `process/prioritization-moscow-rice`, `process/adr-technical-decisions`, `process/security-by-design`, `process/testing-before-done`

package/skills/process/architecture-before-code/SKILL.md

@@ -0,0 +1,52 @@
+# Skill — architecture-before-code
+
+**Trigger:** A scoped slice/feature is about to be implemented and it introduces new systems, boundaries, data flows, or integrations — before writing the implementation.
+
+Produces a shared, just-enough architecture description (C4-style diagrams + the load-bearing decisions) so engineers agree on boundaries and data flow before code locks them in.
+
+## When to use
+- The work adds a new container (service, app, database, queue), a new integration, or a non-trivial data flow across boundaries.
+- Decisions about boundaries, data ownership, or technology are hard to reverse later and must be gotten approximately right early.
+- More than one engineer/agent will touch the system and needs a shared mental model.
+
+## When NOT to use
+- The change fits cleanly inside an existing component with no new boundary or data-flow (just implement, following existing patterns in `.claude/CLAUDE.md`).
+- A current, accurate architecture doc already covers this change.
+- It is a pure UI flow with no architectural impact — use `mocks-and-screen-flows`.
+
+## Required context & inputs
+- The scoped slice (`mvp-slice.md`) and its requirements/specs.
+- The org's `.claude/CLAUDE.md` (declared stack, existing services, runtime root and isolation model, sync/watcher architecture).
+- The existing system's current architecture (read the code/structure to know what is already there).
+
+## Procedure
+Document with the **C4 model**: describe the software at increasing zoom — **System Context → Containers → Components → (optionally) Code** — using the abstractions person, software system, container, and component (see Related). Keep it "just enough": architecture is the shared understanding of the important, hard-to-change stuff (per Fowler), not exhaustive UML.
+
+1. **System Context diagram.** Show the system as one box, the people (actors) who use it, and the external systems it depends on. Establishes scope and who/what it talks to.
+2. **Container diagram.** Decompose the system into deployable/runnable units (web app, API, database, worker, agent runtime) with the technology of each and the data that flows between them. This is the primary architecture artifact for most features.
+3. **Component diagram (only where it adds value).** Inside the container you are changing, show the major components and responsibilities. Skip for containers you are not touching.
+4. **Define boundaries & ownership.** State which container owns which data, the contract (API/event/schema) at each boundary, and the direction of dependencies. Avoid cyclic dependencies between containers.
+5. **Trace the data flow.** Walk the slice's main path across the diagram (a dynamic/sequence view) — request in, transformations, persistence, response out — confirming every hop exists and is owned.
+6. **Record the decisions.** For each significant, hard-to-reverse choice (boundary placement, datastore, sync strategy, build vs. integrate), write a short decision: context, options considered, choice, consequences. Prefer one ADR per decision.
+7. **Check internal quality.** Confirm the design favors high internal quality (clear seams, low coupling) — this speeds future delivery, not slows it (per Fowler). Reject designs that bypass existing isolation/sync boundaries the org depends on.
+8. **Review with the team** before coding; the diagrams are the alignment instrument.
+
+## Output format
+- An `architecture.md` (in the work item's planning folder) containing the C4 Context and Container diagrams (and Component where useful), the boundary/ownership/contract notes, and the traced data flow.
+- One ADR per significant decision (context · options · decision · consequences), linked from `architecture.md`.
+
+## Quality & validation rules
+- Every container has a named responsibility, technology, and the data it owns; every boundary names its contract.
+- The slice's main path traces end-to-end across the diagram with no missing or unowned hop.
+- Each hard-to-reverse decision has a recorded rationale and considered alternatives (an ADR), so future readers know *why*, not just *what*.
+- The design respects the org's existing architectural invariants (e.g. Constella's runtime root, FS isolation/jail, sync-engine/watcher boundaries). Done = a reviewer agrees boundaries and data flow before any implementation begins.
+
+## Failure handling
+- **Two valid boundary options and no clear winner:** record both in the ADR with trade-offs and escalate the decision rather than picking silently.
+- **Design violates an existing invariant:** stop; either redesign within the invariant or raise an explicit, justified ADR to change it.
+- **Architecture grows beyond the slice:** scope the diagram to this slice and note future containers as out-of-scope rather than designing the whole platform.
+- Keep `architecture.md` and ADRs updated if implementation forces a change, so the doc stays the source of truth.
+
+## Related
+- Sources: https://c4model.com/ ; https://martinfowler.com/architecture/ ; ADRs — https://adr.github.io/
+- Skills: ../mocks-and-screen-flows, ../requirements-to-specs, ../specs-to-issues

package/skills/process/breaking-work-into-sprints/SKILL.md

@@ -0,0 +1,53 @@
+# Skill — breaking-work-into-sprints
+
+**Trigger:** A backlog of well-formed issues/stories exists and must be sliced into deliverable increments (sprints) with a goal and a Definition of Done — before the team starts building.
+
+Produces a Sprint Backlog (Sprint Goal + selected items + a plan) where every increment is potentially releasable and meets a shared Definition of Done.
+
+## When to use
+- The work item's backlog (from `specs-to-issues`) is ready and must be scheduled into one or more increments.
+- You need to commit to a focused, achievable goal for the next increment rather than "do everything".
+- A feature is too large for one increment and must be delivered in usable slices.
+
+## When NOT to use
+- Issues/specs do not exist yet — go to `specs-to-issues` / `requirements-to-specs`.
+- Decomposing a raw idea into an MVP — that is `idea-to-product` (this skill schedules already-defined work).
+- The org does not run iterative increments and uses continuous flow only — adapt the Definition-of-Done and increment-sizing parts, skip the time-box.
+
+## Required context & inputs
+- The prioritized backlog of issues (`issues.md`) with acceptance criteria and dependencies.
+- The team's capacity, the Product Goal, and the agreed **Definition of Done**.
+- Dependency/ordering constraints from `architecture.md`.
+
+## Procedure
+Run **Sprint Planning** per the Scrum Guide: a Sprint is a fixed-length container (one month or less) in which ideas turn into value; planning answers **Why** (the Sprint Goal), **What** (selected Product Backlog items), and **How** (the plan to deliver them). Nothing counts as part of the **Increment** until it meets the **Definition of Done** (see Related).
+
+1. **Confirm the Definition of Done.** Make explicit the quality bar an increment must meet to be releasable (built, tested, reviewed, parity-checked, docs updated, deployed/deployable). For Constella, include the 3-axis parity gate and build/typecheck gates.
+2. **Refine the backlog (Why-ready).** Ensure top items are small, clear, and estimated. Split any item too large to finish within one Sprint (`specs-to-issues` mechanics). Order by value and dependency.
+3. **Set the Sprint Goal (Why).** Define one coherent objective for the increment that delivers user/business value — the single thing the increment is *about*. Items are selected to serve it.
+4. **Select the work (What).** Pull the highest-value, dependency-respecting items from the top of the backlog that fit the team's capacity and serve the goal. Do not overcommit; capacity, not ambition, sets the line.
+5. **Plan the delivery (How).** Break selected items into the concrete tasks needed to meet the Definition of Done (build, test, review, integrate). This is the Sprint Backlog.
+6. **Sequence within the increment.** Order tasks so dependencies are satisfied and a usable slice emerges early; front-load the riskiest item.
+7. **Make each increment releasable.** Each Sprint must produce at least one valuable, usable Increment that meets the Definition of Done — not a half-done layer.
+8. **Reserve continuous refinement.** Keep refining the rest of the backlog during the increment so the next planning is fast.
+
+## Output format
+- A `sprint-plan.md` (or tracker sprint/board) per increment containing: the **Sprint Goal**, the **selected items** (links to issues), the **delivery plan** (task breakdown per item), the **Definition of Done** in force, and the dependency-aware sequence.
+- For multi-sprint features, a short increment roadmap listing each Sprint Goal and the releasable slice it ships.
+
+## Quality & validation rules
+- Every selected item fits within the increment and traces to the Sprint Goal; nothing selected is unrelated to the goal.
+- The increment is potentially releasable and every included item can meet the Definition of Done — no item is "done except for testing/review".
+- Selection respects capacity (no overcommit) and dependency order (nothing scheduled before its blocker).
+- The Definition of Done is explicit and shared. Done = the team agrees the plan is achievable and the increment, if completed, ships real value.
+
+## Failure handling
+- **An item is too big for one Sprint:** split it before committing; never carry an unsplittable giant into the increment.
+- **Capacity does not fit the goal:** narrow the Sprint Goal or drop lowest-value items — keep the increment releasable rather than overcommitting.
+- **A blocking dependency is unresolved:** reorder or descope; do not schedule blocked work.
+- **Scope discovered mid-increment:** add to the backlog for refinement, not to the current Sprint, unless it serves the goal and capacity allows; record the change.
+- Log the goal, commitments, and any descoping in `sprint-plan.md` for the increment review.
+
+## Related
+- Sources: https://scrumguides.org/scrum-guide.html (2020 Scrum Guide — Sprint, Sprint Planning, Increment, Definition of Done)
+- Skills: ../specs-to-issues, ../requirements-to-specs, ../idea-to-product

package/skills/process/idea-to-product/SKILL.md

@@ -0,0 +1,50 @@
+# Skill — idea-to-product
+
+**Trigger:** A validated problem (or a strong raw idea) exists and must become a small, buildable, testable slice — before writing specs or code for the whole thing.
+
+Produces a scoped MVP slice with its riskiest assumption, the experiment that tests it, and the success metric — so the team ships the smallest thing that produces validated learning.
+
+## When to use
+- Discovery/framing produced a problem worth solving and you must decide *what to build first*.
+- The idea is large and you need to carve a thin end-to-end slice rather than build everything at once.
+- You want evidence the solution works before investing in the full feature.
+
+## When NOT to use
+- The problem itself is not yet validated — go to `product-discovery` / `problem-framing` first.
+- The slice is already chosen and specced — go to `requirements-to-specs`.
+- Scope is being cut into delivery increments for an *already-committed* feature — that is sprint slicing (`breaking-work-into-sprints`), not idea-to-MVP.
+
+## Required context & inputs
+- The validated problem statement / job-to-be-done (`discovery.md`, `problem-framing.md`).
+- The success metric the business cares about.
+- The org's `.claude/CLAUDE.md` stack and constraints (what is cheap vs expensive to build).
+
+## Procedure
+Apply the Lean Startup **Build–Measure–Learn** loop with a Minimum Viable Product: the smallest thing that lets you start the learning loop and gather **validated learning** (see Related). Optimize for fastest learning, not most features.
+
+1. **State the value & growth hypotheses.** Write the leap-of-faith assumptions the idea depends on (does the user want this? will it produce the intended outcome?). These are the things that, if false, kill the product.
+2. **Rank by risk.** Identify the single riskiest assumption — the one whose failure is most likely and most damaging. The MVP exists to test *that*.
+3. **Design the MVP slice.** Define the thinnest end-to-end path through the product that exercises the riskiest assumption and delivers real value to one user for one job. Cut everything not required to learn. (A concierge, mock, or single-flow build often suffices.)
+4. **Define Measure.** Pick a clear, actionable success metric and the threshold that counts as validation vs. invalidation *before* building. Avoid vanity metrics.
+5. **Specify Learn.** State, in advance, what result will make you persevere, pivot, or stop.
+6. **Scope the build.** List what is in the slice and explicitly what is deferred. Keep the slice releasable and observable.
+7. **Hand the slice off** to `requirements-to-specs` (to make it testable) and `specs-to-issues` (to make it trackable).
+
+## Output format
+- An `mvp-slice.md` (in the work item's planning folder) with: value & growth hypotheses, the ranked riskiest assumption, the MVP slice definition (in-scope path + explicit out-of-scope list), the success metric + validation threshold, and the persevere/pivot/stop criteria.
+
+## Quality & validation rules
+- The slice is end-to-end (a user can complete one real job), releasable, and instrumented to produce the chosen metric.
+- The riskiest assumption is named and the slice demonstrably tests it. Done = building this slice will produce validated learning, not just output.
+- The success threshold and pivot/persevere criteria were written *before* building, so the result cannot be rationalized after the fact.
+- Out-of-scope items are explicit, preventing scope creep.
+
+## Failure handling
+- **Slice still too big to ship fast:** cut to a single flow or a non-code experiment (concierge/Wizard-of-Oz) that still tests the riskiest assumption.
+- **No measurable success metric available:** treat that as the first risk to resolve — define how learning will be observed before building anything.
+- **MVP invalidates the assumption:** that is a successful experiment; record the learning and route back to `problem-framing` to pivot rather than forcing the build.
+- Log hypotheses, metric, and outcome so the next loop iteration builds on real evidence.
+
+## Related
+- Sources: https://leanstartup.co/ ; https://www.nngroup.com/articles/minimum-viable-product/
+- Skills: ../product-discovery, ../problem-framing, ../requirements-to-specs, ../breaking-work-into-sprints

package/skills/process/mocks-and-screen-flows/SKILL.md

@@ -0,0 +1,52 @@
+# Skill — mocks-and-screen-flows
+
+**Trigger:** A scoped slice or feature needs a UI and you are about to design or build screens — before any component or page code is written.
+
+Produces a wireflow (screen mocks wired by interaction arrows) that maps every screen state and transition for the flow, so engineers build from an unambiguous visual + behavioral spec.
+
+## When to use
+- A user-facing flow must be designed: you know the job-to-be-done but not the exact screens, states, and transitions.
+- The app is dynamic (content/state changes on a few core screens, AJAX-style updates, checkout/filter/onboarding flows) where a static screen-by-screen wireframe set would not capture behavior.
+- In Constella, before reproducing or extending UI, to nail the 3-axis parity target (visual + structure + behavior) the build will be judged against.
+
+## When NOT to use
+- The flow is a large static website with many discrete linked pages and little dynamic behavior — a sitemap + page wireframes fit better than a wireflow.
+- An approved mock/`Spec.html` already exists and is canonical — build to it (parity work), do not re-design.
+- No UI is involved (pure backend/data work).
+
+## Required context & inputs
+- The scoped slice (`mvp-slice.md`) and the job-to-be-done / problem statement.
+- The org's design system / existing components and `.claude/CLAUDE.md` UI conventions, plus any prototype baseline to match.
+- The list of user goals/tasks this flow must support.
+
+## Procedure
+Build a **wireflow**: wireframe-style page layouts connected by a simplified flowchart of interactions, where an arrow leaves the specific UI element a user acts on and points to the resulting screen *state* (see Related).
+
+1. **List the tasks & happy path.** Enumerate the user goals this flow serves and the primary (happy-path) sequence of steps to complete each.
+2. **Sketch low-fidelity first.** Rough each distinct screen as a wireframe (layout, key elements, content placeholders) — paper/whiteboard fidelity. Resolve structure before visual polish.
+3. **Wire interactions.** From each actionable element (button, link, field, filter), draw an arrow to the resulting state. That state may be a *new* screen, the *same* screen with changed content, or a feedback element (confirmation, error, loading).
+4. **Cover non-happy states.** Add empty, loading, error, validation-failure, and permission-denied states as their own nodes — these are where builds usually diverge from intent.
+5. **Map branches & loops.** Show decision points (auth required, item in/out of stock) and back/cancel paths so no transition is undefined.
+6. **Raise fidelity to mocks.** Once the flow is complete and reviewed, raise the wireframes to mocks using the design system so visual detail matches the build target.
+7. **Annotate behavior.** Note any logic an image cannot convey (validation rules, what data populates a region, side effects of an action) next to the relevant arrow/node.
+8. **Review against the tasks.** Walk each user task through the wireflow end-to-end; confirm every step has a screen and every action has a defined result.
+
+## Output format
+- A wireflow artifact (image/Figma link, or `Spec.html`-style page in the work item folder) showing every screen state as a node and every interaction as a labeled arrow to its resulting state.
+- A short `screen-flows.md` listing the tasks covered, each screen state, and the behavior annotations (validation, data sources, side effects) keyed to the wireflow.
+
+## Quality & validation rules
+- Every actionable element has exactly one defined resulting state; no dangling or ambiguous transitions.
+- Empty / loading / error / edge states are present, not just the happy path.
+- Every user task from step 1 can be traced node-to-node through the wireflow to completion.
+- Mocks reference real design-system components and (for parity work) match the prototype baseline. Done = an engineer could build the flow without guessing any state or transition.
+
+## Failure handling
+- **A transition's target state is unknown:** stop and resolve it with the product owner; do not let engineering invent it.
+- **Flow has too many screens to wireflow cleanly:** split into sub-flows (one wireflow per task) and link them.
+- **Mock conflicts with design-system constraints:** flag the conflict in `screen-flows.md` and resolve before build, not during.
+- Record open UI questions in `screen-flows.md` so the build phase inherits them.
+
+## Related
+- Sources: https://www.nngroup.com/articles/wireflows/ ; https://www.nngroup.com/articles/wireframe-fidelity/
+- Skills: ../idea-to-product, ../requirements-to-specs, ../architecture-before-code

package/skills/process/prioritization-moscow-rice/SKILL.md

@@ -0,0 +1,64 @@
+# Skill — prioritization-moscow-rice
+
+**Trigger:** A backlog, feature list, or set of competing initiatives needs an explicit, defensible priority order before committing engineering capacity.
+
+Produces a prioritized work list: a MoSCoW categorization for release-scoping plus a RICE-scored ranking for the contested items, with the reasoning recorded.
+
+## When to use
+- You have more candidate work than capacity for the next release/sprint and must decide what is in, what waits, and what is cut.
+- Stakeholders disagree on order and you need an objective, repeatable tiebreaker.
+- Planning a milestone where the "must-have" set defines whether the release ships at all.
+
+## When NOT to use
+- A single obvious item with no contention (just do it).
+- The decision is architectural rather than about *what* to build — use `process/adr-technical-decisions` and `process/app-planning`.
+- You lack any data or even rough estimates for Reach/Impact/Effort and cannot get them — fix that first; do not fabricate scores.
+
+## Required context & inputs
+- The candidate list of features/initiatives, each stated as an outcome (not a solution).
+- The release goal or business objective they serve.
+- Rough estimates per item: how many users it reaches in a fixed time window, expected per-user impact, your confidence, and effort in person-months.
+- The org's declared stack and team size (from `.claude/CLAUDE.md`) to calibrate effort.
+
+## Procedure
+1. **Frame the timebox.** Fix the period RICE Reach is measured over (e.g. "per quarter") and the capacity available (person-months). Every item is scored against the same window — never mix windows.
+2. **First pass — MoSCoW categorize.** Sort every item into exactly one bucket (Dai Clegg's method):
+   - **Must have** — release is useless or broken without it. Non-negotiable for *this* timebox.
+   - **Should have** — important and high-value, but the release still works if it slips to a future release.
+   - **Could have** — nice-to-have, small impact if dropped; the first to be cut if Must/Should overrun.
+   - **Won't have (this time)** — explicitly out of scope for this timebox; record it to prevent scope creep and reset stakeholder expectations.
+3. **Budget the Musts.** If "Must have" exceeds the capacity from step 1, the release is over-scoped — renegotiate scope or timeline now, before scoring further. Musts must fit.
+4. **Second pass — RICE-score the contested tier.** For the Should/Could items competing for the remaining capacity, score each factor:
+   - **Reach** — number of people or events affected in the fixed time window (e.g. 1,200 customers/quarter).
+   - **Impact** — per-person magnitude on the multiple-choice scale: 3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal.
+   - **Confidence** — percentage on the scale: 100% = high, 80% = medium, 50% = low; below that is a moonshot — flag it, don't score it.
+   - **Effort** — total person-months across all functions; use whole numbers, or 0.5 for sub-month work. Higher effort lowers the score.
+5. **Compute the score** for each item: `RICE = (Reach × Impact × Confidence) ÷ Effort`. This yields impact-per-time-worked.
+6. **Rank and slot.** Order the contested items by descending RICE score and fill the remaining capacity top-down. Items that don't fit fall to the next release (re-label them Should/Won't-have-this-time).
+7. **Record the decision.** Capture the bucket, the four raw RICE inputs, and the final score per item so the priority is auditable and re-runnable when estimates change.
+
+## Output format
+- A `prioritization.md` (or the planning doc's priority section) in the workspace containing:
+  - A MoSCoW table: `Item | Bucket | Rationale`.
+  - A RICE table for contested items: `Item | Reach | Impact | Confidence | Effort | RICE score`, sorted descending.
+  - The fixed time window, the capacity budget, and the cut line (what's in vs. deferred).
+
+## Quality & validation rules
+- Every item lands in exactly one MoSCoW bucket; no item is uncategorized.
+- The "Must have" set fits within stated capacity (step 3) — if not, the plan is not done.
+- RICE uses the canonical scales (Impact 3/2/1/0.5/0.25; Confidence 100/80/50%); no invented values.
+- All RICE items share one Reach time window.
+- Each score traces to its four raw inputs — a bare number with no inputs is invalid.
+- MoSCoW is the scoping lens, RICE is the objective tiebreaker; do not rely on MoSCoW alone for the contested tier.
+
+## Failure handling
+- **No reliable estimates** → score Confidence honestly (low/moonshot), mark the item "needs discovery," and exclude it from the committed set rather than guessing high.
+- **Must-haves overflow capacity** → stop and renegotiate scope/timeline with stakeholders; do not silently demote a true Must.
+- **Stakeholder dispute on a bucket** → resolve by RICE-scoring the disputed item; the higher impact-per-effort wins. Record the disagreement and resolution.
+- **Score ties** → break ties by lower Effort (cheaper first) or higher Confidence; note the tiebreak used.
+
+## Related
+- Sources:
+  - MoSCoW — https://www.productplan.com/glossary/moscow-prioritization/
+  - RICE — https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/
+- Skills: `process/app-planning`, `process/adr-technical-decisions`

package/skills/process/problem-framing/SKILL.md

@@ -0,0 +1,51 @@
+# Skill — problem-framing
+
+**Trigger:** A problem statement or request exists but it may be the *wrong* or too-narrow framing — before committing scope, specs, or architecture to it.
+
+Produces a reframed, validated problem statement (often with the underlying job-to-be-done) so the team solves the highest-value version of the problem, not the first one stated.
+
+## When to use
+- Discovery surfaced a problem, or a stakeholder handed you one, and you suspect it is stated as a pre-baked solution ("we need a button that…") rather than a need.
+- The team is jumping straight to solution mode without checking it understands the problem (the most common and most costly failure — most organizations are weak at diagnosis, not solving).
+- Multiple stakeholders describe "the problem" differently.
+
+## When NOT to use
+- The problem is already crisply framed, agreed, and evidenced (proceed to `requirements-to-specs` or `architecture-before-code`).
+- Reframing would be procrastination: the problem is small, well-understood, and the cost of solving the "wrong" version is trivial.
+
+## Required context & inputs
+- The current problem statement and who authored it.
+- `discovery.md` / research evidence if it exists (from `product-discovery`).
+- Access to at least one outsider (someone not embedded in the problem) and the original stakeholders.
+
+## Procedure
+Use Wedell-Wedellsborg's reframing method (HBR, see Related). The goal is **not** to find the "real" problem but to see whether there is a *better* problem to solve. Run a short, repeatable reframing loop.
+
+1. **Establish legitimacy.** Get explicit buy-in that questioning the framing is welcome, so people engage instead of defending the original ask.
+2. **Bring in outsiders.** Include at least one person without stake in the current framing; they spot blind spots insiders cannot.
+3. **Get definitions in writing.** Have each stakeholder write down, in one or two sentences, what they think the problem is. Compare — divergence reveals the real disagreement.
+4. **Ask what's missing.** What does every written definition leave out? Add the missing factors.
+5. **Consider multiple categories.** Is this a process problem? An incentive problem? An expectation problem? Re-categorize deliberately.
+6. **Analyze positive exceptions.** Where does this problem *not* occur (a person, team, or context that already succeeds)? Study why — the reframe often hides there.
+7. **Question the objective.** Ask what goal the stated problem actually serves; a higher goal may have a cheaper or entirely different solution.
+8. **Restate as a job-to-be-done.** Express the chosen frame as the outcome the user is trying to achieve ("When [situation], I want to [motivation], so I can [expected outcome]"), independent of any solution.
+9. **Pick the better problem** and record why it beats the original framing.
+
+## Output format
+- A `problem-framing.md` (in the work item's planning folder) with: the original statement, each stakeholder's written definition, what was missing, alternative categorizations considered, positive exceptions found, the questioned objective, and the **chosen reframed problem statement** expressed as a job-to-be-done, plus a one-line rationale for choosing it.
+
+## Quality & validation rules
+- The final problem statement is solution-free: it names a situation, a motivation, and a desired outcome — no UI, schema, or technology.
+- At least three of the seven reframing practices were actually applied and their output recorded (not just listed).
+- An outsider's input is captured. Done = the reframe is traceable to evidence/perspectives, not to one author's preference.
+- The original framing is preserved alongside the new one so the decision is auditable.
+
+## Failure handling
+- **Reframing produces no better problem:** keep the original framing and record that it was deliberately validated (this is a success, not a waste).
+- **Stakeholders cannot agree on the frame:** escalate the disagreement with the written definitions attached; do not silently pick one.
+- **Reframe invalidates prior discovery:** loop back to `product-discovery` to re-validate the new frame before building on it.
+- Log the chosen frame and rejected alternatives so later phases do not relitigate them.
+
+## Related
+- Sources: https://hbr.org/2017/01/are-you-solving-the-right-problems (Thomas Wedell-Wedellsborg — the seven reframing practices)
+- Skills: ../product-discovery, ../idea-to-product, ../requirements-to-specs