agent-issues 0.0.119

package/skills/ai-implement/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ai-implement
+description: Delivers a change in thin, independently-verified vertical slices instead of one large pass, anchored to the active agent-issues issue. Use for broad refactors, config or infrastructure changes, multi-file migrations, or other work with no fast test seam.
+argument-hint: Issue ID to implement (or the briefing ai-prepare just reported)
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Incremental Implementation
+
+Build in thin vertical slices: implement one piece, verify it, then expand. Each increment leaves the system in a working, verified state. Never implement an entire issue in one uninterrupted pass.
+
+You write and verify every slice yourself, in this conversation. Never start a subagent to implement a slice, even to save time or context. The only subagent this skill starts is the read-only review in step 4, after the last slice's verification passes.
+
+If a slice turns out to have a natural test seam, write the test for that slice. Verification and tests can work together in this skill.
+
+When an issue removes a feature, constraint, or compatibility path, remove or update its obsolete tests. Do not add a new test whose only purpose is to confirm that deleted code or an obsolete restriction has not returned. That test has no current behavior contract and adds maintenance cost. Test a replacement or newly supported observable behavior when the change creates one. Add an absence test only when the active issue or a relevant ADR makes the absence an explicit, observable requirement.
+
+## Workflow
+
+### 1. Planning
+
+Run the **Entity Read** recipe, the **Relation Query** recipe, and the **Context Read** recipe for the active issue and its scope. Read every linked `planEntries` item returned by the issue; its current body can contain implementation decisions and constraints. If `ai-prepare` reported a briefing at the fork, use that instead. Confirm the public interface, the priority behaviors, and the approach. Resolve any hard-to-reverse question before you write code. Send it to `/ai-grill-with-docs` instead of deciding it yourself.
+
+Treat the issue's `planEntries` as planning inputs. Do not create or change Plan-entry links. Report missing Plan-entry provenance to the issue creator.
+
+Break the approach into vertical slices before you start:
+
+- **Vertical (preferred):** each slice is a complete path through the stack. The slice gives the user or caller new, working capability. Do not build one layer at a time across every slice, for example all models, then all endpoints, then all UI.
+- **Contract-first:** when two sides of a boundary must move in parallel, fix the shared type or interface first. Then implement each side against it independently.
+- **Risk-first:** sometimes one slice is genuinely uncertain, for example an external integration, a tricky migration, or a performance question. Do that slice first. A dead end then surfaces before you build on top of it.
+
+### 2. The increment cycle
+
+For each slice:
+
+1. **Implement** the smallest complete piece of the slice. Before you write it, ask what the simplest thing that could work is. After you write it, check that each abstraction earns its complexity. Do not add complexity for a problem this issue does not have. Three similar lines are better than one early abstraction.
+2. **Verify** with the narrowest check available. Run the slice's tests if a test seam exists. If not, run the repository's build, typecheck, and lint commands for the touched packages. Then run a manual check that the behavior matches what the slice promised.
+3. **Move to the next slice.** Carry the working state forward. Do not restart. Do not batch verification across slices.
+
+Touch only what the issue requires. If you notice unrelated cleanup worth doing, name it in your report instead of doing it:
+
+```
+NOTICED BUT NOT TOUCHING:
+- <file>: <what you noticed, and why it's out of this issue's scope>
+```
+
+### 3. Increment discipline
+
+- **One thing at a time.** Each increment changes one logical thing. Do not mix a feature addition with an unrelated refactor or config change in the same slice.
+- **Keep it compilable.** After every slice, the touched packages must build and their existing tests must still pass. Never leave the tree in a broken state between slices.
+- **Safe defaults.** New behavior defaults to off, or to the conservative choice, unless the issue asks for the opposite. Do not change existing behavior for every caller as a side effect of one slice.
+- **Rollback-friendly.** Prefer additive changes over edits to existing code, where the issue allows it. Additive changes are new files or new functions. Do not delete code and replace it in the same slice. Split the delete and the replacement into separate slices, so either half reverts on its own.
+
+### 4. Implementation review gate
+
+You, the visible `ai-implement` agent, own every increment, its verification, and any repairs. Do not hand the build to a subagent: you hold the context on what the active `ai-*` skills expect, and a subagent does not have it. Do not treat the first working slice as the end of the work.
+
+After the last slice's focused verification passes, start one read-only review subagent. This is the only step that runs as a subagent. Give the reviewer the active issue context, the changed-file diff, the verification you already ran, and the shared [language standard](../agent-issues-language.md). The reviewer's report, its findings, and every message it writes must follow that standard.
+
+The reviewer must cover both of these:
+
+- **Behavior and contract:** Compare the implementation against the active issue, the linked user stories, the relevant ADRs, and the observable public behavior. Find missing behaviors, wrong semantics, and gaps in behavior coverage.
+- **Code and regression risk:** Inspect the changed code for correctness defects, unplanned scope, regressions, gaps in error handling, maintainability concerns, and gaps in validation.
+
+The reviewer must not edit files. It must return either no findings, or structured findings with a severity, a file and location, evidence, and a concrete fix.
+
+`ai-implement` rejects a finding only when it can explain why the finding is invalid or out of scope. For every valid, material finding, fix it yourself. Then re-run the verification that covers the fix. Do not hand repairs to a subagent. If there are no material findings, `ai-implement` records the reviewer report before the final verification. Do not mark the issue done until this gate is complete.
+
+### 5. Complete and report
+
+After the review gate and the final verification pass, mark the active issue `done`. Start the `ai-next-work` skill with the active initiative. Include its result in the completion report. Do not start the selected issue.
+
+## Red flags
+
+Stop and reconsider the current slice if any of these show up:
+
+- More than roughly 100 lines written without running any verification.
+- Two or more unrelated changes landing in the same slice.
+- Scope creep, for example telling yourself "let me just quickly add this too."
+- Skipping verification to move faster.
+- The build or tests are broken between slices.
+- An abstraction built before a third use case actually demands it.
+- Editing files outside the issue's scope because you happened to be nearby.
+- Starting a subagent to implement or fix a slice instead of doing it yourself.
+
+## Checklist per slice
+
+```
+[ ] Slice is a complete, working vertical step, not a partial layer
+[ ] A test, build, typecheck, or manual check ran and passed
+[ ] New tests cover current or newly supported behavior, not only the absence of removed behavior
+[ ] Obsolete tests were removed or updated
+[ ] No unrelated changes riding along in this slice
+[ ] No speculative abstractions added ahead of a real second or third use case
+[ ] The tree builds and existing checks still pass after this slice
+```

