@shaykec/bridge 0.4.25 → 0.4.27

package/journeys/ai-engineer.yaml

@@ -0,0 +1,34 @@
+slug: ai-engineer
+title: "AI/ML Engineer"
+version: 1.0.0
+description: "From prompt engineering to building AI agents — harness LLMs in production systems."
+icon: brain
+tags: [ai, llm, agents, rag, prompt-engineering, ml]
+difficulty: beginner-to-advanced
+estimated_hours: 30
+
+stages:
+  - name: "Prompt Engineering"
+    description: "Master the art of communicating with AI models"
+    modules:
+      - prompt-engineering
+
+  - name: "LLM Fundamentals"
+    description: "Understand how large language models work under the hood"
+    modules:
+      - llm-fundamentals
+      - { slug: llm-evaluation, title: "LLM Evaluation & Benchmarking" }
+
+  - name: "RAG & Knowledge Systems"
+    description: "Ground AI responses in your own data"
+    modules:
+      - rag-fundamentals
+      - { slug: vector-databases, title: "Vector Databases & Embeddings" }
+
+  - name: "AI Agents & Workflows"
+    description: "Build autonomous agents that use tools and reason"
+    modules:
+      - ai-agents
+      - ai-pair-programming
+      - { slug: ai-safety, title: "AI Safety & Alignment" }
+      - { slug: ai-ops, title: "AI Ops — Monitoring & Deploying AI Systems" }

package/journeys/backend-developer.yaml

@@ -0,0 +1,36 @@
+slug: backend-developer
+title: "Backend Developer"
+version: 1.0.0
+description: "Design robust APIs, work with databases, and architect scalable systems."
+icon: server
+tags: [backend, api, sql, architecture, systems]
+difficulty: beginner-to-advanced
+estimated_hours: 30
+
+stages:
+  - name: "Language & Code Quality"
+    description: "Write clean, principled code from day one"
+    modules:
+      - typescript-fundamentals
+      - clean-code
+
+  - name: "Data & APIs"
+    description: "Databases and API design — the backbone of any backend"
+    modules:
+      - sql-fundamentals
+      - api-design
+
+  - name: "Architecture"
+    description: "Design systems that scale and evolve"
+    modules:
+      - solid-principles
+      - design-patterns
+      - system-design
+
+  - name: "Reliability & Operations"
+    description: "Debug, review, and respond when things go wrong"
+    modules:
+      - debugging-systematically
+      - code-review
+      - incident-response
+      - { slug: observability, title: "Observability & Monitoring" }

package/journeys/business-analyst.yaml

@@ -0,0 +1,37 @@
+slug: business-analyst
+title: "Business Analyst"
+version: 1.0.0
+description: "Bridge business needs and technical solutions — requirements, data analysis, and stakeholder alignment."
+icon: bar-chart
+tags: [business-analysis, requirements, data, stakeholders, process]
+difficulty: beginner-to-advanced
+estimated_hours: 28
+
+stages:
+  - name: "Requirements & Documentation"
+    description: "Capture, structure, and communicate what needs to be built"
+    modules:
+      - writing-prds
+      - user-story-mapping
+      - adr-writing
+
+  - name: "Data & SQL"
+    description: "Query data to inform decisions and validate requirements"
+    modules:
+      - sql-fundamentals
+      - { slug: data-visualization, title: "Data Visualization & Reporting" }
+
+  - name: "Stakeholder & Process"
+    description: "Align people, manage risk, and plan delivery"
+    modules:
+      - stakeholder-communication
+      - sprint-planning
+      - risk-management
+      - prioritization-frameworks
+
+  - name: "AI-Assisted Analysis"
+    description: "Accelerate research and analysis with AI tools"
+    modules:
+      - ai-assisted-research
+      - prompt-engineering
+      - { slug: process-modeling, title: "Business Process Modeling" }

package/journeys/devops-engineer.yaml

