@prmichaelsen/task-mcp 0.2.0

package/agent/commands/acp.validate.md

@@ -0,0 +1,385 @@
+# Command: validate
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.validate` 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**: Validate all ACP documents for structure, consistency, and correctness
+**Category**: Documentation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command validates all ACP documentation to ensure it follows proper structure, maintains consistency, and contains no errors. It checks document formatting, verifies links and references, validates YAML syntax, and ensures all required sections are present.
+
+Use this command before committing documentation changes, after creating new documents, or periodically to ensure documentation quality. It's particularly useful before releases or when onboarding new contributors.
+
+Unlike `@acp.sync` which compares docs to code, `@acp.validate` checks the internal consistency and correctness of the documentation itself.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] Documentation exists in `agent/` directory
+- [ ] You want to verify documentation quality
+
+---
+
+## Steps
+
+### 1. Validate Directory Structure
+
+Check that all required directories and files exist.
+
+**Actions**:
+- Verify `agent/` directory exists
+- Check for `agent/design/`, `agent/milestones/`, `agent/patterns/`, `agent/tasks/`
+- Verify `agent/progress.yaml` exists
+- Check for `agent/commands/` directory
+- Note any missing directories
+
+**Expected Outcome**: Directory structure validated
+
+### 2. Validate progress.yaml
+
+Check YAML syntax and required fields.
+
+**Actions**:
+- Parse `agent/progress.yaml` as YAML
+- Verify required fields exist (project, milestones, tasks)
+- Check field types (strings, numbers, dates)
+- Validate date formats (YYYY-MM-DD)
+- Verify progress percentages (0-100)
+- Check milestone/task references are consistent
+- Validate status values (not_started, in_progress, completed)
+
+**Expected Outcome**: progress.yaml is valid
+
+### 3. Validate Design Documents
+
+Check design document structure and content.
+
+**Actions**:
+- Read all files in `agent/design/`
+- Verify required sections exist (Overview, Problem, Solution)
+- Check for proper markdown formatting
+- Validate code blocks have language tags
+- Verify dates are in correct format
+- Check status values are valid
+- Ensure no broken internal links
+
+**Expected Outcome**: Design docs are well-formed
+
+### 4. Validate Milestone Documents
+
+Check milestone document structure.
+
+**Actions**:
+- Read all files in `agent/milestones/`
+- Verify required sections (Overview, Deliverables, Success Criteria)
+- Check naming convention (milestone-N-name.md)
+- Validate task references exist
+- Verify success criteria are checkboxes
+- Check for proper formatting
+
+**Expected Outcome**: Milestone docs are valid
+
+### 5. Validate Task Documents
+
+Check task document structure.
+
+**Actions**:
+- Read all files in `agent/tasks/`
+- Verify required sections (Objective, Steps, Verification)
+- Check naming convention (task-N-name.md)
+- Validate milestone references
+- Verify verification items are checkboxes
+- Check for proper formatting
+
+**Expected Outcome**: Task docs are valid
+
+### 6. Validate Pattern Documents
+
+Check pattern document structure.
+
+**Actions**:
+- Read all files in `agent/patterns/`
+- Verify required sections (Overview, Implementation, Examples)
+- Check code examples are properly formatted
+- Validate examples have language tags
+- Verify no broken links
+
+**Expected Outcome**: Pattern docs are valid
+
+### 7. Validate Command Documents
+
+Check command document structure.
+
+**Actions**:
+- Read all files in `agent/commands/`
+- Verify required sections (Purpose, Steps, Verification)
+- Check agent directive is present
+- Validate namespace and version fields
+- Verify examples are complete
+- Check related commands links work
+
+**Expected Outcome**: Command docs are valid
+
+### 8. Check Cross-References
+
+Validate links between documents.
+
+**Actions**:
+- Extract all internal links from documents
+- Verify linked files exist
+- Check milestone → task references
+- Verify task → milestone back-references
+- Validate command → command links
+- Note any broken links
+
+**Expected Outcome**: All links are valid
+
+### 9. Generate Validation Report
+
+Summarize validation results.
+
+**Actions**:
+- Count total documents validated
+- List any errors found
+- List any warnings
+- Provide recommendations
+- Suggest fixes for issues
+
+**Expected Outcome**: Validation report generated
+
+---
+
+## Verification
+
+- [ ] All required directories exist
+- [ ] progress.yaml is valid YAML
+- [ ] progress.yaml has all required fields
+- [ ] All design documents are well-formed
+- [ ] All milestone documents are valid
+- [ ] All task documents are valid
+- [ ] All pattern documents are valid
+- [ ] All command documents are valid
+- [ ] No broken internal links
+- [ ] Validation report generated
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a read-only validation command
+
+### Console Output
+```
+✓ Validating ACP Documentation
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Directory Structure:
+✓ agent/ directory exists
+✓ agent/design/ exists (5 files)
+✓ agent/milestones/ exists (2 files)
+✓ agent/patterns/ exists (3 files)
+✓ agent/tasks/ exists (7 files)
+✓ agent/commands/ exists (11 files)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+progress.yaml:
+✓ Valid YAML syntax
+✓ All required fields present
+✓ Date formats correct
+✓ Progress percentages valid (0-100)
+✓ Status values valid
+✓ Task/milestone references consistent
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Design Documents (5):
+✓ All have required sections
+✓ Markdown formatting correct
+✓ Code blocks properly tagged
+⚠️  auth-design.md: Missing "Last Updated" date
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone Documents (2):
+✓ All have required sections
+✓ Naming convention followed
+✓ Task references valid
+✓ Success criteria are checkboxes
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Task Documents (7):
+✓ All have required sections
+✓ Naming convention followed
+✓ Milestone references valid
+✓ Verification items are checkboxes
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Pattern Documents (3):
+✓ All have required sections
+✓ Code examples properly formatted
+✓ No broken links
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Command Documents (11):
+✓ All have required sections
+✓ Agent directives present
+✓ Namespace and version fields valid
+✓ Examples complete
+✓ Related command links valid
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Cross-References:
+✓ All internal links valid
+✓ Milestone → task references correct
+✓ Task → milestone back-references correct
+✓ Command → command links work
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Validation Complete!
+
+Summary:
+- Documents validated: 28
+- Errors: 0
+- Warnings: 1
+- Overall: PASS
+
+Warnings:
+⚠️  auth-design.md: Missing "Last Updated" date
+
+Recommendations:
+- Add "Last Updated" date to auth-design.md
+- Consider adding more code examples to patterns
+```
+
+### Status Update
+- Validation completed
+- Issues identified (if any)
+- Documentation quality confirmed
+
+---
+
+## Examples
+
+### Example 1: Before Committing Changes
+
+**Context**: Made changes to several docs, want to verify before commit
+
+**Invocation**: `@acp.validate`
+
+**Result**: Validates all docs, finds 2 broken links, reports them, you fix them before committing
+
+### Example 2: After Creating New Documents
+
+**Context**: Created 3 new design documents
+
+**Invocation**: `@acp.validate`
+
+**Result**: Validates new docs, confirms they follow proper structure, identifies missing section in one doc
+
+### Example 3: Periodic Quality Check
+
+**Context**: Monthly documentation review
+
+**Invocation**: `@acp.validate`
+
+**Result**: Validates all 50+ documents, finds minor formatting issues in 3 files, overall quality is good
+
+---
+
+## Related Commands
+
+- [`@acp.sync`](acp.sync.md) - Sync documentation with code (different from validation)
+- [`@acp.update`](acp.update.md) - Update progress tracking
+- [`@acp.report`](acp.report.md) - Generate comprehensive report including validation results
+- [`@acp.init`](acp.init.md) - Can include validation as part of initialization
+
+---
+
+## Troubleshooting
+
+### Issue 1: YAML parsing errors
+
+**Symptom**: progress.yaml fails to parse
+
+**Cause**: Invalid YAML syntax (indentation, special characters)
+
+**Solution**: Use YAML validator, check indentation (2 spaces), quote strings with special characters
+
+### Issue 2: Many broken links reported
+
+**Symptom**: Validation finds numerous broken links
+
+**Cause**: Files were moved or renamed
+
+**Solution**: Update links to reflect new file locations, use relative paths, verify files exist
+
+### Issue 3: Validation takes too long
+
+**Symptom**: Command runs for several minutes
+
+**Cause**: Very large project with many documents
+
+**Solution**: This is normal for large projects, consider validating specific directories only, run less frequently
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: All files in `agent/` directory
+- **Writes**: None (read-only validation)
+- **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 is a read-only command - it doesn't modify files
+- Validation should be fast (< 30 seconds for most projects)
+- Run before committing documentation changes
+- Integrate into CI/CD pipeline if desired
+- Warnings are informational, not failures
+- Errors should be fixed before proceeding
+- Consider running after major documentation updates
+- Can be automated as a pre-commit hook
+
+---
+
+**Namespace**: acp
+**Command**: validate
+**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.version-check-for-updates.md

@@ -0,0 +1,275 @@
+# Command: version-check-for-updates
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-version-check-for-updates` 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**: Check if newer version of ACP is available without applying updates
+**Category**: Maintenance
+**Frequency**: Per Session
+
+---
+
+## What This Command Does
+
+This command checks if a newer version of ACP is available by running the update check script. It's a non-destructive operation that only reports whether updates exist and what changed, without modifying any files.
+
+Use this command at the start of sessions (it's part of `@acp-init`) or when you want to see if improvements are available. It shows what's new via the CHANGELOG and lets you decide whether to update.
+
+Unlike `@acp-version-update` which applies updates immediately, this command only checks and reports, giving you control over when to update.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/scripts/check-for-updates.sh` exists
+- [ ] Internet connection available
+- [ ] Git installed
+
+---
+
+## Steps
+
+### 1. Run Update Check Script
+
+Execute the check-for-updates script.
+
+**Actions**:
+- Check if `./agent/scripts/check-for-updates.sh` exists
+- If exists, run the script
+- If doesn't exist, report that update checking is unavailable
+- Capture script output
+
+**Expected Outcome**: Update status determined
+
+### 2. Parse Script Output
+
+Interpret the results from the update check.
+
+**Actions**:
+- Check if updates are available
+- Extract available version number (if updates exist)
+- Note if already up to date
+- Handle any errors from script
+
+**Expected Outcome**: Update status understood
+
+### 3. Display Update Status
+
+Show whether updates are available.
+
+**Actions**:
+- If up to date: Display success message
+- If updates available: Show new version number
+- Display current version for comparison
+- Show update availability clearly
+
+**Expected Outcome**: User knows if updates exist
+
+### 4. Show What Changed
+
+If updates are available, display changelog.
+
+**Actions**:
+- Fetch CHANGELOG from repository
+- Show changes between current and new version
+- Highlight Added, Changed, Removed, Fixed sections
+- Make it easy to understand what's new
+
+**Expected Outcome**: User understands what would change
+
+### 5. Prompt for Action
+
+Ask user if they want to update.
+
+**Actions**:
+- If updates available: Suggest running `@acp-version-update`
+- If up to date: No action needed
+- Provide clear next steps
+
+**Expected Outcome**: User knows what to do next
+
+---
+
+## Verification
+
+- [ ] Update check script executed successfully
+- [ ] Update status determined (up to date or updates available)
+- [ ] If updates available, changelog displayed
+- [ ] Clear next steps provided
+- [ ] No files modified
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a read-only command
+
+### Console Output (Up to Date)
+```
+🔍 Checking for ACP updates...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Your ACP is up to date!
+
+Current Version: 1.0.3
+Latest Version: 1.0.3
+Released: 2026-02-13
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ℹ️  No action needed.
+```
+
+### Console Output (Updates Available)
+```
+🔍 Checking for ACP updates...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🆕 Updates Available!
+
+Current Version: 1.0.3
+Latest Version: 1.1.0
+Released: 2026-02-20
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 What's New in 1.1.0:
+
+Added:
+  • ACP Commands system with 15 core commands
+  • Flat directory structure with dot notation
+  • Command template for creating custom commands
+  • Third-party command installation via @acp-install
+
+Changed:
+  • Improved installation scripts
+  • Better autocomplete support
+  • Enhanced documentation
+
+Fixed:
+  • Various bug fixes and improvements
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 To update, run: @acp-version-update
+
+📚 Full changelog:
+  https://github.com/prmichaelsen/agent-context-protocol/blob/mainline/CHANGELOG.md
+```
+
+### Status Update
+No status changes - read-only operation
+
+---
+
+## Examples
+
+### Example 1: Session Start Check
+
+**Context**: Starting work session, want to check for updates
+
+**Invocation**: `@acp-version-check-for-updates`
+
+**Result**: Shows you're on 1.0.3, latest is 1.1.0, displays what's new, suggests updating
+
+### Example 2: Already Up to Date
+
+**Context**: Checking for updates after recent update
+
+**Invocation**: `@acp-version-check-for-updates`
+
+**Result**: Confirms you're on latest version (1.0.3), no action needed
+
+### Example 3: No Internet Connection
+
+**Context**: Offline, trying to check for updates
+
+**Invocation**: `@acp-version-check-for-updates`
+
+**Result**: Reports cannot connect to repository, shows current version, suggests trying again when online
+
+---
+
+## Related Commands
+
+- [`@acp-version-check`](acp.version-check.md) - Show current version without checking for updates
+- [`@acp-version-update`](acp.version-update.md) - Apply updates if available
+- [`@acp-init`](acp.init.md) - Includes update check as first step
+
+---
+
+## Troubleshooting
+
+### Issue 1: Script not found
+
+**Symptom**: Error "check-for-updates.sh not found"
+
+**Cause**: Older ACP installation without update scripts
+
+**Solution**: Update ACP manually by downloading latest AGENT.md, or install update scripts from repository
+
+### Issue 2: Network error
+
+**Symptom**: Error "Cannot connect to repository"
+
+**Cause**: No internet connection or GitHub unavailable
+
+**Solution**: Check internet connection and try again. Use `@acp-version-check` to see current version offline.
+
+### Issue 3: Permission denied
+
+**Symptom**: Error "Permission denied" when running script
+
+**Cause**: Script not executable
+
+**Solution**: Run `chmod +x agent/scripts/check-for-updates.sh` to make it executable
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `AGENT.md`, `CHANGELOG.md`
+- **Writes**: None (read-only command)
+- **Executes**: `./agent/scripts/check-for-updates.sh`
+
+### Network Access
+- **APIs**: GitHub API (via check-for-updates script)
+- **Repositories**: Accesses ACP repository to check latest version
+
+### Sensitive Data
+- **Secrets**: Does not access any secrets or credentials
+- **Credentials**: Does not access any credentials
+
+---
+
+## Notes
+
+- Non-destructive operation - only checks, doesn't modify files
+- Requires internet connection to check for updates
+- Part of `@acp-init` workflow
+- Safe to run multiple times
+- Update check script may cache results briefly
+- Shows changelog diff between versions
+
+---
+
+**Namespace**: acp
+**Command**: version-check-for-updates
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.0.3+
+**Author**: ACP Project