package/skills/ai-migrate-docs/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ai-migrate-docs
+description: Migrates existing project documentation into tracked agent-issues records and relationships. Use when you import or backfill PRDs, ADRs, glossary docs, planning notes, or issue lists into agent-issues.
+disable-model-invocation: true
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Migrate Docs
+
+Existing markdown docs, tickets, and notes are source material. Interpret them. Do not treat them as the final source of truth.
+Use the [Context Summary](../recipes/context-summary.md), [Context Term](../recipes/context-term.md), [Initiative](../recipes/initiative.md), [PRD](../recipes/prd.md), [User Story](../recipes/user-story.md), [ADR](../recipes/adr.md), and [Issue](../recipes/issue.md) recipes when you create or edit those record bodies.
+
+## Process
+
+### 1. List the source material
+
+- Find the specific documents or notes the user wants to migrate.
+- Classify each source: glossary or context, initiative or roadmap, PRD or spec, ADR, or issue or task breakdown.
+
+### 2. Map source docs to tracked entities
+
+- Initiative or roadmap doc: create or reuse one `initiative`.
+- PRD or feature spec: create or reuse one `prd` under the initiative.
+- Numbered user commitments inside a PRD: create one `userStory` child for each committed story.
+- ADR or architecture decision doc: create or reuse one `adr` under the initiative.
+- Task list, checklist, or backlog doc: create one `issue` for each slice you can grab independently.
+- Glossary, terminology, or domain-language notes: migrate into initiative-scoped context records.
+
+If one document mixes more than one concern, split it into the smallest set of tracked records that keeps the original intent.
+
+### 3. Publish records in dependency order
+
+1. Create or reuse the parent initiative.
+2. Migrate glossary and context terms.
+3. Run the **Entity Create And Edit** recipe to create or reuse PRDs with their migrated markdown as direct body text. If you reuse an existing PRD, update its body.
+4. Run the **Entity Create And Edit** recipe to create the PRD's user stories with the PRD as parent. Keep the full committed story text in the body, even when the title is shorter. If you reuse a story, update its body.
+5. Run the **Entity Create And Edit** recipe to create or reuse ADRs with their decision text in the body. If you reuse an ADR, update its body.
+6. Run the **Entity Create And Edit** recipe to create issues with their migrated implementation text in the body. If you reuse an issue, update its body.
+7. Run the **Entity Relations** recipe to link issues to user stories with `fixes`.
+8. Run the **Entity Relations** recipe to link ADR constraints with `constrains` when a decision clearly governs implementation work.
+9. Run the **Entity Relations** recipe to link issue dependencies with `blocks`.
+
+Publish blockers before you publish blocked issues, so every relation points to a real record.
+
+When you migrate markdown docs, store the source text in the record body. Do not compress it into a title. Drop only the duplicate top-level heading when the record title already covers it. The **Entity Create And Edit** recipe uses direct MCP body input or its exact CLI standard-input fallback, so multiline markdown lands exactly as written.
+
+### 4. Handle gaps and unclear cases carefully
+
+- Do not create placeholder records for claims the source docs do not support.
+- When the source material is old or contradictory, migrate only the parts you can defend. State the unresolved parts clearly.
+- If a source task list is too coarse, break it into thin vertical slices before you create issues.
+- If a doc appears to describe an existing record under a different title, reuse the existing record and report the mapping instead of creating a duplicate.
+
+### 5. Return a migration report
+
+Return a short report that includes:
+
+- Each source document you processed.
+- Every initiative, PRD, user story, ADR, and issue ID you created or reused.
+- The links you added.
+- Any source material you skipped, merged, or left unresolved.
+
+Do not treat the migration as complete until the local `agent-issues` graph matches the source material.

