@shaykec/bridge 0.4.25 → 0.4.26

package/modules/code-review/resources.md

@@ -0,0 +1,40 @@
+# Code Review — Resources
+
+## Videos
+
+- [Code Review Best Practices](https://www.youtube.com/watch?v=0l_7Fy5_wfc) — Google Developers, ~20 min. Covers what reviewers look for, CL author tips, and reviewer guidance from Google's eng-practices.
+- [How to Give and Receive Code Reviews](https://www.youtube.com/watch?v=a9_2vv7C1_Y) — GOTO Conferences, ~45 min. Practical advice on feedback tone, prioritization, and team dynamics.
+
+## Articles and Readings
+
+- [Google Engineering Practices: Code Review](https://google.github.io/eng-practices/review/) — Google. Canonical guide: what to look for, CL author guide, reviewer guide. Key takeaway: correctness and design first; nits are optional.
+- [The CL Author's Guide](https://google.github.io/eng-practices/review/developer/) — Google. How to write good descriptions, scope PRs, and respond to feedback.
+- [How to Do a Code Review](https://google.github.io/eng-practices/review/reviewer/) — Google. Reviewer checklist, picking reviewers, in-person reviews.
+- [Code Review at Microsoft](https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-request-overview) — Microsoft. PR workflow and review practices in Azure DevOps.
+
+## Books
+
+- **The Clean Coder** by Robert C. Martin — Chapter on professional collaboration and accepting feedback. Why code review is part of professionalism.
+- **Software Team Lead's Handbook** by Christen Gilly — Sections on code review as a knowledge-sharing and quality mechanism.
+
+## Tools and Playgrounds
+
+- [GitHub Pull Requests](https://docs.github.com/en/pull-requests) — Native PR and review flow. Inline comments, suggestions, approval workflows.
+- [GitLab Merge Requests](https://docs.gitlab.com/ee/user/project/merge_requests/) — MR lifecycle, approval rules, code review features.
+- [Gerrit Code Review](https://www.gerritcodereview.com/) — Patch-based review used by many large open-source projects. Strong for strict workflows.
+
+## Podcasts
+
+- [Software Engineering Radio — Code Review](https://www.se-radio.net/) — Episodes on review culture and process.
+- [Changelog — Code Review Culture](https://changelog.com/podcast) — How top teams build effective review practices.
+- [Developer Tea — Giving Feedback](https://developertea.com/) — Short episodes on communication and feedback skills essential for reviews.
+
+## Interactive and Visual
+
+- [Conventional Comments](https://conventionalcomments.org/) — Labeling system for review comments (praise, suggestion, nitpick, etc.) with examples.
+- [ReviewBoard](https://www.reviewboard.org/) — Open-source code review tool with visual diff and comment threading.
+
+## Courses
+
+- [Google Engineering Practices — Full Guide (free)](https://google.github.io/eng-practices/) — Complete guide to Google's code review standards, reviewer and author guides.
+- [Pluralsight — Code Review Best Practices](https://www.pluralsight.com/) — Structured course on effective code reviews.

package/modules/code-review/walkthrough.md

@@ -0,0 +1,106 @@
+# Code Review Walkthrough — Learn by Doing
+
+## Before We Begin
+
+Code review works best when we treat feedback as a collaborative improvement, not a judgment. The goal is better code and shared learning—not winning an argument.
+
+**Diagnostic question:** When you've given or received code feedback, what made it feel helpful? What made it feel adversarial?
+
+**Checkpoint:** You can name one behavior that makes feedback land well and one that makes it land poorly.
+
+---
+
+## Step 1: Prepare Your Mindset
+
+Before reviewing or being reviewed, set the right frame.
+
+**Task:** Think of the last time someone critiqued your work (code or otherwise). How did you feel? What made it easier or harder to accept?
+
+**Question:** Why do you think code review comments can feel personal, even when they're about the code? What's one way to mentally separate feedback from identity?
+
+**Checkpoint:** The user should recognize that feedback targets the work, not the person, and that separating the two reduces defensiveness.
+
+---
+
+## Step 2: Write a PR Description
+
+Good descriptions make reviews faster and more accurate.
+
+**Task:** Pick a small change you've made recently (or imagine one). Write a PR description with "What", "Why", and "How" sections. Keep it under 10 lines.
+
+**Question:** What information would a reviewer need that isn't in the diff itself? Why does "Why" matter as much as "What"?
+
+**Checkpoint:** The user should include context (what problem it solves), rationale (why this approach), and enough technical detail for a reviewer to verify the change.
+
+---
+
+## Step 3: Turn a Vague Comment into a Good One
+
+Practice giving specific, constructive feedback.
+
+<!-- hint:code language="javascript" highlight="2,4" -->
+
+**Task:** You see this code in a PR:
+
+```javascript
+function findUser(id) {
+  for (let i = 0; i < users.length; i++) {
+    if (users[i].id === id) return users[i];
+  }
+  return null;
+}
+```
+
+Write three possible review comments: one vague, one specific but unhelpful, one specific and constructive (with a suggestion).
+
+**Question:** What makes the third comment more useful? How would it change the author's next steps?
+
+**Checkpoint:** The user produces a comment that explains the issue, why it matters, and suggests an improvement (e.g., `find()` or a Map for repeated lookups).
+
+---
+
+## Step 4: Prioritize Feedback
+
+Not all feedback is equal.
+
+<!-- hint:buttons type="single" prompt="What's the priority of 'API key hardcoded'?" options="Blocking,Should fix,Nit" -->
+
+**Task:** Given these hypothetical review comments, classify each as "blocking", "should fix", or "nit":
+
+1. "There's a potential null reference on line 42 when `response` is undefined."
+2. "Consider renaming `x` to `userCount` for clarity."
+3. "This API key is hardcoded; it should come from env."
+4. "I'd use `forEach` instead of `for` loop here."
+
+**Question:** What criteria help you decide whether something blocks merge vs is optional?
+
+**Checkpoint:** The user correctly prioritizes: (1) blocking, (2) nit, (3) blocking, (4) nit — and can explain why security and correctness trump style.
+
+---
+
+## Step 5: Respond to Feedback
+
+Practice receiving feedback gracefully.
+
+**Task:** Imagine a reviewer wrote: "This function is too long and does too much. Hard to test."
+
+Write two responses: one defensive, one constructive. The constructive response should either (a) ask a clarifying question, or (b) propose a concrete next step.
+
+**Question:** What does a "constructive" response accomplish that a defensive one doesn't?
+
+**Checkpoint:** The user's response acknowledges the concern and either asks for specifics or proposes refactoring into smaller, testable functions.
+
+---
+
+## Step 6: Build a Review Checklist
+
+Make reviews consistent and thorough.
+
+<!-- hint:list style="cards" -->
+<!-- hint:card type="tip" title="Best practices: correctness first, then tests, then readability" -->
+
+**Task:** Create a personal checklist of 5–7 items you'll check on every PR you review. Mix correctness, readability, and process (e.g., "PR has tests").
+
+**Question:** How might a checklist change your review behavior? What might you overlook without one?
+
+**Checkpoint:** The user's checklist covers at least correctness, tests, security considerations, and readability. They can explain why each item matters.

package/modules/daily-workflow/content.md

@@ -0,0 +1,81 @@
+# A Day with Claude Code
+
+> **Level: 🌱 Beginner** | *Story*
+
+## 8:30 AM — Starting the Day
+
+Maya opens her terminal and launches Claude Code in her team's monorepo. First thing she does every morning:
+
+```
+> /teach:stats
+```
+
+Her dashboard shows she's at Green Belt (180 XP) with 6 modules completed. She notices she's 220 XP away from Blue Belt. The level-up command suggests trying the "sub-agents" module next.
+
+But first, work.
+
+## 9:00 AM — Reviewing a PR
+
+A teammate's PR came in overnight. Maya asks Claude to help review it:
+
+```
+> Review PR #347 — focus on error handling and edge cases
+```
+
+Claude reads the diff, identifies a potential null pointer in the payment handler, and suggests a fix. Maya copies the feedback into the PR review. That interaction earns her a few bonus XP from the hooks tracking her tool usage.
+
+## 10:30 AM — Debugging a Production Issue
+
+An alert fires. The checkout flow is returning 500 errors for a subset of users. Maya opens Claude Code in the service repo:
+
+```
+> There's a 500 error in the checkout flow for users with expired promo codes.
+> Help me trace the issue.
+```
+
+Claude reads the error logs, follows the code path from the API endpoint through the promo code validator, and finds the bug: the validator throws an unhandled exception when the promo code's expiry date is null (legacy data).
+
+Maya fixes it with a null check, Claude helps write the test, and the hotfix ships by lunch.
+
+## 1:00 PM — Learning Something New
+
+After lunch, Maya has a 30-minute learning slot. She decides to try the hooks module:
+
+```
+> /teach hooks
+```
+
+The Socratic tutor walks her through lifecycle events, asking questions like "What do you think happens when a PostToolUse hook fails?" Instead of giving her the answer, it lets her reason about it — and she discovers that hooks should fail gracefully because they run synchronously.
+
+She gets through 4 of 7 walkthrough steps before her next meeting. Progress is saved automatically.
+
+## 3:00 PM — Building a Feature
+
+Back to feature work. Maya's building a new notification preferences page:
+
+```
+> I need a notification preferences page. Users should be able to toggle
+> email, push, and SMS notifications independently for each notification type
+> (marketing, transactional, security).
+```
+
+Claude scaffolds the component, creates the API endpoints, and writes the database migration. Maya reviews each piece, asks questions about the design choices, and makes a few adjustments.
+
+## 4:30 PM — Wrapping Up
+
+Before she leaves, Maya checks her stats one more time:
+
+```
+> /teach:stats
+```
+
+She earned 35 XP today — 15 from the hooks module walkthrough and 20 bonus from active tool usage (the production debugging session hit several categories). She's now at 215 XP, getting closer to Blue Belt.
+
+Tomorrow she'll finish the hooks walkthrough and maybe start on sub-agents.
+
+## What Made This Day Productive
+
+1. **Real work and learning blend together** — the production debugging wasn't a tutorial, but the hooks module directly helped Maya understand the tooling better.
+2. **Progress is visible** — XP and belts provide a tangible sense of growth.
+3. **Learning fits into small gaps** — 30 minutes with the Socratic tutor is enough to make real progress.
+4. **The AI adapts** — during the feature build, Claude is a productivity tool. During the learning slot, it switches to teaching mode.

package/modules/daily-workflow/exercises.md

@@ -0,0 +1,50 @@
+# A Day with Claude Code — Exercises
+
+## Exercise 1: Set Up a Claude Code Session and Check Stats
+
+**Task:** Start a Claude Code session in a project (or a test directory). Run the stats command to see your current XP and belt. Note how far you are from the next belt and what the level-up suggestion recommends.
+
+**Validation:**
+- [ ] Claude Code session started successfully
+- [ ] Stats command executed (e.g., `/teach:stats` or equivalent)
+- [ ] You can state your current XP and belt level
+- [ ] You can identify at least one suggested next step
+
+**Hints:**
+1. Ensure Claude Code is installed and configured for your workspace
+2. Stats may be available via a plugin command or slash command — check your setup
+3. If gamification isn't configured, the exercise still counts if you successfully ran the session
+
+---
+
+## Exercise 2: Use AI to Review a Real PR
+
+**Task:** Pick a real pull request — your own, a teammate's, or from an open-source repo you have cloned. Ask Claude to review it with a specific focus (e.g., error handling, security, readability). Incorporate at least one piece of Claude's feedback into your understanding or a comment.
+
+**Validation:**
+- [ ] PR identified and context provided to Claude
+- [ ] Review requested with a clear focus area
+- [ ] Claude's feedback received and understood
+- [ ] At least one actionable insight applied (comment written, or mental note for future PRs)
+
+**Hints:**
+1. Smaller PRs (under ~400 lines) work best for focused review
+2. Specify the focus: "error handling," "edge cases," "naming" — it improves the quality of feedback
+3. You can copy Claude's suggestions into GitHub/GitLab review comments
+
+---
+
+## Exercise 3: Use AI to Debug an Issue
+
+**Task:** Find or create a bug — a failing test, a runtime error, or unexpected behavior. Describe it to Claude with relevant context (error message, stack trace, steps to reproduce). Work through Claude's suggested investigation steps, identify the root cause, and apply a fix.
+
+**Validation:**
+- [ ] Bug described with sufficient context (error, logs, or reproduction steps)
+- [ ] Investigation followed (code path traced, hypothesis formed)
+- [ ] Root cause identified
+- [ ] Fix applied and verified (test passes or error resolved)
+
+**Hints:**
+1. Start with the error message — paste it verbatim
+2. If Claude suggests a hypothesis, try it (add a null check, add a test) to validate
+3. Writing a test for the fix (with Claude's help) reinforces the debugging session

package/modules/daily-workflow/module.yaml

@@ -0,0 +1,33 @@
+slug: daily-workflow
+title: "A Day with Claude Code"
+version: 1.0.0
+description: "Story: follow a developer through a typical day using Claude Code for real tasks."
+category: claude-code
+tags: [claude-code, workflow, story, productivity]
+difficulty: beginner
+narrative: true
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 10
+  guided: 45
+
+prerequisites: []
+related: [hooks, skills, sub-agents]
+
+visuals:
+  diagrams: [diagram-flow, diagram-mermaid]
+  quiz-types: [quiz-matching, quiz-timed-choice]
+  playground: bash
+
+triggers:
+  - "What does a typical day with Claude Code look like?"
+  - "How do people actually use Claude Code?"
+  - "Show me a real workflow with Claude Code"

package/modules/daily-workflow/quick-ref.md

@@ -0,0 +1,37 @@
+# A Day with Claude Code — Quick Reference
+
+## Claude Code Commands
+
+| Command | Purpose |
+|---|---|
+| `/teach:stats` | View XP, belt level, and suggested next modules |
+| `/teach:level-up` | See belt roadmap and personalized suggestions |
+| `/teach <module>` | Start Socratic teaching for a module (e.g., `hooks`) |
+| `/teach:canvas` | Open the visual canvas (diagrams, quizzes) |
+| `/teach:learn <topic>` | Free-style learning — generate a module on any topic |
+
+## Workflow Patterns
+
+| Scenario | Approach |
+|---|---|
+| **Morning** | Run stats, note current belt and suggested next module |
+| **PR review** | "Review PR #N — focus on [error handling | security | readability]" |
+| **Debugging** | Provide error, logs, steps to reproduce; ask Claude to trace and suggest fixes |
+| **Learning slot** | `/teach <module>` — 30 min is enough for 3–4 walkthrough steps |
+| **Feature build** | Describe feature in natural language; review each generated piece |
+| **End of day** | Run stats again; reflect on XP earned from work vs. learning |
+
+## XP Sources
+
+| Source | Example |
+|---|---|
+| **Module completion** | Finishing walkthrough steps, passing quizzes |
+| **Tool usage** | Production debugging, PR review, code generation |
+| **Games & exercises** | Interactive exercises, workshop scenarios |
+
+## Key Principles
+
+- **Blend work and learning** — Use Claude for real tasks and for teaching in the same day
+- **Progress is visible** — XP and belts make growth tangible
+- **Learning fits gaps** — Short sessions (e.g., 30 min) are effective
+- **AI adapts to context** — Productivity mode for features; teaching mode for `/teach`

package/modules/daily-workflow/quiz.md

@@ -0,0 +1,65 @@
+# A Day with Claude Code — Quiz
+
+## Question 1
+
+What does `/teach:stats` show you?
+
+A) Only your completed modules
+B) XP, belt level, and suggestions for what to learn next
+C) A list of all available modules
+D) Your recent chat history
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The stats dashboard displays your current XP total, your belt level (e.g., Green Belt), how far you are from the next belt, and personalized suggestions like "try the sub-agents module next." -->
+
+## Question 2
+
+<!-- VISUAL: matching -->
+
+Match the scenario to the Claude Code feature that helps:
+
+| Scenario | Feature |
+|----------|---------|
+| A) Teammate's PR needs review | 1) `/teach:stats` |
+| B) Want to see learning progress | 2) Natural language PR review request |
+| C) Need to learn hooks | 3) `/teach <module>` |
+| D) Production 500 error | 4) Debugging prompt with logs and context |
+
+<!-- ANSWER: A-2, B-1, C-3, D-4 -->
+<!-- EXPLANATION: PR review uses natural language ("Review PR #347 — focus on error handling"). Stats uses /teach:stats. Learning uses /teach <module>. Debugging uses descriptive prompts with context. -->
+
+## Question 3
+
+Why might checking stats in the morning and again at end of day be useful?
+
+A) It's required for Claude Code to work
+B) It makes progress visible and reinforces productive habits
+C) It resets your XP for the day
+D) It syncs with team dashboards
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Visible progress (XP gains, belt advancement) reinforces the blend of real work and learning. Seeing "I earned 35 XP today" makes both productive sessions and learning sessions feel tangible. -->
+
+## Question 4
+
+During a debugging session, what does the human typically provide that Claude needs?
+
+A) Nothing — Claude reads everything automatically
+B) Error logs, stack traces, and domain context
+C) Only the file path to the bug
+D) A pre-written fix to apply
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Claude needs context to debug effectively: error messages, stack traces, which users are affected, and domain knowledge (e.g., "users with expired promo codes"). The human supplies this; Claude traces the code path and suggests fixes. -->
+
+## Question 5
+
+What is the main benefit of Socratic teaching (asking questions instead of giving answers) in a learning session?
+
+A) It's faster than reading documentation
+B) It forces active reasoning, which improves retention
+C) It reduces the number of modules available
+D) It requires less setup
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: When you reason through "What do you think happens when a PostToolUse hook fails?" instead of being told the answer, you discover it yourself. That active engagement leads to better retention than passive reading. -->

