feat(skills): adapt planning skills to artifact workflow

skills/prototype/SKILL.md

@@ -5,43 +5,70 @@ description: Build a throwaway prototype to answer a design question. Use when t
 
 # Prototype
 
-A prototype is **throwaway code that answers a question**.
-The question decides the shape.
+A prototype is **throwaway code that answers one question**.
+The question decides the branch.
 
-## Pick a branch
+## 1. 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:
+Identify the question from the user's prompt and surrounding code.
+Ask when it remains genuinely ambiguous and the user is reachable.
 
-- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md).
-  Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
-- **"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.
+- **Does this logic or state model feel right?**
+  Follow [`LOGIC.md`](LOGIC.md) to build a tiny interactive terminal app that pushes the model through hard-to-reason-about cases.
+- **What should this look like?**
+  Follow [`UI.md`](UI.md) to build several radically different UI variants on one route with a URL-controlled switcher.
 
-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.
+When the user is unavailable, default to Logic for a backend module and UI for a page or component, then state the assumption in the prototype.
 
-## Rules that apply to both
+Done when exactly one branch and one design question govern the prototype.
 
-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. **One command to run.**
-   Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc.
-   The user must be able to start it without thinking.
-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.**
-   When the caller permits implementation, fold any validated decision into the real code.
-   A planning-only caller such as Wayfinder stops at the verdict.
-   Commit the prototype itself to a throwaway branch, out of main, as a **primary source**.
-   Write a Prototype artifact under `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>/`, where `<project>` is the lowercase basename of the current working directory, following the vault's `AGENTS.md`.
-   Include the question, a context pointer to the branch, run instructions, and the verdict, plus screenshots and useful code snippets where they help preserve the result.
-   The main branch keeps only a validated decision that the caller permitted the skill to fold in.
+## Common rules
+
+- **Throwaway from day one.**
+  Locate the code close to where it would be used, but name it so nobody mistakes it for production.
+  Follow the project's routing and source-layout conventions rather than inventing a new top-level structure.
+- **One command to run.**
+  Use the project's existing task runner so the user does not need to remember a path or setup sequence.
+- **No persistence by default.**
+  Keep state in memory unless persistence is the question being tested.
+  Use an unmistakably disposable database or local file when that question requires one.
+- **Skip polish.**
+  Add no tests, production-grade error handling, speculative abstractions, or unrelated cleanup.
+- **Surface state.**
+  Show the full relevant state after every Logic action or UI variant switch.
+
+## 2. Build and reach a verdict
+
+Follow the selected branch through its handover step and iterate on the prototype in response to the user's feedback.
+Do not treat a runnable prototype as the result.
+The result is the verdict that answers the design question.
+
+Done when the user has reached an explicit verdict or stated that the prototype did not resolve the question.
+
+## 3. Capture the primary source
+
+Commit the complete prototype to a throwaway branch outside main.
+The branch is the primary source.
+
+Resolve the AI artifacts vault through `$(xdg-user-dir DOCUMENTS)/ai-artifacts` and read its `AGENTS.md` before writing.
+Use the lowercase basename of the current working directory as the project.
+
+When the caller provides an allocated filename and `parent`, use them exactly and do not advance `.counter`.
+Create only the Prototype artifact and leave the parent artifact unchanged.
+Otherwise, allocate the next vault-sequence identifier and name the artifact `<NNN>-<project>-<subject-slug>-prototype.md`.
+Include `parent` only when an earlier artifact directly caused the prototype.
+
+The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence:
+
+- UI evidence uses screenshots.
+- Logic evidence uses useful code snippets and, where needed, a short interaction transcript.
+
+Done when the complete prototype is committed outside main and exactly one Prototype artifact preserves the result according to the vault convention.
+
+## 4. Fold in the decision when permitted
+
+A planning-only caller such as Wayfinder stops after the verdict and leaves production code unchanged.
+Otherwise, fold the validated decision into production only when the caller permits implementation.
+Follow the selected branch's **Production mapping** and keep all other throwaway code out of main.
+
+Done when production is unchanged for a planning-only run, or contains only the permitted validated decision for an implementation run.