package/skills/ai-next-work/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ai-next-work
+description: Selects the next workable issue from a tracked scope and reports the reason to work on it next. Use after completing an issue or when choosing the next implementation slice.
+argument-hint: Initiative or issue ID
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Next Work
+
+Select work. Do not implement it or change the issue status.
+
+## Input
+
+Accept the active initiative, or an issue whose initiative you can resolve from its relations.
+
+## Selection
+
+1. Run the **Next Work** recipe with the supplied initiative or descendant. This one operation resolves a PRD, user story, or issue to its owning initiative and returns the complete work order.
+2. A candidate is **workable** when it appears in `available`. The command excludes issues with an open `blocks` source and parent issues with unfinished decomposed children.
+3. Use `unblocks` to prefer work that releases the most unfinished issues. A child issue lists its decomposed parent in `unblocks`, so the command makes the path to an unfinished parent explicit.
+4. Prefer the thinnest tracer-bullet slice among the available issues with the largest unblock count. Run the **Entity Read** recipe only for finalists whose authored outcome or acceptance criteria you need to compare.
+5. Run the **Initiative Read** recipe only when the work order lacks the records needed for a planned initiative-wide decision.
+
+Use the refreshed graph each time. Do not rely on state you captured before the previous issue finished.
+
+## Result
+
+Return the selected issue's:
+
+- Reference and title.
+- parent or leaf classification
+- user stories it `fixes`
+- open blockers
+- short reason for the selection
+
+If no issue is workable, return one of:
+
+- **Complete:** every issue in the initiative is `done`, no matter what the initiative's manual status says.
+- **Blocked:** unfinished issues remain. Report the blocker chain.
+
+Do not set the selected issue to `in-progress`. The caller decides whether to start it.

