arkaos 5.2.0 → 5.4.0

package/departments/brand/skills/design-dna/references/generation-guide.md

@@ -0,0 +1,209 @@
+# Generation Guide
+
+How to use a completed Design DNA JSON to generate designs in Phase 3. Covers all three dimensions.
+
+## Priority Order
+
+When generating a design from DNA JSON + content:
+
+1. **Color & Typography** — define 80% of visual identity
+2. **Spacing & Layout** — structural rhythm
+3. **Shape & Elevation** — surface treatment
+4. **Design Style qualitative fields** — mood, personality, composition approach
+5. **Visual Effects** — special rendering layer (Canvas, WebGL, shaders, etc.)
+6. **Motion & Interaction** — enhance after static layout and effects are solid
+
+## Dimension 1: design_system → Code
+
+### Tailwind CSS / Utility-First
+```
+color.primary.hex        → --color-primary / bg-[hex]
+typography.font_families → font-family config
+spacing.scale            → spacing config values
+shape.border_radius      → rounded-{sm|md|lg|full}
+elevation.levels         → shadow-{sm|md|lg}
+```
+
+### Plain CSS / CSS Variables
+Generate a `:root` block with all design tokens:
+```css
+:root {
+  --color-primary: {color.primary.hex};
+  --color-secondary: {color.secondary.hex};
+  --color-accent: {color.accent.hex};
+  --font-heading: {typography.font_families.heading};
+  --font-body: {typography.font_families.body};
+  --radius-sm: {shape.border_radius.small};
+  --radius-md: {shape.border_radius.medium};
+  --radius-lg: {shape.border_radius.large};
+  --shadow-low: {elevation.levels.low};
+  --shadow-med: {elevation.levels.medium};
+  --shadow-high: {elevation.levels.high};
+  --ease: {motion.easing};
+  --duration-micro: {motion.duration_scale.micro};
+  --duration-normal: {motion.duration_scale.normal};
+  --duration-macro: {motion.duration_scale.macro};
+  /* ... map all tokens */
+}
+```
+
+### Component Decisions
+- `components.button_style` → button classes and variants
+- `components.card_style` → card container treatment
+- `components.navigation_pattern` → nav component choice
+- `interaction_feel.hover_behavior` → :hover / :focus states
+- `motion.easing` + `motion.duration_scale` → transition properties
+
+## Dimension 2: design_style → Subjective Decisions
+
+| DNA Field | Guides |
+|---|---|
+| aesthetic.mood | Overall emotional feeling — warm tones, cool precision, etc. |
+| visual_language.whitespace_usage | padding/margin generosity |
+| visual_language.contrast_level | How much elements pop vs. blend |
+| composition.hierarchy_method | What tool to use for emphasis |
+| composition.balance_type | Symmetric layout vs. dynamic asymmetry |
+| imagery.graphic_elements | Decorative SVGs, gradients, patterns |
+| brand_voice_in_ui.tone | Microcopy phrasing |
+| interaction_feel.microinteraction_density | How many hover/click effects |
+
+## Dimension 3: visual_effects → Special Rendering
+
+### Technology Selection by Performance Tier
+
+| Tier | Technologies | When to Use |
+|---|---|---|
+| **lightweight** | CSS animations, SVG SMIL, vanilla JS | `overview.performance_tier` = "lightweight" |
+| **medium** | Canvas 2D, GSAP, Lottie, anime.js | `overview.performance_tier` = "medium" |
+| **heavy** | Three.js, custom GLSL, Pixi.js, WebGL | `overview.performance_tier` = "heavy" |
+
+### Implementation Patterns
+
+#### Background Effects
+```
+"none"              → skip
+"gradient-animation" → CSS @keyframes on linear-gradient or conic-gradient
+"noise-field"       → Canvas 2D with Perlin/simplex noise
+"mesh-gradient"     → SVG <mesh> or canvas interpolation
+"video-bg"          → <video autoplay muted loop> with poster fallback
+"generative-art"    → Canvas 2D or WebGL generative algorithms
+```
+
+#### Particle Systems
+When `particle_systems.enabled: true`:
+- For `count` < 100 and no complex physics → vanilla JS + Canvas 2D
+- For `count` >= 100 or complex interaction → consider Pixi.js or Three.js Points
+- Map `interaction` ("mouse-repel", "mouse-attract") to pointer event handlers
+- Use `requestAnimationFrame` loop; include destroy/cleanup on unmount
+
+#### 3D Elements
+When `3d_elements.enabled: true`:
+- Default to Three.js unless DNA specifies otherwise
+- Apply `lighting`, `camera`, `materials` from params
+- Add `post_processing` effects via EffectComposer
+- Handle resize with `ResizeObserver`
+- Load via CDN: `https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js`
+
+#### Shader Effects
+When `shader_effects.enabled: true`:
+- Create vertex/fragment shaders based on `type`
+- Pass `uniforms` from params (time, resolution, mouse position)
+- For "noise-distortion": use noise functions matching `noise_type`
+- Animate via `requestAnimationFrame` updating `u_time` uniform
+
+#### Scroll Effects
+- **Parallax**: Use `transform: translateY()` with scroll offset × layer speed
+- **Scroll-triggered**: Use `IntersectionObserver` with `threshold` array
+- **Scrub behavior**: If "scrubbed", animation progress = scroll progress. If "triggered", play once on enter.
+
+#### Text Effects
+```
+"split-letter-animate" → Split text into <span> per char/word, stagger CSS animation
+"typewriter"           → CSS steps() or JS interval revealing chars
+"glitch"               → Layered clip-path + color offset animation
+"gradient-fill"        → background-clip: text with animated gradient
+"3d-extrude"           → text-shadow stack or WebGL text geometry
+```
+
+#### Cursor Effects
+When `cursor_effects.enabled: true`:
+- Hide default cursor: `cursor: none`
+- Create custom cursor element following `pointermove`
+- "magnetic-buttons": Apply transform pull on hover proximity
+- "spotlight": Radial gradient mask following cursor
+- "trail": Spawn fading elements on move
+
+#### Glassmorphism / Neumorphism
+```
+"glass"             → backdrop-filter: blur({blur_radius}); background: rgba(..., {transparency})
+"neumorphic-light"  → Dual box-shadow (light + dark offset) on light bg
+"neumorphic-dark"   → Dual box-shadow (inverted) on dark bg
+"frosted-layers"    → Stacked blur layers with varying opacity
+```
+
+#### Canvas Drawings
+When `canvas_drawings.enabled: true`:
+- Initialize canvas with `width/height` matching container
+- Use `draw_method` to select rendering approach
+- Animate with `requestAnimationFrame`
+- Handle `responsiveness` via ResizeObserver
+
+#### SVG Animations
+When `svg_animations.enabled: true`:
+- "path-draw": Animate `stroke-dashoffset` from path length to 0
+- "morph-shapes": Interpolate `d` attribute between two paths
+- "stroke-animation": Animate stroke properties (dasharray, width, color)
+
+### Fallback Strategy
+
+Always implement the fallback defined in `overview.fallback_strategy`:
+
+```js
+// Example: reduce to CSS on low-end devices
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const isLowEnd = navigator.hardwareConcurrency <= 2;
+if (prefersReduced || isLowEnd) {
+  // Apply fallback: static CSS version, disable canvas/WebGL
+}
+```
+
+## Output Format
+
+Generate output as a single self-contained HTML file with inline CSS and JS (unless user specifies a framework). Include:
+
+1. CSS custom properties block from `design_system` tokens
+2. Component styles from `design_system.components` + `design_style`
+3. Layout structure per `design_system.layout`
+4. Content populated from user-provided content
+5. Visual effects implemented per `visual_effects` specification
+6. Animations/transitions if `design_system.motion.philosophy` is not "none"
+7. Fallback handling for effects
+
+For heavy effects requiring external libraries, load via CDN `<script>` tags:
+```html
+<!-- Three.js -->
+<script type="importmap">{"imports":{"three":"https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js"}}</script>
+
+<!-- GSAP -->
+<script src="https://cdn.jsdelivr.net/npm/gsap@latest/dist/gsap.min.js"></script>
+
+<!-- Lottie -->
+<script src="https://cdn.jsdelivr.net/npm/lottie-web@latest/build/player/lottie.min.js"></script>
+```
+
+## Quality Checks
+
+Before delivering, verify:
+- [ ] Every color in output traces back to DNA palette
+- [ ] Font families match DNA specification
+- [ ] Spacing rhythm matches DNA scale
+- [ ] Border radius matches DNA shape tokens
+- [ ] Overall mood matches `design_style.aesthetic.mood`
+- [ ] Component patterns match DNA `components` descriptions
+- [ ] Contrast ratios meet WCAG AA minimum (4.5:1 body text, 3:1 large text)
+- [ ] Visual effects match `visual_effects` specification (type, technology, params)
+- [ ] Fallback strategy is implemented for effects
+- [ ] `prefers-reduced-motion` is respected
+- [ ] No effects render when their `enabled` flag is `false`
+- [ ] Canvas/WebGL contexts are properly sized and handle resize
+- [ ] Animation loops use `requestAnimationFrame` (no `setInterval`)

