@prmichaelsen/task-mcp 0.2.0

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

package/agent/commands/acp.update.md

@@ -0,0 +1,301 @@
+# Command: update
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.update` 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**: Update progress.yaml with latest project status, task completion, and recent work
+**Category**: Documentation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command updates `agent/progress.yaml` with the latest project status. It's used after completing work to ensure progress tracking accurately reflects what's been accomplished. The command updates task statuses, milestone progress percentages, recent work entries, and next steps.
+
+Use this command when you've completed tasks, made significant progress, or need to ensure the progress tracking is current. It's particularly useful after finishing a work session or when transitioning between tasks.
+
+Unlike `@acp.sync` which updates documentation based on code changes, `@acp.update` focuses specifically on updating the progress tracking file to reflect completed work and current status.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists
+- [ ] Work has been completed that needs to be tracked
+- [ ] You know which tasks/milestones to update
+
+---
+
+## Steps
+
+### 1. Read Current Progress
+
+Read `agent/progress.yaml` to understand current state.
+
+**Actions**:
+- Open and parse `agent/progress.yaml`
+- Note current milestone and its progress
+- Identify tasks and their statuses
+- Review recent work entries
+- Check next steps
+
+**Expected Outcome**: Current progress state understood
+
+### 2. Identify What Changed
+
+Determine what work was completed since last update.
+
+**Actions**:
+- Review what tasks were worked on
+- Identify completed tasks
+- Note any milestone completions
+- Determine new blockers or resolved blockers
+- Identify what should be in recent work
+
+**Expected Outcome**: Changes to track are identified
+
+### 3. Update Task Statuses
+
+Update individual task statuses and completion dates.
+
+**Actions**:
+- Mark completed tasks as `completed`
+- Set `completed_date` to today's date (YYYY-MM-DD)
+- Update task notes if needed
+- Change `in_progress` tasks if no longer active
+
+**Expected Outcome**: Task statuses reflect reality
+
+### 4. Update Milestone Progress
+
+Recalculate and update milestone progress percentages.
+
+**Actions**:
+- Count tasks completed vs total tasks
+- Calculate progress percentage
+- Update `progress` field (0-100)
+- Update `tasks_completed` count
+- Set `completed` date if milestone finished
+- Update milestone status if needed
+
+**Expected Outcome**: Milestone progress is accurate
+
+### 5. Add Recent Work Entry
+
+Add entry to `recent_work` section documenting what was done.
+
+**Actions**:
+- Add new entry with today's date
+- Write clear description of work completed
+- List specific items accomplished (use ✅, 📋, ⚠️ emojis)
+- Keep entries concise but informative
+- Maintain chronological order (newest first)
+
+**Expected Outcome**: Recent work documented
+
+### 6. Update Next Steps
+
+Refresh the `next_steps` list based on current state.
+
+**Actions**:
+- Remove completed items
+- Add new next steps based on progress
+- Prioritize by importance/urgency
+- Keep list focused (3-5 items)
+- Be specific and actionable
+
+**Expected Outcome**: Next steps are current
+
+### 7. Update Blockers
+
+Update the `current_blockers` list.
+
+**Actions**:
+- Remove resolved blockers
+- Add new blockers discovered
+- Keep descriptions clear and actionable
+- Empty list if no blockers
+
+**Expected Outcome**: Blockers list is accurate
+
+### 8. Save Changes
+
+Write updated progress.yaml back to disk.
+
+**Actions**:
+- Ensure YAML formatting is correct
+- Preserve structure and indentation
+- Save file
+- Verify file was written successfully
+
+**Expected Outcome**: progress.yaml updated on disk
+
+---
+
+## Verification
+
+- [ ] progress.yaml file updated successfully
+- [ ] Task statuses reflect completed work
+- [ ] Milestone progress percentages are accurate
+- [ ] Recent work entry added with today's date
+- [ ] Next steps list is current and actionable
+- [ ] Blockers list is accurate
+- [ ] YAML syntax is valid
+- [ ] No data was lost or corrupted
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/progress.yaml` - Updated with latest progress
+
+### Console Output
+```
+📝 Updating Progress Tracking
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Reading current progress...
+✓ Current milestone: M2 - Documentation & Utility Commands
+✓ Progress: 40% (2/5 tasks completed)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Updating progress...
+✓ Marked task-5 as completed
+✓ Updated milestone progress: 40% → 60%
+✓ Added recent work entry (2026-02-16)
+✓ Updated next steps
+✓ No new blockers
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Progress Updated!
+
+Summary:
+- Tasks completed: 2 → 3
+- Milestone progress: 40% → 60%
+- Recent work: Added entry for today
+- Next: task-6 - Implement Utility Commands
+```
+
+### Status Update
+- Task statuses updated
+- Milestone progress recalculated
+- Recent work documented
+- Next steps refreshed
+
+---
+
+## Examples
+
+### Example 1: After Completing a Task
+
+**Context**: Just finished task-3, need to update progress
+
+**Invocation**: `@acp.update`
+
+**Result**: Marks task-3 as completed, updates milestone from 40% to 60%, adds recent work entry, identifies task-4 as next
+
+### Example 2: Mid-Task Progress Update
+
+**Context**: Made significant progress on task-5 but not complete
+
+**Invocation**: `@acp.update`
+
+**Result**: Adds recent work entry documenting progress, updates task notes, keeps task status as in_progress
+
+### Example 3: Milestone Completion
+
+**Context**: Just finished last task in milestone
+
+**Invocation**: `@acp.update`
+
+**Result**: Marks task and milestone as completed, sets completion dates, updates to next milestone, celebrates achievement
+
+---
+
+## Related Commands
+
+- [`@acp.status`](acp.status.md) - View current status before updating
+- [`@acp.proceed`](acp.proceed.md) - Automatically updates progress after completing tasks
+- [`@acp.sync`](acp.sync.md) - Update documentation based on code changes
+- [`@acp.report`](acp.report.md) - Generate comprehensive progress report
+
+---
+
+## Troubleshooting
+
+### Issue 1: YAML syntax error after update
+
+**Symptom**: progress.yaml has syntax errors
+
+**Cause**: Incorrect indentation or formatting
+
+**Solution**: Validate YAML syntax, fix indentation (use 2 spaces), ensure proper structure
+
+### Issue 2: Progress percentages don't match
+
+**Symptom**: Calculated percentage doesn't match tasks completed
+
+**Cause**: Math error or incorrect task count
+
+**Solution**: Recalculate: (tasks_completed / tasks_total) * 100, round to nearest integer
+
+### Issue 3: Recent work entries out of order
+
+**Symptom**: Dates not in chronological order
+
+**Cause**: New entry added in wrong position
+
+**Solution**: Ensure newest entries are first in the list, maintain reverse chronological order
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `agent/progress.yaml`
+- **Writes**: `agent/progress.yaml` (updates progress tracking)
+- **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 command only updates progress.yaml, not other documentation
+- Use `@acp.sync` to update design docs and other documentation
+- Progress percentages should be integers (0-100)
+- Recent work entries should be concise but informative
+- Keep next steps list focused (3-5 items maximum)
+- Update frequently to maintain accurate tracking
+- Can be run multiple times per day as needed
+
+---
+
+**Namespace**: acp
+**Command**: update
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.1.0+
+**Author**: ACP Project