package/skills/ai-plan/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ai-plan
+description: Ask the user detailed questions about a plan, decision, or idea. Use when the user wants to test a plan or uses a plan trigger phrase.
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+Use the `ai-domain-modeling` skill for this interview.
+
+## Persist Plan State
+
+At the start of a new planning effort, run the **Entity Read** recipe for the active initiative. Run the **Entity Create And Edit** recipe to create one initiative-owned Plan with a stable Goal and Context body. If the user gives an explicit Plan reference, resume that Plan instead. Do not infer a Plan to resume or create a duplicate Plan.
+
+Use the **Plan Entry Write** recipe to record planning state as it changes:
+
+- Record each design question as a `question` entry before asking it.
+- Record each durable user answer before continuing to the next round. When an answer resolves a design question, add a `decision` entry that supersedes the question reference.
+- Record each durable fact from code or tool output before it affects later planning. Use the approved role that describes the fact.
+- Replace a changed entry by superseding it. A decision targets a question or decision. Edit only corrections.
+- Add no entry for transient conversation that does not change planning state.
+
+Run the **Entity State And Structure** recipe to set the Plan to `ready` only after the planning frontier is empty and the user confirms shared understanding. A ready Plan can retain only explicit implementation-discovery questions.
+
+Ask questions until you and the user have the same understanding. Make a **design tree**. Each decision has related decisions below it.
+
+Work on the tree in **rounds**. The **frontier** contains all decisions with settled prerequisites. These are the questions that you can ask now. Do not assume an answer that the user has not given. Ask all frontier questions in one round. Number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Each question should be formatted like so:
+
+```
+❓ **Q1** - **<question title>**: <question body. It can have more than one paragraph or choice.>
+
+➡️ <your recommended answer>
+```
+
+After each user response, update the tree. A settled decision can make more questions ready. Calculate the frontier again, then ask the next round. Put a question in a later round if its answer needs an answer from an open question in the current round.
+
+Find _facts_ yourself. Do not ask the user for facts that you can find in the environment, such as files or tool output. When a frontier question needs a fact, send a sub-agent to find it. Do not wait for the sub-agent. Treat the fact search as an unsettled prerequisite. Wait for its result before you ask questions that need that fact. Ask other frontier questions now. The user makes the _decisions_. Ask the user for each decision and wait for an answer.
+
+End the session when the frontier is empty. At this point, you have checked each branch of the design tree. Do not leave any assumption unstated. Do not act until the user confirms that you and the user have the same understanding.

