From 7444e5bfb59d9bb81e68c9e3ba9e580091fc9f3c Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:26:18 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 17 + README.md | 3 + agents/project-governance.md | 553 ++++++++++++++++ commands/project-init.md | 340 ++++++++++ commands/project-report.md | 920 +++++++++++++++++++++++++++ commands/project-status.md | 483 ++++++++++++++ plugin.lock.json | 77 +++ skills/initialize-project/SKILL.md | 986 +++++++++++++++++++++++++++++ skills/manage-sprint/SKILL.md | 919 +++++++++++++++++++++++++++ skills/project-search/SKILL.md | 655 +++++++++++++++++++ skills/track-meeting/SKILL.md | 900 ++++++++++++++++++++++++++ skills/track-milestone/SKILL.md | 640 +++++++++++++++++++ 12 files changed, 6493 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/project-governance.md create mode 100644 commands/project-init.md create mode 100644 commands/project-report.md create mode 100644 commands/project-status.md create mode 100644 plugin.lock.json create mode 100644 skills/initialize-project/SKILL.md create mode 100644 skills/manage-sprint/SKILL.md create mode 100644 skills/project-search/SKILL.md create mode 100644 skills/track-meeting/SKILL.md create mode 100644 skills/track-milestone/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9f6dd74 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "projectmaster", + "description": "Comprehensive software project management system with support for Agile, Scrum, Kanban, and Waterfall methodologies. Manages meetings, sprints, milestones, and project documentation with full AkashicRecords governance integration.", + "version": "1.0.0", + "author": { + "name": "Frank Wang" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..e75d5bb --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# projectmaster + +Comprehensive software project management system with support for Agile, Scrum, Kanban, and Waterfall methodologies. Manages meetings, sprints, milestones, and project documentation with full AkashicRecords governance integration. diff --git a/agents/project-governance.md b/agents/project-governance.md new file mode 100644 index 0000000..6e0b9e7 --- /dev/null +++ b/agents/project-governance.md @@ -0,0 +1,553 @@ +--- +description: Specialized agent for validating and maintaining ProjectMaster governance including RULE.md compliance, README.md indexes, directory structure, and milestones.yaml integrity +--- + +# Project Governance Agent + +You are a specialized agent responsible for ensuring ProjectMaster project governance is healthy, compliant, and up-to-date. + +## Your Role + +You maintain the integrity of ProjectMaster-managed projects by: +1. Validating RULE.md configuration +2. Ensuring README.md indexes are current +3. Verifying directory structure matches RULE.md specifications +4. Validating milestones.yaml structure and dependencies +5. Checking cross-references and links +6. Identifying and fixing governance issues + +## Governance Protocol + +Every ProjectMaster Skill follows this protocol. You ensure it's being followed: + +``` +1. Pre-check: + - Locate RULE.md (current or nearest parent) + - Read RULE.md constraints and workflows + - Read README.md for current state + - Validate operation is allowed + +2. Execute: + - Perform requested operation + - Follow RULE.md specifications exactly + - Log operation internally + +3. Post-update: + - Update README.md with new/modified files + - Update timestamps + - Verify README.md is valid markdown + - Update related indexes + +4. Report: + - Confirm operation completed + - Show README.md updates made + - Note any governance warnings +``` + +## Validation Tasks + +### Task 1: RULE.md Validation + +When validating RULE.md, check: + +#### Required Fields + +All ProjectMaster RULE.md files must have: + +```markdown +# Project: {Name} + +## Purpose +[Project description] + +## Methodology +methodology: [scrum|kanban|waterfall|agile|hybrid] +[Methodology-specific configuration] + +## Team Structure +team_size: [number] +[Team details] + +## Directory Structure +[Defined structure matching actual directories] + +## Document Templates +[Templates for each document type used] + +## File Naming Convention +format: [convention] + +## Auto Workflows +[Workflow specifications] + +## Allowed Operations +[Operation permissions] +``` + +#### Validation Steps: + +1. **Read RULE.md**: + ```bash + Read RULE.md + ``` + +2. **Check each required section**: + - Purpose: Present and non-empty + - Methodology: Valid value (scrum, kanban, waterfall, agile, hybrid) + - Team Structure: Has team_size or roles defined + - Directory Structure: Lists expected directories + - Document Templates: At least one template defined + - Auto Workflows: At least one workflow defined + - Allowed Operations: Present + +3. **Check methodology-specific fields**: + - If Scrum: sprint_length, ceremonies + - If Kanban: workflow_stages, wip_limits (optional) + - If Waterfall: phases + +4. **Validate document templates**: + - Templates use valid YAML frontmatter + - Required fields defined for each type + - Example content provided + +5. **Check auto workflows**: + - Workflow steps are clear and actionable + - References to tools are valid (Read, Write, Edit, Bash, etc.) + - Conditions are specific + +6. **Report findings**: + ``` + ✅ RULE.md Validation + + Required Sections: + - Purpose: ✅ Present + - Methodology: ✅ scrum (valid) + - Team Structure: ✅ 6 members defined + - Directory Structure: ✅ Present + - Document Templates: ✅ 4 templates defined + - Auto Workflows: ✅ 5 workflows defined + - Allowed Operations: ✅ Present + + Methodology Configuration (Scrum): + - sprint_length: ✅ 2_weeks + - ceremonies: ✅ planning, review, retrospective + + Issues: {count} + ``` + +### Task 2: README.md Index Validation + +When validating README.md files, check: + +#### Project Root README.md + +**Required sections**: +- Project name and description +- Project Information (status, methodology, team, dates) +- Quick Links +- Team +- Current Status +- Recent Activity +- Contents (will be updated) +- Last updated timestamp + +**Validation**: +1. Read README.md +2. Check all required sections present +3. Verify "Last updated" is recent (within last 30 days if project active) +4. Check "Recent Activity" has entries (if project active) +5. Verify all links in "Quick Links" point to existing files + +**Common Issues**: +- Outdated timestamp (update needed) +- Broken links in Quick Links +- Empty "Recent Activity" despite recent changes +- "Contents" section not reflecting actual directories + +#### Subdirectory README.md Files + +Each major directory should have README.md: +- meetings/README.md +- sprints/README.md (or iterations/, board/) +- docs/README.md +- decisions/README.md + +**Required sections** (for each): +- Directory name and purpose +- Contents/Recent Items +- Last updated timestamp + +**Validation**: +1. **Check existence**: + ```bash + ls meetings/README.md sprints/README.md docs/README.md decisions/README.md + ``` + +2. **For each existing README.md**: + - Read file + - Check structure + - Verify "Last updated" timestamp + - Check if Contents matches actual files in directory + +3. **For each missing README.md**: + - Note as issue + - Offer to create + +4. **Validate index accuracy**: + ```bash + # List actual files + ls -1 meetings/sprint-planning/ + # Compare with README.md index + ``` + +5. **Report findings**: + ``` + 📚 README.md Index Validation + + Root README.md: ✅ Present, updated 2025-11-13 + meetings/README.md: ⚠️ Outdated (2025-11-01, 8 new meetings) + sprints/README.md: ✅ Present, updated 2025-11-13 + docs/README.md: ❌ Missing + decisions/README.md: ✅ Present, updated 2025-11-10 + + Issues: 2 (1 outdated, 1 missing) + ``` + +### Task 3: Directory Structure Validation + +When validating directory structure: + +1. **Read RULE.md Directory Structure section**: + Extract expected directories + +2. **Check if directories exist**: + ```bash + ls -ld {directory1} {directory2} {directory3} + ``` + +3. **Compare expected vs actual**: + - Missing directories: Issue + - Extra directories: Note (may be valid additions) + - Misnamed directories: Issue + +4. **Check directory contents match purpose**: + - meetings/ should contain meeting notes + - sprints/ should contain sprint plans + - docs/ should contain documentation + - decisions/ should contain decision records + +5. **Report findings**: + ``` + 📁 Directory Structure Validation + + Expected Directories (from RULE.md): + - meetings/ ✅ Present + - sprints/ ✅ Present + - docs/ ✅ Present + - decisions/ ⚠️ Missing + + Additional Directories Found: + - archive/ (not in RULE.md, may be valid) + + Issues: 1 (decisions/ directory missing) + ``` + +### Task 4: milestones.yaml Validation + +When validating milestones.yaml: + +#### Structure Validation + +**Required structure**: +```yaml +project: + name: "..." + start_date: YYYY-MM-DD + target_completion: YYYY-MM-DD or "TBD" + status: [planning|active|completed] + +milestones: + - id: ... + name: "..." + description: "..." + target_date: YYYY-MM-DD + actual_date: YYYY-MM-DD or null + status: [planned|in_progress|completed|delayed] + dependencies: [...] + deliverables: [...] + owner: "@..." +``` + +**Validation steps**: + +1. **Read milestones.yaml**: + ```bash + Read milestones.yaml + ``` + +2. **Check YAML validity**: + - Valid YAML syntax + - Proper indentation + - Quoted strings where needed + +3. **Validate project section**: + - name: Present and non-empty + - start_date: Valid date format (YYYY-MM-DD) + - status: Valid value + +4. **Validate each milestone**: + - id: Unique, no duplicates + - name: Present and non-empty + - target_date: Valid date format + - actual_date: Valid date format or null + - status: Valid value (planned, in_progress, completed, delayed) + - dependencies: All referenced IDs exist + - owner: Valid format (@name) if present + +5. **Check for circular dependencies**: + ``` + milestone-1 depends on milestone-2 + milestone-2 depends on milestone-3 + milestone-3 depends on milestone-1 ← CIRCULAR! + ``` + +6. **Check date logic**: + - If milestone completed: actual_date should be set + - If milestone in_progress: target_date should be in future or near term + - If milestone depends on another: dependent milestone target_date should be after dependency + +7. **Report findings**: + ``` + 🎯 milestones.yaml Validation + + Structure: ✅ Valid YAML + Project Section: ✅ All required fields present + + Milestones: 7 defined + + Milestone Validation: + - milestone-1: ✅ Valid + - milestone-2: ✅ Valid + - milestone-3: ⚠️ Depends on non-existent "milestone-x" + - milestone-4: ✅ Valid + - milestone-5: ⚠️ target_date before dependency target_date + - milestone-6: ✅ Valid + - milestone-7: ⚠️ Status "completed" but actual_date is null + + Dependencies: No circular dependencies found ✅ + + Issues: 3 (1 missing dependency, 1 date conflict, 1 missing actual_date) + ``` + +### Task 5: Cross-Reference Validation + +When validating cross-references: + +1. **Scan documents for links**: + - Internal markdown links: `[text](path/to/file.md)` + - Cross-references: "See Sprint 5", "Related to Beta Release" + - @mentions: "@alice", "@bob" + +2. **Verify link targets exist**: + ```bash + # For each link, check file exists + ls {linked_file_path} + ``` + +3. **Verify referenced items exist**: + - Sprint references → Check sprints/ directory + - Milestone references → Check milestones.yaml + - Meeting references → Check meetings/ directory + +4. **Verify @mentions are team members**: + - Check against team list in RULE.md + - Note unknown @mentions + +5. **Report broken links**: + ``` + 🔗 Cross-Reference Validation + + Scanned: 45 documents + + Links Found: 127 + - Valid: 118 + - Broken: 9 + + Broken Links: + - meetings/sprint-planning/2025-11-01_sprint-4-planning.md + → Line 23: [Sprint 3](../../sprints/sprint-03/sprint-plan.md) + ✗ File does not exist + + Unknown @mentions: 2 + - @john (mentioned in 3 documents, not in RULE.md team list) + - @susan (mentioned in 1 document, not in RULE.md team list) + + Issues: 11 (9 broken links, 2 unknown mentions) + ``` + +## Fixing Issues + +When issues are found, offer to fix them automatically: + +### Auto-Fix Capabilities + +#### Fix 1: Create Missing README.md + +If directory missing README.md: + +1. Identify directory type (meetings, sprints, docs, etc.) +2. Generate appropriate template +3. Scan directory contents +4. Create initial index +5. Write README.md + +#### Fix 2: Update Outdated README.md + +If README.md outdated: + +1. Read current README.md +2. Scan directory for new files since last update +3. Add new files to Contents section +4. Update "Recent Activity" or equivalent +5. Update "Last updated" timestamp +6. Write updated README.md + +#### Fix 3: Create Missing Directory + +If RULE.md specifies directory that doesn't exist: + +1. Create directory: + ```bash + mkdir -p {directory_name} + ``` +2. Create README.md for directory +3. Update project README.md to reference new directory + +#### Fix 4: Fix milestones.yaml Issues + +If milestone has issues: + +1. **Missing actual_date for completed milestone**: + - Use last modification date of milestone entry or + - Ask user for completion date + +2. **Broken dependency reference**: + - Ask user which milestone it should reference + - Or remove broken dependency + +3. **Date conflicts**: + - Report to user + - Cannot auto-fix (requires decision) + +#### Fix 5: Update Broken Links + +If links are broken: + +1. **Try to find moved file**: + ```bash + find . -name "{filename}" + ``` + +2. **If found, update link** + +3. **If not found**: + - Note in report + - Require user action + +## Validation Report Format + +When performing full validation, present comprehensive report: + +``` +🏥 ProjectMaster Governance Validation Report + +Project: {Project Name} +Location: {path} +Validated: {YYYY-MM-DD HH:MM} + +═══════════════════════════════════════════════════════ + +📋 RULE.md +Status: {✅ Valid | ⚠️ Issues | ❌ Invalid | ❓ Missing} +Issues: {count} +[If issues, list them] + +═══════════════════════════════════════════════════════ + +📚 README.md Indexes +Root: {✅ Up to date | ⚠️ Outdated | ❌ Missing} +Subdirectories: {X}/{Y} up to date +Issues: {count} +[If issues, list them] + +═══════════════════════════════════════════════════════ + +📁 Directory Structure +Expected: {count} directories +Found: {count} directories +Match: {✅ Complete | ⚠️ Partial | ❌ Mismatch} +Issues: {count} +[If issues, list them] + +═══════════════════════════════════════════════════════ + +🎯 milestones.yaml +Status: {✅ Valid | ⚠️ Issues | ❌ Invalid | ❓ Missing} +Milestones: {count} +Issues: {count} +[If issues, list them] + +═══════════════════════════════════════════════════════ + +🔗 Cross-References +Links checked: {count} +Broken links: {count} +Unknown @mentions: {count} +Issues: {count} + +═══════════════════════════════════════════════════════ + +📊 GOVERNANCE HEALTH: {Excellent | Good | Fair | Poor} + +Overall: {X}/{Y} checks passed + +{If issues exist:} +Would you like me to fix issues automatically? +1. Fix all automatically +2. Let me fix manually +3. Show detailed fix plan first + +{If no issues:} +✅ All governance checks passed. Project is well-maintained! + +═══════════════════════════════════════════════════════ +``` + +## When to Activate This Agent + +This agent is activated: +1. By `/project-init` command (validation option) +2. Manually when user requests governance validation +3. Automatically by other Skills when post-update governance check needed +4. On a schedule (if user sets up periodic validation) + +## Interaction with Skills + +All ProjectMaster Skills should: +1. **Pre-check**: Read RULE.md before operations +2. **Post-update**: Update README.md after changes +3. **Report**: Notify this agent if governance update made + +This agent verifies Skills are following protocol correctly. + +## Notes + +- Governance validation is non-destructive - it only reads unless user approves fixes +- Auto-fix is conservative - only fixes unambiguous issues +- Complex issues (broken dependencies, date conflicts) require user decisions +- Regular validation (weekly or per-sprint) keeps projects healthy +- This agent complements AkashicRecords governance agent (can work together) + +--- + +Healthy governance enables all other ProjectMaster functionality. This agent is the guardian of project integrity. diff --git a/commands/project-init.md b/commands/project-init.md new file mode 100644 index 0000000..768ad5c --- /dev/null +++ b/commands/project-init.md @@ -0,0 +1,340 @@ +--- +description: Initialize or validate ProjectMaster configuration for the current directory and its subdirectories +--- + +# Initialize ProjectMaster Configuration + +When the user runs `/project-init`, perform the following tasks: + +## Task 1: Scan Current Directory + +Scan the current directory and subdirectories to understand the existing structure: + +1. **Check for RULE.md files**: + ```bash + find . -name "RULE.md" -type f + ``` + List all RULE.md files found. + +2. **Check for milestones.yaml**: + ```bash + find . -name "milestones.yaml" -type f + ``` + +3. **Check for project directories**: + Look for typical project directories: + - meetings/ + - sprints/ or iterations/ or board/ + - docs/ + - decisions/ + +4. **Identify project structure type**: + - Initialized ProjectMaster project (has RULE.md with ProjectMaster metadata) + - AkashicRecords project (has RULE.md but no ProjectMaster config) + - Uninitialized directory (no RULE.md) + - Multiple projects (multiple RULE.md files in different subdirectories) + +## Task 2: Report Current State + +Present findings to the user: + +``` +📋 ProjectMaster Configuration Scan + +Current directory: {path} + +🔍 Found: +- RULE.md files: {count} ({locations}) +- milestones.yaml: {count} ({locations}) +- Project directories: {list} + +📊 Assessment: +{One of:} +- ✅ ProjectMaster project detected at {path} +- ⚠️ AkashicRecords project detected (no ProjectMaster config) +- ℹ️ No project governance detected +- 📁 Multiple projects detected: {count} +``` + +## Task 3: Offer Actions + +Based on assessment, offer appropriate actions: + +### If ProjectMaster project detected: + +``` +✅ ProjectMaster is initialized for this project. + +**Configuration**: +- Methodology: {from RULE.md} +- Team size: {from RULE.md} +- Documentation format: {from RULE.md} + +**Health check**: +- RULE.md: ✅ Present +- milestones.yaml: ✅ Present +- README.md: {✅ Present | ⚠️ Missing} +- Directory structure: {✅ Complete | ⚠️ Missing directories} + +Would you like to: +1. Validate governance (check README.md indexes) +2. Update RULE.md configuration +3. View project status (/project-status) +4. No action needed +``` + +### If AkashicRecords project (no ProjectMaster config): + +``` +ℹ️ This directory has AkashicRecords governance but no ProjectMaster configuration. + +Would you like to add ProjectMaster to this project? + +This will: +- Add ProjectMaster-specific configuration to RULE.md +- Create milestones.yaml +- Create project management directories (meetings/, sprints/) +- Maintain AkashicRecords compatibility + +Proceed with ProjectMaster initialization? +- Yes, initialize ProjectMaster +- No, keep as is +``` + +If yes, activate the `initialize-project` Skill to add ProjectMaster to the existing structure. + +### If no governance detected: + +``` +ℹ️ This directory is not initialized for ProjectMaster. + +Would you like to initialize project management for this directory? + +This will create: +- RULE.md with project governance +- Project directory structure (meetings/, sprints/, docs/) +- milestones.yaml for milestone tracking +- README.md files for navigation + +Proceed with initialization? +- Yes, initialize new project +- No, cancel +``` + +If yes, activate the `initialize-project` Skill with guided Q&A. + +### If multiple projects detected: + +``` +📁 Multiple projects detected: + +1. {path1} - {Project Name or "Unnamed"} +2. {path2} - {Project Name or "Unnamed"} +3. {path3} - {Project Name or "Unnamed"} + +Which project would you like to work with? +- Select project: {1-3} +- Initialize new project in current directory +- Validate all projects +- Cancel +``` + +Handle user selection and proceed accordingly. + +## Task 4: Validate Governance (if requested) + +If user chooses to validate governance: + +1. **Read RULE.md**: + Check that all required fields are present: + - methodology + - team_size or team_structure + - Document Templates section + - Auto Workflows section + - Directory Structure section + +2. **Check directory structure**: + Verify that directories specified in RULE.md exist: + ```bash + ls -ld meetings/ sprints/ docs/ decisions/ + ``` + +3. **Check README.md files**: + Verify that README.md files exist and are up to date: + - Project root README.md + - meetings/README.md + - sprints/README.md (or appropriate work tracking directory) + - docs/README.md + +4. **Check milestones.yaml**: + Verify structure and required fields: + ```yaml + project: + name: ... + start_date: ... + milestones: + - id: ... + name: ... + [etc.] + ``` + +5. **Report validation results**: + ``` + ✅ Governance Validation Report + + **RULE.md**: ✅ All required fields present + **Directory Structure**: ✅ All directories exist + **README.md Indexes**: {status} + - Root: ✅ Present, last updated {date} + - meetings/: ✅ Present, last updated {date} + - sprints/: ⚠️ Outdated (last updated {date}, {count} new items) + - docs/: ❌ Missing + **milestones.yaml**: ✅ Valid structure + + Issues found: {count} + ``` + +6. **Offer fixes**: + ``` + Would you like to fix issues automatically? + - Yes, fix all issues + - Let me fix manually + ``` + + If yes: + - Create missing README.md files + - Update outdated README.md indexes + - Fix structural issues + +## Task 5: Execute Chosen Action + +Carry out the user's selected action: +- If initialize: Use `initialize-project` Skill +- If validate and fix: Perform governance updates +- If update RULE.md: Open RULE.md for editing and guide user +- If view status: Run `/project-status` command + +## Notes + +- This command provides a quick way to check and initialize ProjectMaster +- It integrates with existing AkashicRecords projects +- It validates governance health and offers to fix issues +- It's safe to run repeatedly - it only makes changes with user confirmation + +## Examples + +### Example 1: Uninitialized directory + +``` +User: /project-init + +Claude: 📋 ProjectMaster Configuration Scan + +Current directory: /Users/user/my-project + +🔍 Found: +- RULE.md files: 0 +- milestones.yaml: 0 +- Project directories: None + +📊 Assessment: +ℹ️ No project governance detected + +Would you like to initialize project management for this directory? + +This will create: +- RULE.md with project governance +- Project directory structure +- milestones.yaml +- README.md files + +Proceed? [Yes/No] + +User: Yes + +Claude: Great! Let's set up your project... +[Activates initialize-project Skill with Q&A] +``` + +### Example 2: Existing ProjectMaster project + +``` +User: /project-init + +Claude: 📋 ProjectMaster Configuration Scan + +Current directory: /Users/user/ecommerce-redesign + +🔍 Found: +- RULE.md files: 1 (./RULE.md) +- milestones.yaml: 1 (./milestones.yaml) +- Project directories: meetings/, sprints/, docs/, decisions/ + +📊 Assessment: +✅ ProjectMaster project detected + +**Configuration**: +- Methodology: Scrum (2-week sprints) +- Team size: 6 +- Documentation format: Structured with frontmatter + +**Health check**: +- RULE.md: ✅ Present +- milestones.yaml: ✅ Present +- README.md: ✅ Present, updated 2025-11-13 +- Directory structure: ✅ Complete + +Would you like to: +1. Validate governance +2. Update RULE.md configuration +3. View project status +4. No action needed + +User: 1 + +Claude: Running governance validation... + +✅ Governance Validation Report +All systems healthy! No issues found. +``` + +### Example 3: Governance validation finds issues + +``` +User: /project-init + +Claude: [Scans and detects issues] + +⚠️ Governance Validation Report + +**Issues found**: 3 + +1. ⚠️ meetings/README.md is outdated + - Last updated: 2025-11-01 + - 8 new meetings since then + +2. ❌ docs/README.md is missing + - 5 documentation files exist + - No index found + +3. ⚠️ milestones.yaml has invalid entry + - milestone-3 references non-existent dependency + +Would you like to fix these automatically? + +User: Yes + +Claude: Fixing issues... + +✅ Updated meetings/README.md with 8 new entries +✅ Created docs/README.md with index of 5 files +⚠️ milestones.yaml issue requires manual review: + milestone-3 depends on "milestone-x" which doesn't exist. + Please check milestones.yaml and correct the dependency. + +2 of 3 issues resolved. 1 requires manual attention. +``` + +--- + +This command is the entry point for ProjectMaster setup and maintenance. It ensures projects stay healthy and well-governed. diff --git a/commands/project-report.md b/commands/project-report.md new file mode 100644 index 0000000..25940f9 --- /dev/null +++ b/commands/project-report.md @@ -0,0 +1,920 @@ +--- +description: Generate comprehensive project reports in various formats (summary, sprint, milestone, velocity, full) +--- + +# Generate Project Report + +When the user runs `/project-report [project-name] [report-type]`, generate a comprehensive report document. + +## Command Syntax + +``` +/project-report # Interactive: asks for project and type +/project-report [project-name] # Interactive: asks for type +/project-report [project-name] [type] # Direct: generates specified report +``` + +**Report Types**: +- `summary` - High-level project overview (default) +- `sprint` - Current/recent sprint detailed analysis +- `milestone` - Milestone progress and roadmap +- `velocity` - Team velocity and estimation analysis +- `full` - Complete project report (all sections) + +## Task 1: Identify Project and Report Type + +### If no parameters provided: + +1. **Discover projects in workspace**: + ```bash + find . -name "RULE.md" -type f + ``` + +2. **Present project selection**: + ``` + 📊 Generate Project Report + + Select project: + 1. {Project 1 Name} ({path}) + 2. {Project 2 Name} ({path}) + 3. {Project 3 Name} ({path}) + + Which project? (1-3) + ``` + +3. **Present report type selection**: + ``` + Select report type: + 1. Summary - High-level overview (recommended for stakeholders) + 2. Sprint - Current sprint detailed analysis + 3. Milestone - Milestone progress and timeline + 4. Velocity - Team performance metrics + 5. Full - Comprehensive report (all sections) + + Which type? (1-5) + ``` + +### If parameters provided: + +Parse and validate: +- Project name matches existing project +- Report type is valid (summary|sprint|milestone|velocity|full) + +## Task 2: Gather Report Data + +Based on report type, collect relevant information: + +### For All Report Types: + +- Project name and basic info (from RULE.md) +- Current date and report generation metadata +- Project start date and duration + +### For Summary Report: + +- Methodology and team size +- Current sprint/phase status +- Milestone completion overview +- Key achievements (last 30 days) +- Upcoming milestones and deadlines +- High-level risks or blockers + +### For Sprint Report: + +- Current or most recent sprint details +- Sprint goal and dates +- Story breakdown with status +- Burndown/velocity data +- Team assignments +- Blockers and resolutions +- Sprint ceremony notes (planning, review, retro) +- Comparison with previous sprints + +### For Milestone Report: + +- All milestones with status +- Timeline and roadmap +- Dependencies between milestones +- Progress against targets +- Contributing sprints for each milestone +- Risk analysis for upcoming milestones + +### For Velocity Report: + +- Historical sprint velocities (last 6-10 sprints) +- Average velocity calculation +- Velocity trends (improving/declining/stable) +- Estimation accuracy analysis +- Team capacity over time +- Factors affecting velocity +- Recommendations for future sprint planning + +### For Full Report: + +All of the above sections combined. + +## Task 3: Generate Report Document + +Create a comprehensive markdown document with proper formatting: + +### Summary Report Format: + +```markdown +# Project Report: {Project Name} + +**Report Type**: Summary +**Generated**: {YYYY-MM-DD HH:MM} +**Report Period**: {project_start} to {current_date} +**Project Duration**: {X} months + +--- + +## Executive Summary + +{2-3 paragraph overview of project status, key achievements, and next steps} + +--- + +## Project Information + +| Field | Value | +|-------|-------| +| **Project Name** | {name} | +| **Methodology** | {Scrum/Kanban/etc.} | +| **Team Size** | {size} members | +| **Project Start** | {date} | +| **Current Phase** | {Sprint X / Phase Y} | +| **Status** | {On Track / At Risk / Behind} | + +--- + +## Current Status + +### Active Sprint/Phase + +**{Sprint Number}: {Goal}** +- Duration: {start_date} to {end_date} +- Progress: {X}/{Y} stories completed ({percentage}%) +- Status: {On Track | At Risk | Behind} +- Days Remaining: {days} + +### Recent Completions + +- ✅ {Item 1} +- ✅ {Item 2} +- ✅ {Item 3} + +### In Progress + +- 🔄 {Item 1} - @{owner} +- 🔄 {Item 2} - @{owner} + +### Blockers + +{If any blockers exist:} +- ⚠️ {Blocker description} - {impact} + +{If no blockers:} +- None. All work proceeding smoothly. + +--- + +## Milestone Progress + +**Overall**: {X}/{Y} milestones completed ({percentage}%) + +### Completed Milestones +- ✅ {Milestone 1} - {completion_date} +- ✅ {Milestone 2} - {completion_date} + +### In Progress +- 🔄 {Milestone name} - {target_date} ({progress}%) + - Status: {On Time | At Risk | Delayed} + +### Upcoming (Next 90 Days) +- 📅 {Milestone name} - {target_date} +- 📅 {Milestone name} - {target_date} + +--- + +## Key Achievements (Last 30 Days) + +{Extract from Recent Activity in README.md} + +- {Date}: {Achievement} +- {Date}: {Achievement} +- {Date}: {Achievement} + +--- + +## Upcoming Priorities + +### This Month +1. {Priority item 1} +2. {Priority item 2} +3. {Priority item 3} + +### Next Month +1. {Priority item 1} +2. {Priority item 2} + +--- + +## Risks and Concerns + +{If risks exist:} + +### High Priority +- ⚠️ {Risk description} + - Impact: {impact} + - Mitigation: {mitigation plan} + +### Medium Priority +- {Risk description} + +{If no major risks:} + +No significant risks identified. Project is progressing according to plan. + +--- + +## Team Performance + +- **Sprint Velocity**: {average} points/sprint +- **Completion Rate**: {percentage}% of planned work delivered +- **Team Morale**: {from retrospective notes if available} + +--- + +## Recommendations + +{Based on analysis, provide 3-5 actionable recommendations} + +1. {Recommendation 1} +2. {Recommendation 2} +3. {Recommendation 3} + +--- + +## Next Steps + +1. {Next step 1} +2. {Next step 2} +3. {Next step 3} + +--- + +**Report Generated by**: ProjectMaster +**Last Updated**: {YYYY-MM-DD HH:MM} +``` + +### Sprint Report Format: + +```markdown +# Sprint Report: Sprint {Number} + +**Project**: {Project Name} +**Sprint Goal**: {Goal} +**Generated**: {YYYY-MM-DD HH:MM} + +--- + +## Sprint Overview + +| Field | Value | +|-------|-------| +| **Sprint Number** | {number} | +| **Duration** | {start_date} to {end_date} | +| **Sprint Length** | {X} weeks | +| **Days Elapsed** | {Y} of {Z} days | +| **Status** | {Planning / Active / Review / Completed} | + +--- + +## Sprint Goal + +{Detailed description of sprint goal} + +--- + +## Story Breakdown + +### Summary + +| Status | Count | Story Points | +|--------|-------|--------------| +| ✅ Completed | {X} | {A} pts | +| 🔄 In Progress | {Y} | {B} pts | +| ⏸️ Not Started | {Z} | {C} pts | +| ⚠️ Blocked | {W} | {D} pts | +| **Total** | **{total}** | **{total_pts} pts** | + +### Completed Stories + +{For each completed story:} + +#### ✅ {Story Title} +- **Story Points**: {X} +- **Assignee**: @{name} +- **Completed**: {date} +- **Description**: {brief description} +- **Acceptance Criteria**: All met + +--- + +### In Progress Stories + +{For each in-progress story:} + +#### 🔄 {Story Title} +- **Story Points**: {X} +- **Assignee**: @{name} +- **Progress**: {percentage}% +- **Status**: On track / Needs attention +- **Next Steps**: {what's next} + +--- + +### Blocked Stories + +{If any blockers:} + +#### ⚠️ {Story Title} +- **Story Points**: {X} +- **Assignee**: @{name} +- **Blocker**: {blocker description} +- **Impact**: {impact on sprint} +- **Resolution Plan**: {plan} +- **Owner**: @{resolution_owner} + +--- + +## Velocity Analysis + +- **Planned Velocity**: {planned} points +- **Actual Velocity**: {actual} points (if sprint completed) +- **Completion Rate**: {percentage}% +- **Comparison to Average**: {above/below/on par} with team average of {avg} points + +{If sprint active:} +- **Projected Velocity**: {projected} points based on current progress +- **On Track For**: {percentage}% completion + +--- + +## Team Assignments + +{For each team member:} + +### @{member_name} +- **Assigned**: {count} stories ({points} points) +- **Completed**: {count} stories ({points} points) +- **In Progress**: {count} stories +- **Utilization**: {percentage}% + +--- + +## Daily Progress + +{Summary of daily updates if tracked} + +### Week 1 +- **Mon**: {summary} +- **Tue**: {summary} +- **Wed**: {summary} +- **Thu**: {summary} +- **Fri**: {summary} + +### Week 2 +- **Mon**: {summary} +- ... + +--- + +## Sprint Ceremonies + +### Sprint Planning +- **Date**: {date} +- **Duration**: {X} minutes +- **Attendees**: {list} +- **Key Decisions**: {summary} +- **Meeting Notes**: [Link](path/to/meeting.md) + +{If sprint completed:} + +### Sprint Review +- **Date**: {date} +- **Demos**: {count} stories demonstrated +- **Stakeholder Feedback**: {summary} +- **Meeting Notes**: [Link](path/to/meeting.md) + +### Sprint Retrospective +- **Date**: {date} +- **What Went Well**: {summary} +- **What Could Improve**: {summary} +- **Action Items**: {list} +- **Meeting Notes**: [Link](path/to/meeting.md) + +--- + +## Blockers and Resolutions + +{Detailed list of blockers encountered and how they were resolved} + +| Blocker | Reported | Resolved | Duration | Impact | +|---------|----------|----------|----------|--------| +| {description} | {date} | {date / "Open"} | {days} | {High/Med/Low} | + +--- + +## Sprint Health Assessment + +**Overall Health**: {Excellent / Good / Fair / Poor} + +**Indicators**: +- Velocity: {On Track / Below / Above} +- Blockers: {None / Minor / Significant} +- Team Capacity: {Appropriate / Overloaded / Underutilized} +- Goal Achievement: {Likely / Uncertain / Unlikely} + +--- + +## Recommendations + +{3-5 specific recommendations for this sprint or next} + +1. {Recommendation} +2. {Recommendation} +3. {Recommendation} + +--- + +## Related Links + +- [Sprint Plan Document](path/to/sprint-plan.md) +- [Sprint Planning Meeting](path/to/meeting.md) +- [Related Milestone](path/to/milestones.yaml) +- [Project README](../README.md) + +--- + +**Report Generated by**: ProjectMaster +**Last Updated**: {YYYY-MM-DD HH:MM} +``` + +### Milestone Report Format: + +```markdown +# Milestone Report: {Project Name} + +**Generated**: {YYYY-MM-DD HH:MM} +**Report Period**: {project_start} to {current_date} + +--- + +## Milestone Summary + +| Metric | Value | +|--------|-------| +| **Total Milestones** | {total} | +| **Completed** | {completed} ({percentage}%) | +| **In Progress** | {in_progress} | +| **Planned** | {planned} | +| **Delayed** | {delayed} | + +--- + +## Timeline Overview + +{Text-based timeline visualization} + +``` +Q1 2025 +├── [✅] Alpha Release (2025-02-15) ← Completed on time +└── [✅] Internal Testing (2025-03-01) ← Completed 2 days early + +Q2 2025 +├── [🔄] Beta Release (2025-03-31) ← In Progress (75%) +└── [📅] Feature Freeze (2025-04-15) ← Planned (blocked by Beta) + +Q3 2025 +├── [📅] Public Launch (2025-06-30) ← Planned +└── [📅] 1.0 Release (2025-07-31) ← Planned +``` + +--- + +## Milestone Details + +{For each milestone:} + +### {Status Icon} {Milestone Name} + +**ID**: {milestone-id} +**Target Date**: {target_date} +**Actual Date**: {actual_date if completed} +**Status**: {planned / in_progress / completed / delayed} +**Owner**: @{name} + +**Description**: +{milestone description} + +**Deliverables**: +- [X] {Deliverable 1} (if completed) +- [🔄] {Deliverable 2} (if in progress) +- [ ] {Deliverable 3} (if pending) + +**Dependencies**: +{If dependencies exist:} +- Depends on: {dependency names} +- Blocks: {dependent milestone names} + +**Contributing Sprints**: +- Sprint {X}: {contribution} +- Sprint {Y}: {contribution} + +**Progress**: {percentage}% + +**Status**: {On Time / Early / Delayed by X days / At Risk} + +{If completed:} +**Completion Report**: [View Report](path/to/completion-report.md) + +--- + +{Repeat for each milestone} + +--- + +## Dependency Map + +{Visual representation of milestone dependencies} + +``` +Alpha Release + └── Internal Testing + └── Beta Release + ├── Feature Freeze + └── Public Launch + └── 1.0 Release +``` + +--- + +## Progress Against Roadmap + +**Original Plan vs. Actual**: + +| Milestone | Planned Date | Actual/Projected | Variance | Status | +|-----------|--------------|------------------|----------|--------| +| Alpha | 2025-02-15 | 2025-02-15 | On time | ✅ | +| Beta | 2025-03-31 | 2025-04-05 | +5 days | ⚠️ | +| Launch | 2025-06-30 | 2025-07-10 | +10 days | ⚠️ | + +--- + +## Risk Analysis + +### Milestones At Risk + +{For milestones at risk:} + +#### ⚠️ {Milestone Name} +- **Risk Level**: {High / Medium / Low} +- **Reason**: {why at risk} +- **Impact**: {what happens if delayed} +- **Mitigation**: {plan to get back on track} +- **Owner**: @{responsible person} + +--- + +## Recommendations + +{Based on milestone analysis:} + +1. {Recommendation for getting milestones on track} +2. {Recommendation for risk mitigation} +3. {Recommendation for process improvement} + +--- + +**Report Generated by**: ProjectMaster +**Last Updated**: {YYYY-MM-DD HH:MM} +``` + +### Velocity Report Format: + +```markdown +# Velocity Report: {Project Name} + +**Generated**: {YYYY-MM-DD HH:MM} +**Analysis Period**: {first_sprint_date} to {current_date} +**Sprints Analyzed**: {count} + +--- + +## Velocity Summary + +| Metric | Value | +|--------|-------| +| **Average Velocity** | {avg} story points/sprint | +| **Highest Velocity** | {max} points (Sprint {X}) | +| **Lowest Velocity** | {min} points (Sprint {Y}) | +| **Standard Deviation** | {stddev} points | +| **Trend** | {Improving / Stable / Declining} | + +--- + +## Sprint-by-Sprint Velocity + +| Sprint | Goal | Planned | Actual | Completion % | Status | +|--------|------|---------|--------|--------------|--------| +| Sprint 1 | {goal} | {planned} | {actual} | {pct}% | {icon} | +| Sprint 2 | {goal} | {planned} | {actual} | {pct}% | {icon} | +| Sprint 3 | {goal} | {planned} | {actual} | {pct}% | {icon} | +| ... | ... | ... | ... | ... | ... | + +**Total Story Points Delivered**: {total} points across {count} sprints + +--- + +## Velocity Trend Analysis + +{Text-based trend visualization} + +``` +Story Points +50 │ +45 │ ● +40 │ ● ● +35 │● +30 │ ● +25 │ ● + └───────────────────────── + S1 S2 S3 S4 S5 S6 +``` + +**Trend**: {Improving / Stable / Declining} + +**Analysis**: +{Interpret the trend:} +- Sprint 1-2: Ramping up, team finding rhythm +- Sprint 3-4: Peak performance, all team members fully onboarded +- Sprint 5-6: {Slight decline due to complexity / Maintained pace / etc.} + +--- + +## Estimation Accuracy + +**Overall Accuracy**: {percentage}% + +| Sprint | Estimated | Delivered | Accuracy | Notes | +|--------|-----------|-----------|----------|-------| +| Sprint 1 | {est} | {actual} | {pct}% | {notes} | +| Sprint 2 | {est} | {actual} | {pct}% | {notes} | +| ... | ... | ... | ... | ... | + +**Observations**: +- {Observation about overestimation/underestimation patterns} +- {Observation about improving accuracy over time} + +--- + +## Factors Affecting Velocity + +{Analyze factors that impacted velocity} + +### Positive Factors +- {Factor 1}: Increased velocity by ~{X}% (Sprint {Y}) +- {Factor 2}: Contributed to higher output + +### Negative Factors +- {Factor 1}: Reduced velocity by ~{X}% (Sprint {Y}) +- {Factor 2}: Caused delays + +### Lessons Learned +- {Lesson 1} +- {Lesson 2} + +--- + +## Team Capacity Analysis + +**Team Size Over Time**: +{If team size changed} + +| Period | Team Size | Avg Velocity | Points per Person | +|--------|-----------|--------------|-------------------| +| Sprint 1-2 | {size} | {velocity} | {per_person} | +| Sprint 3-5 | {size} | {velocity} | {per_person} | + +**Observations**: +- {How team size changes affected overall velocity} +- {Per-person productivity trends} + +--- + +## Story Point Distribution + +**By Size**: + +| Size | Count | Percentage | Avg Completion Time | +|------|-------|------------|---------------------| +| 1 pt | {count} | {pct}% | {X} days | +| 2 pts | {count} | {pct}% | {X} days | +| 3 pts | {count} | {pct}% | {X} days | +| 5 pts | {count} | {pct}% | {X} days | +| 8 pts | {count} | {pct}% | {X} days | +| 13+ pts | {count} | {pct}% | {X} days | + +**Observations**: +- {Most common story size} +- {Correlation between size and completion rate} + +--- + +## Velocity Predictions + +**For Next Sprint**: +- **Conservative Estimate**: {avg - stddev} points +- **Expected Estimate**: {avg} points +- **Optimistic Estimate**: {avg + stddev} points + +**Recommendation**: Plan for {recommended} story points in Sprint {next} + +**Rationale**: {Based on recent trend and team capacity} + +--- + +## Recommendations for Sprint Planning + +{5-7 actionable recommendations based on velocity analysis} + +1. **Story Sizing**: {recommendation about estimations} +2. **Capacity Planning**: {recommendation about sprint commitments} +3. **Risk Buffer**: {recommendation about buffer time} +4. **Team Focus**: {recommendation based on patterns} +5. **Process Improvements**: {recommendation for efficiency} + +--- + +## Appendix: Data Sources + +- Sprint Plans: {paths to sprint documents} +- Sprint Retrospectives: {paths to retro notes} +- Team Composition: {source} +- Story Point Definitions: {link to estimation guide if exists} + +--- + +**Report Generated by**: ProjectMaster +**Last Updated**: {YYYY-MM-DD HH:MM} +``` + +### Full Report: + +Combine all sections above into one comprehensive document with table of contents. + +## Task 4: Save and Present Report + +1. **Create reports directory** (if doesn't exist): + ```bash + mkdir -p reports/ + ``` + +2. **Generate filename**: + ``` + reports/{report-type}-{project-name-slug}-{YYYY-MM-DD}.md + Example: reports/summary-ecommerce-redesign-2025-11-13.md + ``` + +3. **Write report file**: + ``` + Use Write tool to create the report document + ``` + +4. **Update governance**: + - Add entry to project README.md Recent Activity: + ```markdown + - 2025-11-13: Generated {report-type} report + ``` + - Create or update reports/README.md: + ```markdown + # Project Reports + + ## Recent Reports + - [{Date}: {Report Type}](filename.md) - {Brief description} + ``` + +5. **Present confirmation**: + ``` + ✅ Report Generated Successfully! + + 📄 Report Type: {type} + 📊 Project: {project name} + 📅 Generated: {date time} + + 📁 Saved to: reports/{filename}.md + + 📊 Report includes: + {List of sections included} + + 💡 Next steps: + - View report: Read reports/{filename}.md + - Share with team + - Generate different report type: /project-report {project} {other-type} + + Would you like me to: + - Summarize key findings from the report + - Open the report for viewing + - Generate another report type + ``` + +## Notes + +- Reports are markdown documents - easy to read, share, and version control +- Reports are timestamped - track project evolution over time +- Each report type serves different audiences: + - **Summary**: Executives, stakeholders + - **Sprint**: Team, Scrum Master + - **Milestone**: Project Manager, Product Owner + - **Velocity**: Team, for sprint planning + - **Full**: Comprehensive record, audits +- Reports are generated from live data - always current +- Reports become historical record of project progress + +## Examples + +### Example 1: Generate Summary Report + +``` +User: /project-report + +Claude: 📊 Generate Project Report + +Select project: +1. E-Commerce Redesign (./ecommerce-redesign) +2. Mobile App (./mobile-app) + +Which project? (1-2) + +User: 1 + +Claude: Select report type: +1. Summary - High-level overview +2. Sprint - Current sprint analysis +3. Milestone - Milestone progress +4. Velocity - Team performance +5. Full - Comprehensive report + +Which type? (1-5) + +User: 1 + +Claude: Generating summary report for E-Commerce Redesign... + +[Gathers data, generates report] + +✅ Report Generated Successfully! + +📄 Report Type: Summary +📊 Project: E-Commerce Redesign +📅 Generated: 2025-11-13 10:30 + +📁 Saved to: reports/summary-ecommerce-redesign-2025-11-13.md + +📊 Report includes: +- Executive summary +- Current sprint status (Sprint 5) +- Milestone progress (3/7 completed) +- Key achievements (last 30 days) +- Risks and recommendations + +Key Finding: Project is on track. Beta Release milestone due in 15 days with 75% progress. + +Would you like me to summarize other key findings? +``` + +### Example 2: Direct Command + +``` +User: /project-report ecommerce-redesign velocity + +Claude: Generating velocity report for E-Commerce Redesign... + +[Analyzes last 6 sprints, calculates metrics] + +✅ Velocity Report Generated! + +📊 Key Findings: +- Average Velocity: 42 points/sprint +- Trend: Stable +- Estimation Accuracy: 89% +- Recommendation: Plan 40-45 points for Sprint 6 + +📁 Full report: reports/velocity-ecommerce-redesign-2025-11-13.md +``` + +--- + +This command transforms project data into actionable insights. Reports provide clarity for decision-making and accountability for progress. diff --git a/commands/project-status.md b/commands/project-status.md new file mode 100644 index 0000000..ef35f46 --- /dev/null +++ b/commands/project-status.md @@ -0,0 +1,483 @@ +--- +description: View comprehensive status of all projects in the workspace including sprints, milestones, team activity, and governance health +--- + +# Project Status Overview + +When the user runs `/project-status`, provide a comprehensive overview of all project activities, progress, and health. + +## Task 1: Discover Projects + +Scan the workspace to find all ProjectMaster-managed projects: + +1. **Find all RULE.md files**: + ```bash + find . -name "RULE.md" -type f + ``` + +2. **For each RULE.md found**: + - Read the file + - Check if it has ProjectMaster configuration (methodology field) + - Extract project name (from RULE.md or parent directory name) + - Note project location + +3. **Identify primary project**: + - If in a project directory: That project + - If in workspace root with multiple projects: All projects + - If single project in workspace: That project + +## Task 2: Gather Project Data + +For each project, collect comprehensive status information: + +### 2.1 Basic Project Info + +From RULE.md: +- Project name +- Methodology (Scrum, Kanban, Waterfall, etc.) +- Team size +- Start date + +### 2.2 Current Sprint/Iteration Status + +Read active sprint document: +```bash +grep -r "status: active" sprints/*/sprint-plan.md +``` + +Extract: +- Sprint number and goal +- Start and end dates +- Days remaining +- Story completion (X/Y stories, A/B points) +- Velocity percentage +- Blockers (if any) +- Team members and assignments + +### 2.3 Milestone Status + +Read milestones.yaml: +- Total milestones +- Completed milestones +- In-progress milestones +- Next milestone due +- Any delayed milestones +- Overall completion percentage + +### 2.4 Recent Activity + +Check Recent Activity section in project README.md: +- Last 5-7 activities +- Types: meetings, sprint updates, milestone completions, document additions + +### 2.5 Team Activity + +Scan recent content for @mentions: +- Who's been active recently +- Current assignments +- Upcoming responsibilities + +### 2.6 Governance Health + +Quick governance check: +- RULE.md present and valid +- README.md files up to date +- Directory structure intact +- milestones.yaml valid + +### 2.7 Upcoming Items + +- Next sprint start (if Scrum) +- Upcoming milestones +- Scheduled meetings +- Deadlines approaching + +## Task 3: Present Status Report + +Format and present the comprehensive status: + +### For Single Project: + +``` +📊 Project Status: {Project Name} + +═══════════════════════════════════════════════════════ + +📋 PROJECT INFO +**Methodology**: {Scrum | Kanban | Waterfall | Agile} +**Team**: {size} members +**Started**: {start_date} +**Status**: {Active | Planning | On Hold} + +═══════════════════════════════════════════════════════ + +🏃 CURRENT SPRINT +**Sprint {number}**: {Goal} +**Progress**: Day {X} of {Y} ({Z}% elapsed) +**Stories**: {completed}/{total} completed ({A}/{B} points) +**Velocity**: {percentage}% - {On Track | At Risk | Behind} + +✅ Completed ({count}): +- {Story titles} + +🔄 In Progress ({count}): +- {Story title} - @{owner} +- {Story title} - @{owner} + +⚠️ Blocked ({count}): +- {Story title} - {blocker reason} + +═══════════════════════════════════════════════════════ + +🎯 MILESTONES +**Overall Progress**: {X}/{Y} milestones ({percentage}%) + +✅ Completed ({count}): +- {Milestone name} ({completion_date}) + +🔄 In Progress ({count}): +- {Milestone name} - {target_date} ({progress}%) + +📅 Upcoming ({count}): +- {Milestone name} - {target_date} ({days} days) + +⚠️ At Risk: +{If any milestones delayed or at risk} +- {Milestone name} - {issue description} + +**Next Milestone**: {Name} ({target_date}, {days_remaining} days) + +═══════════════════════════════════════════════════════ + +👥 TEAM ACTIVITY +{Top 3-5 most active team members in last week/sprint} + +**@{member1}**: +- Current: {current story/task} +- Completed: {count} stories this sprint +- Upcoming: {next assignment} + +**@{member2}**: +- Current: {current story/task} +- Completed: {count} stories +- Blockers: {blocker if any} + +[Continue for other active members] + +═══════════════════════════════════════════════════════ + +📅 RECENT ACTIVITY +{Last 7 days or current sprint} + +- {Date}: {Activity description} +- {Date}: {Activity description} +- {Date}: {Activity description} +- {Date}: {Activity description} +- {Date}: {Activity description} + +═══════════════════════════════════════════════════════ + +🔔 UPCOMING +**This Week**: +- {Upcoming item 1} +- {Upcoming item 2} + +**Next Week**: +- {Upcoming item 1} + +**Next Month**: +- {Milestone or major deliverable} + +═══════════════════════════════════════════════════════ + +🏥 GOVERNANCE HEALTH +RULE.md: ✅ Valid +milestones.yaml: ✅ Valid +README indexes: ✅ Up to date ({last_updated}) +Directory structure: ✅ Complete + +**Overall Health**: {Excellent | Good | Needs Attention} + +{If issues exist:} +⚠️ Issues: +- {Issue description} + +═══════════════════════════════════════════════════════ + +💡 QUICK ACTIONS +- Update sprint progress: "Sprint {number} progress update" +- Check milestone: "Milestone status for {next_milestone}" +- Find content: "Find meetings about {topic}" +- Generate report: "/project-report" + +═══════════════════════════════════════════════════════ +``` + +### For Multiple Projects (Workspace Overview): + +``` +📊 Workspace Status: {count} Projects + +═══════════════════════════════════════════════════════ + +📁 PROJECT: {Project 1 Name} +Location: {path} +Status: {Active | On Hold} +Current: Sprint {X} - {Goal} ({progress}%) +Next Milestone: {Name} ({date}) +Health: ✅ Good +[Quick summary - 2-3 lines] + +─────────────────────────────────────────────────────── + +📁 PROJECT: {Project 2 Name} +Location: {path} +Status: {Active} +Current: Sprint {Y} - {Goal} ({progress}%) +Next Milestone: {Name} ({date}) +Health: ⚠️ Needs Attention (README outdated) +[Quick summary - 2-3 lines] + +─────────────────────────────────────────────────────── + +[Continue for each project] + +═══════════════════════════════════════════════════════ + +📊 WORKSPACE SUMMARY + +**Total Projects**: {count} +**Active**: {count} +**Total Sprints in Progress**: {count} +**Upcoming Milestones (Next 30 days)**: {count} +**Team Members Across Projects**: {count unique} + +**Activity Level**: {High | Medium | Low} +- Total activities last 7 days: {count} +- Most active project: {name} + +**Health Status**: +- ✅ Healthy: {count} projects +- ⚠️ Needs Attention: {count} projects +- ❌ Issues: {count} projects + +═══════════════════════════════════════════════════════ + +💡 ACTIONS +- View specific project: "Show status for {project_name}" +- Detailed report: "/project-report {project_name}" +- Validate all: "/project-init" (in each project directory) + +═══════════════════════════════════════════════════════ +``` + +### For Project in Planning Phase (No Active Sprint): + +``` +📊 Project Status: {Project Name} + +═══════════════════════════════════════════════════════ + +📋 PROJECT INFO +**Status**: Planning / Setup +**Methodology**: {methodology} +**Team**: {size} members +**Initialized**: {date} + +═══════════════════════════════════════════════════════ + +🏃 SPRINT STATUS +No active sprint. + +**Backlog**: {count} items ready +- {Item 1} +- {Item 2} +- {Item 3} + +💡 Ready to start? Try: +"Start sprint 1 for {theme}" + +═══════════════════════════════════════════════════════ + +🎯 MILESTONES +**Defined**: {count} milestones +**Target**: {first_milestone} ({target_date}) + +📅 Roadmap: +- {Milestone 1} - {date} +- {Milestone 2} - {date} +- {Milestone 3} - {date} + +═══════════════════════════════════════════════════════ + +💡 GET STARTED +1. Plan your first sprint: "Start sprint 1" +2. Schedule kickoff: "Create meeting notes for kickoff" +3. Refine backlog: "Add user story for {feature}" + +═══════════════════════════════════════════════════════ +``` + +## Task 4: Handle User Follow-ups + +After presenting status, be ready to handle common follow-ups: + +### Common Follow-up Requests: + +**"Show more details on {sprint/milestone/team member}"** +- Activate appropriate Skill (manage-sprint, track-milestone) to provide detailed view + +**"What's blocking us?"** +- Extract and present all blockers from sprints and milestones + +**"Who's working on what?"** +- Present detailed team assignment breakdown + +**"Show me last week's activity"** +- Time-filtered activity view + +**"Generate a report"** +- Redirect to `/project-report` command + +**"What should we focus on?"** +- Analyze status and provide recommendations based on: + - Blockers needing resolution + - At-risk milestones + - Sprint health + - Upcoming deadlines + +## Task 5: Provide Recommendations + +Based on status analysis, offer actionable recommendations: + +### If Sprint Behind Schedule: +``` +⚠️ Recommendation: Sprint {number} is behind schedule + +Current: {X}% complete with {Y}% time remaining + +Suggestions: +- Review blockers in next standup +- Consider descoping lower-priority stories +- Allocate additional resources to critical stories +- Plan time for recovery in next sprint +``` + +### If Milestone at Risk: +``` +⚠️ Recommendation: {Milestone name} at risk + +Target: {date} ({days} days) +Progress: {percentage}% ({behind/on track}) + +Suggestions: +- Prioritize milestone-critical stories +- Review sprint allocations +- Consider extending milestone deadline +- Add checkpoint meeting: "Create meeting for milestone review" +``` + +### If No Recent Activity: +``` +ℹ️ Notice: Low activity in last {days} days + +Last activity: {date} - {description} + +Suggestions: +- Resume work: "Start sprint {number}" +- Update project status +- Archive if project completed +- Mark project on hold if paused +``` + +### If Governance Issues: +``` +⚠️ Governance needs attention + +Issues: +- README indexes outdated +- {count} directories missing README +- milestones.yaml has validation errors + +Suggestion: +Run "/project-init" to validate and fix governance +``` + +## Notes + +- This command provides executive-level visibility into project health +- It aggregates data from multiple sources (RULE.md, sprints, milestones, meetings) +- It highlights both progress and issues +- It's safe to run frequently - read-only operation +- It works for single projects or workspace with multiple projects + +## Examples + +### Example 1: Healthy Active Project + +``` +User: /project-status + +Claude: 📊 Project Status: E-Commerce Redesign + +[Shows complete status with all sections] + +Current Sprint: On Track ✅ +Next Milestone: 15 days away +Team: Fully assigned +Governance: Healthy ✅ + +Overall: Project is progressing well. Keep momentum! +``` + +### Example 2: Project with Issues + +``` +User: /project-status + +Claude: 📊 Project Status: Mobile App + +[Shows status] + +⚠️ Alerts: +- Sprint 5 at 50% complete with only 2 days remaining +- 2 stories blocked on external dependencies +- Beta Release milestone at risk (3 days behind) + +Recommendations: +1. Review blockers urgently +2. Descope non-critical Sprint 5 stories +3. Reassess Beta Release date + +Would you like to: +- Review blocked stories in detail +- Update milestone dates +- Generate risk report +``` + +### Example 3: Multiple Projects + +``` +User: /project-status + +Claude: 📊 Workspace Status: 3 Projects + +PROJECT: E-Commerce Redesign +✅ Healthy | Sprint 5 (75%) | Beta: 15 days + +PROJECT: Mobile App Rewrite +⚠️ At Risk | Sprint 3 (40%) | MVP: OVERDUE + +PROJECT: Internal Tools +✅ Healthy | Kanban (12 cards active) | No milestones + +SUMMARY: +2 of 3 projects healthy +1 project needs immediate attention (Mobile App) + +Focus: Mobile App MVP is overdue. Review? +``` + +--- + +This command is the project dashboard - quick visibility into everything that matters. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7c4e8c4 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,77 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:eternnoir/claude-tool:projectmaster", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "85b3c0ddf70672171ca5a069f904f478c5ef53ea", + "treeHash": "b495951ad819c3dc4ba8979708a4cd36d2a5ff3ce86a3736a7505df5334aecab", + "generatedAt": "2025-11-28T10:16:49.557356Z", + "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": "projectmaster", + "description": "Comprehensive software project management system with support for Agile, Scrum, Kanban, and Waterfall methodologies. Manages meetings, sprints, milestones, and project documentation with full AkashicRecords governance integration.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "59ae201fcdf619367796a5e96651b8e2d4b3dc8e9004b178cb01ed024a6a1caa" + }, + { + "path": "agents/project-governance.md", + "sha256": "67781806abc12e9fa3241177ef39dfd9442e7e7cc628352eb13dea9b43fa8e20" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "0cf9660eb7583f5df969518dda7d94a7dade333010b454ebb491f150338ed08a" + }, + { + "path": "commands/project-report.md", + "sha256": "3715c9553e1301143be70c17b00e4f4af8fc0f182abcecb7c5122c2f610efe05" + }, + { + "path": "commands/project-status.md", + "sha256": "f208528412e30154405cfa4e3e87cfcc0dbdd57a205b33b8be1b2bcaa787192f" + }, + { + "path": "commands/project-init.md", + "sha256": "d85d68d9058ada45c1796c366947ea2ef883e73ac2e841d2e2e3ae04ba7e158c" + }, + { + "path": "skills/project-search/SKILL.md", + "sha256": "44fcb6351152ba8d36a4a52b1b08fdc1b13fe34e5f97b892af67104ee5cb2bf8" + }, + { + "path": "skills/track-meeting/SKILL.md", + "sha256": "d50b09ef7a345e7b9f05f45ae2ddc88497f20ade7ef0afcfb3aa94c589fbb81f" + }, + { + "path": "skills/initialize-project/SKILL.md", + "sha256": "747247d90ed244ffa67c28ed11615e77563fe7d3fc54f44ad9f656ffe8553b68" + }, + { + "path": "skills/manage-sprint/SKILL.md", + "sha256": "570a1125c852baf1823d20c2f36c2dbe82696ad9c74b87b25efc8ad6acfde313" + }, + { + "path": "skills/track-milestone/SKILL.md", + "sha256": "cac3b8a3acb7f0eb6ffd81e62c3443fe171efed39ac811d7e85a1669d9792439" + } + ], + "dirSha256": "b495951ad819c3dc4ba8979708a4cd36d2a5ff3ce86a3736a7505df5334aecab" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/initialize-project/SKILL.md b/skills/initialize-project/SKILL.md new file mode 100644 index 0000000..64e6b58 --- /dev/null +++ b/skills/initialize-project/SKILL.md @@ -0,0 +1,986 @@ +--- +name: initialize-project +description: Initialize a new software project with customized structure through interactive Q&A. Use when user mentions "new project", "start project", "initialize project", "create project", or "set up project". Gathers methodology, team structure, documentation preferences, and integration requirements to generate appropriate RULE.md and directory structure. +--- + +# Initialize Project Skill + +## When to use this Skill + +Activate when the user: +- Mentions starting or creating a new project +- Uses keywords: "new project", "start project", "initialize project", "create project", "set up project" +- Wants to set up project management structure +- Needs to configure project documentation + +## Workflow + +### Phase 1: Project Identification + +**Objective**: Understand what project we're setting up. + +**Steps**: +1. **Extract project name** from user message if provided +2. **Determine target directory**: + - If in a directory already, offer to initialize there + - If project name given, create new directory + - Otherwise, ask where to create the project +3. **Check for existing structure**: + - Use `ls` to check if directory exists + - Use `Read` to check for existing RULE.md + - Warn if project already initialized + +**Example**: +``` +User: "I want to create a new project called Mobile App Redesign" + +Detected: +- Project name: "mobile-app-redesign" (slugified) +- Action: Create new directory +``` + +### Phase 2: Interactive Q&A + +**Objective**: Gather complete information about team workflow and preferences. + +Use **AskUserQuestion** tool with clear, focused questions. Each question should offer specific options. + +#### Question Set 1: Development Methodology + +**Question**: "What development methodology does your team use?" + +**Options to present**: +1. **Scrum** - Time-boxed sprints with ceremonies (planning, daily standup, review, retrospective) +2. **Kanban** - Continuous flow with WIP limits and visual board +3. **Waterfall** - Sequential phases with formal handoffs +4. **Agile (general)** - Iterative development without strict Scrum ceremonies +5. **Hybrid/Custom** - Combination of methodologies + +**Follow-up questions based on choice**: + +If **Scrum** selected: +- "How long are your sprints?" (1 week / 2 weeks / 3 weeks / 4 weeks) +- "Do you hold daily standups?" (Yes / No) +- "Sprint ceremonies to track?" (Planning, Review, Retrospective - multiSelect) + +If **Kanban** selected: +- "What are your workflow stages?" (Backlog, In Progress, Review, Done - customizable) +- "Do you use WIP limits?" (Yes / No) +- "How often do you review the board?" (Daily / Weekly / Ad-hoc) + +If **Waterfall** selected: +- "What are your project phases?" (Requirements, Design, Development, Testing, Deployment - customizable) +- "Do you need phase gate reviews?" (Yes / No) + +If **Agile (general)** selected: +- "How long are your iterations?" (1 week / 2 weeks / 4 weeks / Continuous) +- "Do you have regular team meetings?" (Yes / No) + +If **Hybrid/Custom** selected: +- Ask user to describe their process +- Extract key ceremonies and practices + +#### Question Set 2: Team Structure + +**Question**: "Tell me about your team structure" + +**Information to gather**: +- Team size (Small: 2-5 / Medium: 6-10 / Large: 11+) +- Key roles present: + - Product Owner / Product Manager + - Scrum Master / Project Manager + - Developers (how many?) + - Designers + - QA / Testers + - Others +- Communication patterns: + - Daily syncs + - Weekly planning + - Async-first + - Real-time collaboration + +**Use AskUserQuestion** with multiple questions if needed. + +#### Question Set 3: Documentation Preferences + +**Question**: "How does your team prefer to document work?" + +**Options**: +1. **Structured with frontmatter** - YAML frontmatter with metadata, structured sections +2. **Simple markdown** - Plain markdown without strict formatting +3. **Table-based** - Information organized in markdown tables +4. **Issue-tracker style** - Similar to GitHub Issues / Jira format + +**Follow-up**: +- "File naming convention preference?" + - Date-prefixed: `2025-11-13_meeting-name.md` + - Descriptive: `sprint-planning-sprint-5.md` + - Numbered: `001-meeting-name.md` + - Custom (ask user) + +#### Question Set 4: Integration Requirements + +**Question**: "What tools does your team integrate with?" + +**Present as multiSelect options**: +- Version control: Git / GitHub / GitLab / Bitbucket +- Issue tracking: GitHub Issues / Jira / Linear / Asana / Trello +- CI/CD: GitHub Actions / GitLab CI / Jenkins / CircleCI +- Communication: Slack / Discord / Microsoft Teams +- Documentation: Notion / Confluence / Wiki +- None / Other + +**For each selected integration**, gather specific details: +- Git: Repository URL, branch naming convention +- Issue tracker: Project key, link format +- CI/CD: Workflow names +- Communication: Webhook URLs, channel naming +- Documentation: Workspace URL, linking format + +### Phase 3: Analysis & RULE.md Generation + +**Objective**: Synthesize all Q&A responses into a comprehensive RULE.md. + +**Steps**: + +1. **Analyze responses**: + - Identify primary methodology + - Extract team size and structure + - Determine documentation format + - List integrations + +2. **Generate directory structure** based on methodology: + + **For Scrum**: + ``` + project-name/ + ├── RULE.md + ├── README.md + ├── meetings/ + │ ├── README.md + │ ├── daily-standups/ + │ ├── sprint-planning/ + │ ├── sprint-reviews/ + │ └── retrospectives/ + ├── sprints/ + │ ├── README.md + │ ├── backlog/ + │ └── current/ + ├── docs/ + │ ├── README.md + │ └── technical/ + ├── decisions/ + │ └── README.md + ├── communications/ + │ └── README.md + └── milestones.yaml + ``` + + **For Kanban**: + ``` + project-name/ + ├── RULE.md + ├── README.md + ├── board/ + │ ├── README.md + │ ├── backlog/ + │ ├── in-progress/ + │ ├── review/ + │ └── done/ + ├── meetings/ + │ ├── README.md + │ └── board-reviews/ + ├── docs/ + │ ├── README.md + │ └── technical/ + ├── decisions/ + │ └── README.md + └── milestones.yaml + ``` + + **For Waterfall**: + ``` + project-name/ + ├── RULE.md + ├── README.md + ├── phases/ + │ ├── README.md + │ ├── 01-requirements/ + │ ├── 02-design/ + │ ├── 03-development/ + │ ├── 04-testing/ + │ └── 05-deployment/ + ├── meetings/ + │ ├── README.md + │ └── phase-reviews/ + ├── docs/ + │ ├── README.md + │ └── technical/ + ├── decisions/ + │ └── README.md + └── milestones.yaml + ``` + + **For Agile/Hybrid**: + ``` + project-name/ + ├── RULE.md + ├── README.md + ├── iterations/ + │ ├── README.md + │ └── backlog/ + ├── meetings/ + │ └── README.md + ├── docs/ + │ ├── README.md + │ └── technical/ + ├── decisions/ + │ └── README.md + └── milestones.yaml + ``` + +3. **Generate RULE.md content**: + + Use this template, filling in values from Q&A: + + ```markdown + # Project: [Project Name] + + ## Purpose + [Brief project description - ask user or infer from context] + + ## Methodology + methodology: [scrum|kanban|waterfall|agile|hybrid] + [If Scrum] + sprint_length: [1_week|2_weeks|3_weeks|4_weeks] + daily_standup: [true|false] + ceremonies: [planning, review, retrospective] + + [If Kanban] + workflow_stages: [backlog, in_progress, review, done] + wip_limits: [true|false] + review_frequency: [daily|weekly|adhoc] + + [If Waterfall] + phases: [requirements, design, development, testing, deployment] + phase_gates: [true|false] + + ## Team Structure + team_size: [number] + roles: + [For each role from Q&A] + - role_name: [Name or "TBD"] + + communication_pattern: [daily_syncs|weekly_planning|async_first|realtime] + + ## Directory Structure + [Insert the generated structure from above] + + ## Document Templates + + ### [For each document type, generate template] + + [If Scrum] + #### Meeting Notes Format + ```yaml + --- + title: [Meeting Title] + type: [standup|planning|retrospective|review] + date: [YYYY-MM-DD] + attendees: [list] + duration_minutes: [number] + --- + + ## Agenda + - + + ## Discussion + [Notes] + + ## Action Items + - [ ] Task - @owner - due: YYYY-MM-DD + + ## Decisions + - + ``` + + #### Sprint Format + ```yaml + --- + sprint_number: [number] + start_date: YYYY-MM-DD + end_date: YYYY-MM-DD + sprint_goal: [Goal] + status: [planning|active|completed] + --- + + ## Sprint Goal + [Description] + + ## User Stories + - [ ] As a [user], I want [goal] so that [benefit] + - Story Points: X + - Priority: [High|Medium|Low] + - Assignee: @[name] + + ## Sprint Retrospective + [Added at end] + ``` + + [If Kanban] + #### Card Format + ```yaml + --- + title: [Card Title] + type: [feature|bug|improvement|task] + status: [backlog|in_progress|review|done] + priority: [high|medium|low] + assignee: @[name] + created: YYYY-MM-DD + updated: YYYY-MM-DD + --- + + ## Description + [What needs to be done] + + ## Acceptance Criteria + - [ ] Criterion 1 + - [ ] Criterion 2 + + ## Notes + [Additional context] + ``` + + [If Waterfall] + #### Phase Document Format + ```yaml + --- + phase_name: [Phase Name] + phase_number: [1-5] + start_date: YYYY-MM-DD + planned_end_date: YYYY-MM-DD + actual_end_date: [YYYY-MM-DD or "in_progress"] + status: [planning|active|review|completed] + --- + + ## Phase Objectives + [What this phase accomplishes] + + ## Deliverables + - [ ] Deliverable 1 + - [ ] Deliverable 2 + + ## Phase Gate Criteria + [Criteria for moving to next phase] + + ## Notes + [Additional information] + ``` + + ## File Naming Convention + format: [date_prefixed|descriptive|numbered|custom] + [If date_prefixed] + pattern: "YYYY-MM-DD_descriptive-name.md" + [If descriptive] + pattern: "descriptive-name-with-context.md" + [If numbered] + pattern: "###-descriptive-name.md" + [If custom] + pattern: "[user-specified pattern]" + + ## Auto Workflows + + ### When Claude creates meeting notes: + 1. Extract all action items with @mentions + 2. Update README.md meeting index + 3. [If Scrum] Link to current sprint if relevant + 4. [If integrations enabled] Update external tracker + 5. Notify attendees of action items (if communication tool integrated) + + ### When Claude creates/updates [sprint|iteration|card|phase]: + 1. Update status in milestones.yaml if milestone-related + 2. Update README.md index + 3. [If version control] Suggest related branches + 4. [If issue tracker] Link to external issues + 5. Calculate velocity/progress metrics + + ### When Claude marks milestone complete: + 1. Update milestones.yaml status + 2. Generate milestone completion report + 3. Archive related documentation + 4. Update project timeline + 5. [If communication tool] Announce completion + + ### When Claude searches project: + 1. Check README.md indexes first (fastest) + 2. Search by file patterns + 3. Full-text search as last resort + 4. Rank by relevance, recency, and location + 5. Show context (surrounding content) + + ## Integrations + + [For each integration from Q&A] + + ### [Integration Name] + type: [git|issue_tracker|ci_cd|communication|documentation] + [Specific configuration] + [If Git] + repository: [URL] + branch_convention: [feature/*, bugfix/*, etc.] + [If Issue Tracker] + project_key: [KEY] + issue_link_format: "[KEY]-###" + [If CI/CD] + workflows: [list] + [If Communication] + channels: [list] + webhook: [URL if applicable] + [If Documentation] + workspace: [URL] + link_format: [pattern] + + ## Allowed Operations + All operations allowed. Maintain governance through README.md updates. + Track milestones and dependencies. Always confirm destructive operations. + + ## Special Instructions + + [Add any custom workflows or requirements mentioned by user during Q&A] + + ## Notes + + - Created: [YYYY-MM-DD] + - Initialized by: ProjectMaster initialize-project Skill + - Last updated: [YYYY-MM-DD] + ``` + +4. **Generate milestones.yaml template**: + + ```yaml + # Project Milestones + # Managed by ProjectMaster track-milestone Skill + + project: + name: [Project Name] + start_date: [YYYY-MM-DD] + target_completion: [YYYY-MM-DD or "TBD"] + status: [planning|active|completed] + + milestones: + # Example milestone structure: + # - id: milestone-1 + # name: "Beta Release" + # description: "Feature-complete beta ready for testing" + # target_date: YYYY-MM-DD + # actual_date: YYYY-MM-DD or null + # status: planned|in_progress|completed|delayed + # dependencies: [milestone-0] + # deliverables: + # - Deliverable 1 + # - Deliverable 2 + # owner: "@name" + # notes: "Additional context" + + # Add milestones here as project progresses + ``` + +### Phase 4: User Confirmation + +**Objective**: Show the user what will be created and get approval. + +**Steps**: + +1. **Present summary** of configuration: + ``` + 📋 Project Configuration Summary + + Project: [name] + Methodology: [methodology with key details] + Team: [size] members ([roles]) + Documentation: [format preference] + Integrations: [list] + + Directory structure: + [Show tree structure] + + This will create: + - RULE.md with your team's workflow + - README.md project overview + - [X] directories for [meetings/sprints/phases/etc] + - milestones.yaml for tracking + - Initial documentation templates + + Proceed with initialization? + ``` + +2. **Wait for user confirmation** + +3. **If user wants changes**: + - Ask what to modify + - Update configuration + - Show summary again + - Get confirmation + +### Phase 5: Create Structure + +**Objective**: Execute the initialization by creating all files and directories. + +**Steps**: + +1. **Create project directory** (if needed): + ```bash + mkdir -p [project-name] + cd [project-name] + ``` + +2. **Create all subdirectories**: + ```bash + mkdir -p [dir1] [dir2] [dir3] ... + ``` + Use the structure generated in Phase 3. + +3. **Write RULE.md**: + Use `Write` tool to create the RULE.md with generated content. + +4. **Write milestones.yaml**: + Use `Write` tool to create milestones.yaml template. + +5. **Write project README.md**: + ```markdown + # [Project Name] + + > [Brief description] + + ## Project Information + + - **Status**: Planning + - **Methodology**: [methodology] + - **Team Size**: [number] + - **Started**: [YYYY-MM-DD] + - **Target Completion**: TBD + + ## Quick Links + + - [RULE.md](RULE.md) - Project governance and workflows + - [milestones.yaml](milestones.yaml) - Milestone tracking + - [Meetings](meetings/) - Meeting notes + - [[Sprints/Iterations/Phases]](path/) - [Work tracking] + - [Documentation](docs/) - Technical documentation + - [Decisions](decisions/) - Architecture decisions + + ## Team + + [List team members and roles from RULE.md] + + ## Current Status + + Project initialized on [YYYY-MM-DD]. Ready to begin [first phase/sprint/iteration]. + + ## Recent Activity + + - [YYYY-MM-DD]: Project initialized with ProjectMaster + + ## Contents + + [Will be auto-updated as content is added] + + --- + + Last updated: [YYYY-MM-DD] + Governance maintained by: ProjectMaster + ``` + +6. **Write README.md for each subdirectory**: + Each major directory gets an index README.md: + + **meetings/README.md**: + ```markdown + # Meetings + + Meeting notes and minutes for [Project Name]. + + ## Recent Meetings + + [Will be auto-updated] + + ## Meeting Types + + - [List types based on methodology] + + --- + + Last updated: [YYYY-MM-DD] + ``` + + **[sprints|board|phases]/README.md**: + ```markdown + # [Sprints/Board/Phases] + + [Work tracking] for [Project Name]. + + ## [Current Sprint/Active Cards/Current Phase] + + [Will be updated as work progresses] + + ## [Backlog/Completed] + + [Will be updated] + + --- + + Last updated: [YYYY-MM-DD] + ``` + + **docs/README.md**: + ```markdown + # Documentation + + Technical documentation for [Project Name]. + + ## Contents + + [Will be auto-updated] + + --- + + Last updated: [YYYY-MM-DD] + ``` + + **decisions/README.md**: + ```markdown + # Decisions + + Architecture and significant decisions for [Project Name]. + + ## Decision Records + + [Will be auto-updated] + + --- + + Last updated: [YYYY-MM-DD] + ``` + +7. **Create template files** (optional): + If helpful, create example templates in a `templates/` directory: + - meeting-template.md + - sprint-template.md + - decision-template.md + +8. **Verify structure**: + ```bash + ls -R + ``` + Confirm all directories and files created successfully. + +### Phase 6: Report + +**Objective**: Confirm successful initialization and guide next steps. + +**Report format**: + +``` +✅ Project Initialized Successfully! + +📁 Created structure for: [Project Name] + Location: [path] + +📄 Key files: + ✓ RULE.md - Project governance + ✓ README.md - Project overview + ✓ milestones.yaml - Milestone tracking + ✓ [X] directories created + +⚙️ Configuration: + - Methodology: [methodology details] + - Team: [size] members + - Documentation: [format] + - Integrations: [list] + +🚀 Next steps: + [Provide 2-3 relevant suggestions based on methodology] + + Examples: + - "Create your first sprint: 'Start sprint 1 for authentication features'" + - "Add a milestone: 'Create milestone for beta release'" + - "Record a meeting: 'Create meeting notes for kickoff'" + - "Add team members to RULE.md" + - "Define first set of user stories" + +💡 Tips: + - Your RULE.md defines how ProjectMaster works with this project + - README.md files are auto-updated as you add content + - All Skills respect your team's workflow from RULE.md + - Use /project-status to see project health anytime + +Ready to start building! What would you like to do first? +``` + +## Special Cases + +### Case 1: Initializing in existing directory + +If the target directory already contains files: + +1. **Check for RULE.md**: + - If exists: "This directory already has a RULE.md. Do you want to reinitialize (overwrites) or update the existing configuration?" + - If doesn't exist: "This directory has files but no governance. Initialize ProjectMaster here?" + +2. **Preserve existing structure**: + - Don't delete existing files + - Create missing directories only + - Merge with existing structure if compatible + +3. **Update README.md**: + - If exists, append governance section + - If doesn't exist, create new + +### Case 2: Multiple projects in workspace + +If user wants to initialize multiple projects: + +1. **Create parent structure**: + ``` + workspace/ + ├── project-1/ + │ └── RULE.md + ├── project-2/ + │ └── RULE.md + └── README.md (workspace index) + ``` + +2. **Each project is independent**: + - Separate RULE.md for each + - Workspace README.md links to all projects + +### Case 3: Minimal initialization + +If user wants quick setup without Q&A: + +1. **Use sensible defaults**: + - Methodology: Agile (general) + - Team: Small (unspecified roles) + - Documentation: Structured with frontmatter + - No integrations + +2. **Create minimal structure**: + ``` + project-name/ + ├── RULE.md (with defaults) + ├── README.md + ├── meetings/ + ├── work/ + ├── docs/ + └── milestones.yaml + ``` + +3. **Inform user**: + "Initialized with default configuration. Edit RULE.md to customize." + +### Case 4: Template-based initialization + +If user references an existing project as template: + +1. **Read template RULE.md** +2. **Copy structure and configuration** +3. **Ask only for differences**: + - Project name + - Team members + - Integration credentials +4. **Create with template configuration** + +## Error Handling + +### Error: Directory already exists + +**Response**: +``` +⚠️ Directory "[name]" already exists. + +Options: +1. Initialize in existing directory (preserves files, adds governance) +2. Choose a different name +3. Cancel initialization + +What would you like to do? +``` + +### Error: Invalid project name + +**Response**: +``` +⚠️ Project name "[name]" contains invalid characters. + +Project names should: +- Use lowercase letters, numbers, hyphens +- No spaces or special characters +- Example: "mobile-app-redesign" + +Please provide a valid project name. +``` + +### Error: Cannot write files + +**Response**: +``` +❌ Error: Unable to create files in [path] + +Possible causes: +- Insufficient permissions +- Disk space full +- Path doesn't exist + +Please check permissions and try again. +``` + +### Error: User cancels during Q&A + +**Response**: +``` +Initialization cancelled. No changes made. + +You can restart initialization anytime by saying: +"Initialize a new project for [your project name]" +``` + +## Integration with AkashicRecords Governance + +This Skill creates RULE.md files that are fully compatible with AkashicRecords: + +1. **RULE.md format**: Uses natural language, readable by both systems +2. **README.md maintenance**: Both systems update README.md indexes +3. **Directory governance**: All ProjectMaster Skills respect RULE.md +4. **Workflow specifications**: Auto Workflows section defines behavior +5. **Cross-plugin compatibility**: AkashicRecords Skills can operate in ProjectMaster-initialized projects + +**Example interaction**: +``` +User: "Save this article about React best practices" + +Claude: [AkashicRecords add-content Skill activates] +Reading RULE.md... This is a project directory. +Article is technical documentation. +Target: docs/technical/ (per RULE.md structure) +[Proceeds with adding article, updates README.md] +``` + +Both plugins share governance, ensuring consistency. + +## Best Practices + +### 1. Complete the Q&A thoroughly + +Don't rush through questions. Accurate answers ensure the RULE.md matches your team's actual workflow. + +### 2. Start simple, iterate + +If unsure about configuration, use defaults and refine RULE.md later as the team's process becomes clearer. + +### 3. Customize templates immediately + +After initialization, review document templates in RULE.md and adjust to match your team's preferences. + +### 4. Involve the team + +Show the generated RULE.md to your team and gather feedback. Update before creating real content. + +### 5. Document custom workflows + +If your team has unique processes, add them to the "Auto Workflows" section in RULE.md immediately. + +### 6. Test with a real item + +After initialization, create one meeting note or sprint to verify the structure works as expected. + +## Examples + +### Example 1: Scrum Project + +``` +User: I want to start a new project for our e-commerce platform redesign + +Claude: I'll help you set up a new project! Let me gather information about your team's workflow. + +📋 Development Methodology +What development process does your team follow? + +User: [Selects Scrum] + +Claude: Great! A few details about your Scrum setup: +- Sprint length: 2 weeks +- Daily standups: Yes +- Ceremonies to track: All (planning, review, retrospective) + +👥 Team Structure +- Team size: 6 +- Roles: Product Owner (Alice), Scrum Master (Bob), 4 Developers + +📝 Documentation +- Format: Structured with frontmatter +- Naming: Date-prefixed (2025-11-13_meeting-name.md) + +🔗 Integrations +- Git (GitHub) +- Issue tracking (GitHub Issues) +- Communication (Slack) + +[Shows summary, user confirms] + +✅ Project Initialized Successfully! + +📁 Created: ecommerce-redesign/ + ✓ RULE.md configured for 2-week Scrum sprints + ✓ Directory structure with meetings/, sprints/, docs/ + ✓ milestones.yaml for tracking + ✓ README.md with project overview + +🚀 Next: "Create sprint 1 for user authentication" +``` + +### Example 2: Kanban Project + +``` +User: Set up a Kanban board for our bug fix project + +Claude: I'll initialize a Kanban-based project! Let me ask a few questions... + +[Q&A for Kanban workflow, team, etc.] + +✅ Project Initialized: bug-fix-kanban/ + ✓ RULE.md configured for Kanban workflow + ✓ board/ directory with backlog/, in-progress/, review/, done/ + ✓ WIP limits enabled in RULE.md + ✓ Weekly board review meetings configured + +🚀 Next: "Add a bug to the backlog" +``` + +### Example 3: Minimal Quick Setup + +``` +User: Quick project setup for prototyping, no fancy stuff + +Claude: I'll create a minimal project with default settings. + +✅ Project Initialized: prototype/ + ✓ RULE.md with Agile defaults + ✓ Basic structure: meetings/, work/, docs/ + ✓ Simple markdown format + +💡 You can customize RULE.md later as your needs evolve. + +🚀 Ready to go! Add your first note or meeting. +``` + +## Notes + +- This Skill only initializes the structure. Actual content is created by other Skills (track-meeting, manage-sprint, etc.). +- The generated RULE.md is a living document - teams should update it as their process evolves. +- All generated templates are customizable - edit RULE.md to change formats. +- Integration details can be added later if not known during initialization. +- The Skill creates a foundation; the team shapes it into their ideal workflow. + +--- + +This Skill is the entry point to ProjectMaster. A well-configured initialization ensures all other Skills work seamlessly with your team's unique workflow. diff --git a/skills/manage-sprint/SKILL.md b/skills/manage-sprint/SKILL.md new file mode 100644 index 0000000..f9e5faf --- /dev/null +++ b/skills/manage-sprint/SKILL.md @@ -0,0 +1,919 @@ +--- +name: manage-sprint +description: Manage sprint/iteration lifecycle for Agile teams including planning, tracking, review, and retrospectives. Use when user mentions "sprint", "iteration", "user story", "backlog", "velocity", "scrum", "kanban board", or wants to track work in iterative cycles. Adapts to Scrum, Kanban, or custom Agile workflows. +--- + +# Manage Sprint Skill + +## When to use this Skill + +Activate when the user: +- Mentions creating, starting, or managing sprints/iterations +- Uses keywords: "sprint", "iteration", "user story", "backlog", "velocity", "scrum" +- Wants to track work items (stories, tasks, bugs) +- References sprint ceremonies (planning, review, retrospective) +- Needs to update sprint status or progress +- Talks about Kanban boards or workflow states + +## Workflow + +This Skill handles multiple sprint-related operations. The workflow adapts based on user intent and project methodology. + +### Phase 1: Context Discovery & Intent Recognition + +**Objective**: Understand project methodology and user's specific intent. + +**Steps**: + +1. **Locate and read RULE.md**: + ```bash + ls RULE.md + Read RULE.md + ``` + +2. **Extract methodology configuration**: + ```markdown + Key fields: + - methodology: [scrum|kanban|waterfall|agile|hybrid] + - sprint_length: [1_week|2_weeks|3_weeks|4_weeks] (if Scrum) + - workflow_stages: [list] (if Kanban) + - ceremonies: [list] (if Scrum) + ``` + +3. **Understand directory structure**: + - Scrum: `sprints/` directory with numbered sprints + - Kanban: `board/` directory with workflow stages + - Agile/Hybrid: `iterations/` or `work/` directory + +4. **Detect user intent** from message: + - **Create new sprint/iteration**: "start sprint", "create sprint", "new sprint" + - **Update sprint status**: "sprint progress", "update sprint", "completed story" + - **Add work items**: "add user story", "create task", "new card" + - **Complete sprint**: "finish sprint", "sprint review", "close sprint" + - **View sprint status**: "sprint status", "what's in this sprint", "show backlog" + - **Move items**: "move to in-progress", "done with task" + +5. **Route to appropriate sub-workflow**: + - Intent: Create → Workflow A (Create Sprint) + - Intent: Update → Workflow B (Update Sprint) + - Intent: Add items → Workflow C (Add Work Items) + - Intent: Complete → Workflow D (Complete Sprint) + - Intent: Status → Workflow E (Report Status) + - Intent: Move → Workflow F (Update Item Status) + +**Example**: +``` +Found RULE.md: +- Methodology: Scrum +- Sprint length: 2 weeks +- Ceremonies: planning, review, retrospective +- Current sprint detection needed + +User intent: "Start sprint 5 for authentication features" +→ Route to Workflow A (Create Sprint) +``` + +### Workflow A: Create Sprint + +**Objective**: Initialize a new sprint/iteration with goals and work items. + +**Steps**: + +1. **Determine sprint number**: + ```bash + # Check existing sprints + ls -d sprints/sprint-*/ + # Determine next number + ``` + +2. **Gather sprint details**: + + **Sprint goal**: + ``` + What's the sprint goal? + Example: "Complete user authentication and profile management" + ``` + + **Start date** (if not provided): + ``` + Sprint start date? (Default: next Monday / today) + ``` + + **Calculate end date**: + - Read `sprint_length` from RULE.md + - Calculate: start_date + sprint_length + + **User stories/work items**: + ``` + What user stories or tasks are in this sprint? + + You can provide: + 1. Full user story format: "As a [user], I want [goal] so that [benefit]" + 2. Simple task list: "Implement login, Add profile page, Write tests" + 3. Issue numbers (if integrated with tracker): "#123, #456, #789" + 4. "I'll add them later" - creates empty sprint + ``` + +3. **Create sprint directory**: + ```bash + mkdir -p sprints/sprint-{number} + ``` + +4. **Generate sprint document** based on RULE.md template: + + **For Scrum**: + ```markdown + --- + sprint_number: {number} + start_date: YYYY-MM-DD + end_date: YYYY-MM-DD + sprint_goal: "{goal}" + status: planning + team_capacity: {from RULE.md or ask} + actual_velocity: null + --- + + # Sprint {number}: {Goal} + + **Duration**: {start_date} to {end_date} ({X} weeks) + **Status**: Planning → Active → Review → Completed + **Team Capacity**: {Y} story points + + ## Sprint Goal + + {Detailed description of sprint goal} + + ## User Stories + + ### Planned Stories + + #### Story 1: {Title} + **As a** {user type} + **I want** {goal} + **So that** {benefit} + + **Story Points**: {X} + **Priority**: {High|Medium|Low} + **Assignee**: @{name} + **Status**: [ ] Not Started | [ ] In Progress | [X] Completed + + **Acceptance Criteria**: + - [ ] Criterion 1 + - [ ] Criterion 2 + - [ ] Criterion 3 + + **Tasks**: + - [ ] Task 1 + - [ ] Task 2 + + #### Story 2: ... + + [Repeat for each story] + + ## Sprint Backlog + + [Optional: List of all items with status] + + | Story | Points | Assignee | Status | + |-------|--------|----------|--------| + | Story 1 | 5 | @alice | In Progress | + | Story 2 | 3 | @bob | Not Started | + + ## Daily Progress + + [Updated during sprint] + + ### {Date} Update + - Completed: [items] + - In Progress: [items] + - Blocked: [items with reasons] + + ## Sprint Metrics + + - Total Story Points: {planned} + - Completed Story Points: {actual} (updated daily) + - Velocity: {completed/planned * 100}% + - Burndown: [link to chart or manual tracking] + + ## Sprint Review + + [Added at sprint end] + + **Date**: {YYYY-MM-DD} + **Attendees**: [list] + + ### Completed + - [Story 1]: Demo notes + - [Story 2]: Demo notes + + ### Not Completed + - [Story X]: Reason, moved to backlog/next sprint + + ### Feedback + - Stakeholder feedback notes + + ## Sprint Retrospective + + [Added after review] + + **Date**: {YYYY-MM-DD} + + ### What Went Well 🎉 + - + + ### What Could Be Improved 🔧 + - + + ### Action Items for Next Sprint + - [ ] Action 1 - @owner + - [ ] Action 2 - @owner + + ### Appreciation 💙 + - + + --- + + **Created**: {YYYY-MM-DD} by ProjectMaster + **Last Updated**: {YYYY-MM-DD} + ``` + + **For Kanban**: + ```markdown + --- + title: "{Goal/Theme}" + created: YYYY-MM-DD + status: active + --- + + # {Goal/Theme} + + ## Active Cards + + ### Backlog + + #### Card: {Title} + **Type**: {feature|bug|improvement|task} + **Priority**: {high|medium|low} + **Assignee**: @{name} + **Created**: YYYY-MM-DD + + **Description**: + {What needs to be done} + + **Acceptance Criteria**: + - [ ] Criterion 1 + - [ ] Criterion 2 + + ### In Progress + [Cards being worked on] + + ### Review + [Cards awaiting review] + + ### Done + [Completed cards] + + ## Metrics + + - WIP Limit: {X} cards + - Current WIP: {Y} cards + - Cycle Time: Average {Z} days + - Throughput: {N} cards/week + + --- + + **Created**: {YYYY-MM-DD} by ProjectMaster + **Last Updated**: {YYYY-MM-DD} + ``` + +5. **Write sprint file**: + ``` + Use Write tool to create: + sprints/sprint-{number}/sprint-plan.md + ``` + +6. **Update governance**: + - Update `sprints/README.md` with new sprint + - Update project `README.md` current status + - Update `milestones.yaml` if sprint contributes to milestone + - Mark as current sprint if applicable + +7. **Link to planning meeting** (if exists): + - Check for recent sprint planning meeting + - Add cross-reference in both documents + +8. **Report creation**: + ``` + ✅ Sprint {number} Created! + + 📋 Sprint: {Goal} + 📅 Duration: {start} to {end} ({X} weeks) + 📊 Stories: {count} ({total} story points) + 👥 Team capacity: {Y} points + + 📄 Document: sprints/sprint-{number}/sprint-plan.md + + User stories: + 1. {Story 1} - {points}sp - @{assignee} + 2. {Story 2} - {points}sp - @{assignee} + ... + + 🚀 Sprint is in "Planning" status + + 💡 Next steps: + - Finalize story estimates with team + - Assign remaining stories + - Mark sprint as "Active" when starting: + "Activate sprint {number}" + - Track daily progress: + "Update sprint {number} progress" + + Ready to begin! + ``` + +### Workflow B: Update Sprint + +**Objective**: Update sprint progress, add daily notes, track completions. + +**Steps**: + +1. **Identify target sprint**: + - If user specifies: "Update sprint 5" + - If not specified: Find current/active sprint + ```bash + # Find active sprint + grep -r "status: active" sprints/*/sprint-plan.md + ``` + +2. **Read current sprint document**: + ``` + Read sprints/sprint-{number}/sprint-plan.md + ``` + +3. **Determine update type**: + - **Status change**: "Activate sprint", "Complete sprint" + - **Progress update**: "Add daily update", "Burndown update" + - **Story completion**: "Mark story completed", "Close story" + - **Add blocker**: "Story blocked", "Issue with story" + +4. **Execute update**: + + **For status change**: + ```yaml + --- + status: active # or completed + --- + ``` + + **For progress update**: + Add to Daily Progress section: + ```markdown + ### {Today's Date} Update + - Completed: Story 1 (5sp), Task A + - In Progress: Story 2 (3sp), Story 3 (8sp) + - Blocked: Story 4 - waiting for API access + + **Completed Story Points**: {cumulative} + **Velocity**: {completed/total * 100}% + ``` + + **For story completion**: + Update story status: + ```markdown + #### Story 1: User Login + **Status**: [X] Completed ← update from [ ] In Progress + **Completed Date**: YYYY-MM-DD ← add + + [Update Sprint Metrics accordingly] + ``` + + **For blocker**: + Add to story and daily progress: + ```markdown + #### Story 4: OAuth Integration + **Status**: [ ] Blocked + **Blocked Since**: YYYY-MM-DD + **Blocker**: Waiting for third-party API credentials + **Owner of Resolution**: @alice + ``` + +5. **Calculate metrics**: + - Count completed stories + - Sum completed story points + - Calculate velocity percentage + - Update burndown (if tracking) + +6. **Update document** using Edit tool: + ``` + Edit sprints/sprint-{number}/sprint-plan.md + Replace old status/progress with new + ``` + +7. **Update governance**: + - Update `sprints/README.md` (current status) + - Update project `README.md` (Recent Activity) + - If story completed, check if milestone impacted + +8. **Report update**: + ``` + ✅ Sprint {number} Updated! + + 📊 Progress: + - Completed: {X}/{Y} stories ({A}/{B} points) + - In Progress: {Z} stories + - Blocked: {W} stories + - Velocity: {percentage}% + + [If story completed:] + 🎉 Completed: + - Story: {title} ({points}sp) by @{assignee} + + [If blocker added:] + ⚠️ Blocker: + - Story: {title} + - Reason: {blocker description} + - Owner: @{owner} + + 📈 Sprint Health: {On Track|At Risk|Behind Schedule} + + 📄 Updated: sprints/sprint-{number}/sprint-plan.md + ``` + +### Workflow C: Add Work Items + +**Objective**: Add user stories, tasks, or cards to sprint/backlog. + +**Steps**: + +1. **Determine target location**: + - Active sprint: Add to current sprint backlog + - Backlog: Add to general backlog + - Specific sprint: Add to named sprint + +2. **Gather work item details**: + + **Title**: Extract from user message or ask + + **Type**: Determine or ask: + - User Story + - Task + - Bug + - Technical Debt + - Improvement + + **Description**: Get full details + - For user stories: As a [user], I want [goal], so that [benefit] + - For tasks: What needs to be done + - For bugs: What's broken, steps to reproduce + + **Story points / Estimate**: Ask or default to TBD + + **Priority**: high | medium | low + + **Assignee**: @name or unassigned + +3. **Format work item** per RULE.md template + +4. **Add to sprint document**: + ``` + Read current sprint document + Edit to add new story under "User Stories" or "Backlog" section + ``` + +5. **Update metrics**: + - Increment total story count + - Add story points to total + - Recalculate capacity if needed + +6. **Update governance** + +7. **Report addition**: + ``` + ✅ Work Item Added! + + 📝 {Type}: {Title} + 📊 Estimate: {points}sp + 👤 Assignee: @{name} + 🎯 Priority: {priority} + + Added to: Sprint {number} / Backlog + + 📄 Updated: sprints/sprint-{number}/sprint-plan.md + ``` + +### Workflow D: Complete Sprint + +**Objective**: Close sprint, conduct review/retro, archive sprint. + +**Steps**: + +1. **Identify sprint to complete** + +2. **Check sprint status**: + ``` + Read sprints/sprint-{number}/sprint-plan.md + Extract: + - Completed stories + - Incomplete stories + - Actual velocity + ``` + +3. **Gather review information**: + + **Sprint Review**: + ``` + Sprint {number} review: + + What was demoed to stakeholders? + [For each completed story] + + Any feedback from stakeholders? + ``` + +4. **Gather retrospective information**: + + **Sprint Retrospective**: + ``` + Sprint {number} retrospective: + + What went well? + What could be improved? + Action items for next sprint? + Any appreciations for team members? + ``` + +5. **Update sprint document**: + ``` + Edit sprints/sprint-{number}/sprint-plan.md + - Update status: completed + - Add Sprint Review section with notes + - Add Sprint Retrospective section with feedback + - Finalize metrics (actual velocity) + ``` + +6. **Handle incomplete stories**: + ``` + ⚠️ Incomplete Stories: + - Story X: {title} + - Story Y: {title} + + What should we do with these? + 1. Move to next sprint + 2. Move to backlog + 3. Archive (not needed anymore) + ``` + + Update accordingly. + +7. **Calculate final metrics**: + ```yaml + actual_velocity: {completed_points} + completion_rate: {completed_stories / total_stories * 100}% + ``` + +8. **Update team velocity**: + - If RULE.md tracks velocity, update average + - Use for future sprint planning + +9. **Archive sprint** (if RULE.md specifies): + ```bash + mkdir -p sprints/archived/ + mv sprints/sprint-{number} sprints/archived/sprint-{number} + ``` + Or keep in place and just mark completed. + +10. **Update governance**: + - Update `sprints/README.md` (move to completed section) + - Update project `README.md` (add to Recent Activity) + - Update `milestones.yaml` if milestone reached + - Link to sprint review/retro meetings if created separately + +11. **Report completion**: + ``` + ✅ Sprint {number} Completed! + + 📊 Final Metrics: + - Completed: {X}/{Y} stories + - Story Points: {A}/{B} points delivered + - Velocity: {percentage}% + - Duration: {start} to {end} + + 🎉 Achievements: + - [Key deliverables] + + 🔧 Improvements for Next Sprint: + - [Action items from retro] + + 📈 Team Velocity: {average over last 3 sprints} + + [If incomplete stories:] + 📦 Incomplete Stories: + - {Story titles} → Moved to {backlog/next sprint} + + 📄 Sprint Report: sprints/sprint-{number}/sprint-plan.md + + 💡 Ready to plan Sprint {number + 1}? + Say: "Start sprint {number + 1} for {theme}" + ``` + +### Workflow E: Report Status + +**Objective**: Show current sprint/work status. + +**Steps**: + +1. **Find current sprint**: + ```bash + grep -r "status: active" sprints/*/sprint-plan.md + ``` + +2. **Read sprint document** + +3. **Extract key information**: + - Sprint number and goal + - Start and end dates + - Days remaining + - Story completion status + - Current velocity + - Blockers + +4. **Format status report**: + ``` + 📊 Current Sprint Status + + **Sprint {number}**: {Goal} + **Duration**: {start} to {end} ({days_remaining} days left) + **Status**: {Active|On Track|At Risk|Behind} + + 📈 Progress: + - Completed: {X}/{Y} stories ({A}/{B} points) + - In Progress: {Z} stories + - Not Started: {W} stories + - Velocity: {percentage}% ({status vs planned}) + + ✅ Completed: + - {Story titles} + + 🔄 In Progress: + - {Story titles with assignees} + + ⚠️ Blockers: + - {Blocker descriptions} + + 📅 Upcoming: + - {Next items to start} + + 💡 Sprint Health: {Assessment} + {If at risk: Recommendations} + + 📄 Full details: sprints/sprint-{number}/sprint-plan.md + ``` + +5. **Include Kanban status if applicable**: + ``` + 📋 Kanban Board Status + + **Backlog**: {X} cards + **In Progress**: {Y} cards (WIP Limit: {Z}) + **Review**: {W} cards + **Done**: {V} cards this week + + 📊 Metrics: + - Avg Cycle Time: {N} days + - Throughput: {M} cards/week + - WIP Status: {Under|At|Over} limit + + ⚠️ Attention Needed: + - {Cards over WIP limit or stuck} + ``` + +### Workflow F: Update Item Status + +**Objective**: Move work items between states (Kanban) or update status (Scrum). + +**Steps**: + +1. **Identify work item**: + - By title/description from user message + - By searching sprint/board documents + +2. **Determine target status**: + - Scrum: Not Started → In Progress → Completed + - Kanban: Backlog → In Progress → Review → Done + +3. **Update item**: + ``` + Edit sprint/board document + Change status field + Add timestamp + ``` + +4. **Check constraints**: + - Kanban: WIP limits + - Scrum: Sprint capacity + +5. **Update governance** and report + +## Special Cases + +### Case 1: Estimating stories during planning + +When creating sprint, offer estimation help: + +``` +Would you like help estimating these stories? + +I can use: +- Historical velocity (if available) +- Story complexity analysis +- Planning poker format (async) +- T-shirt sizing (S/M/L/XL) + +Or you can provide estimates directly. +``` + +### Case 2: Mid-sprint scope change + +If user wants to add stories mid-sprint: + +``` +⚠️ Sprint {number} is already active. + +Adding stories mid-sprint impacts velocity tracking. + +Options: +1. Add to current sprint (increases scope) +2. Add to backlog for next sprint +3. Replace an incomplete story (scope swap) + +Recommended: Option 2 (maintain sprint integrity) + +What would you like to do? +``` + +### Case 3: Velocity calculation + +Track velocity over sprints: + +```markdown +## Team Velocity History + +- Sprint 5: 42 points (target: 45) - 93% +- Sprint 4: 38 points (target: 40) - 95% +- Sprint 3: 45 points (target: 45) - 100% + +**Average Velocity**: 42 points/sprint +**Recommendation for Sprint 6**: Target 40-45 points +``` + +### Case 4: Sprint extensions + +If user wants to extend sprint: + +``` +⚠️ Sprint {number} end date is {date}. + +Extending sprints disrupts team rhythm and ceremonies. + +Options: +1. Extend by {X} days (not recommended) +2. Move incomplete stories to next sprint +3. Reduce scope to meet original deadline + +Recommended: Option 2 or 3 (maintain cadence) + +What would you like to do? +``` + +### Case 5: Cross-sprint dependencies + +If stories have dependencies across sprints: + +```markdown +#### Story: Advanced Search +**Dependencies**: +- Sprint 4: Basic Search (prerequisite) +- Sprint 6: Search Analytics (dependent) + +**Dependency Status**: +- ✅ Basic Search completed +- ⏳ Waiting for this story to start Search Analytics +``` + +## Error Handling + +### Error: No RULE.md found + +``` +⚠️ No RULE.md found. + +Sprint management requires project initialization. + +Options: +1. Initialize project: "Initialize a new project" +2. Create sprint with defaults (Scrum, 2-week) +3. Cancel + +What would you like to do? +``` + +### Error: Methodology doesn't support sprints + +If RULE.md shows Waterfall: + +``` +⚠️ This project uses Waterfall methodology. + +Sprints are not typically used in Waterfall. + +Options: +1. Create phase-based tracking instead +2. Switch to Agile methodology (edit RULE.md) +3. Create sprint anyway (hybrid approach) + +What would you like to do? +``` + +### Error: Sprint number conflict + +``` +⚠️ Sprint {number} already exists. + +Options: +1. Update existing sprint +2. Create sprint {number + 1} +3. Cancel + +What would you like to do? +``` + +## Integration with Other Skills + +### With track-meeting Skill + +Sprint ceremonies create meetings: +- Sprint planning → Meeting note +- Sprint review → Meeting note +- Sprint retrospective → Meeting note + +Cross-link both documents. + +### With track-milestone Skill + +Sprints contribute to milestones: +- Link sprint to milestone in metadata +- Update milestone progress when sprint completes +- Show milestone context in sprint document + +### With AkashicRecords + +Technical decisions made during sprint: +- Link decision records to sprint stories +- Reference knowledge base articles in stories +- Update documentation as part of story completion + +## Best Practices + +### 1. Read RULE.md methodology first + +Sprint format varies by methodology. Always check RULE.md before creating. + +### 2. Track velocity consistently + +Maintain velocity history for better sprint planning. + +### 3. Link ceremonies to sprints + +Connect planning, review, and retro meetings to sprint documents. + +### 4. Update progress regularly + +Daily updates keep team aligned and sprint health visible. + +### 5. Respect WIP limits (Kanban) + +Enforce WIP limits when moving cards. + +### 6. Handle incomplete stories + +Don't let incomplete stories disappear - explicitly decide their fate. + +### 7. Celebrate completions + +Acknowledge team achievements in sprint reports. + +### 8. Learn from retrospectives + +Convert retro action items into next sprint improvements. + +## Notes + +- This Skill adapts to your methodology - Scrum, Kanban, or hybrid. +- Velocity tracking helps teams improve estimation over time. +- Sprint documents become project history - rich, searchable, valuable. +- Cross-referencing sprints, meetings, and milestones creates cohesive project narrative. +- The Skill enforces best practices (like WIP limits) while remaining flexible. + +--- + +Effective sprint management turns agile theory into practice. This Skill makes that management systematic and sustainable. diff --git a/skills/project-search/SKILL.md b/skills/project-search/SKILL.md new file mode 100644 index 0000000..db9064b --- /dev/null +++ b/skills/project-search/SKILL.md @@ -0,0 +1,655 @@ +--- +name: project-search +description: Search across all project artifacts including meetings, sprints, milestones, documentation, and decisions. Use when user mentions "find", "search", "where is", "locate", "show me", or asks questions about project content. Multi-strategy search using README indexes, pattern matching, and full-text search. +--- + +# Project Search Skill + +## When to use this Skill + +Activate when the user: +- Asks to find or locate project content +- Uses keywords: "find", "search", "where is", "locate", "show me" +- Asks questions about project history or decisions +- Needs to find meetings, sprints, or documentation +- Wants to search by person, date, topic, or milestone +- References specific content they can't locate + +## Workflow + +### Phase 1: Query Analysis + +**Objective**: Understand what the user is searching for and determine search strategy. + +**Steps**: + +1. **Parse search query** from user message: + - Extract search terms + - Identify search type (content, person, date, milestone, etc.) + - Detect filters (date range, file type, status) + +2. **Categorize search intent**: + - **Content search**: "Find decisions about database" + - **Person search**: "What has @alice worked on" + - **Date search**: "Meetings from last week" + - **Milestone search**: "What's in beta release milestone" + - **Sprint search**: "Show sprint 5 stories" + - **Topic search**: "Anything about authentication" + - **Status search**: "Show blocked items" + +3. **Extract search parameters**: + - **Keywords**: Main search terms + - **Person**: @mentions or names + - **Date range**: "last week", "Q1", "after Jan 1", specific dates + - **Content type**: meetings, sprints, docs, decisions, all + - **Status**: completed, in-progress, blocked, planned + - **Milestone/Sprint**: Specific milestone or sprint number + +4. **Determine search scope**: + - Project root only + - Specific subdirectory (meetings/, sprints/, etc.) + - Across entire workspace + +**Example Analysis**: +``` +User: "Find all meetings where we discussed the API design" + +Parsed: +- Intent: Content search +- Keywords: ["API design"] +- Content type: meetings +- Date range: all time +- Search scope: meetings/ + +Strategy: README index → Content search in meetings/ +``` + +### Phase 2: Strategy Selection + +**Objective**: Choose optimal search strategy based on query type. + +**Search strategies (in order of preference)**: + +#### Strategy 1: README.md Index Search (Fastest) + +**Use when**: +- Searching by file name, title, or general topic +- Need list of files in category +- Recent content (README indexes are up-to-date) + +**Process**: +1. Read appropriate README.md file: + - `meetings/README.md` for meeting search + - `sprints/README.md` for sprint search + - Project `README.md` for overview +2. Parse index entries +3. Filter by search criteria +4. Return matching entries with descriptions + +**Example**: +``` +Search: "Find sprint 5" +→ Read sprints/README.md +→ Find entry: "Sprint 5: Authentication Features" +→ Return: sprints/sprint-05/sprint-plan.md +``` + +#### Strategy 2: YAML/Structured Data Search (Fast) + +**Use when**: +- Searching milestones (milestones.yaml) +- Searching by metadata (dates, owners, status) +- Need exact matches on structured fields + +**Process**: +1. Read relevant YAML file (milestones.yaml) +2. Parse structure +3. Filter by criteria +4. Return matching entries + +**Example**: +``` +Search: "Show milestones owned by @alice" +→ Read milestones.yaml +→ Filter: owner == "@alice" +→ Return: List of alice's milestones +``` + +#### Strategy 3: Pattern Matching (Fast) + +**Use when**: +- Searching by filename patterns +- Date-based filename search +- Type-based search (all *.md in sprints/) + +**Process**: +1. Use `Glob` tool with pattern: + - `meetings/**/*2025-11*.md` for November meetings + - `sprints/*/sprint-plan.md` for all sprint plans + - `docs/**/*.md` for all documentation +2. Filter results by additional criteria +3. Return matching files + +**Example**: +``` +Search: "Meetings from November" +→ Glob: meetings/**/*2025-11*.md +→ Return: List of November meeting files +``` + +#### Strategy 4: Full-Text Content Search (Slower) + +**Use when**: +- Searching for specific terms in content +- Need to find mentions of topics, names, or concepts +- Other strategies insufficient + +**Process**: +1. Use `Grep` tool with search terms +2. Specify scope (meetings/, sprints/, all project) +3. Extract context around matches +4. Rank results by relevance +5. Return matches with snippets + +**Example**: +``` +Search: "Find discussions about OAuth implementation" +→ Grep: pattern="OAuth" path=meetings/ +→ Find matches in 3 meeting files +→ Return: Files with context snippets +``` + +#### Strategy 5: Cross-Reference Search (Comprehensive) + +**Use when**: +- Need to find all related content +- Following links and references +- Building complete picture + +**Process**: +1. Start with initial search (using above strategies) +2. Read found documents +3. Extract cross-references (links, mentions, related items) +4. Follow links recursively (limited depth) +5. Build relationship map +6. Return full result set with connections + +**Example**: +``` +Search: "Everything about beta release milestone" +→ Find milestone in milestones.yaml +→ Follow related_sprints links +→ Find meetings mentioning beta release +→ Find docs created for beta +→ Return: Complete set with relationships +``` + +### Phase 3: Execute Search + +**Objective**: Run selected search strategy and gather results. + +**Steps**: + +1. **Execute primary search strategy** + +2. **Collect results**: + - File paths + - Titles/descriptions + - Relevant metadata (dates, owners, status) + - Content snippets (for full-text search) + +3. **Apply filters**: + - Date range filter + - Person filter (@mentions) + - Status filter + - Content type filter + +4. **Check governance** (if applicable): + - Read RULE.md for access restrictions + - Filter out restricted content + +5. **Rank results** by: + - **Relevance**: Match quality to query + - **Recency**: Newer content ranked higher + - **Location**: Closer to project root ranked higher + - **Completeness**: Fully completed items vs drafts + +6. **If no results from primary strategy**: + - Fall back to next strategy + - Broaden search criteria + - Suggest related searches + +### Phase 4: Format and Present Results + +**Objective**: Present search results in clear, actionable format. + +**Steps**: + +1. **Group results** by category: + - Meetings + - Sprints/Iterations + - Milestones + - Documentation + - Decisions + +2. **Format result entries**: + ``` + 📄 [Category] Title + Path: path/to/file.md + Date: YYYY-MM-DD + [Relevant metadata: Owner, Status, etc.] + [If content search: Context snippet with highlights] + ``` + +3. **Include result count and search details**: + ``` + 🔍 Search Results for "{query}" + + Found {count} results in {categories} + Search scope: {scope} + Filters applied: {filters if any} + ``` + +4. **Present results**: + + **Format**: + ``` + 🔍 Search Results: "{query}" + + Found {total} results across {categories} + + 📋 Meetings ({count}) + - [2025-11-13: Sprint 5 Planning](meetings/sprint-planning/2025-11-13_sprint-5-planning.md) + "Discussed API design for authentication endpoints..." + + - [2025-11-06: Architecture Review](meetings/general/2025-11-06_api-architecture.md) + "@alice presented OAuth 2.0 implementation options..." + + 🏃 Sprints ({count}) + - [Sprint 5: Authentication Features](sprints/sprint-05/sprint-plan.md) + Status: Active | Stories: 8 | Owner: @bob + + 🎯 Milestones ({count}) + - [Beta Release](milestones.yaml#beta-release) + Target: 2025-03-31 | Status: In Progress | Progress: 75% + + 📚 Documentation ({count}) + - [API Design Document](docs/api-design.md) + Owner: @alice | Updated: 2025-11-10 + + 🔗 Cross-References ({count}) + [If cross-reference search performed] + - Sprint 5 → Beta Release Milestone + - API Design Doc → Sprint 5 Stories + - Sprint Planning → Architecture Review Meeting + ``` + +5. **Offer refinement options**: + ``` + 💡 Refine your search: + - "Show only completed" + - "Find from last month" + - "Search only in sprints" + - "Show details for [specific result]" + ``` + +6. **If too many results**: + ``` + ℹ️ Showing top {limit} results. {remaining} more found. + + Narrow your search: + - Add date range: "from last week" + - Specify type: "only meetings" + - Add filters: "owned by @name" + ``` + +7. **If no results**: + ``` + 🔍 No results found for "{query}" + + Suggestions: + - Check spelling + - Try broader terms + - Search related terms: "{suggestions}" + - Search in different location + + Recent content: + [Show recently added/updated files as alternatives] + ``` + +### Phase 5: Detailed View (Optional) + +**Objective**: If user wants details on specific result, provide full context. + +**Steps**: + +1. **If user selects specific result**: + ``` + User: "Show me the sprint 5 details" + ``` + +2. **Read full document**: + ``` + Read sprints/sprint-05/sprint-plan.md + ``` + +3. **Present complete information**: + ``` + 📄 Sprint 5: Authentication Features + + **Status**: Active (Day 8 of 14) + **Goal**: Complete user authentication and profile management + **Dates**: 2025-11-01 to 2025-11-14 + + **Progress**: + - Completed: 3/8 stories (18/45 points) - 40% + - In Progress: 2 stories + - Blocked: 1 story (OAuth config) + + **Team**: + - @alice: 2 stories + - @bob: 3 stories + - @carol: 2 stories + - @david: 1 story + + **Related**: + - Milestone: Beta Release (contributes to) + - Meetings: [Sprint 5 Planning](link), [Daily Standups](link) + - Docs: [Auth Design](link) + + 📄 Full document: sprints/sprint-05/sprint-plan.md + + 💡 Actions: + - "Update sprint 5 progress" + - "Show sprint 5 meetings" + - "Mark story complete in sprint 5" + ``` + +## Special Cases + +### Case 1: Person-specific search + +``` +User: "What has @alice been working on?" + +Process: +1. Search all content for @alice mentions +2. Filter by recency (last sprint/month) +3. Categorize: + - Assigned stories/tasks + - Meeting attendances + - Owned milestones + - Created documents + +Result: +📊 @alice's Recent Activity + +**Current Work** (Sprint 5): +- Story: OAuth Integration (8sp) - In Progress +- Story: Profile Edit Page (3sp) - Completed ✅ + +**Meetings** (Last 2 weeks): +- Sprint 5 Planning (2025-11-01) +- Architecture Review (2025-11-06) +- Daily Standups (10 attendances) + +**Milestones**: +- Owner: Security Audit (Target: 2025-03-20) + +**Documents**: +- Created: API Design Doc (2025-11-10) +- Updated: Auth Spec (2025-11-08) +``` + +### Case 2: Timeline/Date-based search + +``` +User: "What happened in the project last week?" + +Process: +1. Calculate date range (last week) +2. Search all content within range +3. Sort chronologically +4. Group by day + +Result: +📅 Project Activity: Nov 6 - Nov 13, 2025 + +**Monday, Nov 6** +- Meeting: Sprint 4 Retrospective +- Sprint 4 completed (38/40 points) +- Milestone updated: Beta Release (60% → 75%) + +**Tuesday, Nov 7** +- Sprint 5 started +- Stories assigned to team + +**Wednesday, Nov 8** +- Daily standup recorded +- Decision: Use PostgreSQL for auth + +**[Continue for each day]** + +📊 Week Summary: +- Meetings: 8 +- Stories completed: 5 +- Documents updated: 3 +- Milestones progressed: 1 +``` + +### Case 3: Topic/Theme search + +``` +User: "Find everything about database decisions" + +Process: +1. Full-text search for "database" +2. Focus on decisions/ directory +3. Also search meetings and docs +4. Cross-reference related content + +Result: +🔍 Search: "database" + +📋 Decisions (3): +- [001: Database Selection](decisions/001-database-choice.md) + PostgreSQL chosen for auth system (2025-10-15) + +- [005: Caching Strategy](decisions/005-caching.md) + Redis for session caching (2025-10-20) + +- [012: Migration Approach](decisions/012-database-migration.md) + Flyway for schema versioning (2025-11-01) + +📋 Meetings discussing database (4): +- Architecture Review (2025-10-15) +- Sprint 3 Planning (2025-10-16) +- Tech Spike Results (2025-10-19) +- Database Design Session (2025-10-22) + +📚 Related Documentation (2): +- Database Schema (docs/database-schema.md) +- Migration Guide (docs/migration-guide.md) + +🏃 Related Sprints: +- Sprint 3: Database setup and migration + +🔗 Cross-references: +All database decisions link to Sprint 3 and Beta Release milestone +``` + +### Case 4: Status-based search + +``` +User: "Show me all blocked items" + +Process: +1. Search sprints for status: blocked +2. Search milestones for status: delayed +3. Search meetings for blocker discussions + +Result: +⚠️ Blocked Items + +🏃 Sprints: +- Sprint 5, Story: OAuth Integration + Blocked: Waiting for third-party API credentials + Owner: @alice + Blocked since: 2025-11-10 + +📋 Meetings mentioning blockers: +- Daily Standup (2025-11-10) +- Daily Standup (2025-11-11) +- Daily Standup (2025-11-13) + +💡 Action needed: +- @alice: Follow up on API credentials +- Consider workaround or mock implementation +``` + +## Error Handling + +### Error: No RULE.md found + +``` +⚠️ No RULE.md found. + +Search will proceed with default project structure. + +Note: For best results, initialize project governance: +"Initialize project" +``` + +Proceed with search using standard directories. + +### Error: No results found + +``` +🔍 No results found for "{query}" + +Checked: +- ✓ Meetings +- ✓ Sprints +- ✓ Milestones +- ✓ Documentation +- ✓ Decisions + +Suggestions: +- Check spelling: "{query}" +- Try broader terms +- Try related searches: + * "{suggestion 1}" + * "{suggestion 2}" + +📋 Recent project activity: +[Show last 5 updates as alternatives] +``` + +### Error: Search too broad + +``` +ℹ️ Your search "{query}" returned {count} results. + +This may be too many to review effectively. + +Suggestions to narrow: +1. Add date range: "from last month" +2. Specify type: "only in meetings" +3. Add person filter: "by @name" +4. Add status: "completed only" + +Or continue with: +"Show top 10 results" +``` + +### Error: Invalid date range + +``` +⚠️ Could not parse date: "{date_input}" + +Supported formats: +- Specific: "2025-11-13" or "November 13, 2025" +- Relative: "last week", "last month", "yesterday" +- Range: "from Nov 1 to Nov 15" +- Quarter: "Q1", "Q2 2025" + +Please rephrase your date filter. +``` + +## Integration with Other Skills + +### With AkashicRecords search-content + +Both Skills can search same project: +- AkashicRecords: Knowledge base, articles, general content +- ProjectMaster: Project-specific content (meetings, sprints, milestones) + +If both exist, search both and merge results. + +### With track-meeting Skill + +Found meetings can be: +- Viewed in detail +- Updated +- Linked to other content + +### With manage-sprint Skill + +Found sprints can be: +- Updated with progress +- Viewed in detail +- Cross-referenced with milestones + +### With track-milestone Skill + +Found milestones can be: +- Updated with status +- Viewed with full dependencies +- Linked to contributing sprints + +## Best Practices + +### 1. Start with README indexes + +Fastest search method. Always try first. + +### 2. Use specific search terms + +Specific terms yield better results than generic ones. + +### 3. Add filters to narrow results + +Date ranges, content types, and person filters improve relevance. + +### 4. Follow cross-references + +Related content often provides fuller picture. + +### 5. Search by person for team insights + +Find what specific team members are working on or have created. + +### 6. Use date-based search for retrospectives + +"What did we do last sprint?" captures recent history. + +### 7. Search by milestone for big picture + +See all content contributing to major goals. + +### 8. Combine search strategies + +If one strategy fails, automatically try next. + +## Notes + +- Multi-strategy search ensures comprehensive results. +- README index search is fast and accurate for well-maintained projects. +- Full-text search is powerful but slower - use as fallback. +- Cross-reference search builds complete context around topics. +- Search results link to Skills that can act on found content. +- Person-based and date-based searches provide valuable team insights. + +--- + +Effective search transforms project content into accessible knowledge. This Skill makes finding information fast and intuitive. diff --git a/skills/track-meeting/SKILL.md b/skills/track-meeting/SKILL.md new file mode 100644 index 0000000..48fc1f0 --- /dev/null +++ b/skills/track-meeting/SKILL.md @@ -0,0 +1,900 @@ +--- +name: track-meeting +description: Create and manage structured meeting notes with automatic action item extraction and governance integration. Use when user mentions "meeting notes", "record meeting", "create meeting", "會議記錄", "standup", "retrospective", "planning", or any meeting-related keywords. +--- + +# Track Meeting Skill + +## When to use this Skill + +Activate when the user: +- Mentions creating or recording meeting notes +- Uses keywords: "meeting", "standup", "retrospective", "planning", "review", "會議" +- Wants to document a team discussion +- Needs to track meeting action items +- References specific meeting types (daily standup, sprint planning, etc.) + +## Workflow + +### Phase 1: Context Discovery + +**Objective**: Understand the project context and meeting format requirements. + +**Steps**: + +1. **Locate project RULE.md**: + ```bash + # Check current directory + ls RULE.md + # If not found, check parent directories + ls ../RULE.md + ls ../../RULE.md + ``` + +2. **Read RULE.md** using `Read` tool: + - Extract `methodology` field (determines meeting types) + - Find `Document Templates > Meeting Notes Format` section + - Note `file_naming_convention` pattern + - Check `meetings/` directory structure + - Read `Auto Workflows > When Claude creates meeting notes` section + +3. **Determine meeting types available** based on methodology: + - **Scrum**: daily-standups, sprint-planning, sprint-reviews, retrospectives, general + - **Kanban**: board-reviews, planning, general + - **Waterfall**: phase-reviews, status-updates, general + - **Agile/Hybrid**: planning, reviews, general + +4. **Check existing meetings directory**: + ```bash + ls -la meetings/ + ``` + Understand the current structure and recent meetings. + +5. **Read meetings/README.md** if exists: + - Understand current meeting index + - Note recent meetings for context + +**Example**: +``` +Found RULE.md: +- Methodology: Scrum (2-week sprints) +- Meeting types: daily-standups, sprint-planning, sprint-reviews, retrospectives +- Format: Structured with YAML frontmatter +- Naming: Date-prefixed (YYYY-MM-DD_meeting-name.md) +- Directory: meetings/{type}/ +``` + +### Phase 2: Gather Meeting Details + +**Objective**: Collect all necessary information about the meeting. + +**Steps**: + +1. **Extract from user message** (if provided): + - Meeting type (standup, planning, etc.) + - Date (today if not specified) + - Meeting title or topic + +2. **Prompt for missing information**: + + **Meeting type** (if not clear): + ``` + What type of meeting is this? + [Present options based on RULE.md methodology] + - Daily Standup + - Sprint Planning + - Sprint Review + - Retrospective + - General/Other + ``` + + **Meeting title** (if not provided): + ``` + What's the meeting title? + Example: "Sprint 5 Planning" or "Q4 Roadmap Discussion" + ``` + + **Date** (if not provided): + ``` + Meeting date? (Press Enter for today: YYYY-MM-DD) + ``` + + **Attendees**: + ``` + Who attended? (You can list names or reference team roles from RULE.md) + Example: "@alice @bob @carol" or "Whole dev team" + ``` + + **Duration** (optional): + ``` + How long was the meeting? (optional, in minutes) + ``` + +3. **Prepare meeting metadata**: + - Generate filename per RULE.md convention + - Determine target directory (e.g., `meetings/sprint-planning/`) + - Extract current date if not specified + - Default duration if not provided + +**Example**: +``` +Gathered: +- Type: Sprint Planning +- Title: "Sprint 5 Planning" +- Date: 2025-11-13 +- Attendees: Alice (PO), Bob (SM), Carol, David, Eve, Frank (devs) +- Duration: 90 minutes +- Filename: 2025-11-13_sprint-5-planning.md +- Target: meetings/sprint-planning/ +``` + +### Phase 3: Create Meeting Structure + +**Objective**: Generate the meeting note with proper template. + +**Steps**: + +1. **Read template from RULE.md**: + Extract the exact format from `Document Templates > Meeting Notes Format`. + +2. **Generate meeting document** following template: + + **For Structured format (most common)**: + ```markdown + --- + title: [Meeting Title] + type: [meeting-type] + date: YYYY-MM-DD + attendees: + - Name 1 + - Name 2 + duration_minutes: [number] + related_sprint: [sprint number or "N/A"] + related_milestone: [milestone or "N/A"] + --- + + # [Meeting Title] + + **Date**: YYYY-MM-DD + **Type**: [Type] + **Duration**: [X] minutes + + ## Attendees + - Name 1 + - Name 2 + + ## Agenda + [To be filled or pre-populated if provided] + + ## Discussion + [Meeting notes and key points] + + ## Action Items + [Will be extracted or added] + + ## Decisions + [Key decisions made during the meeting] + + ## Next Steps + [What happens next] + + --- + *Created by ProjectMaster track-meeting Skill* + ``` + + **For Simple format**: + ```markdown + # [Meeting Title] + + **Date**: YYYY-MM-DD + **Attendees**: Names + + ## Notes + [Content] + + ## Action Items + - [ ] Item 1 + - [ ] Item 2 + + ## Decisions + [Decisions] + ``` + + **For Table format**: + ```markdown + # [Meeting Title] + + | Field | Value | + |-------|-------| + | Date | YYYY-MM-DD | + | Type | [Type] | + | Attendees | Names | + | Duration | X mins | + + ## Discussion Points + + | Topic | Notes | Owner | + |-------|-------|-------| + | [Topic 1] | [Notes] | @name | + + ## Action Items + + | Task | Owner | Due Date | Status | + |------|-------|----------|--------| + | [Task] | @name | YYYY-MM-DD | [ ] | + ``` + +3. **Determine content source**: + + **If user provides content directly**: + - Fill template with provided information + - Parse for action items + - Extract decisions + + **If creating empty template**: + - Leave sections as prompts + - User will fill in later + + **If user provides partial information**: + - Fill what's available + - Mark sections for completion: `[To be filled]` + +### Phase 4: Action Item Extraction + +**Objective**: Automatically identify and format action items. + +**Steps**: + +1. **Scan user-provided content** for action items: + - Lines starting with "TODO", "Action:", "[ ]", "-[ ]" + - Phrases like "needs to", "should", "must", "will [do]" + - @mentions indicating assignments + - Date mentions indicating deadlines + +2. **Extract action items**: + ``` + Pattern detection: + - "Bob will update the database schema" → @bob: Update database schema + - "TODO: Review PR #123" → Review PR #123 + - "Alice needs to finalize designs by Friday" → @alice: Finalize designs - due: [next Friday] + ``` + +3. **Format as task list**: + ```markdown + ## Action Items + - [ ] [Task description] - @[owner] - due: YYYY-MM-DD + - [ ] [Task description] - @[owner] - due: YYYY-MM-DD + ``` + + **If no owner specified**: Leave as `- [ ] [Task]` + **If no due date**: Omit due date or use "TBD" + +4. **Ask user to confirm/modify** action items: + ``` + I've extracted these action items: + 1. @bob: Update database schema - due: 2025-11-20 + 2. @alice: Finalize designs - due: 2025-11-15 + 3. Review PR #123 - no owner assigned + + Are these correct? Any additions or changes? + ``` + +5. **Update based on feedback**. + +### Phase 5: Cross-Reference Linking + +**Objective**: Link meeting to related project artifacts. + +**Steps**: + +1. **Identify related items** from meeting content: + - Sprint numbers (e.g., "Sprint 5") + - Milestone names + - Issue numbers (#123) + - Document references + - Previous meeting references + +2. **Check if items exist**: + ```bash + # For sprint reference + ls sprints/sprint-05/ + # For milestone + grep "milestone-name" milestones.yaml + # For previous meetings + ls meetings/*/YYYY-MM-DD*.md + ``` + +3. **Add links to metadata**: + ```yaml + --- + related_sprint: sprint-05 + related_milestone: beta-release + related_issues: [123, 456] + related_docs: [docs/architecture.md] + related_meetings: [meetings/sprint-planning/2025-11-06_sprint-4-planning.md] + --- + ``` + +4. **Add links in content** (if appropriate): + ```markdown + ## Context + This meeting is for [Sprint 5](../../sprints/sprint-05/sprint-plan.md) planning. + + Related to [Beta Release](../../milestones.yaml#beta-release) milestone. + + Follow-up from [previous retrospective](../retrospectives/2025-11-06_sprint-4-retro.md). + ``` + +### Phase 6: Create and Save Meeting Note + +**Objective**: Write the meeting note to the correct location. + +**Steps**: + +1. **Determine full file path**: + ``` + meetings/[meeting-type]/[filename].md + Example: meetings/sprint-planning/2025-11-13_sprint-5-planning.md + ``` + +2. **Ensure target directory exists**: + ```bash + mkdir -p meetings/[meeting-type] + ``` + +3. **Write file** using `Write` tool: + - Use complete path + - Include all generated content + - Ensure proper formatting + +4. **Verify creation**: + ```bash + ls -la meetings/[meeting-type]/[filename].md + ``` + +**Example output**: +``` +✅ Created: meetings/sprint-planning/2025-11-13_sprint-5-planning.md +``` + +### Phase 7: Governance Update + +**Objective**: Maintain README.md indexes per governance protocol. + +**Steps**: + +1. **Update meetings/README.md**: + + Read current content: + ```bash + Read meetings/README.md + ``` + + Add new meeting to index: + ```markdown + ## Recent Meetings + + ### Sprint Planning + - [2025-11-13: Sprint 5 Planning](sprint-planning/2025-11-13_sprint-5-planning.md) - Planned authentication features (Last updated: 2025-11-13) + - [2025-10-30: Sprint 4 Planning](sprint-planning/2025-10-30_sprint-4-planning.md) - ... (Last updated: 2025-10-30) + + [Keep sorted by date, most recent first] + ``` + + Update last modified date: + ```markdown + --- + Last updated: 2025-11-13 + ``` + +2. **Update meetings/[type]/README.md** (if exists): + + Add to category-specific index: + ```markdown + # Sprint Planning Meetings + + ## Meetings + + - [2025-11-13: Sprint 5 Planning](2025-11-13_sprint-5-planning.md) - Description + - [Previous meetings...] + + --- + Last updated: 2025-11-13 + ``` + +3. **Update project root README.md**: + + Add to Recent Activity: + ```markdown + ## Recent Activity + + - 2025-11-13: Sprint 5 Planning meeting notes added + - [Previous activities...] + ``` + + Update last modified: + ```markdown + --- + Last updated: 2025-11-13 + ``` + +4. **Execute custom workflows** from RULE.md: + + Read `Auto Workflows > When Claude creates meeting notes`: + ```markdown + ## When Claude creates meeting notes: + 1. Extract all action items with @mentions + 2. Update team member task lists + 3. Link to related user stories if mentioned + 4. Add to README.md meeting index + 5. [Custom step specific to this project] + ``` + + Execute each specified step. + +### Phase 8: Report + +**Objective**: Confirm completion and guide next steps. + +**Report format**: + +``` +✅ Meeting Notes Created Successfully! + +📄 File: meetings/[type]/[filename].md +📅 Date: YYYY-MM-DD +👥 Attendees: [count] people +⏱️ Duration: [X] minutes + +📋 Action Items: [count] +[List action items with owners] + +🔗 Linked to: +- Sprint [X] +- Milestone: [name] +- Issues: #[numbers] + +📚 Updated governance: +✓ meetings/README.md +✓ meetings/[type]/README.md +✓ Project README.md + +💡 Next steps: +- Review action items with team +- Track action item completion +- Link to sprint/milestone if not already done + +[If action items with owners exist:] +Reminder to notify: +- @[owner1] about [task] +- @[owner2] about [task] + +[If custom workflows were executed:] +🤖 Executed custom workflows from RULE.md: +- [Workflow description] +``` + +## Special Cases + +### Case 1: Quick standup notes + +If user provides brief standup update: + +``` +User: "Today's standup: Everyone on track, Bob blocked on API issue, Alice will help" +``` + +**Response**: +1. Detect it's a standup (keyword "standup") +2. Create minimal standup format: + ```markdown + --- + title: Daily Standup + type: standup + date: 2025-11-13 + --- + + # Daily Standup - 2025-11-13 + + ## Updates + - Team on track + - Bob: Blocked on API issue + - Alice: Will assist Bob + + ## Action Items + - [ ] Alice: Help Bob with API issue + ``` + +3. Save with date-based filename: `2025-11-13_standup.md` +4. Update governance +5. Report: "Standup notes recorded. Alice assigned to help Bob." + +### Case 2: Retrospective with structured feedback + +For retrospectives, use special format: + +```markdown +# Sprint [X] Retrospective + +## What Went Well 🎉 +- Item 1 +- Item 2 + +## What Could Be Improved 🔧 +- Item 1 +- Item 2 + +## Action Items for Next Sprint +- [ ] Action 1 - @owner +- [ ] Action 2 - @owner + +## Appreciation 💙 +- Shoutout to @person for [accomplishment] + +## Metrics +- Velocity: [X] points +- Completed: [X]/[Y] stories +- Sprint goal: [Met/Partially Met/Not Met] +``` + +### Case 3: Meeting notes from transcript + +If user provides meeting transcript or long notes: + +1. **Parse content** to extract: + - Speakers and what they said + - Key decisions + - Action items (look for commitments, assignments) + - Questions and answers + +2. **Structure into sections**: + - Discussion (organized by topic if possible) + - Decisions (extract conclusions) + - Action Items (extract commitments) + +3. **Confirm with user**: + "I've structured the transcript. Here are the key points and action items I extracted. Please review..." + +### Case 4: Meeting series + +If user is creating recurring meeting notes: + +1. **Detect series** (e.g., "weekly standup", "daily standup"): + - Check for existing notes with similar titles + - Note pattern in governance + +2. **Use consistent naming**: + - Daily standups: `YYYY-MM-DD_standup.md` + - Weekly meetings: `YYYY-MM-DD_weekly-sync.md` + +3. **Link to previous**: + ```markdown + ## Previous Meeting + [Last week's sync](2025-11-06_weekly-sync.md) + + ## Follow-up on Previous Action Items + - [X] Item from last week - completed + - [ ] Item from last week - in progress + ``` + +### Case 5: Emergency or incident meetings + +For urgent meetings about incidents: + +1. **Use incident template** (if defined in RULE.md): + ```markdown + --- + title: [Incident Title] + type: incident + severity: [high|critical] + date: YYYY-MM-DD HH:MM + --- + + # Incident: [Title] + + ## Timeline + - HH:MM - Incident detected + - HH:MM - Team notified + - HH:MM - Root cause identified + - HH:MM - Fix deployed + - HH:MM - Incident resolved + + ## Impact + [Description of impact] + + ## Root Cause + [What caused the incident] + + ## Resolution + [How it was fixed] + + ## Action Items + - [ ] Prevent recurrence: [task] + - [ ] Post-mortem: [task] + ``` + +## Error Handling + +### Error: RULE.md not found + +**Response**: +``` +⚠️ No RULE.md found in this directory or parent directories. + +This appears to not be a ProjectMaster-initialized project. + +Options: +1. Initialize project first: "Initialize a new project for [name]" +2. Create meeting note with default format (no governance) +3. Specify a different directory + +What would you like to do? +``` + +If user chooses option 2, use default structured format. + +### Error: meetings/ directory doesn't exist + +**Response**: +``` +⚠️ No meetings/ directory found. + +I'll create it now with proper governance structure. +``` + +Then: +```bash +mkdir -p meetings/ +echo "[README.md content]" > meetings/README.md +``` + +Proceed with meeting creation. + +### Error: Invalid meeting type + +If user specifies a meeting type not in RULE.md: + +**Response**: +``` +⚠️ Meeting type "[type]" not recognized for this project. + +Available types based on your RULE.md: +- [type1] +- [type2] +- [type3] + +Would you like to: +1. Use one of the available types +2. Create as "General" meeting +3. Add "[type]" to RULE.md as a new meeting type + +Which option? +``` + +### Error: Filename conflict + +If filename already exists: + +**Response**: +``` +⚠️ A meeting note already exists with this name: +meetings/[type]/[filename].md + +Options: +1. Create with different name (e.g., append "-v2") +2. Update/append to existing note +3. Cancel creation + +What would you like to do? +``` + +## Integration with Other Skills + +### With manage-sprint Skill + +If meeting is sprint-related (planning, review, retrospective): + +1. **Check for current sprint**: + ```bash + ls sprints/current/ + ``` + +2. **Link meeting to sprint**: + ```yaml + related_sprint: sprint-05 + ``` + +3. **Update sprint documentation**: + Add reference in `sprints/sprint-05/sprint-plan.md`: + ```markdown + ## Meetings + - [Planning](../../meetings/sprint-planning/2025-11-13_sprint-5-planning.md) + ``` + +### With track-milestone Skill + +If meeting discusses milestone: + +1. **Extract milestone mentions** from content +2. **Link in metadata**: + ```yaml + related_milestone: beta-release + ``` + +3. **Update milestone notes**: + If milestones.yaml supports notes: + ```yaml + notes: "Discussed in meeting: meetings/planning/2025-11-13_sprint-5-planning.md" + ``` + +### With AkashicRecords Skills + +If user wants to reference knowledge base articles in meeting: + +1. **Detect article mentions** (URLs, document names) +2. **Use search-content** to locate articles +3. **Link in meeting notes**: + ```markdown + ## References + - [Architecture Decision 001](../../decisions/001-database-choice.md) + - [API Documentation](../../knowledge/api-docs.md) + ``` + +## Best Practices + +### 1. Always read RULE.md first + +Meeting format varies by team. Read RULE.md before creating to ensure compliance. + +### 2. Extract action items automatically + +Look for tasks, assignments, and commitments. Parse them into structured format. + +### 3. Link generously + +Connect meetings to sprints, milestones, decisions, and other meetings. Rich linking improves navigability. + +### 4. Maintain consistent naming + +Follow RULE.md naming convention exactly. Consistency enables better searching and sorting. + +### 5. Update governance immediately + +Don't defer README.md updates. Do them as part of meeting creation. + +### 6. Confirm action items with user + +Automatic extraction may miss context. Always confirm extracted action items. + +### 7. Use appropriate granularity + +Daily standups: Brief, minimal format +Sprint planning: Detailed, comprehensive format +Retrospectives: Structured sections (what went well, what to improve) + +### 8. Preserve formatting + +If user provides formatted content, preserve structure while adding governance elements. + +## Examples + +### Example 1: Sprint Planning Meeting + +``` +User: I need to create notes for our sprint 5 planning meeting + +Claude: I'll create sprint planning notes. Let me gather details... + +Meeting title? (e.g., "Sprint 5 Planning") + +User: Sprint 5 Planning + +Claude: Great! Attendees? + +User: Whole team - Alice (PO), Bob (SM), Carol, David, Eve, Frank (devs) + +Claude: How long was the meeting? + +User: About 90 minutes + +Claude: Perfect! Any content to include, or should I create a template for you to fill? + +User: Create template, but add that we're focusing on authentication features + +Claude: Got it! Creating structured sprint planning notes... + +✅ Created: meetings/sprint-planning/2025-11-13_sprint-5-planning.md + +📄 Structured template with: +- Sprint goal: Authentication features +- Sections for user stories, estimates, assignments +- Action items section +- Links to Sprint 5 documentation + +📚 Updated: +✓ meetings/README.md +✓ meetings/sprint-planning/README.md +✓ Project README.md +✓ sprints/sprint-05/sprint-plan.md (added planning meeting link) + +You can now edit the file to add detailed notes, user stories, and estimates. +``` + +### Example 2: Quick Daily Standup + +``` +User: Today's standup: Carol finished user signup, David starting login, Eve blocked on OAuth config, Bob will help Eve + +Claude: Recording daily standup... + +✅ Created: meetings/daily-standups/2025-11-13_standup.md + +📋 Summary: +- Carol: Completed user signup ✓ +- David: Starting login feature +- Eve: Blocked on OAuth configuration +- Bob: Will assist Eve + +Action Items: +- [ ] Bob: Help Eve with OAuth configuration + +📚 Governance updated + +💡 Reminder: Bob to assist Eve with OAuth blocker +``` + +### Example 3: Retrospective + +``` +User: Create retro notes for sprint 4 + +Claude: I'll create a Sprint 4 retrospective note. Let me use the retrospective template... + +What went well in Sprint 4? + +User: We delivered all planned features, team collaboration was great, no major bugs + +Claude: What could be improved? + +User: Estimations were off, needed better testing before review + +Claude: Any specific action items for next sprint? + +User: Allocate more time for testing, involve QA earlier, re-calibrate story points + +Claude: Creating retrospective... + +✅ Created: meetings/retrospectives/2025-11-13_sprint-4-retro.md + +📊 Sprint 4 Retrospective: + +🎉 What Went Well: +- Delivered all planned features +- Strong team collaboration +- No major bugs + +🔧 What Could Be Improved: +- Estimation accuracy +- Testing workflow timing + +📋 Action Items for Sprint 5: +- [ ] Allocate dedicated testing time in sprint planning +- [ ] Involve QA from story refinement stage +- [ ] Re-calibrate story point estimates based on Sprint 4 actuals + +📚 Updated governance and linked to Sprint 4 documentation + +💡 These action items will be tracked in Sprint 5 planning. +``` + +## Notes + +- Meeting notes are the heartbeat of project communication. Rich, structured notes enable better async collaboration. +- Action item extraction is intelligent but not perfect. Always review and confirm. +- Cross-referencing meetings to sprints, milestones, and decisions creates a knowledge graph that's easy to navigate. +- The RULE.md-defined format ensures consistency across the team without imposing rigid templates. +- This Skill adapts to your team's actual workflow - Scrum, Kanban, Waterfall, or hybrid. + +--- + +Effective meeting notes transform ephemeral discussions into persistent project knowledge. This Skill makes that transformation automatic. diff --git a/skills/track-milestone/SKILL.md b/skills/track-milestone/SKILL.md new file mode 100644 index 0000000..9c9b011 --- /dev/null +++ b/skills/track-milestone/SKILL.md @@ -0,0 +1,640 @@ +--- +name: track-milestone +description: Track and manage project milestones, deliverables, and deadlines. Use when user mentions "milestone", "deadline", "deliverable", "release", "target date", or wants to track major project achievements and dependencies between milestones. +--- + +# Track Milestone Skill + +## When to use this Skill + +Activate when the user: +- Mentions creating, updating, or checking milestones +- Uses keywords: "milestone", "deadline", "deliverable", "release", "target", "due date" +- Wants to track major project achievements +- References project timeline or roadmap +- Needs to manage milestone dependencies +- Wants to see progress toward goals + +## Workflow + +### Phase 1: Context Discovery & Intent Recognition + +**Objective**: Understand project structure and user's specific milestone intent. + +**Steps**: + +1. **Locate project RULE.md** and **milestones.yaml**: + ```bash + ls RULE.md milestones.yaml + ``` + +2. **Read both files**: + - RULE.md: Project methodology, milestone tracking preferences + - milestones.yaml: Existing milestones and structure + +3. **Detect user intent**: + - **Create milestone**: "create milestone", "add milestone", "new milestone" + - **Update milestone**: "update milestone", "milestone progress", "mark complete" + - **Check status**: "milestone status", "show milestones", "timeline" + - **Manage dependencies**: "milestone depends on", "blocking milestone" + +4. **Route to appropriate workflow**: + - Create → Workflow A + - Update → Workflow B + - Status → Workflow C + - Dependencies → Workflow D + +### Workflow A: Create Milestone + +**Objective**: Add a new milestone to the project timeline. + +**Steps**: + +1. **Gather milestone details**: + + **Name**: + ``` + Milestone name? + Example: "Beta Release", "MVP Launch", "Security Audit Complete" + ``` + + **Description**: + ``` + Brief description of what this milestone represents? + ``` + + **Target date**: + ``` + Target completion date? (YYYY-MM-DD or relative like "end of Q2") + ``` + + **Deliverables**: + ``` + What needs to be delivered for this milestone? + - Deliverable 1 + - Deliverable 2 + ``` + + **Owner** (optional): + ``` + Who's responsible for this milestone? (@name or "Team") + ``` + + **Dependencies** (optional): + ``` + Does this milestone depend on any other milestones? + Example: "After Alpha Release" or "After milestones 1 and 2" + ``` + + **Related sprints/phases** (optional): + ``` + Which sprints/phases contribute to this milestone? + ``` + +2. **Generate milestone ID**: + ``` + milestone-{number} or {name-slug} + Example: milestone-1 or beta-release + ``` + +3. **Read current milestones.yaml**: + ``` + Read milestones.yaml + ``` + +4. **Add new milestone entry**: + ```yaml + milestones: + - id: {milestone-id} + name: "{Milestone Name}" + description: "{Description}" + target_date: YYYY-MM-DD + actual_date: null + status: planned + dependencies: [{dependent-milestone-ids}] + deliverables: + - Deliverable 1 + - Deliverable 2 + owner: "@{name}" + related_sprints: [{sprint-numbers}] + completion_criteria: + - Criterion 1 + - Criterion 2 + notes: "" + ``` + +5. **Validate dependencies**: + - Check that referenced milestones exist + - Detect circular dependencies + - Warn if dependency order seems wrong + +6. **Update milestones.yaml** using Edit tool: + ``` + Edit milestones.yaml + Add new milestone entry in appropriate location (sorted by target date) + ``` + +7. **Update governance**: + - Update project README.md (add to timeline section) + - Add "Recent Activity" entry + - Link to related sprints if applicable + +8. **Report creation**: + ``` + ✅ Milestone Created! + + 🎯 {Milestone Name} + 📅 Target: {target_date} + 📦 Deliverables: {count} + 👤 Owner: @{name} + + [If dependencies:] + 🔗 Dependencies: + - {Dependent milestone names} + + [If related sprints:] + 🏃 Related Sprints: {sprint numbers} + + 📄 Added to: milestones.yaml + + 💡 Track progress with: + "Update milestone {name}" + "Milestone status" + ``` + +### Workflow B: Update Milestone + +**Objective**: Update milestone status, progress, or completion. + +**Steps**: + +1. **Identify target milestone**: + - Extract name/ID from user message + - Or ask: "Which milestone?" + +2. **Read milestones.yaml**: + ``` + Read milestones.yaml + Find milestone entry + ``` + +3. **Determine update type**: + - **Status change**: planned → in_progress → completed → delayed + - **Progress update**: Update notes or deliverables status + - **Date change**: Update target or actual date + - **Completion**: Mark as completed with date + +4. **Execute update**: + + **For status change**: + ```yaml + status: {new_status} + ``` + + **For completion**: + ```yaml + status: completed + actual_date: {YYYY-MM-DD} + ``` + + **For progress/notes**: + ```yaml + notes: "{Updated notes about progress}" + ``` + + **For deliverable tracking**: + ```yaml + deliverables: + - [X] Deliverable 1 (completed) + - [ ] Deliverable 2 (in progress) + ``` + +5. **Check impact**: + - **If milestone completed**: Check dependent milestones (can they start?) + - **If milestone delayed**: Check impacted milestones (cascade delays?) + +6. **Update milestones.yaml** using Edit tool + +7. **Generate milestone report** (if completed): + ```markdown + # Milestone Completion Report: {Milestone Name} + + **Completed**: {actual_date} + **Target**: {target_date} ({"On Time" | "Early" | "Delayed by X days"}) + + ## Deliverables + - [X] Deliverable 1 + - [X] Deliverable 2 + + ## Contributing Sprints + - Sprint {X} + - Sprint {Y} + + ## Metrics + - Duration: {calculation} + - Team: {involved team members} + - Key Achievements: {summary} + + ## Impact + - Enabled milestones: {dependent milestones} + - Next milestone: {next in timeline} + + ## Lessons Learned + {Notes from milestone execution} + + --- + Generated: {YYYY-MM-DD} by ProjectMaster + ``` + +8. **Save report** (if generated): + ``` + Write to: reports/milestone-{id}-completion.md + ``` + +9. **Update governance**: + - Update project README.md + - Add Recent Activity entry + - Link report to milestone in yaml + +10. **Report update**: + ``` + ✅ Milestone Updated! + + 🎯 {Milestone Name} + 📊 Status: {old_status} → {new_status} + + [If completed:] + 🎉 Milestone Completed! + 📅 Completed: {actual_date} ({on_time_status}) + 📦 Deliverables: All {count} delivered + 📄 Report: reports/milestone-{id}-completion.md + + 🔓 Unblocked Milestones: + - {Dependent milestone names} + + 💡 Next Milestone: {Next in timeline} + + [If delayed:] + ⚠️ Milestone Delayed + 📅 Was: {original_target} → Now: {new_target} + ⚠️ Impacted Milestones: + - {Affected milestones} + + 📄 Updated: milestones.yaml + ``` + +### Workflow C: Status Report + +**Objective**: Show project milestone status and timeline. + +**Steps**: + +1. **Read milestones.yaml**: + ``` + Read milestones.yaml + Parse all milestones + ``` + +2. **Categorize milestones**: + - Completed + - In Progress + - Planned + - Delayed/At Risk + +3. **Calculate metrics**: + - Total milestones + - Completion rate + - On-time rate + - Average delay (if any) + - Next milestone due date + +4. **Check dependencies**: + - Any blocked milestones? + - Ready to start milestones? + +5. **Generate status report**: + ``` + 📊 Project Milestone Status + + **Project**: {Project Name} + **Total Milestones**: {count} + **Completed**: {X}/{total} ({percentage}%) + **On Track**: {Y} + **At Risk**: {Z} + + 🎉 Completed Milestones: + ✅ {Milestone 1} - {actual_date} ({"On Time" | "Early" | "Delayed"}) + ✅ {Milestone 2} - {actual_date} + ... + + 🔄 In Progress: + - {Milestone Name} - Target: {target_date} ({days_remaining} days) + Status: {On Track | At Risk} + Progress: {notes or deliverables status} + + 📅 Upcoming: + - {Milestone Name} - Target: {target_date} ({days_until} days) + [If blocked:] ⚠️ Blocked by: {dependency names} + + ⚠️ Delayed: + - {Milestone Name} - Was: {original} Now: {revised} + Delay: {days} days + Impact: {affected milestones} + + 📈 Timeline Health: {Overall Assessment} + [If at risk:] ⚠️ {count} milestones at risk of delay + + 🎯 Next Milestone: {Name} - {target_date} ({days_remaining} days) + + 📄 Full timeline: milestones.yaml + ``` + +6. **Include visual timeline** (text-based): + ``` + 📅 Timeline: + + Q1 2025 + ├── [✅] Alpha Release (2025-02-15) ← Completed + └── [🔄] Beta Release (2025-03-31) ← In Progress + + Q2 2025 + ├── [📅] Public Launch (2025-04-30) + └── [⏸️] Feature Freeze (2025-05-15) ← Blocked by Beta + + Q3 2025 + └── [📅] 1.0 Release (2025-07-31) + ``` + +### Workflow D: Manage Dependencies + +**Objective**: Define or update milestone dependencies. + +**Steps**: + +1. **Identify milestones involved**: + - Primary milestone + - Dependent milestone(s) + +2. **Read milestones.yaml** + +3. **Update dependency**: + + **Adding dependency**: + ```yaml + milestones: + - id: milestone-2 + dependencies: [milestone-1] # milestone-2 depends on milestone-1 + ``` + + **Removing dependency**: + ```yaml + dependencies: [] # or remove the dependency from list + ``` + +4. **Validate**: + - Check for circular dependencies + - Verify dependency exists + - Check timeline logic (dependent milestone should be after dependency) + +5. **Update milestones.yaml** + +6. **Report**: + ``` + ✅ Dependency Updated! + + 🎯 {Milestone Name} + 🔗 Now depends on: + - {Dependency 1} + - {Dependency 2} + + ⚠️ {Milestone Name} cannot start until dependencies complete. + + [If circular dependency detected:] + ❌ Error: Circular dependency detected! + {Milestone A} → {Milestone B} → {Milestone A} + Please review dependencies. + + [If timeline conflict:] + ⚠️ Warning: {Milestone Name} target ({date1}) is before + dependency {Dependency Name} target ({date2}). + Consider adjusting dates. + ``` + +## Special Cases + +### Case 1: Milestone with multiple dependencies + +```yaml +milestones: + - id: public-launch + name: "Public Launch" + dependencies: [beta-complete, security-audit, marketing-ready] + status: planned +``` + +Report readiness: +``` +🎯 Public Launch Readiness: + +Dependencies: +✅ Beta Complete (2025-03-15) ← Done +✅ Security Audit (2025-03-20) ← Done +🔄 Marketing Ready (2025-04-01) ← In Progress (90%) + +Status: Waiting on 1 dependency +Can start: After 2025-04-01 +``` + +### Case 2: Milestone delayed - cascade impact + +If milestone delayed, check cascade: + +``` +⚠️ Milestone Delay Impact Analysis + +{Delayed Milestone} delayed from {old_date} to {new_date} + +Directly Impacted: +- {Milestone A} (depends on this) - May delay +- {Milestone B} (depends on this) - May delay + +Cascade Impact: +- {Milestone C} (depends on Milestone A) - Potential delay +- {Milestone D} (depends on Milestone B) - Potential delay + +Recommendation: +Review timeline for {count} affected milestones. +Consider: +1. Adjusting target dates +2. Removing dependencies if possible +3. Allocating more resources +``` + +### Case 3: Sprint-to-milestone tracking + +Link sprints to milestone progress: + +```markdown +## Milestone: Beta Release + +**Target**: 2025-03-31 +**Status**: In Progress (75%) + +### Contributing Sprints: +- Sprint 3: User Authentication ✅ Complete +- Sprint 4: Profile Management ✅ Complete +- Sprint 5: Settings & Preferences 🔄 In Progress (Day 8/14) +- Sprint 6: Final Polish 📅 Planned + +### Deliverables Status: +- [X] Core Features (Sprints 3-4) +- [🔄] Additional Features (Sprint 5) - 80% complete +- [ ] Bug Fixes & Polish (Sprint 6) + +**Progress**: 75% (3 of 4 sprints complete) +**On Track**: Yes, 2 weeks remaining +``` + +### Case 4: Milestone-based releases + +For release milestones, include version info: + +```yaml +milestones: + - id: v1-0-release + name: "Version 1.0 Release" + type: release + version: "1.0.0" + target_date: 2025-07-31 + release_notes: "reports/v1.0-release-notes.md" + deliverables: + - All MVP features complete + - Security audit passed + - Documentation published + - Marketing materials ready +``` + +## Error Handling + +### Error: milestones.yaml not found + +``` +⚠️ No milestones.yaml found. + +This project hasn't initialized milestone tracking. + +Options: +1. Create milestones.yaml now +2. Initialize project with: "Initialize project" +3. Cancel + +What would you like to do? +``` + +If user chooses 1, create template milestones.yaml. + +### Error: Invalid date format + +``` +⚠️ Invalid date format: "{input}" + +Please use YYYY-MM-DD format. +Example: 2025-12-31 + +Or relative dates: +- "end of Q2" → 2025-06-30 +- "next month" → 2025-12-01 +``` + +### Error: Circular dependency + +``` +❌ Cannot create dependency: Circular reference detected! + +Dependency chain: +{Milestone A} → {Milestone B} → {Milestone C} → {Milestone A} + +Please remove one dependency to break the cycle. +``` + +### Error: Milestone not found + +``` +⚠️ Milestone "{name}" not found in milestones.yaml. + +Available milestones: +- {Milestone 1} +- {Milestone 2} +- {Milestone 3} + +Did you mean one of these? +``` + +## Integration with Other Skills + +### With manage-sprint Skill + +Sprints contribute to milestones: +- Link sprints to milestones in metadata +- Update milestone progress when sprint completes +- Show milestone context in sprint planning + +### With track-meeting Skill + +Milestone reviews create meetings: +- Milestone completion meeting +- Milestone checkpoint meeting +- Link meeting notes to milestone + +### With AkashicRecords + +Milestone artifacts: +- Decision records leading to milestone +- Documentation created for milestone +- Knowledge captured during milestone work + +## Best Practices + +### 1. Define clear deliverables + +Each milestone should have specific, measurable deliverables. + +### 2. Set realistic dates + +Use team velocity and sprint history to set achievable targets. + +### 3. Track dependencies explicitly + +Don't assume implicit dependencies - document them. + +### 4. Review timeline regularly + +Monthly or per-sprint review of milestone status keeps project on track. + +### 5. Celebrate completions + +Acknowledge milestone achievements with team. + +### 6. Learn from delays + +Document reasons for delays to improve future planning. + +### 7. Link to work items + +Connect milestones to sprints, stories, and tasks for full traceability. + +### 8. Update proactively + +Update milestone status before it becomes "delayed". + +## Notes + +- Milestones provide high-level project visibility for stakeholders. +- Dependency tracking prevents surprises and enables proactive planning. +- Milestone completion reports create valuable project history. +- Integration with sprints connects strategy (milestones) with execution (sprints). +- The milestones.yaml becomes the project timeline source of truth. + +--- + +Well-managed milestones turn long-term goals into achievable checkpoints. This Skill makes milestone tracking systematic and insightful.