@starcier/create-builder 0.0.0-stage → 1.0.0-next.1

package/template/.claude/skills/design-system/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: design-system
+description: Design principles applied automatically when creating or modifying any component or screen in this design system. Covers accessibility (color-alone rule, contrast per theme, reduced motion), token governance (how to fix broken tokens without breaking other components), UX writing, empty/loading/error states, floating elements, icon semantics, typography, and component location. Trigger whenever making any visual or design decision — not just new components, but any edit touching states, colors, typography, icons, or copy.
+---
+
+# Design System — Design Principles
+
+These principles apply automatically whenever any component is created or modified — without
+needing to be reminded. This is about the design decisions themselves; technical conventions
+live in `AGENTS.md`.
+
+---
+
+## 1. State is never communicated by color alone — when no other carrier exists
+
+If a state is already communicated through text, a number, an icon, or a shape, color is
+reinforcement, not the sole carrier. This rule applies where color is the ONLY distinguishing
+factor (e.g. an empty vs. filled circle with no text or icon inside).
+
+Before implementing any state: is there anything besides color that distinguishes it? If not,
+add a shape, icon or text difference.
+
+---
+
+## 2. Dark theme is checked always, for every component — not on request
+
+Every component must be verified in both themes before it is considered done. If a color token
+looks unadapted for dark (too light or dark, no contrast, identical value in both sets), catch it
+during the build — don't leave it for the user to discover.
+
+---
+
+## 3. Contrast is checked separately for light and for dark
+
+Passing WCAG AA in light does NOT guarantee passing in dark, and vice versa. Check each theme
+independently, especially muted or disabled states, text on colored surfaces, and small text.
+
+---
+
+## 4. How to resolve a token problem depends on whether the token is used elsewhere
+
+If a color token fails a contrast check or looks wrong in one theme:
+
+- **Used only in the current component** → fix the token itself, in both sets in `tokens.ts`.
+- **Already used by other components** → do NOT change it globally. Add a NEW semantic token
+  for this component with correct light and dark values.
+
+---
+
+## 5. Any token problem is resolved as an explicit decision — never silently patched
+
+Before choosing a path from Rule 4, say: "this token is also used in [list] / nowhere else, so I'm
+choosing [A/B]." Never use a TODO comment instead — it hides the problem.
+
+---
+
+## 6. UX writing follows the established copy — or the user decides
+
+Before writing any text (labels, placeholders, helper text, errors, empty states, status
+labels), check how existing components and prototypes phrase the same thing: tone, casing,
+length, terminology, punctuation. Match it. If there is no precedent for a case, ask the user
+rather than inventing a rule.
+
+---
+
+## 7. Sizing, spacing, and radius — only from the scales, never hardcoded
+
+Padding, gap, radius and sizing come only from `space` and `radius` in `tokens.ts`. If no value
+fits, ask the user whether to add one to the scale.
+
+---
+
+## 8. Empty / Loading / Error states are required, not an afterthought
+
+Any component that displays data (lists, cards, tables) needs all three: empty, loading and
+error. If the reference shows only the happy path, flag the gap and ask — do not silently skip.
+
+---
+
+## 9. Icons — semantic consistency, not arbitrary choice
+
+The same action or concept always uses the same icon. Before choosing an icon, check whether
+the concept already has one elsewhere, and reuse it.
+
+---
+
+## 10. Text truncation / overflow is a defined decision, not an accident
+
+For text with constrained width, decide upfront: truncate with "…", wrap, or grow the container.
+If the reference doesn't show it, ask.
+
+---
+
+## 11. Minimum clickable/tap target size
+
+Interactive elements have a target of at least 24×24px (44×44px on mobile), even when the visual
+element is smaller.
+
+---
+
+## 12. Reduced motion — animations have a static fallback
+
+Any animation or transition respects `prefers-reduced-motion`. `global.css` turns transitions
+off for it; a component with its own animation must not defeat that.
+
+---
+
+## 13. Focus order matches visual order
+
+In components with several focusable parts, Tab follows the logical, visual order. Every
+interactive element shows a visible focus ring, using `--color-border-focus`.
+
+---
+
+## 14. Floating elements overlay content — they never displace it
+
+Tooltips, dropdowns, menus and popovers:
+
+1. **Overlay adjacent content, never shift it.**
+2. **Are never clipped by a parent** with `overflow: hidden/auto` — render through a portal at
+   `document.body` when needed.
+3. **Stack correctly.** Overlays sit between the builder's top bar (200) and its comments and
+   tours (9140 and up); use `zIndex` from the tokens. Test inside a scrolling container, not only
+   on an empty page.
+
+---
+
+## 15. Typography — only from the existing text styles
+
+Every text element uses a style from `typography` (through `--text-<role>-*`). Never an arbitrary
+size, weight, line-height or family. A new style is created only when the user asks for one.
+
+---
+
+## 16. Colors are never hardcoded; a new color always becomes a token
+
+No hex, rgb, hsl or gradient in components or prototypes. If a color doesn't exist yet:
+
+1. Add a semantic token to both sets in `tokens.ts` (a role name, not "custom-blue-1").
+2. Give it correct light and dark values immediately (Rules 2 and 3).
+3. Use the new token.
+
+---
+
+## 17. Component location is verified, not assumed
+
+Generic, reusable components live in `src/design-system/components/<Name>/`. Prototype-only
+pieces live in their prototype's folder. Before creating a file, state which it is and why, and
+check it against `AGENTS.md`. A disagreement about the architecture is the user's decision to
+make and document — not something to "fix" silently.
+
+---
+
+## 18. Never use the native browser tooltip (`title` attribute)
+
+The `title` attribute cannot be styled, ignores the tokens and the dark theme, and behaves
+differently across browsers. If the design system has no Tooltip component yet and one is needed,
+propose adding it (Rule 17) rather than reaching for `title`. Icon-only controls still need an
+`aria-label`.
+
+---
+
+## 19. Changes to the chrome go through the palette
+
+The builder's top bar, catalogue and sign-in pages are colored by `src/design-system/palette.ts`,
+which maps tokens onto the `BuilderPalette` contract. When a token used there changes or is
+renamed, update the mapping in the same change. The review and tour controls keep their own fixed
+look on purpose — do not try to restyle them.
+
+---
+
+## General principle
+
+Before any design decision (color, state, contrast, text, icon, layout), check whether an
+established source of truth exists in this system — the tokens, an existing component, existing
+copy — and follow it. Inventing a plausible-sounding decision without checking is the root cause
+of most errors.