package/skills/ai-prepare/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: ai-prepare
+description: Given whatever the user provides — an ID, a topic, a description, a rough pointer — find all the surrounding tracker context and codebase context relevant to it, then stop for a conversation fork. Widens a single issue, story, or ADR out to its whole owning initiative instead of reporting on just that one entity. Does not narrow to one issue, change any status, or name what to do next. Use at the start of a work session to gather what forked conversations need without growing the session that will run them.
+argument-hint: An ID, a topic, or a description of what to look into
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Prepare
+
+One job: given whatever information the user hands you, build a durable orientation to the relevant initiative, so that any conversation forked from here has what it needs without redoing the discovery. This is an initiative briefing, not a snapshot of one issue.
+
+When the input names or resolves to a single issue, user story, or ADR, do not stop at that one entity. Widen out to its whole owning initiative, because any conversation forked from here may end up working on a different issue inside the same initiative. The briefing is initiative-wide, not entity-wide.
+
+Do not narrow the input down to a single issue to work on. Do not decide what gets built. Do not write production code, run tests, change any status, or start a build skill in this skill.
+
+## Process
+
+### 1. Take the input as given
+
+Accept anything: an issue, user story, ADR, initiative, or handoff ID; a topic; a plain description; a fragment of a conversation. Do not force it into a single tracked entity first. If it names or describes one or more entities, run the **Entity Read** recipe to resolve them. If it is a handoff, run the **Handoff Read** recipe. If it is a description with no obvious ID, run the **Context Read** recipe with search input and the **Entity List** recipe. It is normal for this to surface zero, one, or many entities — report what exists, do not force a pick.
+
+### 2. Widen each entity to its owning initiative
+
+The briefing must cover the whole initiative an entity belongs to, not just that one entity. A conversation forked from here may end up working on any issue inside the initiative, not only the one the user named.
+
+For every resolved entity that is not itself an initiative, project, or epic:
+
+- Run the **Relation Query** recipe for incoming structural relation types: `tracks`, `decomposes`, `creates`, `owns`, or `records`. The source of the returned edge is the structural parent.
+- Repeat on that parent until you reach an entity of kind `initiative`. An issue tracked directly by an initiative takes one hop; a decomposed sub-issue or a user story reached through a PRD can take two or three.
+- Treat that initiative, not the original entity, as the scope for the rest of this skill. Keep a note of which entity started the search, so the briefing can say, for example, "started from ISS53, part of INIT7."
+
+If an entity has no owning initiative (a standalone ADR, project, or epic), keep it as its own scope instead.
+
+### 3. Load the whole initiative
+
+For every initiative in scope:
+
+- Run the **Initiative Read** recipe once. It returns the initiative plus every reachable PRD, user story, ADR, and issue, including deeply decomposed sub-issues, together with `fixLinks`, `subIssueLinks`, `blockerLinks`, and `constrainsLinks`. This is the ground truth for initiative scope. Do not rebuild it from separate entity and relation reads.
+- Run the **Context Read** recipe for the matching initiative or project scope.
+- Read open blockers directly from `blockerLinks`: a `source` whose status is not `done` means its `target` is still blocked. Do not query relations per issue for this.
+
+Stay within the owning initiative. Follow a linked handoff only when it is the input or when it contains information that changes the initiative-level briefing. Do not expand into related initiatives or other linked records just because they are reachable.
+
+### 4. Explore the codebase
+
+Explore the codebase only when it is needed to explain the initiative's purpose, boundaries, or a shared contract. Report broad areas and owning abstractions, not a list of issue seams or likely files that will become stale after the next issue is done. Surface a hard-to-reverse design question only when it is still unresolved in the tracker and it blocks safe implementation; send it to `/ai-grill-with-docs` instead of deciding it yourself.
+
+### 5. Report everything found
+
+Return a compact, self-contained briefing so a fresh conversation does not need to redo discovery:
+
+- The initiative's purpose, durable scope, and important boundaries.
+- The purpose of the current open work, grouped by durable work area. Do not enumerate every issue or preserve exact issue counts and statuses unless they explain a blocker or a dependency that matters to the forked conversation.
+- Only the relations that affect those work areas: open blockers, parent boundaries, user-story outcomes, and ADR constraints.
+- The glossary terms and decisions that apply.
+- Broad codebase areas and owning abstractions, only where they clarify the initiative's boundaries.
+- Only open questions that are both unresolved in the tracker and blocking safe implementation. Do not repeat questions already answered by grilling, the PRD, an ADR, or another tracked decision. If none remain, say that there are no blocking open questions.
+
+If the input named one entity inside the initiative, say so, but do not shrink the briefing back down to just that entity.
+
+Do not recommend a single issue to build next, and do not set any status. Selecting the next issue is the `ai-next-work` skill's job, not this one.
+
+### 6. Stop for the fork
+
+End your response with this instruction, and do not continue past it:
+
+> Fork this conversation now. Pick up the next step in the new conversation with whatever this briefing points to.
+
+Do not start a build skill yourself, even if asked to continue in the same reply. The fork is what keeps the next step's context small.
+
+### 7. Handle replies that stay in this conversation
+
+The user may answer an open question from the briefing right here instead of forking first. An answer is not an order to keep going.
+
+- Treat the answer as new input for the briefing, not as authorization to build. Fold it in, restate the affected part of the briefing, and end with the same fork instruction from step 6 again.
+- Only start a build skill, write code, run tests, or change status if the user's reply is an explicit instruction to do so (for example, "go ahead and implement it" or "start ai-implement"). A reply that only answers a question, states a preference, or resolves ambiguity is not that instruction.
+- If it is unclear whether the reply is an answer or an instruction to proceed, ask which one it is instead of guessing.

