shmakk 1.1.0 → 1.2.0

package/skills/design.md

@@ -0,0 +1,221 @@
+---
+name: design
+version: 1
+category: design
+---
+
+# Visual Design & Design Systems
+
+Build and audit design systems, design tokens, typography, color, spacing, component libraries, and CSS architecture.
+
+## When to use this skill
+
+- User wants to set up or extend a design system
+- User asks about design tokens, CSS variables, or theming
+- User wants consistent spacing, typography, or color usage across a project
+- User asks about Tailwind configuration, CSS architecture (BEM, ITCSS, utility-first)
+- User wants to add or support dark mode
+- User mentions Figma, Storybook, or component documentation
+- User wants to audit visual inconsistencies across a UI
+
+## Procedure
+
+### Step 1: Audit existing design decisions
+
+Before introducing anything new, map what already exists:
+```bash
+# Find CSS custom properties (design tokens)
+grep -rn "^  --" src/ --include="*.css" --include="*.scss" | head -30
+
+# Find hardcoded colors (potential tokens)
+grep -rn "#[0-9a-fA-F]\{3,6\}\|rgb(\|rgba(\|hsl(" src/ --include="*.css" --include="*.scss" --include="*.tsx" | head -20
+
+# Find hardcoded spacing (potential tokens)
+grep -rn "margin:\|padding:\|gap:" src/ --include="*.css" | grep -E "[0-9]+px" | head -20
+
+# Check Tailwind config
+cat tailwind.config.ts 2>/dev/null || cat tailwind.config.js 2>/dev/null
+```
+
+### Step 2: Design token architecture
+
+Tokens should follow a three-tier structure:
+1. **Primitive tokens** — raw values, no semantic meaning
+2. **Semantic tokens** — named by purpose, reference primitives
+3. **Component tokens** — specific to one component, reference semantic
+
+```css
+/* 1. Primitive tokens */
+:root {
+  --color-blue-500: #3b82f6;
+  --color-blue-600: #2563eb;
+  --space-4: 1rem;
+  --space-6: 1.5rem;
+  --radius-md: 0.375rem;
+}
+
+/* 2. Semantic tokens */
+:root {
+  --color-primary: var(--color-blue-500);
+  --color-primary-hover: var(--color-blue-600);
+  --space-button-padding-x: var(--space-4);
+  --radius-button: var(--radius-md);
+}
+
+/* 3. Component tokens (optional, for complex components) */
+.card {
+  --card-padding: var(--space-6);
+  --card-radius: var(--radius-md);
+}
+```
+
+### Step 3: Typography system
+
+A well-defined type scale has:
+- 5–8 size steps (following a ratio: 1.25, 1.333, or 1.5)
+- Defined line-height per size (larger text = tighter line-height)
+- Maximum content width: 60–75 characters per line (`max-width: 65ch`)
+- Correct font-weight usage (not just bold/normal)
+
+```css
+:root {
+  --font-size-xs:   0.75rem;   /* 12px */
+  --font-size-sm:   0.875rem;  /* 14px */
+  --font-size-base: 1rem;      /* 16px */
+  --font-size-lg:   1.125rem;  /* 18px */
+  --font-size-xl:   1.25rem;   /* 20px */
+  --font-size-2xl:  1.5rem;    /* 24px */
+  --font-size-3xl:  1.875rem;  /* 30px */
+  --font-size-4xl:  2.25rem;   /* 36px */
+}
+```
+
+Check font loading:
+```bash
+grep -rn "font-family\|@font-face\|font-display" src/ public/ --include="*.css" | head -10
+```
+
+### Step 4: Color system
+
+Every color system needs:
+1. **Brand palette**: primary, secondary, accent
+2. **Semantic colors**: success (green), warning (yellow/amber), danger (red), info (blue)
+3. **Neutral scale**: 8–12 steps from white to black (gray-50 through gray-950)
+4. **Surface colors**: background, foreground, border, overlay
+
+Contrast requirements (WCAG AA):
+- Normal text (< 18pt): ≥ 4.5:1
+- Large text (≥ 18pt or bold ≥ 14pt): ≥ 3:1
+- UI components and icons: ≥ 3:1
+
+```bash
+# Test contrast programmatically
+node -e "
+const l = (hex) => {
+  const r = parseInt(hex.slice(1,3),16)/255;
+  const g = parseInt(hex.slice(3,5),16)/255;
+  const b = parseInt(hex.slice(5,7),16)/255;
+  const toLinear = c => c <= 0.03928 ? c/12.92 : Math.pow((c+0.055)/1.055, 2.4);
+  return 0.2126*toLinear(r) + 0.7152*toLinear(g) + 0.0722*toLinear(b);
+};
+const contrast = (fg, bg) => {
+  const l1 = Math.max(l(fg), l(bg)), l2 = Math.min(l(fg), l(bg));
+  return ((l1 + 0.05) / (l2 + 0.05)).toFixed(2);
+};
+// Example:
+console.log('Contrast ratio:', contrast('#1e293b', '#f8fafc'));
+"
+```
+
+### Step 5: Spacing system
+
+Use a consistent scale. Options:
+- **4px base** (Tailwind default): 4, 8, 12, 16, 20, 24, 32, 40, 48, 64...
+- **8px base**: 8, 16, 24, 32, 48, 64, 96...
+
+Check for inconsistencies:
+```bash
+# Find spacing values not on the scale
+grep -rn "margin\|padding\|gap" src/ --include="*.css" --include="*.scss" | grep -E "[0-9]+(px)" | grep -vE "(0px|4px|8px|12px|16px|20px|24px|32px|40px|48px|64px|80px|96px)" | head -10
+```
+
+### Step 6: Dark mode
+
+If dark mode is needed:
+1. Use CSS custom properties (design tokens) — never hardcode colors
+2. Use `prefers-color-scheme` media query OR data attribute (`data-theme="dark"`)
+3. Every semantic token needs a light and dark value
+
+```css
+:root {
+  --color-background: #ffffff;
+  --color-foreground: #0f172a;
+  --color-surface: #f8fafc;
+  --color-border: #e2e8f0;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-background: #0f172a;
+    --color-foreground: #f8fafc;
+    --color-surface: #1e293b;
+    --color-border: #334155;
+  }
+}
+```
+
+### Step 7: Component documentation (Storybook)
+
+For any component with variants:
+```bash
+npx storybook init  # if not set up
+npm run storybook   # start dev server
+```
+
+Every component story should cover:
+- Default state
+- All variants (size, color, style)
+- Interactive states (hover, focus, active, disabled)
+- Edge cases (long text, empty content, error state)
+
+## Common patterns
+
+### Tailwind: extend the theme, don't override
+```ts
+// tailwind.config.ts
+export default {
+  theme: {
+    extend: {  // ← extend, not replace
+      colors: {
+        brand: { 500: '#6366f1', 600: '#4f46e5' },
+      },
+      fontFamily: {
+        sans: ['Inter var', 'system-ui', 'sans-serif'],
+      },
+    },
+  },
+}
+```
+
+### CSS custom properties for theming
+```css
+/* Use in components */
+.button-primary {
+  background: var(--color-primary);
+  color: var(--color-on-primary);
+  padding: var(--space-button-padding-y) var(--space-button-padding-x);
+  border-radius: var(--radius-button);
+}
+```
+
+## Red flags to report
+
+- Hardcoded hex colors in component files (should be token references)
+- Multiple slightly-different grays with no systematic relationship
+- Spacing values that don't follow any grid (e.g., 7px, 11px, 22px)
+- No dark mode support despite the project targeting multiple contexts
+- Font loaded without `font-display: swap` (causes invisible text while loading)
+- Text color that doesn't meet 4.5:1 contrast on its background
+- No Storybook or isolated component documentation for a UI library
+- Design decisions made in multiple places (no single source of truth)
+- CSS specificity wars — overrides piled on overrides instead of a clean architecture

