@prmichaelsen/acp-visualizer 0.1.0

package/agent/commands/acp.sessions.md

@@ -0,0 +1,301 @@
+# Command: sessions
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.sessions` has been invoked. Follow the steps below to execute this command.
+> Pretend this command was entered with this additional context: "Execute directive `@acp-sessions` 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."
+>
+> **STEP 0: CHECK FOR ARGUMENTS FIRST.**
+> If arguments or natural language follow `@acp.sessions`, detect the subcommand before doing anything else.
+> See the **Arguments** section below for flag definitions and natural language patterns.
+> If no arguments, default to `list`.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-03-01
+**Last Updated**: 2026-03-01
+**Status**: Active
+**Scripts**: acp.sessions.sh, acp.common.sh, acp.yaml-parser.sh
+
+---
+
+**Purpose**: Manage and view active agent sessions across projects
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## Arguments
+
+This command supports both CLI-style flags and natural language arguments.
+
+**CLI-Style Arguments**:
+- `list` (default) — list all active sessions
+- `clean` — remove stale sessions (dead PIDs, timed out)
+- `deregister` — end current session
+- `count` — output number of active sessions
+- `--project <name>` — filter by project name (used with `list`)
+- `--id <session-id>` — target specific session (used with `deregister`)
+
+**Natural Language Arguments**:
+- "what's running?" → list
+- "show remember-core" → list --project remember-core
+- "stop my session" → deregister
+- "clean up" → clean
+- "how many sessions?" → count
+- "what's active?" → list
+- "end session" → deregister
+
+**Argument Mapping**:
+The agent infers intent from context:
+1. Parse explicit CLI-style subcommands/flags if present
+2. Extract intent from natural language keywords: `running`, `active`, `stop`, `end`, `clean`, `how many`, `count`
+3. Project names after `show` or `for` map to `--project` filter
+4. Default to `list` if no subcommand is detected
+
+---
+
+## What This Command Does
+
+This command provides a user-friendly interface for managing agent sessions tracked in `~/.acp/sessions.yaml`. It wraps the `acp.sessions.sh` script subcommands with NLP argument parsing and formatted output.
+
+Sessions are registered when `@acp.init` runs and deregistered when `@acp.report` runs. Between those, this command lets you see what's active, clean stale sessions, or manually end a session.
+
+Use this command when you want to see what other agents are working on, check if stale sessions need cleanup, or manage your current session. The default behavior (`list`) always runs stale cleanup first to show accurate state.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `./agent/scripts/acp.sessions.sh` exists and is executable
+
+---
+
+## Steps
+
+### 1. Parse Arguments
+
+Determine the requested action from CLI flags or natural language.
+
+**Actions**:
+- Check for explicit subcommand: `list`, `clean`, `deregister`, `count`
+- Check for `--project` and `--id` flags
+- Apply natural language mapping if no explicit subcommand
+- Default to `list` if no subcommand detected
+
+**Expected Outcome**: Subcommand and options determined
+
+### 2. Run Stale Cleanup
+
+Always clean stale sessions before displaying results.
+
+**Actions**:
+- Run `./agent/scripts/acp.sessions.sh clean` (silently, unless `clean` is the explicit subcommand)
+- This removes sessions with dead PIDs or inactive for 2+ hours
+
+**Expected Outcome**: Stale sessions removed
+
+### 3. Execute Requested Subcommand
+
+Run the appropriate `acp.sessions.sh` subcommand.
+
+**Actions**:
+- **list** (default): Run `./agent/scripts/acp.sessions.sh list [--project <name>]`
+- **clean**: Run `./agent/scripts/acp.sessions.sh clean` (verbose output)
+- **deregister**: Run `./agent/scripts/acp.sessions.sh deregister [--id <session-id>]`
+- **count**: Run `./agent/scripts/acp.sessions.sh count`
+
+**Expected Outcome**: Subcommand executed successfully
+
+### 4. Display Formatted Output
+
+Present results in a clear format.
+
+**List output**:
+```
+Active Sessions (3):
+
+  sess_a1b2c3  remember-core
+               Task 12: Implement Auth Middleware
+               Started 45m ago, last active 2m ago
+
+  sess_d4e5f6  agent-context-protocol  (this session)
+               Task 91: Sessions Infrastructure
+               Started 10m ago, last active now
+
+  sess_g7h8i9  agentbase.me
+               Task 5: Fix API Routes
+               Started 1h ago, last active 20m ago
+```
+
+**Clean output**:
+```
+Cleaned 2 stale sessions:
+  sess_x1y2z3  old-project (PID 12345 not running)
+  sess_m4n5o6  test-project (inactive for 3h)
+
+Active sessions remaining: 3
+```
+
+**Deregister output**:
+```
+Session sess_a1b2c3 deregistered.
+Active sessions remaining: 2
+```
+
+**Count output**:
+```
+3
+```
+
+**Expected Outcome**: User sees formatted session information
+
+### 5. Suggest Next Actions
+
+If relevant, suggest follow-up actions.
+
+**Actions**:
+- If sessions are stale: "Run `@acp.sessions clean` to remove stale sessions"
+- If no sessions: "Run `@acp.init` to register a new session"
+- If showing list: No suggestions needed (informational)
+
+**Expected Outcome**: User knows what to do next (if applicable)
+
+---
+
+## Verification
+
+- [ ] Arguments parsed correctly (CLI or NLP)
+- [ ] Stale cleanup ran before list/count
+- [ ] Subcommand executed with correct flags
+- [ ] Output formatted clearly
+- [ ] Edge cases handled (no sessions, missing script)
+
+---
+
+## Expected Output
+
+### Files Modified
+- `~/.acp/sessions.yaml` — updated by clean/deregister subcommands
+
+### Console Output
+See output formats in Step 4 above.
+
+---
+
+## Examples
+
+### Example 1: List All Sessions (Default)
+
+**Context**: You want to see what's currently running
+
+**Invocation**: `@acp.sessions`
+
+**Result**: Shows all active sessions with project, description, and timing info
+
+### Example 2: Filter by Project
+
+**Context**: You want to see sessions for a specific project
+
+**Invocation**: `@acp.sessions --project remember-core`
+
+**Result**: Shows only sessions for remember-core
+
+### Example 3: Clean Stale Sessions
+
+**Context**: You suspect some sessions are stale
+
+**Invocation**: `@acp.sessions clean`
+
+**Result**: Removes dead-PID and timed-out sessions, shows what was cleaned
+
+### Example 4: Natural Language Usage
+
+**Context**: You want to check what's running using natural language
+
+**Invocation**: `@acp.sessions what's running?`
+
+**Result**: Same as `@acp.sessions list` — shows all active sessions
+
+### Example 5: End Current Session
+
+**Context**: You're done working and want to deregister
+
+**Invocation**: `@acp.sessions stop my session`
+
+**Result**: Deregisters the current session, shows remaining count
+
+---
+
+## Related Commands
+
+- [`@acp.init`](acp.init.md) — Registers session automatically at start
+- [`@acp.status`](acp.status.md) — Shows session count in status output
+- [`@acp.report`](acp.report.md) — Deregisters session automatically at end
+
+---
+
+## Troubleshooting
+
+### Issue 1: "acp.sessions.sh not found"
+
+**Symptom**: Command reports script not found
+
+**Cause**: Sessions script not installed or path incorrect
+
+**Solution**: Verify `./agent/scripts/acp.sessions.sh` exists and is executable. Run `chmod +x agent/scripts/acp.sessions.sh` if needed.
+
+### Issue 2: Sessions disappear immediately
+
+**Symptom**: Registered sessions are gone on next list
+
+**Cause**: Stale cleanup removing sessions because the registering process PID is dead
+
+**Solution**: Use `--pid <pid>` when registering to track the long-lived parent process (terminal/agent) instead of the script's own PID.
+
+### Issue 3: "No active sessions" when sessions should exist
+
+**Symptom**: List shows no sessions despite recent registration
+
+**Cause**: Sessions were registered under a different process tree and stale cleanup removed them
+
+**Solution**: Re-register with `@acp.init` or manually via `./agent/scripts/acp.sessions.sh register --project <name> --pid <pid>`
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `~/.acp/sessions.yaml`
+- **Writes**: `~/.acp/sessions.yaml` (clean, deregister modify the file)
+- **Executes**: `./agent/scripts/acp.sessions.sh`
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not access secrets or credentials
+- **Credentials**: Does not access credentials files
+- **PIDs**: Stores process IDs for stale detection (not sensitive)
+
+---
+
+## Notes
+
+- Mark current session with "(this session)" indicator in list output
+- NLP parsing should be forgiving — "sessions", "what's active", "running" all map to list
+- Always run `clean` before `list` to show accurate state
+- Sessions are advisory only — no locking or coordination
+- `~/.acp/sessions.yaml` is auto-created on first register
+
+---
+
+**Namespace**: acp
+**Command**: sessions
+**Version**: 1.0.0
+**Created**: 2026-03-01
+**Last Updated**: 2026-03-01
+**Status**: Active
+**Compatibility**: ACP 5.9.1+
+**Author**: ACP Project

