@prmichaelsen/acp-mcp 0.1.0

package/agent/commands/acp.task-create.md

@@ -0,0 +1,390 @@
+# Command: task-create
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.task-create` has been invoked.
+> 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."
+>
+> **This is a CREATION command - you will create files directly, no shell scripts needed.**
+>
+> Follow the steps below to create a task file with proper structure and automatic progress updates.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+
+---
+
+**Purpose**: Create task files with proper structure, milestone linking, and automatic progress.yaml updates
+**Category**: Creation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command creates a new task file with proper structure, milestone linking, and automatic updates to progress.yaml. It provides a guided workflow for creating well-structured tasks that follow ACP conventions.
+
+**Key Features**:
+- Milestone-aware (links to current or specified milestone)
+- Automatic task numbering
+- Draft file support with clarification workflow
+- Auto-updates progress.yaml with new task
+- Uses task-1-{title}.template.md as base
+
+**Use this when**: Creating a new task in an ACP project.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in current directory
+- [ ] Task template exists (agent/tasks/task-1-{title}.template.md)
+- [ ] progress.yaml exists with at least one milestone
+- [ ] (Optional) Draft file prepared if using draft workflow
+
+---
+
+## Steps
+
+### 1. Detect Current Milestone
+
+Determine which milestone this task belongs to:
+
+**Actions**:
+- Read progress.yaml
+- Identify current milestone (current_milestone field)
+- Get milestone details (name, ID)
+- Ask user to confirm or select different milestone
+
+**Expected Outcome**: Target milestone identified
+
+### 2. Determine Task Number
+
+Find the next available task number:
+
+**Actions**:
+- List all existing task files in agent/tasks/
+- Parse task numbers (task-1-*, task-2-*, etc.)
+- Find highest number
+- Increment by 1 for new task number
+
+**Expected Outcome**: Next task number determined (e.g., task-25)
+
+### 3. Check for Draft File
+
+Check if draft file was provided as argument:
+
+**Syntax**:
+- `@acp.task-create @my-draft.md` (@ reference)
+- `@acp.task-create agent/drafts/my-draft.md` (path)
+- `@acp.task-create` (no draft)
+
+**Actions**:
+- If draft provided: Read draft file
+- If no draft: Proceed to Step 4
+
+**Expected Outcome**: Draft file read (if provided)
+
+### 4. Collect Task Information
+
+Gather information from user via chat:
+
+**Information to Collect**:
+- **Task name** (descriptive, without "Task N:" prefix)
+  - Example: "Implement User Authentication" (not "Task 25: Implement User Authentication")
+  - Validation: Clear, action-oriented
+- **Task description** (objective - what this task accomplishes)
+  - Example: "Implement Firebase Authentication with email/password and Google sign-in"
+- **Estimated time** (hours or days)
+  - Example: "4-6 hours" or "2 days"
+- **Dependencies** (other tasks that must complete first)
+  - Example: "Task 24" or "None"
+- **Context** (background information)
+  - Example: "Authentication is required before implementing user-scoped data"
+
+**If no draft provided**:
+- Ask: "Describe what you want this task to accomplish" OR
+- Offer: "Would you like to create an empty draft file first?"
+
+**Expected Outcome**: All task metadata collected
+
+### 5. Process Draft (If Provided)
+
+If draft file was provided, create clarification if needed:
+
+**Actions**:
+- Analyze draft for clarity and completeness
+- If draft is clear and complete: Skip clarification, use draft content
+- If draft is ambiguous: Create clarification document
+  - Find next clarification number
+  - Create `agent/clarifications/clarification-{N}-task-{name}.md`
+  - Generate questions about unclear aspects
+  - Wait for user to answer clarification
+  - Read answered clarification
+
+**Expected Outcome**: Clarification created and answered (if needed)
+
+### 6. Generate Task File
+
+Create task file from template:
+
+**Actions**:
+- Determine full filename: `task-{N}-{name}.md`
+  - N = task number from Step 2
+  - name = kebab-case version of task name
+- Copy from task template (agent/tasks/task-1-{title}.template.md)
+- Fill in metadata:
+  - Task number and name
+  - Milestone link
+  - Estimated time
+  - Dependencies
+  - Status: "Not Started"
+- Fill in sections:
+  - Objective (from collected info)
+  - Context (from collected info or draft)
+  - Steps (from draft/clarification or template structure)
+  - Verification checklist
+- Save to `agent/tasks/task-{N}-{name}.md`
+
+**Expected Outcome**: Task file created
+
+### 7. Update progress.yaml
+
+Add task to progress.yaml:
+
+**Actions**:
+- Read progress.yaml
+- Find the milestone section (e.g., milestone_4)
+- Add new task entry:
+  ```yaml
+  - id: task-{N}
+    name: {Task Name}
+    status: not_started
+    file: agent/tasks/task-{N}-{name}.md
+    estimated_hours: {hours}
+    completed_date: null
+    notes: |
+      {Brief description or empty}
+  ```
+- Update milestone tasks_total count
+- Save progress.yaml
+
+**Expected Outcome**: progress.yaml updated with new task
+
+### 8. Prompt to Delete Draft (If Used)
+
+If draft file was used, ask to delete it:
+
+**Actions**:
+- Ask: "Would you like to delete the draft file? (yes/no)"
+- If yes: Delete draft file
+- If no: Keep draft file
+
+**Expected Outcome**: User chooses whether to keep draft
+
+### 9. Report Success
+
+Display what was created:
+
+**Output**:
+```
+✅ Task Created Successfully!
+
+File: agent/tasks/task-{N}-{name}.md
+Task Number: {N}
+Milestone: M{X} - {Milestone Name}
+Estimated Time: {hours}
+Status: Not Started
+
+✓ Task file created
+✓ progress.yaml updated
+✓ Draft file deleted (if requested)
+
+Next steps:
+- Review and refine task steps
+- Add verification items
+- Start working with @acp.proceed
+```
+
+**Expected Outcome**: User knows task was created successfully
+
+---
+
+## Verification
+
+- [ ] Current milestone identified
+- [ ] Next task number determined correctly
+- [ ] Task information collected
+- [ ] Draft processed (if provided)
+- [ ] Task file created with correct number and name
+- [ ] progress.yaml updated with new task
+- [ ] Milestone tasks_total incremented
+- [ ] Task follows template structure
+- [ ] All metadata filled in correctly
+- [ ] Task linked to correct milestone
+
+---
+
+## Expected Output
+
+### Files Created
+- `agent/tasks/task-{N}-{name}.md` - Task file
+- `agent/clarifications/clarification-{N}-task-{name}.md` - Clarification (if draft was ambiguous)
+
+### Files Modified
+- `agent/progress.yaml` - Task added to milestone section
+
+---
+
+## Examples
+
+### Example 1: Creating Task for Current Milestone
+
+**Context**: Working on Milestone 3, need to add a new task
+
+**Invocation**: `@acp.task-create`
+
+**Interaction**:
+```
+Agent: Current milestone: M3 - ACP Package Management System
+Agent: Create task for this milestone? (yes/no)
+User: yes
+
+Agent: What would you like to name your task?
+User: Implement Package Search Command
+
+Agent: Provide a description (what this task accomplishes):
+User: Create @acp.package-search command to discover ACP packages via GitHub API
+
+Agent: Estimated time? (e.g., "4 hours", "2 days")
+User: 6-8 hours
+
+Agent: Dependencies? (other task numbers or "None")
+User: Task 10
+
+Agent: Any additional context?
+User: Needs GitHub API integration for repository search
+
+✅ Task Created Successfully!
+
+File: agent/tasks/task-11-package-search-command.md
+Task Number: 11
+Milestone: M3 - ACP Package Management System
+Estimated Time: 6-8 hours
+Status: Not Started
+
+✓ Task file created
+✓ progress.yaml updated
+```
+
+### Example 2: Creating Task with Draft
+
+**Context**: Have draft file describing task
+
+**Invocation**: `@acp.task-create @my-task-draft.md`
+
+**Result**: Reads draft, creates clarification if needed, generates task, updates progress.yaml
+
+### Example 3: Creating Task for Different Milestone
+
+**Context**: Want to add task to future milestone
+
+**Invocation**: `@acp.task-create`
+
+**Interaction**:
+```
+Agent: Current milestone: M3 - ACP Package Management System
+Agent: Create task for this milestone? (yes/no)
+User: no
+
+Agent: Available milestones:
+  - M1: ACP Commands Infrastructure (completed)
+  - M2: Documentation & Utility Commands (completed)
+  - M3: ACP Package Management System (in progress)
+  - M4: Package Development System (not started)
+
+Agent: Which milestone? (enter ID like "M4")
+User: M4
+
+[Continues with task creation for M4...]
+```
+
+---
+
+## Related Commands
+
+- [`@acp.pattern-create`](acp.pattern-create.md) - Create patterns
+- [`@acp.command-create`](acp.command-create.md) - Create commands
+- [`@acp.design-create`](acp.design-create.md) - Create designs
+- [`@acp.proceed`](acp.proceed.md) - Start working on created task
+
+---
+
+## Troubleshooting
+
+### Issue 1: No milestones found
+
+**Symptom**: Error message "No milestones found in progress.yaml"
+
+**Solution**: Create a milestone first using milestone template, or add milestone to progress.yaml manually
+
+### Issue 2: Invalid task name
+
+**Symptom**: Task name rejected
+
+**Solution**: Use descriptive, action-oriented names. Avoid special characters except hyphens.
+
+### Issue 3: progress.yaml update failed
+
+**Symptom**: Error updating progress.yaml
+
+**Solution**: Verify progress.yaml exists and is valid YAML. Check milestone section exists for target milestone.
+
+### Issue 4: Task number conflict
+
+**Symptom**: Task file already exists with that number
+
+**Solution**: Command should auto-detect and use next available number. If conflict persists, manually check agent/tasks/ directory.
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: progress.yaml, draft files, task templates, milestone documents
+- **Writes**: agent/tasks/task-{N}-{name}.md, progress.yaml
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Never include secrets in tasks
+- **Credentials**: Never include credentials
+
+---
+
+## Notes
+
+- Task name should be action-oriented (start with verb)
+- Task number is automatically assigned (sequential)
+- Tasks are always created as "Not Started" status
+- Draft files can be any format (free-form markdown)
+- Clarifications are created only if draft is ambiguous
+- progress.yaml is automatically updated
+- Task is linked to milestone via file path and progress.yaml entry
+- Estimated time helps with milestone planning
+
+---
+
+**Namespace**: acp
+**Command**: task-create
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+**Compatibility**: ACP 2.10.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