@prmichaelsen/acp-visualizer 0.1.0

package/agent/commands/acp.report.md

@@ -0,0 +1,407 @@
+# Command: report
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.report` 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**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Scripts**: None
+
+---
+
+**Purpose**: Generate a comprehensive project status report including progress, accomplishments, and next steps
+**Category**: Documentation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command generates a comprehensive markdown report summarizing the project's current status, progress, accomplishments, and plans. It reads all ACP documentation and creates a formatted report suitable for sharing with stakeholders, team members, or for project records.
+
+Use this command when you need to communicate project status, before milestone reviews, for weekly/monthly updates, or when onboarding new team members. The report provides a complete snapshot of the project at a point in time.
+
+Unlike `@acp.status` which provides a quick console summary, `@acp.report` generates a detailed markdown document that can be saved, shared, or archived.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists and is current
+- [ ] Documentation exists in `agent/` directory
+
+---
+
+## Steps
+
+### 1. Read Project Information
+
+Load basic project details from progress.yaml.
+
+**Actions**:
+- Read `agent/progress.yaml`
+- Extract project name, version, start date
+- Note current status and milestone
+- Get project description
+
+**Expected Outcome**: Project basics loaded
+
+### 2. Gather Milestone Information
+
+Collect data about all milestones.
+
+**Actions**:
+- Read all milestone documents
+- Extract milestone goals and deliverables
+- Note progress percentages
+- Identify completed vs in-progress vs not-started
+- Calculate overall project progress
+
+**Expected Outcome**: Milestone data collected
+
+### 3. Gather Task Information
+
+Collect data about all tasks.
+
+**Actions**:
+- Read task data from progress.yaml
+- Count total tasks, completed, in-progress
+- Calculate completion percentages
+- Identify current task
+- Note any blocked tasks
+
+**Expected Outcome**: Task data collected
+
+### 4. Summarize Recent Work
+
+Extract recent accomplishments.
+
+**Actions**:
+- Read recent_work from progress.yaml
+- Format accomplishments by date
+- Highlight major achievements
+- Note any significant milestones reached
+
+**Expected Outcome**: Recent work summarized
+
+### 5. Identify Next Steps
+
+Extract and prioritize next steps.
+
+**Actions**:
+- Read next_steps from progress.yaml
+- Read current task for immediate next steps
+- Identify upcoming milestones
+- Note any dependencies
+
+**Expected Outcome**: Next steps identified
+
+### 6. Document Blockers and Risks
+
+List current blockers and risks.
+
+**Actions**:
+- Read current_blockers from progress.yaml
+- Note any risks mentioned in milestone docs
+- Identify dependencies on external factors
+- Assess impact of blockers
+
+**Expected Outcome**: Blockers documented
+
+### 7. Generate Statistics
+
+Calculate project metrics.
+
+**Actions**:
+- Total milestones and completion rate
+- Total tasks and completion rate
+- Overall project progress percentage
+- Time elapsed since project start
+- Estimated time remaining (if available)
+- Documentation count (design docs, patterns, etc.)
+
+**Expected Outcome**: Metrics calculated
+
+### 8. Format Report
+
+Create formatted markdown report.
+
+**Actions**:
+- Create report header with project info
+- Add executive summary
+- Include progress section with charts/percentages
+- List milestones with status
+- Summarize recent accomplishments
+- Document next steps
+- List blockers and risks
+- Include statistics
+- Add footer with generation date
+
+**Expected Outcome**: Report formatted
+
+### 9. Save Report
+
+Write report to file.
+
+**Actions**:
+- Generate filename with date (e.g., `report-2026-02-16.md`)
+- Save to `agent/reports/` directory (create if needed)
+- Confirm file written successfully
+- Display report location
+
+**Expected Outcome**: Report saved
+
+### 10. Deregister Session (Optional)
+
+End the current agent session.
+
+**Actions**:
+- If `./agent/scripts/acp.sessions.sh` exists, run `./agent/scripts/acp.sessions.sh deregister`
+- Display: `"Session deregistered"` in report footer
+
+**Expected Outcome**: Session deregistered
+
+**Note**: If `./agent/scripts/acp.sessions.sh` does not exist, skip this step silently.
+
+---
+
+## Verification
+
+- [ ] Project information extracted
+- [ ] Milestone data collected
+- [ ] Task data collected
+- [ ] Recent work summarized
+- [ ] Next steps identified
+- [ ] Blockers documented
+- [ ] Statistics calculated
+- [ ] Report formatted as markdown
+- [ ] Report saved to file
+- [ ] Report location displayed
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/reports/report-YYYY-MM-DD.md` - Generated report file
+
+### Console Output
+```
+📊 Generating Project Report
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Gathering project information...
+✓ Project: agent-context-protocol v1.1.0
+✓ Started: 2026-02-16
+✓ Current milestone: M2
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Collecting milestone data...
+✓ Milestone 1: Complete (100%)
+✓ Milestone 2: In Progress (60%)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Analyzing tasks...
+✓ Total tasks: 7
+✓ Completed: 5 (71%)
+✓ In progress: 1
+✓ Not started: 1
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Calculating statistics...
+✓ Overall progress: 75%
+✓ Documentation: 8 design docs, 3 patterns
+✓ Commands: 11 implemented
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Formatting report...
+✓ Report generated (2,500 words)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Report Complete!
+
+Saved to: agent/reports/report-2026-02-16.md
+
+Summary:
+- Overall progress: 75%
+- Milestones: 1 complete, 1 in progress
+- Tasks: 5/7 complete
+- Blockers: 0
+```
+
+### Report Structure
+```markdown
+# Project Status Report
+## agent-context-protocol
+
+**Generated**: 2026-02-16
+**Version**: 1.1.0
+**Status**: In Progress
+
+---
+
+## Executive Summary
+
+[2-3 paragraph summary of project status]
+
+---
+
+## Progress Overview
+
+**Overall Progress**: 75%
+
+### Milestones
+- ✅ Milestone 1: ACP Commands Infrastructure (100%)
+- 🔄 Milestone 2: Documentation & Utility Commands (60%)
+
+### Tasks
+- Total: 7
+- Completed: 5 (71%)
+- In Progress: 1
+- Not Started: 1
+
+---
+
+## Recent Accomplishments
+
+[List of recent work with dates]
+
+---
+
+## Next Steps
+
+[Prioritized list of next steps]
+
+---
+
+## Current Blockers
+
+[List of blockers, or "None"]
+
+---
+
+## Statistics
+
+[Detailed metrics and counts]
+
+---
+
+**Report generated by ACP v1.1.0**
+```
+
+---
+
+## Examples
+
+### Example 1: Weekly Status Report
+
+**Context**: End of week, need to report progress
+
+**Invocation**: `@acp.report`
+
+**Result**: Generates comprehensive report showing week's accomplishments, current status, and next week's plans
+
+### Example 2: Milestone Review
+
+**Context**: Just completed milestone 1, need review document
+
+**Invocation**: `@acp.report`
+
+**Result**: Report highlights milestone 1 completion, shows deliverables achieved, documents lessons learned
+
+### Example 3: Stakeholder Update
+
+**Context**: Monthly update for stakeholders
+
+**Invocation**: `@acp.report`
+
+**Result**: Executive-friendly report with high-level progress, key achievements, and timeline
+
+---
+
+## Related Commands
+
+- [`@acp.status`](acp.status.md) - Quick console status (not a full report)
+- [`@acp.update`](acp.update.md) - Update progress before generating report
+- [`@acp.validate`](acp.validate.md) - Validate documentation before reporting
+- [`@acp.sync`](acp.sync.md) - Sync docs before generating report
+
+---
+
+## Troubleshooting
+
+### Issue 1: Report is empty or incomplete
+
+**Symptom**: Generated report missing sections
+
+**Cause**: progress.yaml not up to date or missing data
+
+**Solution**: Run `@acp.update` first to ensure progress.yaml is current, then generate report
+
+### Issue 2: Statistics don't match reality
+
+**Symptom**: Numbers in report seem wrong
+
+**Cause**: Progress tracking out of sync
+
+**Solution**: Review and update progress.yaml manually, verify task counts, then regenerate report
+
+### Issue 3: Report too long or too short
+
+**Symptom**: Report length not appropriate
+
+**Cause**: Too much or too little detail
+
+**Solution**: Adjust report generation to include/exclude sections, customize for audience
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: All files in `agent/` directory, especially `agent/progress.yaml`
+- **Writes**: `agent/reports/report-YYYY-MM-DD.md` (creates report file)
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not access secrets or credentials
+- **Credentials**: Does not access credentials files
+
+---
+
+## Notes
+
+- Reports are saved with date in filename for easy tracking
+- Reports are markdown for easy sharing and version control
+- Generate reports regularly for historical record
+- Customize report format for different audiences
+- Include reports in project documentation
+- Consider automating report generation (weekly/monthly)
+- Reports can be converted to PDF or HTML if needed
+- Keep reports in version control for history
+
+---
+
+**Namespace**: acp
+**Command**: report
+**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.resume.md

