pi-feature-dev 1.13.0 → 1.14.0

package/README.md

@@ -42,10 +42,15 @@ into concrete work without losing the creator's taste, feeling, or human focus.
 It applies to creative technical and everyday work, while staying out of
 factual, mechanical, exact, or fully specified tasks.
 
+The `prototype` skill builds disposable logic or UI experiments that answer one
+design question before production implementation. It follows the current
+project and adapts its handoff, preview, task, and source-control steps to the
+capabilities of the current agent environment.
+
 The `visual-recap` skill turns a plan or completed non-trivial change into an
 evidence-backed visual review aid. It helps a reviewer see the outcome, affected
 system parts, risk, and the best place to inspect first. It adapts to the current
-host agent and always keeps a portable inline fallback.
+host agent, uses Mermaid for portable diagrams, and keeps an inline fallback.
 
 ## Install
 
@@ -89,6 +94,7 @@ from:
 - [umputun/cc-thingz](https://github.com/umputun/cc-thingz)
 - [anthropics/claude-code feature-dev plugin](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev)
 - [mattpocock/skills batch-grill-me and domain-modeling skills](https://github.com/mattpocock/skills)
+- [mattpocock/skills prototype](https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype)
 - [danyuchn/asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill)
 - [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish/tree/main/skills/simple-english)
 - [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd)
@@ -121,6 +127,12 @@ Create a visual review aid for a plan or completed change:
 /skill:visual-recap Show the architecture impact of the current change.
 ```
 
+Build a disposable prototype to answer one design question:
+
+```text
+/skill:prototype Compare three structurally different settings-page layouts.
+```
+
 The files under `skills/*/SKILL.md` are portable Markdown and can be adapted for
 other agent environments.
 
@@ -225,6 +237,11 @@ pi-feature-dev/
     ├── plan-review/
     │   ├── agents/openai.yaml
     │   └── SKILL.md
+    ├── prototype/
+    │   ├── agents/openai.yaml
+    │   ├── LOGIC.md
+    │   ├── UI.md
+    │   └── SKILL.md
     ├── ste/
     │   ├── agents/openai.yaml
     │   ├── references/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-feature-dev",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Portable coding-agent workflows packaged as skills.",
   "license": "MIT",
   "type": "module",

package/skills/prototype/LOGIC.md

@@ -0,0 +1,73 @@
+# 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 the file has nothing to install, a designer, product manager, or domain expert can drive it directly. Use domain language, not implementation language.
+
+## 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, identify the state model, the question, and the evidence that will answer it. Put this information in a visible introduction, not only in a comment. A returning user must be able to understand the experiment without the earlier conversation.
+
+### 2. Isolate the logic in a portable module
+
+Put the logic that answers the question in one `<script>` block. Keep it in a small, pure module. The page is disposable. Treat the module as evidence for a later production implementation, not as production-ready code.
+
+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 the shape that fits the question. Do not pick a shape only because it is easy to connect to the page. Keep the logic independent of the DOM: the page calls the logic, and the logic never calls the page. Reimplement or harden validated logic under the production project's normal standards.
+
+### 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 (labeled 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 color. No animations, no gimmicks — nothing that competes with the state and the buttons.
+
+### 4. Verify the prototype
+
+Open the file when the current environment supports local previews. Otherwise, provide its exact path and tell the user to open it in a browser.
+
+Run the happy path, one difficult edge case, and one illegal or rejected action. Confirm that each action updates the visible state. Confirm that reopening the file resets the state.
+
+### 5. Hand it over
+
+Give the user the file and name the walkthroughs. Invite feedback about impossible states, surprising transitions, and missing actions. Add a scenario only when it helps answer the original question.
+
+### 6. Capture the answer and the prototype
+
+When the prototype answers its question, record the verdict and evidence as [SKILL.md](SKILL.md) describes. Use the validated reducer, machine, or function set as input to the production implementation. Do not promote the HTML shell directly.
+
+## Anti-patterns
+
+- **Don't add a production test suite to the disposable shell.** Validate it by running the scenarios that answer the question.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalize.** 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 optimized for manual exploration. Carry the validated decision into production code and tests.

package/skills/prototype/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: prototype
+description: Build disposable code to answer one product or engineering design question. Use when the user wants to validate logic, state transitions, a data model, or API behavior, or compare structurally different UI directions before production implementation. Adapt to the current repository and agent environment. Do not require a specific model, coding agent, tool, browser, task runner, version-control host, or issue tracker.
+---
+
+# Prototype
+
+A prototype is **disposable code that answers one question**. The question determines the artifact.
+
+## Pick a branch
+
+Identify the question from the user's request and the surrounding code. Then read the matching branch before writing code:
+
+- **"Does this logic or state model feel right?"** → [LOGIC.md](LOGIC.md). Build one shareable HTML file. Let a non-developer drive difficult cases with free-play actions and guided walkthroughs.
+- **"What should this look like?"** → [UI.md](UI.md). Build several structurally different UI variants on one route. Make them switchable through a URL search parameter and a floating control.
+
+The branches produce different artifacts. If the choice is genuinely ambiguous, ask one focused question. If interaction is unavailable, infer from the surrounding code: use Logic for a backend module and UI for a page or component. State the assumption in the prototype.
+
+## Define success before coding
+
+State these points before you edit files:
+
+- the single question;
+- the evidence that will answer it;
+- the shortest way to run or open the artifact;
+- the production boundary that the prototype must not cross.
+
+Stop expanding the prototype when it can answer the question. Do not turn it into an alternative implementation project.
+
+## Adapt to the current environment
+
+- Follow project instructions, file layout, routing, framework, and styling conventions.
+- Use only capabilities that the current agent environment provides.
+- Open or render the prototype when a browser or preview tool is available. Otherwise, provide the exact file path, command, or route.
+- Use the project's normal planning and progress mechanism when one exists. Otherwise, keep a short checklist in the conversation.
+- Do not require Git, a hosted repository, an issue tracker, or an external service. Use them only when the current workflow already authorizes them.
+
+## Rules that apply to both
+
+1. **Mark it as disposable.** Put the prototype near the module or page it explores. Use `prototype` in the file, route, or directory name. Follow existing routing conventions.
+2. **Make it easy to run.** Prefer one existing project command for a UI prototype. Make a logic prototype a self-contained HTML file when possible.
+3. **Keep state in memory by default.** If the question requires persistence, use an isolated scratch store. Mark it clearly as disposable. Never use production data.
+4. **Skip production polish.** Add only the error handling needed to keep the prototype runnable. Do not add speculative abstractions or production tests for the disposable shell.
+5. **Expose relevant state.** After each logic action or UI variant switch, render the state that helps answer the question.
+6. **Protect production behavior.** Keep real mutations and production data outside the experiment. If the prototype uses an existing route, gate all prototype rendering so production ignores it.
+7. **Hand over an exact entry point.** Give the user the file path, command, route, and variant keys or scenarios. Open the artifact when the environment supports it.
+8. **Record the answer.** Record the question, verdict, and evidence in the current workflow. Preserve the prototype on a temporary branch or other archive only when requested or already authorized. Keep the main branch focused on the validated production decision.

package/skills/prototype/UI.md

@@ -0,0 +1,114 @@
+# UI Prototype
+
+Generate **several structurally different UI variants** on one route. Let the user switch variants with a floating bottom control. The user can choose one direction or combine specific parts, then discard the experiment.
+
+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.
+
+## Choose the host shape
+
+A UI prototype is easier to judge beside the real application shell, data shape, and information density. Prefer an existing host page. Create a new route only when no suitable page exists.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Render variants **on the same route** behind a `?variant=` URL search parameter. Keep existing parameters and authorization. Use approved non-production data or representative fixtures. Change only the rendered subtree.
+
+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 **disposable route** with the project's routing convention. Do not invent a new top-level structure. Include `prototype` in the path or file name. Use the 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 the question and plan in one line near the prototype or in a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+Also state what difference the user should compare between the variants.
+
+### 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 colors. 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 approved non-production data fetching above the switcher. Change only the rendered subtree.
+
+For sub-shape B (new page): the disposable route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-center 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).
+
+Behavior:
+
+- 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.
+- Disable the complete prototype path in production. Use the project's existing development or feature guard. The production route must ignore the variant parameter.
+
+Keep the switcher close to the prototype. Reuse an existing prototype control when one exists. Do not add a shared abstraction for one experiment.
+
+### 5. Verify and hand it over
+
+Run the project's focused build, type check, or route check when one is available. Open every variant when preview tools are available. Confirm that the URL preserves the selection and that keyboard controls do not intercept text input.
+
+Give the user the command, route, and `?variant=` keys. If the current environment cannot open the UI, say so and provide the exact manual steps.
+
+### 6. Capture the answer and clean up
+
+When a variant wins, record which parts won and why. Then follow the capture rules in [SKILL.md](SKILL.md). Implement the decision under normal production standards. Remove the prototype from the main branch when the current workflow authorizes cleanup:
+
+- **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 disposable route and the switcher from main.
+
+If the current workflow preserves prototypes, archive the full variant set outside the main branch. Otherwise, ask before deleting the files. Do not leave losing variants or the switcher in production code.
+
+## Anti-patterns
+
+- **Variants that differ only in color 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/prototype/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Prototype"
+  short_description: "Build disposable logic and UI prototypes"
+  default_prompt: "Use $prototype to build a disposable prototype that answers one design question."

package/skills/visual-recap/SKILL.md

@@ -73,19 +73,21 @@ State why the overall risk has that level. A new unit is not automatically high
 
 Match the visual to the review question:
 
-- Use a map for relationships and blast radius.
-- Use a flow or timeline for behavior that crosses several steps.
+- Use a Mermaid flowchart for relationships and blast radius.
+- Use a Mermaid sequence or state diagram for behavior that crosses several steps or states.
 - Use a table for exact mappings or classifications.
 - Use a side-by-side view for before and after.
 - Use interaction only when it helps the reviewer trace a path, inspect evidence, or compare states.
 
 Skip the diagram when one obvious relationship or a short table explains the change better.
 
-Prefer a native interactive surface when the current **Host Agent** can present it reliably and interaction saves review effort. Otherwise, use a rendered visual or inline Markdown. If diagrams do not render, use a compact text map.
+Use Mermaid as the default portable diagram format. It is an output representation, not a required tool. Let the current **Host Agent** render it with its native interface. Use a richer interactive surface only when it saves review effort.
+
+If the current interface does not render Mermaid, use a compact ASCII-art diagram as the first fallback. Use a Markdown table and short relationship list only when ASCII would be harder to scan or cannot express the relationship clearly.
 
 Do not require or name a product-specific tool. Do not add a dependency, deployment, or standalone application only to render the recap.
 
-Always provide a concise inline fallback. The fallback must preserve the outcome, affected units, risk, review hotspots, and evidence links.
+Always provide a concise inline summary. It must preserve the outcome, affected units, risk, review hotspots, and evidence links.
 
 ## Compose the Result