package/skills/ai-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" — 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 — 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 happy path, a tricky edge case, an attempt at something that should be illegal — the ones hard to reason about on paper.
+
+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/skills/ai-prototype/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: ai-prototype
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+Before you create a prototype, run the **Entity Read** recipe, the **Relation Query** recipe, and the **Context Read** recipe for the active issue and scope. If no issue owns the question, run the **Entity Create And Edit** recipe to create one under the active initiative. Keep the prototype, its question, and its result attached to that issue.
+
+## Pick a branch
+
+Identify which question is being answered — from 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 — 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.** Do not fold the prototype into production code in this skill. Commit the prototype to a throwaway branch outside `main`, then run the **Entity Create And Edit** recipe to add its branch or commit reference, its question, run command, and verdict to the active issue body according to the [Issue recipe](../recipes/issue.md). When it resolves a decision ticket, use the **Entity Create And Edit** recipe and the **Entity State And Structure** recipe to update that ticket's `## Resolution` and set it to `done`. Run the **Context Write** recipe only when the prototype resolves glossary language, not to record the prototype. The main branch keeps only a later, validated implementation.

package/skills/ai-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 — 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) — that'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 — 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 — `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"** — that's 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 — 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/skills/ai-recipe-migration/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ai-recipe-migration
+description: Restructure approved tracker record bodies to use their applicable record body recipes.
+disable-model-invocation: true
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Recipe Migration
+
+Recipe migration is a user-invoked process that restructures existing authored bodies to use their applicable [record body recipes](../recipes/README.md). It preserves the source meaning, keeps typed facts and graph relations outside body prose, and writes through normal tracker revisions.
+
+## Scope
+
+Start from an entity, initiative, shared context, or full project. Preview one selected scope at a time:
+
+- **Entity:** Run the **Entity Read** recipe.
+- **Initiative:** Run the **Initiative Read** recipe and the **Context Read** recipe.
+- **Shared context:** Run the **Context Read** recipe for the shared context.
+- **Full project:** Run the **Entity List** recipe for each supported entity kind, then run the **Context Read** recipe with directory input.
+
+Include authored entity bodies, context summaries, and context terms in the selected scope. Do not migrate generated bodies, empty bodies, or issue comments. Comment migration remains reserved until comment records exist.
+
+## Preview
+
+1. Read the applicable recipe for every selected record.
+2. Produce a per-record migration preview before any write. Include the complete tracker reference, record kind, observed revision, and the proposed body.
+3. Preserve clear source content. Put content that cannot be assigned safely in `## Notes` when that recipe has a Notes section.
+4. Do not add status, parentage, timestamps, revisions, references, or graph relations to body prose. Do not use the generated-content marker as an authored placeholder.
+5. Show unchanged records and per-record exclusions with the proposed changes. Let the user exclude any record.
+
+For a full-project recipe migration, preview all supported authored entity bodies and all context summaries and term definitions in the current project. Do not write while the preview is under review.
+
+## Approval And Write
+
+1. Ask for explicit approval of the remaining preview. Approval may cover the selected scope after per-record exclusions.
+2. Before each write, run the **Entity Read** recipe or the **Context Read** recipe to reload the record and compare its revision and body with the preview. The migration skips it when the body changed after preview. Do not retry or overwrite a stale record.
+3. Run the **Entity Create And Edit** recipe to update an approved entity with direct body text.
+4. Run the **Context Write** recipe to update an approved context summary with direct title and body text.
+5. Run the **Context Write** recipe to update an approved context term with direct definition and `avoid` text.
+
+Use existing tracker operations only. Do not add a recipe operation group or conditional-write options.
+
+## Report
+
+Report updated, unchanged, excluded, and stale records separately. For every item, include its complete tracker reference. For updated records, report the prior and resulting revisions. Run the **Revision Read** recipe before the **Entity Restore** recipe or the **Context Restore** recipe. The context restore recipe explicitly identifies its CLI-only fallback.
+
+End after the report. A stale record needs a new preview before it can be considered again.