package/departments/brand/skills/design-dna/references/schema.md

@@ -0,0 +1,366 @@
+# Design DNA Schema
+
+Three-dimensional design profile:
+- **design_system** — measurable tokens
+- **design_style** — qualitative perception
+- **visual_effects** — special rendering such as Canvas, WebGL, 3D, particles, shaders, scroll effects, cursor effects, SVG animation, and glassmorphism
+
+Every field below must appear in the final JSON output.
+
+## Top-Level Structure
+
+### `meta`
+- `name`
+- `description`
+- `source_references`
+- `created_at`
+
+### `design_system`
+The structural and measurable layer.
+
+#### `design_system.color`
+- `palette_type`
+- `primary.hex`
+- `primary.role`
+- `secondary.hex`
+- `secondary.role`
+- `accent.hex`
+- `accent.role`
+- `neutral.scale`
+- `neutral.usage`
+- `semantic.success`
+- `semantic.warning`
+- `semantic.error`
+- `semantic.info`
+- `surface.background`
+- `surface.card`
+- `surface.elevated`
+- `contrast_strategy`
+
+#### `design_system.typography`
+- `type_scale.display.size`
+- `type_scale.display.weight`
+- `type_scale.display.line_height`
+- `type_scale.display.tracking`
+- `type_scale.heading_1.size`
+- `type_scale.heading_1.weight`
+- `type_scale.heading_1.line_height`
+- `type_scale.heading_1.tracking`
+- `type_scale.heading_2.size`
+- `type_scale.heading_2.weight`
+- `type_scale.heading_2.line_height`
+- `type_scale.heading_2.tracking`
+- `type_scale.heading_3.size`
+- `type_scale.heading_3.weight`
+- `type_scale.heading_3.line_height`
+- `type_scale.heading_3.tracking`
+- `type_scale.body.size`
+- `type_scale.body.weight`
+- `type_scale.body.line_height`
+- `type_scale.body.tracking`
+- `type_scale.body_small.size`
+- `type_scale.body_small.weight`
+- `type_scale.body_small.line_height`
+- `type_scale.body_small.tracking`
+- `type_scale.caption.size`
+- `type_scale.caption.weight`
+- `type_scale.caption.line_height`
+- `type_scale.caption.tracking`
+- `type_scale.overline.size`
+- `type_scale.overline.weight`
+- `type_scale.overline.line_height`
+- `type_scale.overline.tracking`
+- `font_families.heading`
+- `font_families.body`
+- `font_families.mono`
+- `font_style_notes`
+
+#### `design_system.spacing`
+- `base_unit`
+- `scale`
+- `content_density`
+- `section_rhythm`
+
+#### `design_system.layout`
+- `grid_system`
+- `max_content_width`
+- `columns`
+- `gutter`
+- `breakpoints`
+- `alignment_tendency`
+
+#### `design_system.shape`
+- `border_radius.small`
+- `border_radius.medium`
+- `border_radius.large`
+- `border_radius.pill`
+- `border_usage`
+- `divider_style`
+
+#### `design_system.elevation`
+- `shadow_style`
+- `levels.low`
+- `levels.medium`
+- `levels.high`
+- `depth_cues`
+
+#### `design_system.iconography`
+- `style`
+- `stroke_weight`
+- `size_scale`
+- `preferred_set`
+
+#### `design_system.motion`
+- `easing`
+- `duration_scale.micro`
+- `duration_scale.normal`
+- `duration_scale.macro`
+- `entrance_pattern`
+- `exit_pattern`
+- `philosophy`
+
+#### `design_system.components`
+- `button_style`
+- `input_style`
+- `card_style`
+- `navigation_pattern`
+- `modal_style`
+- `list_style`
+- `component_notes`
+
+### `design_style`
+The qualitative and perceptual layer.
+
+#### `design_style.aesthetic`
+- `mood`
+- `visual_metaphor`
+- `era_influence`
+- `genre`
+- `personality_traits`
+- `adjectives`
+
+#### `design_style.visual_language`
+- `complexity`
+- `ornamentation`
+- `whitespace_usage`
+- `visual_weight_distribution`
+- `focal_strategy`
+- `contrast_level`
+- `texture_usage`
+
+#### `design_style.composition`
+- `hierarchy_method`
+- `balance_type`
+- `flow_direction`
+- `grouping_strategy`
+- `negative_space_role`
+
+#### `design_style.imagery`
+- `photo_treatment`
+- `illustration_style`
+- `graphic_elements`
+- `pattern_usage`
+- `image_shape`
+
+#### `design_style.interaction_feel`
+- `feedback_style`
+- `hover_behavior`
+- `transition_personality`
+- `loading_style`
+- `microinteraction_density`
+
+#### `design_style.brand_voice_in_ui`
+- `tone`
+- `formality`
+- `cta_style`
+- `empty_state_approach`
+- `error_tone`
+
+### `visual_effects`
+The special rendering and advanced visual behavior layer.
+
+#### `visual_effects.overview`
+- `effect_intensity`
+- `performance_tier`
+- `fallback_strategy`
+- `primary_technology`
+
+#### `visual_effects.background_effects`
+- `type`
+- `description`
+- `technology`
+- `params.color_palette`
+- `params.speed`
+- `params.density`
+- `params.opacity`
+- `params.blend_mode`
+
+#### `visual_effects.particle_systems`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.count`
+- `params.shape`
+- `params.size_range`
+- `params.movement_pattern`
+- `params.color_behavior`
+- `params.interaction`
+- `params.spawn_area`
+
+#### `visual_effects.3d_elements`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.renderer`
+- `params.lighting`
+- `params.camera`
+- `params.materials`
+- `params.geometry`
+- `params.post_processing`
+- `params.interaction_model`
+
+#### `visual_effects.shader_effects`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.uniforms`
+- `params.vertex_manipulation`
+- `params.fragment_output`
+- `params.noise_type`
+- `params.distortion`
+
+#### `visual_effects.scroll_effects.parallax`
+- `enabled`
+- `layers`
+- `depth_range`
+- `speed_curve`
+
+#### `visual_effects.scroll_effects.scroll_triggered_animations`
+- `enabled`
+- `trigger_points`
+- `animation_type`
+- `scrub_behavior`
+
+#### `visual_effects.scroll_effects.scroll_morphing`
+- `enabled`
+- `description`
+
+#### `visual_effects.text_effects`
+- `type`
+- `description`
+- `technology`
+- `params.split_strategy`
+- `params.animation_per_unit`
+- `params.stagger`
+- `params.effect_style`
+
+#### `visual_effects.cursor_effects`
+- `enabled`
+- `type`
+- `description`
+- `params.shape`
+- `params.size`
+- `params.blend_mode`
+- `params.trail`
+- `params.interaction_zone`
+
+#### `visual_effects.image_effects`
+- `type`
+- `description`
+- `technology`
+- `params.filter_pipeline`
+- `params.hover_transform`
+- `params.reveal_animation`
+- `params.distortion_type`
+
+#### `visual_effects.glassmorphism_neumorphism`
+- `enabled`
+- `style`
+- `params.blur_radius`
+- `params.transparency`
+- `params.border_treatment`
+- `params.shadow_type`
+- `params.light_source_angle`
+
+#### `visual_effects.canvas_drawings`
+- `enabled`
+- `type`
+- `description`
+- `technology`
+- `params.draw_method`
+- `params.animation_loop`
+- `params.color_scheme`
+- `params.responsiveness`
+- `params.interaction`
+
+#### `visual_effects.svg_animations`
+- `enabled`
+- `type`
+- `description`
+- `params.animation_method`
+- `params.path_morphing`
+- `params.stroke_animation`
+- `params.filter_effects`
+
+#### `visual_effects.composite_notes`
+- Free-text notes for layered effects, implementation ambiguity, performance trade-offs, or screenshot-only observations
+
+## Field Guidance
+
+### `design_system` (Dimension 1: Structural / Measurable)
+Concrete, token-level values. Extract exact values where visible; estimate from visual inspection otherwise.
+
+- **`color.palette_type`**: "monochromatic", "complementary", "analogous", "triadic", "split-complementary"
+- **`color.contrast_strategy`**: How text/background contrast is managed — "high contrast", "subtle layers", "dark-on-light dominant"
+- **`typography.font_style_notes`**: e.g. "geometric sans with humanist touches"
+- **`spacing.content_density`**: "compact", "comfortable", "spacious"
+- **`spacing.section_rhythm`**: How vertical spacing varies between sections
+- **`layout.alignment_tendency`**: "strict grid", "centered", "asymmetric", "mixed"
+- **`shape.border_usage`**: "none", "subtle 1px", "bold borders", "only on inputs"
+- **`elevation.shadow_style`**: "none", "soft diffused", "hard drop", "layered"
+- **`elevation.depth_cues`**: "shadows", "overlapping layers", "blur/glass", "color intensity"
+- **`motion.philosophy`**: "minimal functional", "playful bouncy", "cinematic", "none"
+- **`components`**: Describe observed patterns — e.g. "ghost buttons with thick borders, rounded inputs with inner shadow"
+
+### `design_style` (Dimension 2: Qualitative / Perceptual)
+Subjective assessments. Use descriptive language.
+
+- **`aesthetic.mood`**: Array of 3–5 mood words, e.g. ["calm", "professional", "warm"]
+- **`aesthetic.genre`**: e.g. "corporate SaaS", "indie creative", "luxury editorial", "neo-brutalist"
+- **`aesthetic.personality_traits`**: As if the design were a person, e.g. ["confident", "approachable", "meticulous"]
+- **`visual_language.complexity`**: "minimal", "moderate", "rich", "maximal"
+- **`visual_language.ornamentation`**: "none", "subtle accents", "decorative", "heavily ornamented"
+- **`visual_language.focal_strategy`**: "single hero element", "distributed interest", "progressive reveal"
+- **`composition.hierarchy_method`**: "scale contrast", "color weight", "spatial isolation", "typographic hierarchy"
+- **`composition.balance_type`**: "symmetric", "asymmetric", "radial", "mosaic"
+- **`interaction_feel.transition_personality`**: "snappy", "smooth glide", "bouncy elastic", "fade-subtle"
+- **`brand_voice_in_ui.cta_style`**: "direct imperative", "friendly invitation", "urgent scarcity", "subtle suggestion"
+
+### `visual_effects` (Dimension 3: Special Rendering / Visual Wizardry)
+Effects beyond standard CSS. These often require Canvas, WebGL, SVG animation, shader programs, or JS animation libraries. When not directly observable from static code, describe them from screenshots or video.
+
+- **`overview.effect_intensity`**: "none", "subtle-accent", "moderate", "heavy-immersive"
+- **`overview.performance_tier`**: "lightweight" (CSS + simple JS), "medium" (Canvas 2D, SVG anim), "heavy" (WebGL, Three.js, shaders)
+- **`overview.fallback_strategy`**: What happens on low-end devices — "disable effects", "reduce to CSS", "static snapshot"
+- **`overview.primary_technology`**: "CSS only", "Canvas 2D", "WebGL/Three.js", "GSAP", "Lottie", "SVG SMIL", "Pixi.js"
+- **`background_effects.type`**: "gradient-animation", "noise-field", "mesh-gradient", "video-bg", "generative-art", "none"
+- **`particle_systems.type`**: "floating-dots", "confetti", "snow", "fireflies", "connected-nodes", "custom"
+- **`particle_systems.params.interaction`**: "mouse-repel", "mouse-attract", "click-burst", "none"
+- **`3d_elements.type`**: "hero-model", "product-viewer", "scene-bg", "text-extrusion", "abstract-geometry"
+- **`3d_elements.params.post_processing`**: e.g. ["bloom", "FXAA", "depth-of-field", "chromatic-aberration"]
+- **`shader_effects.type`**: "noise-distortion", "wave", "morph", "color-shift", "custom-GLSL"
+- **`shader_effects.params.noise_type`**: "perlin", "simplex", "worley", "fbm"
+- **`scroll_effects.parallax.layers`**: Number of depth layers, e.g. "3"
+- **`scroll_effects.scroll_triggered_animations.animation_type`**: "fade-up", "scale-in", "clip-reveal", "counter", "draw-SVG"
+- **`text_effects.type`**: "split-letter-animate", "typewriter", "glitch", "gradient-fill", "3d-extrude", "none"
+- **`text_effects.params.split_strategy`**: "by-char", "by-word", "by-line"
+- **`cursor_effects.type`**: "custom-cursor", "magnetic-buttons", "spotlight", "trail", "none"
+- **`image_effects.type`**: "hover-distortion", "reveal-clip", "parallax-tilt", "rgb-shift", "none"
+- **`image_effects.params.distortion_type`**: "barrel", "wave", "liquid", "glitch"
+- **`glassmorphism_neumorphism.style`**: "glass", "neumorphic-light", "neumorphic-dark", "frosted-layers", "none"
+- **`canvas_drawings.type`**: "generative-lines", "interactive-blobs", "data-visualization", "pattern-fill", "none"
+- **`svg_animations.type`**: "path-draw", "morph-shapes", "logo-reveal", "decorative-loop", "none"
+- **`composite_notes`**: Free-text description of how multiple effects layer together, performance trade-offs, or effects visible only in screenshots that cannot be fully captured in structured fields

