agileflow 2.51.0 → 2.55.0

package/src/core/skills/agileflow-retro-facilitator/cookbook/glad-sad-mad.md

@@ -0,0 +1,79 @@
+# Glad/Sad/Mad Retrospective Format
+
+Best for emotional topics and team dynamics. Use when morale is low or interpersonal issues need addressing.
+
+## When to Use
+
+- Team seems frustrated or burnt out
+- Recent conflicts or tensions
+- Major changes (team composition, process, tools)
+- After particularly difficult sprints
+- When standard retro feels stale
+
+## Template
+
+```markdown
+# Glad/Sad/Mad Retrospective
+
+**Date**: YYYY-MM-DD
+**Facilitator**: [Name]
+**Attendees**: [Team members present]
+**Context**: [Why using this format]
+
+## Glad (Things that made us happy)
+
+- [Glad 1: Celebration or positive moment]
+- [Glad 2: Something that worked well]
+- [Glad 3: Team success]
+
+## Sad (Things that disappointed us)
+
+- [Sad 1: Unmet expectation]
+- [Sad 2: Missed opportunity]
+- [Sad 3: Something we hoped would go better]
+
+## Mad (Things that frustrated us)
+
+- [Mad 1: Recurring problem]
+- [Mad 2: Blocker or impediment]
+- [Mad 3: Process that isn't working]
+
+## Patterns Identified
+
+- [Pattern 1: Theme across categories]
+- [Pattern 2: Root cause analysis]
+
+## Action Items
+
+- [ ] **[Action 1]** - @Owner - Due: [Date]
+  - Addresses: [Which Sad/Mad item]
+
+- [ ] **[Action 2]** - @Owner - Due: [Date]
+  - Addresses: [Which Sad/Mad item]
+
+## What We Want to Protect
+
+- [Glad item to protect and maintain]
+- [Process or practice to keep]
+```
+
+## Facilitation Notes
+
+**Creating Psychological Safety**:
+- Acknowledge that emotions are valid
+- Focus on situations, not individuals
+- Use "I feel..." statements
+- Allow venting, then redirect to solutions
+
+**Timing**:
+- Glad: 10 minutes
+- Sad: 15 minutes
+- Mad: 15 minutes
+- Action Items: 15 minutes
+- Total: ~60 minutes
+
+**Tips**:
+- Start with Glad to set positive tone
+- Let people express frustration fully before problem-solving
+- End with concrete actions to channel emotions productively
+- Follow up on emotional items in 1:1s if needed

package/src/core/skills/agileflow-retro-facilitator/cookbook/start-stop-continue.md

@@ -0,0 +1,142 @@
+# Start/Stop/Continue Retrospective Format
+
+The standard format for sprint retrospectives. Best for regular, recurring retros.
+
+## Template
+
+```markdown
+# Sprint [Number] Retrospective
+
+**Date**: YYYY-MM-DD
+**Facilitator**: [Name]
+**Attendees**: [Team members present]
+**Sprint Duration**: [Start] - [End]
+
+## Sprint Metrics
+
+- **Committed**: X story points
+- **Completed**: Y story points
+- **Velocity**: Z%
+- **Stories Done**: A / B
+- **Bugs Found**: C
+
+## What Went Well
+
+- [Positive 1: Specific thing that worked]
+- [Positive 2: Team success]
+- [Positive 3: Process improvement]
+
+## What Didn't Go Well
+
+- [Challenge 1: Specific problem]
+- [Challenge 2: Blocker or delay]
+- [Challenge 3: Process issue]
+
+## Start (New Practices)
+
+- **[Practice 1]**
+  - Why: [Reasoning]
+  - Owner: [Who will drive this]
+  - Success metric: [How we'll measure]
+
+## Stop (Remove Practices)
+
+- **[Practice 1]**
+  - Why it's not working: [Reasoning]
+  - Alternative: [What we'll do instead]
+
+## Continue (Keep Doing)
+
+- **[Practice 1]**
+  - Why it's working: [Reasoning]
+  - How to maintain: [Keep it going]
+
+## Action Items
+
+- [ ] **[Action 1]** - @Owner - Due: [Date]
+  - Success criteria: [How we know it's done]
+
+- [ ] **[Action 2]** - @Owner - Due: [Date]
+  - Success criteria: [How we know it's done]
+
+## Previous Action Items Review
+
+- [] **[Completed Action]** - Implemented, improved X by Y%
+- [] **[In Progress Action]** - Still working on it, 60% done
+- [] **[Not Done Action]** - Blocked by Z, rolling to next sprint
+
+## Key Insights
+
+1. [Insight 1: Pattern or learning]
+2. [Insight 2: Team dynamic observation]
+3. [Insight 3: Process discovery]
+```
+
+## Metrics to Track
+
+**Sprint Health**:
+- Velocity trend (increasing, stable, decreasing?)
+- Commitment accuracy (completed vs committed)
+- Bug count (increasing, decreasing?)
+- Blocker frequency
+
+**Team Health**:
+- Meeting effectiveness
+- Communication quality
+- Collaboration level
+- Work-life balance
+
+**Process Health**:
+- Cycle time (story start to done)
+- Code review turnaround
+- Deployment frequency
+- Incident count
+
+## Common Themes to Watch For
+
+**Positive Patterns**:
+- Consistent velocity
+- Low bug count
+- Fast code reviews
+- Clear requirements
+- Good collaboration
+
+**Warning Signs**:
+- Declining velocity
+- Recurring blockers
+- Communication issues
+- Scope creep
+- Burnout indicators
+
+## Facilitator Tips
+
+**Do**:
+- Create safe space for honest feedback
+- Focus on process, not people
+- Time-box discussions (5-10 min per topic)
+- Ensure everyone participates
+- End on positive note
+- Follow up on action items
+
+**Don't**:
+- Blame individuals
+- Let discussions run too long
+- Skip retros ("too busy")
+- Create action items without owners
+- Ignore previous action items
+
+## Remote Retro Adaptations
+
+For distributed teams:
+- Use anonymous feedback tools (Retrium, Metro Retro)
+- Give time for async reflection before meeting
+- Use polls/voting for prioritization
+- Record session for absent team members
+- Use collaborative docs for brainstorming
+
+## Frequency Guidelines
+
+- **Every sprint**: Standard retros (60-90 min)
+- **Major milestones**: Extended retros (2-3 hours)
+- **Quarterly**: Big-picture retros (process, tools, culture)
+- **Post-incident**: Blameless postmortems (as needed)

