contextos-agents 2.1.0 → 2.1.1

package/catalog/skills/graphify/EXAMPLES.md

@@ -0,0 +1,73 @@
+# Graphify Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Codebase Exploration & Architecture Mapping
+
+### Anti-pattern: Context Window Flooding (Dumping source directories into prompt)
+
+```bash
+# BAD: Reading 150 TypeScript files into context to understand system architecture.
+# Burns 200k+ tokens, causes model hallucinations, and loses attention span.
+cat src/**/*.ts | llm "explain the architecture and component connections"
+```
+
+### Best practice: ContextOS Standard (Deterministic Tree-sitter AST Graph)
+
+```bash
+# GOOD: Generate queryable AST knowledge graph and compact architecture summary
+graphify run ./src --output .graphify/
+
+# Inspect high-level architecture and god nodes with minimal tokens (<2k tokens)
+cat .graphify/GRAPH_REPORT.md
+```
+
+---
+
+## Example 2: Refactoring Blast-Radius Analysis
+
+### Anti-pattern: String Grep Guesswork
+
+```bash
+# BAD: Grepping for common symbol names returns hundreds of false positives (comments, logs, unrelated types)
+grep -rn "PaymentService" src/
+```
+
+### Best practice: ContextOS Standard (Inbound Dependency Traversal via graph.json)
+
+```javascript
+// GOOD: Precise AST-level callers extracted directly from knowledge graph edges
+const fs = require('fs');
+const graph = JSON.parse(fs.readFileSync('.graphify/graph.json', 'utf8'));
+
+const targetNode = 'PaymentService';
+const dependents = graph.edges
+  .filter(edge => edge.target === targetNode && edge.type === 'imports')
+  .map(edge => edge.source);
+
+console.log(`Modules directly broken by modifying ${targetNode}:`, dependents);
+```
+
+---
+
+## Example 3: Keeping Graph Fresh in CI / Pre-commit
+
+### Anti-pattern: Relying on Outdated Graphs
+
+```bash
+# BAD: Developing against a graph generated two months ago.
+# Dependencies drift, leading to false safety assumptions.
+```
+
+### Best practice: ContextOS Standard (Git Hook & Automated Watch)
+
+```bash
+# Option A: Active development in watch mode
+graphify watch ./src --output .graphify/
+
+# Option B: Pre-commit hook to verify fresh GRAPH_REPORT.md
+#!/bin/sh
+# .git/hooks/pre-commit
+if command -v graphify >/dev/null 2>&1; then
+  graphify run ./src --report-only
+  git add GRAPH_REPORT.md
+fi
+```