package/departments/brand/skills/design-system/SKILL.md

@@ -6,9 +6,11 @@ description: >
   pages), WCAG 2.2 AA conformance report, Storybook CSF3 story stubs, and an
   integration guide. TRIGGER: "design system", "cria o design system", "design
   tokens", "component library", "biblioteca de componentes", "/brand
-  design-system". SKIP: only a color palette -> brand/colors; implementing the
-  components in application code -> dev frontend workflows (this skill
-  specifies the system, it does not build the app); reviewing an existing UI
+  design-system". SKIP: only a color palette -> brand/colors; reproducing the
+  look of an existing reference (screenshot, image, URL) -> brand/design-dna
+  (it reverse-engineers a system; this one specifies a new one); implementing
+  the components in application code -> dev frontend workflows (this skill
+  specifies the system; it does not build the app); reviewing an existing UI
   against brand guidelines -> brand/design-review.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 metadata:
@@ -72,6 +74,13 @@ A production design system in 5 deliverables:
 
 ## Study mode (design DNA extraction)
 
+> **Entry point:** a request that leads with a reference now routes to
+> `brand/design-dna`, which runs this same protocol with the same
+> guardrails and adds the qualitative and visual-effects dimensions. This
+> section stays because the study still runs *inside* a design-system
+> engagement whenever a reference turns up mid-brief — the protocol below
+> is the one both skills execute.
+
 When the operator brings a **reference** — a screenshot or a live URL —
 instead of a brief, run the study protocol in
 `references/design-dna-study.md`: it extracts structural DNA