package/src/core/skills/agileflow-retro-facilitator/prompts/action-items.md

@@ -0,0 +1,83 @@
+# Action Items Template
+
+Shared template for creating SMART action items across all retro formats.
+
+## SMART Action Items
+
+- **S**pecific: Clear what needs to be done
+- **M**easurable: Can verify it's complete
+- **A**ssignable: Has an owner
+- **R**elevant: Addresses the issue
+- **T**ime-bound: Has a deadline
+
+## Good vs Bad Examples
+
+**Good (Specific, Actionable)**:
+```
+- [ ] **Create PR size guideline** - @TechLead - Due: Before next sprint
+  - Success criteria: Document written, shared with team, added to CLAUDE.md
+  - Metric: 80% of PRs under 300 lines
+```
+
+**Bad (Vague, Unactionable)**:
+```
+- [ ] Fix code reviews
+- [ ] Be better at communication
+- [ ] Improve quality
+```
+
+## Good vs Bad Feedback
+
+**Good (Specific, Constructive)**:
+```
+"Daily standups ran long (20+ min) because we discussed
+implementation details. Consider moving technical discussions
+to separate sessions."
+
+"Code reviews were faster this sprint (avg 4 hours vs 24 hours
+last sprint) thanks to smaller PR sizes."
+```
+
+**Bad (Vague, Blame-Oriented)**:
+```
+"Meetings were bad"
+"Bob didn't do his job"
+"Everything was terrible"
+"Process is broken"
+```
+
+## Action Item Template
+
+```markdown
+- [ ] **[Specific Action]** - @Owner - Due: [Date]
+  - Context: [What retro item this addresses]
+  - Success criteria: [How we know it's done]
+  - Metric: [Measurable outcome if applicable]
+```
+
+## Tracking Action Items
+
+**Status Markers**:
+- `[ ]` - Not started
+- `[~]` - In progress
+- `[x]` - Completed
+- `[!]` - Blocked
+- `[-]` - Cancelled/Deferred
+
+**Review Format**:
+```markdown
+## Previous Action Items Review
+
+- [x] **[Completed Action]** - Implemented, improved X by Y%
+- [~] **[In Progress Action]** - 60% done, on track for next week
+- [!] **[Blocked Action]** - Blocked by Z, need help from [team]
+- [-] **[Cancelled Action]** - No longer relevant due to [reason]
+```
+
+## Best Practices
+
+1. **Limit to 3-5 actions per retro** - More than 5 rarely get done
+2. **Assign single owners** - Shared ownership = no ownership
+3. **Set realistic deadlines** - Usually before next retro
+4. **Review at next retro** - Accountability matters
+5. **Track completion rate** - Target: >80%

