@use-the-fork/spindle 0.0.0-stage → 0.0.2

package/build/Assets/Blueprints/skills/int-domain-modeling/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: int-domain-modeling
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.0.1
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the _active_ discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely _reading_ `GLOSSARY.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── GLOSSARY.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `GLOSSARY-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── GLOSSARY-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── GLOSSARY.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── GLOSSARY.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `GLOSSARY.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `GLOSSARY.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update GLOSSARY.md inline
+
+When a term is resolved, update `GLOSSARY.md` right there. Don't batch these up: capture them as they happen. Use the format in [GLOSSARY-FORMAT.md](./references/GLOSSARY-FORMAT.md).
+
+`GLOSSARY.md` should be totally devoid of implementation details. Do not treat `GLOSSARY.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./references/ADR-FORMAT.md).

package/build/Assets/Blueprints/skills/int-domain-modeling/references/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording _that_ a decision was made and _why_, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/build/Assets/Blueprints/skills/int-domain-modeling/references/GLOSSARY-FORMAT.md

@@ -0,0 +1,60 @@
+# GLOSSARY.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `GLOSSARY.md` at the repo root.
+
+**Multiple contexts:** A `GLOSSARY-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Glossary Map
+
+## Contexts
+
+- [Ordering](./src/ordering/GLOSSARY.md): receives and tracks customer orders
+- [Billing](./src/billing/GLOSSARY.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/GLOSSARY.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `GLOSSARY-MAP.md` exists, read it to find contexts
+- If only a root `GLOSSARY.md` exists, single context
+- If neither exists, create a root `GLOSSARY.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/build/Assets/Blueprints/skills/int-prototype/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste, so make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that's answering the question) in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state, just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, _not_ whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code: buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks: nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different"; those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source, and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

package/build/Assets/Blueprints/skills/int-prototype/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: int-prototype
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered, using the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a single shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts, so getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious, but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **Trivial to run.** A UI prototype starts from one command in the project's task runner: `pnpm <name>`, `python <path>`, `bun <path>`, etc. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too (the verdict and the question it settled) in the issue or a commit. The main branch keeps only the validated decision.

package/build/Assets/Blueprints/skills/int-prototype/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like, this is the wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes: strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app**: real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A: adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay. Only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but _would naturally live inside one_ (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow), it's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B: a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside (e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible).
+
+Create a **throwaway route** following whatever routing convention the project already uses. Don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise, so cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different**: different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code, adapt to the project's framework
+const variant = searchParams.get("variant") ?? "A";
+return (
+  <>
+    {variant === "A" && <VariantA {...data} />}
+    {variant === "B" && <VariantB {...data} />}
+    {variant === "C" && <VariantC {...data} />}
+    <PrototypeSwitcher variants={["A", "B", "C"]} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow**: cycles to the previous variant (wraps around).
+- **Variant label**: shows the current variant key and, if the variant exports a name, that name too. e.g. `B (Sidebar layout)`.
+- **Right arrow**: cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router, e.g. `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds: gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"**, which is the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer (which variant and why), then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
+
+- **Sub-shape A**: fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B**: promote the winning variant to a real route; drop the throwaway route and the switcher from main.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin, since variant components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub: the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/build/Assets/Blueprints/skills/int-retrospective/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: int-retrospective
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.4.1
+---
+
+# Retrospective
+
+Capture evidence-backed improvements to the agent environment and domain model. The controller coordinates; a fresh, read-only reader assesses.
+
+## Mode selection
+
+Select the mode from the explicit purpose in the calling context, not from flags or unrelated conversational mentions.
+
+- `delivery`: a delivery caller invokes this after final verification, once for the full spec or for a standalone ticket, and supplies verified delivery evidence pointers. This mode records proposals and applies nothing, even when asked to apply them.
+- `maintainer`: the maintainer retrospective caller requests an assessment of the current or selected session and may supply a proposal-report pointer. With no session selection, use the current session. This mode obtains item-level approval before applying changes.
+
+If the calling context does not clearly establish exactly one mode, explain that the retrospective mode is unclear and ask for the purpose or caller context before starting the workflow. Delivery still requires its evidence pointers.
+
+## Workflow
+
+Before acting on each node, announce `Step <node ID> - <node label>`. Announce resumed steps and loop re-entries. After each decision, state its result and selected branch before entering the next node. Select the mode from the calling context before entering A.
+
+```mermaid
+flowchart TD
+    A[Select evidence] --> B[Assess or reuse]
+    A -- Blocked --> H[Report outcomes]
+    B -- Blocked --> H
+    B --> C[Present proposals]
+    C --> D{Entry?}
+    D -- delivery --> H
+    D -- maintainer --> E[Obtain approval]
+    E --> F{Approved items?}
+    F -- No --> H
+    F -- Yes --> G[Apply and verify]
+    G --> H
+```
+
+### A. Select evidence
+
+For delivery, list the spec or brief, every ticket and its `## Comments` log, starting and final revisions, and final review. For maintainer, locate primary sources for the selected session, including relevant local session logs. Start from a supplied report or the work's existing dated `retrospective.md` when available. Include applicable glossary, ADR and instruction pointers.
+
+**Complete when:** the selected entry and accessible sources are explicit, selecting B; unavailable required sources select H with a blocker. Session sources need not contain delivery artifacts; state genuine evidence gaps.
+
+### B. Assess or reuse
+
+Read the [assessment reference](./references/assessment.md). Reuse an existing report only after checking its cited evidence still covers the selected work and its proposals satisfy that reference's [report contract](./references/assessment.md#report-contract); reuse requires no dispatch. Otherwise fill every slot in the [assignment template](./assets/retrospective-prompt.md) for one fresh read-only subagent that did not participate in the assessed work. Supply the assessment reference's resolved absolute path as a required first read, plus evidence pointers validated against its entry-specific requirements. The reader returns the report; the controller owns persistence and approval.
+
+**Complete when:** an evidence-current, contract-compliant report is available, selecting C; required reader skills were confirmed for fresh assessment. Missing prerequisites select H with a blocker, not a completed assessment.
+
+### C. Present proposals
+
+Rank by impact and show stable IDs with their evidence and verification criteria. Delivery writes `.scratch/YYYY-MM-DD-<feature-slug>/retrospective.md` in the work's existing dated directory. Maintainer presents the report; reuse that destination when one exists, otherwise present in chat.
+
+**Complete when:** proposals (or "None") and assessment limitations are visible, selecting D; delivery's report exists and no environment or domain files have changed.
+
+### D. Entry?
+
+Evaluate the mode selected from the calling context.
+
+**Complete when:** `delivery` selects its branch to H; `maintainer` selects its branch to E. Delivery never enters approval or application.
+
+### E. Obtain approval
+
+Ask for approval by proposal ID, recording approved, declined and pending items. A blanket "just apply it" is a request to review: list proposals for item-level approval and wait in E. On the response, resume E. Resolve approved domain proposals with the maintainer through `int-domain-modeling`; unresolved decisions remain pending.
+
+**Complete when:** the item-level response is recorded and approved IDs, targets and any domain decisions are explicit, selecting F. An empty proposal list proceeds to F without an approval request.
+
+### F. Approved items?
+
+Check for individually approved items whose targets and required domain decisions are settled.
+
+**Complete when:** at least one actionable approved item selects Yes and G; none selects No and H. Unresolved items remain pending.
+
+### G. Apply and verify
+
+Change only approved targets. Load `int-writing-for-agents` for agent-facing writing, `int-writing-instruction` for workspace instructions, `int-writing-skills` for skills, and `int-testing-agent-guidance` for behavior-shaping guidance validation. Instruction briefs are not validated files. Use existing repository tooling for checks and test each proposal against its recorded criterion.
+
+**Complete when:** each actionable approved item has an applied change and passing evidence, or an explicit blocker/unverified result, selecting H.
+
+### H. Report outcomes
+
+Delivery hands the report path and pending proposals to the maintainer and stops without applying changes. Maintainer reports applied, declined and pending IDs, verification evidence and limitations; update an existing proposal report without overwriting its evidence. A blocked assessment reports missing prerequisites instead of claiming completion. Commit or publish only when requested.
+
+**Complete when:** the caller has the report or explicit blocker, proposal statuses and applicable verification results; stop.

package/build/Assets/Blueprints/skills/int-retrospective/assets/retrospective-prompt.md

@@ -0,0 +1,38 @@
+# Template
+
+```md
+## Assignment
+
+Assess the selected work for evidence-backed retrospective proposals.
+Entry: [ENTRY]
+
+## Required first read
+
+Read this assessment reference before assessing evidence:
+[ABSOLUTE_ASSESSMENT_REFERENCE_PATH]
+
+If it is unavailable, return a blocker rather than a completed assessment.
+
+## Evidence inputs
+
+Selected session's primary sources, plus any existing report:
+[SESSION_SOURCE_POINTERS_OR_NOT_APPLICABLE]
+
+Spec or brief: [SPEC_OR_BRIEF_POINTER]
+Every ticket file, including its Comments log: [TICKET_LOG_POINTERS]
+Integration range: [BASE_SHA]..[HEAD_SHA]
+Final review report: [FINAL_REVIEW_REPORT_POINTER]
+Glossary map or applicable glossary: [GLOSSARY_POINTERS_OR_ABSENT]
+Applicable context and system-wide ADR directories: [ADR_DIRECTORIES_OR_ABSENT]
+Existing applicable workspace instructions: [INSTRUCTION_POINTERS_OR_ABSENT]
+
+## Permissions
+
+Read-only, proposals-only. Return the report to the controller; do not write
+project files, apply proposals, or dispatch agents.
+
+## Hand-back
+
+Return the report required by the assessment reference, or an explicit blocker
+with missing prerequisites. The controller handles persistence and approval.
+```

package/build/Assets/Blueprints/skills/int-retrospective/references/assessment.md

@@ -0,0 +1,56 @@
+# Retrospective assessment
+
+## Reader scope and required skills
+
+Read this reference before assessing evidence. If it is unavailable, return a blocker rather than a completed assessment. Assess primary sources independently; this assignment is read-only and proposals-only. Return the report to the controller, which owns persistence and approval. Do not edit project files, apply proposals or dispatch agents.
+
+Before assessing evidence, use the Skill tool to load `int-domain-modeling` and read its instructions. This is required even when the session went smoothly or no domain findings are expected; the assignment cannot waive it. If loading fails or the skill is unavailable, report the blocker rather than claiming a completed assessment.
+
+Apply its terminology challenges, context boundaries, implementation-free glossary guidance, and three-test ADR criteria to the analysis. Express glossary updates and ADRs as drafts in the report. Put unresolved terminology or model decisions in Open questions for the maintainer instead of resolving them on their behalf. Do not run the skill's inline-update actions.
+
+When evidence suggests missing, misleading, duplicate or overly broad workspace instructions, load `int-writing-instruction` before assessing that candidate. Use its scope, file-organization and discovery guidance to prepare a proposal brief only, without executing its authoring and validation workflow. If the skill cannot be loaded, report the affected assessment as blocked. If no instruction candidate is supported, say "None".
+
+## Evidence requirements
+
+Entry is `delivery` or `maintainer`. Delivery requires the spec/brief, every ticket and its Comments log, starting and final revisions, and final review; session sources may say "Not applicable". Maintainer requires selected-session primary sources, including relevant local session logs; delivery-only inputs may say "Not applicable" when that session has no such artifacts. An existing report supplements rather than replaces primary-source pointers.
+
+Include applicable glossary, context and system-wide ADR directories, and workspace instructions, or explicitly state "Absent". Absence is context, not permission to create files. Report missing required inputs as blockers and other evidence gaps explicitly; never invent sources. Read the primary sources yourself and judge from them.
+
+## Assessment categories
+
+The reader uses these prompts for both entry paths. They are candidate categories, not a quota: retain only evidence-backed improvements, and report "None" when appropriate.
+
+Look for **friction**: recurring findings, blockers and their duration, rework, missing information, expensive detours, and terms that disagree with the glossary.
+
+- **Navigation:** repeated searches, hidden dependencies or expensive discovery. Prefer a scoped navigation pointer to existing documentation over copying it into always-loaded instructions.
+- **Workspace instructions:** durable guidance gaps, misleading rules, duplication or overly broad scope. Consult `int-writing-instruction` for scoped proposal briefs and check existing guidance for overlap.
+- **Automated checks:** mistakes a deterministic check could catch, or missing enforcement. Inspect repository lint/typecheck/test commands, hooks and CI first. Repair existing unwired or broken checks before reinventing them. Establish absence of a guardrail from those sources, not from a session that omitted a command.
+- **Coding standards:** judgement calls requiring context, such as cross-file consistency. Route mechanical patterns (imports, banned calls, file locations) to deterministic checks instead. Place guidance where the actor making the decision needs it; reviewers may also need exploration.
+- **Steering scope:** oversized workspace or global steering files. Propose moving reference material behind pointers and judgement rules to their appropriate owner. Global changes require explicit approval of that target.
+- **Tool economy:** expensive calls, oversized results or repeated lookups with measurable cheaper alternatives.
+- **No-ops:** steering text suspected of leaving behavior unchanged. Propose a baseline comparison before removal; document size alone does not prove a no-op.
+- **Information access:** missing logs or other sources that blocked decisions. Propose scoped access appropriate to the evidence.
+
+Keep each correction authoritative in one place. Reuse existing documentation and tooling; put reusable capabilities in skills, scoped project conventions in instructions, and one-off fixes in the task.
+
+Domain assessment follows `int-domain-modeling`: terminology drift on integrated work belongs in domain proposals, not triage.
+
+## Report contract
+
+Every proposal has a stable ID, impact/severity, **evidence** (session source location, ticket/comment, review finding or revision), **observed problem**, **durable correction**, **target**, and a checkable **verification criterion**. Rank proposals by impact. Shared fields apply to environment, domain and instruction proposals; cross-reference IDs rather than duplicate a proposal across sections. Verification criteria describe follow-up checks, not validation already performed.
+
+1. **Summary:** entry and assessed work; confirm `int-domain-modeling` was loaded and whether `int-writing-instruction` was consulted (or no instruction candidates were supported); available delivery outcomes, review rounds, blockers with duration, final verdict and evidence gaps. Mark unavailable session metrics explicitly.
+2. **Environment findings:** shared proposal fields and an assessment category.
+3. **Domain findings**, per `int-domain-modeling`:
+   - **Glossary drift:** the term used, the glossary's term, the context glossary path, and a proposed entry in the [glossary format](../../int-domain-modeling/GLOSSARY-FORMAT.md), free of implementation detail.
+   - **Undefined terms:** a proposed definition, or a rename to an existing term.
+   - **ADR candidates:** only decisions meeting all three tests (hard to reverse, surprising without context, the result of a real trade-off), with evidence for each test and a draft in the [ADR format](../../int-domain-modeling/ADR-FORMAT.md).
+4. **Instruction suggestions:** evidence-backed briefs for `.github/instructions/**/*.instructions.md`, not full files. In addition to shared fields, include:
+   - Operation (add, amend, consolidate or remove), proposed topic-specific target path, and why that file is the right owner; prefer amending existing guidance over a duplicate.
+   - Intended source scope: a narrow proposed `applyTo` glob and/or task-discovery `description`, with rationale. Use `**` only when the evidence supports genuinely workspace-wide guidance.
+   - A short proposed actionable rule or change, expected behavioral benefit, and applicable existing instruction paths checked for overlap or conflict. Resolve conflicts in the proposal rather than relying on instruction precedence.
+   - Why guidance is appropriate instead of a deterministic check, a cheap repository lookup, or a one-off task fix. Route mechanically enforceable rules to Automated checks instead; reference the corresponding environment finding without duplicating it here.
+   - A representative follow-up task for the shared verification criterion. Do not claim discovery or adherence was tested during this read-only retrospective.
+5. **Open questions** for the maintainer, including unresolved scope/ownership decisions.
+
+Write "None" for an empty section. Every finding cites evidence; omit any finding you cannot evidence.