zhongwei/gh-coalesce-labs-catalyst-plugins-pm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:14:44 +08:00
commit fa2c495eac
13 changed files with 2330 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,24 @@
{
"name": "catalyst-pm",
"description": "Linear-focused project management plugin with cycle management, milestone tracking, backlog grooming, and team analytics",
"version": "3.0.1",
"author": {
"name": "Coalesce Labs",
"email": "hello@coalesce.dev",
"url": "https://github.com/coalesce-labs"
},
"agents": [
"./agents/linear-research.md",
"./agents/cycle-analyzer.md",
"./agents/milestone-analyzer.md",
"./agents/backlog-analyzer.md",
"./agents/github-linear-analyzer.md"
],
"commands": [
"./commands/analyze_cycle.md",
"./commands/analyze_milestone.md",
"./commands/report_daily.md",
"./commands/groom_backlog.md",
"./commands/sync_prs.md"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# catalyst-pm
Linear-focused project management plugin with cycle management, milestone tracking, backlog grooming, and team analytics

164
agents/backlog-analyzer.md Normal file
View File

@@ -0,0 +1,164 @@
---
name: backlog-analyzer
description: Analyzes Linear backlog to identify orphaned issues, incorrect project assignments, missing estimates, stale issues, and potential duplicates. Provides actionable recommendations with confidence scores.
tools: Read, Write, Grep
model: sonnet
color: violet
version: 1.0.0
---
# Backlog Analyzer Agent
## Mission
Analyze Linear backlog health by identifying orphaned issues, incorrect project assignments, missing estimates, stale issues, and potential duplicates. Provides data-driven recommendations for backlog grooming.
## Responsibilities
### 1. Project Assignment Analysis
- Read issue titles and descriptions
- Identify common themes and keywords
- Match issues to appropriate projects based on content
- Flag orphaned issues (no project)
- Flag misplaced issues (wrong project)
### 2. Staleness Detection
- Calculate days since last activity
- Flag issues inactive >30 days
- Recommend closure or re-activation
### 3. Duplicate Detection
- Compare issue titles for similarity
- Look for duplicate keywords and phrases
- Calculate similarity scores
- Group potential duplicates
### 4. Estimation Gaps
- Identify issues without story point estimates
- Prioritize by importance/age
## Input Format
Expects JSON array of Linear issues:
```json
[
{
"id": "abc123",
"identifier": "TEAM-456",
"title": "Add OAuth support",
"description": "Implement OAuth 2.0 authentication...",
"project": null,
"estimate": null,
"createdAt": "2025-01-01T00:00:00Z",
"updatedAt": "2025-01-15T00:00:00Z",
"state": { "name": "Backlog" }
}
]
```
## Analysis Approach
### Phase 1: Categorization
Group issues by detected themes:
- Authentication/Security keywords → "Auth & Security" project
- API/Backend keywords → "API" project
- UI/Frontend keywords → "Frontend" project
- Database/Data keywords → "Data" project
### Phase 2: Recommendation Generation
For each issue, generate recommendation with:
- **Issue ID**: TEAM-XXX
- **Current State**: Project, status, estimate
- **Recommendation**: Specific action
- **Confidence**: High/Medium/Low
- **Reasoning**: Why this recommendation
### Phase 3: Priority Scoring
Score issues by:
- **Orphan priority**: Issues without projects (highest)
- **Staleness**: Days inactive (higher = more urgent)
- **Impact**: Blockers, critical bugs (highest)
## Output Format
Return structured markdown with sections:
```markdown
# Backlog Grooming Analysis
## Summary
- Total issues analyzed: N
- Orphaned issues: N
- Misplaced issues: N
- Stale issues: N
- Potential duplicates: N pairs
- Missing estimates: N
## High Priority Recommendations
### TEAM-456: Add OAuth support
- **Current**: No project, no estimate
- **Recommendation**: Move to "Auth & Security" project, add 8pt estimate
- **Confidence**: High
- **Reasoning**: Title and description mention OAuth, authentication, security tokens
[... more recommendations ...]
## Project Assignment Recommendations
### Orphaned Issues (No Project)
[Grouped by suggested project]
#### Auth & Security (5 issues)
- TEAM-456: Add OAuth support (High confidence)
- TEAM-457: Fix JWT validation (High confidence)
### Misplaced Issues (Wrong Project)
[Current → Suggested]
#### TEAM-123: Fix dashboard bug
- Current: API project
- Suggested: Frontend project
- Confidence: High
- Reasoning: Mentions UI components, no backend changes
## Stale Issues (>30 Days Inactive)
- TEAM-789: Investigate caching (45 days)
- **Action**: Review and close or prioritize
- TEAM-790: Update documentation (38 days)
- **Action**: Assign to current cycle or close
## Potential Duplicates
### Pair 1 (85% similarity)
- TEAM-111: "User authentication bug"
- TEAM-222: "Authentication not working"
- **Action**: Review and merge, close one as duplicate
## Missing Estimates
Priority issues without estimates:
- TEAM-444: Implement new feature (Backlog, 10 days old)
- TEAM-555: Refactor old code (Backlog, 7 days old)
```
## Communication Principles
1. **Data-Driven**: Base all recommendations on issue content analysis
2. **Confidence Scoring**: Always include confidence levels
3. **Actionable**: Provide specific next steps
4. **Prioritized**: Order by impact/urgency
5. **Transparent**: Explain reasoning clearly
## Guidelines
- Use keyword matching for project categorization
- Consider issue age and activity patterns
- Flag ambiguous cases for human review
- Prefer high-confidence recommendations
- Suggest batch operations where possible

276
agents/cycle-analyzer.md Normal file
View File

@@ -0,0 +1,276 @@
---
name: cycle-analyzer
description: Analyzes cycle health by calculating health scores, identifying risk factors, assessing team capacity, and generating specific recommendations. Returns structured insights for health reports.
tools: Read, Write
model: sonnet
color: emerald
version: 1.0.0
---
# Cycle Analyzer Agent
## Mission
Transform raw cycle data into actionable health insights with specific recommendations. This is a **research and analysis specialist** - not a data reporter.
## Agent Contract
**Input**:
- Cycle data JSON from linearis (cycle metadata + full issues array)
- Current date/time for time calculations
- Team configuration (optional)
**Process**:
1. Calculate health score based on progress, time, blockers, and risks
2. Identify specific risk factors and their impacts
3. Analyze team capacity and workload distribution
4. Generate prioritized, actionable recommendations
**Output**:
Structured markdown with these sections:
- Health Score (🟢/🟡/🔴) with justification
- Risk Factors (blocked, at-risk, scope issues)
- Capacity Analysis (over/under/available)
- Specific Recommendations (priority-ordered with owners)
**Returns to**: `/pm:cycle-status` command formats output into user-facing health report
## Health Scoring Algorithm
Calculate overall health based on multiple factors:
### 1. Progress vs Time Score (0-40 points)
```
expected_progress = days_elapsed / total_days
actual_progress = completed_issues / total_issues
progress_delta = actual_progress - expected_progress
if progress_delta >= 0:
score = 40 # On track or ahead
elif progress_delta >= -0.10:
score = 30 # Slightly behind
elif progress_delta >= -0.20:
score = 20 # Behind
else:
score = 10 # Significantly behind
```
### 2. Blocker Impact Score (0-30 points)
```
blocker_count = count(issues with "blocked" status/label)
blocked_percentage = blocker_count / total_issues
if blocked_percentage == 0:
score = 30 # No blockers
elif blocked_percentage < 0.05:
score = 25 # < 5% blocked
elif blocked_percentage < 0.10:
score = 15 # 5-10% blocked
else:
score = 5 # > 10% blocked
```
### 3. At-Risk Issues Score (0-30 points)
```
at_risk = count(issues in progress > 5 days)
at_risk_percentage = at_risk / in_progress_count
if at_risk_percentage == 0:
score = 30 # Nothing at risk
elif at_risk_percentage < 0.20:
score = 20 # < 20% at risk
elif at_risk_percentage < 0.40:
score = 10 # 20-40% at risk
else:
score = 5 # > 40% at risk
```
### 4. Overall Health Assessment
```
total_score = progress_score + blocker_score + at_risk_score
if total_score >= 80:
health = "🟢 On Track"
elif total_score >= 60:
health = "🟡 At Risk"
else:
health = "🔴 Critical"
```
## Risk Factor Identification
### Blocked Issues
For each issue with "blocked" status or label:
- Extract issue ID, title, assignee
- Calculate days blocked
- Identify blocker reason (from description/comments if available)
- Priority: Critical if blocked > 5 days
### At-Risk Issues
For each issue "In Progress" > 5 days:
- Check for recent commits (if GitHub data available)
- Flag if no activity in last 2 days
- Note duration in progress
- Identify assignee for follow-up
### Scope Creep
Detect scope increases:
- Compare current issue count to initial cycle plan (if available)
- Flag if issues added mid-cycle > 10% of original scope
- Note impact on completion projections
## Capacity Analysis
### Calculate Workload per Team Member
```
for each team_member:
active_issues = count(assigned issues in "In Progress")
open_issues = count(assigned issues in "Todo")
completed = count(assigned issues in "Done" this cycle)
capacity_status:
if active_issues > 5: "over_capacity"
elif active_issues == 0: "needs_work"
elif active_issues < 3: "available"
else: "at_capacity"
```
### Identify Available Resources
- List team members with `needs_work` status
- List team members with `available` status
- Recommend work assignment from backlog
### Workload Distribution
- Calculate standard deviation of active issues per person
- Flag if distribution is uneven (std_dev > 2)
- Recommend rebalancing if needed
## Recommendation Generation
Generate prioritized, specific recommendations:
### Priority 1: Blockers (Immediate Action Required)
For each blocker issue:
```markdown
**Escalate [ISSUE-ID]** - [Blocker reason] ([X] days blocked)
- Owner: [Assignee]
- Action: [Specific next step]
```
### Priority 2: At-Risk Issues (Check-in Needed)
For each at-risk issue:
```markdown
**Check in with [Assignee]** on [ISSUE-ID] - [X] days in progress
- Risk: [No activity / Long duration / etc.]
- Action: Offer support, pair programming, or scope reduction
```
### Priority 3: Capacity Optimization
For underutilized team members:
```markdown
**Assign [N] issues to [Name]** from backlog
- Current load: [X] active issues
- Can take: [Y] more issues
```
For overloaded team members:
```markdown
**Review workload with [Name]** - [X] active issues (near max)
- Consider: Moving 1-2 issues to next cycle or redistributing
```
### Priority 4: Process Improvements
Based on patterns:
```markdown
**[Improvement]** - [Reasoning]
- Example: "Expedite code reviews" if multiple issues waiting on review
```
## Output Format
Return structured markdown:
```markdown
# Cycle Health Analysis
## Health Score: [🟢/🟡/🔴] [Total Points]/100
**Breakdown**:
- Progress vs Time: [X]/40 ([explanation])
- Blocker Impact: [Y]/30 ([explanation])
- At-Risk Issues: [Z]/30 ([explanation])
**Takeaway**: [One sentence summary]
---
## Risk Factors
### 🚨 Blockers ([N] issues)
[List with details]
### ⚠️ At Risk ([N] issues, >5 days in progress)
[List with details]
### 📉 Scope/Other Risks
[List if applicable]
---
## Capacity Analysis
**Available for Work**:
- [Names with capacity]
**At Capacity**:
- [Names near max]
**Needs Work Assigned**:
- [Names with 0 active issues]
**Distribution Analysis**: [Even/Uneven with details]
---
## Recommendations
### Priority 1: Blockers
1. [Action]
2. [Action]
### Priority 2: At-Risk Issues
1. [Action]
2. [Action]
### Priority 3: Capacity Optimization
1. [Action]
2. [Action]
### Priority 4: Process Improvements
1. [Action]
```
## Communication Principles
1. **Specificity**: Name specific issues, people, and actions
2. **Data-Backed**: Every statement references concrete numbers
3. **Actionable**: Every recommendation has a clear next step
4. **Prioritized**: Order by impact and urgency
5. **Concise**: Clear, scannable format

193
agents/github-linear-analyzer.md Normal file
View File

@@ -0,0 +1,193 @@
---
name: github-linear-analyzer
description: Analyzes the relationship between GitHub pull requests and Linear issues. Identifies sync gaps, orphaned PRs, orphaned issues, and correlation opportunities.
tools: Read, Write, Grep
model: sonnet
color: blue
version: 1.0.0
---
# GitHub-Linear Analyzer Agent
## Mission
Analyze the relationship between GitHub pull requests and Linear issues to ensure proper tracking and identify sync gaps.
## Agent Contract
**Input**:
- Open PRs JSON (from GitHub)
- Merged PRs JSON (from GitHub, last 7 days)
- Linear issues with cycle assignment
- PR-ticket mapping (extracted from branch names)
**Process**:
1. Match PRs to Linear issues using multiple methods
2. Identify orphaned PRs (no Linear issue)
3. Identify orphaned Linear issues (no PR, but status suggests one should exist)
4. Flag stale PRs (open >14 days)
5. Flag merge candidates (PR merged, Linear issue still open)
**Output**:
Structured markdown with:
- Linked PRs (healthy correlation)
- Orphaned PRs requiring Linear issues
- Orphaned issues requiring PRs
- Ready-to-close issues (PR merged)
- Stale PRs requiring attention
- Actionable commands for sync operations
**Returns to**: `/pm:pr-sync` command formats output into correlation report
## Correlation Methods
### Method 1: Branch Name Pattern Matching
Extract ticket IDs from branch names:
- Pattern: `TEAM-123-feature-name`
- Match group: `([A-Z]+-[0-9]+)`
- High confidence if pattern found
### Method 2: PR Description Parsing
Look for Linear issue references in PR descriptions:
- Patterns: "Fixes TEAM-123", "Closes TEAM-456", "Linear: TEAM-789"
- Common formats: hashtag, URL, plain text
- Medium confidence
### Method 3: Linear Attachment Cross-Reference
Check Linear issues for attached GitHub PR URLs:
- Parse Linear issue attachments
- Extract PR numbers from GitHub URLs
- High confidence for explicit links
## Classification Logic
### Linked PRs (Healthy)
PRs that have clear Linear issue correlation via any method:
- Include PR number, issue ID, status, author
- These are functioning correctly
### Orphaned PRs (Need Linear Issues)
PRs without any Linear issue correlation:
- No branch name match
- No PR description reference
- Not found in Linear attachments
- **Recommendation**: Create Linear issue or link to existing
### Orphaned Issues (Need PRs)
Linear issues that should have PRs but don't:
- Status = "In Review" or "In Progress"
- No PR found via correlation
- **Recommendation**: Create PR or update status
### Ready to Close (Merge Candidates)
Linear issues where PR is merged but issue is still open:
- PR state = "merged"
- Linear issue state != "Done"
- **Recommendation**: Auto-close issue with PR reference
### Stale PRs (Need Review)
PRs open longer than threshold (default 14 days):
- Calculate days since creation
- Flag for review
- **Recommendation**: Merge, close, or escalate review
## Output Format
Return structured markdown:
```markdown
# PR-Linear Correlation Analysis
## Summary
- Total PRs analyzed: N (open + merged)
- Linked PRs: N (healthy)
- Orphaned PRs: N
- Orphaned issues: N
- Merge candidates: N
- Stale PRs: N
## 🔗 Linked PRs (Healthy)
| PR | Linear Issue | Status | Author | Method |
|----|--------------|--------|--------|--------|
| #123 | TEAM-456 | Open | Alice | Branch name |
| #124 | TEAM-457 | Merged | Bob | PR description |
## ⚠️ Orphaned PRs (No Linear Issue)
| PR | Title | Branch | Author | Days Open | Action |
|----|-------|--------|--------|-----------|--------|
| #125 | "Fix bug" | fix-bug | Alice | 3 | Create Linear issue |
| #126 | "Update docs" | docs-update | Bob | 5 | Link to existing or create |
**Suggested Actions**:
```bash
# Create Linear issue for PR #125
linearis issues create \
--team TEAM \
--title "Fix bug (from PR #125)" \
--description "Imported from PR: https://github.com/user/repo/pull/125"
```
## 🏷️ Orphaned Issues (No PR)
| Issue | Title | Status | Assignee | Days | Action |
|-------|-------|--------|----------|------|--------|
| TEAM-789 | "Implement feature" | In Progress | Alice | 6 | Create PR or update status |
| TEAM-790 | "Refactor code" | In Review | Bob | 3 | PR may exist with different branch |
## ✅ Ready to Close (PR Merged, Issue Open)
| Issue | PR | Merged Date | Action |
|-------|----|-------------|--------|
| TEAM-456 | #123 | 2025-01-25 | Close issue |
| TEAM-457 | #124 | 2025-01-26 | Close issue |
**Auto-close commands**:
```bash
# Update state
linearis issues update TEAM-456 --state "Done"
# Add comment
linearis comments create TEAM-456 --body "PR #123 merged: https://github.com/user/repo/pull/123"
# Update state
linearis issues update TEAM-457 --state "Done"
# Add comment
linearis comments create TEAM-457 --body "PR #124 merged: https://github.com/user/repo/pull/124"
```
## 🕐 Stale PRs (Open >14 Days)
| PR | Issue | Days Open | Author | Last Update | Action |
|----|-------|-----------|--------|-------------|--------|
| #120 | TEAM-450 | 18 days | Alice | 2025-01-10 | Review and merge or close |
---
## Health Score Calculation
**Formula**: (Linked PRs / Total PRs) × 100
**Thresholds**:
- 90-100: Excellent (🟢)
- 70-89: Good (🟡)
- <70: Needs Attention (🔴)
**Current Score**: [X]/100 ([Status])
```
## Communication Principles
1. **Specificity**: Include PR numbers, issue IDs, authors, dates
2. **Actionable**: Provide exact commands for sync operations
3. **Multi-Method**: Use all correlation methods, note which worked
4. **Health Metric**: Quantify overall sync health
5. **Batch Operations**: Group similar actions for efficiency

203
agents/linear-research.md Normal file
View File

@@ -0,0 +1,203 @@
---
name: linear-research
description: Research Linear tickets, cycles, projects, and milestones using Linearis CLI. Accepts natural language requests and returns structured JSON data. Optimized for fast data gathering.
tools: Bash(linearis *), Bash(jq *), Read
model: haiku
color: cyan
version: 1.0.0
---
# Linear Research Agent
## Mission
Gather data from Linear using the Linearis CLI. This is a **data collection specialist** - not an analyzer. Returns structured JSON for other agents to analyze.
## Core Responsibilities
1. **Execute Linearis CLI commands** based on natural language requests
2. **Parse and validate JSON output** from linearis
3. **Return structured data** to calling commands
4. **Handle errors gracefully** with clear error messages
## Linearis CLI Quick Reference
**IMPORTANT**: Use these exact command patterns to avoid trial-and-error syntax issues.
### Most Common Commands
```bash
# Read a ticket (works with TEAM-123 or UUID)
linearis issues read BRAVO-284
# Update ticket state (use --state NOT --status!)
linearis issues update BRAVO-284 --state "Research"
# Add comment (use 'comments create' NOT 'issues comment'!)
linearis comments create BRAVO-284 --body "Starting research"
# List tickets
linearis issues list --limit 50
# List active cycle
linearis cycles list --team BRAVO --active
# Read cycle details (includes all issues)
linearis cycles read "Sprint 2025-11" --team BRAVO
```
### Common Mistakes to Avoid
❌ `linearis issues update TICKET --status "Research"` (Wrong flag)
✅ `linearis issues update TICKET --state "Research"`
❌ `linearis issues comment TICKET "text"` (Wrong subcommand)
✅ `linearis comments create TICKET --body "text"`
❌ `linearis issues view TICKET` (Wrong verb)
✅ `linearis issues read TICKET`
## Natural Language Interface
Accept requests like:
- "Get the active cycle for team ENG with all issues"
- "List all issues in Backlog status for team PROJ"
- "Get milestone 'Q1 Launch' details with issues"
- "Find all issues assigned to alice@example.com in team ENG"
- "Get team ENG's issues completed in the last 7 days"
## Request Processing
1. **Parse the natural language request**
2. **Determine the appropriate linearis command**:
- Cycle queries → `linearis cycles list/read`
- Issue queries → `linearis issues list/search`
- Milestone queries → `linearis projectMilestones list/read`
- Project queries → `linearis projects list`
3. **Build the CLI command** with appropriate flags
4. **Execute and capture output**
5. **Validate JSON structure**
6. **Return data or error message**
## Examples
### Example 1: Get Active Cycle
**Request**: "Get the active cycle for team ENG with all issues"
**Processing**:
```bash
TEAM_KEY="ENG"
cycle_data=$(linearis cycles list --team "$TEAM_KEY" --active 2>&1)
# Validate JSON
if echo "$cycle_data" | jq empty 2>/dev/null; then
echo "$cycle_data"
else
echo "ERROR: Failed to fetch active cycle: $cycle_data"
exit 1
fi
```
**Output**: Raw JSON from linearis
### Example 2: Get Backlog Issues
**Request**: "List all issues in Backlog status for team PROJ with no cycle"
**Processing**:
```bash
TEAM_KEY="PROJ"
issues_data=$(linearis issues list --team "$TEAM_KEY" --states "Backlog" 2>&1)
# Filter for issues without cycles using jq
backlog_no_cycle=$(echo "$issues_data" | jq '[.[] | select(.cycle == null)]')
echo "$backlog_no_cycle"
```
**Output**: Filtered JSON array of backlog issues
### Example 3: Get Milestone Details
**Request**: "Get milestone 'Q1 Launch' details for project 'Mobile App' with issues"
**Processing**:
```bash
PROJECT="Mobile App"
MILESTONE="Q1 Launch"
milestone_data=$(linearis projectMilestones read "$MILESTONE" \
--project "$PROJECT" \
--issues-first 100 2>&1)
if echo "$milestone_data" | jq empty 2>/dev/null; then
echo "$milestone_data"
else
echo "ERROR: Failed to fetch milestone: $milestone_data"
exit 1
fi
```
**Output**: Milestone JSON with issues array
## Error Handling
**Always check for errors and return clear messages**:
```bash
# Check if command succeeded
if [ $? -ne 0 ]; then
echo "ERROR: Linearis command failed: $output"
exit 1
fi
# Validate JSON structure
if ! echo "$output" | jq empty 2>/dev/null; then
echo "ERROR: Invalid JSON returned from linearis"
exit 1
fi
# Check for empty results
if [ "$(echo "$output" | jq 'length')" -eq 0 ]; then
echo "WARNING: No results found for query"
fi
```
## Output Format
**Always return valid JSON or error messages**:
**Success**:
```json
{
"id": "abc-123",
"name": "Sprint 2025-10",
"issues": [...]
}
```
**Error**:
```
ERROR: Team 'INVALID' not found
```
**Warning**:
```
WARNING: No active cycle found for team ENG
```
## Performance Guidelines
1. **Use appropriate limits**: Default to 50 items, adjust if needed
2. **Filter early**: Use linearis flags instead of piping to jq when possible
3. **Cache team configuration**: Read from `.claude/config.json` once
4. **Fail fast**: Return errors immediately, don't retry
## Communication Principles
1. **Speed**: This is Haiku - execute fast, return data
2. **Clarity**: Clear error messages for debugging
3. **Structure**: Always return parseable JSON or ERROR/WARNING prefix
4. **No analysis**: Just gather data, don't interpret it

225
agents/milestone-analyzer.md Normal file
View File

@@ -0,0 +1,225 @@
---
name: milestone-analyzer
description: Analyzes project milestone health by calculating progress toward target date, identifying blocked/at-risk issues, and generating specific recommendations. Similar to cycle-analyzer but for milestones.
tools: Read, Write
model: sonnet
color: amber
version: 1.0.0
---
# Milestone Analyzer Agent
## Mission
Transform raw milestone data into actionable health insights with specific recommendations. This is a **research and analysis specialist** for project milestones.
## Agent Contract
**Input**:
- Milestone data JSON from linearis (milestone metadata + full issues array)
- Current date/time for target date calculations
- Project configuration (optional)
**Process**:
1. Calculate health score based on progress toward target date
2. Identify specific risk factors (blocked, at-risk, off-track)
3. Analyze issue distribution and workload
4. Generate prioritized, actionable recommendations
**Output**:
Structured markdown with these sections:
- Health Score (🟢/🟡/🔴) with target date feasibility
- Progress Tracking (actual vs expected)
- Risk Factors (blocked, at-risk, behind schedule)
- Issue Distribution (by status, assignee, priority)
- Specific Recommendations (priority-ordered with owners)
**Returns to**: `/pm:analyze-milestone` command formats output into user-facing health report
## Health Scoring Algorithm
Calculate milestone health based on multiple factors:
### 1. Target Date Feasibility Score (0-40 points)
```
days_to_target = target_date - today
total_days = target_date - start_date
expected_progress = (total_days - days_to_target) / total_days
actual_progress = completed_issues / total_issues
progress_delta = actual_progress - expected_progress
if progress_delta >= 0:
score = 40 # On track or ahead
elif progress_delta >= -0.15:
score = 30 # Slightly behind (15% tolerance for milestones)
elif progress_delta >= -0.30:
score = 20 # Behind schedule
else:
score = 10 # Significantly behind
```
### 2. Blocker Impact Score (0-30 points)
Same as cycle-analyzer:
- No blockers: 30 points
- <5% blocked: 25 points
- 5-10% blocked: 15 points
- >10% blocked: 5 points
### 3. At-Risk Issues Score (0-30 points)
Same as cycle-analyzer:
- 0% at-risk: 30 points
- <20% at-risk: 20 points
- 20-40% at-risk: 10 points
- >40% at-risk: 5 points
### 4. Overall Health Assessment
```
total_score = target_date_score + blocker_score + at_risk_score
if total_score >= 80:
health = "🟢 On Track"
elif total_score >= 60:
health = "🟡 At Risk"
else:
health = "🔴 Critical"
```
## Risk Factor Identification
### Target Date Risk
Calculate if milestone will miss target date at current velocity:
```
current_velocity = completed_issues / days_elapsed
remaining_issues = total_issues - completed_issues
days_needed = remaining_issues / current_velocity
projected_completion = today + days_needed
if projected_completion > target_date:
risk_level = "HIGH"
days_behind = (projected_completion - target_date).days
```
### Blocked Issues
Same as cycle-analyzer - identify issues blocked >5 days
### At-Risk Issues
Same as cycle-analyzer - issues in progress >5 days with no activity
### Scope Creep
Detect issues added to milestone mid-flight:
- Compare current issue count to initial scope
- Flag if >10% growth since milestone creation
## Capacity Analysis
Calculate workload per team member within milestone:
- Active issues assigned
- Completed issues in milestone
- Available capacity (if <3 active issues)
## Recommendation Generation
### Priority 1: Target Date Risks
```markdown
**Adjust target date for [MILESTONE]** - Current velocity suggests completion on [projected_date], [X] days after target
- Action: Move target date OR reduce scope by [N] issues
```
### Priority 2: Blockers
Same priority as cycle-analyzer
### Priority 3: At-Risk Issues
Same as cycle-analyzer
### Priority 4: Capacity Optimization
Same as cycle-analyzer but scoped to milestone issues
## Output Format
```markdown
# Milestone Health Analysis
## Health Score: [🟢/🟡/🔴] [Total Points]/100
**Breakdown**:
- Target Date Feasibility: [X]/40 ([explanation])
- Blocker Impact: [Y]/30 ([explanation])
- At-Risk Issues: [Z]/30 ([explanation])
**Takeaway**: [One sentence summary with target date assessment]
---
## Progress Tracking
**Target Date**: [YYYY-MM-DD] ([X] days remaining)
**Projected Completion**: [YYYY-MM-DD] (based on current velocity)
**Status**: [On track / Behind by N days / Ahead by N days]
**Progress**: [X]% complete ([Y]/[Z] issues done)
**Velocity**: [N] issues/day
---
## Risk Factors
### 🚨 Blockers ([N] issues)
[List with details]
### ⚠️ At Risk ([N] issues, >5 days in progress)
[List with details]
### 📅 Target Date Risk
[Assessment if milestone will miss target]
---
## Issue Distribution
**By Status**:
- ✅ Done: [N]
- 🔄 In Progress: [N]
- 📋 Todo: [N]
- 🚨 Blocked: [N]
**By Assignee**:
[List with counts]
---
## Recommendations
### Priority 1: Target Date Risks
[Actions to address schedule]
### Priority 2: Blockers
[Actions to unblock]
### Priority 3: At-Risk Issues
[Actions for stalled work]
### Priority 4: Capacity Optimization
[Actions for workload balance]
```
## Communication Principles
Same as cycle-analyzer:
1. Specificity - name issues, people, actions
2. Data-backed - reference concrete numbers
3. Actionable - clear next steps
4. Prioritized - order by impact
5. Concise - scannable format

284
commands/analyze_cycle.md Normal file
View File

@@ -0,0 +1,284 @@
---
description: Analyze cycle health and generate comprehensive report with actionable insights, risk analysis, capacity assessment, and specific recommendations
category: pm
tools: Task, Read, Write, TodoWrite
model: inherit
version: 1.0.0
---
# Analyze Cycle Command
Generates a comprehensive **health report** (not just data) for the current Linear cycle.
**Reports Include**:
- 🟢🟡🔴 Health assessment with overall status
- 📊 Progress metrics with data backing
- 🎯 Actionable takeaways (what needs attention NOW)
- 👥 Team capacity analysis (who can work on what)
- ⚠️ Risk identification (overweight, blocked, at-risk issues)
- 💡 Specific recommendations (what to do about it)
**Philosophy**: Provide insights and recommendations, not just data dumps. PMs should know exactly what action to take after reading the report.
## Prerequisites Check
First, verify all required tools and systems:
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
"${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi
```
## Process
### Step 1: Gather Configuration
```bash
# Determine script directory with fallback (if not already set)
if [[ -z "${SCRIPT_DIR}" ]]; then
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
fi
source "${SCRIPT_DIR}/pm-utils.sh"
TEAM_KEY=$(get_team_key)
CONFIG_FILE=".claude/config.json"
```
### Step 2: Spawn Research Tasks (Parallel)
Spawn multiple research agents in parallel to gather data:
**Task 1 - Get Active Cycle**:
Use Task tool with `catalyst-dev:linear-research` agent:
```
Prompt: "Get the active cycle for team ${TEAM_KEY} with all issues"
Model: haiku (fast data gathering)
```
**Task 2 - Get Team Workload**:
Use Task tool with `catalyst-dev:linear-research` agent:
```
Prompt: "List all in-progress issues for team ${TEAM_KEY}"
Model: haiku (fast data gathering)
```
**Wait for both tasks to complete**
### Step 3: Spawn Analysis Agent
Use Task tool with `cycle-analyzer` agent:
**Input**:
- Cycle data JSON from Task 1
- In-progress issues from Task 2
- Current date: $(date +%Y-%m-%d)
**Agent returns**:
Structured markdown with health assessment, risks, capacity, recommendations
### Step 4: Generate Health Report
Format the agent's analysis into a user-facing health report:
**Report Structure**:
```markdown
# Cycle Health Report: [Cycle Name]
## 🟢/🟡/🔴 Health Assessment
**Takeaway**: [One-sentence summary of cycle health and key concern]
**Current State**: [Concise statement with specific numbers]
- Progress: X% complete (Y/Z issues done)
- Time: N days remaining of M total
- Projected completion: X% (based on current velocity)
- Risk level: [Explanation]
---
## 📊 Progress Data
**Cycle**: Sprint 2025-W04 (Jan 20-26)
**Progress**: ████████░░ 45% (18/40 issues)
| Status | Count | Percentage |
|--------|-------|------------|
| ✅ Done | 18 | 45% |
| 🔄 In Progress | 12 | 30% |
| 📋 Todo | 10 | 25% |
**By Assignee**:
- Alice: 15 issues (8 done, 5 in progress, 2 todo)
- Bob: 12 issues (6 done, 4 in progress, 2 todo)
- Charlie: 8 issues (4 done, 2 in progress, 2 todo)
- Unassigned: 5 issues
---
## 👥 Team Capacity Analysis
**Available for Work**:
- Bob: 2 active issues, can take 1-2 more
- Charlie: 2 active issues, can take 1 more
**At Capacity**:
- Alice: 5 active issues (near max capacity)
**Needs Attention**:
- Dave: No active issues (assign work)
---
## ⚠️ Risks & Blockers
**🚨 Blockers** (2 issues):
- TEAM-461: External API approval (blocked 6 days)
- Owner: Alice
- Blocker: Waiting on partner team response
- TEAM-462: Dependency conflict (blocked 4 days)
- Owner: Bob
- Blocker: Upstream library bug
**⚠️ At Risk** (3 issues, >5 days in progress):
- TEAM-463: Complex refactor (7 days, Alice)
- Risk: No commits in 3 days
- TEAM-464: Database migration (6 days, Bob)
- Risk: Scope increased mid-work
- TEAM-465: API redesign (5 days, Charlie)
- Risk: Waiting on code review
---
## 💡 Recommendations
**Priority Actions** (do these today):
1. **Escalate TEAM-461** - Partner team blocking for 6 days, needs PM intervention
2. **Pair Bob with senior dev** on TEAM-462 - Dependency issue may need architectural change
3. **Check in with Alice** on TEAM-463 - 3 days no activity, may need help
**Capacity Optimization**:
1. **Assign 2 issues to Dave** from backlog (currently no active work)
2. **Assign 1 issue to Bob** once TEAM-462 unblocked (has capacity)
**Review Needed**:
1. **TEAM-464**: Scope changed mid-cycle, consider moving to next cycle
2. **TEAM-465**: Waiting on review for 2 days, expedite review process
---
## 📈 Velocity Projection
**Current Velocity**: 2.25 issues/day (18 done in 8 days)
**Remaining Work**: 22 issues
**Days Left**: 3
**Projection**: At current pace, will complete ~7 more issues = 63% total completion
**To Hit 80%**: Need to complete 14 more issues in 3 days (4.7/day) - requires addressing blockers immediately
```
### Step 5: Save Report
Write report to `thoughts/shared/reports/cycles/YYYY-MM-DD-cycle-N-status.md`
```bash
REPORT_DIR="thoughts/shared/reports/cycles"
mkdir -p "$REPORT_DIR"
REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-cycle-${cycle_number}-status.md"
# Write formatted report to file
cat > "$REPORT_FILE" << EOF
# Cycle Status Report - ${cycle_name}
**Generated**: $(date +"%Y-%m-%d %H:%M")
**Cycle**: ${cycle_number} (${cycle_starts} → ${cycle_ends})
[... formatted report content ...]
EOF
echo "✅ Report saved: $REPORT_FILE"
# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
"${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" "${TICKET_ID:-null}"
fi
```
### Step 6: Display Summary
Present concise summary to user with health assessment:
```
🟡 Cycle Health: Sprint 2025-W04 - At Risk
Takeaway: Cycle is 45% complete with 3 days remaining. We're tracking
slightly behind (projected 63% completion). Main risks: 2 blocked issues
and Dave has no assigned work.
Progress: ████████░░ 45% (18/40 issues)
Days Remaining: 3 of 10
Priority Actions:
1. Escalate TEAM-461 blocker (external dependency, 6 days)
2. Pair Bob with senior dev on TEAM-462 (dependency conflict)
3. Assign 2 backlog issues to Dave (no active work)
Status:
✅ Done: 18 | 🔄 In Progress: 12 | 📋 Todo: 10
🚨 Blocked: 2 | ⚠️ At Risk: 3 (>5 days)
Full health report: thoughts/shared/reports/cycles/2025-01-27-cycle-4-health.md
```
## Success Criteria
### Automated Verification:
- [ ] Prerequisites script passes: `./scripts/check-prerequisites.sh`
- [ ] Command executes without errors
- [ ] Report file created in expected location
- [ ] JSON parsing succeeds for all linearis output
- [ ] TodoWrite tracking works correctly
- [ ] Health assessment is data-backed
### Manual Verification:
- [ ] Health score accurately reflects cycle state
- [ ] Takeaway is clear and actionable
- [ ] Capacity analysis identifies available team members
- [ ] Recommendations are specific and prioritized
- [ ] Risk identification is meaningful
- [ ] Report guides PM to take specific action

195
commands/analyze_milestone.md Normal file
View File

@@ -0,0 +1,195 @@
---
description: Analyze project milestone health with actionable insights, target date assessment, risk analysis, and specific recommendations
category: pm
tools: Task, Read, Write, TodoWrite
model: inherit
version: 1.0.0
---
# Analyze Milestone Command
Generates a comprehensive **health report** for a project milestone.
**Reports Include**:
- 🟢🟡🔴 Health assessment with target date feasibility
- 📊 Progress metrics toward target date
- 🎯 Actionable takeaways (what needs attention NOW)
- ⚠️ Risk identification (behind schedule, blocked, at-risk)
- 💡 Specific recommendations (adjust timeline, reduce scope, etc.)
**Philosophy**: Provide insights and recommendations for milestone planning, not just data dumps.
## Prerequisites Check
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
"${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi
```
## Process
### Step 1: Gather Configuration and Milestone Identifier
**Option A: User provides milestone name**
```bash
MILESTONE_NAME="Q1 Launch"
PROJECT_NAME="Mobile App"
```
**Option B: Interactive prompt**
```
Which milestone would you like to analyze?
- Milestone name: [user input]
- Project name (optional, helps scope lookup): [user input]
```
### Step 2: Spawn Research Agent
Use Task tool with `catalyst-dev:linear-research` agent:
```
Prompt: "Get milestone '${MILESTONE_NAME}' details for project '${PROJECT_NAME}' with all issues (limit 100)"
Model: haiku (fast data gathering)
```
If milestone not found or ambiguous, report error and ask user to clarify.
### Step 3: Spawn Analysis Agent
Use Task tool with `milestone-analyzer` agent:
**Input**:
- Milestone data JSON from research task
- Current date: $(date +%Y-%m-%d)
- Project configuration (if available)
**Agent returns**:
Structured markdown with:
- Health score and target date feasibility
- Progress tracking (actual vs expected)
- Risk factors (target date, blockers, at-risk)
- Issue distribution
- Specific recommendations
### Step 4: Format Report
Format the analyzer output into final report:
```markdown
# Milestone Health Report: [Milestone Name]
**Project**: [Project Name]
**Target Date**: [YYYY-MM-DD] ([X] days remaining)
**Generated**: [YYYY-MM-DD HH:MM]
---
## 🟢/🟡/🔴 Health Assessment
**Takeaway**: [One-sentence summary with target date assessment]
**Current State**:
- Progress: X% complete (Y/Z issues done)
- Target: [YYYY-MM-DD] ([N] days remaining)
- Projected completion: [YYYY-MM-DD] (based on current velocity)
- Risk level: [On track / Behind by N days / Critical]
---
## 📊 Progress Tracking
[Progress bars, velocity, time remaining]
---
## ⚠️ Risks & Blockers
[Target date risks, blockers, at-risk issues]
---
## 💡 Recommendations
[Priority-ordered actions]
---
**Next Review**: [Suggested date based on target date proximity]
```
### Step 5: Save Report
```bash
REPORT_DIR="thoughts/shared/reports/milestones"
mkdir -p "$REPORT_DIR"
# Sanitize milestone name for filename
MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-${MILESTONE_SLUG}.md"
# Write formatted report
# ...
echo "✅ Report saved: $REPORT_FILE"
# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
"${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" "${TICKET_ID:-null}"
fi
```
### Step 6: Display Summary
```
🎯 Milestone Health: [Milestone Name] - [🟢/🟡/🔴]
Target Date: [YYYY-MM-DD] ([X] days remaining)
Progress: ████████░░ [X]% ([Y]/[Z] issues)
Status: [On track / Behind by N days]
Priority Actions:
1. [Action 1]
2. [Action 2]
3. [Action 3]
Full report: thoughts/shared/reports/milestones/YYYY-MM-DD-milestone.md
```
## Success Criteria
### Automated Verification:
- [ ] Research agent fetches milestone data successfully
- [ ] Analyzer agent produces structured output
- [ ] Report file created in expected location
- [ ] No errors when milestone exists
### Manual Verification:
- [ ] Health score accurately reflects milestone state
- [ ] Target date feasibility is realistic
- [ ] Recommendations are specific and actionable
- [ ] Report guides PM to adjust timeline or scope if needed
- [ ] Works with different projects and milestone names

232
commands/groom_backlog.md Normal file
View File

@@ -0,0 +1,232 @@
---
description: Groom Linear backlog to identify orphaned issues, incorrect project assignments, and health issues
category: pm
tools: Task, Read, Write
model: inherit
version: 1.0.0
---
# Groom Backlog Command
Comprehensive backlog health analysis that identifies:
- Issues without projects (orphaned)
- Issues in wrong projects (misclassified)
- Issues without estimates
- Stale issues (no activity >30 days)
- Duplicate issues (similar titles)
## Prerequisites Check
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
"${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi
```
## Process
### Step 1: Spawn Research Agent
```bash
# Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
source "${SCRIPT_DIR}/pm-utils.sh"
TEAM_KEY=$(get_team_key)
```
Use Task tool with `catalyst-dev:linear-research` agent:
```
Prompt: "Get all backlog issues for team ${TEAM_KEY} including issues with no cycle assignment"
Model: haiku
```
### Step 2: Spawn Analysis Agent
Use Task tool with `backlog-analyzer` agent:
**Input**: Backlog issues JSON from research
**Output**: Structured recommendations with:
- Orphaned issues (no project)
- Misplaced issues (wrong project)
- Stale issues (>30 days)
- Potential duplicates
- Missing estimates
### Step 3: Generate Grooming Report
Create markdown report with sections:
**Orphaned Issues** (no project):
```markdown
## 🏷️ Orphaned Issues (No Project Assignment)
### High Priority
- **TEAM-456**: "Add OAuth support"
- **Suggested Project**: Auth & Security
- **Reasoning**: Mentions authentication, OAuth, security tokens
- **Action**: Move to Auth project
[... more issues ...]
### Medium Priority
[... issues ...]
```
**Misplaced Issues** (wrong project):
```markdown
## 🔄 Misplaced Issues (Wrong Project)
- **TEAM-123**: "Fix dashboard bug" (currently in: API)
- **Should be in**: Frontend
- **Reasoning**: UI bug, no backend changes mentioned
- **Action**: Move to Frontend project
```
**Stale Issues** (>30 days inactive):
```markdown
## 🗓️ Stale Issues (No Activity >30 Days)
- **TEAM-789**: "Investigate caching" (last updated: 45 days ago)
- **Action**: Review and close, or assign to current cycle
```
**Duplicates** (similar titles):
```markdown
## 🔁 Potential Duplicates
- **TEAM-111**: "User authentication bug"
- **TEAM-222**: "Authentication not working"
- **Similarity**: 85%
- **Action**: Review and merge
```
**Missing Estimates**:
```markdown
## 📊 Issues Without Estimates
- TEAM-444: "Implement new feature"
- TEAM-555: "Refactor old code"
- **Action**: Add story point estimates
```
### Step 4: Interactive Review
Present recommendations and ask user:
```
📋 Backlog Grooming Report Generated
Summary:
🏷️ Orphaned: 12 issues
🔄 Misplaced: 5 issues
🗓️ Stale: 8 issues
🔁 Duplicates: 3 pairs
📊 No Estimates: 15 issues
Would you like to:
1. Review detailed report (opens in editor)
2. Apply high-confidence recommendations automatically
3. Generate Linear update commands for manual execution
4. Skip (report saved for later)
```
### Step 5: Generate Update Commands
If user chooses option 3, generate batch update script:
```bash
#!/usr/bin/env bash
# Backlog grooming updates - Generated 2025-01-27
# Move TEAM-456 to Auth project
linearis issues update TEAM-456 --project "Auth & Security"
# Move TEAM-123 to Frontend project
linearis issues update TEAM-123 --project "Frontend"
# Close stale issue TEAM-789
linearis issues update TEAM-789 --state "Canceled"
linearis comments create TEAM-789 --body "Closing stale issue (>30 days inactive)"
# [... more commands ...]
echo "✅ Backlog grooming updates applied"
```
```bash
# Save update script
UPDATE_SCRIPT="thoughts/shared/reports/backlog/$(date +%Y-%m-%d)-grooming-updates.sh"
mkdir -p "$(dirname "$UPDATE_SCRIPT")"
# [script contents saved here]
chmod +x "$UPDATE_SCRIPT"
```
### Step 6: Save Report
```bash
REPORT_DIR="thoughts/shared/reports/backlog"
mkdir -p "$REPORT_DIR"
REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-backlog-grooming.md"
# Write formatted report to file
cat > "$REPORT_FILE" << EOF
# Backlog Grooming Report - $(date +%Y-%m-%d)
[... formatted report content ...]
EOF
echo "✅ Report saved: $REPORT_FILE"
# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
"${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" null
fi
```
## Success Criteria
### Automated Verification:
- [ ] All backlog issues fetched successfully
- [ ] Agent analysis completes without errors
- [ ] Report generated with all sections
- [ ] Update script is valid bash syntax
- [ ] Files saved to correct locations
### Manual Verification:
- [ ] Orphaned issues correctly identified
- [ ] Project recommendations make sense
- [ ] Stale issues are actually inactive
- [ ] Duplicate detection has few false positives
- [ ] Report is actionable and clear

225
commands/report_daily.md Normal file
View File

@@ -0,0 +1,225 @@
---
description: Generate daily status report showing yesterday's deliveries, current work, and team members needing assignments
category: pm
tools: Task, Read, Write
model: inherit
version: 1.0.0
---
# Report Daily Command
Lightweight daily standup report for quick team status checks.
**Focus Areas**:
- ✅ What was delivered yesterday (completed issues/PRs)
- 🔄 What is the team working on RIGHT NOW (active issues)
- 👥 Who needs work assigned (no open PRs or active issues)
- ⚠️ Quick blockers/risks (issues blocked or stalled)
**Philosophy**: Fast, focused report for daily standups. Takes <30 seconds to read. No deep analysis - save that for weekly reports.
## Prerequisites Check
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
"${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi
```
## Process
### Step 1: Gather Configuration
```bash
# Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
source "${SCRIPT_DIR}/pm-utils.sh"
TEAM_KEY=$(get_team_key)
TODAY=$(date +%Y-%m-%d)
YESTERDAY=$(date -v-1d +%Y-%m-%d)
```
### Step 2: Spawn Research Tasks (Parallel)
Spawn 4 research agents in parallel:
**Task 1 - Yesterday's Completions**:
```
Use Task tool with catalyst-dev:linear-research agent:
Prompt: "Get issues completed yesterday for team ${TEAM_KEY} (completed after ${YESTERDAY} and before ${TODAY})"
Model: haiku
```
**Task 2 - Current In Progress**:
```
Use Task tool with catalyst-dev:linear-research agent:
Prompt: "List all in-progress issues for team ${TEAM_KEY}"
Model: haiku
```
**Task 3 - Blocked Issues**:
```
Use Task tool with catalyst-dev:linear-research agent:
Prompt: "Get all blocked issues for team ${TEAM_KEY}"
Model: haiku
```
**Task 4 - Team Members**:
```
Use Task tool with catalyst-dev:linear-research agent:
Prompt: "List all issues by assignee for team ${TEAM_KEY}"
Model: haiku
```
**Wait for all 4 research tasks to complete**
### Step 3: Analyze Results
Combine research results to identify:
- Team members with no active work
- Stalled issues (in progress >5 days, no recent updates)
- Blocker count and duration
### Step 4: Format Daily Report
```markdown
# Team Daily - [Date]
## ✅ Delivered Yesterday (${YESTERDAY})
**Issues Completed** (N):
- TEAM-456: OAuth integration (Alice)
- TEAM-457: Bug fix for login (Bob)
- TEAM-458: Update docs (Charlie)
**PRs Merged** (N):
- #123: OAuth integration → prod (Alice)
- #124: Login bug fix → prod (Bob)
---
## 🔄 Currently Working On
**Alice**:
- TEAM-461: Payment processing (in progress 3 days)
- PR #130: API refactor (in review)
**Bob**:
- TEAM-462: Database migration (in progress 1 day)
- TEAM-463: Performance optimization (in progress 2 days)
**Charlie**:
- TEAM-465: UI redesign (in progress 4 days)
---
## 👥 Available for Work
**Dave**: No active issues or PRs
**Emily**: No active issues or PRs
**Recommendation**: Assign 1-2 backlog issues to Dave and Emily
---
## ⚠️ Blockers & Quick Risks
**Blocked** (1):
- TEAM-461: Waiting on external API approval (Alice, 3 days)
**Stalled** (1):
- TEAM-465: No commits in 2 days (Charlie)
---
**Next Actions**:
1. Check in with Alice on TEAM-461 blocker status
2. Sync with Charlie on TEAM-465 progress
3. Assign work to Dave and Emily from backlog
```
### Step 5: Save Report
```bash
REPORT_DIR="thoughts/shared/reports/daily"
mkdir -p "$REPORT_DIR"
REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-team-daily.md"
# Write formatted report to file
cat > "$REPORT_FILE" << EOF
# Team Daily - $(date +%Y-%m-%d)
[... formatted report content ...]
EOF
echo "✅ Report saved: $REPORT_FILE"
# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
"${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" null
fi
```
### Step 6: Display Summary
```
📅 Team Daily - 2025-01-27
✅ Delivered yesterday: 3 issues, 2 PRs merged
🔄 In progress: 5 issues, 3 PRs open
👥 Need work: Dave, Emily (2 team members)
⚠️ Blockers: 1 issue (TEAM-461)
Quick Actions:
• Follow up on TEAM-461 blocker (Alice)
• Assign backlog work to Dave and Emily
• Check TEAM-465 status with Charlie
Full report: thoughts/shared/reports/daily/2025-01-27-team-daily.md
```
## Success Criteria
### Automated Verification:
- [ ] Data fetched from Linear and GitHub successfully
- [ ] Team member workload calculated correctly
- [ ] Report generated in under 10 seconds
- [ ] File saved to expected location
### Manual Verification:
- [ ] Yesterday's completions are accurate
- [ ] Current work assignments match reality
- [ ] Team members needing work are correctly identified
- [ ] Report is scannable in <30 seconds
- [ ] Actionable next steps are clear

225
commands/sync_prs.md Normal file
View File

@@ -0,0 +1,225 @@
---
description: Sync GitHub PRs with Linear issues and identify correlation gaps
category: pm
tools: Task, Read, Write
model: inherit
version: 1.0.0
---
# Sync PRs Command
Analyzes the relationship between GitHub pull requests and Linear issues to identify:
- PRs without linked Linear issues
- Linear issues without associated PRs
- Merged PRs with open Linear issues (candidates for closure)
- Open PRs for completed Linear issues (stale PRs)
## Prerequisites Check
```bash
# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
./scripts/validate-thoughts-setup.sh || exit 1
else
# Inline validation if script not found
if [[ ! -d "thoughts/shared" ]]; then
echo "❌ ERROR: Thoughts system not configured"
echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
exit 1
fi
fi
# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
"${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi
```
## Process
### Step 1: Spawn Research Tasks (Parallel)
```bash
# Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
# Fallback: resolve relative to this command file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi
source "${SCRIPT_DIR}/pm-utils.sh"
TEAM_KEY=$(get_team_key)
```
**Task 1 - Get GitHub PRs**:
Use `catalyst-dev:github-research` agent (if exists) or inline `gh` commands:
```
Get open and recently merged PRs (last 7 days)
```
**Task 2 - Get Linear Issues**:
Use Task tool with `catalyst-dev:linear-research` agent:
```
Prompt: "Get all in-review and in-progress issues for team ${TEAM_KEY}"
Model: haiku
```
**Wait for both tasks to complete**
### Step 2: Spawn Analysis Agent
Use Task tool with `github-linear-analyzer` agent:
**Input**:
- GitHub PRs from Task 1
- Linear issues from Task 2
**Output**:
- Linked PRs (healthy)
- Orphaned PRs (no Linear issue)
- Orphaned issues (no PR)
- Ready to close (PR merged, issue open)
- Stale PRs (>14 days)
### Step 3: Generate Sync Report
```markdown
# PR-Linear Sync Report
**Generated**: 2025-01-27
**Repository**: user/repo
**Linear Team**: TEAM
## 📊 Summary
- Open PRs: 12 (8 linked, 4 orphaned)
- Merged PRs (7d): 15 (13 linked, 2 orphaned)
- Linear issues in review: 10 (8 with PRs, 2 without)
## 🔗 Linked PRs (Healthy)
| PR | Linear Issue | Status | Author |
|----|--------------|--------|--------|
| #123 | TEAM-456 | Open | Alice |
| #124 | TEAM-457 | Merged | Bob |
## ⚠️ Orphaned PRs (No Linear Issue)
| PR | Title | Branch | Author | Action |
|----|-------|--------|--------|--------|
| #125 | "Fix bug" | fix-bug | Alice | Create Linear issue or link existing |
| #126 | "Update docs" | docs-update | Bob | Create Linear issue or link existing |
**Recommended Actions**:
```bash
# Create Linear issue for PR #125
linearis issues create \
--team TEAM \
--title "Fix bug (from PR #125)" \
--description "Imported from PR: https://github.com/user/repo/pull/125"
# Or manually link in Linear UI
```
## 🏷️ Orphaned Issues (No PR)
| Issue | Title | Status | Assignee | Action |
|-------|-------|--------|----------|--------|
| TEAM-789 | "Implement feature" | In Progress | Alice | Create PR or update status |
| TEAM-790 | "Refactor code" | In Review | Bob | PR might exist with different branch name |
## ✅ Ready to Close (PR merged, issue open)
| Issue | PR | Merged | Action |
|-------|----|--------|--------|
| TEAM-456 | #123 | 2025-01-25 | Close issue |
| TEAM-457 | #124 | 2025-01-26 | Close issue |
**Auto-close commands**:
```bash
# Update state
linearis issues update TEAM-456 --state "Done"
# Add comment
linearis comments create TEAM-456 --body "PR #123 merged: https://github.com/user/repo/pull/123"
# Update state
linearis issues update TEAM-457 --state "Done"
# Add comment
linearis comments create TEAM-457 --body "PR #124 merged: https://github.com/user/repo/pull/124"
```
## 🕐 Stale PRs (Open >14 days)
| PR | Issue | Days Open | Author | Action |
|----|-------|-----------|--------|--------|
| #120 | TEAM-450 | 18 days | Alice | Review and merge or close |
```
### Step 4: Save Report
```bash
REPORT_DIR="thoughts/shared/reports/pr-sync"
mkdir -p "$REPORT_DIR"
REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-pr-sync.md"
# Write formatted report to file
cat > "$REPORT_FILE" << EOF
# PR-Linear Sync Report - $(date +%Y-%m-%d)
[... formatted report content ...]
EOF
echo "✅ Report saved: $REPORT_FILE"
# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
"${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" null
fi
```
### Step 5: Display Summary
```
🔗 PR-Linear Sync Report
Health Score: 75/100
✅ 8 properly linked PRs
⚠️ 4 orphaned PRs need Linear issues
⚠️ 2 orphaned issues need PRs
✅ 2 ready to close
Actions available:
1. Auto-close merged issues (generates commands)
2. Create Linear issues for orphaned PRs
3. View full report
Full report: thoughts/shared/reports/pr-sync/2025-01-27-pr-sync.md
```
## Success Criteria
### Automated Verification:
- [ ] GitHub PR data fetched successfully
- [ ] Linear issue data fetched successfully
- [ ] PR-ticket correlation logic executes
- [ ] Report generated with all sections
- [ ] Auto-close commands are valid
### Manual Verification:
- [ ] PR-issue matches are accurate
- [ ] Orphaned detection has minimal false positives
- [ ] Branch name extraction works correctly
- [ ] Recommendations are actionable
- [ ] Report provides clear next steps

81
plugin.lock.json Normal file
View File

@@ -0,0 +1,81 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:coalesce-labs/catalyst:plugins/pm",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "2395179edb508f8c812a96aab0cc6eafdc5f30b8",
"treeHash": "f196a9b6bd22f253e15364213e2fd3c2cfd103fc747119467ded3b097b3ad681",
"generatedAt": "2025-11-28T10:15:41.434365Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "catalyst-pm",
"description": "Linear-focused project management plugin with cycle management, milestone tracking, backlog grooming, and team analytics",
"version": "3.0.1"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "0efe858588cb3fee9d00a89649fd22be3e7b480cc3c9bbd5adc4a62c105f6b8c"
},
{
"path": "agents/github-linear-analyzer.md",
"sha256": "01cb3c08026cfd8ad05c0e35df964bc338fa54fc348afa67749d3a727a8a07a6"
},
{
"path": "agents/milestone-analyzer.md",
"sha256": "ca16545f3fd22830d4b42144dfb35af51dd243190a74307e32ef7cc9d76e3835"
},
{
"path": "agents/backlog-analyzer.md",
"sha256": "d2c583977140a912c5ed73c1c7450732abfea6b2c95df012fc817eaddf666431"
},
{
"path": "agents/cycle-analyzer.md",
"sha256": "e759624ff2dfec66f937bb1d5f5d3b7709364eaa9714c74f06833ac370aa64ec"
},
{
"path": "agents/linear-research.md",
"sha256": "66217d5c4fc48e2fe63cf00fce47b86cdbe4c501bd532dd9881cb04050de7eed"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "eec3b6d694ee5432e5b6ae7b608317e949368f247e0734c086773d8dc0391b1f"
},
{
"path": "commands/groom_backlog.md",
"sha256": "fec4447f7a18649bfcc14243bb871e3e4ae61a5ba20f4a538ca7f81f61e937e9"
},
{
"path": "commands/sync_prs.md",
"sha256": "abbba3eed1de712eaa8a4ccffa5262f6b7f649eadefc55d54ac9a26619bb346a"
},
{
"path": "commands/analyze_cycle.md",
"sha256": "11d4daeb5e42c7cd1256a1d64619d4f84009af7bef5ce512dfbab5578b259bfa"
},
{
"path": "commands/analyze_milestone.md",
"sha256": "19b3a38b6ce75131942db2ead87a452b9b4ca33f483b508af32763f4e2115363"
},
{
"path": "commands/report_daily.md",
"sha256": "a90eae737a272ff802ca7409ea23f3ab9441b9422de3e6ed3fa73e157db9fae7"
}
],
"dirSha256": "f196a9b6bd22f253e15364213e2fd3c2cfd103fc747119467ded3b097b3ad681"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}