package/departments/dev/SKILL.md

@@ -37,6 +37,7 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | `/dev performance <target>` | Performance audit (CWV, API latency, DB) | Focused |
 | `/dev pipeline <project>` | CI/CD pipeline design and setup | Focused |
 | `/dev clean-review <file>` | Clean Code + SOLID compliance review | Specialist |
+| `/dev research <topic>` | Library evaluation and pattern discovery (KB + Context7 + gh-grep + web) | Specialist |
 | `/dev spec <description>` | Create feature specification (mandatory pre-impl) | Specialist |
 | `/dev scaffold <type> <name>` | Project scaffolding from starter repos | Specialist |
 | `/dev do <description>` | Smart routing to the right dev command | Orchestrator |
@@ -81,6 +82,30 @@ Diagnose step: `get_architecture` for the structural map,
 PRIOR, not ground truth: verify with Read before editing. When the MCP
 is absent the phases run as before (Grep/Read exploration).
 
+## Real-world grounding (gh-grep MCP)
+
+`codebase-memory` answers "how does OUR code do this". When the question
+is "how does anyone do this", call `mcp__gh-grep__searchGitHub` — literal
+grep with regex over public repositories — in Phase 1 RESEARCH and in
+Diagnose, whenever an external API, library idiom, or error signature is
+unfamiliar or disputed.
+
+Query it with **code tokens**: `useSyncExternalStore`, `from
+sqlalchemy.orm import`, `Cannot read properties of undefined`. Filter by
+language and path. A natural-language sentence returns noise, so a first
+attempt that phrases the question in prose will look like the tool failing
+when it is the query that failed.
+
+Pair it with Context7, which answers the complementary question: Context7
+gives the documented contract; gh-grep gives the practice N teams actually
+shipped. Where they disagree, the docs win and the divergence itself is
+worth reporting. Treat results as a prior about practice — they carry no
+authority over our own code, which you still read directly.
+
+Skip it for private code (it indexes public repositories only — use
+`codebase-memory` or the KB), for documentation lookups (Context7), and for
+anything that is not code (WebSearch, Firecrawl).
+
 ## Focused Workflow (4 Phases)
 
 For `/dev debug`, `/dev refactor`, `/dev db`, `/dev performance`, `/dev pipeline`: Diagnose → Implement with tests → Rita validates → Quality Gate (Marta).

