constellai 0.3.0

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

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