package/agent/commands/acp.status.md

@@ -0,0 +1,293 @@
+# Command: status
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-status` 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**: None
+
+---
+
+**Purpose**: Display current project status including milestone progress, current task, recent work, and next steps
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command provides a comprehensive overview of the current project status by reading `agent/progress.yaml` and presenting key information in an organized format. It shows where the project stands, what's been accomplished recently, and what needs to be done next.
+
+Use this command when you need to quickly understand the current state of the project without performing a full initialization. It's ideal for checking progress during a session, before starting new work, or when reporting status to stakeholders.
+
+Unlike `@acp-init` which performs a full context load and updates documentation, `@acp-status` is a read-only operation that simply reports the current state as recorded in progress tracking.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/progress.yaml` exists and is up to date
+
+---
+
+## Steps
+
+### 1. Read Progress Tracking
+
+Read the `agent/progress.yaml` file to get current project state.
+
+**Actions**:
+- Open and parse `agent/progress.yaml`
+- Extract key information: current milestone, current task, progress percentages
+- Note any errors or missing data
+
+**Expected Outcome**: Progress data loaded successfully
+
+### 2. Display Current Milestone
+
+Show the current milestone information.
+
+**Actions**:
+- Display milestone ID and name
+- Show milestone progress percentage
+- Show tasks completed vs total tasks
+- Display milestone status (not_started, in_progress, completed)
+
+**Expected Outcome**: User sees current milestone summary
+
+### 3. Display Current Task
+
+Show the current task being worked on.
+
+**Actions**:
+- Display task ID and name
+- Show task status
+- Display task file path
+- Show estimated hours and completion date (if completed)
+
+**Expected Outcome**: User sees current task details
+
+### 4. Display Recent Work
+
+List recent work completed.
+
+**Actions**:
+- Show recent work entries from `progress.yaml`
+- Display dates and descriptions
+- Show completed items with checkmarks
+
+**Expected Outcome**: User sees what was recently accomplished
+
+### 5. Display Next Steps
+
+Show what needs to be done next.
+
+**Actions**:
+- List next steps from `progress.yaml`
+- Prioritize by order in the list
+- Highlight any urgent items
+
+**Expected Outcome**: User knows what to work on next
+
+### 5.5. Display Active Sessions (Optional)
+
+Show the count of active agent sessions.
+
+**Actions**:
+- If `./agent/scripts/acp.sessions.sh` exists, run `./agent/scripts/acp.sessions.sh count`
+- Display: `"Sessions: N active"` in status output
+
+**Expected Outcome**: Session count displayed
+
+**Note**: If `./agent/scripts/acp.sessions.sh` does not exist, omit the Sessions line.
+
+### 6. Display Blockers
+
+Show any current blockers or issues.
+
+**Actions**:
+- List current blockers from `progress.yaml`
+- Highlight critical blockers
+- Note if no blockers exist
+
+**Expected Outcome**: User is aware of any obstacles
+
+---
+
+## Verification
+
+- [ ] `agent/progress.yaml` read successfully
+- [ ] Current milestone displayed with progress percentage
+- [ ] Current task displayed with status
+- [ ] Recent work listed (if any exists)
+- [ ] Next steps listed
+- [ ] Blockers displayed (or noted as none)
+- [ ] Output is clear and well-formatted
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a read-only command
+
+### Console Output
+```
+📊 Project Status
+
+Project: example-project (v0.1.0)
+Status: in_progress
+Started: 2026-01-15
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📍 Current Milestone: M1 - Foundation
+Progress: 40% (2/5 tasks completed)
+Status: in_progress
+Started: 2026-01-15
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Current Task: task-3-implement-core-logic
+Status: in_progress
+File: agent/tasks/task-3-implement-core-logic.md
+Estimated: 4 hours
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Recent Work:
+  2026-02-15:
+    - ✅ Completed task-2 (database setup)
+    - ✅ Updated progress tracking
+    - 📋 Started task-3
+
+  2026-02-14:
+    - ✅ Completed task-1 (project structure)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 Next Steps:
+  1. Complete task-3 (implement core logic)
+  2. Begin task-4 (add tests)
+  3. Review milestone-1 success criteria
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️  Current Blockers:
+  None
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall Progress: 35% complete
+```
+
+### Status Update
+No status changes - read-only operation
+
+---
+
+## Examples
+
+### Example 1: Checking Status Mid-Session
+
+**Context**: You're in the middle of working and want to see where things stand
+
+**Invocation**: `@acp-status`
+
+**Result**: Displays current milestone (M1, 40% complete), current task (task-3, in progress), recent work (completed task-2 yesterday), and next steps (finish task-3, start task-4)
+
+### Example 2: Starting a New Session
+
+**Context**: Beginning work after a break, want to see project state before diving in
+
+**Invocation**: `@acp-status`
+
+**Result**: Shows you're on milestone 2, 60% through, currently on task-7, with 3 tasks completed this week and 2 blockers to address
+
+### Example 3: Reporting to Stakeholders
+
+**Context**: Need to provide a quick status update
+
+**Invocation**: `@acp-status`
+
+**Result**: Clean, formatted output showing overall progress (65%), current phase (Testing), and upcoming milestones
+
+---
+
+## Related Commands
+
+- [`@acp-init`](acp.init.md) - Use for full context initialization at session start
+- [`@acp-proceed`](acp.proceed.md) - Use after checking status to continue with current task
+- [`@acp-update`](acp.update.md) - Use to update progress.yaml after completing work
+- [`@acp-sync`](acp.sync.md) - Use to sync documentation with code changes
+
+---
+
+## Troubleshooting
+
+### Issue 1: progress.yaml not found
+
+**Symptom**: Error message "Cannot read file: agent/progress.yaml"
+
+**Cause**: Progress tracking file doesn't exist yet
+
+**Solution**: Create progress.yaml from template: `cp agent/progress.template.yaml agent/progress.yaml`, then fill in initial project information
+
+### Issue 2: Empty or incomplete output
+
+**Symptom**: Status shows "No data" or missing sections
+
+**Cause**: progress.yaml is not properly filled out
+
+**Solution**: Review progress.yaml and ensure all required fields are populated (project name, current milestone, current task, etc.)
+
+### Issue 3: Outdated information displayed
+
+**Symptom**: Status shows old task or milestone that's already completed
+
+**Cause**: progress.yaml hasn't been updated after recent work
+
+**Solution**: Run `@acp-update` to refresh progress tracking, or manually update progress.yaml
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `agent/progress.yaml` only
+- **Writes**: None (read-only command)
+- **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 is a read-only command that doesn't modify any files
+- For best results, keep `agent/progress.yaml` up to date
+- Use `@acp-update` after completing tasks to ensure status is accurate
+- Status output is designed to be human-readable and suitable for reports
+- Can be run multiple times per session without side effects
+- Faster than `@acp-init` since it only reads one file
+
+---
+
+**Namespace**: acp
+**Command**: status
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.0.3+
+**Author**: ACP Project