@@ -0,0 +1,239 @@
+# Command: resume
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.resume` 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**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+**Scripts**: None
+
+---
+
+**Purpose**: Resume work on a project by initializing context, reviewing recent progress, and continuing with the next task
+**Category**: Workflow
+**Frequency**: Per Session
+
+---
+
+## What This Command Does
+
+This command is a convenient alias that combines three essential workflow commands into one:
+
+1. **Initialize Context** - Loads all project documentation via `@acp.init`
+2. **Review Recent Work** - Reads the latest session report to understand what was done
+3. **Continue Work** - Proceeds with the current/next task via `@acp.proceed`
+
+**Use this when**: Starting a new session or returning to a project after a break.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists
+- [ ] Session reports exist in `agent/reports/` (optional but recommended)
+
+---
+
+## Steps
+
+### 1. Initialize Agent Context
+
+Run the initialization workflow to load complete project context.
+
+**Actions**:
+- Execute `@acp.init` workflow
+- Check for ACP updates
+- Read all agent documentation
+- Read key files from `agent/index/` (via `@acp.init` step 2.8)
+- Review key source files
+- Update stale documentation
+- Refresh progress tracking
+
+**Expected Outcome**: Complete project context loaded (including key file index)
+
+### 2. Read Latest Session Report
+
+Find and read the most recent session report to understand what was accomplished.
+
+**Actions**:
+- List files in `agent/reports/` directory
+- Find most recent report (by date in filename)
+- Read the report file
+- Summarize key accomplishments
+- Note any blockers or issues mentioned
+
+**Expected Outcome**: Recent work understood
+
+### 3. Proceed with Current/Next Task
+
+Continue work by executing the current or next task.
+
+**Actions**:
+- Execute `@acp.proceed` workflow
+- Identify current task from progress.yaml
+- Read task document
+- **START IMPLEMENTING immediately**
+- Update progress tracking
+
+**Expected Outcome**: Task implementation in progress
+
+---
+
+## Verification
+
+- [ ] Context initialized successfully
+- [ ] Latest report read and summarized
+- [ ] Current task identified
+- [ ] Implementation started
+- [ ] No errors encountered
+
+---
+
+## Expected Output
+
+### Console Output
+```
+🚀 Resuming Work on Project
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 1: Initializing Context (@acp.init)
+
+✓ ACP version check: v3.7.1 (up to date)
+✓ Read agent/progress.yaml
+✓ Read 6 design documents
+✓ Read 5 milestone documents
+✓ Read 36 task documents
+✓ Reviewed key source files
+✓ Documentation is current
+✓ Progress tracking updated
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 2: Reviewing Recent Work
+
+📋 Latest Report: agent/reports/report-2026-02-21-session-4.md
+
+Recent Accomplishments:
+- ✅ Task 34: Generic YAML parser with AST
+- ✅ Task 35: YAML parser migration
+- ✅ Created E2E test infrastructure
+- ✅ Fixed 11 critical bugs in package scripts
+- ✅ Created GitHub Pages package browser
+
+Current Status:
+- Milestone 5: Global Package Installation (0% complete)
+- Next: Task 25 - Global Infrastructure Setup
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 3: Proceeding with Next Task (@acp.proceed)
+
+📋 Current Task: task-25-global-infrastructure
+
+Objective: Create ~/.acp/ directory structure with AGENT.md and manifest.yaml
+
+[Implementation begins...]
+```
+
+---
+
+## Examples
+
+### Example 1: Resuming After Break
+
+**Context**: Haven't worked on project in a few days
+
+**Invocation**: `@acp.resume`
+
+**Result**: 
+- Loads complete context
+- Reviews last 3 sessions of work
+- Identifies current task (task-12)
+- Starts implementing task-12
+
+### Example 2: Starting New Session
+
+**Context**: Beginning work for the day
+
+**Invocation**: `@acp.resume`
+
+**Result**:
+- Initializes context
+- Shows yesterday's accomplishments
+- Continues with current task
+
+### Example 3: Switching Agents
+
+**Context**: Different AI agent picking up the project
+
+**Invocation**: `@acp.resume`
+
+**Result**:
+- Complete onboarding via @acp.init
+- Understands recent work from reports
+- Ready to contribute immediately
+
+---
+
+## Related Commands
+
+- [`@acp.init`](acp.init.md) - Initialize context only
+- [`@acp.proceed`](acp.proceed.md) - Proceed with task only
+- [`@acp.status`](acp.status.md) - Check status without proceeding
+- [`@acp.report`](acp.report.md) - Generate session report
+
+---
+
+## Troubleshooting
+
+### Issue 1: No reports found
+
+**Symptom**: Warning "No session reports found"
+
+**Cause**: No reports in agent/reports/ directory
+
+**Solution**: This is fine for new projects. The command will skip report review and proceed to task execution.
+
+### Issue 2: Context initialization fails
+
+**Symptom**: Error during @acp.init
+
+**Cause**: Missing agent/ directory or corrupted files
+
+**Solution**: Run `@acp.init` separately to see detailed error, fix issues, then run `@acp.resume` again
+
+### Issue 3: No current task
+
+**Symptom**: Error "No current task found"
+
+**Cause**: All tasks completed or progress.yaml doesn't have current task
+
+**Solution**: Review progress.yaml, create new tasks, or mark a task as in_progress
+
+---
+
+## Notes
+
+- This is a convenience command that chains three workflows
+- Equivalent to running: `@acp.init` → read reports → `@acp.proceed`
+- Saves time when starting new sessions
+- Provides comprehensive context before starting work
+- Reports are optional but highly recommended for context
+- If no reports exist, command still works (skips report review)
+
+---
+
+**Namespace**: acp
+**Command**: resume
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+**Compatibility**: ACP 3.7.0+
+**Author**: ACP Project