agile-observer

# Agile Observer Proactive agile metrics engine for Scrum Masters and Agile Coaches. Analyzes Trello or Jira boards to compute flow metrics, detect problems, and generate health reports. ## Workflow 1. **Identify platform and credentials.** Ask for Trello or Jira. Look for credential files in workspace secrets (`trello-credentials.json` or `jira-credentials.json`). 2. **List boards/projects.** Fetch available boards and let the user choose, or use the one specified. 3. **Fetch board data.** Pull lists/statuses, cards/issues, and movement history using the API patterns in references. 4. **Classify workflow states.** Map list names or status categories to: backlog, doing, review, done. 5. **Compute metrics.** Calculate cycle time, throughput, WIP, aging, and blockers. 6. **Generate health report.** Assess overall health and add coaching suggestions. ## Metrics to Compute | Metric | Formula | Source | |--------|---------|--------| | Cycle Time (median + P85) | Time from "doing" to "done" per item | Card/issue transition history | | Throughput | Items completed in period | Cards/issues moved to done | | WIP | Items currently in doing/review | Current board state | | Aging WIP | In-progress items with no activity for 5+ days | dateLastActivity or changelog | | Blockers | Items with "blocked" label or blocker priority | Labels/flags | | Sprint Burndown | Done points vs. committed points (Jira only) | Story points field | ## List/Status Classification Map names to workflow states using these patterns (case-insensitive): - **Backlog:** backlog, to do, todo, icebox, upcoming - **Doing:** doing, in progress, working, development, dev, active - **Review:** review, testing, qa, validation, code review - **Done:** done, complete, finished, deployed, released, closed For Jira, use `statusCategory.key`: `new` = backlog, `indeterminate` = doing, `done` = done. ## Health Score Logic - **🟢 GOOD:** No significant issues. Steady flow. - **🟡 ATTENTION:** WIP exceeds 10 items, OR items aging without activity, OR blockers present. - **🔴 CONCERN:** Cycle time median exceeds 7 days, OR multiple blockers, OR very low throughput. ## Report Format ``` 📊 Agile Health Report — [Board/Project Name] Period: last [N] days 🔄 Throughput: [X] items completed ⏱ Cycle Time: Median [X]d | P85 [X]d ([N] items measured) 📋 WIP: [X] items in progress 📈 Sprint Progress: [X]/[Y] points ([Z]%) — Jira only 🚫 Blocked: [X] items — [names] 🧓 Stale: "[item]" (no activity [X]d) [🟢/🟡/🔴] Health — [summary] ``` ## Coaching Suggestions Include actionable advice based on findings: - High WIP: "Consider a WIP limit of [team size x 1.5]. What needs finishing before starting something new?" - Slow cycle time: "Where do items spend the most time? Look at the flow between columns." - Stale items: "This item hasn't moved in [X] days. Still a priority, or should we park it?" - Blockers: "What would it take to unblock [item]? Who needs to be involved?" - Good health: "Flow looks healthy. What's one thing to improve next sprint?" ## Platform API Details - **Trello endpoints and patterns:** See `references/trello-api.md` - **Jira endpoints and patterns:** See `references/jira-api.md` - **Detailed metric definitions:** See `references/metrics.md` ## Credential Formats ### Trello ```json {"api_key": "...", "token": "..."} ``` Also accepts: `apiKey` + `apiToken` ### Jira ```json {"instance": "mycompany", "email": "user@example.com", "api_token": "..."} ``` ## Scheduling For automated recurring reports, create a cron job: - Schedule: weekly Monday 9:00 AM - Task: Run agile-observer for board [X], deliver report to primary channel