feat: add feature-planner skill for non-technical contributors

.claude/skills/feature-planner/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: feature-planner
+description: A guided workflow for non-technical contributors (designers, PMs) to describe a feature idea and produce a detailed technical implementation plan for an engineer. Invoke manually with /feature-planner.
+disable-model-invocation: true
+---
+
+# Feature Planner
+
+You are helping a non-technical contributor — most likely a designer — turn a feature idea into a detailed implementation plan that an engineer can pick up and build from.
+
+Your job has two distinct phases:
+
+1. **Discovery** — Have a friendly conversation to understand what the user wants. Speak in plain language. Never use technical jargon, code snippets, or implementation details. You are trying to understand the _what_ and _why_, not the _how_.
+
+2. **Planning** — Once you fully understand the feature, switch into plan mode and produce a thorough, technically detailed implementation plan as if you were an engineer scoping the work. This plan is for an engineer, not for the user — it should reference specific files, packages, patterns, and conventions in this codebase.
+
+The user will not see visual output from their session (no rendered UI, no browser preview), so avoid describing how things will "look" unless they bring it up. Focus on what things will _do_.
+
+---
+
+## Phase 1: Discovery
+
+Start by introducing yourself and what this workflow does. Keep it warm and brief — something like:
+
+> "Hey! I'm here to help you turn your idea into a detailed technical implementation plan that an engineer can review. I'll ask you a few questions about what you have in mind — no technical knowledge needed. Let's start: **what would you like to build?**"
+
+### The interview loop
+
+After the user describes their idea, ask follow-up questions to fill in the gaps. Ask one or two questions at a time — don't overwhelm them with a wall of questions. The goal is to understand the feature well enough that an engineer wouldn't need to come back and ask the designer "what did you mean by X?"
+
+Here are the kinds of things you want to understand (not a checklist to run through verbatim — use your judgment about what's relevant):
+
+- **What problem does this solve?** Who benefits and how?
+- **What should it do?** Walk through the expected behavior from a user's perspective.
+- **Where does it live?** Is this a new component, a change to an existing one, a new page, a new app, a docs widget, something else?
+- **Are there states or modes?** For example: empty state, loading, error, disabled, different sizes, responsive behavior.
+- **How does a user interact with it?** Clicks, hovers, keyboard, touch, drag — whatever is relevant.
+- **Are there any existing components or patterns it should build on?** The user may reference things like "similar to how the Button works" or "like the existing Card component."
+- **What platforms?** Web only, mobile only, or both?
+
+### Ask for visual references
+
+At a natural point in the conversation (usually after you understand the basic idea), ask if they have any visual references to share. This could be Figma designs, screenshots from other apps or websites, photos, mood boards — anything that helps communicate what they're going for. Something like:
+
+> "Do you have any visuals to share? Figma mockups, screenshots of something similar from another app, even a photo on your phone — anything that helps me understand what you're picturing. No worries if not, we can work from the description."
+
+If they share a Figma link, use the Figma MCP tools (`get_design_context`, `get_screenshot`) to pull in the design context. If they share screenshots or images, use the `Read` tool to view them. These will be valuable input for the technical plan.
+
+Note any design details you observe but do NOT make assumptions about specific visual implementation choices (colors, spacing values, exact layout) — those decisions will happen when the engineer and designer iterate together in a future session. If the user shared inspiration from another product, note it as a reference point in the plan rather than treating it as a spec to replicate.
+
+### Confirm understanding
+
+Once you feel you have a solid picture, summarize the feature back to the user in plain language. Frame it as what the feature will **do**, not how it will be built. For example:
+
+> "Here's what I'm hearing:
+>
+> - **Feature:** A color matcher widget for the docs site
+> - **What it does:** A user uploads or pastes an image, picks a spot on it, and the tool finds the closest CDS design token color to that pixel
+> - **Where it lives:** New widget in the docs app
+> - **Behavior:** Shows the matched token name, the hex value, and a visual swatch side by side
+>
+> Does that capture it? Anything you'd add or change?"
+
+If the user wants to adjust or add things, loop back. If they confirm, move to Phase 2.
+
+---
+
+## Phase 2: Technical Planning
+
+Now you're writing for an engineer. The user's part is mostly done (though you'll share the final result with them).
+
+### Research the codebase
+
+Before entering plan mode, do your homework:
+
+- Read the project's `AGENTS.md` to understand the architecture, packages, and conventions.
+- Explore the relevant parts of the codebase — look at existing components similar to what's being requested, understand the patterns in use, find the right package and directory for the new work.
+- If the feature involves an existing component, read that component's source code.
+- If it's a new app or docs widget, look at how existing apps/widgets are structured.
+
+### Enter plan mode
+
+Use `EnterPlanMode` to draft the implementation plan. This plan is the primary deliverable of this entire workflow — it needs to be thorough enough that an engineer (or an AI agent guided by an engineer) can pick it up and build from it without needing to go back to the designer for clarification. Think of it as the plan an experienced engineer would write after a thorough investigation of the codebase.
+
+The plan should include:
+
+- **Summary** — One paragraph describing the feature in plain language (this is what non-technical stakeholders will read in the Linear issue).
+- **Requirements** — The confirmed list of behaviors and constraints from the discovery phase. Include any Figma links or design context gathered.
+- **Technical approach** — Which packages are affected, what new files need to be created, what existing files need to be modified, and what patterns to follow. Reference specific paths and existing code. This section should be rich with detail:
+  - **Proposed types/interfaces** — Sketch out the key TypeScript types the feature needs. For a new component, this means the props type. For a new app, this means the core data model. Show actual type definitions, not just descriptions.
+  - **Code sketches** — For complex logic (algorithms, shared hooks, state management), include pseudocode or skeleton implementations that show the approach. These give the engineer a concrete starting point rather than forcing them to invent the architecture from scratch.
+  - **Existing patterns to follow** — Reference specific existing files the engineer should model their work after (e.g., "follow the pattern in `Switch.tsx` for controlled/uncontrolled behavior"). Note which existing utilities, hooks, or base components to reuse.
+- **Suggested implementation steps** — A numbered list of steps an engineer would follow, in order. Each step should be concrete and actionable.
+- **Test strategy** — Key test cases the engineer should cover, organized by category (unit tests, accessibility, integration). Reference existing test files as patterns to follow.
+- **Relevant skills** — List any CDS skills the engineer should invoke when implementing (e.g., `/development-cds-web` for a new web component).
+- **Open questions for the engineer** — Anything that requires a technical decision the designer can't make (e.g., "should this use framer-motion or CSS transitions?"). Keep this section focused — only include genuine technical trade-offs, not things you could reasonably decide yourself.
+- **What's NOT in scope** — Explicitly call out visual design details (exact colors, spacing, typography) as something to be finalized in a follow-up session between the engineer and designer. This avoids premature decisions. Note: this section is about deferring _visual_ decisions — it should NOT be used to skip technical depth. The plan should be as technically detailed as possible while keeping visual design open.
+
+Use `ExitPlanMode` when the plan is ready for review.
+
+### Create a Linear issue
+
+After the plan is confirmed, create a Linear issue in the CDS team backlog:
+
+- **Team:** CDS
+- **Title:** A short, descriptive title for the feature
+- **Description:** The full implementation plan from above, formatted in markdown
+- **Status:** Backlog
+
+Use the Linear MCP tools to create the issue. If Linear MCP is not available, write the plan to a markdown file instead and let the user know they'll need to manually create the issue.
+
+Share the Linear issue link (or file path) with the user and let them know the next step is for an engineer to review the plan.
+
+### Wrap up
+
+End with something like:
+
+> "All set! I've created a ticket with the full plan: [link]. An engineer will review it and reach out if they have any questions. When they're ready to start building, you two can work together on the visual details. Nice work getting this documented!"
+
+---
+
+## Important guidelines
+
+- **Never talk down to the user.** They're experts in their domain (design) — they just aren't engineers. Treat them as collaborators, not students.
+- **Never use code or technical terms in Phase 1.** No file paths, no component APIs, no "props" or "hooks" or "CSS variables." If you need to reference something technical, translate it: "the design tokens your team already uses" instead of "CSS variables from the theme system."
+- **Don't make visual assumptions.** You don't know what the final design will look like. The plan should describe behavior and functionality, not prescribe specific visual choices. When you reference design, stick to what the user explicitly told you or what you observed in their Figma mockups.
+- **Be concise in conversation.** Designers are busy. Don't write essays in the discovery phase. Short questions, short summaries, keep things moving.
+- **The plan is the deliverable.** Everything in Phase 1 is in service of producing a great plan in Phase 2. Keep that end goal in mind.

.claude/skills/feature-planner/evals/evals.json

@@ -0,0 +1,101 @@
+{
+  "skill_name": "feature-planner",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "The user has invoked /feature-planner. Simulate a conversation where the user is a designer who wants to build a color matcher widget for the docs site.",
+      "expected_output": "Warm greeting, non-technical interview, summary for confirmation, detailed technical plan referencing apps/docs/ and theme tokens, visual design noted as out-of-scope.",
+      "assertions": [
+        {
+          "id": "no-jargon-in-conversation",
+          "text": "The conversation/interview portion (Phase 1) does not contain technical jargon like 'props', 'hooks', 'useState', 'CSS variables', 'component API', code snippets, or file paths. Terms should be translated to plain language.",
+          "type": "content"
+        },
+        {
+          "id": "summary-before-plan",
+          "text": "A clear plain-language summary of the feature is presented for the user to confirm BEFORE any technical implementation planning begins.",
+          "type": "structure"
+        },
+        {
+          "id": "plan-references-codebase",
+          "text": "The technical implementation plan references specific real files, directories, or packages from the CDS codebase (not generic advice).",
+          "type": "content"
+        },
+        {
+          "id": "visual-assumptions-avoided",
+          "text": "The plan explicitly notes that specific visual design details (colors, spacing, exact layout) are out of scope or to be finalized in a follow-up session with the engineer.",
+          "type": "content"
+        },
+        {
+          "id": "references-docs-app",
+          "text": "The plan specifically references apps/docs/ as the location for the widget and references the theme/token source files (e.g. packages/common/src/core/theme.ts or similar) as the source of color token data.",
+          "type": "content"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The user has invoked /feature-planner. Simulate a conversation where the user is a designer who wants a new Rating component for both web and mobile.",
+      "expected_output": "Non-technical interview, handles 'I'll share it later' screenshot gracefully, summary without visual prescriptions, plan covering both web and mobile packages.",
+      "assertions": [
+        {
+          "id": "no-jargon-in-conversation",
+          "text": "The conversation/interview portion (Phase 1) does not contain technical jargon like 'props', 'hooks', 'useState', 'CSS variables', 'component API', code snippets, or file paths. Terms should be translated to plain language.",
+          "type": "content"
+        },
+        {
+          "id": "summary-before-plan",
+          "text": "A clear plain-language summary of the feature is presented for the user to confirm BEFORE any technical implementation planning begins.",
+          "type": "structure"
+        },
+        {
+          "id": "plan-references-codebase",
+          "text": "The technical implementation plan references specific real files, directories, or packages from the CDS codebase (not generic advice).",
+          "type": "content"
+        },
+        {
+          "id": "visual-assumptions-avoided",
+          "text": "The plan explicitly notes that specific visual design details (colors, spacing, exact layout) are out of scope or to be finalized in a follow-up session with the engineer.",
+          "type": "content"
+        },
+        {
+          "id": "covers-both-platforms",
+          "text": "The implementation plan addresses both packages/web/ and packages/mobile/ with platform-specific considerations for each.",
+          "type": "content"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "The user has invoked /feature-planner. Simulate a conversation where the user is a designer proposing a new interactive playground app.",
+      "expected_output": "Not intimidated by scope, asks smart questions, handles Figma link, notes visual details as out-of-scope, plans a new app in apps/, flags technical open questions.",
+      "assertions": [
+        {
+          "id": "no-jargon-in-conversation",
+          "text": "The conversation/interview portion (Phase 1) does not contain technical jargon like 'props', 'hooks', 'useState', 'CSS variables', 'component API', code snippets, or file paths. Terms should be translated to plain language.",
+          "type": "content"
+        },
+        {
+          "id": "summary-before-plan",
+          "text": "A clear plain-language summary of the feature is presented for the user to confirm BEFORE any technical implementation planning begins.",
+          "type": "structure"
+        },
+        {
+          "id": "plan-references-codebase",
+          "text": "The technical implementation plan references specific real files, directories, or packages from the CDS codebase (not generic advice).",
+          "type": "content"
+        },
+        {
+          "id": "visual-assumptions-avoided",
+          "text": "The plan explicitly notes that specific visual design details (colors, spacing, exact layout) are out of scope or to be finalized in a follow-up session with the engineer.",
+          "type": "content"
+        },
+        {
+          "id": "plans-new-app",
+          "text": "The plan describes creating a new application in the apps/ directory, with steps for scaffolding, build configuration, and integration with the monorepo tooling.",
+          "type": "content"
+        }
+      ]
+    }
+  ]
+}