@@ -0,0 +1,37 @@
+slug: devops-engineer
+title: "DevOps Engineer"
+version: 1.0.0
+description: "Automate, deploy, and operate — from version control to incident response."
+icon: terminal
+tags: [devops, git, ci-cd, infrastructure, monitoring]
+difficulty: beginner-to-advanced
+estimated_hours: 28
+
+stages:
+  - name: "Version Control Mastery"
+    description: "Git workflows and collaboration at scale"
+    modules:
+      - git
+      - code-review
+
+  - name: "Automation & CI/CD"
+    description: "Automate builds, tests, and deployments"
+    modules:
+      - { slug: ci-cd-pipelines, title: "CI/CD Pipelines" }
+      - { slug: infrastructure-as-code, title: "Infrastructure as Code" }
+      - test-strategy
+
+  - name: "Systems & Architecture"
+    description: "Design for reliability and scalability"
+    modules:
+      - system-design
+      - { slug: containerization, title: "Containerization (Docker & K8s)" }
+      - { slug: cloud-fundamentals, title: "Cloud Fundamentals (AWS/GCP/Azure)" }
+
+  - name: "Operations & Reliability"
+    description: "Monitor, debug, and respond to incidents"
+    modules:
+      - debugging-systematically
+      - incident-response
+      - { slug: observability, title: "Observability & Monitoring" }
+      - { slug: sre-practices, title: "SRE Practices & SLOs" }

package/journeys/engineering-manager.yaml

@@ -0,0 +1,44 @@
+slug: engineering-manager
+title: "Engineering Manager"
+version: 1.0.0
+description: "Transition from individual contributor to engineering leader — people, process, and technical strategy."
+icon: users
+tags: [management, leadership, hiring, mentoring, process]
+difficulty: intermediate-to-advanced
+estimated_hours: 40
+
+stages:
+  - name: "Technical Foundation"
+    description: "Lead by example — stay sharp on code quality and architecture"
+    modules:
+      - code-review
+      - adr-writing
+      - system-design
+
+  - name: "People Skills"
+    description: "One-on-ones, mentoring, and building trust"
+    modules:
+      - one-on-ones
+      - technical-mentoring
+      - hiring-interviews
+
+  - name: "Team Operations"
+    description: "Run effective teams — standups, sprints, and communication"
+    modules:
+      - running-effective-standups
+      - sprint-planning
+      - stakeholder-communication
+
+  - name: "Team Strategy"
+    description: "Organize teams for delivery and growth"
+    modules:
+      - team-topologies
+      - risk-management
+      - incident-response
+
+  - name: "Scaling Impact"
+    description: "Drive organizational improvement"
+    modules:
+      - technical-debt
+      - { slug: engineering-metrics, title: "Engineering Metrics & OKRs" }
+      - { slug: tech-strategy, title: "Technical Strategy & Roadmaps" }

package/journeys/frontend-developer.yaml

@@ -0,0 +1,41 @@
+slug: frontend-developer
+title: "Frontend Developer"
+version: 1.0.0
+description: "From language fundamentals to production React apps — build modern, accessible web interfaces."
+icon: code
+tags: [frontend, web, react, javascript, typescript]
+difficulty: beginner-to-advanced
+estimated_hours: 35
+
+stages:
+  - name: "Language Foundations"
+    description: "Master TypeScript before diving into frameworks"
+    modules:
+      - typescript-fundamentals
+      - clean-code
+
+  - name: "Design Principles"
+    description: "Write maintainable, extensible code"
+    modules:
+      - solid-principles
+      - design-patterns
+
+  - name: "React Mastery"
+    description: "Components, hooks, state management, and the React mental model"
+    modules:
+      - react-fundamentals
+      - { slug: react-advanced-patterns, title: "React Advanced Patterns" }
+
+  - name: "Quality & Testing"
+    description: "Ship with confidence — testing strategy and accessibility"
+    modules:
+      - test-strategy
+      - accessibility-fundamentals
+      - { slug: frontend-testing, title: "Frontend Testing (Vitest + Playwright)" }
+
+  - name: "Professional Practice"
+    description: "Code review, debugging, and managing technical debt"
+    modules:
+      - code-review
+      - debugging-systematically
+      - technical-debt

package/journeys/fullstack-developer.yaml

@@ -0,0 +1,49 @@
+slug: fullstack-developer
+title: "Full-Stack Developer"
+version: 1.0.0
+description: "End-to-end mastery — from databases to React UIs, APIs to deployment."
+icon: layers
+tags: [fullstack, frontend, backend, react, api, sql]
+difficulty: beginner-to-advanced
+estimated_hours: 50
+
+stages:
+  - name: "Foundations"
+    description: "The building blocks every full-stack developer needs"
+    modules:
+      - typescript-fundamentals
+      - clean-code
+      - git
+
+  - name: "Data Layer"
+    description: "Store, query, and expose data through APIs"
+    modules:
+      - sql-fundamentals
+      - api-design
+
+  - name: "Frontend"
+    description: "Build modern, accessible user interfaces"
+    modules:
+      - react-fundamentals
+      - accessibility-fundamentals
+
+  - name: "Architecture & Design"
+    description: "Patterns for code that lasts"
+    modules:
+      - solid-principles
+      - design-patterns
+      - system-design
+
+  - name: "Quality"
+    description: "Testing, code review, and debugging across the stack"
+    modules:
+      - test-strategy
+      - code-review
+      - debugging-systematically
+
+  - name: "Production Readiness"
+    description: "Manage complexity and respond to incidents"
+    modules:
+      - technical-debt
+      - incident-response
+      - { slug: ci-cd-pipelines, title: "CI/CD Pipelines" }

