@prmichaelsen/task-mcp 0.2.0

package/agent/commands/acp.report.md

@@ -0,0 +1,392 @@
+# Command: report
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.report` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+
+---
+
+**Purpose**: Generate a comprehensive project status report including progress, accomplishments, and next steps
+**Category**: Documentation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command generates a comprehensive markdown report summarizing the project's current status, progress, accomplishments, and plans. It reads all ACP documentation and creates a formatted report suitable for sharing with stakeholders, team members, or for project records.
+
+Use this command when you need to communicate project status, before milestone reviews, for weekly/monthly updates, or when onboarding new team members. The report provides a complete snapshot of the project at a point in time.
+
+Unlike `@acp.status` which provides a quick console summary, `@acp.report` generates a detailed markdown document that can be saved, shared, or archived.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists and is current
+- [ ] Documentation exists in `agent/` directory
+
+---
+
+## Steps
+
+### 1. Read Project Information
+
+Load basic project details from progress.yaml.
+
+**Actions**:
+- Read `agent/progress.yaml`
+- Extract project name, version, start date
+- Note current status and milestone
+- Get project description
+
+**Expected Outcome**: Project basics loaded
+
+### 2. Gather Milestone Information
+
+Collect data about all milestones.
+
+**Actions**:
+- Read all milestone documents
+- Extract milestone goals and deliverables
+- Note progress percentages
+- Identify completed vs in-progress vs not-started
+- Calculate overall project progress
+
+**Expected Outcome**: Milestone data collected
+
+### 3. Gather Task Information
+
+Collect data about all tasks.
+
+**Actions**:
+- Read task data from progress.yaml
+- Count total tasks, completed, in-progress
+- Calculate completion percentages
+- Identify current task
+- Note any blocked tasks
+
+**Expected Outcome**: Task data collected
+
+### 4. Summarize Recent Work
+
+Extract recent accomplishments.
+
+**Actions**:
+- Read recent_work from progress.yaml
+- Format accomplishments by date
+- Highlight major achievements
+- Note any significant milestones reached
+
+**Expected Outcome**: Recent work summarized
+
+### 5. Identify Next Steps
+
+Extract and prioritize next steps.
+
+**Actions**:
+- Read next_steps from progress.yaml
+- Read current task for immediate next steps
+- Identify upcoming milestones
+- Note any dependencies
+
+**Expected Outcome**: Next steps identified
+
+### 6. Document Blockers and Risks
+
+List current blockers and risks.
+
+**Actions**:
+- Read current_blockers from progress.yaml
+- Note any risks mentioned in milestone docs
+- Identify dependencies on external factors
+- Assess impact of blockers
+
+**Expected Outcome**: Blockers documented
+
+### 7. Generate Statistics
+
+Calculate project metrics.
+
+**Actions**:
+- Total milestones and completion rate
+- Total tasks and completion rate
+- Overall project progress percentage
+- Time elapsed since project start
+- Estimated time remaining (if available)
+- Documentation count (design docs, patterns, etc.)
+
+**Expected Outcome**: Metrics calculated
+
+### 8. Format Report
+
+Create formatted markdown report.
+
+**Actions**:
+- Create report header with project info
+- Add executive summary
+- Include progress section with charts/percentages
+- List milestones with status
+- Summarize recent accomplishments
+- Document next steps
+- List blockers and risks
+- Include statistics
+- Add footer with generation date
+
+**Expected Outcome**: Report formatted
+
+### 9. Save Report
+
+Write report to file.
+
+**Actions**:
+- Generate filename with date (e.g., `report-2026-02-16.md`)
+- Save to `agent/reports/` directory (create if needed)
+- Confirm file written successfully
+- Display report location
+
+**Expected Outcome**: Report saved
+
+---
+
+## Verification
+
+- [ ] Project information extracted
+- [ ] Milestone data collected
+- [ ] Task data collected
+- [ ] Recent work summarized
+- [ ] Next steps identified
+- [ ] Blockers documented
+- [ ] Statistics calculated
+- [ ] Report formatted as markdown
+- [ ] Report saved to file
+- [ ] Report location displayed
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/reports/report-YYYY-MM-DD.md` - Generated report file
+
+### Console Output
+```
+📊 Generating Project Report
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Gathering project information...
+✓ Project: agent-context-protocol v1.1.0
+✓ Started: 2026-02-16
+✓ Current milestone: M2
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Collecting milestone data...
+✓ Milestone 1: Complete (100%)
+✓ Milestone 2: In Progress (60%)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Analyzing tasks...
+✓ Total tasks: 7
+✓ Completed: 5 (71%)
+✓ In progress: 1
+✓ Not started: 1
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Calculating statistics...
+✓ Overall progress: 75%
+✓ Documentation: 8 design docs, 3 patterns
+✓ Commands: 11 implemented
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Formatting report...
+✓ Report generated (2,500 words)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Report Complete!
+
+Saved to: agent/reports/report-2026-02-16.md
+
+Summary:
+- Overall progress: 75%
+- Milestones: 1 complete, 1 in progress
+- Tasks: 5/7 complete
+- Blockers: 0
+```
+
+### Report Structure
+```markdown
+# Project Status Report
+## agent-context-protocol
+
+**Generated**: 2026-02-16
+**Version**: 1.1.0
+**Status**: In Progress
+
+---
+
+## Executive Summary
+
+[2-3 paragraph summary of project status]
+
+---
+
+## Progress Overview
+
+**Overall Progress**: 75%
+
+### Milestones
+- ✅ Milestone 1: ACP Commands Infrastructure (100%)
+- 🔄 Milestone 2: Documentation & Utility Commands (60%)
+
+### Tasks
+- Total: 7
+- Completed: 5 (71%)
+- In Progress: 1
+- Not Started: 1
+
+---
+
+## Recent Accomplishments
+
+[List of recent work with dates]
+
+---
+
+## Next Steps
+
+[Prioritized list of next steps]
+
+---
+
+## Current Blockers
+
+[List of blockers, or "None"]
+
+---
+
+## Statistics
+
+[Detailed metrics and counts]
+
+---
+
+**Report generated by ACP v1.1.0**
+```
+
+---
+
+## Examples
+
+### Example 1: Weekly Status Report
+
+**Context**: End of week, need to report progress
+
+**Invocation**: `@acp.report`
+
+**Result**: Generates comprehensive report showing week's accomplishments, current status, and next week's plans
+
+### Example 2: Milestone Review
+
+**Context**: Just completed milestone 1, need review document
+
+**Invocation**: `@acp.report`
+
+**Result**: Report highlights milestone 1 completion, shows deliverables achieved, documents lessons learned
+
+### Example 3: Stakeholder Update
+
+**Context**: Monthly update for stakeholders
+
+**Invocation**: `@acp.report`
+
+**Result**: Executive-friendly report with high-level progress, key achievements, and timeline
+
+---
+
+## Related Commands
+
+- [`@acp.status`](acp.status.md) - Quick console status (not a full report)
+- [`@acp.update`](acp.update.md) - Update progress before generating report
+- [`@acp.validate`](acp.validate.md) - Validate documentation before reporting
+- [`@acp.sync`](acp.sync.md) - Sync docs before generating report
+
+---
+
+## Troubleshooting
+
+### Issue 1: Report is empty or incomplete
+
+**Symptom**: Generated report missing sections
+
+**Cause**: progress.yaml not up to date or missing data
+
+**Solution**: Run `@acp.update` first to ensure progress.yaml is current, then generate report
+
+### Issue 2: Statistics don't match reality
+
+**Symptom**: Numbers in report seem wrong
+
+**Cause**: Progress tracking out of sync
+
+**Solution**: Review and update progress.yaml manually, verify task counts, then regenerate report
+
+### Issue 3: Report too long or too short
+
+**Symptom**: Report length not appropriate
+
+**Cause**: Too much or too little detail
+
+**Solution**: Adjust report generation to include/exclude sections, customize for audience
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: All files in `agent/` directory, especially `agent/progress.yaml`
+- **Writes**: `agent/reports/report-YYYY-MM-DD.md` (creates report file)
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not access secrets or credentials
+- **Credentials**: Does not access credentials files
+
+---
+
+## Notes
+
+- Reports are saved with date in filename for easy tracking
+- Reports are markdown for easy sharing and version control
+- Generate reports regularly for historical record
+- Customize report format for different audiences
+- Include reports in project documentation
+- Consider automating report generation (weekly/monthly)
+- Reports can be converted to PDF or HTML if needed
+- Keep reports in version control for history
+
+---
+
+**Namespace**: acp
+**Command**: report
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.1.0+
+**Author**: ACP Project

