
Agile Coach
- 237 installs
- 451 repo stars
- Updated July 21, 2026
- borghei/claude-skills
Facilitate sprint planning, retrospectives, backlog refinement, and team coaching prompts so squads adopt Scrum or Kanban ceremonies, metrics, and continuous improvement habits.
About
Agile coach skill from borghei/claude-skills that facilitates sprint planning, retrospectives, backlog refinement, and team coaching, helping squads run Scrum or Kanban ceremonies, improve velocity, and embed continuous improvement into delivery workflows.
- Sprint planning and retrospective facilitation
- Backlog refinement and prioritization coaching
- Scrum and Kanban ceremony templates
- Continuous improvement and team health guidance
Agile Coach by the numbers
- 237 all-time installs (skills.sh)
- Ranked #971 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/borghei/claude-skills --skill agile-coachAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 237 |
|---|---|
| repo stars | ★ 451 |
| Last updated | July 21, 2026 |
| Repository | borghei/claude-skills ↗ |
What it does
Facilitate sprint planning, retrospectives, backlog refinement, and team coaching prompts so squads adopt Scrum or Kanban ceremonies, metrics, and continuous improvement habits.
Files
Agile Coach
The agent acts as an expert agile coach guiding teams and organizations through framework selection, transformation planning, maturity assessment, and continuous improvement. It matches coaching stance to team development stage and uses data-driven metrics to track progress.
Core Capabilities
- Maturity assessment — score organizational agility on a 5-level model across 6 dimensions.
- Framework selection — recommend Scrum / Kanban / SAFe / LeSS by team size, complexity, and readiness.
- Transformation roadmap — structure change in 4 phases (Foundation → Pilot → Expand → Optimize) with phase gates.
- Team coaching — adapt the directive↔non-directive stance and run GROW conversations.
- Facilitation — select retrospective formats by maturity; resolve conflict.
- Metrics tracking — monitor outcome, process, quality, and team-health categories.
When to Use
- Selecting an agile framework for a team or organization.
- Coaching through Tuckman development stages or adapting coaching stance.
- Facilitating retrospectives and resolving team conflict.
- Assessing organizational agile maturity.
- Designing or running a transformation roadmap.
Tools
| Tool | Purpose | Command |
|---|---|---|
maturity_scorer.py | Score organizational agile maturity | python scripts/maturity_scorer.py --assessment assessment.yaml |
metrics_dashboard.py | Generate team metrics dashboard | python scripts/metrics_dashboard.py --team "Team Alpha" |
retro_format.py | Generate retrospective facilitation guide | python scripts/retro_format.py --format sailboat |
transformation_tracker.py | Track transformation phase progress | python scripts/transformation_tracker.py --phase pilot |
References
- [references/frameworks.md](references/frameworks.md) — read this to assess maturity (5-level model, 6 dimensions) and select a framework (size × complexity grid, Scrum/Kanban/SAFe/LeSS comparison).
- [references/coaching_techniques.md](references/coaching_techniques.md) — read this for coaching stances, the GROW model, and the stakeholder management matrix.
- [references/facilitation.md](references/facilitation.md) — read this to pick a retrospective format (Start-Stop-Continue / 4Ls / Sailboat) and run the 4-step conflict resolution process.
- [references/transformation.md](references/transformation.md) — read this for the 4-phase transformation playbook with phase gates, the four metric categories, a worked kickoff assessment, troubleshooting, and success criteria.
- [references/red-flags.md](references/red-flags.md) — read this to recognize the common ways agile coaching goes wrong, with concrete fixes.
Scope & Limitations
In Scope: Framework selection and recommendation, team-level coaching and facilitation, maturity assessment and scoring, retrospective design, transformation roadmap creation, conflict resolution within agile teams, stakeholder alignment for agile adoption.
Out of Scope: Jira/Confluence tool configuration (hand off to jira-expert/ or atlassian-admin/), production incident management (hand off to delivery-manager/), portfolio-level investment decisions (hand off to program-manager/), hiring or performance management of team members.
Limitations: Maturity scoring is a point-in-time assessment that requires honest self-reporting; scores can be gamed. Framework recommendations are guidelines, not prescriptions -- every organization has unique constraints. Transformation timelines assume consistent leadership support; political changes can invalidate roadmaps.
Integration Points
| Integration | Direction | What Flows |
|---|---|---|
scrum-master/ | Bidirectional | Agile coach sets framework; Scrum Master executes sprint-level practices |
delivery-manager/ | Coach -> DM | Transformation roadmap milestones feed into delivery planning |
program-manager/ | Coach -> PgM | Scaling framework selection informs program governance structure |
jira-expert/ | Coach -> Jira | Board and workflow requirements derived from framework selection |
senior-pm/ | PM -> Coach | Portfolio priorities shape which teams get coaching focus first |
confluence-expert/ | Coach -> Confluence | Coaching artifacts (maturity reports, retro outcomes) documented in Confluence |
Example: Wayfinder Analytics — Maturity Assessment for a Series-B Waterfall-to-Agile Transition
Real-world scenario showing how to apply this skill end-to-end.
Context
Wayfinder Analytics is a Series-B B2B analytics platform (180 employees, ~$22M ARR) that grew up on waterfall delivery. Engineering ships every six weeks against a tightly scoped quarterly release plan owned by a PMO. Roadmaps are committed 12 months out. Three engineering teams (Platform, Insights, Connectors) and one product-led team (Activation) have been quietly running "Scrum-ish" two-week sprints for the last quarter but with no formal coaching, inconsistent ceremonies, and no shared definition of done.
The new VP Engineering, hired six weeks ago, wants an honest maturity assessment before he commits to a transformation budget. He has explicitly asked: "Don't sell me SAFe. Tell me where we actually are, and what the next 90 days should look like." This is exactly the work the agile-coach skill exists for.
Inputs
- Five teams: 4 engineering (avg 6 engineers each) + 1 product/design pod
- Self-reported survey from 23 engineers, 5 EMs, 4 PMs, 2 designers (34 respondents, 89% response rate)
- Sprint metrics for the last six sprints from Jira (cycle time, velocity variance, escaped defect rate)
- Three observed ceremonies per team (standup, planning, retro) over two weeks
- VP Engineering constraint: 90-day proof of progress, no SAFe, pilot must be opt-in
- Cultural reality: middle managers cautiously supportive, senior leadership skeptical after a failed 2024 "agile rollout" that was really a Jira rollout
Applying the skill
1. Assess current state. Scored the six maturity dimensions using the standard 1-5 model with evidence pulled from survey, ceremonies, and Jira data. The team would not have survived a generic 1-5 self-rating — the agent forced evidence per dimension. 2. Identify the framework gap. Wayfinder is already attempting Scrum without coaching. The decision was not "Scrum vs. Kanban vs. SAFe" — it was "fix the Scrum we already have." This is the key insight the framework selection grid surfaces: never recommend SAFe below maturity Level 2, and recommend Kanban only if the work is operational. Wayfinder's work is product development, so Scrum stays. 3. Design a Foundation phase plan. Because the previous transformation failed, the agent did NOT recommend launching all teams at once. Instead: two volunteer pilot teams, 12 weeks, success criteria defined up front. This maps directly to the Foundation -> Pilot phase boundary in the transformation roadmap. 4. Match coaching stance to team stage. Three of the four engineering teams are in Tuckman "norming"; one (Connectors) is still "storming" due to a tech-lead conflict. The agent flagged that Connectors needs facilitative + conflict-resolution coaching first, not Scrum coaching. 5. Set 90-day metrics. Picked one metric from each of the four categories (outcome, process, quality, team) — not all of them. The VP got a one-page scorecard, not a 40-row spreadsheet.
The artifact
================================================================
Wayfinder Analytics — Agile Maturity Assessment
Date: 2026-05-22
Coach: Agile Coach (skill)
Sponsor: VP Engineering
================================================================
OVERALL MATURITY SCORE: 2.2 / 5.0 (Level 2: Repeatable)
EXECUTIVE SUMMARY
-----------------
Wayfinder is at the low end of Level 2. Teams have adopted Scrum
ceremonies but the underlying mindset, technical practices, and
outcome-orientation are still Level 1-2. The 2024 transformation
failure was not an agile failure — it was a tool rollout
masquerading as a transformation. Engineers correctly remember
it as "they renamed our Gantt chart Jira." Re-using the word
"transformation" will fail. Re-frame as "fixing the Scrum we
already have."
DIMENSION SCORES (with evidence)
--------------------------------
1. Values & Mindset 2 / 5
Evidence: 71% of engineers said "agile = sprints"; only 18%
could name a value from the Agile Manifesto without prompting.
Daily standups are status reports to EMs, not team coordination.
2. Team Practices 3 / 5
Evidence: Ceremonies happen on cadence across all 4 teams.
However, retros average 22 minutes (too short for real
reflection) and only 1 of 4 teams has a written Definition
of Done.
3. Technical Excellence 2 / 5
Evidence: CI exists but takes 47 minutes; integration tests
are flaky (8% spurious failure rate over last 4 weeks);
no trunk-based development; production deploys gated by a
manual change-advisory board on Wednesdays.
4. Product Ownership 2 / 5
Evidence: PMs ship features, not outcomes. 0 of 11 PRDs
reviewed in the last quarter listed a measurable outcome.
Quarterly OKRs at the company level do not connect to
sprint goals.
5. Leadership Support 3 / 5
Evidence: New VP Engineering is a strong sponsor. Middle EMs
are supportive but burned by 2024. CEO neutral. CFO concerned
about velocity tracking changing — sees it as a control loss.
6. Continuous Improvement 1 / 5
Evidence: Retro action items tracked in a Confluence page
no one reads. Of 47 action items in Q1, 6 were completed (13%).
Most action items are vague ("communicate better").
FRAMEWORK RECOMMENDATION
------------------------
KEEP Scrum. Do NOT introduce SAFe (we are below the L2
threshold for scaled frameworks and have only 4 product teams).
Do NOT switch to Kanban (work is product development with
discrete features, not ops flow).
The framework is not the problem. The execution is.
90-DAY PILOT PLAN (FOUNDATION PHASE)
------------------------------------
Pilot teams: Insights, Activation
(Both teams volunteered. Connectors NOT included — see
below. Platform NOT included — too central; failure
blast radius too large.)
WEEK 1-2: Baseline
- Capture current sprint metrics (cycle time p50/p85,
velocity variance, escaped defects, retro action close rate)
- Run a "why agile" workshop framed as "fix the Scrum we
already have" (avoid the word transformation)
- Define a single team-level Definition of Done per pilot team
- Establish one outcome OKR per pilot team for the quarter
WEEK 3-8: Coaching cadence
- 1 hour/week embedded coach time per pilot team
- Stance: facilitative for Insights (norming);
teaching+advising for Activation (still forming
after recent re-org)
- Re-shape retros: 60 minutes, Sailboat format every other
sprint, 4Ls on alternates, hard cap of 3 action items
per retro with named owners and due dates
- Reserve 15% sprint capacity for improvement items
WEEK 9-12: Demonstrate quick wins
- Publish a one-page scorecard to the engineering all-hands
- Run a cross-team show-and-tell where pilot teams share
what changed
- Decide go/no-go on expanding to Connectors and Platform
CONNECTORS TEAM — SEPARATE TRACK
--------------------------------
Connectors is in Tuckman storming due to an unresolved
tech-lead conflict. Doing Scrum coaching there now will fail.
Recommend a 4-week conflict-resolution intervention first:
1. Acknowledge — joint session with both leads
2. Understand — separate 1:1s, surface underlying interests
3. Explore — facilitated team chartering session
4. Agree — written team agreement, 30-day check-in
Re-evaluate Connectors for Scrum coaching at the 60-day mark.
90-DAY SUCCESS METRICS (ONE PER CATEGORY)
-----------------------------------------
Outcome Each pilot team has 1 outcome OKR tied to NSM;
progress reported in week 12 review
Process Cycle time p85 reduced by 20% on pilot teams
(baseline: Insights 9.2 days, Activation 11.4 days)
Quality Escaped defect rate cut by 30% on pilot teams
(baseline: 4.1 escaped defects / 100 stories)
Team Team NPS improves by +10 on quarterly survey
(baseline: Insights -8, Activation +4)
RISKS & MITIGATIONS
-------------------
R1 CFO sees velocity tracking change as control loss.
-> VP Eng to co-present the scorecard format with CFO
before week 1; preserve velocity reporting alongside
new metrics for the first quarter.
R2 Engineers compare this to the failed 2024 rollout.
-> Open the "why agile" workshop by NAMING the 2024
failure. Do not pretend it didn't happen.
R3 Connectors team conflict spills into pilot teams.
-> Separate track (see above). Brief EMs across all
teams not to discuss Connectors situation cross-team.
R4 Pilot success looks like cherry-picked teams.
-> Publish pilot selection criteria up front. Make
criteria for inviting next 2 teams explicit.
GO / NO-GO DECISION GATE (END OF WEEK 12)
-----------------------------------------
Advance to Pilot expansion only if all of these are true:
- At least 2 of 4 success metrics moved in the right
direction with statistical significance
- Retro action item close rate exceeds 60% on pilot teams
- VP Eng, CFO, and at least one pilot EM rate progress as
"on track or better"
- At least one engineer per pilot team volunteers to coach
the next wave (the seed of internal coaches)Why this works
- Honest scoring with evidence. The maturity score is anchored in survey data, observed ceremonies, and Jira metrics — not vibes. A weaker coach would have scored Wayfinder a 3 because "they have sprints."
- Refused to recommend SAFe. Wayfinder is below Level 2 in three dimensions. The framework selection grid is unambiguous: never SAFe below L2. A consulting firm trying to sell capacity would have pitched SAFe Essential here.
- Named the 2024 failure. Most maturity reports gloss over prior failed attempts. Surfacing it explicitly is what makes the "fix the Scrum we already have" reframe credible to skeptical engineers.
- Connectors gets a different intervention. Coaching stance must match team development stage. Storming teams do not benefit from Scrum mechanics; they need conflict resolution. This is straight from the GROW model + Tuckman stage matching.
- One metric per category, not forty. The four-category scorecard is the framework. The instinct to track everything is the anti-pattern.
What's next
- After week 12 go/no-go, hand off team-level execution to `../scrum-master/` for the two pilot teams.
- Use `../sprint-retrospective/` to instrument Sailboat and 4Ls retros with data-driven follow-up.
- For the CFO conversation, pair this assessment with a portfolio-level view from `../senior-pm/` so engineering and finance share a single picture.
- When Connectors is ready for Scrum coaching at the 60-day mark, run a fresh maturity scoring for that team in isolation.
- For the "why agile" workshop, draw facilitation patterns from
references/facilitation.md.
Coaching Techniques
Read this when coaching a team or aligning stakeholders: the directive↔non-directive stance spectrum, the GROW model for coaching conversations, and the stakeholder management matrix.
Coach Teams
The agent adapts coaching stance based on team development stage:
DIRECTIVE <-------------------------------------------> NON-DIRECTIVE
Teaching Advising Coaching Mentoring Facilitating
"Do this" "Consider "What do "In my "What does
this..." you think?" experience" the team think?"GROW Model for coaching conversations:
- G (Goal): What do you want to achieve? What would success look like?
- R (Reality): What is happening now? What have you tried? What obstacles exist?
- O (Options): What could you do? What if there were no constraints?
- W (Way Forward): What will you do? When? What support do you need?
Stakeholder Management
| Stakeholder | Influence | Interest | Strategy |
|---|---|---|---|
| Executives | High | Variable | Align to business goals, show ROI |
| Middle Mgmt | High | Medium | Address concerns, show career path |
| Teams | Medium | High | Enable success, remove impediments |
| Customers | Medium | High | Show value delivery improvement |
Facilitation
Read this when facilitating a retrospective or resolving conflict: retrospective format selection by team maturity and the 4-step conflict resolution process.
Facilitate Retrospectives
The agent selects a retrospective format based on team maturity and current needs:
Start-Stop-Continue -- Best for new teams. Simple structure: what should we begin doing, stop doing, and keep doing?
4Ls -- Best for teams in norming stage. Captures Liked, Learned, Lacked, Longed For.
Sailboat -- Best for teams needing strategic perspective. Maps goals (sun), helpers (wind), impediments (anchor), and risks (rocks).
Conflict Resolution Process
1. Acknowledge -- Recognize the conflict, create safe space, set ground rules 2. Understand -- Hear all perspectives, identify underlying needs, separate positions from interests 3. Explore -- Generate options, find common ground, build on shared interests 4. Agree -- Define acceptable solution, document agreements, set follow-up plan
Agile Framework Comparison and Selection
Read this when assessing organizational maturity or selecting a framework: the 5-level maturity model and its 6 dimensions, the size × complexity selection grid, and the Scrum/Kanban/SAFe/LeSS comparison table.
Assess Current State
The agent evaluates organizational agile maturity using the 5-level model:
python scripts/maturity_scorer.py --assessment assessment.yamlMaturity Levels:
| Level | Name | Indicators |
|---|---|---|
| 1 | Initial | Ad-hoc processes, hero-dependent delivery, limited visibility |
| 2 | Repeatable | Basic Scrum/Kanban in place, team-level practices, some metrics |
| 3 | Defined | Consistent practices across teams, cross-team coordination, CI culture |
| 4 | Managed | Quantitative management, predictable outcomes, business alignment |
| 5 | Optimizing | Innovation culture, market responsiveness, organizational learning |
Validation checkpoint: Score each of 6 dimensions (Values & Mindset, Team Practices, Technical Excellence, Product Ownership, Leadership Support, Continuous Improvement) on 1-5 scale with evidence.
Select Framework
The agent recommends a framework based on team size and complexity:
Simple Complex
Small (1-2 teams) Kanban Scrum
XP Scrumban
Medium (3-8 teams) Scrum@Scale SAFe Essential
Nexus LeSS
Large (9+ teams) SAFe Portfolio SAFe Full
Enterprise Custom Hybrid
Kanban| Aspect | Scrum | Kanban | SAFe | LeSS |
|---|---|---|---|---|
| Roles | SM, PO, Dev | Flexible | Many defined | SM, PO, Dev |
| Cadence | Fixed sprints | Continuous | PI Planning | Sprints |
| Planning | Sprint Planning | On-demand | PI Planning | Sprint Planning |
| Best For | Product dev | Operations | Enterprise | Multi-team |
| Change | End of sprint | Anytime | PI boundaries | Sprint |
Validation checkpoint: Framework selection must account for existing culture, leadership support level, and team readiness. Never recommend SAFe for teams below maturity level 2.
Red Flags: Agile Coach
Common ways this skill's output goes wrong — concrete examples, why they're bad, and how to fix them. Pair with the SKILL.md and Troubleshooting table.
How to use this document
When you have just produced a maturity assessment, framework recommendation, transformation roadmap, or retrospective design, scan the red flags below before sharing. Each one names a specific failure mode and shows the bad version next to the good version. If anything in your artifact rhymes with a bad example, fix it before the artifact leaves your hands.
---
Red Flag 1: Process Worship (ceremony over outcomes)
Symptom. The recommendation lists ceremonies, roles, and artifacts in detail but never connects them to a business or delivery outcome.
Why it's bad. Process worship is how organizations end up doing daily standups religiously while shipping nothing. The 5-level maturity model exists to measure outcomes (predictability, business alignment, learning), not ceremony attendance. Recommending Scrum because "the team should do Scrum" without a problem statement produces resentment and theater.
Bad example:
"Team should adopt Scrum: daily standups at 9:30, sprint planning every other Monday, retrospectives every other Friday, story-point estimation, definition of done, sprint reviews."
Good example:
"Problem: Team commits ~30 points/sprint but delivers ~17 (57% predictability). Recommendation: Adopt Scrum with a 2-week cadence, but the leading indicator we will track is forecast hit rate, not ceremony attendance. Target: 80% predictability by sprint 6."
How to catch it. For every ceremony you prescribe, ask: "what outcome does this improve, and how will we measure it?" If you cannot answer, do not prescribe it.
---
Red Flag 2: ScrumBut ("we do Scrum, but...")
Symptom. The team adopts Scrum vocabulary but quietly removes the parts that hurt — no retrospective, no definition of done, the PO is part-time, sprints get extended when work is unfinished.
Why it's bad. ScrumBut keeps the cost (ceremonies, jargon, planning overhead) while removing the learning loops that justify it. The result is worse than not doing Scrum at all, because the team believes they have already tried it and "it didn't work."
Bad example:
"We do Scrum, but we skip retros when sprints are busy. We do Scrum, but the PO is also the engineering manager. We do Scrum, but we extend the sprint by a few days when stories aren't done."
Good example:
"We are doing Scrum with these named deviations: (1) no PO yet — EM is acting PO until Q3, (2) retros are non-negotiable, (3) unfinished work returns to backlog and is re-estimated. Each deviation has an owner and a target end date."
How to catch it. Make every deviation from the framework named, owned, and time-boxed. Anonymous ScrumBut becomes the new normal.
---
Red Flag 3: Wrong Framework for Team Size and Complexity
Symptom. Recommending SAFe to a 12-person startup, or pure Kanban to a 60-engineer organization with five interdependent teams.
Why it's bad. Framework selection is the single highest-leverage decision in agile coaching. The size/complexity matrix in the SKILL.md exists because a framework optimized for a small simple context ships pure overhead in a large complex one, and vice versa.
Bad example:
"Recommendation: SAFe 6.0 with ARTs and PI Planning." (Team: 8 engineers, 1 PM, 1 designer, single product line, single backlog.)
Good example:
"Recommendation: Kanban with WIP limits of 2 per engineer, weekly cadence cycle, daily standup. Defer Scrum until team grows past 12 people or until predictability becomes a stakeholder concern."
How to catch it. Plot the team on the simple/complex x small/large matrix from the SKILL.md before recommending a framework. Justify every step away from the matrix default.
---
Red Flag 4: Velocity as a Performance Metric
Symptom. Maturity report celebrates "team velocity increased from 30 to 45 points" as if that were a success metric.
Why it's bad. Velocity is a planning input, not a performance output. Teams that are measured on velocity inflate estimates within a single sprint. The right output metrics are predictability (forecast hit rate), cycle time, deployment frequency, and change failure rate — the DORA metrics — none of which can be inflated by re-pointing.
Bad example:
"Q2 results: velocity up 50% (30 -> 45 story points). Team is performing exceptionally."
Good example:
"Q2 results: cycle time down from 9 to 5 days (p50), deployment frequency 2x/week up from 1x/2-weeks, predictability 82% (target 80%). Velocity was stable at ~30 points; the improvement came from smaller stories and fewer rollbacks."
How to catch it. If velocity appears in a report to leadership without DORA or predictability alongside it, rewrite.
---
Red Flag 5: Tuckman Stage Misdiagnosis
Symptom. Coaching stance is wrong for the team's actual development stage — directing a Performing team or coaching a Forming team that just needs role clarity.
Why it's bad. The four-stages model (Forming, Storming, Norming, Performing) is in the skill because intervention style must match stage. Coaching open-ended questions to a Forming team produces paralysis; directing a Performing team produces resentment and attrition.
Bad example:
"Team is in conflict (Storming). Recommendation: Schedule open-ended retrospectives and ask 'what does great look like for us?' to surface the team's vision."
Good example:
"Team is in Storming. Recommendation: Coach (not direct). Run a working agreement session to make implicit conflicts explicit. Use 1:1s to surface specific interpersonal frictions. Defer vision work until Norming."
How to catch it. Name the stage explicitly. Reference the stage-to-stance mapping (Directing/Coaching/Supporting/Delegating). If your intervention does not match the mapping, revise.
---
Red Flag 6: Maturity Score Inflation
Symptom. Self-assessment puts the team at Level 4 across all six dimensions when, by evidence, they are at Level 2.
Why it's bad. A maturity score that flatters the team is worthless: it produces no improvement actions and gives leadership false confidence. The validation checkpoint in the SKILL.md exists to require evidence for every score.
Bad example:
"Technical Excellence: 4/5. The team values quality and has good engineers."
Good example:
"Technical Excellence: 2/5. Evidence: no CI on main branch (1/5 indicator), partial unit test coverage (~40%), no production monitoring beyond uptime, two of last three releases required hotfixes within 24 hours. Target Level 3 in two quarters."
How to catch it. Require a one-sentence evidence statement for every dimension score. No evidence, no score.
---
Red Flag 7: Transformation Roadmap with No Sequencing Logic
Symptom. The roadmap is a bullet list of practices to adopt with no rationale for order — "Q1: Scrum, OKRs, CI/CD, Lean Portfolio, SAFe."
Why it's bad. Practices have prerequisites. CI/CD without trunk-based development creates merge hell. SAFe without team-level Scrum produces planning theater. Sequencing failure is the most common reason transformations stall.
Bad example:
"Q1: Adopt Scrum, OKRs, DevOps, and product trios."
Good example:
"Q1: Stabilize team-level Scrum (predictability gate: 70%). Q2: Introduce product trios and CD pipeline (prereq: Q1 predictability). Q3: Roll up to org-level OKRs (prereq: stable team backlogs). Each quarter has a gate; if the gate is missed, the next quarter slips."
How to catch it. For every practice in the roadmap, name its prerequisite and its gate. If practices can be reordered without consequence, the sequencing is fake.
---
Red Flag 8: Retrospective as Complaint Session
Symptom. Retro output is a list of grievances with no owned actions, or the same three actions appear retro after retro with no closure.
Why it's bad. The retrospective is the team's main learning loop. If it produces no committed actions or no follow-through, it converts into theater and the team stops believing in it. Continuous Improvement (the sixth maturity dimension) flatlines.
Bad example:
"What went wrong: too many meetings, unclear requirements, ops keeps interrupting us. Actions: 'reduce meetings', 'better requirements'."
Good example:
"Action 1: PM and EM block 9-11am as deep-work no-meeting window starting next sprint. Owner: EM. Done when: calendar reflects it by Friday. Action 2: PRD must include 'definition of done' before story is pulled. Owner: PM. Done when: next 3 PRDs reviewed. Carryover from last retro: 'requirements clarity' — closed; replaced by Action 2."
How to catch it. Every retro action must have an owner, a date, and a "done when" condition. Track carryovers explicitly; if an action appears in three retros, escalate or kill it.
---
Red Flag 9: Coach as Decision-Maker
Symptom. The coach is making product, technical, or staffing decisions on behalf of the team — "I decided we will move to Kanban" rather than "I helped the team decide."
Why it's bad. Agile coaching is a facilitative discipline. A coach who makes decisions creates dependency and undermines the team's ownership. The team will revert the moment the coach leaves.
Bad example:
"I have decided that this team will adopt Scrum and that the EM will be the new Scrum Master."
Good example:
"I facilitated a 90-minute working session where the team reviewed the framework selection matrix and chose Scrum 8-1. The EM volunteered as Scrum Master with a 6-month sunset to a rotating role."
How to catch it. Read your recommendation document. Search for "I decided" or "I will". If the team is not the subject of those sentences, rewrite.
---
Red Flag 10: Ignoring the Andon Cord (Stop-the-Line Discipline)
Symptom. Recommendations include continuous improvement language but never empower the team to halt work when quality is broken.
Why it's bad. Maturity Level 4 and above (Managed, Optimizing) requires stop-the-line discipline — the team's right and obligation to halt progress when a quality issue surfaces. Continuous improvement without stop-the-line is just slogans.
Bad example:
"Recommend the team adopt continuous improvement practices and discuss quality issues in retro."
Good example:
"Recommend an explicit andon policy: any engineer can halt the deployment pipeline by tagging #andon in the team channel. Halt is automatic; restart requires team agreement and a 15-minute root cause. Track andon-pulls per quarter as a leading indicator of psychological safety."
How to catch it. A continuous improvement system must have a named mechanism for stopping, not just for talking about quality.
---
Red Flag 11: Framework Selection without Looking at the Work
Symptom. The framework recommendation is based on team size and self-described complexity, but never on the actual type of work (predictable feature delivery vs unpredictable incident response vs research).
Why it's bad. Kanban beats Scrum for support/ops work; Scrum beats Kanban for feature delivery with a quarterly horizon; XP overlays on either when engineering practices are the bottleneck. Skipping a look at the work mix produces framework mismatches.
Bad example:
"Team is 8 people with moderate complexity. Recommend Scrum."
Good example:
"Team is 8 people. Work mix: 60% planned feature work, 30% interrupt-driven support, 10% R&D. Recommendation: Scrum for the feature track (separate backlog, 2-week sprints) and a Kanban swim lane for support (WIP limit 2). R&D handled as time-boxed spikes during sprint planning."
How to catch it. Estimate the work mix (% planned vs interrupt vs research) before recommending. Mixed-mode work usually wants mixed-mode frameworks.
---
Red Flag Quick Reference
| # | Anti-pattern | One-line check |
|---|---|---|
| 1 | Process Worship | Does every ceremony map to a measurable outcome? |
| 2 | ScrumBut | Are deviations named, owned, and time-boxed? |
| 3 | Wrong Framework for Size/Complexity | Did you justify departures from the size/complexity matrix? |
| 4 | Velocity as Performance Metric | Are DORA + predictability alongside any velocity number? |
| 5 | Tuckman Stage Misdiagnosis | Does your stance match the named stage? |
| 6 | Maturity Score Inflation | Is there a one-sentence evidence statement per dimension? |
| 7 | Roadmap with No Sequencing | Does every Q have a prereq and a gate? |
| 8 | Retro as Complaint Session | Does every action have owner + date + done-when? |
| 9 | Coach as Decision-Maker | Is the team the subject of decision sentences? |
| 10 | No Andon Cord | Is there a named mechanism for stopping work? |
| 11 | Framework without Work Mix | Did you estimate planned vs interrupt vs research? |
Related Reading
- SKILL.md Troubleshooting section (for symptom -> root cause -> resolution)
- references/maturity-model.md (for the 5-level scoring rubric, if present)
- references/retrospective-formats.md (for retro variety beyond start-stop-continue, if present)
Transformation Playbook
Read this when designing or running a transformation: the 4-phase roadmap with phase gates, the four metric categories to track, a worked kickoff-assessment example, the troubleshooting table, and success criteria.
Design Transformation Roadmap
The agent structures transformation in 4 phases:
1. Foundation (Months 1-3): Establish leadership buy-in, create transformation team, assess current state, select pilot teams, design training program 2. Pilot (Months 4-6): Launch pilot teams, deliver framework training, run coaching sessions, capture lessons learned and success stories 3. Expand (Months 7-12): Scale successful patterns, build communities of practice, develop internal coaches, optimize processes 4. Optimize (Months 13+): Portfolio-level agility, cross-team coordination, metrics-driven improvement, innovation enablement
Validation checkpoint: Each phase has explicit success criteria. Do not advance to the next phase until criteria are met.
Track Metrics
The agent monitors four metric categories:
| Category | Metrics | Purpose |
|---|---|---|
| Outcome | Customer satisfaction, time to market, revenue delivered | Business value |
| Process | Lead time, cycle time, throughput, WIP | Flow efficiency |
| Quality | Defect rate, tech debt, test coverage, deploy frequency | Technical health |
| Team | Happiness, psychological safety, engagement, sustainability | Team health |
python scripts/metrics_dashboard.py --team "Team Alpha"Validation checkpoint: Review metrics monthly. If any category degrades for 2+ consecutive periods, trigger a coaching intervention.
Example: Transformation Kickoff Assessment
# assessment.yaml
organization: "Acme Corp"
teams_assessed: 5
dimensions:
values_and_mindset: 2
team_practices: 3
technical_excellence: 2
product_ownership: 2
leadership_support: 3
continuous_improvement: 2$ python scripts/maturity_scorer.py --assessment assessment.yaml
Agile Maturity Assessment: Acme Corp
=====================================
Overall Score: 2.3 / 5.0 (Level 2: Repeatable)
Dimension Scores:
Values & Mindset: 2/5 - Teams follow process but lack agile mindset
Team Practices: 3/5 - Consistent Scrum ceremonies across teams
Technical Excellence: 2/5 - Limited automation, manual testing prevalent
Product Ownership: 2/5 - Feature-driven, not outcome-driven
Leadership Support: 3/5 - Middle management supportive, exec sponsorship partial
Continuous Improvement: 2/5 - Retrospectives happen but action items stall
Recommendation: Start with Scrum pilot on 2 willing teams.
Focus first on Technical Excellence and Product Ownership.
Target Level 3 within 6 months.Troubleshooting
| Problem | Likely Cause | Resolution |
|---|---|---|
| Teams revert to waterfall habits after initial training | Coaching stance too directive; team never internalized agile values | Shift to facilitative coaching; run a "why agile" workshop focused on outcomes, not ceremonies |
| Velocity fluctuates wildly sprint to sprint | Inconsistent story pointing, scope changes mid-sprint, or unplanned work not tracked | Calibrate estimation with reference stories; track unplanned work separately; protect sprint scope |
| Retrospective action items never get implemented | Actions too vague, no owners, or no capacity reserved for improvements | Apply SMART criteria to retro actions; reserve 10-15% sprint capacity for improvement items |
| Leadership loses patience with transformation timeline | Unrealistic expectations set during Phase 1; no visible quick wins | Identify and publicize early wins within first 60 days; show leading indicators (cycle time, team satisfaction) before lagging indicators (revenue, quality) |
| Teams resist framework adoption | Change fatigue, lack of psychological safety, or imposed top-down mandate | Start with volunteer pilot teams; let success stories create pull rather than push; address fears openly |
| Agile maturity score plateaus at Level 2-3 | Focus on ceremonies over outcomes; technical practices neglected | Invest in engineering excellence (CI/CD, TDD, pair programming); shift metrics from output to outcomes |
| Cross-team coordination breaks down at scale | No explicit coordination mechanisms beyond team-level Scrum | Introduce Scrum-of-Scrums, communities of practice, or consider a lightweight scaling framework (LeSS, Nexus) |
Success Criteria
- Team velocity stabilizes within +/-15% variance after 4 sprints of coaching engagement
- Agile maturity score improves by at least 1 full level within 6 months of sustained coaching
- Retrospective action item completion rate exceeds 70% per sprint
- Team NPS or satisfaction score (measured quarterly) trends upward over 3 consecutive periods
- Cycle time for standard work items decreases by 20%+ within the first quarter
- At least 80% of team members can articulate the purpose behind each ceremony they practice
- Leadership stakeholders rate transformation progress as "on track" or better in quarterly reviews
#!/usr/bin/env python3
"""Agile Maturity Scorer - Score organizational agile maturity across 6 dimensions.
Reads an assessment file and produces a scored report with level classification,
gap analysis, and prioritized improvement recommendations aligned with the
Kanban Maturity Model and standard agile maturity frameworks.
Usage:
python agile_maturity_scorer.py --assessment assessment.json
python agile_maturity_scorer.py --assessment assessment.json --json
python agile_maturity_scorer.py --example
"""
import argparse
import json
import sys
DIMENSIONS = [
"values_and_mindset",
"team_practices",
"technical_excellence",
"product_ownership",
"leadership_support",
"continuous_improvement",
]
DIMENSION_LABELS = {
"values_and_mindset": "Values & Mindset",
"team_practices": "Team Practices",
"technical_excellence": "Technical Excellence",
"product_ownership": "Product Ownership",
"leadership_support": "Leadership Support",
"continuous_improvement": "Continuous Improvement",
}
LEVEL_NAMES = {
1: "Initial",
2: "Repeatable",
3: "Defined",
4: "Managed",
5: "Optimizing",
}
LEVEL_DESCRIPTIONS = {
1: "Ad-hoc processes, hero-dependent delivery, limited visibility into work.",
2: "Basic Scrum/Kanban in place, team-level practices established, some metrics tracked.",
3: "Consistent practices across teams, cross-team coordination, CI/CD culture emerging.",
4: "Quantitative management, predictable outcomes, business-aligned delivery.",
5: "Innovation culture, market responsiveness, organizational learning embedded.",
}
IMPROVEMENT_ACTIONS = {
"values_and_mindset": {
1: "Start with agile values workshops; share success stories from other organizations.",
2: "Run agile mindset training for all team members; introduce team working agreements.",
3: "Embed agile values in performance reviews; create communities of practice for knowledge sharing.",
4: "Develop internal agile champions program; align agile values with company mission.",
5: "Foster innovation culture; enable teams to experiment and learn from failure safely.",
},
"team_practices": {
1: "Establish basic Scrum ceremonies (standup, planning, review, retro) with coaching support.",
2: "Standardize ceremony formats; introduce Definition of Done; start tracking velocity.",
3: "Cross-team ceremony alignment; introduce Scrum-of-Scrums; standardize estimation practices.",
4: "Optimize ceremonies based on metrics; reduce ceremony overhead; self-facilitating teams.",
5: "Teams autonomously adapt practices; ceremonies evolved to fit context; practices shared across org.",
},
"technical_excellence": {
1: "Set up basic CI pipeline; introduce code reviews; establish coding standards.",
2: "Automate unit testing; introduce TDD practices; set up staging environments.",
3: "Full CI/CD pipeline; automated integration testing; feature flags; infrastructure as code.",
4: "Canary deployments; chaos engineering; comprehensive observability; zero-downtime deploys.",
5: "Self-healing systems; automated security scanning; continuous architecture evolution.",
},
"product_ownership": {
1: "Identify a dedicated Product Owner; create a basic product backlog.",
2: "Regular backlog refinement; connect stories to user outcomes; stakeholder feedback loops.",
3: "Outcome-driven roadmapping; product discovery practices; hypothesis-driven development.",
4: "Continuous discovery; data-driven prioritization; customer-centric OKRs at every level.",
5: "Market-responsive product strategy; real-time customer feedback integration; portfolio-level alignment.",
},
"leadership_support": {
1: "Secure executive sponsor for agile transformation; educate leadership on agile principles.",
2: "Leadership participates in PI planning or sprint reviews; resources allocated for coaching.",
3: "Leadership models agile behaviors; impediment removal happens within 48 hours.",
4: "Servant leadership embedded; leaders create environment for teams to self-organize.",
5: "Decentralized decision-making; leaders focus on strategy and vision; teams fully empowered.",
},
"continuous_improvement": {
1: "Run basic retrospectives; start capturing action items.",
2: "Retro action items tracked and completed; improvement experiments initiated.",
3: "Metrics-driven improvement; improvement items in sprint backlog; cross-team learning.",
4: "Systematic experimentation; improvement velocity tracked; lean thinking pervasive.",
5: "Kaizen culture; improvement is everyone's job; organization learns faster than competitors.",
},
}
def load_assessment(path: str) -> dict:
"""Load assessment data from JSON file."""
with open(path, "r") as f:
return json.load(f)
def validate_assessment(data: dict) -> list:
"""Validate assessment structure."""
errors = []
if "organization" not in data:
errors.append("Missing 'organization' field")
if "dimensions" not in data or not isinstance(data.get("dimensions"), dict):
errors.append("Missing or invalid 'dimensions' object")
return errors
for dim in DIMENSIONS:
score = data["dimensions"].get(dim)
if score is None:
errors.append(f"Missing dimension: '{dim}'")
elif not isinstance(score, (int, float)) or score < 1 or score > 5:
errors.append(f"'{dim}' must be 1-5, got {score}")
return errors
def score_maturity(data: dict) -> dict:
"""Calculate maturity scores and generate recommendations."""
org = data.get("organization", "Unknown")
dims = data["dimensions"]
teams_assessed = data.get("teams_assessed", "N/A")
# Calculate overall score
scores = [dims[d] for d in DIMENSIONS]
overall = round(sum(scores) / len(scores), 2)
level = max(1, min(5, round(overall)))
# Dimension detail
dim_detail = {}
for dim in DIMENSIONS:
s = dims[dim]
dim_level = max(1, min(5, round(s)))
dim_detail[dim] = {
"label": DIMENSION_LABELS[dim],
"score": s,
"level": dim_level,
"level_name": LEVEL_NAMES[dim_level],
}
# Gap analysis: identify dimensions furthest from target
target_level = min(level + 1, 5)
gaps = []
for dim in DIMENSIONS:
gap = target_level - dims[dim]
if gap > 0:
gaps.append({
"dimension": DIMENSION_LABELS[dim],
"current_score": dims[dim],
"target": target_level,
"gap": round(gap, 1),
"priority": "High" if gap >= 2 else "Medium" if gap >= 1 else "Low",
})
gaps.sort(key=lambda x: x["gap"], reverse=True)
# Improvement recommendations
recommendations = []
for dim in DIMENSIONS:
current_level = max(1, min(5, round(dims[dim])))
if current_level < 5:
action = IMPROVEMENT_ACTIONS[dim].get(current_level, "Continue optimizing practices.")
recommendations.append({
"dimension": DIMENSION_LABELS[dim],
"current_level": current_level,
"action": action,
})
# Framework recommendation
if overall < 2:
framework_rec = "Start with Kanban (minimal process overhead); focus on making work visible before adding ceremonies."
elif overall < 3:
framework_rec = "Scrum is recommended for product teams; Kanban for operations. Do not attempt scaling frameworks yet."
elif overall < 4:
framework_rec = "Teams are ready for lightweight scaling (LeSS, Nexus). Consider SAFe Essential only if >8 teams need coordination."
else:
framework_rec = "Organization is mature enough for portfolio-level agility (SAFe Portfolio, Enterprise Kanban, or custom hybrid)."
return {
"organization": org,
"teams_assessed": teams_assessed,
"overall_score": overall,
"overall_level": level,
"overall_level_name": LEVEL_NAMES[level],
"level_description": LEVEL_DESCRIPTIONS[level],
"dimensions": dim_detail,
"target_level": target_level,
"gap_analysis": gaps,
"recommendations": recommendations,
"framework_recommendation": framework_rec,
}
def print_report(result: dict) -> None:
"""Print human-readable maturity report."""
print(f"\nAgile Maturity Assessment: {result['organization']}")
print(f"Teams Assessed: {result['teams_assessed']}")
print("=" * 60)
print(f"Overall Score: {result['overall_score']:.1f} / 5.0 (Level {result['overall_level']}: {result['overall_level_name']})")
print(f" {result['level_description']}")
print()
print("Dimension Scores:")
for dim in DIMENSIONS:
info = result["dimensions"][dim]
bar = "#" * (info["score"] * 4) + "-" * (20 - info["score"] * 4)
print(f" {info['label']:<25} {info['score']}/5 [{bar}] Level {info['level']}: {info['level_name']}")
if result["gap_analysis"]:
print(f"\nGap Analysis (target: Level {result['target_level']}):")
for g in result["gap_analysis"]:
print(f" [{g['priority']}] {g['dimension']}: {g['current_score']:.0f} -> {g['target']} (gap: {g['gap']:.1f})")
print(f"\nFramework Recommendation:")
print(f" {result['framework_recommendation']}")
print(f"\nImprovement Actions:")
for r in result["recommendations"][:3]:
print(f" [{r['dimension']}]")
print(f" {r['action']}")
print()
def print_example() -> None:
"""Print example assessment JSON."""
example = {
"organization": "Acme Corp",
"teams_assessed": 5,
"dimensions": {
"values_and_mindset": 2,
"team_practices": 3,
"technical_excellence": 2,
"product_ownership": 2,
"leadership_support": 3,
"continuous_improvement": 2,
},
}
print(json.dumps(example, indent=2))
def main():
parser = argparse.ArgumentParser(
description="Score organizational agile maturity across 6 dimensions."
)
parser.add_argument("--assessment", type=str, help="Path to assessment JSON file")
parser.add_argument("--json", action="store_true", help="Output results as JSON")
parser.add_argument("--example", action="store_true", help="Print example assessment JSON and exit")
args = parser.parse_args()
if args.example:
print_example()
return
if not args.assessment:
parser.error("--assessment is required (use --example to see the expected format)")
data = load_assessment(args.assessment)
errors = validate_assessment(data)
if errors:
print("Validation errors:", file=sys.stderr)
for e in errors:
print(f" - {e}", file=sys.stderr)
sys.exit(1)
result = score_maturity(data)
if args.json:
print(json.dumps(result, indent=2))
else:
print_report(result)
if __name__ == "__main__":
main()
#!/usr/bin/env python3
"""Team Health Checker - Evaluate team health across multiple dimensions.
Reads a YAML/JSON team health survey and produces a scored report with
recommendations. Based on the Spotify Squad Health Check model adapted
for general agile teams.
Usage:
python team_health_checker.py --survey survey.json
python team_health_checker.py --survey survey.json --json
python team_health_checker.py --example
"""
import argparse
import json
import sys
from datetime import datetime
DIMENSIONS = [
"psychological_safety",
"delivery_pace",
"code_quality",
"learning",
"collaboration",
"fun",
"mission_clarity",
"autonomy",
"support",
"sustainable_pace",
]
DIMENSION_LABELS = {
"psychological_safety": "Psychological Safety",
"delivery_pace": "Delivery Pace",
"code_quality": "Code & Quality",
"learning": "Learning & Growth",
"collaboration": "Collaboration",
"fun": "Fun & Engagement",
"mission_clarity": "Mission Clarity",
"autonomy": "Autonomy",
"support": "Support & Tools",
"sustainable_pace": "Sustainable Pace",
}
RECOMMENDATIONS = {
"psychological_safety": "Run a team agreement workshop; introduce blameless post-mortems; leader models vulnerability by sharing own mistakes.",
"delivery_pace": "Review WIP limits; identify and remove top 3 blockers; check if sprint commitments are realistic.",
"code_quality": "Introduce pair programming sessions; increase code review coverage; invest in CI/CD pipeline improvements.",
"learning": "Allocate 10% time for learning; start a book club or tech talk series; create individual development plans.",
"collaboration": "Introduce mob programming; create cross-functional pairing rotations; improve documentation for shared context.",
"fun": "Plan team social events; celebrate wins publicly; introduce team rituals (e.g., Friday demos).",
"mission_clarity": "Revisit team charter; connect sprint goals to product vision; share customer impact stories regularly.",
"autonomy": "Reduce approval gates; empower team to make technical decisions; increase ownership of end-to-end features.",
"support": "Audit tooling satisfaction; address top infrastructure pain points; ensure management removes escalated blockers.",
"sustainable_pace": "Review overtime trends; protect sprint capacity from ad-hoc requests; check vacation usage rates.",
}
def load_survey(path: str) -> dict:
"""Load survey data from JSON file."""
with open(path, "r") as f:
return json.load(f)
def validate_survey(data: dict) -> list:
"""Validate survey structure and return list of errors."""
errors = []
if "team" not in data:
errors.append("Missing 'team' field")
if "respondents" not in data or not isinstance(data.get("respondents"), list):
errors.append("Missing or invalid 'respondents' list")
return errors
for i, resp in enumerate(data["respondents"]):
if "name" not in resp:
errors.append(f"Respondent {i}: missing 'name'")
if "scores" not in resp or not isinstance(resp.get("scores"), dict):
errors.append(f"Respondent {i}: missing or invalid 'scores'")
continue
for dim in DIMENSIONS:
score = resp["scores"].get(dim)
if score is None:
errors.append(f"Respondent {i} ({resp.get('name', '?')}): missing score for '{dim}'")
elif not isinstance(score, (int, float)) or score < 1 or score > 5:
errors.append(f"Respondent {i} ({resp.get('name', '?')}): '{dim}' score must be 1-5, got {score}")
return errors
def analyze_health(data: dict) -> dict:
"""Analyze team health from survey data."""
respondents = data["respondents"]
n = len(respondents)
dimension_scores = {}
for dim in DIMENSIONS:
scores = [r["scores"][dim] for r in respondents if dim in r.get("scores", {})]
if scores:
avg = sum(scores) / len(scores)
spread = max(scores) - min(scores)
dimension_scores[dim] = {
"average": round(avg, 2),
"min": min(scores),
"max": max(scores),
"spread": spread,
"responses": len(scores),
}
overall = sum(d["average"] for d in dimension_scores.values()) / len(dimension_scores) if dimension_scores else 0
# Classify health
if overall >= 4.0:
status = "Thriving"
elif overall >= 3.0:
status = "Healthy"
elif overall >= 2.0:
status = "At Risk"
else:
status = "Critical"
# Find strengths and concerns
sorted_dims = sorted(dimension_scores.items(), key=lambda x: x[1]["average"], reverse=True)
strengths = [(dim, info) for dim, info in sorted_dims[:3]]
concerns = [(dim, info) for dim, info in sorted_dims[-3:] if info["average"] < 3.5]
# High-spread dimensions (disagreement)
high_spread = [(dim, info) for dim, info in dimension_scores.items() if info["spread"] >= 3]
# Generate recommendations
recs = []
for dim, info in concerns:
recs.append({
"dimension": DIMENSION_LABELS.get(dim, dim),
"score": info["average"],
"action": RECOMMENDATIONS.get(dim, "Investigate root cause with the team."),
})
return {
"team": data.get("team", "Unknown"),
"date": data.get("date", datetime.now().strftime("%Y-%m-%d")),
"respondent_count": n,
"overall_score": round(overall, 2),
"status": status,
"dimensions": dimension_scores,
"strengths": [{"dimension": DIMENSION_LABELS.get(d, d), "score": i["average"]} for d, i in strengths],
"concerns": [{"dimension": DIMENSION_LABELS.get(d, d), "score": i["average"]} for d, i in concerns],
"high_disagreement": [{"dimension": DIMENSION_LABELS.get(d, d), "spread": i["spread"]} for d, i in high_spread],
"recommendations": recs,
}
def print_report(result: dict) -> None:
"""Print human-readable health check report."""
print(f"\nTeam Health Check: {result['team']}")
print(f"Date: {result['date']} | Respondents: {result['respondent_count']}")
print("=" * 60)
print(f"Overall Score: {result['overall_score']:.1f} / 5.0 ({result['status']})")
print()
print("Dimension Scores:")
for dim in DIMENSIONS:
info = result["dimensions"].get(dim, {})
label = DIMENSION_LABELS.get(dim, dim)
avg = info.get("average", 0)
bar = "#" * int(avg * 4) + "-" * (20 - int(avg * 4))
indicator = ""
if info.get("spread", 0) >= 3:
indicator = " [!] High disagreement"
print(f" {label:<25} {avg:.1f} [{bar}]{indicator}")
if result["strengths"]:
print(f"\nStrengths:")
for s in result["strengths"]:
print(f" + {s['dimension']} ({s['score']:.1f})")
if result["concerns"]:
print(f"\nConcerns:")
for c in result["concerns"]:
print(f" - {c['dimension']} ({c['score']:.1f})")
if result["recommendations"]:
print(f"\nRecommendations:")
for r in result["recommendations"]:
print(f" [{r['dimension']} @ {r['score']:.1f}]")
print(f" {r['action']}")
print()
def print_example() -> None:
"""Print example survey JSON."""
example = {
"team": "Team Alpha",
"date": "2026-03-21",
"respondents": [
{
"name": "Alice",
"scores": {
"psychological_safety": 4, "delivery_pace": 3, "code_quality": 4,
"learning": 3, "collaboration": 5, "fun": 4,
"mission_clarity": 4, "autonomy": 3, "support": 3, "sustainable_pace": 2,
},
},
{
"name": "Bob",
"scores": {
"psychological_safety": 3, "delivery_pace": 4, "code_quality": 3,
"learning": 2, "collaboration": 4, "fun": 3,
"mission_clarity": 3, "autonomy": 2, "support": 4, "sustainable_pace": 3,
},
},
{
"name": "Carol",
"scores": {
"psychological_safety": 5, "delivery_pace": 3, "code_quality": 4,
"learning": 4, "collaboration": 4, "fun": 5,
"mission_clarity": 5, "autonomy": 4, "support": 3, "sustainable_pace": 2,
},
},
],
}
print(json.dumps(example, indent=2))
def main():
parser = argparse.ArgumentParser(
description="Evaluate team health across 10 dimensions with recommendations."
)
parser.add_argument("--survey", type=str, help="Path to survey JSON file")
parser.add_argument("--json", action="store_true", help="Output results as JSON")
parser.add_argument("--example", action="store_true", help="Print example survey JSON and exit")
args = parser.parse_args()
if args.example:
print_example()
return
if not args.survey:
parser.error("--survey is required (use --example to see the expected format)")
data = load_survey(args.survey)
errors = validate_survey(data)
if errors:
print("Validation errors:", file=sys.stderr)
for e in errors:
print(f" - {e}", file=sys.stderr)
sys.exit(1)
result = analyze_health(data)
if args.json:
print(json.dumps(result, indent=2))
else:
print_report(result)
if __name__ == "__main__":
main()
#!/usr/bin/env python3
"""Velocity Analyzer - Analyze sprint velocity trends and forecast capacity.
Reads sprint history data and produces trend analysis, statistical forecasts,
and stability metrics to support sprint planning decisions.
Usage:
python velocity_analyzer.py --sprints sprints.json
python velocity_analyzer.py --sprints sprints.json --forecast 3 --json
python velocity_analyzer.py --example
"""
import argparse
import json
import math
import sys
def load_data(path: str) -> dict:
"""Load sprint data from JSON file."""
with open(path, "r") as f:
return json.load(f)
def calculate_stats(values: list) -> dict:
"""Calculate descriptive statistics for a list of numbers."""
if not values:
return {"mean": 0, "median": 0, "std_dev": 0, "min": 0, "max": 0, "count": 0}
n = len(values)
mean = sum(values) / n
sorted_v = sorted(values)
median = sorted_v[n // 2] if n % 2 == 1 else (sorted_v[n // 2 - 1] + sorted_v[n // 2]) / 2
variance = sum((x - mean) ** 2 for x in values) / n if n > 1 else 0
std_dev = math.sqrt(variance)
return {
"mean": round(mean, 1),
"median": round(median, 1),
"std_dev": round(std_dev, 1),
"min": min(values),
"max": max(values),
"count": n,
}
def analyze_velocity(data: dict, forecast_sprints: int = 3) -> dict:
"""Analyze velocity from sprint data."""
team = data.get("team", "Unknown")
sprints = data.get("sprints", [])
if len(sprints) < 2:
return {"team": team, "error": "Need at least 2 sprints for analysis"}
# Extract velocity values
velocities = [s.get("completed_points", 0) for s in sprints]
committed = [s.get("committed_points", 0) for s in sprints]
sprint_names = [s.get("name", f"Sprint {i+1}") for i, s in enumerate(sprints)]
stats = calculate_stats(velocities)
# Commitment reliability
reliability_scores = []
for c, v in zip(committed, velocities):
if c > 0:
reliability_scores.append(min(v / c, 1.5)) # Cap at 150%
avg_reliability = round(sum(reliability_scores) / len(reliability_scores) * 100, 1) if reliability_scores else 0
# Trend: compare last 3 sprints avg to previous 3
recent = velocities[-3:] if len(velocities) >= 3 else velocities
earlier = velocities[-6:-3] if len(velocities) >= 6 else velocities[:len(velocities)//2] if len(velocities) >= 4 else []
recent_avg = sum(recent) / len(recent)
earlier_avg = sum(earlier) / len(earlier) if earlier else recent_avg
if earlier_avg > 0:
trend_pct = round((recent_avg - earlier_avg) / earlier_avg * 100, 1)
else:
trend_pct = 0
if trend_pct > 10:
trend_label = "Improving"
elif trend_pct < -10:
trend_label = "Declining"
else:
trend_label = "Stable"
# Stability: coefficient of variation
cv = round(stats["std_dev"] / stats["mean"] * 100, 1) if stats["mean"] > 0 else 0
if cv <= 15:
stability = "High"
elif cv <= 30:
stability = "Moderate"
else:
stability = "Low"
# Forecast using recent average +/- 1 std_dev
recent_stats = calculate_stats(recent)
forecast = {
"sprints_ahead": forecast_sprints,
"optimistic": round(recent_stats["mean"] + recent_stats["std_dev"], 0),
"expected": round(recent_stats["mean"], 0),
"conservative": round(max(recent_stats["mean"] - recent_stats["std_dev"], 0), 0),
"range_total_expected": round(recent_stats["mean"] * forecast_sprints, 0),
}
# Sprint-by-sprint detail
sprint_detail = []
for i, s in enumerate(sprints):
detail = {
"name": sprint_names[i],
"committed": committed[i],
"completed": velocities[i],
}
if committed[i] > 0:
detail["reliability_pct"] = round(velocities[i] / committed[i] * 100, 1)
sprint_detail.append(detail)
return {
"team": team,
"sprint_count": len(sprints),
"statistics": stats,
"commitment_reliability_pct": avg_reliability,
"trend": {"direction": trend_label, "change_pct": trend_pct},
"stability": {"coefficient_of_variation": cv, "rating": stability},
"forecast": forecast,
"sprints": sprint_detail,
}
def print_report(result: dict) -> None:
"""Print human-readable velocity report."""
if "error" in result:
print(f"Error: {result['error']}")
return
print(f"\nVelocity Analysis: {result['team']}")
print(f"Sprints Analyzed: {result['sprint_count']}")
print("=" * 60)
s = result["statistics"]
print(f"\nStatistics:")
print(f" Average Velocity: {s['mean']:.1f} points/sprint")
print(f" Median: {s['median']:.1f}")
print(f" Std Deviation: {s['std_dev']:.1f}")
print(f" Range: {s['min']} - {s['max']}")
t = result["trend"]
print(f"\nTrend: {t['direction']} ({t['change_pct']:+.1f}%)")
st = result["stability"]
print(f"Stability: {st['rating']} (CV: {st['coefficient_of_variation']:.1f}%)")
print(f"Commitment Reliability: {result['commitment_reliability_pct']:.1f}%")
print(f"\nSprint History:")
print(f" {'Sprint':<20} {'Committed':>10} {'Completed':>10} {'Reliability':>12}")
print(f" {'-'*20} {'-'*10} {'-'*10} {'-'*12}")
for sp in result["sprints"]:
rel = f"{sp.get('reliability_pct', 0):.0f}%" if "reliability_pct" in sp else "N/A"
print(f" {sp['name']:<20} {sp['committed']:>10} {sp['completed']:>10} {rel:>12}")
f = result["forecast"]
print(f"\nForecast (next {f['sprints_ahead']} sprints):")
print(f" Optimistic: {f['optimistic']:.0f} pts/sprint")
print(f" Expected: {f['expected']:.0f} pts/sprint")
print(f" Conservative: {f['conservative']:.0f} pts/sprint")
print(f" Total Expected ({f['sprints_ahead']} sprints): {f['range_total_expected']:.0f} pts")
print()
def print_example() -> None:
"""Print example sprint data JSON."""
example = {
"team": "Team Alpha",
"sprints": [
{"name": "Sprint 18", "committed_points": 34, "completed_points": 30},
{"name": "Sprint 19", "committed_points": 32, "completed_points": 32},
{"name": "Sprint 20", "committed_points": 35, "completed_points": 28},
{"name": "Sprint 21", "committed_points": 30, "completed_points": 31},
{"name": "Sprint 22", "committed_points": 33, "completed_points": 35},
{"name": "Sprint 23", "committed_points": 35, "completed_points": 33},
],
}
print(json.dumps(example, indent=2))
def main():
parser = argparse.ArgumentParser(
description="Analyze sprint velocity trends and forecast future capacity."
)
parser.add_argument("--sprints", type=str, help="Path to sprint data JSON file")
parser.add_argument("--forecast", type=int, default=3, help="Number of sprints to forecast (default: 3)")
parser.add_argument("--json", action="store_true", help="Output results as JSON")
parser.add_argument("--example", action="store_true", help="Print example input JSON and exit")
args = parser.parse_args()
if args.example:
print_example()
return
if not args.sprints:
parser.error("--sprints is required (use --example to see the expected format)")
data = load_data(args.sprints)
result = analyze_velocity(data, args.forecast)
if args.json:
print(json.dumps(result, indent=2))
else:
print_report(result)
if __name__ == "__main__":
main()