package/journeys/mobile-developer.yaml

@@ -0,0 +1,42 @@
+slug: mobile-developer
+title: "Mobile Developer"
+version: 1.0.0
+description: "Build cross-platform mobile apps with React Native — from fundamentals to app store."
+icon: smartphone
+tags: [mobile, react-native, ios, android, cross-platform]
+difficulty: beginner-to-advanced
+estimated_hours: 35
+
+stages:
+  - name: "Language & Fundamentals"
+    description: "TypeScript and clean code — the foundation for React Native"
+    modules:
+      - typescript-fundamentals
+      - clean-code
+
+  - name: "React Core"
+    description: "Master React before going mobile"
+    modules:
+      - react-fundamentals
+      - solid-principles
+
+  - name: "React Native"
+    description: "Cross-platform mobile development"
+    modules:
+      - react-native-fundamentals
+      - { slug: mobile-navigation, title: "Mobile Navigation Patterns" }
+      - { slug: mobile-performance, title: "Mobile Performance Optimization" }
+
+  - name: "Quality & Testing"
+    description: "Test mobile apps effectively"
+    modules:
+      - test-strategy
+      - { slug: mobile-testing, title: "Mobile Testing (Detox + Maestro)" }
+      - accessibility-fundamentals
+
+  - name: "Ship It"
+    description: "From code review to the app store"
+    modules:
+      - code-review
+      - debugging-systematically
+      - { slug: app-store-deployment, title: "App Store Deployment" }

package/journeys/product-manager.yaml

@@ -0,0 +1,35 @@
+slug: product-manager
+title: "Product Manager"
+version: 1.0.0
+description: "Define, prioritize, and ship products — from PRDs to AI-assisted research."
+icon: target
+tags: [product, prd, prioritization, research, stakeholders]
+difficulty: beginner-to-advanced
+estimated_hours: 25
+
+stages:
+  - name: "Product Fundamentals"
+    description: "Write clear requirements and understand your users"
+    modules:
+      - writing-prds
+      - user-story-mapping
+
+  - name: "Prioritization & Planning"
+    description: "Decide what to build and when"
+    modules:
+      - prioritization-frameworks
+      - sprint-planning
+      - risk-management
+
+  - name: "Communication"
+    description: "Align stakeholders and drive decisions"
+    modules:
+      - stakeholder-communication
+      - { slug: product-analytics, title: "Product Analytics & Metrics" }
+
+  - name: "AI-Powered Product Work"
+    description: "Use AI to accelerate research and decision-making"
+    modules:
+      - ai-assisted-research
+      - prompt-engineering
+      - { slug: competitive-analysis, title: "Competitive Analysis with AI" }

package/journeys/qa-engineer.yaml

@@ -0,0 +1,37 @@
+slug: qa-engineer
+title: "QA Engineer"
+version: 1.0.0
+description: "From test strategy to AI-powered testing — ensure software quality at every level."
+icon: shield-check
+tags: [testing, qa, automation, exploratory, ai-testing]
+difficulty: beginner-to-advanced
+estimated_hours: 30
+
+stages:
+  - name: "Testing Foundations"
+    description: "Build a solid testing mindset and strategy"
+    modules:
+      - test-strategy
+      - clean-code
+      - debugging-systematically
+
+  - name: "Exploratory & Manual Testing"
+    description: "Find bugs humans miss — structured exploration"
+    modules:
+      - exploratory-testing
+      - user-story-mapping
+      - { slug: test-case-design, title: "Test Case Design Techniques" }
+
+  - name: "Automation & Tools"
+    description: "Automate what matters"
+    modules:
+      - typescript-fundamentals
+      - { slug: test-automation, title: "Test Automation Frameworks" }
+      - { slug: api-testing, title: "API Testing" }
+
+  - name: "AI-Powered Testing"
+    description: "Leverage AI for smarter, faster testing"
+    modules:
+      - ai-test-generation
+      - prompt-engineering
+      - { slug: visual-regression-testing, title: "Visual Regression Testing" }

package/journeys/ux-designer.yaml

