@prmichaelsen/remember-mcp 2.3.0 → 2.3.1

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.sync.md

@@ -0,0 +1,323 @@
+# Command: sync
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.sync` 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**: Synchronize documentation with source code by identifying and updating stale documentation
+**Category**: Documentation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command synchronizes ACP documentation with the actual source code implementation. It reads source files, compares them with design documents and patterns, identifies documentation drift, and updates stale documentation to match reality.
+
+Use this command after making significant code changes, when you suspect documentation is outdated, or periodically to ensure documentation stays current. It's particularly useful after implementing features, refactoring code, or completing milestones.
+
+Unlike `@acp.update` which updates progress tracking, `@acp.sync` focuses on keeping design documents, patterns, and technical documentation aligned with the actual codebase.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] Source code exists to compare against
+- [ ] Design documents exist in `agent/design/`
+- [ ] You have understanding of what changed in code
+
+---
+
+## Steps
+
+### 1. Read Design Documents
+
+Load all design documents to understand documented architecture.
+
+**Actions**:
+- Read all files in `agent/design/`
+- Note documented features, patterns, and architecture
+- Understand documented API contracts
+- Identify documented dependencies
+- List documented file structures
+
+**Expected Outcome**: Documented architecture understood
+
+### 2. Read Source Code
+
+Review actual implementation in source files.
+
+**Actions**:
+- Identify main source directories (src/, lib/, etc.)
+- Read key implementation files
+- Note actual features implemented
+- Understand actual architecture
+- Identify actual dependencies
+- Document actual file structures
+
+**Expected Outcome**: Actual implementation understood
+
+### 3. Compare Documentation vs Reality
+
+Identify discrepancies between docs and code.
+
+**Actions**:
+- Compare documented features with implemented features
+- Check if documented patterns match actual patterns
+- Verify API contracts match implementation
+- Compare file structures
+- Note undocumented features in code
+- Identify documented features not yet implemented
+
+**Expected Outcome**: Documentation drift identified
+
+### 4. Identify Stale Documentation
+
+Determine which documents need updates.
+
+**Actions**:
+- List design docs that are outdated
+- Note patterns that don't match code
+- Identify missing documentation for new features
+- Flag incorrect technical specifications
+- Prioritize updates by importance
+
+**Expected Outcome**: Update priorities established
+
+### 5. Update Design Documents
+
+Refresh design documents to match reality.
+
+**Actions**:
+- Update feature descriptions
+- Correct technical specifications
+- Update code examples to match actual code
+- Add notes about implementation differences
+- Update status fields (Proposal → Implemented)
+- Add "Last Updated" dates
+
+**Expected Outcome**: Design docs reflect reality
+
+### 6. Update Pattern Documents
+
+Refresh patterns to match actual usage.
+
+**Actions**:
+- Update pattern examples with real code
+- Correct pattern descriptions
+- Add new patterns discovered in code
+- Update anti-patterns based on lessons learned
+- Ensure code examples compile/work
+
+**Expected Outcome**: Patterns match actual usage
+
+### 7. Document New Features
+
+Add documentation for undocumented features.
+
+**Actions**:
+- Create design docs for undocumented features
+- Document new patterns found in code
+- Add technical specifications
+- Include code examples
+- Link related documents
+
+**Expected Outcome**: All features documented
+
+### 8. Update Progress Tracking
+
+Update progress.yaml to reflect sync activity.
+
+**Actions**:
+- Add recent work entry for sync
+- Note what was updated
+- Update documentation counts if needed
+- Add notes about documentation status
+
+**Expected Outcome**: Sync activity tracked
+
+---
+
+## Verification
+
+- [ ] All design documents reviewed
+- [ ] Source code reviewed and compared
+- [ ] Documentation drift identified
+- [ ] Stale documents updated
+- [ ] New features documented
+- [ ] Pattern documents current
+- [ ] Code examples work correctly
+- [ ] progress.yaml updated with sync notes
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/design/*.md` - Updated design documents
+- `agent/patterns/*.md` - Updated pattern documents
+- `agent/progress.yaml` - Sync activity logged
+- Potentially new design/pattern documents created
+
+### Console Output
+```
+🔄 Synchronizing Documentation with Code
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Reading design documents...
+✓ Read 5 design documents
+✓ Read 3 pattern documents
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Reviewing source code...
+✓ Reviewed src/services/
+✓ Reviewed src/models/
+✓ Reviewed src/utils/
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Comparing documentation vs reality...
+⚠️  Found 3 discrepancies:
+  1. auth-design.md: Documented OAuth, implemented API keys
+  2. data-pattern.md: Example code outdated
+  3. api-design.md: Missing /health endpoint documentation
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Updating documentation...
+✓ Updated auth-design.md (OAuth → API keys)
+✓ Updated data-pattern.md (refreshed examples)
+✓ Updated api-design.md (added /health endpoint)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Sync Complete!
+
+Summary:
+- Documents reviewed: 8
+- Discrepancies found: 3
+- Documents updated: 3
+- New documents created: 0
+- Documentation is now current
+```
+
+### Status Update
+- Design documents synchronized
+- Patterns updated
+- New features documented
+- Sync logged in progress.yaml
+
+---
+
+## Examples
+
+### Example 1: After Major Refactoring
+
+**Context**: Refactored authentication system, docs are outdated
+
+**Invocation**: `@acp.sync`
+
+**Result**: Identifies auth-design.md is stale, updates it to reflect new implementation, updates related patterns
+
+### Example 2: After Adding Features
+
+**Context**: Added 3 new API endpoints, not yet documented
+
+**Invocation**: `@acp.sync`
+
+**Result**: Identifies undocumented endpoints, updates api-design.md with new endpoints, adds code examples
+
+### Example 3: Periodic Maintenance
+
+**Context**: Monthly documentation review
+
+**Invocation**: `@acp.sync`
+
+**Result**: Reviews all docs, finds minor drift in 2 files, updates them, confirms rest is current
+
+---
+
+## Related Commands
+
+- [`@acp.update`](acp.update.md) - Update progress tracking (not documentation)
+- [`@acp.validate`](acp.validate.md) - Validate documentation structure and consistency
+- [`@acp.init`](acp.init.md) - Includes sync as part of initialization
+- [`@acp.report`](acp.report.md) - Generate report including documentation status
+
+---
+
+## Troubleshooting
+
+### Issue 1: Can't determine what changed
+
+**Symptom**: Unclear what documentation needs updating
+
+**Cause**: Too many changes or unclear code
+
+**Solution**: Review git commits since last sync, focus on major changes first, update incrementally
+
+### Issue 2: Documentation and code both seem wrong
+
+**Symptom**: Neither docs nor code match expected behavior
+
+**Cause**: Requirements changed or misunderstood
+
+**Solution**: Clarify requirements first, then update both code and docs to match correct requirements
+
+### Issue 3: Too many discrepancies to fix
+
+**Symptom**: Overwhelming number of outdated docs
+
+**Cause**: Long time since last sync
+
+**Solution**: Prioritize by importance, fix critical docs first, schedule time for rest, sync more frequently going forward
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: All files in `agent/design/`, `agent/patterns/`, source code directories
+- **Writes**: `agent/design/*.md`, `agent/patterns/*.md`, `agent/progress.yaml`
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not access secrets or credentials
+- **Credentials**: Does not access credentials files
+
+---
+
+## Notes
+
+- This command can be time-consuming for large projects
+- Focus on high-priority documentation first
+- Sync regularly to avoid large drift
+- Use git diff to see what changed in code
+- Document the "why" not just the "what"
+- Keep code examples working and tested
+- Update "Last Updated" dates in documents
+- Consider running after each milestone completion
+
+---
+
+**Namespace**: acp
+**Command**: sync
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.1.0+
+**Author**: ACP Project