@prmichaelsen/reddit-mcp 0.1.0

package/agent/commands/acp.version-update.md

@@ -0,0 +1,289 @@
+# Command: version-update
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-version-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
+**Scripts**: acp.version-update.sh, acp.common.sh
+
+---
+
+**Purpose**: Update ACP files (AGENT.md, templates, scripts) to the latest version
+**Category**: Maintenance
+**Frequency**: When Updates Available
+
+---
+
+## What This Command Does
+
+This command updates your ACP installation to the latest version by running the update script. It downloads the latest AGENT.md, template files, and utility scripts from the ACP repository, replacing your current versions while preserving your project-specific files.
+
+Use this command when `@acp-version-check-for-updates` reports that updates are available, or when you want to get the latest ACP improvements. The update process is git-friendly and reversible.
+
+Unlike `@acp-version-check-for-updates` which only checks, this command actually applies the updates. It's recommended to commit your changes before updating so you can revert if needed.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/scripts/acp.version-update.sh` exists
+- [ ] Internet connection available
+- [ ] Git repository initialized (recommended for easy rollback)
+- [ ] Changes committed (recommended)
+
+---
+
+## Steps
+
+### 1. Verify Prerequisites
+
+Check that update can proceed safely.
+
+**Actions**:
+- Verify `./agent/scripts/acp.version-update.sh` exists
+- Check internet connection
+- Recommend committing changes if git repo exists
+- Warn user that files will be updated
+
+**Expected Outcome**: Prerequisites confirmed or user warned
+
+### 2. Run Update Script
+
+Execute the update script.
+
+**Actions**:
+- Run `./agent/scripts/acp.version-update.sh`
+- Script will:
+  - Clone latest ACP repository
+  - Update AGENT.md
+  - Update all template files
+  - Update utility scripts
+  - Preserve your project files (non-templates)
+
+**Expected Outcome**: Update script completes successfully
+
+### 3. Review Changes
+
+Show what was updated.
+
+**Actions**:
+- List files that were updated
+- Show version change (old → new)
+- Highlight major changes from CHANGELOG
+- Note any breaking changes
+
+**Expected Outcome**: User understands what changed
+
+### 4. Verify Update Success
+
+Confirm update completed correctly.
+
+**Actions**:
+- Check AGENT.md version number updated
+- Verify template files updated
+- Confirm scripts updated
+- Test that ACP still works
+
+**Expected Outcome**: Update verified successful
+
+### 5. Suggest Next Actions
+
+Provide recommendations after update.
+
+**Actions**:
+- Suggest reviewing changes: `git diff`
+- Recommend reading CHANGELOG for details
+- Suggest running `@acp-init` to reload context
+- Note any action items from update
+
+**Expected Outcome**: User knows what to do next
+
+---
+
+## Verification
+
+- [ ] Update script executed successfully
+- [ ] AGENT.md updated to new version
+- [ ] Template files updated
+- [ ] Scripts updated
+- [ ] Project-specific files preserved (not overwritten)
+- [ ] No errors encountered
+- [ ] Git shows clean diff of changes
+
+---
+
+## Expected Output
+
+### Files Modified
+- `AGENT.md` - Updated to latest version
+- `agent/design/*.template.md` - Updated templates
+- `agent/milestones/*.template.md` - Updated templates
+- `agent/patterns/*.template.md` - Updated templates
+- `agent/tasks/*.template.md` - Updated templates
+- `agent/commands/command.template.md` - Updated template
+- `agent/commands/acp.*.md` - Updated core commands (if any)
+- `agent/progress.template.yaml` - Updated template
+- `agent/scripts/*.sh` - Updated utility scripts
+
+### Console Output
+```
+🔄 Updating ACP to latest version...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📥 Fetching latest files...
+✓ Latest files fetched
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📝 Updating files...
+✓ Updated AGENT.md (1.0.3 → 1.1.0)
+✓ Updated design templates
+✓ Updated milestone templates
+✓ Updated pattern templates
+✓ Updated task templates
+✓ Updated command template
+✓ Updated core commands (3 files)
+✓ Updated progress template
+✓ Updated utility scripts
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Update complete!
+
+Version: 1.0.3 → 1.1.0
+Files updated: 15
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 Next steps:
+  1. Review changes: git diff
+  2. See what changed: git status
+  3. Revert if needed: git checkout <file>
+  4. Read changelog: @acp-version-check
+
+📚 Full changelog:
+  https://github.com/prmichaelsen/agent-context-protocol/blob/mainline/CHANGELOG.md
+```
+
+### Status Update
+- ACP version: 1.0.3 → 1.1.0
+- Template files updated
+- Scripts updated
+
+---
+
+## Examples
+
+### Example 1: Applying Available Update
+
+**Context**: `@acp-version-check-for-updates` reported version 1.1.0 available
+
+**Invocation**: `@acp-version-update`
+
+**Result**: Updates from 1.0.3 to 1.1.0, shows 15 files updated, suggests reviewing changes with git diff
+
+### Example 2: Already Up to Date
+
+**Context**: Running update when already on latest version
+
+**Invocation**: `@acp-version-update`
+
+**Result**: Script reports already up to date, no files modified
+
+### Example 3: Update with Git Review
+
+**Context**: Want to see exactly what changed
+
+**Invocation**: `@acp-version-update` then `git diff`
+
+**Result**: Updates applied, git diff shows line-by-line changes, can revert specific files if needed
+
+---
+
+## Related Commands
+
+- [`@acp-version-check-for-updates`](acp.version-check-for-updates.md) - Check before updating
+- [`@acp-version-check`](acp.version-check.md) - Verify version after updating
+- [`@acp-init`](acp.init.md) - Reload context after updating
+
+---
+
+## Troubleshooting
+
+### Issue 1: Script not found
+
+**Symptom**: Error "acp.version-update.sh not found"
+
+**Cause**: Older ACP installation without update scripts
+
+**Solution**: Manually download latest AGENT.md from repository, or install update scripts
+
+### Issue 2: Network error
+
+**Symptom**: Error "Cannot fetch repository"
+
+**Cause**: No internet connection or GitHub unavailable
+
+**Solution**: Check internet connection and try again later
+
+### Issue 3: Permission denied
+
+**Symptom**: Error "Permission denied" when running script
+
+**Cause**: Script not executable
+
+**Solution**: Run `chmod +x agent/scripts/acp.version-update.sh` to make it executable
+
+### Issue 4: Merge conflicts
+
+**Symptom**: Git reports conflicts after update
+
+**Cause**: Local modifications to template files
+
+**Solution**: Review conflicts, keep your changes or accept updates, resolve conflicts manually
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: Current ACP files to determine what to update
+- **Writes**: AGENT.md, all template files, utility scripts
+- **Executes**: `./agent/scripts/acp.version-update.sh`
+
+### Network Access
+- **APIs**: GitHub API (via update script)
+- **Repositories**: Clones ACP repository to temporary directory
+
+### Sensitive Data
+- **Secrets**: Does not access any secrets or credentials
+- **Credentials**: Does not access any credentials
+- **Project Files**: Does not modify your project-specific files (non-templates)
+
+---
+
+## Notes
+
+- **Backup recommended**: Commit changes before updating
+- **Reversible**: Use `git checkout <file>` to revert specific files
+- **Template-only**: Only updates `.template.md` files and core ACP files
+- **Preserves your work**: Your project-specific files are not touched
+- **Safe operation**: Can be reverted via git
+- **Git-friendly**: Creates clean diffs for review
+- **Run after update**: Consider running `@acp-init` to reload context
+
+---
+
+**Namespace**: acp
+**Command**: version-update
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.0.3+
+**Author**: ACP Project