@@ -0,0 +1,43 @@
+slug: ux-designer
+title: "UX Designer"
+version: 1.0.0
+description: "Design inclusive, user-centered experiences — from research to critique to accessible interfaces."
+icon: palette
+tags: [ux, design, accessibility, user-research, critique]
+difficulty: beginner-to-advanced
+estimated_hours: 30
+
+stages:
+  - name: "User Research"
+    description: "Understand your users before designing for them"
+    modules:
+      - user-story-mapping
+      - { slug: user-research-methods, title: "User Research Methods" }
+      - { slug: personas-and-journeys, title: "Personas & User Journeys" }
+
+  - name: "Design Foundations"
+    description: "Core design principles and critique skills"
+    modules:
+      - design-critique
+      - { slug: information-architecture, title: "Information Architecture" }
+      - { slug: interaction-design, title: "Interaction Design Patterns" }
+
+  - name: "Accessibility"
+    description: "Design for everyone — WCAG compliance and inclusive design"
+    modules:
+      - accessibility-fundamentals
+      - { slug: inclusive-design, title: "Inclusive Design Practices" }
+
+  - name: "Prototyping & Validation"
+    description: "Test your designs before building them"
+    modules:
+      - { slug: prototyping, title: "Prototyping & Wireframing" }
+      - { slug: usability-testing, title: "Usability Testing" }
+      - writing-prds
+
+  - name: "Design Operations"
+    description: "Scale design across teams and products"
+    modules:
+      - stakeholder-communication
+      - { slug: design-systems, title: "Design Systems" }
+      - { slug: design-handoff, title: "Design-to-Development Handoff" }

package/modules/README.md