package/agent/commands/acp.status.md

@@ -0,0 +1,280 @@
+# Command: status
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-status` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+
+---
+
+**Purpose**: Display current project status including milestone progress, current task, recent work, and next steps
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command provides a comprehensive overview of the current project status by reading `agent/progress.yaml` and presenting key information in an organized format. It shows where the project stands, what's been accomplished recently, and what needs to be done next.
+
+Use this command when you need to quickly understand the current state of the project without performing a full initialization. It's ideal for checking progress during a session, before starting new work, or when reporting status to stakeholders.
+
+Unlike `@acp-init` which performs a full context load and updates documentation, `@acp-status` is a read-only operation that simply reports the current state as recorded in progress tracking.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists and is up to date
+
+---
+
+## Steps
+
+### 1. Read Progress Tracking
+
+Read the `agent/progress.yaml` file to get current project state.
+
+**Actions**:
+- Open and parse `agent/progress.yaml`
+- Extract key information: current milestone, current task, progress percentages
+- Note any errors or missing data
+
+**Expected Outcome**: Progress data loaded successfully
+
+### 2. Display Current Milestone
+
+Show the current milestone information.
+
+**Actions**:
+- Display milestone ID and name
+- Show milestone progress percentage
+- Show tasks completed vs total tasks
+- Display milestone status (not_started, in_progress, completed)
+
+**Expected Outcome**: User sees current milestone summary
+
+### 3. Display Current Task
+
+Show the current task being worked on.
+
+**Actions**:
+- Display task ID and name
+- Show task status
+- Display task file path
+- Show estimated hours and completion date (if completed)
+
+**Expected Outcome**: User sees current task details
+
+### 4. Display Recent Work
+
+List recent work completed.
+
+**Actions**:
+- Show recent work entries from `progress.yaml`
+- Display dates and descriptions
+- Show completed items with checkmarks
+
+**Expected Outcome**: User sees what was recently accomplished
+
+### 5. Display Next Steps
+
+Show what needs to be done next.
+
+**Actions**:
+- List next steps from `progress.yaml`
+- Prioritize by order in the list
+- Highlight any urgent items
+
+**Expected Outcome**: User knows what to work on next
+
+### 6. Display Blockers
+
+Show any current blockers or issues.
+
+**Actions**:
+- List current blockers from `progress.yaml`
+- Highlight critical blockers
+- Note if no blockers exist
+
+**Expected Outcome**: User is aware of any obstacles
+
+---
+
+## Verification
+
+- [ ] `agent/progress.yaml` read successfully
+- [ ] Current milestone displayed with progress percentage
+- [ ] Current task displayed with status
+- [ ] Recent work listed (if any exists)
+- [ ] Next steps listed
+- [ ] Blockers displayed (or noted as none)
+- [ ] Output is clear and well-formatted
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a read-only command
+
+### Console Output
+```
+📊 Project Status
+
+Project: example-project (v0.1.0)
+Status: in_progress
+Started: 2026-01-15
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📍 Current Milestone: M1 - Foundation
+Progress: 40% (2/5 tasks completed)
+Status: in_progress
+Started: 2026-01-15
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Current Task: task-3-implement-core-logic
+Status: in_progress
+File: agent/tasks/task-3-implement-core-logic.md
+Estimated: 4 hours
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Recent Work:
+  2026-02-15:
+    - ✅ Completed task-2 (database setup)
+    - ✅ Updated progress tracking
+    - 📋 Started task-3
+
+  2026-02-14:
+    - ✅ Completed task-1 (project structure)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 Next Steps:
+  1. Complete task-3 (implement core logic)
+  2. Begin task-4 (add tests)
+  3. Review milestone-1 success criteria
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️  Current Blockers:
+  None
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall Progress: 35% complete
+```
+
+### Status Update
+No status changes - read-only operation
+
+---
+
+## Examples
+
+### Example 1: Checking Status Mid-Session
+
+**Context**: You're in the middle of working and want to see where things stand
+
+**Invocation**: `@acp-status`
+
+**Result**: Displays current milestone (M1, 40% complete), current task (task-3, in progress), recent work (completed task-2 yesterday), and next steps (finish task-3, start task-4)
+
+### Example 2: Starting a New Session
+
+**Context**: Beginning work after a break, want to see project state before diving in
+
+**Invocation**: `@acp-status`
+
+**Result**: Shows you're on milestone 2, 60% through, currently on task-7, with 3 tasks completed this week and 2 blockers to address
+
+### Example 3: Reporting to Stakeholders
+
+**Context**: Need to provide a quick status update
+
+**Invocation**: `@acp-status`
+
+**Result**: Clean, formatted output showing overall progress (65%), current phase (Testing), and upcoming milestones
+
+---
+
+## Related Commands
+
+- [`@acp-init`](acp.init.md) - Use for full context initialization at session start
+- [`@acp-proceed`](acp.proceed.md) - Use after checking status to continue with current task
+- [`@acp-update`](acp.update.md) - Use to update progress.yaml after completing work
+- [`@acp-sync`](acp.sync.md) - Use to sync documentation with code changes
+
+---
+
+## Troubleshooting
+
+### Issue 1: progress.yaml not found
+
+**Symptom**: Error message "Cannot read file: agent/progress.yaml"
+
+**Cause**: Progress tracking file doesn't exist yet
+
+**Solution**: Create progress.yaml from template: `cp agent/progress.template.yaml agent/progress.yaml`, then fill in initial project information
+
+### Issue 2: Empty or incomplete output
+
+**Symptom**: Status shows "No data" or missing sections
+
+**Cause**: progress.yaml is not properly filled out
+
+**Solution**: Review progress.yaml and ensure all required fields are populated (project name, current milestone, current task, etc.)
+
+### Issue 3: Outdated information displayed
+
+**Symptom**: Status shows old task or milestone that's already completed
+
+**Cause**: progress.yaml hasn't been updated after recent work
+
+**Solution**: Run `@acp-update` to refresh progress tracking, or manually update progress.yaml
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `agent/progress.yaml` only
+- **Writes**: None (read-only command)
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not access any secrets or credentials
+- **Credentials**: Does not access any credentials
+
+---
+
+## Notes
+
+- This is a read-only command that doesn't modify any files
+- For best results, keep `agent/progress.yaml` up to date
+- Use `@acp-update` after completing tasks to ensure status is accurate
+- Status output is designed to be human-readable and suitable for reports
+- Can be run multiple times per session without side effects
+- Faster than `@acp-init` since it only reads one file
+
+---
+
+**Namespace**: acp
+**Command**: status
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.0.3+
+**Author**: ACP Project