package/src/core/skills/writing-skills/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: writing-skills
+description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
+---
+
+# Writing Skills
+
+## Overview
+
+**Writing skills IS Test-Driven Development applied to process documentation.**
+
+You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
+
+## What is a Skill?
+
+A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
+
+**Skills are:** Reusable techniques, patterns, tools, reference guides
+
+**Skills are NOT:** Narratives about how you solved a problem once
+
+## TDD Mapping for Skills
+
+| TDD Concept | Skill Creation |
+|-------------|----------------|
+| **Test case** | Pressure scenario with subagent |
+| **Production code** | Skill document (SKILL.md) |
+| **Test fails (RED)** | Agent violates rule without skill (baseline) |
+| **Test passes (GREEN)** | Agent complies with skill present |
+| **Refactor** | Close loopholes while maintaining compliance |
+| **Write test first** | Run baseline scenario BEFORE writing skill |
+| **Watch it fail** | Document exact rationalizations agent uses |
+| **Minimal code** | Write skill addressing those specific violations |
+| **Watch it pass** | Verify agent now complies |
+| **Refactor cycle** | Find new rationalizations → plug → re-verify |
+
+## When to Create a Skill
+
+**Create when:**
+- Technique wasn't intuitively obvious to you
+- You'd reference this again across projects
+- Pattern applies broadly (not project-specific)
+- Others would benefit
+
+**Don't create for:**
+- One-off solutions
+- Standard practices well-documented elsewhere
+- Project-specific conventions (put in CLAUDE.md)
+- Mechanical constraints (if enforceable with validation, automate it)
+
+## Skill Types
+
+### Technique
+Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
+
+### Pattern
+Way of thinking about problems (flatten-with-flags, test-invariants)
+
+### Reference
+API docs, syntax guides, tool documentation
+
+## Directory Structure
+
+```
+skills/
+  skill-name/
+    SKILL.md              # Main reference (required)
+    cookbook/             # Per-use-case docs (if multiple workflows)
+    prompts/              # Reusable prompt templates
+    tools/                # Scripts, utilities
+    supporting-file.*     # Only if needed
+```
+
+**Flat namespace** - all skills in one searchable namespace
+
+**Separate files for:**
+1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
+2. **Reusable tools** - Scripts, utilities, templates
+3. **Multiple workflows** - Use cookbook/ pattern for progressive disclosure
+
+**Keep inline:**
+- Principles and concepts
+- Code patterns (< 50 lines)
+- Everything else
+
+## SKILL.md Structure
+
+**Frontmatter (YAML):**
+- Only two fields supported: `name` and `description`
+- Max 1024 characters total
+- `name`: Use letters, numbers, and hyphens only
+- `description`: Third-person, describes ONLY when to use (NOT what it does)
+
+```markdown
+---
+name: skill-name-with-hyphens
+description: Use when [specific triggering conditions and symptoms]
+---
+
+# Skill Name
+
+## Overview
+What is this? Core principle in 1-2 sentences.
+
+## When to Use
+Bullet list with SYMPTOMS and use cases
+When NOT to use
+
+## Variables (if using cookbook pattern)
+Feature flags for conditional behavior
+
+## Cookbook (if multiple workflows)
+If condition A → read cookbook/a.md
+If condition B → read cookbook/b.md
+
+## Core Pattern (for techniques/patterns)
+Before/after code comparison
+
+## Quick Reference
+Table or bullets for scanning common operations
+
+## Implementation
+Inline code for simple patterns
+Link to file for heavy reference
+
+## Common Mistakes
+What goes wrong + fixes
+```
+
+## Claude Search Optimization (CSO)
+
+**Critical for discovery:** Future Claude needs to FIND your skill
+
+### 1. Rich Description Field
+
+**Purpose:** Claude reads description to decide which skills to load. Make it answer: "Should I read this skill right now?"
+
+**Format:** Start with "Use when..." to focus on triggering conditions
+
+**CRITICAL: Description = When to Use, NOT What the Skill Does**
+
+```yaml
+# BAD: Summarizes workflow - Claude may follow this instead of reading skill
+description: Use when executing plans - dispatches subagent per task with code review
+
+# GOOD: Just triggering conditions, no workflow summary
+description: Use when executing implementation plans with independent tasks
+```
+
+### 2. Keyword Coverage
+
+Use words Claude would search for:
+- Error messages: "Hook timed out", "race condition"
+- Symptoms: "flaky", "hanging", "zombie"
+- Synonyms: "timeout/hang/freeze", "cleanup/teardown"
+- Tools: Actual commands, library names, file types
+
+### 3. Descriptive Naming
+
+**Use active voice, verb-first:**
+- `creating-skills` not `skill-creation`
+- `condition-based-waiting` not `async-test-helpers`
+
+### 4. Token Efficiency
+
+**Target word counts:**
+- Frequently-loaded skills: <200 words total
+- Other skills: <500 words (still be concise)
+
+**Techniques:**
+- Move details to tool help
+- Use cross-references to other skills
+- Compress examples
+- Eliminate redundancy
+
+## The Iron Law
+
+```
+NO SKILL WITHOUT A FAILING TEST FIRST
+```
+
+This applies to NEW skills AND EDITS to existing skills.
+
+Write skill before testing? Delete it. Start over.
+Edit skill without testing? Same violation.
+
+**No exceptions:**
+- Not for "simple additions"
+- Not for "just adding a section"
+- Not for "documentation updates"
+- Delete means delete
+
+## Testing Skill Types
+
+### Discipline-Enforcing Skills (rules/requirements)
+
+**Test with:**
+- Academic questions: Do they understand the rules?
+- Pressure scenarios: Do they comply under stress?
+- Multiple pressures combined: time + sunk cost + exhaustion
+
+**Success criteria:** Agent follows rule under maximum pressure
+
+### Technique Skills (how-to guides)
+
+**Test with:**
+- Application scenarios: Can they apply the technique correctly?
+- Variation scenarios: Do they handle edge cases?
+- Missing information tests: Do instructions have gaps?
+
+**Success criteria:** Agent successfully applies technique to new scenario
+
+### Pattern Skills (mental models)
+
+**Test with:**
+- Recognition scenarios: Do they recognize when pattern applies?
+- Counter-examples: Do they know when NOT to apply?
+
+**Success criteria:** Agent correctly identifies when/how to apply pattern
+
+### Reference Skills (documentation/APIs)
+
+**Test with:**
+- Retrieval scenarios: Can they find the right information?
+- Gap testing: Are common use cases covered?
+
+**Success criteria:** Agent finds and correctly applies reference information
+
+## Common Rationalizations for Skipping Testing
+
+| Excuse | Reality |
+|--------|---------|
+| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
+| "It's just a reference" | References can have gaps. Test retrieval. |
+| "Testing is overkill" | Untested skills have issues. Always. |
+| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE. |
+| "Too tedious to test" | Testing is less tedious than debugging later. |
+| "No time to test" | Deploying untested wastes more time fixing later. |
+
+## Bulletproofing Against Rationalization
+
+### Close Every Loophole Explicitly
+
+Don't just state the rule - forbid specific workarounds:
+
+```markdown
+# BAD
+Write code before test? Delete it.
+
+# GOOD
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Delete means delete
+```
+
+### Build Rationalization Table
+
+Capture rationalizations from baseline testing:
+
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+```
+
+### Create Red Flags List
+
+```markdown
+## Red Flags - STOP and Start Over
+
+- Code before test
+- "I already manually tested it"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over.**
+```
+
+## RED-GREEN-REFACTOR for Skills
+
+### RED: Write Failing Test (Baseline)
+
+Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
+- What choices did they make?
+- What rationalizations did they use (verbatim)?
+
+### GREEN: Write Minimal Skill
+
+Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
+
+Run same scenarios WITH skill. Agent should now comply.
+
+### REFACTOR: Close Loopholes
+
+Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
+
+## Anti-Patterns
+
+### Narrative Example
+"In session 2025-10-03, we found empty projectDir caused..."
+**Why bad:** Too specific, not reusable
+
+### Multi-Language Dilution
+example-js.js, example-py.py, example-go.go
+**Why bad:** Mediocre quality, maintenance burden
+
+### Generic Labels
+helper1, helper2, step3, pattern4
+**Why bad:** Labels should have semantic meaning
+
+## Skill Creation Checklist
+
+**RED Phase - Write Failing Test:**
+- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
+- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
+- [ ] Identify patterns in rationalizations/failures
+
+**GREEN Phase - Write Minimal Skill:**
+- [ ] Name uses only letters, numbers, hyphens
+- [ ] YAML frontmatter with only name and description
+- [ ] Description starts with "Use when..." with specific triggers
+- [ ] Keywords throughout for search
+- [ ] Address specific baseline failures identified in RED
+- [ ] One excellent example (not multi-language)
+- [ ] Run scenarios WITH skill - verify agents now comply
+
+**REFACTOR Phase - Close Loopholes:**
+- [ ] Identify NEW rationalizations from testing
+- [ ] Add explicit counters (if discipline skill)
+- [ ] Build rationalization table from all test iterations
+- [ ] Re-test until bulletproof
+
+**Quality Checks:**
+- [ ] Quick reference table
+- [ ] Common mistakes section
+- [ ] No narrative storytelling
+- [ ] Supporting files only for tools or heavy reference
+
+## The Bottom Line
+
+**Creating skills IS TDD for process documentation.**
+
+Same Iron Law: No skill without failing test first.
+Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
+Same benefits: Better quality, fewer surprises, bulletproof results.
+
+If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.