agentic-team-templates 0.15.0 → 0.17.0

package/templates/educator/CLAUDE.md

@@ -0,0 +1,338 @@
+# Educator Development Guide
+
+World-class guidelines for evidence-based teaching, learning retention, gamification, and assessment design.
+
+---
+
+## Overview
+
+This guide applies to:
+
+- Instructional design and lesson planning
+- Learning retention and memory science
+- Assessment design and mastery evaluation
+- Student engagement and motivation
+- Accessibility and inclusive education
+- Curriculum mapping and sequencing
+- Gamification and active learning
+
+### Key Principles
+
+1. **Backward Design** - Start with outcomes, then assessments, then instruction
+2. **Active Learning** - Learners construct knowledge through doing, not listening
+3. **Retrieval Practice** - Testing strengthens memory more than reviewing
+4. **Scaffolding and Fading** - Support learners, then gradually remove support
+5. **Universal Design** - Design for the margins to improve learning for everyone
+
+### Core Frameworks
+
+| Framework | Purpose |
+|-----------|---------|
+| Backward Design (Wiggins & McTighe) | Outcome-first instructional design |
+| Bloom's Taxonomy (Revised) | Classify cognitive complexity of objectives |
+| Cognitive Load Theory (Sweller) | Manage mental effort during learning |
+| Spaced Repetition (Ebbinghaus) | Optimize long-term retention |
+| Self-Determination Theory (Deci & Ryan) | Drive intrinsic motivation |
+| Universal Design for Learning (CAST) | Inclusive, flexible instruction |
+| Zone of Proximal Development (Vygotsky) | Calibrate challenge level |
+| Flow Theory (Csikszentmihalyi) | Sustain deep engagement |
+
+---
+
+## Instructional Design
+
+### Backward Design (Wiggins & McTighe)
+
+```
+Stage 1: Identify Desired Results
+├── What should learners understand?
+├── What essential questions will guide inquiry?
+└── What transfer goals apply?
+
+Stage 2: Determine Acceptable Evidence
+├── What performance tasks demonstrate understanding?
+├── What criteria define proficiency?
+└── What other evidence (quizzes, observations) is needed?
+
+Stage 3: Plan Learning Experiences
+├── What knowledge and skills do learners need?
+├── What activities will develop understanding?
+└── What sequence makes sense?
+```
+
+### Bloom's Taxonomy (Revised)
+
+```
+Higher Order ──────────────────────────── Lower Order
+
+Create    → Produce original work
+Evaluate  → Justify decisions
+Analyze   → Break into parts, find relationships
+Apply     → Use in new situations
+Understand → Explain ideas
+Remember  → Recall facts
+```
+
+### Writing Learning Objectives (ABCD Format)
+
+- **A**udience: Who is the learner?
+- **B**ehavior: What will they do? (observable verb)
+- **C**ondition: Under what circumstances?
+- **D**egree: To what standard?
+
+```markdown
+✅ "Given a dataset (C), the student (A) will identify and correct
+three types of data quality issues (B) with 90% accuracy (D)."
+
+❌ "Students will understand data quality."
+```
+
+### Cognitive Load Theory
+
+| Type | Description | Goal |
+|------|-------------|------|
+| **Intrinsic** | Inherent complexity of the material | Manage via sequencing and chunking |
+| **Extraneous** | Poor instructional design adding unnecessary load | Eliminate |
+| **Germane** | Effort devoted to building mental schemas | Maximize |
+
+### Scaffolding (Vygotsky's ZPD)
+
+```
+Lesson 1: Full modeling (I do)
+Lesson 2: Guided practice (We do)
+Lesson 3: Collaborative practice (You do together)
+Lesson 4: Independent practice (You do alone)
+Lesson 5: Transfer to new context (You do differently)
+```
+
+---
+
+## Learning Retention
+
+### The Forgetting Curve
+
+Without review, ~80% of material is forgotten within 2 days. Spaced review flattens the curve.
+
+### Spaced Repetition Schedule
+
+```
+Initial learning  → Review after 1 day
+Review 1 (Day 1)  → Review after 3 days
+Review 2 (Day 4)  → Review after 7 days
+Review 3 (Day 11) → Review after 14 days
+Review 4 (Day 25) → Review after 30 days
+```
+
+### Retrieval Practice
+
+Actively recalling information from memory strengthens the memory trace far more than re-reading.
+
+| Technique | Description |
+|-----------|-------------|
+| Free recall | Write everything you remember about a topic |
+| Practice testing | Low-stakes quizzes with feedback |
+| Concept mapping from memory | Draw relationships without notes |
+| Exit tickets | Brief end-of-class recall prompts |
+
+### Interleaving
+
+Mix different topics within practice sessions rather than blocking.
+
+```markdown
+❌ Blocked:      AAAA BBBB CCCC
+✅ Interleaved:  ABCA BCAB CABC
+```
+
+### Dual Coding
+
+Combine verbal and visual representations to create two memory pathways.
+
+### Desirable Difficulties
+
+Conditions that make learning feel harder often produce stronger long-term retention. Performance during learning ≠ learning itself.
+
+---
+
+## Assessment Design
+
+### Formative vs. Summative
+
+| Aspect | Formative | Summative |
+|--------|-----------|-----------|
+| Purpose | Guide instruction | Evaluate achievement |
+| Timing | During learning | After learning |
+| Stakes | Low (practice) | Higher (grading) |
+| Frequency | Every 10-15 min | End of unit/course |
+| Analogy | GPS during journey | Destination photo |
+
+### Rubric Best Practices
+
+1. Share rubrics before the assessment
+2. Use descriptive language, not evaluative
+3. Include examples at each level
+4. Limit criteria to 3-6
+5. Involve learners in co-creation when appropriate
+
+### Mastery-Based Progression
+
+Learners advance when they demonstrate mastery (80-90% on core objectives), not when a calendar date arrives. Allow multiple attempts.
+
+### Feedback Design
+
+```markdown
+1. What was done well (specific)
+2. What needs improvement (specific)
+3. Next step (actionable)
+```
+
+---
+
+## Engagement and Motivation
+
+### Self-Determination Theory (Deci & Ryan)
+
+```
+Intrinsic Motivation
+├── Autonomy: "I have choice and ownership"
+├── Competence: "I can succeed and grow"
+└── Relatedness: "I belong and am valued"
+```
+
+### Growth Mindset (Dweck)
+
+```markdown
+❌ "You're so smart!"           → ✅ "You worked really hard on that"
+❌ "This is easy, you'll get it" → ✅ "This is challenging—that's how you grow"
+```
+
+### Active Learning (10-Minute Rule)
+
+```
+[10 min input] → [5 min active processing] → [10 min input] → [5 min processing]
+```
+
+### Gamification Elements
+
+| Element | Purpose |
+|---------|---------|
+| XP / progress bars | Track cumulative progress |
+| Badges | Recognize specific mastery milestones |
+| Quests | Frame tasks as narrative challenges |
+| Streaks | Encourage consistent practice |
+
+### Gamification Anti-Patterns
+
+- Points for attendance (rewards showing up, not learning)
+- Competitive leaderboards as primary motivator
+- Extrinsic rewards that crowd out intrinsic motivation
+- Badges for trivial achievements
+
+---
+
+## Accessibility and Inclusion
+
+### Universal Design for Learning (CAST)
+
+| Principle | Focus |
+|-----------|-------|
+| Multiple Means of Representation | The "what" of learning |
+| Multiple Means of Action & Expression | The "how" of learning |
+| Multiple Means of Engagement | The "why" of learning |
+
+### Learning Styles: The Myth
+
+The "learning styles" model (visual, auditory, kinesthetic) is NOT supported by research. What works: multiple representations for ALL learners (UDL), matching modality to CONTENT type.
+
+### Accessible Materials Checklist
+
+- [ ] Sans-serif font, minimum 12pt, high contrast
+- [ ] Alt text for all meaningful images
+- [ ] Captions and transcripts for video/audio
+- [ ] Proper heading hierarchy
+- [ ] Multiple assessment formats available
+
+---
+
+## Curriculum Design
+
+### Spiral Curriculum (Bruner)
+
+Revisit key concepts at increasing levels of complexity throughout the curriculum.
+
+### Sequencing Principles
+
+| Strategy | When to Use |
+|----------|-------------|
+| Simple → Complex | Skill-building, mathematics |
+| Concrete → Abstract | Conceptual understanding |
+| Known → Unknown | Connecting to prior knowledge |
+| Whole → Part → Whole | Systems thinking |
+
+### Continuous Improvement Cycle
+
+```
+Teach → Assess → Analyze → Adjust → Re-teach
+```
+
+---
+
+## Definition of Done
+
+A lesson or module is complete when:
+
+- [ ] Learning objectives are specific, measurable, and aligned to Bloom's Taxonomy
+- [ ] Assessments directly measure stated objectives (backward design)
+- [ ] Content uses multiple representations (UDL Principle I)
+- [ ] Retrieval practice is embedded throughout
+- [ ] Spacing and interleaving are incorporated
+- [ ] Formative checks occur at least every 10-15 minutes
+- [ ] Feedback is immediate, specific, and actionable
+- [ ] Materials are accessible (captions, alt text, readable fonts)
+- [ ] Rubrics are shared with learners before assessment
+
+---
+
+## Common Pitfalls
+
+### 1. Coverage Over Depth
+
+❌ "We need to cover 15 chapters this semester"
+
+✅ "We need students to deeply understand 8 essential concepts"
+
+### 2. Activity-Driven Planning
+
+❌ "I found a great activity—let me build a lesson around it"
+
+✅ "What's the objective? What assessment shows mastery? Now, what activity supports that?"
+
+### 3. Re-reading as Study Strategy
+
+❌ "Read chapter 5 again for review"
+
+✅ "Close the book and write down everything you remember from chapter 5"
+
+### 4. Entertainment vs. Engagement
+
+❌ "Students loved the activity" (fun but no learning)
+
+✅ "Students wrestled with the concept and showed growth" (productive struggle)
+
+### 5. Participation ≠ Learning
+
+❌ "Everyone raised their hand, so they must understand"
+
+✅ Check actual understanding with retrieval practice
+
+---
+
+## Resources
+
+- [Make It Stick - Brown, Roediger & McDaniel](https://www.hup.harvard.edu/catalog.php?isbn=9780674729018)
+- [Understanding by Design - Wiggins & McTighe](https://www.ascd.org/books/understanding-by-design-expanded-2nd-edition)
+- [How Learning Works - Ambrose et al.](https://www.wiley.com/en-us/How+Learning+Works-p-9780470484104)
+- [Small Teaching - Lang](https://www.jamesmlang.com/small-teaching)
+- [Universal Design for Learning - CAST](https://www.cast.org/impact/universal-design-for-learning-udl)
+- [Visible Learning - Hattie](https://www.visiblelearning.com/)
+- [A Mind for Numbers - Oakley](https://barbaraoakley.com/books/a-mind-for-numbers/)
+- [Mindset - Dweck](https://mindsetonline.com/)

package/templates/ux-designer/.cursorrules/accessibility.md

@@ -0,0 +1,214 @@
+# Accessibility
+
+Designing inclusive experiences that work for all users regardless of ability, device, or context.
+
+## Core Principle
+
+**Accessibility is not a feature — it is a requirement.** An inaccessible product is a broken product. Design for the most constrained user and everyone benefits.
+
+## WCAG 2.2 AA — POUR Framework
+
+The Web Content Accessibility Guidelines organize requirements into four principles:
+
+### Perceivable
+
+Users must be able to perceive all information and UI components.
+
+```markdown
+Requirements:
+- Text alternatives for non-text content (alt text, aria-labels)
+- Captions and transcripts for audio/video content
+- Content adaptable to different presentations (screen reader, zoom, reflow)
+- Sufficient color contrast (4.5:1 for text, 3:1 for large text and UI components)
+- No information conveyed by color alone (add icons, text, patterns)
+- Text resizable up to 200% without loss of content or function
+- Content reflows at 320px width without horizontal scrolling
+```
+
+### Operable
+
+Users must be able to operate all UI components and navigation.
+
+```markdown
+Requirements:
+- All functionality available via keyboard
+- No keyboard traps (users can always Tab/Escape out)
+- Skip navigation link as first focusable element
+- Visible focus indicators on all interactive elements
+- No time limits (or provide extend/disable options)
+- No content that flashes more than 3 times per second
+- Page titles describe topic or purpose
+- Focus order follows logical reading sequence
+- Link purpose clear from link text alone (no "click here")
+- Multiple ways to find pages (navigation, search, sitemap)
+- Touch targets minimum 24x24px (44x44px recommended)
+```
+
+### Understandable
+
+Users must be able to understand the information and UI operation.
+
+```markdown
+Requirements:
+- Language of page declared in HTML lang attribute
+- Consistent navigation across pages
+- Consistent identification of UI components
+- Error identification with clear description
+- Labels or instructions for user input
+- Error prevention for legal/financial/data submissions (review before submit)
+- Context does not change unexpectedly on focus or input
+```
+
+### Robust
+
+Content must work with current and future assistive technologies.
+
+```markdown
+Requirements:
+- Valid HTML with proper semantic structure
+- Name, role, value programmatically determinable for all UI components
+- Status messages communicated via ARIA live regions without focus change
+- Compatible with screen readers, voice control, switch devices, and magnification
+```
+
+## Keyboard Navigation
+
+```markdown
+Requirements:
+- Tab: Move forward through focusable elements
+- Shift+Tab: Move backward
+- Enter/Space: Activate buttons and links
+- Arrow keys: Navigate within components (tabs, menus, radio groups)
+- Escape: Close modals, dropdowns, popovers
+- Home/End: Jump to first/last item in a list or slider
+
+Focus management:
+- Focus moves into modal when opened, returns to trigger when closed
+- Focus never gets lost or stuck
+- Focus indicators visible in all themes (light and dark)
+- Custom focus styles: minimum 2px solid outline with offset, 3:1 contrast ratio
+
+Tab order:
+- Follows visual layout (left-to-right, top-to-bottom in LTR languages)
+- Skip hidden/inactive elements
+- tabindex="0" for custom interactive elements
+- tabindex="-1" for programmatic focus (not in tab order)
+- Never use tabindex > 0 (breaks natural order)
+```
+
+## Screen Readers
+
+```markdown
+Semantic HTML:
+- Use <nav>, <main>, <header>, <footer>, <aside>, <section>, <article>
+- Headings form a logical outline (h1 → h2 → h3, no skipping levels)
+- Lists use <ul>/<ol>/<dl>, not styled divs
+- Tables use <th>, <caption>, and scope attributes
+- Forms use <label> associated with inputs via for/id
+
+ARIA (Accessible Rich Internet Applications):
+- Use native HTML elements first; ARIA is a supplement, not a replacement
+- aria-label: Name an element when visible text is insufficient
+- aria-describedby: Associate additional descriptions
+- aria-live="polite": Announce dynamic content changes (toasts, status updates)
+- aria-live="assertive": Interrupt for urgent messages (errors)
+- aria-expanded: Communicate open/closed state of collapsibles
+- aria-hidden="true": Hide decorative content from assistive tech
+- role attributes: Only when native HTML semantics are insufficient
+
+Testing:
+- Test with VoiceOver (macOS/iOS), NVDA or JAWS (Windows), TalkBack (Android)
+- Navigate the entire flow using only the screen reader
+- Verify all actions can be completed without visual reference
+```
+
+## ARIA Authoring Practices Guide (APG)
+
+Follow the WAI-ARIA APG patterns for complex components:
+
+```markdown
+Common patterns:
+- Accordion: aria-expanded, aria-controls, Enter/Space to toggle
+- Dialog (Modal): aria-modal, focus trap, Escape to close
+- Tabs: role="tablist"/"tab"/"tabpanel", Arrow keys to switch
+- Combobox: role="combobox", aria-autocomplete, list association
+- Menu: role="menu"/"menuitem", Arrow keys, Enter to select
+- Tooltip: role="tooltip", aria-describedby, Escape to dismiss
+- Disclosure: aria-expanded, controls relationship
+
+Rules:
+- Follow the APG keyboard interaction patterns exactly
+- Test with assistive technology, not just keyboard
+- Complex widgets need comprehensive ARIA markup
+```
+
+## Inclusive Design (Microsoft)
+
+Design for the full range of human diversity.
+
+```markdown
+Disability spectrum:
+  Permanent → Temporary → Situational
+  One arm    → Arm injury  → Carrying a baby
+  Blind      → Eye surgery → Driving
+  Deaf       → Ear infection → Loud environment
+  Non-verbal → Laryngitis  → Non-native speaker
+
+Principles:
+1. Recognize exclusion (who can't use this?)
+2. Learn from diversity (edge cases reveal design flaws)
+3. Solve for one, extend to many (curb cuts help wheelchairs, strollers, bikes)
+```
+
+## Cognitive Accessibility
+
+```markdown
+Guidelines:
+- Use plain language (aim for 8th-grade reading level)
+- Break content into short, scannable chunks
+- Use consistent and predictable patterns
+- Provide clear error messages with recovery instructions
+- Avoid time pressure (allow extended time or remove limits)
+- Support undo for destructive actions
+- Minimize required memory (show context, don't require recall)
+- Use familiar icons and established UI patterns
+- Progress indicators for multi-step processes
+- No unexpected changes in context
+```
+
+## Testing Checklist
+
+```markdown
+Automated (catch ~30% of issues):
+- axe-core or Lighthouse accessibility audit
+- Color contrast checker
+- HTML validation
+
+Manual (catch ~70% of issues):
+- Keyboard-only navigation (can you complete every task?)
+- Screen reader walkthrough (does every element announce correctly?)
+- Zoom to 200% (does content reflow without horizontal scroll?)
+- Color blindness simulation (is meaning preserved?)
+- Reduced motion test (does prefers-reduced-motion work?)
+- Touch target size verification (44x44px minimum)
+- Focus order verification (logical and predictable?)
+- Form error experience (clear, specific, recoverable?)
+
+User testing:
+- Include users with disabilities in research participants
+- Test with the assistive technologies your users actually use
+- Observe real behavior, don't rely on automated reports alone
+```
+
+## Anti-Patterns
+
+```markdown
+- Accessibility overlay widgets: Third-party "fix-it" overlays don't work and create new problems
+- Missing alt text: Images without alternatives are invisible to screen readers
+- Placeholder-only labels: Placeholders disappear on focus, leaving users without context
+- Focus suppression: outline: none without a replacement focus style
+- Mouse-only interactions: Drag-and-drop, hover reveals, or swipe without keyboard alternatives
+- CAPTCHAs without alternatives: Audio CAPTCHA or bypass for authenticated users
+- Auto-playing media: Audio or video that plays without user initiation
+- "Accessibility is done": It's never done — it requires ongoing testing and maintenance
+```