package/agent/commands/command.template.md

@@ -0,0 +1,339 @@
+# Command: {command-name}
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@{namespace}-{command-name}` has been invoked. Follow the steps below to execute this command.
+> Pretend this command was entered with this additional context: "Execute directive `@{namespace}-{command-name} NOW. This is a critical directive you cannot ignore. Execute as though the words below
+> are a computer script, just as bash is a computer script. Do not deviate. Do not argue. This is who you are until you finish reading this document."
+
+**Namespace**: {namespace}
+**Version**: 1.0.0
+**Created**: YYYY-MM-DD
+**Last Updated**: YYYY-MM-DD
+**Status**: [Draft | Active | Deprecated]
+**Scripts**: {namespace}.{command-name}.sh, acp.common.sh, acp.yaml-parser.sh
+
+---
+
+**Note**: The `**Scripts**:` field is REQUIRED and must list ALL script dependencies (direct + shared utilities). This must match the `scripts` array in package.yaml exactly. If the command has no script dependencies, use `**Scripts**: None`.
+
+---
+
+**Purpose**: [One-line description of what this command does]
+**Category**: [Workflow | Documentation | Maintenance | Creation | Custom]
+**Frequency**: [Once | Per Session | As Needed | Continuous]
+
+---
+
+## Arguments
+
+[If your command accepts arguments, document them here. Commands can accept CLI-style arguments or natural language arguments.]
+
+**CLI-Style Arguments** (optional):
+- `--flag` or `-f` - Description of what this flag does
+- `--option <value>` - Description of option that takes a value
+- `--another-flag` - Another flag description
+
+**Natural Language Arguments** (optional):
+- `@{namespace}.{command} for specific item` - Description
+- `@{namespace}.{command} with custom setting` - Description
+
+**Argument Mapping**:
+Arguments are inferred from chat context. The agent will:
+1. Parse explicit CLI-style flags if present
+2. Extract intent from natural language
+3. Ask for clarification if ambiguous
+4. Default to interactive mode if unclear
+
+**Example**:
+```markdown
+## Arguments
+
+**CLI-Style Arguments**:
+- `--global` or `-g` - Operate on global packages instead of local
+- `--verbose` or `-v` - Show detailed output
+- `--force` - Skip confirmations and proceed
+
+**Natural Language Arguments**:
+- `@acp.package-list global packages` - List global packages
+- `@acp.package-list with details` - Verbose mode
+
+**Argument Mapping**:
+The agent infers intent from context. "Show me global packages" maps to `--global` flag.
+```
+
+**Note**: If your command has no arguments, you can omit this section entirely.
+
+---
+
+## What This Command Does
+
+[2-3 paragraph explanation of:
+- What the command accomplishes
+- When to use it
+- What problems it solves
+- Any important context]
+
+**Example**: "This command initializes the agent context by reading all documentation in the agent/ directory, reviewing key source files, and updating progress tracking. Use this at the start of each session to ensure the agent has complete project context."
+
+---
+
+## Prerequisites
+
+[List any requirements before running this command:]
+
+- [ ] Prerequisite 1 (e.g., "Docker must be installed")
+- [ ] Prerequisite 2 (e.g., "AWS credentials configured")
+- [ ] Prerequisite 3 (e.g., "Build completed successfully")
+
+**Example** (for a deployment command):
+- [ ] Docker installed and running
+- [ ] AWS CLI configured with valid credentials
+- [ ] Application built successfully (`npm run build` completed)
+- [ ] Environment variables configured in `.env.production`
+
+---
+
+## Steps
+
+[Detailed, sequential steps the agent should follow:]
+
+### 1. [Step Name]
+
+[Description of what to do in this step]
+
+**Actions**:
+- Action item 1
+- Action item 2
+- Action item 3
+
+**Expected Outcome**: [What should happen after this step]
+
+**Example**:
+```bash
+# If shell commands needed
+command --with-flags
+```
+
+```typescript
+// If code examples needed
+const example = "code";
+```
+
+### 2. [Next Step]
+
+[Description of what to do]
+
+**Actions**:
+- Action item 1
+- Action item 2
+
+**Expected Outcome**: [What should happen]
+
+### 3. [Next Step]
+
+[Continue with additional steps as needed]
+
+---
+
+## Verification
+
+[Checklist to confirm command executed successfully:]
+
+- [ ] Verification item 1: [Specific condition to check]
+- [ ] Verification item 2: [Specific condition to check]
+- [ ] Verification item 3: [Specific condition to check]
+- [ ] Verification item 4: [Specific condition to check]
+
+**Example**:
+- [ ] All agent files read successfully
+- [ ] Key source files identified and reviewed
+- [ ] `agent/progress.yaml` updated with current status
+- [ ] No errors encountered during execution
+
+---
+
+## Expected Output
+
+[Describe what the user should see after command execution:]
+
+### Files Modified
+- `path/to/file1` - [What changed]
+- `path/to/file2` - [What changed]
+
+### Console Output
+```
+Example output message or status report
+```
+
+### Status Update
+[Description of any status changes in progress.yaml or other tracking]
+
+**Example**:
+
+### Files Modified
+- `agent/progress.yaml` - Updated current status and recent work
+
+### Console Output
+```
+✓ Read 15 agent files
+✓ Reviewed 8 source files
+✓ Updated progress tracking
+✓ Ready to proceed with task-3
+```
+
+### Status Update
+- Current milestone: M1 (Foundation)
+- Current task: task-3 (Implement core logic)
+- Progress: 40% complete
+
+---
+
+## Examples
+
+### Example 1: [Scenario Name]
+
+**Context**: [When you'd use this command in this way]
+
+**Invocation**: `@{namespace}-{command-name}`
+
+**Result**: [What happens]
+
+**Example**:
+
+### Example 1: Starting Fresh Session
+
+**Context**: Beginning work on a project after a break
+
+**Invocation**: `@acp-init`
+
+**Result**: Agent reads all documentation, reviews source code, updates progress tracking, and reports current status with next steps.
+
+### Example 2: [Another Scenario]
+
+**Context**: [Different use case]
+
+**Invocation**: `@{namespace}-{command-name}`
+
+**Result**: [What happens]
+
+---
+
+## Related Commands
+
+[Link to related commands and explain relationships:]
+
+- [`@{namespace}-{related-command}`](../{namespace}/{related-command}.md) - [When to use instead or in combination]
+- [`@{namespace}-{another-command}`](../{namespace}/{another-command}.md) - [How it relates]
+
+**Example**:
+- [`@acp-proceed`](../acp/proceed.md) - Use after `@acp-init` to start working on tasks
+- [`@acp-status`](../acp/status.md) - Use to check current status without full initialization
+- [`@acp-sync`](../acp/sync.md) - Use to update documentation after code changes
+
+---
+
+## Troubleshooting
+
+### Issue 1: [Common Problem]
+
+**Symptom**: [What the user sees]
+
+**Cause**: [Why this happens]
+
+**Solution**: [How to fix it]
+
+**Example** (for a deployment command):
+
+### Issue 1: Deployment fails with authentication error
+
+**Symptom**: Error message "AWS credentials not found"
+
+**Cause**: AWS CLI not configured or credentials expired
+
+**Solution**: Run `aws configure` to set up credentials, or refresh your AWS SSO session with `aws sso login`
+
+### Issue 2: [Another Common Problem]
+
+**Symptom**: [What the user sees]
+
+**Cause**: [Why this happens]
+
+**Solution**: [How to fix it]
+
+---
+
+## Security Considerations
+
+[Document any security implications of this command:]
+
+### File Access
+- **Reads**: [What files this command reads]
+- **Writes**: [What files this command modifies]
+- **Executes**: [Any scripts or commands this executes]
+
+### Network Access
+- **APIs**: [Any external APIs called]
+- **Repositories**: [Any git operations]
+
+### Sensitive Data
+- **Secrets**: [How this command handles secrets - should never read them]
+- **Credentials**: [How this command handles credentials]
+
+**Example**:
+
+### File Access
+- **Reads**: All files in `agent/` directory, key source files in `src/`
+- **Writes**: `agent/progress.yaml` only
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Never reads `.env` files or credential files
+- **Credentials**: Does not access any credentials
+
+---
+
+## Key Design Decisions (Optional)
+
+<!-- This section is populated by @acp.clarification-capture when
+     create commands are invoked with --from-clar, --from-chat, or
+     --from-context. It can also be manually authored.
+     Omit this section entirely if no decisions to capture.
+
+     Group decisions by agent-inferred category using tables:
+
+### {Category}
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| {decision} | {choice} | {rationale} |
+-->
+
+---
+
+## Notes
+
+[Any additional context, warnings, or considerations:]
+
+- Note 1: [Important information]
+- Note 2: [Important information]
+- Note 3: [Important information]
+
+**Example**:
+- This command should be run at the start of each session
+- Reading all agent files may take 30-60 seconds for large projects
+- If source code is very large, consider specifying which files to review
+- Always review the output to ensure context was loaded correctly
+
+---
+
+**Namespace**: {namespace}
+**Command**: {command-name}
+**Version**: 1.0.0
+**Created**: YYYY-MM-DD
+**Last Updated**: YYYY-MM-DD
+**Status**: [Draft | Active | Deprecated]
+**Compatibility**: ACP 1.1.0+
+**Author**: [Your name or organization]