package/modules/daily-workflow/resources.md

@@ -0,0 +1,38 @@
+# A Day with Claude Code — Resources
+
+## Official Docs
+
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) — Setup, commands, and configuration.
+- [Claude Code Best Practices](https://docs.anthropic.com/en/docs/claude-code/best-practices) — Prompt tips and workflow patterns for productive sessions.
+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) — Practical examples and patterns for building with Claude.
+
+## Videos
+
+- [Claude Code in 100 Seconds](https://www.youtube.com/results?search_query=claude+code+100+seconds) — Quick overview of what Claude Code is and does.
+- [Cursor AI — Full Tutorial](https://www.youtube.com/results?search_query=cursor+ai+full+tutorial) — Demonstrates AI-assisted coding workflows similar to Claude Code.
+- [AI Coding Assistants Compared](https://www.youtube.com/results?search_query=ai+coding+assistants+compared+2025) — Context on where Claude Code fits in the AI tooling landscape.
+
+## Articles and Readings
+
+- [Anthropic's Blog — Claude Code](https://www.anthropic.com/news) — Launch announcements and capability updates.
+- [Simon Willison — AI-Assisted Development](https://simonwillison.net/series/ai/) — Practical insights on coding with AI assistants.
+- [Addy Osmani — AI-Assisted Development](https://addyosmani.com/blog/) — Patterns for productive human-AI collaboration.
+- [Swyx — AI Engineering](https://www.latent.space/) — Latent Space blog and podcast on AI tooling.
+
+## Books
+
+- **The Pragmatic Programmer** by Hunt & Thomas — Foundational productivity practices that pair well with AI assistance. [pragprog.com](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/).
+- **Deep Work** by Cal Newport — Focus strategies relevant to getting the most from AI pairing sessions.
+
+## Podcasts
+
+- [Latent Space](https://www.latent.space/podcast) — AI engineering podcast covering coding agents and developer tools.
+- [Changelog](https://changelog.com/podcast) — Developer-focused show with episodes on AI-assisted workflows.
+- [Software Engineering Daily](https://softwareengineeringdaily.com/) — Technical deep dives, frequent AI/ML tooling episodes.
+
+## Tools
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — The CLI agent featured in this module.
+- [GitHub Copilot](https://github.com/features/copilot) — AI pair programmer for comparison and complementary use.
+- [aider](https://aider.chat/) — Open-source AI coding assistant in the terminal.
+- [Cursor](https://cursor.com/) — AI-native code editor with similar agent capabilities.

package/modules/daily-workflow/walkthrough.md

@@ -0,0 +1,83 @@
+# Daily Workflow Walkthrough — Learn by Doing
+
+## Before We Begin
+
+<!-- hint:buttons type="multi" prompt="Which of these do you use regularly?" options="AI coding assistants,Code review tools,Automated testing,Learning platforms,None of these" -->
+<!-- hint:card type="concept" title="AI-Assisted Development" -->
+
+**Question:** How do you currently use your development tools throughout a typical day? Where do you spend the most time — writing code, reviewing, debugging, or learning?
+
+**Checkpoint:** The user can describe their current workflow and identify at least one area where AI assistance could help.
+
+---
+
+## Step 1: Morning Setup and Stats
+
+<!-- hint:terminal -->
+
+**Task:** Open your terminal and run `/teach:stats` to check your current XP and belt. Then run `/teach list` to see available modules. Note which modules you've completed and which are recommended next.
+
+**Question:** Why might checking your learning progress at the start of the day be useful? How does it connect to deliberate practice?
+
+**Checkpoint:** The user has run both commands and can describe their current progress.
+
+---
+
+## Step 2: Reviewing Code with AI
+
+<!-- hint:list style="numbered" -->
+
+**Task:** Find a recent PR or code change (yours or a teammate's). Ask your AI assistant to review it, focusing on error handling and edge cases. Compare the AI's feedback to what you would have caught yourself.
+
+**Question:** What did the AI catch that you might have missed? What did it miss that you noticed? When should you trust AI feedback vs. apply your own judgment?
+
+**Checkpoint:** The user can articulate the strengths and limitations of AI-assisted code review.
+
+---
+
+## Step 3: Debugging with AI Assistance
+
+<!-- hint:diagram mermaid-type="flowchart" topic="AI-assisted debugging flow: describe bug, AI reads code, trace path, identify root cause, fix and test" -->
+
+**Task:** Think of a recent bug you encountered (or use a hypothetical one). Describe it to your AI assistant with context: the error message, the expected behavior, and the actual behavior. Walk through the debugging process together.
+
+**Question:** How did providing context change the quality of the AI's suggestions? What's the minimum context needed for useful debugging help?
+
+**Checkpoint:** The user understands that AI debugging quality depends heavily on the context provided.
+
+---
+
+## Step 4: Learning During the Day
+
+<!-- hint:buttons type="single" prompt="How would you fit learning into your day?" options="Dedicated 30-min block,Between meetings,After finishing a task,During code review" -->
+
+**Task:** Choose a module from `/teach list` that relates to something you're working on this week. Start the walkthrough and complete at least 2 steps. Notice how the Socratic method asks you to think before giving answers.
+
+**Question:** How is learning through guided questions different from reading documentation? Which approach helps you retain more?
+
+**Checkpoint:** The user has started a module and can explain the value of active recall over passive reading.
+
+---
+
+## Step 5: Building a Feature with AI
+
+<!-- hint:code language="javascript" -->
+
+**Task:** Pick a small feature or improvement in your project. Use your AI assistant to help plan it: describe what you want, ask it to outline the approach, then implement it yourself (with AI help for specific questions). Track how you divide the work.
+
+**Question:** What parts of the feature were faster with AI help? What parts required your own expertise and judgment? Where's the line between productive AI use and over-reliance?
+
+**Checkpoint:** The user can describe a healthy division of labor between themselves and AI tools.
+
+---
+
+## Step 6: End-of-Day Reflection
+
+<!-- hint:buttons type="rating" prompt="How productive did you feel today with AI assistance?" -->
+<!-- hint:celebrate -->
+
+**Task:** Review what you accomplished today. Run `/teach:stats` again and compare to the morning. Write a brief note (mental or written) about: one thing AI helped with, one thing you did better yourself, and one thing you want to learn tomorrow.
+
+**Question:** How would you design your ideal daily workflow that balances AI assistance, independent work, and continuous learning?
+
+**Checkpoint:** The user can articulate a personal workflow that integrates AI tools without depending on them.