package/template/.claude/skills/design-system-audit/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: design-system-audit
+description: Runs a systematic accessibility, dark-theme, token, and consistency audit over existing design-system components — checking them against the rules in the design-system skill. Use this when the user asks to audit, review, clean up, or check existing components against design-system rules, rather than when building a new component. Also proactively suggested (never auto-run) after every 3rd new component, after a cross-cutting token fix, or when the user flags visible inconsistency between components.
+---
+
+# Design System — Audit Skill
+
+This skill defines HOW to audit already-built components. It does NOT define the rules — those
+live in the `design-system` skill (design principles) and `AGENTS.md` (technical conventions).
+Read both, every time, before an audit; they may have changed since you last saw them.
+
+The audit is read-only until Part 5 (Fixing). No fix is applied without the user confirming the
+report first.
+
+The audit keeps its record in `docs/design-system-log.md`: a changes log, past audits, and
+deferred tech debt.
+
+---
+
+## Auto-trigger rule
+
+Suggest an audit (never run one without asking) when:
+
+1. **Every 3rd new component** since the last audit — count from the log's changes section.
+2. **A cross-cutting token issue was just fixed** (e.g. an unadapted dark value) — the same token
+   may be wrong in components that already shipped. Suggest auditing those that share it.
+3. **The user mentions inconsistency** between components ("this looks different from X").
+
+Be specific and low-friction:
+
+> "This is the 3rd component since the last audit. Want me to run a consistency check across
+> them before we continue?"
+
+If the user declines, don't ask again for the same trigger.
+
+---
+
+## Part 1 — Setup
+
+1. Read the `design-system` skill in full.
+2. Read `AGENTS.md`.
+3. Read `docs/design-system-log.md` for known tech debt — don't re-discover it, but verify it is
+   still accurate.
+4. List every component in `src/design-system/components/`. This is the scope; confirm it with
+   the user if the request was ambiguous.
+
+---
+
+## Part 2 — Per-component check
+
+Check each component against every rule, one rule at a time. Each outcome is one of:
+
+- **Pass** — compliant.
+- **Bug** — visibly broken: wrong color, missing state distinction, broken dark theme, clipped
+  popover.
+- **Debt** — violated but not yet visible: a hardcoded value that matches a token today, spacing
+  close to but off the scale.
+- **Question** — cannot be decided without the user.
+
+Cite the exact file, line or token. Give dark theme (Rules 2–3), hardcoded colors (Rule 16) and
+floating-element stacking (Rule 14) explicit attention even when nothing looks wrong.
+
+---
+
+## Part 3 — Cross-component consistency pass
+
+Then look across all components together:
+
+- Do equivalent states (active, disabled, error) use the same tokens everywhere, or did
+  components invent slightly different values for the same concept?
+- Are icons for the same concept identical (Rule 9)?
+- Do components follow the same file shape (`<Name>.tsx`, `<name>.css`, `index.ts`) and class
+  naming (`ds-<name>`)?
+
+---
+
+## Part 4 — Report (before any code changes)
+
+```
+## [Component Name]
+✅ Passes: [rules confirmed compliant, grouped]
+🐛 Bugs:
+  [Rule N]: [finding, file/line/token cited]
+💸 Debt:
+  [Rule N]: [finding, file/line/token cited]
+❓ Questions:
+  [ambiguity, framed as a question]
+```
+
+Order components by severity (most bugs first). Add a final section for cross-component findings.
+
+After the report, add a dated entry under "Audits" in `docs/design-system-log.md`:
+
+```
+- [date] — [N components checked]: [X bugs, Y debt, Z questions]
+```
+
+---
+
+## Part 5 — Fixing
+
+Only after the user confirms which items to fix:
+
+1. Bugs first, then debt, unless the user says otherwise.
+2. A fix touching a shared token follows the design-system skill's Rules 4–5 — say whether the
+   token is used elsewhere before changing it.
+3. Update `docs/design-system-log.md`: remove resolved debt, log what was fixed, and add any debt
+   deliberately deferred, with the reason.
+
+---
+
+## Tech debt cleanup trigger
+
+The tech-debt list is not a parking lot. Suggest a cleanup pass (never run one unasked) when it
+passes 15 open items, when one category appears 3+ times (a batch fix), or when an item has sat
+through 2 audits. Separate mechanical batch fixes from items that need a design decision first.
+
+---
+
+## What this skill deliberately does NOT do
+
+- Define the design principles — read the `design-system` skill fresh instead.
+- Fix anything during scanning — reporting and fixing are separate, with a user checkpoint.
+- Skip components because they are recent — recency is not evidence of compliance.
+- Run itself — it only suggests, and waits for confirmation to run and to fix.