package/catalog/skills/graphify/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: graphify
+description: >
+  Codebase knowledge graph generator and architecture mapping guide.
+  Eliminates context window burn, enables precise dependency mapping, and identifies architectural god nodes.
+---
+
+# graphify
+
+## Overview
+
+**Graphify** is an instruction-only codebase mapping and context optimization guide. Instead of feeding raw directory trees or entire source files into an agent's context window, Graphify instructs agents on how to construct a deterministic, queryable knowledge graph (`graph.json`, `GRAPH_REPORT.md`, `graph.html`) using external companion analyzers (such as the TypeScript AST analyzer in `contextos-mcp` or the external `graphifyy` CLI), keeping the core package 100% zero-dependency without bundled native Tree-sitter binaries.
+
+This skill instructs agents how to build, query, and maintain codebase graphs to navigate complex architectures with near-zero token overhead.
+
+## When to Use
+
+Activate whenever:
+
+- Working in large repositories (10k+ LOC) where full-file reads cause context overflow.
+- Performing cross-module refactorings and needing to determine exact dependency **blast radius**.
+- Onboarding onto an unfamiliar codebase or mapping legacy service boundaries.
+- The user asks to "map the codebase", "show dependency graph", "find central components", or "run graphify".
+- Working alongside `context-manager` to supply an automated `PROJECT_GRAPH.md` / `graph.json`.
+
+## Rules & Patterns
+
+### 1. The Graph-First Navigation Protocol
+
+Before opening and reading arbitrary source files in a large project:
+
+1. **Check for Existing Artifacts**:
+   - Inspect if `graph.json` or `GRAPH_REPORT.md` exists in the project root or `.graphify/`.
+   - If present, query `graph.json` or read `GRAPH_REPORT.md` first to locate target modules.
+2. **Deterministic CLI Execution**:
+   - If missing or stale, generate the graph using the Python package (`pip install graphifyy`):
+
+     ```bash
+     graphify run .
+     ```
+
+   - For live development sessions, run in watch mode:
+
+     ```bash
+     graphify watch .
+     ```
+
+3. **Inspect God Nodes**:
+   - Always check the "God Nodes" section of `GRAPH_REPORT.md`. These represent high-centrality modules (e.g., core configs, base models, central dispatchers). Changes to god nodes have the highest blast radius.
+
+### 2. Context Safety Rules
+
+- **Never load `graph.html` into agent context**: `graph.html` is an interactive visualization for humans in the browser; reading it burns tokens needlessly.
+- **Selective JSON Querying**: Do not dump the entire `graph.json` into prompt context if it exceeds 50KB. Use targeted grep/jq queries to extract specific node neighbors.
+- **Git Hygiene**: Add `graph.html` and `.graphify/cache` to `.gitignore`. Keep `GRAPH_REPORT.md` committed only if the team uses it as shared documentation.
+
+### 3. Blast Radius Verification
+
+When modifying a function, class, or interface:
+
+1. Locate the symbol's node in `graph.json`.
+2. Extract all inbound edges (`dependents` / `callers`).
+3. Formulate the verification plan specifically around those dependent call sites.
+
+---
+
+## Code Examples
+
+### Installing and Running Graphify
+
+```bash
+# Install graphify CLI (package name is graphifyy on PyPI)
+pip install graphifyy
+
+# Generate knowledge graph and markdown architectural report
+graphify run ./src --output .graphify/
+
+# View interactive visualization locally
+open .graphify/graph.html
+```
+
+### Querying Node Dependencies via Shell
+
+```bash
+# Find dependents of a critical module in graph.json without loading entire file
+node -e "
+const g = require('./.graphify/graph.json');
+const target = 'UserService';
+const inbound = g.edges.filter(e => e.target === target).map(e => e.source);
+console.log('Modules dependent on ' + target + ':', inbound);
+"
+```
+
+### Git Pre-Commit Hook Integration
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit: ensure GRAPH_REPORT.md remains fresh
+if command -v graphify >/dev/null 2>&1; then
+  graphify run . --report-only
+  git add GRAPH_REPORT.md
+fi
+```
+
+---
+
+## Validation Checklist
+
+- [ ] `graph.json` and `GRAPH_REPORT.md` are generated without syntax errors.
+- [ ] Central "God Nodes" are identified and accounted for in the implementation plan.
+- [ ] No heavy visualization artifacts (`graph.html`, raw SVG dumps) are ingested into agent prompt context.
+- [ ] Inbound dependencies (callers) are checked before modifying exported signatures.
+- [ ] `.gitignore` properly excludes local graph caches and visualization outputs.
+
+---
+
+## Common Mistakes
+
+- **Context Window Flooding**: Ingesting the complete `graph.json` of a 500k LOC repository into agent context instead of slicing target subgraphs.
+- **Stale Graph Fallacy**: Assuming `graph.json` is up to date after heavy code refactorings without re-running `graphify run` or using `--watch`.
+- **Ignoring Semantic Non-Code Files**: Neglecting SQL migrations, OpenAPI specs, and docker configs during graph extraction.
+- **Mistaking Package Name**: Trying to install `pip install graphify` instead of the official PyPI package `graphifyy`.
+
+---
+
+## Integration Notes
+
+- **Synergy with `context-manager`**: Graphify serves as the automated backend engine for `context-manager`. Instead of manually maintaining `docs/PROJECT_GRAPH.md`, run Graphify to keep `graph.json` current.
+- **Synergy with `system-design`**: Use `GRAPH_REPORT.md` to ground architectural proposals in actual codebase topology.
+- **Synergy with `architecture-diagrams`**: The nodes and edges extracted in `graph.json` can be directly mapped into animated SVG C4 architecture diagrams.

package/catalog/skills/graphify/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/graphify/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: graphify
+category: architecture
+type: instruction-only
+description: Codebase knowledge graph generator and architecture mapping guide. Instructs agents on AST dependency extraction and blast radius analysis.
+version: 1.0.0
+optional:
+  - context-manager
+  - system-design
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - VALIDATION.json

package/catalog/skills/impeccable-design/EXAMPLES.md

@@ -0,0 +1,26 @@
+# impeccable-design Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Dark Mode Surfaces & Elevation
+
+### Anti-pattern: Pure Black with Flat Cards
+
+```css
+/* BAD: Pure #000000 background with harsh pure white borders and flat cards */
+body { background-color: #000000; color: #ffffff; }
+.card { background-color: #111111; border: 1px solid #ffffff; }
+```
+
+### Best practice: ContextOS Standard (Atmospheric Depth & Tinted Surfaces)
+
+```css
+/* GOOD: Tinted dark background with layered elevation surfaces and subtle border */
+body {
+  background-color: #0B0D13; /* Tinted with subtle deep blue */
+  color: #E2E8F0;
+}
+.surface-1 {
+  background-color: #111522;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
+}
+```

package/catalog/skills/impeccable-design/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: impeccable-design
+description: >
+  Visual design quality enforcement. 50 deterministic anti-pattern rules preventing
+  AI design slop. Bans generic fonts, pure colors, nested cards, dated animations.
+  Adapted for Tailwind CSS v4, shadcn/ui, and Framer Motion stacks.
+---
+
+# impeccable-design
+
+## Overview
+
+Hard QA design review checklist consisting of 50 deterministic rules covering typography (T1-T10), color systems (C1-C12), layout constraints (L1-L11), component contracts (K1-K11), and micro-animations (A1-A8).
+
+## When to Use
+
+Activate during the REVIEW phase of all frontend tasks as a strict visual and functional QA gate before marking UI work complete.
+
+## Rules & Patterns
+
+Based on [pbakaus/impeccable](https://github.com/pbakaus/impeccable) - deterministic detector rules for AI-generated frontend design.
+
+## Core Principle
+
+> Every model is trained on the same SaaS templates. Skip this guidance and you get the same handful of tells on every project. Impeccable eliminates them.
+
+## Role in the Pipeline
+
+> **This skill acts as a QA-designer at the `/review` phase.** `ui-ux-pro` is the planning guideline; `impeccable-design` is the hard checklist that runs before merge.
+
+---
+
+## Anti-Pattern Rules
+
+### Typography (Rules T1 - T10)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| T1 | Using Inter for all text | Use Inter for UI body, pair with a distinct display font for headings OR with `JetBrains Mono` for technical/number accents (premium SaaS pattern) |
+| T2 | Using Arial or Helvetica | Use a curated Google Font pairing |
+| T3 | All text same weight | Use weight contrast: 700 headings, 400 body, 500 labels |
+| T4 | Line height = 1 (tight) | Body: 1.6-1.8, Headings: 1.1-1.3 |
+| T5 | No letter-spacing on caps | Uppercase labels: `letter-spacing: 0.08em` (Tailwind: `tracking-widest`) |
+| T6 | Text too wide | Max line length: 60-75 characters - use `max-w-prose` or `max-w-[65ch]` |
+| T7 | Monospace only for code | Use `tabular-nums` Tailwind class for number tables and data grids |
+| T8 | Random font sizing | Use a consistent modular scale (1.25× or 1.333×) - use Tailwind's `text-*` scale |
+| T9 | Body text too small | Minimum `text-sm` (14px) for body, never smaller than 12px |
+| T10 | Bold everywhere | Bold is for emphasis. Diluted if overused. |
+
+**Tailwind typography utilities:**
+
+- `text-balance` - for headlines (prevents orphan words)
+- `text-pretty` - for body paragraphs (smart line-breaks)
+- `tabular-nums` - for numerical data tables
+
+### Color (Rules C1 - C12)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| C1 | Pure black `#000` | Tint toward brand: `hsl(240, 10%, 4%)` |
+| C2 | Pure white `#fff` for surfaces | Near-white with warmth: `hsl(40, 30%, 97%)` |
+| C3 | Gray on colored background | Check contrast - likely fails WCAG. Use white/dark |
+| C4 | Purple → Blue gradient | Clichéd AI palette. Use brand-derived gradients |
+| C5 | Neon primary colors | Neon = accent only, never primary surface or text |
+| C6 | Too many colors | 3 colors max: primary, neutral, semantic (success/error) |
+| C7 | All links same blue `#0000EE` | Style links with brand color, preserve underline |
+| C8 | Disabled state = gray only | Disabled: `opacity-40` + `cursor-not-allowed` |
+| C9 | Success always green, Error always red | Check brand conflicts. Use accessible variants |
+| C10 | Dark mode = inverted light mode | Dark mode needs separate palette - use `@layer base { .dark { ... } }` |
+| C11 | No hover state change | Hover: shift lightness 8-12%, add `transition-colors duration-150` |
+| C12 | Brand color on dark surface loses identity | Adjust saturation/lightness for dark bg context |
+
+### Layout & Spacing (Rules L1 - L11)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| L1 | Cards inside cards | One level of card depth maximum |
+| L2 | Icon tile above every heading | Use icons inline, in context, not decoratively above text |
+| L3 | Centered long paragraphs | `text-center` max 2 lines only. Use `text-pretty` + left-align for body |
+| L4 | Inconsistent spacing | Use Tailwind spacing utilities only. **Never arbitrary values** like `gap-[17px]` |
+| L5 | Zero whitespace between sections | Sections need `py-16` to `py-24` breathing room |
+| L6 | Content touching edges | Always `px-4` minimum on mobile |
+| L7 | Same visual weight everywhere | Use hierarchy: primary > secondary > tertiary zones |
+| L8 | Grid breaks on tablet | Test at 768px. Use 4-col on tablet, 12-col on desktop |
+| L9 | Full-width everything | Max content width: `max-w-7xl` centered |
+| L10 | Missing grid alignment | Use CSS Grid or Tailwind `grid` - not absolute positioning |
+| L11 | Arbitrary high z-indexes | **NEVER** use `z-[999]` or `z-50` manually. Rely on DOM order + Radix/shadcn Portals which already handle modal elevation correctly |
+| L12 | Default Rhythm | Break the 'Hero → 3 Features → CTA' structure. Build structurally diverse pages tailored to the content. |
+| L13 | Symmetric card grids everywhere | Use asymmetric layouts (e.g., bento boxes, masonry, alternating left/right) to reduce the AI-generated feel. |
+
+### Components (Rules K1 - K11)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| K1 | Two filled buttons side-by-side | `<Button variant="default">` + `<Button variant="outline">` or `variant="ghost"` |
+| K2 | Button without loading state | Always add spinner + `disabled` during async actions |
+| K3 | Modal without backdrop blur | shadcn `<Dialog>` handles this. Don't override with plain divs |
+| K4 | Empty states left blank | **Always** design empty states: illustration + helpful message + primary CTA |
+| K5 | No skeleton screens | Use `<Skeleton>` from shadcn for content areas, not just spinners |
+| K6 | Tooltip on click (not hover) | Tooltips on hover, modals on click - use shadcn `<Tooltip>` + `<Dialog>` |
+| K7 | Dropdown without keyboard nav | Use shadcn `<DropdownMenu>` - keyboard nav is built-in |
+| K8 | Table without row hover | shadcn `<TableRow>` handles hover state automatically. Do **not** override it |
+| K9 | Building complex UI from scratch | **Check shadcn/ui first**. If the component exists, generate the CLI command: `npx shadcn@latest add dialog`. Never manually rewrite what shadcn already provides |
+| K10 | Native `<select>` or `<input type="date">` in premium UI | Native form controls cannot be styled consistently across Chrome/Safari/Firefox. Use `shadcn <Select>` and `shadcn <DatePicker>` for cross-browser consistency |
+| K11 | Form without error state styling | Every input must have error state: red border + error message below |
+
+### Animation (Rules A1 - A8)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| A1 | CSS bounce/elastic/spring easing | CSS spring animations are forbidden. **Exception**: If using Framer Motion, highly damped springs are encouraged: `{ type: "spring", stiffness: 400, damping: 30 }` for modals and popovers - this creates a premium, physical feel like Vercel/Linear |
+| A2 | Animations that take > 400ms | Micro: 100-150ms, Components: 200-300ms, Pages: 300-400ms |
+| A3 | Animations everywhere | Animate max 2-3 elements simultaneously |
+| A4 | Same animation for enter and exit | Enter: ease-out (decelerate), Exit: ease-in (accelerate) |
+| A5 | Animating expensive properties | Only animate `transform` and `opacity` - never `height`, `width`, `top` |
+| A6 | No animation on mobile | Respect `prefers-reduced-motion: reduce` - wrap in `@media` or use `useReducedMotion()` |
+| A7 | Scroll-triggered animations that block | Don't block content visibility for scroll reveals |
+| A8 | Hover animations on touch devices | Wrap hover effects in `@media (hover: hover)` |
+
+### Images & Icons (Rules I1 - I8)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| I1 | Decorative icons on every list item | Icons add meaning, not decoration. Use selectively. |
+| I2 | Mix of icon styles | Pick one icon set (e.g., Lucide for shadcn). Stick with it. |
+| I3 | Low-contrast icons | Icons need ≥ 3:1 contrast ratio |
+| I4 | Images without aspect-ratio | Always set `aspect-video` or `aspect-square` to prevent layout shifts |
+| I5 | No image loading state | Use `<Skeleton>` placeholder or blur hash |
+| I6 | SVG icons inline without aria | Add `aria-hidden="true"` or `aria-label` |
+| I7 | Stock photo generic humans | Use illustrations, abstract art, or genuine brand photography |
+| I8 | Unoptimized images | WebP/AVIF, properly sized, `loading="lazy"` below fold |
+
+---
+
+## Design Initialization Checklist
+
+Start every new design with:
+
+```markdown
+## Design Context
+
+**Surface type**: [brand/marketing OR product/app]
+**Target audience**: [who are they? what do they value?]
+**Brand tone**: [professional/playful/bold/minimal/technical]
+**Anti-references**: [designs this should NOT look like]
+**Primary font**: [chosen font + why + Framer Motion / shadcn pairing]
+**Color palette**: [3 semantic colors + HSL values for light AND dark]
+**Component library**: [shadcn/ui | radix | custom]
+**Animation library**: [CSS only | Framer Motion | GSAP]
+```
+
+---
+
+## Design Review Audits
+
+### Quick Audit (before PR)
+
+- Typography: Is there clear visual hierarchy? Are fonts intentional? Is Inter paired properly?
+- Color: Any pure black/white? Contrast failures? Too many colors? Dark mode?
+- Spacing: Consistent Tailwind scale? No arbitrary values? Enough whitespace?
+- Animation: Any CSS bounce/elastic? Too slow (>400ms)? Too many simultaneous?
+- Components: Any native `<select>` or `<input type="date">` that should be shadcn?
+- Z-index: Any hardcoded `z-[999]` or `z-50`?
+
+### Full Audit (before release)
+
+- Accessibility: Run axe DevTools or Lighthouse - target 90+ score
+- Responsiveness: Test at 375px, 768px, 1280px, 1440px
+- Dark mode: Does the full palette hold up? No inverted-only shortcuts?
+- Empty states: Does every list/table have a designed empty state?
+- Edge cases: Loading states, error states, long text overflow, RTL
+
+---
+
+## Premium Design Markers
+
+These details separate premium from mediocre:
+
+1. **Consistent border radius** - pick one and use it everywhere (`rounded-md` = 6px, `rounded-lg` = 8px)
+2. **Intentional drop shadows** - darker near surface, lighter for floating elements
+3. **Micro-copy quality** - button labels are verbs: "Save changes" not "Submit"
+4. **Focus ring styling** - `focus-visible:ring-2 focus-visible:ring-primary` matching brand
+5. **Smooth color transitions** - `transition-colors duration-150` on all interactive elements
+6. **Optical alignment** - icon + text optically centered, not mathematically (`items-center gap-1.5`)
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/catalog/skills/impeccable-design/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# impeccable-design Troubleshooting & Common Mistakes
+
+## 1. Nested Border Radius Mismatch
+
+- **Symptom**: Corners of an inner element poke out or look visually awkward inside a container.
+- **Root Cause**: Using the same border-radius on both outer container and inner child.
+- **Fix**: Inner radius formula: r_inner = max(0, r_outer - padding).
+
+## 2. Animation Performance Stutter
+
+- **Symptom**: Janky animations and dropped frames during transitions.
+- **Root Cause**: Animating layout properties (width, height, top, margin).
+- **Fix**: Animate only composited GPU-accelerated properties: transform and opacity.
+
+## 3. Cluttered Visual Density
+
+- **Symptom**: Interface feels overwhelming, cramped, and cheap.
+- **Root Cause**: Cramming too many borders, dividers, badges, and icons into one view.
+- **Fix**: Replace borders with generous whitespace; let alignment and typography hierarchy define grouping.

package/catalog/skills/impeccable-design/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/impeccable-design/skill.yaml

@@ -0,0 +1,15 @@
+schemaVersion: 2
+name: impeccable-design
+category: design
+type: instruction-only
+description: >
+  Visual design quality skill based on pbakaus/impeccable.
+  46 deterministic anti-pattern rules that prevent AI design slop.
+  Bans overused fonts, pure black/gray, nested cards, bounce animations,
+  and all generic AI-generated design clichés.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/interview-me/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: interview-me
+description: >
+  Interactive requirements elicitation skill. Interrogates ambiguous, complex, or high-blast-radius
+  tasks one focused question at a time before any plan or code is written.
+---
+
+# interview-me
+
+## Overview
+
+Structured requirements interrogation framework inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills). Prevents wasted cycles by transforming vague user intents into crisp, unambiguous architectural constraints through single-question progressive interview loops.
+
+## When to Use
+
+Activate whenever:
+
+- User task has underspecified requirements, open UX decisions, or multiple viable architectural trade-offs.
+- A high-blast-radius change (database migrations, auth refactor, API contract change) is requested.
+- Explicitly triggered via `/spec`, `/interview`, or "ask me questions first".
+
+## Rules & Patterns
+
+### 1. The One-Question-At-A-Time Rule
+
+**Never overwhelm the user with a 10-point interrogation form.**
+
+- Ask **exactly ONE focused question** per turn (or at most two tightly-coupled binary options).
+- Provide the recommended option first with clear rationale: `"(Recommended) Option A because..."`.
+- Always allow write-in or clarification.
+
+### 2. The 4 Interrogation Dimensions
+
+Interrogate in this strict priority order:
+
+1. **Business Outcome & Invariants**:
+   - What core problem does this solve?
+   - What behavior is strictly forbidden?
+2. **Scope Boundaries (In vs Out)**:
+   - What must be delivered in this atomic slice?
+   - What is explicitly deferred to later?
+3. **Technical Constraints**:
+   - Versions, libraries, database engines, backwards compatibility requirements.
+4. **Edge Cases & Failure Modes**:
+   - What happens on network disconnect, empty response, or unauthorized token?
+
+### 3. Progressive Synthesis
+
+After each user answer:
+
+- Acknowledge the decision and update the mental model.
+- If more critical decisions remain, ask the next question.
+- Once 2-4 key questions are resolved, synthesize the formal Feature Spec and transition to `engineering-workflow` (`[PHASE: Plan]`).
+
+---
+
+## Code Examples
+
+### Interactive Interview Turn Example
+
+```markdown
+**Question 1 of 3 (Authentication Strategy)**
+
+Before implementing the API authentication layer, we need to align on session storage:
+
+1. **(Recommended) HTTP-only Secure Cookies with Refresh Tokens**:
+   - *Why*: Immune to XSS token theft, standard for web dashboards.
+2. **Bearer Token in Authorization Header**:
+   - *Why*: Ideal if this API will also be consumed by mobile apps or third-party CLI tools.
+
+Which model fits your architecture best?
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Question addresses an actual ambiguity (never ask about obvious defaults).
+- [ ] Exactly one question (or two tightly coupled choices) asked.
+- [ ] Recommendation provided with clear engineering justification.
+- [ ] User response incorporated into the final spec before coding.
+
+---
+
+## Common Mistakes
+
+- **Asking obvious questions**: Asking "Do you want error handling?" instead of making a sensible senior default.
+- **Interrogation bombardment**: Dumping a list of 8 open-ended questions in a single wall of text.
+- **Ignoring user answers**: Asking a question, receiving an answer, and then implementing something else.
+
+---
+
+## Integration Notes
+
+- Runs at the start of `engineering-workflow` Phase 1 (`/spec`).
+- Interacts with `gstack-roles` (`[ROLE: Product Manager]` or `[ROLE: Architect]`).
+- Hands off to `ponytail-mindset` once scope is defined.

package/catalog/skills/interview-me/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/interview-me/skill.yaml

@@ -0,0 +1,9 @@
+schemaVersion: 2
+name: interview-me
+category: engineering
+type: instruction-only
+description: Interactive requirements elicitation skill. Interrogates ambiguous, complex, or high-blast-radius tasks one focused question at a time before any plan or code is written.
+version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/catalog/skills/microservices/EXAMPLES.md

@@ -0,0 +1,38 @@
+# microservices Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Inter-service Communication
+
+### Anti-pattern: Synchronous HTTP Call Chains (The Distributed Monolith)
+
+```text
+User -> OrderService (HTTP) -> InventoryService (HTTP) -> PaymentService (HTTP) -> EmailService (HTTP)
+Problem: High latency, 99.9% availability compounding to 96% overall availability, cascading failure.
+```
+
+### Best practice: ContextOS Standard (Asynchronous Event Choreography)
+
+```text
+User -> OrderService (creates order with status 'PENDING')
+OrderService publishes 'OrderPlaced' event to Event Broker (Kafka/RabbitMQ)
+  ├── InventoryService consumes 'OrderPlaced' -> Reserves stock
+  ├── PaymentService consumes 'OrderPlaced' -> Charges customer
+  └── NotificationService consumes 'PaymentProcessed' -> Sends confirmation email
+```
+
+---
+
+## Example 2: Database Architecture
+
+### Anti-pattern: Shared Database Across Multiple Microservices
+
+```text
+BAD: OrderService and UserService both directly read and write to the same 'users' table.
+Schema migrations in UserService immediately break OrderService.
+```
+
+### Best practice: ContextOS Standard (Database-per-Service)
+
+```text
+GOOD: UserService owns user data. OrderService maintains a local read-model (denormalized user info)
+synchronized via 'UserUpdated' events. Each service can migrate and scale independently.
+```