package/departments/dev/skills/adversarial-review/SKILL.md

@@ -85,6 +85,11 @@ allowed-tools: [Read, Bash, Grep, Glob, Agent]
 - [ ] Assume every variable could be null/undefined
 - [ ] Assume every external call will fail
 - [ ] Ask: "If I deleted this change, what would break?"
+- [ ] For an abuse vector that depends on how a third-party library
+      behaves, confirm the behaviour with `mcp__gh-grep__searchGitHub`
+      (real call-sites) plus Context7 (documented contract) before
+      raising it as CRITICAL — a hostile persona that invents the
+      library's behaviour is refuting itself, not the code
 
 ## Verdicts
 

package/departments/dev/skills/api-design/SKILL.md

@@ -28,6 +28,14 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 7. **Consistent response** — `{ "data": ..., "meta": { "pagination": ... } }`
 8. **Error format** — `{ "error": { "code": "VALIDATION_FAILED", "message": "...", "details": [...] } }`
 
+When the contract has to interoperate with something you do not control — a
+partner API, an SDK's expectations, a webhook consumer — check the shape
+that already exists in the wild. `mcp__gh-grep__searchGitHub` on the field
+names or the header (`X-Idempotency-Key`, `"cursor":`) shows what clients
+are already written against. Matching an established shape costs nothing
+and removes a whole class of integration surprise; diverging from one is a
+decision that belongs in the ADR with its reason.
+
 ## Output: OpenAPI Snippet
 
 ```yaml

package/departments/dev/skills/architecture-design/SKILL.md

@@ -35,6 +35,12 @@ allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, WebFetch]
 - Ask user: What system/feature needs architecture?
 - Clarify: Scale requirements, team size, tech constraints
 - Identify: Domain boundaries, data flows, external integrations
+- Where the design leans on a specific framework or infrastructure
+  primitive, check the precedent with `mcp__gh-grep__searchGitHub`: grep
+  the structural tokens (a config key, a base class, a directory
+  convention) and read how real systems wired it. Feed what you find into
+  Step 4's Alternatives Considered — a pattern that public repos abandoned
+  is an alternative you can rule out with evidence instead of taste.
 
 ### Step 3: Architecture Design
 Apply the appropriate pattern: