@prmichaelsen/task-mcp 0.2.0

package/agent/commands/acp.package-install.md

@@ -0,0 +1,347 @@
+# Command: package-install
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.package-install` 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**: Install third-party command packages from git repositories using the package-install script
+**Category**: Maintenance
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command installs third-party ACP packages from git repositories by running the `agent/scripts/package-install.sh` script. The script clones the repository and installs files from the `agent/` directory, including commands, patterns, and design documents.
+
+Use this command when you want to add community-created commands and patterns, install organization-specific ACP content, or share reusable components across multiple projects. It enables extending ACP with custom functionality, patterns, and documentation.
+
+⚠️ **SECURITY WARNING**: Third-party packages can instruct agents to modify files and execute scripts. Always review package contents before installation. You assume all risk when installing third-party packages.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] Git installed and available
+- [ ] Internet connection available
+- [ ] `agent/scripts/package-install.sh` exists
+- [ ] You trust the source of the commands
+- [ ] You have reviewed the command repository
+
+---
+
+## Steps
+
+### 1. Run Package Install Script
+
+Execute the package installation script with the repository URL.
+
+**Actions**:
+- Verify `./agent/scripts/package-install.sh` exists
+- Run the script with repository URL as argument:
+  ```bash
+  # Interactive mode (asks for confirmation)
+  ./agent/scripts/package-install.sh <repository-url>
+  
+  # Auto-confirm mode (skips prompts)
+  ./agent/scripts/package-install.sh -y <repository-url>
+  ```
+- The script will:
+  - Validate the repository URL
+  - Clone the repository to a temporary location
+  - Scan agent/ directory for installable files (commands, patterns, design)
+  - Validate command files (agent directive, namespace check)
+  - Check for naming conflicts
+  - Ask for confirmation (unless -y flag used)
+  - Copy files to respective agent/ directories
+  - Clean up temporary files
+  - Report what was installed
+
+**Expected Outcome**: Script completes successfully and files are installed
+
+### 2. Review Installed Files
+
+Verify the files were installed correctly.
+
+**Actions**:
+- List files in `agent/commands/` to see new commands
+- List files in `agent/patterns/` to see new patterns
+- List files in `agent/design/` to see new designs
+- Read the installed files
+- Verify commands have agent directives
+- Check namespace is not `acp` (reserved for commands)
+- Ensure no malicious content
+
+**Expected Outcome**: Files verified safe and functional
+
+### 3. Test Installed Commands
+
+Try invoking one of the installed commands (if any).
+
+**Actions**:
+- Choose a simple command to test
+- Invoke it using `@{namespace}.{action}` syntax
+- Verify it works as expected
+- Check for any errors
+
+**Expected Outcome**: Commands work correctly
+
+### 4. Document Installation
+
+Update progress tracking with installation notes.
+
+**Actions**:
+- Add note to `agent/progress.yaml` about installed package
+- Document which package was installed
+- Note installation date
+- List installed files (commands, patterns, designs)
+
+**Expected Outcome**: Installation tracked in progress
+
+---
+
+## Verification
+
+- [ ] package-install.sh script exists
+- [ ] Script executed successfully
+- [ ] Files installed to appropriate agent/ directories
+- [ ] Installed commands reviewed for safety (if any)
+- [ ] Installed patterns reviewed (if any)
+- [ ] Installed designs reviewed (if any)
+- [ ] Commands tested and working (if any)
+- [ ] Installation documented in progress.yaml
+- [ ] No errors during installation
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/commands/*.md` - Installed command files (if any)
+- `agent/patterns/*.md` - Installed pattern files (if any)
+- `agent/design/*.md` - Installed design files (if any)
+
+### Console Output
+```
+📦 ACP Package Installer
+========================================
+
+Repository: https://github.com/example/fullstack-package.git
+
+Cloning repository...
+✓ Repository cloned
+
+Scanning for installable files...
+
+📁 commands/ (3 file(s))
+  ✓ deploy.production.md
+  ✓ deploy.staging.md
+  ⚠  deploy.rollback.md (will overwrite existing)
+
+📁 patterns/ (2 file(s))
+  ✓ api-service.md
+  ✓ error-handling.md
+
+📁 design/ (1 file(s))
+  ✓ deployment-strategy.md
+
+Ready to install 6 file(s)
+
+Proceed with installation? (y/N) y
+
+Installing files...
+  ✓ Installed commands/deploy.production.md
+  ✓ Installed commands/deploy.staging.md
+  ✓ Installed commands/deploy.rollback.md
+  ✓ Installed patterns/api-service.md
+  ✓ Installed patterns/error-handling.md
+  ✓ Installed design/deployment-strategy.md
+
+✅ Installation complete!
+
+Installed 6 file(s) from:
+  https://github.com/example/fullstack-package.git
+
+Installed commands:
+  - @deploy.production
+  - @deploy.staging
+  - @deploy.rollback
+
+⚠️  Security Reminder:
+Review installed files before using them.
+Third-party files can instruct agents to modify files and execute scripts.
+
+Next steps:
+  1. Review installed files in agent/ directories
+  2. Test installed commands
+  3. Update progress.yaml with installation notes
+```
+
+### Status Update
+- Commands installed
+- Installation documented
+- Commands ready to use
+
+---
+
+## Examples
+
+### Example 1: Installing Deployment Commands
+
+**Context**: Want to add deployment commands from community
+
+**Invocation**: `@acp.package-install https://github.com/example/acp-deploy-package.git`
+
+**Result**: Script clones repo, installs 3 commands to agent/commands/, now can use @deploy.production
+
+### Example 2: Installing Patterns Package
+
+**Context**: Want to add TypeScript patterns from organization
+
+**Invocation**: `@acp.package-install https://github.com/myorg/typescript-patterns.git`
+
+**Result**: Script installs 5 pattern files to agent/patterns/, now have reusable TypeScript patterns
+
+### Example 3: Installing Complete Package
+
+**Context**: Installing package with commands, patterns, and designs
+
+**Invocation**: `@acp.package-install https://github.com/example/fullstack-package.git`
+
+**Result**: Script installs 3 commands, 4 patterns, 2 design docs across agent/ directories
+
+### Example 4: Installing with Conflicts
+
+**Context**: Installing package that conflicts with existing files
+
+**Invocation**: `@acp.package-install https://github.com/example/package.git`
+
+**Result**: Script detects conflicts, asks for confirmation, overwrites if approved
+
+---
+
+## Related Commands
+
+- [`@acp.validate`](acp.validate.md) - Validate installed commands
+- [`@acp.version-update`](acp.version-update.md) - Update core ACP commands
+- [`@acp.status`](acp.status.md) - View project status
+
+---
+
+## Troubleshooting
+
+### Issue 1: Git clone fails
+
+**Symptom**: Cannot clone repository
+
+**Cause**: Invalid URL, no internet, or private repository
+
+**Solution**: Verify URL is correct, check internet connection, ensure repository is public or you have access
+
+### Issue 2: No commands found
+
+**Symptom**: Repository cloned but no commands found
+
+**Cause**: Commands not in expected location or wrong structure
+
+**Solution**: Check repository structure, look for commands/ directory, verify files are .md format
+
+### Issue 3: Validation fails
+
+**Symptom**: Commands fail validation
+
+**Cause**: Commands don't follow ACP structure
+
+**Solution**: Review command files, ensure they have agent directive and required sections, contact command author
+
+### Issue 4: Namespace conflict
+
+**Symptom**: Command uses reserved namespace
+
+**Cause**: Command tries to use 'acp' namespace
+
+**Solution**: Cannot install - 'acp' namespace is reserved for core commands, contact command author to change namespace
+
+---
+
+## Security Considerations
+
+### ⚠️ CRITICAL SECURITY WARNING
+
+**Third-party packages can contain:**
+- **Commands** that instruct agents to modify files and execute scripts
+- **Patterns** that guide code implementation decisions
+- **Designs** that influence architecture and technical decisions
+
+**Third-party commands can:**
+- Modify any files in your project
+- Execute shell commands
+- Make network requests
+- Access environment variables
+- Read sensitive data
+
+**YOU ASSUME ALL RISK when installing third-party packages.**
+
+### Security Best Practices
+
+**Before Installing**:
+1. Review the repository and command files
+2. Check the author's reputation
+3. Read what each command does
+4. Verify no malicious content
+5. Test in a non-production environment first
+
+**After Installing**:
+1. Review installed command files
+2. Test commands in safe environment
+3. Monitor command behavior
+4. Remove if suspicious activity
+5. Keep installation records
+
+### File Access
+- **Reads**: Repository files, existing files in agent/ directories
+- **Writes**: `agent/commands/*.md`, `agent/patterns/*.md`, `agent/design/*.md`
+- **Executes**: `git clone` command, `./agent/scripts/package-install.sh`
+
+### Network Access
+- **APIs**: None directly
+- **Repositories**: Clones from specified git repository
+
+### Sensitive Data
+- **Secrets**: Does not access secrets
+- **Credentials**: May use git credentials for private repos
+
+---
+
+## Notes
+
+- Installs from all agent/ directories: commands, patterns, design
+- Only install packages from trusted sources
+- Review all files before installation (commands, patterns, designs)
+- Test in safe environment first
+- Keep record of installed packages
+- Update installed packages periodically
+- Remove unused files
+- Report security issues to package authors
+- Consider forking repositories for stability
+- Pin to specific versions/commits for reproducibility
+- Use `-y` flag for automated/scripted installations
+- Patterns and designs influence agent behavior just like commands
+
+---
+
+**Namespace**: acp
+**Command**: package-install
+**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.proceed.md

@@ -0,0 +1,311 @@
+# Command: proceed
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-proceed` 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**: Continue with the current or next task, executing steps and updating progress tracking
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command enables you to continue working on the current task or move to the next task in the project. It reads the current task from `agent/progress.yaml`, loads the task document, guides you through executing the task steps, verifies completion, and updates progress tracking.
+
+Use this command when you're ready to work on tasks after initializing context with `@acp-init`, or when continuing work during an active session. It's the primary command for making progress on the project's task list.
+
+Unlike `@acp-status` which only displays information, `@acp-proceed` is an active command that guides task execution and modifies `agent/progress.yaml` to track progress.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists and has current task defined
+- [ ] Current task document exists in `agent/tasks/`
+- [ ] Context initialized (recommended to run `@acp-init` first)
+
+---
+
+## Steps
+
+### 1. Read Progress Tracking
+
+Read `agent/progress.yaml` to identify the current task.
+
+**Actions**:
+- Open and parse `agent/progress.yaml`
+- Find the current milestone
+- Identify the current task (first task with status `in_progress` or `not_started`)
+- Note task ID, name, and file path
+
+**Expected Outcome**: Current task identified
+
+### 2. Load Task Document
+
+Read the task document to understand what needs to be done.
+
+**Actions**:
+- Open the task file (e.g., `agent/tasks/task-3-implement-feature.md`)
+- Read the objective
+- Review all steps
+- Note verification criteria
+- Check for dependencies
+
+**Expected Outcome**: Task requirements understood
+
+### 3. Check Prerequisites
+
+Verify any task prerequisites are met.
+
+**Actions**:
+- Review prerequisites section in task document
+- Check if dependencies are satisfied
+- Verify required tools/files are available
+- Report any missing prerequisites
+
+**Expected Outcome**: Prerequisites confirmed or blockers identified
+
+### 4. Execute Task Steps
+
+Work through the task steps sequentially.
+
+**Actions**:
+- Follow each step in the task document
+- Execute required actions (create files, run commands, etc.)
+- Document any deviations from the plan
+- Handle errors appropriately
+
+**Expected Outcome**: Task steps completed
+
+### 5. Verify Completion
+
+Check all verification items from the task document.
+
+**Actions**:
+- Go through verification checklist
+- Run tests if specified
+- Confirm all acceptance criteria met
+- Note any incomplete items
+
+**Expected Outcome**: Task verified as complete or issues identified
+
+### 6. Update Progress Tracking
+
+Update `agent/progress.yaml` with task completion.
+
+**Actions**:
+- Mark task status as `completed`
+- Set completion date to today
+- Update milestone progress percentage
+- Increment `tasks_completed` count
+- Add entry to `recent_work` section
+- Update `next_steps` if needed
+
+**Expected Outcome**: Progress tracking reflects completed work
+
+### 7. Report Progress
+
+Provide summary of what was accomplished.
+
+**Actions**:
+- Summarize task completion
+- Show updated milestone progress
+- Identify next task
+- Note any blockers or issues
+
+**Expected Outcome**: User informed of progress and next steps
+
+---
+
+## Verification
+
+- [ ] Current task identified from progress.yaml
+- [ ] Task document read and understood
+- [ ] Prerequisites checked
+- [ ] All task steps executed
+- [ ] Verification checklist completed
+- [ ] progress.yaml updated with completion
+- [ ] Milestone progress percentage updated
+- [ ] Recent work entry added
+- [ ] Next task identified
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/progress.yaml` - Task marked complete, progress updated, recent work added
+- Task-specific files (as defined in task document)
+
+### Console Output
+```
+📋 Current Task: task-3-implement-core-logic
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Objective: Implement the core business logic for the application
+
+Steps:
+  1. Create service layer classes
+  2. Implement data access methods
+  3. Add error handling
+  4. Write unit tests
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Executing task steps...
+
+✅ Step 1: Created service layer classes
+✅ Step 2: Implemented data access methods
+✅ Step 3: Added error handling
+✅ Step 4: Wrote unit tests
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Verification:
+✅ All service classes created
+✅ Unit tests pass
+✅ TypeScript compiles without errors
+✅ Code follows project patterns
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Task 3 Complete!
+
+Updated progress.yaml:
+- Task 3: completed (2026-02-16)
+- Milestone 1: 60% complete (3/5 tasks)
+- Added to recent work
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 Next Task: task-4-add-integration-tests
+File: agent/tasks/task-4-add-integration-tests.md
+Estimated: 3 hours
+```
+
+### Status Update
+- Task status: `not_started` → `completed`
+- Milestone progress: 40% → 60%
+- Tasks completed: 2 → 3
+
+---
+
+## Examples
+
+### Example 1: Continuing Current Task
+
+**Context**: You're in the middle of task-3 and want to continue working on it
+
+**Invocation**: `@acp-proceed`
+
+**Result**: Loads task-3, shows remaining steps, guides you through completion, updates progress when done
+
+### Example 2: Starting Next Task
+
+**Context**: Just finished task-2, ready to start task-3
+
+**Invocation**: `@acp-proceed`
+
+**Result**: Identifies task-3 as next, loads task document, guides through all steps, marks complete when done
+
+### Example 3: Task with Blockers
+
+**Context**: Task has unmet prerequisites
+
+**Invocation**: `@acp-proceed`
+
+**Result**: Identifies missing prerequisites, reports blockers, suggests resolution steps, does not proceed until resolved
+
+---
+
+## Related Commands
+
+- [`@acp-init`](acp.init.md) - Use before proceeding to ensure full context loaded
+- [`@acp-status`](acp.status.md) - Use to check which task is current before proceeding
+- [`@acp-update`](acp.update.md) - Use to manually update progress if needed
+- [`@acp-sync`](acp.sync.md) - Use after completing tasks to sync documentation
+
+---
+
+## Troubleshooting
+
+### Issue 1: No current task found
+
+**Symptom**: Error message "No current task identified"
+
+**Cause**: All tasks are completed or progress.yaml doesn't have a current task
+
+**Solution**: Review progress.yaml and either mark a task as `in_progress` or create new tasks for the next milestone
+
+### Issue 2: Task document not found
+
+**Symptom**: Error message "Cannot read task file"
+
+**Cause**: Task file path in progress.yaml is incorrect or file doesn't exist
+
+**Solution**: Verify the file path in progress.yaml matches the actual task file location, or create the missing task document
+
+### Issue 3: Prerequisites not met
+
+**Symptom**: Command reports missing prerequisites
+
+**Cause**: Task has dependencies that aren't satisfied yet
+
+**Solution**: Complete prerequisite tasks first, or resolve the dependencies, then run `@acp-proceed` again
+
+### Issue 4: Verification fails
+
+**Symptom**: Some verification items don't pass
+
+**Cause**: Task steps weren't completed correctly or there are errors
+
+**Solution**: Review the failed verification items, fix issues, then re-run verification steps
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `agent/progress.yaml`, current task document, related design documents
+- **Writes**: `agent/progress.yaml` (updates task status and progress), task-specific files as defined in task document
+- **Executes**: May execute commands as specified in task steps (e.g., `npm test`, `npm run build`)
+
+### Network Access
+- **APIs**: May make API calls if task requires it
+- **Repositories**: May interact with git if task requires it
+
+### Sensitive Data
+- **Secrets**: Should not access secrets unless task explicitly requires configuration
+- **Credentials**: Should not access credentials files
+
+---
+
+## Notes
+
+- This command modifies `agent/progress.yaml` to track progress
+- Task execution may create, modify, or delete files as specified in the task document
+- Always review task steps before proceeding to understand what will be done
+- Use `@acp-status` first to see which task is current
+- If task is complex, consider breaking it into smaller steps
+- Update progress.yaml manually if command doesn't complete successfully
+
+---
+
+**Namespace**: acp
+**Command**: proceed
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.0.3+
+**Author**: ACP Project