@@ -0,0 +1,52 @@
+# @shaykec/modules
+
+[![npm version](https://img.shields.io/npm/v/@shaykec/modules)](https://www.npmjs.com/package/@shaykec/modules)
+
+Built-in learning modules that ship with Socrates. These are always available and serve as reference implementations for the module format.
+
+```bash
+npm install @shaykec/modules
+```
+
+## Built-in Modules
+
+| Module | Slug | Difficulty | Capabilities |
+|--------|------|-----------|-------------|
+| Git - Version Control Fundamentals | `git` | Beginner | content, walkthrough, exercises, quiz |
+| Claude Code Hooks | `hooks` | Intermediate | content |
+| A Day with Claude Code | `daily-workflow` | Beginner | content (narrative) |
+
+## Module Format
+
+Every module is a directory containing:
+
+| File | Required | Purpose |
+|------|----------|---------|
+| `module.yaml` | Yes | Metadata, XP values, triggers, visuals config |
+| `content.md` | Yes | Reference content (the "textbook") |
+| `walkthrough.md` | No | Step-by-step Socratic guided lesson |
+| `exercises.md` | No | Hands-on exercises with validation |
+| `quiz.md` | No | Multiple choice with explanations |
+| `quick-ref.md` | No | Cheat sheet / command reference |
+
+## Module Sources
+
+The registry scans three locations and merges them:
+
+| Source | Location | Purpose |
+|--------|----------|---------|
+| Built-in | `packages/modules/` | Ships with Socrates |
+| Installed packs | `~/.socrates/modules/<pack>/` | Git repos installed by the user |
+| Local custom | `~/.socrates/modules/local/` | User-authored modules |
+
+## Authoring New Modules
+
+Use `/teach:author <topic>` in Claude Code for guided creation, or scaffold manually:
+
+```bash
+socrates author init my-pack
+socrates author add my-pack/my-module
+socrates author validate my-pack
+```
+
+See the [root README](../../README.md) for the full module.yaml schema and authoring guide.

package/modules/accessibility-fundamentals/content.md

@@ -0,0 +1,126 @@
+# Accessibility — WCAG Fundamentals for Designers
+
+<!-- hint:slides topic="Accessibility: WCAG POUR principles, conformance levels, color contrast, keyboard navigation, semantic HTML, and ARIA" slides="6" -->
+
+## Why Accessibility Matters
+
+Accessibility (a11y) ensures products work for people with disabilities—including motor, cognitive, visual, and auditory. It's also:
+
+- **Legal** — Laws (ADA, Section 508, EU accessibility acts) require compliance.
+- **Ethical** — Equal access is a right.
+- **Business** — Larger audience, better SEO, often better UX for everyone.
+
+## WCAG POUR Principles
+
+WCAG 2.1 organizes guidelines under four principles (POUR):
+
+```mermaid
+flowchart TD
+    P[WCAG 2.1]
+    P --> P1[Perceivable]
+    P --> P2[Operable]
+    P --> P3[Understandable]
+    P --> P4[Robust]
+    P1 --> P1A[Info & UI presentable to users]
+    P2 --> P2A[UI operable by all]
+    P3 --> P3A[Info & UI understandable]
+    P4 --> P4A[Content interpretable by assistive tech]
+```
+
+| Principle | Meaning |
+|-----------|---------|
+| **Perceivable** | Information and UI must be presentable to users in ways they can perceive (text alternatives, captions, color not sole indicator). |
+| **Operable** | UI must be operable by everyone (keyboard, enough time, no seizure-inducing content). |
+| **Understandable** | Content and operation must be understandable (readable, predictable, input assistance). |
+| **Robust** | Content must be robust enough for assistive technologies (valid markup, correct roles). |
+
+## Conformance Levels
+
+| Level | Description |
+|-------|-------------|
+| **A** | Minimum—must satisfy to be accessible at all. |
+| **AA** | Target for most sites—addresses major barriers. Legal compliance often requires AA. |
+| **AAA** | Highest—enhanced accessibility. Not always achievable for all content. |
+
+**Practical target:** AA for text, UI, and media. Consider AAA for critical flows.
+
+## Color Contrast
+
+- **Normal text:** 4.5:1 contrast ratio (AA); 7:1 for AAA.
+- **Large text (18pt+ or 14pt+ bold):** 3:1 (AA); 4.5:1 (AAA).
+- **UI components:** 3:1 against adjacent colors.
+
+Use tools like WebAIM Contrast Checker or browser DevTools to verify.
+
+## Keyboard Navigation
+
+- All interactive elements must be reachable via **Tab**.
+- Focus order should follow visual order.
+- Focus must be visible (focus ring).
+- No keyboard traps.
+- Skip links and landmarks help keyboard users navigate quickly.
+
+## Screen Reader Basics
+
+Screen readers (NVDA, JAWS, VoiceOver) announce:
+- Headings and structure
+- Links and buttons
+- Form labels and errors
+- Live regions (dynamic updates)
+
+**Design implications:** Use semantic HTML, meaningful labels, and avoid "click here."
+
+## Semantic HTML
+
+Use the right element for the job:
+
+| Use | Element |
+|-----|---------|
+| Headings | `<h1>`–`<h6>` |
+| Links | `<a href="...">` |
+| Buttons | `<button>` |
+| Forms | `<label>`, `<input>`, `<select>` |
+| Landmarks | `<header>`, `<main>`, `<nav>`, `<footer>`, `<article>`, `<aside>` |
+
+Semantic HTML gives structure without extra ARIA in many cases.
+
+## ARIA: Roles, States, and Properties
+
+ARIA (Accessible Rich Internet Applications) fills gaps when HTML isn't enough:
+
+- **Roles** — `role="button"`, `role="dialog"`, `role="tablist"`
+- **States** — `aria-expanded`, `aria-selected`, `aria-checked`
+- **Properties** — `aria-label`, `aria-describedby`, `aria-labelledby`
+
+### When NOT to Use ARIA
+
+- Prefer native HTML when it exists (`<button>` > `role="button"` on a `<div>`).
+- Don't use ARIA to fix bad semantics—fix the HTML first.
+- Avoid redundant ARIA (e.g., `aria-label` on a visible `<button>` with text—usually unnecessary).
+
+## Focus Management
+
+- **Modals:** Trap focus inside; return focus on close.
+- **Dynamic content:** Move focus to new content when it appears (e.g., after form submit).
+- **Single-page apps:** Ensure route changes update announcements (e.g., `aria-live` or heading updates).
+
+## Alt Text Guidelines
+
+- **Informative images:** Describe the content or function. Be concise.
+- **Decorative images:** `alt=""` (empty) so screen readers skip them.
+- **Complex images:** Provide longer description (e.g., `longdesc` or nearby text).
+
+## Testing Tools
+
+| Tool | What It Helps With |
+|------|--------------------|
+| **axe DevTools** | Automated WCAG audits in browser |
+| **Lighthouse** | Accessibility audit + performance |
+| **WAVE** | Visual feedback on a11y issues |
+| **Screen readers** | NVDA (Windows), VoiceOver (macOS/iOS), TalkBack (Android) |
+
+**Rule:** Automated tools catch ~30% of issues. Manual testing with keyboard and screen reader is essential.
+
+## Summary
+
+Design for POUR: perceivable, operable, understandable, robust. Target WCAG AA. Ensure color contrast (4.5:1), keyboard access, semantic HTML, and sensible ARIA. Test with real users and assistive tech—automated tools are only the first step.