package/template/.claude/skills/design-work-review/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: design-work-review
+description: Senior front-end code review of design work in this repo — evaluates any change (a prototype, a design-system component, or tokens) for architecture, layering, reusability, maintainability, design-system/token compliance, light and dark themes, and the build/lint gate. Default target is the current branch's diff against its base branch; also accepts an explicit target (a component, a prototype, or a folder). Use when asked to "review my branch / this PR / these changes", "review the <component>/<prototype>", "is this ready to merge", or "senior review of this diff".
+---
+
+# Design Work Review
+
+You are a **senior front-end engineer** reviewing design work. Judge whether the change is
+well-architected, in the right layer, reusable, maintainable and compliant with the design system
+— not just whether it runs. Cite `file:line`. **Review only; change code only if the user asks
+you to fix findings.**
+
+## Repo reality
+
+- **Vite + React 19 + TypeScript**, plain CSS driven by tokens, react-router owned by the builder
+  shell. Not Next.js, not Tailwind, no CSS-in-JS runtime.
+- **Design system:** `src/design-system/` — `tokens.ts` (the only source of design values),
+  `ThemeProvider.tsx` and `theme.ts` (tokens as CSS custom properties, the active theme),
+  `palette.ts` (tokens onto the builder's chrome),
+  `components/<Name>/` (`<Name>.tsx`, `<name>.css`, `index.ts`).
+- **Prototypes:** `src/prototypes/<folder>/<id>/`, registered in `registry.ts` and
+  `workflows.ts`.
+- **Layering:** generic UI belongs in the design system; prototype folders hold only that
+  prototype's screen, styles and mock data. Never fork a near-duplicate.
+
+## Step 1 — Resolve the scope
+
+**Default:** the current branch's diff against its base (ask which, if it isn't obvious), plus
+uncommitted work:
+
+```bash
+BASE="${BASE:-main}"
+git fetch origin "$BASE" --quiet 2>/dev/null || true
+git diff --stat "origin/$BASE...HEAD"
+git diff --name-only "origin/$BASE...HEAD"
+git status --short
+```
+
+**Explicit target:** scope to the named component, prototype or folder, plus whatever it wires
+up elsewhere. If ambiguous, list candidates and ask.
+
+## Step 2 — Read the rules
+
+`AGENTS.md`, and the `design-system` skill for design decisions.
+
+## Step 3 — Automated sweeps (on the changed files)
+
+```bash
+# raw colors outside tokens.ts
+rg -niE "#[0-9a-f]{3,8}\b|rgba?\(" $FILES
+# raw px design values (spacing, radius and type come from tokens)
+rg -niE ":\s*-?[0-9]+px" $FILES
+# backend / network / auth — forbidden in prototypes
+rg -niE "fetch\(|axios|/api/|useQuery|swr" $FILES
+# raw interactive elements where a component exists
+rg -nE "<(button|input|dialog)\b" $FILES
+# leftovers
+rg -nE "console\.(log|debug)|: any\b|TODO|FIXME" $FILES
+```
+
+`tokens.ts` is the one place raw values belong; components implementing a primitive (e.g.
+`Button.tsx` rendering `<button>`) are the expected exception to the raw-element sweep.
+
+## Step 4 — The rubric (PASS / FAIL / N/A)
+
+1. **Architecture & layering** — in the right place; a minimal, typed, prop-driven API; an
+   `index.ts` like its siblings.
+2. **Reusability** — composes existing pieces; no near-duplicates; naming consistent.
+3. **Maintainability** — readable, no dead code, strict TypeScript (no `any`), sound effects,
+   accessible (roles, `aria-*`, keyboard).
+4. **Design-system compliance** — tokens only; renders in light AND dark (reason about dark
+   explicitly); overlays stack between 200 and 9140; a token change used by the chrome is
+   reflected in `palette.ts`.
+5. **Quality gate** — run `npm run build` and `npm run lint`; report the actual results.
+6. **Prototypes** (when changed) — no backend; local typed mock data; `data-tour` anchors; a tour
+   whose `prototypeId` equals the registry `slug`; registered in both files.
+
+## Step 5 — Report
+
+- **Verdict:** ✅ Approve / 🔧 Approve with changes / ❌ Request changes.
+- **Summary:** one line per rubric section.
+- **Findings:** ranked, as `severity — file:line — problem — suggested fix`.
+- **Quality gate:** the actual build and lint results.
+- **Nice-to-haves:** separate from must-fix.
+
+Severity: **Blocker** — build or lint fails. **High** — raw color or px value, broken dark theme,
+backend in a prototype, a generic component in the wrong layer, a duplicate. **Medium** — weak
+API, raw element where a component exists, missing `index.ts`. **Low** — nits.
+
+## Fix mode
+
+If asked to fix: apply the fixes, highest severity first, then re-run build and lint and report
+again.

package/template/.claude/skills/process-interviewer/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: process-interviewer
+description: Relentless process interviewer that extracts a complete, unambiguous plan from the user's head before any building begins. Use when the user wants to plan a complex task, design a process, build a skill, create a workflow, scope a project, or says things like "I want to build", "let's plan", "help me think through", "I have an idea for", "scope this out", "interview me", "help me figure out the process", "I need a skill that", or any variation where the user has a fuzzy idea that needs to be sharpened into a concrete plan. Also use when the user wants to stress-test a plan, validate their thinking, or get challenged on their assumptions. If the user's goal is to build a skill, this interviewer will automatically create it after the interview is complete. ALWAYS use this skill before jumping into building anything complex. Even if the user seems confident, the interview reveals gaps they didn't know they had.
+---
+
+# Process Interviewer
+
+You are a relentless interviewer whose job is to extract the complete process from the user's head before anything gets built. Most people think they know what they want, but when pressed on specifics, they discover gaps, contradictions, and unresolved decisions. Your job is to find every one of those gaps.
+
+## The Goal
+
+The single outcome of this skill is **shared understanding**. By the end of the interview, you and the user should be so aligned on what's being built (or planned) that there are zero surprises when execution starts. Every question you ask exists to close a gap between what's in the user's head and what's in yours. The interview is done when both sides could independently describe the same plan and arrive at the same result.
+
+## Why this matters
+
+Bad skills and bad plans fail for the same reason: the creator skipped the hard thinking. They jumped to building before they understood the process. This interviewer exists to prevent that. By the time you're done, the shared understanding should be so complete that building becomes mechanical.
+
+## How the interview works
+
+### Phase 1: The Big Picture (2-4 questions)
+
+Start by understanding what the user is trying to accomplish and why. Don't accept vague answers. If they say "I want a skill that helps with LinkedIn posts," push back: What specifically about LinkedIn posts? What's the input? What does success look like? Who is this for?
+
+Ask ONE question at a time. After each answer, acknowledge what you heard, then dig deeper or move to the next branch.
+
+**Opening question format:** Start with something like: "Before we build anything, I want to make sure we get this right. Let me interview you on this so we don't miss anything. First: [specific question about the goal]."
+
+Key things to establish early:
+
+- What is the actual goal? (Not "what do you want to build" but "what problem are you solving")
+- Who is this for? (Just the user? A team? Clients?)
+- What does the input look like? (Where does data come from? What format?)
+- What does the output look like? (What gets produced? Where does it go?)
+- Is this a skill they want to build, or just a plan/process they want to clarify?
+
+### Phase 2: The Process Deep-Dive (5-15 questions)
+
+This is where you get relentless. Walk through the process step by step, and at each step ask:
+
+- "What exactly happens here?"
+- "What decisions need to be made at this point?"
+- "What could go wrong here?"
+- "What does the user need to provide vs. what should be automatic?"
+- "Show me an example of what this looks like in practice"
+
+**The Relentless Pattern:** For every answer the user gives, ask yourself: "Is this specific enough that I could hand it to a stranger and they'd know exactly what to do?" If not, push deeper.
+
+Examples of pushing deeper:
+
+- User: "Then it analyzes the content." → You: "Analyzes it how? What are you looking for specifically? Give me an example of content going in and what the analysis should produce."
+- User: "It should write in my tone of voice." → You: "Describe your tone of voice in concrete terms. Show me a paragraph that IS your voice and one that ISN'T. What are the specific patterns?"
+- User: "It formats the output nicely." → You: "Define 'nicely'. What format? What sections? What's required vs optional? Show me an ideal output."
+
+**Decision Tree Navigation:** When you hit a branch point (e.g., "it depends on whether the input is a URL or raw text"), resolve BOTH branches before moving on. Don't leave any path unexplored.
+
+### Phase 3: Edge Cases and Failure Modes (3-5 questions)
+
+Once the happy path is clear, probe the edges:
+
+- "What happens when the input is incomplete or malformed?"
+- "What if the user changes their mind halfway through?"
+- "What's the minimum viable input that should still produce useful output?"
+- "Are there cases where this should refuse to proceed? What are they?"
+- "What happens when [specific external dependency] is unavailable?"
+
+### Phase 4: Confirmation and Gaps (2-3 questions)
+
+Summarize the entire process back to the user as you understand it. Use a structured format:
+
+```
+Here's what I've captured so far:
+
+GOAL: [one sentence]
+INPUT: [what goes in]
+PROCESS:
+  1. [step with specifics]
+  2. [step with specifics]
+  ...
+OUTPUT: [what comes out]
+EDGE CASES: [how failures are handled]
+```
+
+Then ask: "What did I get wrong? What's missing?" This almost always surfaces 1-2 more things they forgot to mention.
+
+### Phase 5: Build or Plan
+
+Based on whether the user wants a skill or just a plan:
+
+**If building a skill:** Read `references/skill-output-template.md` for the skill structure, then automatically generate the complete skill. Follow the best practices from the article (concise, progressive disclosure, explain the why, avoid over-explaining things Claude already knows). Create the SKILL.md and any necessary reference files. Save them to the workspace.
+
+**If just planning:** Read `references/plan-output-template.md` and produce a detailed plan document. Save it to the workspace.
+
+## Interview Rules
+
+1. **ONE question at a time.** Never ask 2+ questions in a single message. Pick the most important one.
+2. **Answer your own questions from context first.** Before asking the user anything, check whether the answer already exists in the workspace folder this session has access to. Scan existing skills, reference files, CLAUDE.md files, project folders, and any other available context. If the answer is there, state what you found and confirm with the user ("I found [X] in your existing [file]. Does that still hold, or has it changed?") instead of asking them to repeat themselves. Only ask questions the workspace can't answer.
+3. **Recommend an answer.** For every question, provide your suggested answer or best guess based on what you know so far. This gives the user something to react to instead of staring at a blank page. Format: "My recommendation would be [X] because [reason]. Does that match what you're thinking, or would you go a different direction?"
+4. **Acknowledge before advancing.** After each answer, briefly confirm what you heard ("Got it, so the input is always a YouTube URL and the output is...") before asking the next question. This prevents misunderstandings from compounding.
+5. **Don't accept vague answers.** If the user says "it depends" or "whatever works best," push for specifics. Say: "I need you to make a call here. If you had to pick one default approach, what would it be? We can add flexibility later."
+6. **Use concrete examples.** When the user describes something abstract, ask for a concrete example. "Can you show me what a real input would look like? And what the ideal output would be for that input?"
+7. **Track unresolved items.** If the user says "I'll figure that out later," note it and come back to it before Phase 5. Nothing should be unresolved at the end.
+8. **Be conversational, not interrogative.** You're helping them think, not deposing them. Use a warm but persistent tone. Think of it as a collaborative whiteboarding session where you happen to be the one asking all the questions.
+9. **Know when to stop.** The interview is done when: (a) every step of the process is specific enough to implement, (b) edge cases are handled, (c) the user confirms the summary is accurate. Don't keep asking just to ask.
+10. **Adapt question depth to complexity.** Simple skills (3-4 steps) need 8-10 questions total. Complex workflows (10+ steps, multiple branches) might need 15-20. Don't over-interview simple things.
+11. **If the user gets impatient,** explain why you're being thorough: "I know this feels like a lot of questions, but every gap we close now is a rewrite we avoid later. We're almost through the hard part."
+
+## Detecting the User's Intent
+
+When this skill triggers, immediately determine:
+
+1. **Are they building a skill?** Look for: "I want a skill that...", "build me a skill", "create a skill", "turn this into a skill"
+2. **Are they planning a process?** Look for: "help me plan", "think through this", "scope this out", "figure out the process"
+3. **Are they stress-testing an existing plan?** Look for: "grill me on this", "poke holes in my plan", "what am I missing"
+4. **Not sure?** Ask directly in your first question: "Before we dig in: is the end goal to build a skill that Claude can run, or are you looking for a detailed plan you'll execute yourself?"
+
+## What Makes This Different from Just Asking Questions
+
+Regular planning conversations drift. The user says something vague, the assistant accepts it, and both move on. This skill is different because:
+
+- It follows a structured progression (big picture → process → edges → confirmation)
+- It refuses to move forward with ambiguity
+- It always provides a recommendation (the user reacts instead of generating from scratch)
+- It produces a concrete artifact at the end (a skill or a plan document)
+- It tracks what's been resolved and what hasn't

package/template/.claude/skills/process-interviewer/references/plan-output-template.md

@@ -0,0 +1,53 @@
+# Plan Output Template
+
+After the interview is complete and the user wants a plan (not a skill), produce a document using this structure. Save as a markdown file in the workspace.
+
+## Plan Document Structure
+
+```markdown
+# [Plan Title]
+
+## Goal
+[One clear sentence describing what this plan achieves and why it matters]
+
+## Context
+[2-3 sentences of background: who is this for, what triggered this, any constraints]
+
+## Process Overview
+[Numbered list of high-level steps, each one sentence. This is the "at a glance" version.]
+
+## Detailed Steps
+
+### Step 1: [Step Name]
+**What happens:** [Specific description]
+**Input:** [What's needed to start this step]
+**Output:** [What this step produces]
+**Decisions:** [Any choices that need to be made]
+**Owner:** [Who does this, if applicable]
+**Notes:** [Anything non-obvious]
+
+### Step 2: [Step Name]
+[Same structure as above]
+
+[Continue for all steps...]
+
+## Edge Cases and Failure Modes
+[Bulleted list of what could go wrong and how to handle each case]
+
+## Dependencies and Requirements
+[What needs to be in place before this plan can execute]
+
+## Open Questions
+[Anything that came up during the interview that still needs resolution. Should be minimal if the interview was thorough.]
+
+## Success Criteria
+[How do you know this plan worked? What metrics or outcomes indicate success?]
+```
+
+## Writing Guidelines
+
+- Be specific enough that someone who wasn't in the interview could follow the plan
+- Use the user's own language and terminology where possible
+- Every step should pass the "stranger test": could a competent stranger execute this step with no additional context?
+- Include concrete examples where the user provided them during the interview
+- Flag any areas where the user was uncertain or where assumptions were made

package/template/.claude/skills/process-interviewer/references/skill-output-template.md

@@ -0,0 +1,72 @@
+# Skill Output Template
+
+After the interview is complete and the user wants a skill built, use this template to generate it. Apply the best practices below while writing.
+
+## SKILL.md Structure
+
+```yaml
+---
+name: [lowercase-with-hyphens, max 64 chars, gerund form preferred]
+description: [What it does + when to trigger. Be specific. Include trigger phrases. Max 1024 chars. Write in third person. Be slightly "pushy" about when to use it so it actually triggers.]
+---
+```
+
+## Best Practices to Apply
+
+### Be concise
+Claude is smart. Don't explain what PDFs are or how libraries work. Only add context Claude doesn't already have. Challenge every paragraph: "Does this justify its token cost?"
+
+### Explain the why, not just the what
+Instead of "ALWAYS do X", explain why X matters. Claude responds better to understanding the reasoning than to rigid rules.
+
+### Set appropriate freedom levels
+- High freedom for judgment calls (code review, writing style)
+- Medium freedom for preferred patterns with acceptable variation
+- Low freedom for fragile operations (database migrations, API sequences)
+
+### Use progressive disclosure
+- Keep SKILL.md body under 500 lines
+- Put detailed references in separate files with clear pointers
+- Keep file references one level deep from SKILL.md
+- For files over 100 lines, include a table of contents
+
+### Include workflows with checklists
+For multi-step processes, provide a checklist the model can track:
+```
+Task Progress:
+- [ ] Step 1: ...
+- [ ] Step 2: ...
+```
+
+### Build in feedback loops
+Add validation steps: "After step 3, verify the output by [check]. If validation fails, return to step 2."
+
+### Use examples
+Input/output pairs are more powerful than descriptions. Show what good output looks like.
+
+### Avoid anti-patterns
+- No time-sensitive info ("before August 2025...")
+- Consistent terminology (pick one term, use it everywhere)
+- No vague descriptions ("helps with documents")
+- No deeply nested file references
+- No Windows-style paths
+
+## Skill File Organization
+
+```
+skill-name/
+├── SKILL.md              # Main instructions (under 500 lines)
+├── references/           # Loaded on demand
+│   ├── examples.md       # Input/output examples
+│   ├── templates.md      # Output templates
+│   └── domain-ref.md     # Domain-specific reference
+└── scripts/              # Executed, not loaded into context
+    └── utility.py        # Deterministic operations
+```
+
+## After Writing the Skill
+
+1. Save all files to the workspace folder
+2. Present the skill to the user with a summary of what was created
+3. Offer to refine or adjust anything
+4. Mention they can install it or use the skill-creator skill to run evals on it