@diottodev/runic 1.0.0 → 1.1.0

package/product/spec-to-repo/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: spec-to-repo
+description: "Use when the user says 'build me an app', 'create a project from this spec', 'scaffold a new repo', 'generate a starter', 'turn this idea into code', 'bootstrap a project', 'I have requirements and need a codebase', or provides a natural-language project specification and expects a complete, runnable repository. Stack-agnostic: Next.js, FastAPI, Rails, Go, Rust, Flutter, and more."
+---
+
+# Spec to Repo
+
+Turn a natural-language project specification into a complete, runnable starter repository. Not a template filler — a spec interpreter that generates real, working code for any stack.
+
+## When to Use
+
+- User provides a text description of an app and wants code
+- User has a PRD, requirements doc, or feature list and needs a codebase
+- User says "build me an app that...", "scaffold this", "bootstrap a project"
+- User wants a working starter repo, not just a file tree
+
+**Not this skill** when the user wants a SaaS app with Stripe + Auth specifically — use `product-team/saas-scaffolder` instead.
+
+## Core Workflow
+
+### Phase 1 — Parse & Interpret
+
+Read the spec. Extract these fields silently:
+
+| Field | Source | Required |
+|-------|--------|----------|
+| App name | Explicit or infer from description | yes |
+| Description | First sentence of spec | yes |
+| Features | Bullet points or sentences describing behavior | yes |
+| Tech stack | Explicit ("use FastAPI") or infer from context | yes |
+| Auth | "login", "users", "accounts", "roles" | if mentioned |
+| Database | "store", "save", "persist", "records", "schema" | if mentioned |
+| API surface | "endpoint", "API", "REST", "GraphQL" | if mentioned |
+| Deploy target | "Vercel", "Docker", "AWS", "Railway" | if mentioned |
+
+**Stack inference rules** (when user doesn't specify):
+
+| Signal | Inferred stack |
+|--------|---------------|
+| "web app", "dashboard", "SaaS" | Next.js + TypeScript |
+| "API", "backend", "microservice" | FastAPI (Python) or Express (Node) |
+| "mobile app" | Flutter or React Native |
+| "CLI tool" | Go or Python |
+| "data pipeline" | Python |
+| "high performance", "systems" | Rust or Go |
+
+After parsing, present a structured interpretation back to the user:
+
+```
+## Spec Interpretation
+
+**App:** [name]
+**Stack:** [framework + language]
+**Features:**
+1. [feature]
+2. [feature]
+
+**Database:** [yes/no — engine]
+**Auth:** [yes/no — method]
+**Deploy:** [target]
+
+Does this match your intent? Any corrections before I generate?
+```
+
+Flag ambiguities. Ask **at most 3** clarifying questions. If the user says "just build it", proceed with best-guess defaults.
+
+### Phase 2 — Architecture
+
+Design the project before writing any files:
+
+1. **Select template** — Match to a stack template from `references/stack-templates.md`
+2. **Define file tree** — List every file that will be created
+3. **Map features to files** — Each feature gets at minimum one file/component
+4. **Design database schema** — If applicable, define tables/collections with fields and types
+5. **Identify dependencies** — List every package with version constraints
+6. **Plan API routes** — If applicable, list every endpoint with method, path, request/response shape
+
+Present the file tree to the user before generating:
+
+```
+project-name/
+├── README.md
+├── .env.example
+├── .gitignore
+├── .github/workflows/ci.yml
+├── package.json / requirements.txt / go.mod
+├── src/
+│   ├── ...
+├── tests/
+│   ├── ...
+└── ...
+```
+
+### Phase 3 — Generate
+
+Write every file. Rules:
+
+- **Real code, not stubs.** Every function has a real implementation. No `// TODO: implement` or `pass` placeholders.
+- **Syntactically valid.** Every file must parse without errors in its language.
+- **Imports match dependencies.** Every import must correspond to a package in the manifest (package.json, requirements.txt, go.mod, etc.).
+- **Types included.** TypeScript projects use types. Python projects use type hints. Go projects use typed structs.
+- **Environment variables.** Generate `.env.example` with every required variable, commented with purpose.
+- **README.md.** Include: project description, prerequisites, setup steps (clone, install, configure env, run), and available scripts/commands.
+- **CI config.** Generate `.github/workflows/ci.yml` with: install, lint (if linter in deps), test, build.
+- **.gitignore.** Stack-appropriate ignores (node_modules, __pycache__, .env, build artifacts).
+
+**File generation order:**
+1. Manifest (package.json / requirements.txt / go.mod)
+2. Config files (.env.example, .gitignore, CI)
+3. Database schema / migrations
+4. Core business logic
+5. API routes / endpoints
+6. UI components (if applicable)
+7. Tests
+8. README.md
+
+### Phase 4 — Validate
+
+After generation, run through this checklist:
+
+- [ ] Every imported package exists in the manifest
+- [ ] Every file referenced by an import exists in the tree
+- [ ] `.env.example` lists every env var used in code
+- [ ] `.gitignore` covers build artifacts and secrets
+- [ ] README has setup instructions that actually work
+- [ ] No hardcoded secrets, API keys, or passwords
+- [ ] At least one test file exists
+- [ ] Build/start command is documented and would work
+
+Run `scripts/validate_project.py` against the generated directory to catch common issues.
+
+## Examples
+
+### Example 1: Task Management API
+
+**Input spec:**
+> "Build me a task management API. Users can create, list, update, and delete tasks. Tasks have a title, description, status (todo/in-progress/done), and due date. Use FastAPI with SQLite. Add basic auth with API keys."
+
+**Output file tree:**
+```
+task-api/
+├── README.md
+├── .env.example              # API_KEY, DATABASE_URL
+├── .gitignore
+├── .github/workflows/ci.yml
+├── requirements.txt          # fastapi, uvicorn, sqlalchemy, pytest
+├── main.py                   # FastAPI app, CORS, lifespan
+├── models.py                 # SQLAlchemy Task model
+├── schemas.py                # Pydantic request/response schemas
+├── database.py               # SQLite engine + session
+├── auth.py                   # API key middleware
+├── routers/
+│   └── tasks.py              # CRUD endpoints
+└── tests/
+    └── test_tasks.py         # Smoke tests for each endpoint
+```
+
+### Example 2: Recipe Sharing Web App
+
+**Input spec:**
+> "I want a recipe sharing website. Users sign up, post recipes with ingredients and steps, browse other recipes, and save favorites. Use Next.js with Tailwind. Store data in PostgreSQL."
+
+**Output file tree:**
+```
+recipe-share/
+├── README.md
+├── .env.example              # DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL
+├── .gitignore
+├── .github/workflows/ci.yml
+├── package.json              # next, react, tailwindcss, prisma, next-auth
+├── tailwind.config.ts
+├── tsconfig.json
+├── next.config.ts
+├── prisma/
+│   └── schema.prisma         # User, Recipe, Ingredient, Favorite models
+├── src/
+│   ├── app/
+│   │   ├── layout.tsx
+│   │   ├── page.tsx          # Homepage — recipe feed
+│   │   ├── recipes/
+│   │   │   ├── page.tsx      # Browse recipes
+│   │   │   ├── [id]/page.tsx # Recipe detail
+│   │   │   └── new/page.tsx  # Create recipe form
+│   │   └── api/
+│   │       ├── auth/[...nextauth]/route.ts
+│   │       └── recipes/route.ts
+│   ├── components/
+│   │   ├── RecipeCard.tsx
+│   │   ├── RecipeForm.tsx
+│   │   └── Navbar.tsx
+│   └── lib/
+│       ├── prisma.ts
+│       └── auth.ts
+└── tests/
+    └── recipes.test.ts
+```
+
+### Example 3: CLI Expense Tracker
+
+**Input spec:**
+> "Python CLI tool for tracking expenses. Commands: add, list, summary, export-csv. Store in a local SQLite file. No external API."
+
+**Output file tree:**
+```
+expense-tracker/
+├── README.md
+├── .gitignore
+├── .github/workflows/ci.yml
+├── pyproject.toml
+├── src/
+│   └── expense_tracker/
+│       ├── __init__.py
+│       ├── cli.py            # argparse commands
+│       ├── database.py       # SQLite operations
+│       ├── models.py         # Expense dataclass
+│       └── formatters.py     # Table + CSV output
+└── tests/
+    └── test_cli.py
+```
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| **Placeholder code** — `// TODO: implement`, `pass`, empty function bodies | Every function has a real implementation. If complex, implement a working simplified version. |
+| **Stack override** — picking Next.js when the user said Flask | Always honor explicit tech preferences. Only infer when the user doesn't specify. |
+| **Missing .gitignore** — committing node_modules or .env | Generate stack-appropriate .gitignore as one of the first files. |
+| **Phantom imports** — importing packages not in the manifest | Cross-check every import against package.json / requirements.txt before finishing. |
+| **Over-engineering MVP** — adding Redis caching, rate limiting, WebSockets to a v1 | Build the minimum that works. The user can iterate. |
+| **Ignoring stated preferences** — user says "PostgreSQL" and you generate MongoDB | Parse the spec carefully. Explicit preferences are non-negotiable. |
+| **Missing env vars** — code reads `process.env.X` but `.env.example` doesn't list it | Every env var used in code must appear in `.env.example` with a comment. |
+| **No tests** — shipping a repo with zero test files | At minimum: one smoke test per API endpoint or one test per core function. |
+| **Hallucinated APIs** — generating code that calls library methods that don't exist | Stick to well-documented, stable APIs. When unsure, use the simplest approach. |
+
+## Validation Script
+
+### `scripts/validate_project.py`
+
+Checks a generated project directory for common issues:
+
+```bash
+# Validate a generated project
+python3 scripts/validate_project.py /path/to/generated-project
+
+# JSON output
+python3 scripts/validate_project.py /path/to/generated-project --format json
+```
+
+Checks performed:
+- README.md exists and is non-empty
+- .gitignore exists
+- .env.example exists (if code references env vars)
+- Package manifest exists (package.json, requirements.txt, go.mod, Cargo.toml, pubspec.yaml)
+- No .env file committed (secrets leak)
+- At least one test file exists
+- No TODO/FIXME placeholders in generated code
+
+## Progressive Enhancement
+
+For complex specs, generate in stages:
+
+1. **MVP** — Core feature only, working end-to-end
+2. **Auth** — Add authentication if requested
+3. **Polish** — Error handling, validation, loading states
+4. **Deploy** — Docker, CI, deploy config
+
+Ask the user after MVP: "Core is working. Want me to add auth/polish/deploy next, or iterate on what's here?"
+
+## Cross-References
+
+- Related: `product-team/saas-scaffolder` — SaaS-specific scaffolding (Next.js + Stripe + Auth)
+- Related: `engineering/spec-driven-workflow` — spec-first development methodology
+- Related: `engineering/database-designer` — database schema design patterns
+- Related: `engineering-team/senior-fullstack` — full-stack implementation patterns

package/product/ui-design-system/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: "ui-design-system"
+description: UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration.
+---
+
+# UI Design System
+
+Generate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.
+
+---
+
+## Table of Contents
+
+- [Trigger Terms](#trigger-terms)
+- [Workflows](#workflows)
+  - [Workflow 1: Generate Design Tokens](#workflow-1-generate-design-tokens)
+  - [Workflow 2: Create Component System](#workflow-2-create-component-system)
+  - [Workflow 3: Responsive Design](#workflow-3-responsive-design)
+  - [Workflow 4: Developer Handoff](#workflow-4-developer-handoff)
+- [Tool Reference](#tool-reference)
+- [Quick Reference Tables](#quick-reference-tables)
+- [Knowledge Base](#knowledge-base)
+
+---
+
+## Trigger Terms
+
+Use this skill when you need to:
+
+- "generate design tokens"
+- "create color palette"
+- "build typography scale"
+- "calculate spacing system"
+- "create design system"
+- "generate CSS variables"
+- "export SCSS tokens"
+- "set up component architecture"
+- "document component library"
+- "calculate responsive breakpoints"
+- "prepare developer handoff"
+- "convert brand color to palette"
+- "check WCAG contrast"
+- "build 8pt grid system"
+
+---
+
+## Workflows
+
+### Workflow 1: Generate Design Tokens
+
+**Situation:** You have a brand color and need a complete design token system.
+
+**Steps:**
+
+1. **Identify brand color and style**
+   - Brand primary color (hex format)
+   - Style preference: `modern` | `classic` | `playful`
+
+2. **Generate tokens using script**
+   ```bash
+   python scripts/design_token_generator.py "#0066CC" modern json
+   ```
+
+3. **Review generated categories**
+   - Colors: primary, secondary, neutral, semantic, surface
+   - Typography: fontFamily, fontSize, fontWeight, lineHeight
+   - Spacing: 8pt grid-based scale (0-64)
+   - Borders: radius, width
+   - Shadows: none through 2xl
+   - Animation: duration, easing
+   - Breakpoints: xs through 2xl
+
+4. **Export in target format**
+   ```bash
+   # CSS custom properties
+   python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css
+
+   # SCSS variables
+   python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
+
+   # JSON for Figma/tooling
+   python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
+   ```
+
+5. **Validate accessibility**
+   - Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)
+   - Verify semantic colors have contrast colors defined
+
+---
+
+### Workflow 2: Create Component System
+
+**Situation:** You need to structure a component library using design tokens.
+
+**Steps:**
+
+1. **Define component hierarchy**
+   - Atoms: Button, Input, Icon, Label, Badge
+   - Molecules: FormField, SearchBar, Card, ListItem
+   - Organisms: Header, Footer, DataTable, Modal
+   - Templates: DashboardLayout, AuthLayout
+
+2. **Map tokens to components**
+
+   | Component | Tokens Used |
+   |-----------|-------------|
+   | Button | colors, sizing, borders, shadows, typography |
+   | Input | colors, sizing, borders, spacing |
+   | Card | colors, borders, shadows, spacing |
+   | Modal | colors, shadows, spacing, z-index, animation |
+
+3. **Define variant patterns**
+
+   Size variants:
+   ```
+   sm: height 32px, paddingX 12px, fontSize 14px
+   md: height 40px, paddingX 16px, fontSize 16px
+   lg: height 48px, paddingX 20px, fontSize 18px
+   ```
+
+   Color variants:
+   ```
+   primary: background primary-500, text white
+   secondary: background neutral-100, text neutral-900
+   ghost: background transparent, text neutral-700
+   ```
+
+4. **Document component API**
+   - Props interface with types
+   - Variant options
+   - State handling (hover, active, focus, disabled)
+   - Accessibility requirements
+
+5. **Reference:** See `references/component-architecture.md`
+
+---
+
+### Workflow 3: Responsive Design
+
+**Situation:** You need breakpoints, fluid typography, or responsive spacing.
+
+**Steps:**
+
+1. **Define breakpoints**
+
+   | Name | Width | Target |
+   |------|-------|--------|
+   | xs | 0 | Small phones |
+   | sm | 480px | Large phones |
+   | md | 640px | Tablets |
+   | lg | 768px | Small laptops |
+   | xl | 1024px | Desktops |
+   | 2xl | 1280px | Large screens |
+
+2. **Calculate fluid typography**
+
+   Formula: `clamp(min, preferred, max)`
+
+   ```css
+   /* 16px to 24px between 320px and 1200px viewport */
+   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
+   ```
+
+   Pre-calculated scales:
+   ```css
+   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
+   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
+   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
+   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
+   ```
+
+3. **Set up responsive spacing**
+
+   | Token | Mobile | Tablet | Desktop |
+   |-------|--------|--------|---------|
+   | --space-md | 12px | 16px | 16px |
+   | --space-lg | 16px | 24px | 32px |
+   | --space-xl | 24px | 32px | 48px |
+   | --space-section | 48px | 80px | 120px |
+
+4. **Reference:** See `references/responsive-calculations.md`
+
+---
+
+### Workflow 4: Developer Handoff
+
+**Situation:** You need to hand off design tokens to development team.
+
+**Steps:**
+
+1. **Export tokens in required formats**
+   ```bash
+   # For CSS projects
+   python scripts/design_token_generator.py "#0066CC" modern css
+
+   # For SCSS projects
+   python scripts/design_token_generator.py "#0066CC" modern scss
+
+   # For JavaScript/TypeScript
+   python scripts/design_token_generator.py "#0066CC" modern json
+   ```
+
+2. **Prepare framework integration**
+
+   **React + CSS Variables:**
+   ```tsx
+   import './design-tokens.css';
+
+   <button className="btn btn-primary">Click</button>
+   ```
+
+   **Tailwind Config:**
+   ```javascript
+   const tokens = require('./design-tokens.json');
+
+   module.exports = {
+     theme: {
+       colors: tokens.colors,
+       fontFamily: tokens.typography.fontFamily
+     }
+   };
+   ```
+
+   **styled-components:**
+   ```typescript
+   import tokens from './design-tokens.json';
+
+   const Button = styled.button`
+     background: ${tokens.colors.primary['500']};
+     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
+   `;
+   ```
+
+3. **Sync with Figma**
+   - Install Tokens Studio plugin
+   - Import design-tokens.json
+   - Tokens sync automatically with Figma styles
+
+4. **Handoff checklist**
+   - [ ] Token files added to project
+   - [ ] Build pipeline configured
+   - [ ] Theme/CSS variables imported
+   - [ ] Component library aligned
+   - [ ] Documentation generated
+
+5. **Reference:** See `references/developer-handoff.md`
+
+---
+
+## Tool Reference
+
+### design_token_generator.py
+
+Generates complete design token system from brand color.
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| brand_color | Hex color | #0066CC | Primary brand color |
+| style | modern, classic, playful | modern | Design style preset |
+| format | json, css, scss, summary | json | Output format |
+
+**Examples:**
+
+```bash
+# Generate JSON tokens (default)
+python scripts/design_token_generator.py "#0066CC"
+
+# Classic style with CSS output
+python scripts/design_token_generator.py "#8B4513" classic css
+
+# Playful style summary view
+python scripts/design_token_generator.py "#FF6B6B" playful summary
+```
+
+**Output Categories:**
+
+| Category | Description | Key Values |
+|----------|-------------|------------|
+| colors | Color palettes | primary, secondary, neutral, semantic, surface |
+| typography | Font system | fontFamily, fontSize, fontWeight, lineHeight |
+| spacing | 8pt grid | 0-64 scale, semantic (xs-3xl) |
+| sizing | Component sizes | container, button, input, icon |
+| borders | Border values | radius (per style), width |
+| shadows | Shadow styles | none through 2xl, inner |
+| animation | Motion tokens | duration, easing, keyframes |
+| breakpoints | Responsive | xs, sm, md, lg, xl, 2xl |
+| z-index | Layer system | base through notification |
+
+---
+
+## Quick Reference Tables
+
+### Color Scale Generation
+
+| Step | Brightness | Saturation | Use Case |
+|------|------------|------------|----------|
+| 50 | 95% fixed | 30% | Subtle backgrounds |
+| 100 | 95% fixed | 38% | Light backgrounds |
+| 200 | 95% fixed | 46% | Hover states |
+| 300 | 95% fixed | 54% | Borders |
+| 400 | 95% fixed | 62% | Disabled states |
+| 500 | Original | 70% | Base/default color |
+| 600 | Original × 0.8 | 78% | Hover (dark) |
+| 700 | Original × 0.6 | 86% | Active states |
+| 800 | Original × 0.4 | 94% | Text |
+| 900 | Original × 0.2 | 100% | Headings |
+
+### Typography Scale (1.25x Ratio)
+
+| Size | Value | Calculation |
+|------|-------|-------------|
+| xs | 10px | 16 ÷ 1.25² |
+| sm | 13px | 16 ÷ 1.25¹ |
+| base | 16px | Base |
+| lg | 20px | 16 × 1.25¹ |
+| xl | 25px | 16 × 1.25² |
+| 2xl | 31px | 16 × 1.25³ |
+| 3xl | 39px | 16 × 1.25⁴ |
+| 4xl | 49px | 16 × 1.25⁵ |
+| 5xl | 61px | 16 × 1.25⁶ |
+
+### WCAG Contrast Requirements
+
+| Level | Normal Text | Large Text |
+|-------|-------------|------------|
+| AA | 4.5:1 | 3:1 |
+| AAA | 7:1 | 4.5:1 |
+
+Large text: ≥18pt regular or ≥14pt bold
+
+### Style Presets
+
+| Aspect | Modern | Classic | Playful |
+|--------|--------|---------|---------|
+| Font Sans | Inter | Helvetica | Poppins |
+| Font Mono | Fira Code | Courier | Source Code Pro |
+| Radius Default | 8px | 4px | 16px |
+| Shadows | Layered, subtle | Single layer | Soft, pronounced |
+
+---
+
+## Knowledge Base
+
+Detailed reference guides in `references/`:
+
+| File | Content |
+|------|---------|
+| `token-generation.md` | Color algorithms, HSV space, WCAG contrast, type scales |
+| `component-architecture.md` | Atomic design, naming conventions, props patterns |
+| `responsive-calculations.md` | Breakpoints, fluid typography, grid systems |
+| `developer-handoff.md` | Export formats, framework setup, Figma sync |
+
+---
+
+## Validation Checklist
+
+### Token Generation
+- [ ] Brand color provided in hex format
+- [ ] Style matches project requirements
+- [ ] All token categories generated
+- [ ] Semantic colors include contrast values
+
+### Component System
+- [ ] All sizes implemented (sm, md, lg)
+- [ ] All variants implemented (primary, secondary, ghost)
+- [ ] All states working (hover, active, focus, disabled)
+- [ ] Uses only design tokens (no hardcoded values)
+
+### Accessibility
+- [ ] Color contrast meets WCAG AA
+- [ ] Focus indicators visible
+- [ ] Touch targets ≥ 44×44px
+- [ ] Semantic HTML elements used
+
+### Developer Handoff
+- [ ] Tokens exported in required format
+- [ ] Framework integration documented
+- [ ] Design tool synced
+- [ ] Component documentation complete