package/skills/dev-acquire-codebase-knowledge.md

@@ -0,0 +1,175 @@
+---
+name: acquire-codebase-knowledge
+description: 'Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase. Trigger for prompts like "map this codebase", "document this architecture", "onboard me to this repo", or "create codebase docs". Do not trigger for routine feature implementation, bug fixes, or narrow code edits unless the user asks for repository-level discovery.'
+license: MIT
+compatibility: 'Cross-platform. Requires Python 3.8+ and git. Run scripts/scan.py from the target project root.'
+metadata:
+  version: "1.3"
+  enhancements:
+    - Multi-language manifest detection (25+ languages supported)
+    - CI/CD pipeline detection (10+ platforms)
+    - Container & orchestration detection
+    - Code metrics by language
+    - Security & compliance config detection
+    - Performance testing markers
+argument-hint: 'Optional: specific area to focus on, e.g. "architecture only", "testing and concerns"'
+category: dev
+---
+
+# Acquire Codebase Knowledge
+
+Produces seven populated documents in `docs/codebase/` covering everything needed to work effectively on the project. Only document what is verifiable from files or terminal output — never infer or assume.
+
+## Output Contract (Required)
+
+Before finishing, all of the following must be true:
+
+1. Exactly these files exist in `docs/codebase/`: `STACK.md`, `STRUCTURE.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `INTEGRATIONS.md`, `TESTING.md`, `CONCERNS.md`.
+2. Every claim is traceable to source files, config, or terminal output.
+3. Unknowns are marked as `[TODO]`; intent-dependent decisions are marked `[ASK USER]`.
+4. Every document includes a short "evidence" list with concrete file paths.
+5. Final response includes numbered `[ASK USER]` questions and intent-vs-reality divergences.
+
+## Workflow
+
+Copy and track this checklist:
+
+```
+- [ ] Phase 1: Run scan, read intent documents
+- [ ] Phase 2: Investigate each documentation area
+- [ ] Phase 3: Populate all seven docs in docs/codebase/
+- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items
+```
+
+## Focus Area Mode
+
+If the user supplies a focus area (for example: "architecture only" or "testing and concerns"):
+
+1. Always run Phase 1 in full.
+2. Fully complete focus-area documents first.
+3. For non-focus documents not yet analyzed, keep required sections present and mark unknowns as `[TODO]`.
+4. Still run the Phase 4 validation loop on all seven documents before final output.
+
+### Phase 1: Scan and Read Intent
+
+1. Run the scan script from the target project root:
+   ```bash
+   python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt
+   ```
+   Where `$SKILL_ROOT` is the absolute path to the skill folder. Works on Windows, macOS, and Linux.
+
+   **Quick start:** If you have the path inline:
+   ```bash
+   python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt
+   ```
+
+2. Search for `PRD`, `TRD`, `README`, `ROADMAP`, `SPEC`, `DESIGN` files and read them.
+3. Summarise the stated project intent before reading any source code.
+
+### Phase 2: Investigate
+
+Use the scan output to answer questions for each of the seven templates. Load [`references/inquiry-checkpoints.md`](references/inquiry-checkpoints.md) for the full per-template question list.
+
+If the stack is ambiguous (multiple manifest files, unfamiliar file types, no `package.json`), load [`references/stack-detection.md`](references/stack-detection.md).
+
+### Phase 3: Populate Templates
+
+Copy each template from `assets/templates/` into `docs/codebase/`. Fill in this order:
+
+1. [STACK.md](assets/templates/STACK.md) — language, runtime, frameworks, all dependencies
+2. [STRUCTURE.md](assets/templates/STRUCTURE.md) — directory layout, entry points, key files
+3. [ARCHITECTURE.md](assets/templates/ARCHITECTURE.md) — layers, patterns, data flow
+4. [CONVENTIONS.md](assets/templates/CONVENTIONS.md) — naming, formatting, error handling, imports
+5. [INTEGRATIONS.md](assets/templates/INTEGRATIONS.md) — external APIs, databases, auth, monitoring
+6. [TESTING.md](assets/templates/TESTING.md) — frameworks, file organization, mocking strategy
+7. [CONCERNS.md](assets/templates/CONCERNS.md) — tech debt, bugs, security risks, perf bottlenecks
+
+Use `[TODO]` for anything that cannot be determined from code. Use `[ASK USER]` where the right answer requires team intent.
+
+### Phase 4: Validate, Repair, Verify
+
+Run this mandatory validation loop before finalizing:
+
+1. Validate each doc against `references/inquiry-checkpoints.md`.
+2. For each non-trivial claim, confirm at least one evidence reference exists.
+3. If any required section is missing or unsupported:
+  - Fix the document.
+  - Re-run validation.
+4. Repeat until all seven docs pass.
+
+Then present a summary of all seven documents, list every `[ASK USER]` item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.
+
+Validation pass criteria:
+
+- No unsupported claims.
+- No empty required sections.
+- Unknowns use `[TODO]` rather than assumptions.
+- Team-intent gaps are explicitly marked `[ASK USER]`.
+
+---
+
+## Gotchas
+
+**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
+
+**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
+
+**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
+
+**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.
+
+**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.
+
+**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent, e.g. `[tool.poetry.dependencies]`) runs in production. Document linters, formatters, and test frameworks separately as dev tooling.
+
+**Test TODOs ≠ production debt:** TODOs inside `test/`, `tests/`, `__tests__/`, or `spec/` are coverage gaps, not production technical debt. Separate them in `CONCERNS.md`.
+
+**High-churn files = fragile areas:** Files appearing most in recent git history have the highest modification rate and likely hidden complexity. Always note them in `CONCERNS.md`.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do instead |
+|---------|--------------|
+| "Uses Clean Architecture with Domain/Data layers." (when no such directories exist) | State only what directory structure actually shows. |
+| "This is a Next.js project." (without checking `package.json`) | Check `dependencies` first. State what's actually there. |
+| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |
+| Document `dist/` or `build/` naming patterns as conventions | Source files only. |
+
+---
+
+## Enhanced Scan Output Sections
+
+The `scan.py` script now produce the following sections in addition to the original output:
+
+- **CODE METRICS** — Total files, lines of code by language, largest files (complexity signals)
+- **CI/CD PIPELINES** — Detected GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.
+- **CONTAINERS & ORCHESTRATION** — Docker, Docker Compose, Kubernetes, Vagrant configs
+- **SECURITY & COMPLIANCE** — Snyk, Dependabot, SECURITY.md, SBOM, security policies
+- **PERFORMANCE & TESTING** — Benchmark configs, profiling markers, load testing tools
+
+Use these sections during Phase 2 to inform investigation questions and identify tool-specific patterns.
+
+---
+
+## Bundled Assets
+
+| Asset | When to load |
+|-------|-------------|
+| [`scripts/scan.py`](scripts/scan.py) | Phase 1 — run first, before reading any code (Python 3.8+ required) |
+
+| [`references/inquiry-checkpoints.md`](references/inquiry-checkpoints.md) | Phase 2 — load for per-template investigation questions |
+| [`references/stack-detection.md`](references/stack-detection.md) | Phase 2 — only if stack is ambiguous |
+| [`assets/templates/STACK.md`](assets/templates/STACK.md) | Phase 3 step 1 |
+| [`assets/templates/STRUCTURE.md`](assets/templates/STRUCTURE.md) | Phase 3 step 2 |
+| [`assets/templates/ARCHITECTURE.md`](assets/templates/ARCHITECTURE.md) | Phase 3 step 3 |
+| [`assets/templates/CONVENTIONS.md`](assets/templates/CONVENTIONS.md) | Phase 3 step 4 |
+| [`assets/templates/INTEGRATIONS.md`](assets/templates/INTEGRATIONS.md) | Phase 3 step 5 |
+| [`assets/templates/TESTING.md`](assets/templates/TESTING.md) | Phase 3 step 6 |
+| [`assets/templates/CONCERNS.md`](assets/templates/CONCERNS.md) | Phase 3 step 7 |
+
+Template usage mode:
+
+- Default mode: complete only the "Core Sections (Required)" in each template.
+- Extended mode: add optional sections only when the repo complexity justifies them.

package/skills/dev-add-educational-comments.md

@@ -0,0 +1,129 @@
+---
+name: add-educational-comments
+description: 'Add educational comments to the file specified, or prompt asking for file to comment if one is not provided.'
+category: dev
+---
+
+# Add Educational Comments
+
+Add educational comments to code files so they become effective learning resources. When no file is provided, request one and offer a numbered list of close matches for quick selection.
+
+## Role
+
+You are an expert educator and technical writer. You can explain programming topics to beginners, intermediate learners, and advanced practitioners. You adapt tone and detail to match the user's configured knowledge levels while keeping guidance encouraging and instructional.
+
+- Provide foundational explanations for beginners
+- Add practical insights and best practices for intermediate users
+- Offer deeper context (performance, architecture, language internals) for advanced users
+- Suggest improvements only when they meaningfully support understanding
+- Always obey the **Educational Commenting Rules**
+
+## Objectives
+
+1. Transform the provided file by adding educational comments aligned with the configuration.
+2. Maintain the file's structure, encoding, and build correctness.
+3. Increase the total line count by **125%** using educational comments only (up to 400 new lines). For files already processed with this prompt, update existing notes instead of reapplying the 125% rule.
+
+### Line Count Guidance
+
+- Default: add lines so the file reaches 125% of its original length.
+- Hard limit: never add more than 400 educational comment lines.
+- Large files: when the file exceeds 1,000 lines, aim for no more than 300 educational comment lines.
+- Previously processed files: revise and improve current comments; do not chase the 125% increase again.
+
+## Educational Commenting Rules
+
+### Encoding and Formatting
+
+- Determine the file's encoding before editing and keep it unchanged.
+- Use only characters available on a standard QWERTY keyboard.
+- Do not insert emojis or other special symbols.
+- Preserve the original end-of-line style (LF or CRLF).
+- Keep single-line comments on a single line.
+- Maintain the indentation style required by the language (Python, Haskell, F#, Nim, Cobra, YAML, Makefiles, etc.).
+- When instructed with `Line Number Referencing = yes`, prefix each new comment with `Note <number>` (e.g., `Note 1`).
+
+### Content Expectations
+
+- Focus on lines and blocks that best illustrate language or platform concepts.
+- Explain the "why" behind syntax, idioms, and design choices.
+- Reinforce previous concepts only when it improves comprehension (`Repetitiveness`).
+- Highlight potential improvements gently and only when they serve an educational purpose.
+- If `Line Number Referencing = yes`, use note numbers to connect related explanations.
+
+### Safety and Compliance
+
+- Do not alter namespaces, imports, module declarations, or encoding headers in a way that breaks execution.
+- Avoid introducing syntax errors (for example, Python encoding errors per [PEP 263](https://peps.python.org/pep-0263/)).
+- Input data as if typed on the user's keyboard.
+
+## Workflow
+
+1. **Confirm Inputs** – Ensure at least one target file is provided. If missing, respond with: `Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.`
+2. **Identify File(s)** – If multiple matches exist, present an ordered list so the user can choose by number or name.
+3. **Review Configuration** – Combine the prompt defaults with user-specified values. Interpret obvious typos (e.g., `Line Numer`) using context.
+4. **Plan Comments** – Decide which sections of the code best support the configured learning goals.
+5. **Add Comments** – Apply educational comments following the configured detail, repetitiveness, and knowledge levels. Respect indentation and language syntax.
+6. **Validate** – Confirm formatting, encoding, and syntax remain intact. Ensure the 125% rule and line limits are satisfied.
+
+## Configuration Reference
+
+### Properties
+
+- **Numeric Scale**: `1-3`
+- **Numeric Sequence**: `ordered` (higher numbers represent higher knowledge or intensity)
+
+### Parameters
+
+- **File Name** (required): Target file(s) for commenting.
+- **Comment Detail** (`1-3`): Depth of each explanation (default `2`).
+- **Repetitiveness** (`1-3`): Frequency of revisiting similar concepts (default `2`).
+- **Educational Nature**: Domain focus (default `Computer Science`).
+- **User Knowledge** (`1-3`): General CS/SE familiarity (default `2`).
+- **Educational Level** (`1-3`): Familiarity with the specific language or framework (default `1`).
+- **Line Number Referencing** (`yes/no`): Prepend comments with note numbers when `yes` (default `yes`).
+- **Nest Comments** (`yes/no`): Whether to indent comments inside code blocks (default `yes`).
+- **Fetch List**: Optional URLs for authoritative references.
+
+If a configurable element is missing, use the default value. When new or unexpected options appear, apply your **Educational Role** to interpret them sensibly and still achieve the objective.
+
+### Default Configuration
+
+- File Name
+- Comment Detail = 2
+- Repetitiveness = 2
+- Educational Nature = Computer Science
+- User Knowledge = 2
+- Educational Level = 1
+- Line Number Referencing = yes
+- Nest Comments = yes
+- Fetch List:
+  - <https://peps.python.org/pep-0263/>
+
+## Examples
+
+### Missing File
+
+```text
+[user]
+> /add-educational-comments
+[agent]
+> Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.
+```
+
+### Custom Configuration
+
+```text
+[user]
+> /add-educational-comments #file:output_name.py Comment Detail = 1, Repetitiveness = 1, Line Numer = no
+```
+
+Interpret `Line Numer = no` as `Line Number Referencing = no` and adjust behavior accordingly while maintaining all rules above.
+
+## Final Checklist
+
+- Ensure the transformed file satisfies the 125% rule without exceeding limits.
+- Keep encoding, end-of-line style, and indentation unchanged.
+- Confirm all educational comments follow the configuration and the **Educational Commenting Rules**.
+- Provide clarifying suggestions only when they aid learning.
+- When a file has been processed before, refine existing comments instead of expanding line count.

package/skills/dev-add-model-descriptions.md

@@ -0,0 +1,74 @@
+---
+name: add-model-descriptions
+description: Add descriptions for new models from the HuggingFace router to chat-ui configuration. Use when new models are released on the router and need descriptions added to prod.yaml and dev.yaml. Triggers on requests like "add new model descriptions", "update models from router", "sync models", or when explicitly invoking /add-model-descriptions.
+category: dev
+---
+
+# Add Model Descriptions
+
+Add descriptions for new models available in the HuggingFace router to chat-ui's prod.yaml and dev.yaml.
+
+## Workflow
+
+1. **Fetch models from router**
+
+   ```
+   WebFetch https://router.huggingface.co/v1/models
+   ```
+
+   Extract all model IDs from the response.
+
+2. **Read current configuration**
+
+   - Read `chart/env/prod.yaml`
+   - Extract model IDs from the `MODELS` JSON array in `envVars`
+
+3. **Identify missing models**
+   Compare router models with prod.yaml. Missing = in router but not in prod.yaml.
+
+4. **Research each missing model**
+   For each missing model, search the web for its specifications:
+
+   - Model architecture (dense, MoE, parameters)
+   - Key capabilities (coding, reasoning, vision, multilingual, etc.)
+   - Target use cases
+
+5. **Write descriptions**
+   Match existing style:
+
+   - 8-12 words
+   - Sentence fragments (no period needed)
+   - No articles ("a", "the") unless necessary
+   - Focus on: architecture, specialization, key capability
+
+   Examples:
+
+   - `"Flagship GLM MoE for coding, reasoning, and agentic tool use."`
+   - `"MoE agent model with multilingual coding and fast outputs."`
+   - `"Vision-language Qwen for documents, GUI agents, and visual reasoning."`
+   - `"Mobile agent for multilingual Android device automation."`
+
+6. **Update both files**
+   Add new models at the TOP of the MODELS array in:
+
+   - `chart/env/prod.yaml`
+   - `chart/env/dev.yaml`
+
+   Format:
+
+   ```json
+   { "id": "org/model-name", "description": "Description here." }
+   ```
+
+7. **Commit changes**
+   ```
+   git add chart/env/prod.yaml chart/env/dev.yaml
+   git commit -m "feat: add descriptions for N new models from router"
+   ```
+
+## Notes
+
+- FP8 variants: describe as "FP8 [base model] for efficient inference with [key capability]"
+- Vision models: mention "vision-language" and key visual tasks
+- Agent models: mention "agent" and automation capabilities
+- Regional models: mention language focus (e.g., "European multilingual", "Southeast Asian")

package/skills/dev-adr-review.md

@@ -0,0 +1,56 @@
+---
+name: adr-review
+description: Review code changes against accepted ADRs for compliance violations
+argument-hint: "[--branch BRANCH]"
+allowed-tools: mcp__claude-flow__agentdb_hierarchical-query mcp__claude-flow__agentdb_causal-query mcp__claude-flow__memory_search Bash Read Grep Glob
+category: dev
+---
+
+# ADR Review
+
+Review code changes against accepted Architecture Decision Records to detect violations, drift, and non-compliance.
+
+## When to use
+
+Before merging a PR, after significant code changes, or as part of a periodic compliance check. Use this to ensure code changes respect the architectural decisions the team has agreed upon.
+
+## Steps
+
+1. **Get diff** -- Run `git diff main...HEAD --name-only` (or the specified branch) to list changed files. Then run `git diff main...HEAD` to get the full diff content.
+
+2. **Find relevant ADRs** -- For each changed file:
+   - `Grep` the file for ADR references (`ADR-\d+`)
+   - `Grep` `docs/adr/` for ADRs that mention the changed file paths or modules
+   - Call `mcp__claude-flow__memory_search` with the file path and change summary to find semantically related ADRs
+
+3. **Load ADR content** -- `Read` each relevant ADR file. Focus on:
+   - The **Decision** section (what was decided)
+   - The **Status** (only enforce "accepted" ADRs)
+   - The **Consequences** (expected constraints)
+
+4. **Check for violations** -- Analyze each changed file against its relevant ADRs:
+   - Does the code change contradict an accepted decision?
+   - Does it use a technology/pattern that an ADR explicitly rejected?
+   - Does it modify a module in a way the ADR's consequences warned against?
+   - Is the code referencing a deprecated or superseded ADR?
+
+5. **Query relationship graph** -- Call `mcp__claude-flow__agentdb_causal-query` to check if any referenced ADRs have been superseded. If so, flag that the code references an outdated decision.
+
+6. **Report** -- Present findings as a compliance report:
+   ```
+   ## ADR Compliance Report
+
+   ### Violations
+   - [ ] <file>:<line> — violates ADR-NNN: <reason>
+
+   ### Warnings
+   - [!] <file> references superseded ADR-NNN (replaced by ADR-MMM)
+
+   ### Compliant
+   - [x] <file> — consistent with ADR-NNN
+
+   ### Unlinked Changes
+   - [?] <file> — no ADR coverage (consider creating one)
+   ```
+
+7. **Suggest actions** -- For each violation, suggest whether to update the code or propose a new ADR to supersede the violated one.

package/skills/dev-boost-prompt.md

@@ -0,0 +1,26 @@
+---
+name: boost-prompt
+description: 'Interactive prompt refinement workflow: interrogates scope, deliverables, constraints; copies final markdown to clipboard; never writes code. Requires the Joyride extension.'
+category: dev
+---
+
+You are an AI assistant designed to help users create high-quality, detailed task prompts. DO NOT WRITE ANY CODE.
+
+Your goal is to iteratively refine the user’s prompt by:
+
+- Understanding the task scope and objectives
+- At all times when you need clarification on details, ask specific questions to the user using the `joyride_request_human_input` tool.
+- Defining expected deliverables and success criteria
+- Perform project explorations, using available tools, to further your understanding of the task
+- Clarifying technical and procedural requirements
+- Organizing the prompt into clear sections or steps
+- Ensuring the prompt is easy to understand and follow
+
+After gathering sufficient information, produce the improved prompt as markdown, use Joyride to place the markdown on the system clipboard, as well as typing it out in the chat. Use this Joyride code for clipboard operations:
+
+```clojure
+(require '["vscode" :as vscode])
+(vscode/env.clipboard.writeText "your-markdown-text-here")
+```
+
+Announce to the user that the prompt is available on the clipboard, and also ask the user if they want any changes or additions. Repeat the copy + chat + ask after any revisions of the prompt.