@prmichaelsen/remember-mcp 4.0.2 → 4.1.0

package/agent/commands/acp.plan.md

@@ -75,7 +75,33 @@ This command helps agents systematically plan project milestones and tasks. It s
 
 ## Steps
 
-### 0. Read Contextual Key Files
+### 0. Display Command Header
+
+When invoked, immediately display a brief informational header before proceeding.
+
+**Display format**:
+```
+⚡ @acp.plan
+  Plan milestones OR tasks for undefined items or new requirements
+
+  Usage:
+    @acp.plan                              Scan and plan undefined items interactively
+    @acp.plan --batch                      Plan all undefined items without prompting
+    @acp.plan --milestone <id>             Plan specific milestone
+    @acp.plan --task <id>                  Plan specific task
+    @acp.plan --draft <path>               Use specific draft file
+    @acp.plan --no-commit                  Skip automatic commit after planning
+
+  Related:
+    @acp.task-create     Create individual task documents
+    @acp.design-create   Create design documents
+    @acp.proceed         Start implementing planned tasks
+    @acp.status          Check current project status
+```
+
+**Expected Outcome**: User sees at a glance what the command does, how to customize it, and what else is available
+
+### 1. Read Contextual Key Files
 
 Before planning, load relevant key files from the index.
 
@@ -90,16 +116,19 @@ Before planning, load relevant key files from the index.
 
 **Display format**:
 ```
-📑 Reading Key Files (acp.plan)...
+📑 Reading Key Files & Context (acp.plan)...
   ✓ agent/design/acp-commands-design.md (weight: 0.9, design)
   ✓ agent/design/local.key-file-index-system.md (weight: 0.7, design)
+  📝 "Migration files MUST be numbered sequentia..." (weight: 1.0, note)
 
-  2 key files read for acp.plan context
+  2 files read, 1 inline entry loaded
 ```
 
+**Inline entries** (`path: null`): Display truncated description in quotes. Use 📝 for `kind: note`, ⚡ for `kind: directive`.
+
 **Note**: If `agent/index/` does not exist, skip silently.  
 
-### 1. Scan for Undefined Planning Items
+### 2. Scan for Undefined Planning Items
 
 Automatically scan progress.yaml for items needing planning:
 
@@ -115,7 +144,7 @@ Automatically scan progress.yaml for items needing planning:
 
 **Expected Outcome**: List of undefined items identified  
 
-### 2. Present Planning Options
+### 3. Present Planning Options
 
 Show user what can be planned and offer choices:
 
@@ -156,7 +185,7 @@ What would you like to do?
 
 **Expected Outcome**: User selects planning path  
 
-### 3. Gather Requirements
+### 4. Gather Requirements
 
 Based on user selection, gather requirements:
 
@@ -218,7 +247,7 @@ Based on user selection, gather requirements:
 
 **Expected Outcome**: Requirements gathered and clarified  
 
-### 4. Determine Planning Scope
+### 5. Determine Planning Scope
 
 Decide what to create based on requirements:
 
@@ -231,7 +260,7 @@ Decide what to create based on requirements:
 
 **Expected Outcome**: Planning scope agreed upon  
 
-### 5. Create Milestone Documents
+### 6. Create Milestone Documents
 
 For each milestone to plan:
 
@@ -249,7 +278,7 @@ For each milestone to plan:
 
 **Expected Outcome**: Milestone document(s) created  
 
-### 6. Create Task Documents
+### 7. Create Task Documents
 
 For each task in milestone:
 
@@ -270,7 +299,7 @@ For each task in milestone:
 
 **Expected Outcome**: Task documents created and organized by milestone  
 
-### 7. Update progress.yaml
+### 8. Update progress.yaml
 
 Update progress tracking with new planning items:
 
@@ -286,7 +315,7 @@ Update progress tracking with new planning items:
 
 **Expected Outcome**: progress.yaml fully updated  
 
-### 8. Generate Planning Report
+### 9. Generate Planning Report
 
 Create visual summary of what was planned:
 
@@ -334,7 +363,7 @@ Next Steps:
 
 **Expected Outcome**: User understands what was created  
 
-### 9. Commit Planning Artifacts (MANDATORY unless `--no-commit`)
+### 10. Commit Planning Artifacts (MANDATORY unless `--no-commit`)
 
 > **⚠️ CRITICAL**: This step is NOT optional unless `--no-commit` was specified. You MUST commit planning artifacts before proceeding to Step 10. Do NOT skip this step. Do NOT ask the user whether to commit. Do NOT defer the commit to a later time. Planning is not complete until artifacts are committed. If `--no-commit` was passed, skip this step silently.
 
@@ -353,7 +382,7 @@ Commit all created planning documents and progress.yaml updates.
 
 **Expected Outcome**: All planning artifacts committed to version control. `git status` shows clean working tree for planned files.  
 
-### 10. Offer Next Actions
+### 11. Offer Next Actions
 
 Prompt user for next action:
 

package/agent/commands/acp.proceed.md

@@ -16,8 +16,9 @@
 > - Follow **Autonomous Mode** section.
 > - If `--yes`, `--turbo`, or `--yolo` is present, skip the confirmation prompt (A2).
 > - If `--this` is present (or implied by `--turbo`/`--yolo`), use the task from chat context rather than scanning progress.yaml.
-> - If `--parallel` is present (or implied by `--turbo`/`--yolo`), spin up sub-agents on separate worktrees.
-> - If `--noworktreemerge` / `--holdmerge` / `--safemerge` / `--safe` is present, do NOT auto-merge worktrees; prompt user before each merge (see A10).
+> - If `--parallel` is present, spin up sub-agents to work on tasks concurrently.
+> - If `--worktrees` is present (with `--parallel`), use separate git worktrees for sub-agents. Default is **no worktrees**.
+> - If `--noworktreemerge` / `--holdmerge` / `--safemerge` / `--safe` is present, do NOT auto-merge worktrees; prompt user before each merge (see A10). Only relevant with `--worktrees`.
 > - Do NOT start implementing individual tasks until confirmation is received (unless `--yes`).
 >
 > **If `--dry-run` detected:**
@@ -79,10 +80,12 @@ This command supports both CLI-style flags and natural language arguments.
 
 | Flag | Description |
 |------|-------------|
-| `--parallel` | Spin up sub-agents on separate git worktrees to work on tasks concurrently |
+| `--parallel` | Spin up sub-agents to work on tasks concurrently (does **not** imply worktrees — see `--worktrees`) |
+| `--worktrees` | Use separate git worktrees for parallel sub-agents. Only meaningful with `--parallel`. Default: **off** |
+| `--noworktrees` | Explicitly disable worktrees (this is the default — provided for clarity) |
 | `--yes` | Skip the confirmation prompt (A2) and begin execution immediately |
 | `--dry-run` | Preview what tasks would be completed without executing |
-| `--noworktreemerge` | Do not auto-merge worktrees when sub-agents complete; prompt for permission before each merge (see A10) |
+| `--noworktreemerge` | Do not auto-merge worktrees when sub-agents complete; prompt for permission before each merge (see A10). Only meaningful with `--worktrees` |
 
 #### `--noworktreemerge` Aliases (all equivalent)
 
@@ -97,10 +100,10 @@ This command supports both CLI-style flags and natural language arguments.
 
 | Flag | Description |
 |------|-------------|
-| `--turbo` | Shorthand for `--auto --this --parallel --yes` |
+| `--turbo` | Shorthand for `--auto --this --yes` |
 | `--yolo` | Same as `--turbo` |
 
-**`--turbo` / `--yolo` expand to**: autonomous mode, targeting the current/contextual task, parallel worktree sub-agents, no confirmation prompt.  
+**`--turbo` / `--yolo` expand to**: autonomous mode, targeting the current/contextual task, no confirmation prompt. Does **not** imply `--parallel` or worktrees — add `--worktrees` explicitly if you want parallel worktree sub-agents.
 
 ### Natural Language (Fuzzy Matching)
 
@@ -115,16 +118,18 @@ The agent should detect autonomous intent from natural language following `@acp.
 | `@acp.proceed complete the milestone` | Autonomous |
 | `@acp.proceed complete all tasks` | Autonomous |
 | `@acp.proceed --dry-run` | Dry-Run |
-| `@acp.proceed --turbo` | Autonomous (parallel, no confirm, contextual task) |
+| `@acp.proceed --turbo` | Autonomous (no confirm, contextual task) |
 | `@acp.proceed --yolo` | Same as `--turbo` |
-| `@acp.proceed --yolo --safe` | Autonomous parallel, but prompt before each worktree merge |
-| `@acp.proceed --yolo hold merge` | Same as `--yolo --safe` (NLP) |
-| `@acp.proceed --yolo wait before merging` | Same as `--yolo --safe` (NLP) |
+| `@acp.proceed --yolo --worktrees` | Autonomous with parallel worktree sub-agents |
+| `@acp.proceed --yolo --worktrees --safe` | Autonomous parallel worktrees, prompt before each merge |
+| `@acp.proceed --yolo hold merge` | Same as `--yolo --worktrees --safe` (NLP) |
+| `@acp.proceed --yolo wait before merging` | Same as `--yolo --worktrees --safe` (NLP) |
 | `@acp.proceed` | Single-Task (default) |
 
 **Matching rules**:
 - Look for keywords: `complete`, `finish`, `auto`, `autonomous`, `all tasks`, `everything`, `milestone`, `turbo`, `yolo`
-- Look for `--noworktreemerge` keywords: `safe`, `hold merge`, `wait before merging`, `pause before merge`, `defer merge`, `don't auto-merge`, `gate merge`, `prompt before merge`, `no auto merge`
+- Look for `--worktrees` keywords: `worktree`, `worktrees`, `use worktrees`, `with worktrees`
+- Look for `--noworktreemerge` keywords: `safe`, `hold merge`, `wait before merging`, `pause before merge`, `defer merge`, `don't auto-merge`, `gate merge`, `prompt before merge`, `no auto merge` — these **imply `--worktrees`** (you can't gate merges without worktrees)
 - Be generous with matching — if the user's intent is clearly "do everything", enter autonomous mode
 - When in doubt, **always show the confirmation prompt** before starting autonomous execution
 - Never enter autonomous mode silently — the confirmation gate is mandatory
@@ -135,11 +140,13 @@ The agent should detect autonomous intent from natural language following `@acp.
 |-------------|----------|
 | `--complete` | Autonomous completion with per-task commits |
 | `--complete --yes` | Autonomous completion, skip confirmation prompt |
-| `--complete --parallel` | Autonomous completion with parallel worktree sub-agents |
+| `--complete --parallel` | Autonomous completion with parallel sub-agents (no worktrees unless `--worktrees`) |
+| `--complete --parallel --worktrees` | Autonomous completion with parallel worktree sub-agents |
 | `--complete --this` | Autonomous completion starting from contextual task |
-| `--turbo` / `--yolo` | `--auto --this --parallel --yes` (full autonomous, no confirm, parallel, contextual) |
-| `--yolo --safe` | Full autonomous parallel, but prompt user before each worktree merge |
-| `--complete --parallel --safe` | Autonomous parallel with merge gating |
+| `--turbo` / `--yolo` | `--auto --this --yes` (full autonomous, no confirm, contextual) |
+| `--yolo --parallel --worktrees` | Full autonomous parallel with worktree sub-agents |
+| `--yolo --worktrees --safe` | Autonomous parallel worktrees, but prompt user before each merge |
+| `--complete --parallel --worktrees --safe` | Autonomous parallel worktrees with merge gating |
 | `--complete --dry-run` | Preview task list, no execution |
 | `--dry-run` (alone) | Preview next task only |
 | `--commit` (alone) | Single-task mode, commit after completion |
@@ -197,6 +204,27 @@ When you invoke `@acp.proceed --complete` (or equivalent):
 
 ### 🚨 CRITICAL: These are IMPLEMENTATION steps, not planning steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @acp.proceed
+  Implement tasks — single-task (default) or autonomous milestone completion (with arguments)
+
+  Usage:
+    @acp.proceed                                   Implement next task (single-task)
+    @acp.proceed --complete                        Complete all remaining tasks
+    @acp.proceed --turbo                           Autonomous, no confirm, contextual
+    @acp.proceed --parallel --worktrees            Parallel sub-agents with worktrees
+    @acp.proceed --dry-run                         Preview what would be done
+
+  Related:
+    @acp.init      Load full project context first
+    @acp.status    Check which task is current
+    @git.commit    Git commit (used per-task in autonomous)
+```
+
 ### 1. Identify Current Task (30 seconds max)
 
 **Actions**:
@@ -229,13 +257,17 @@ Before implementing, load relevant key files from the index.
 
 **Display format**:
 ```
-📑 Reading Key Files (acp.proceed)...
+📑 Reading Key Files & Context (acp.proceed)...
   ✓ agent/patterns/local.e2e-testing.md (weight: 0.8, pattern)
   ✓ agent/patterns/local.tracked-untracked-directories.md (weight: 0.7, pattern)
+  📝 "Migration files MUST be numbered sequentia..." (weight: 1.0, note)
+  ⚡ "Never modify files in src/legacy/ without..." (weight: 0.9, directive)
 
-  2 key files read for acp.proceed context
+  2 files read, 2 inline entries loaded
 ```
 
+**Inline entries** (`path: null`): Display truncated description in quotes. Use 📝 for `kind: note`, ⚡ for `kind: directive`.
+
 **Note**: If `agent/index/` does not exist, skip silently. Do NOT spend excessive time here — read files quickly and move to implementation.  
 
 ### 1.7. Load Design Context
@@ -678,7 +710,7 @@ If the user sends a message during autonomous execution:
 
 When `--noworktreemerge` (or any alias: `--holdmerge`, `--safemerge`, `--safe`) is active, the agent **does NOT auto-merge worktrees** when sub-agents complete. Instead, it queues completed worktrees and prompts the user before each merge.
 
-**Why this exists**: When multiple Claude CLI instances run `--yolo` in parallel across overlapping feature areas, concurrent worktree merges create destructive conflicts. Git worktree merges involve intensive, relatively destructive commands — two inflight merges will constantly collide, produce spurious merge conflicts, and leave each agent seeing state that is inconsistent with its context. `--safe` ensures only one merge happens at a time, controlled by the user.
+**Why this exists**: When multiple Claude CLI instances run `--yolo --worktrees` in parallel across overlapping feature areas, concurrent worktree merges create destructive conflicts. Git worktree merges involve intensive, relatively destructive commands — two inflight merges will constantly collide, produce spurious merge conflicts, and leave each agent seeing state that is inconsistent with its context. `--safe` ensures only one merge happens at a time, controlled by the user.
 
 **Behavior**:
 
@@ -707,7 +739,9 @@ When `--noworktreemerge` (or any alias: `--holdmerge`, `--safemerge`, `--safe`)
 5. **On "merge all"**: Merge all `merge-ready` worktrees sequentially (one at a time, in completion order)
 6. **On "skip"**: Leave the worktree unmerged; user can merge manually or later
 
-**Without `--safe`** (default `--parallel` behavior): worktrees auto-merge as soon as each sub-agent completes. This is fine when only one agent is running, but risky with concurrent agents.
+**Without `--safe`** (default `--parallel --worktrees` behavior): worktrees auto-merge as soon as each sub-agent completes. This is fine when only one agent is running, but risky with concurrent agents.
+
+**Without `--worktrees`** (default): `--parallel` runs sub-agents in the same working directory without worktrees. This is simpler and avoids merge complexity, but sub-agents may conflict with each other on file writes.
 
 **`--safe` does NOT change**:
 - How sub-agents are spawned or how they work
@@ -889,11 +923,11 @@ Estimated: 3 hours
 
 **Result**: Implements next task, runs `@git.commit` after completion
 
-### Example 7: Yolo with Safe Merge (Multiple Agents)
+### Example 7: Yolo with Worktrees and Safe Merge (Multiple Agents)
 
 **Context**: You have 3 Claude CLI instances working on different milestones. You want parallel worktree execution but need to control when merges happen to avoid collisions.
 
-**Invocation**: `@acp.proceed --yolo --safe`
+**Invocation**: `@acp.proceed --yolo --worktrees --safe`
 
 **Result**: Sub-agents spin up on worktrees and work in parallel. When each finishes, instead of auto-merging, the agent notifies you and waits. You reply "merge" when no other agent is mid-merge, ensuring clean sequential merges.
 

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

@@ -60,6 +60,19 @@ This command creates a new **generic ACP project** (not a package) with full ACP
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.project-create
+  Create a new generic ACP project with full installation and guided setup
+
+  Related:
+    @acp.package-create      Create distributable ACP packages
+    @acp.init                Initialize context in created project
+    @acp.plan                Plan milestones and tasks
+    @acp.projects-restore    Restore projects from git origins
+```
+
 ### 1. Collect Project Information
 
 Gather project metadata via chat:

package/agent/commands/acp.project-info.md

@@ -36,6 +36,23 @@ Unlike [`@acp.project-list`](acp.project-list.md:1) which shows all projects in
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.project-info
+  Display detailed information about a specific project
+
+  Usage:
+    @acp.project-info <project-name>               Show project details
+
+  Related:
+    @acp.project-list        List all projects in registry
+    @acp.project-set         Switch to a project
+    @acp.project-update      Update project metadata
+    @acp.projects-sync       Sync registry with filesystem
+    @acp.projects-restore    Restore projects from git origins
+```
+
 ### 1. Validate Arguments
 
 Check that project name is provided.

package/agent/commands/acp.project-list.md

@@ -36,6 +36,25 @@ Lists all projects registered in `~/.acp/projects.yaml` with their metadata. Sho
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.project-list
+  List all projects registered in global workspace
+
+  Usage:
+    @acp.project-list                              List all projects
+    @acp.project-list --type <type>                Filter by project type
+    @acp.project-list --status <status>            Filter by status
+
+  Related:
+    @acp.project-create      Create new project
+    @acp.project-set         Switch to project
+    @acp.projects-sync       Discover unregistered projects
+    @acp.project-info        Show project details
+    @acp.projects-restore    Restore projects from git origins
+```
+
 ### 1. Run Shell Script
 
 Execute the project list script with optional filters.

package/agent/commands/acp.project-remove.md

@@ -45,6 +45,24 @@ The command includes safety features:
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.project-remove
+  Remove a project from the global registry with optional directory deletion
+
+  Usage:
+    @acp.project-remove <name>                     Remove from registry only
+    @acp.project-remove <name> --delete-files       Also delete project directory
+    @acp.project-remove <name> -y                   Skip confirmation prompts
+
+  Related:
+    @acp.project-list        List all projects
+    @acp.project-set         Switch to another project
+    @acp.project-info        Show project details
+    @acp.project-update      Update project metadata
+```
+
 ### 1. Run Shell Script
 
 Execute the project-remove script with the project name and options.

package/agent/commands/acp.project-set.md

@@ -44,6 +44,22 @@ After running this command, all subsequent file operations will be relative to t
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.project-set
+  Switch to a different project in the global registry
+
+  Usage:
+    @acp.project-set <project-name>                Switch to project
+
+  Related:
+    @acp.project-list        List all projects
+    @acp.project-info        Show project details
+    @acp.project-create      Create new project
+    @acp.init                Load project context
+```
+
 ### 1. Run Shell Script
 
 Execute the project-set script with the project name.

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

@@ -36,6 +36,28 @@ Unlike [`@acp.project-info`](acp.project-info.md:1) which displays information,
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.project-update
+  Update project metadata in the global registry
+
+  Usage:
+    @acp.project-update <name> --status <status>   Update project status
+    @acp.project-update <name> --description "..."  Update description
+    @acp.project-update <name> --add-tag <tag>      Add a tag
+    @acp.project-update <name> --remove-tag <tag>   Remove a tag
+    @acp.project-update <name> --git-origin <url>   Set git origin URL
+    @acp.project-update <name> --add-related <name> Link related project
+
+  Related:
+    @acp.project-info        View project details before updating
+    @acp.project-list        List all projects
+    @acp.project-set         Switch to a project
+    @acp.projects-sync       Sync registry with filesystem
+    @acp.projects-restore    Restore projects from git origins
+```
+
 ### 1. Parse Arguments
 
 Extract project name and update options.

package/agent/commands/acp.projects-restore.md

@@ -42,6 +42,24 @@ This command reads `~/.acp/projects.yaml` and clones any missing project directo
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.projects-restore
+  Restore/clone missing projects from their registered git origins
+
+  Usage:
+    @acp.projects-restore                          Restore all missing projects
+    @acp.projects-restore --dry-run                Preview what would be cloned
+    @acp.projects-restore --install-acp            Restore and install ACP
+
+  Related:
+    @acp.projects-sync       Discover and register unregistered projects
+    @acp.project-list        List all registered projects
+    @acp.project-info        View project details including git info
+    @acp.project-update      Manually set git_origin/git_branch
+```
+
 ### 1. Execute Restore Script
 
 Run the shell script to restore missing projects.

package/agent/commands/acp.projects-sync.md

@@ -43,6 +43,20 @@ This command scans the `~/.acp/projects/` directory for ACP projects (directorie
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.projects-sync
+  Discover unregistered ACP projects and add them to the registry
+
+  Related:
+    @acp.project-list        List all registered projects
+    @acp.project-info        View project details
+    @acp.project-set         Switch to a project
+    @acp.project-create      Create new project (auto-registers)
+    @acp.projects-restore    Restore projects from git origins
+```
+
 ### 1. Execute Sync Script
 
 Run the shell script to scan for unregistered projects.

package/agent/commands/acp.report.md

@@ -39,6 +39,21 @@ Unlike `@acp.status` which provides a quick console summary, `@acp.report` gener
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.report
+  Generate a comprehensive project status report including progress, accomplishments, and next steps
+
+  Related:
+    @acp.status    Quick console status (not a full report)
+    @acp.update    Update progress before generating report
+    @acp.validate  Validate documentation before reporting
+    @acp.sync      Sync docs before generating report
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Read Project Information
 
 Load basic project details from progress.yaml.

package/agent/commands/acp.resume.md

@@ -41,6 +41,21 @@ This command is a convenient alias that combines three essential workflow comman
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.resume
+  Resume work by initializing context, reviewing progress, and continuing next task
+
+  Related:
+    @acp.init      Initialize context only
+    @acp.proceed   Proceed with task only
+    @acp.status    Check status without proceeding
+    @acp.report    Generate session report
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Initialize Agent Context
 
 Run the initialization workflow to load complete project context.

package/agent/commands/acp.sessions.md

@@ -73,6 +73,27 @@ Use this command when you want to see what other agents are working on, check if
 
 ## Steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @acp.sessions
+  Manage and view active agent sessions across projects
+
+  Usage:
+    @acp.sessions                                  List all active sessions
+    @acp.sessions clean                            Remove stale sessions
+    @acp.sessions deregister                       End current session
+    @acp.sessions count                            Output active session count
+    @acp.sessions --project <name>                 Filter by project name
+
+  Related:
+    @acp.init      Registers session at start
+    @acp.status    Shows session count in status
+    @acp.report    Deregisters session at end
+```
+
 ### 1. Parse Arguments
 
 Determine the requested action from CLI flags or natural language.

package/agent/commands/acp.status.md

@@ -36,6 +36,21 @@ Unlike `@acp-init` which performs a full context load and updates documentation,
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.status
+  Display current project status including milestone progress, current task, recent work, and next steps
+
+  Related:
+    @acp.init      Full context initialization at session start
+    @acp.proceed   Continue with current task
+    @acp.update    Update progress.yaml after completing work
+    @acp.sync      Sync documentation with code changes
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Read Progress Tracking
 
 Read the `agent/progress.yaml` file to get current project state.

package/agent/commands/acp.sync.md

@@ -39,6 +39,21 @@ Unlike `@acp.update` which updates progress tracking, `@acp.sync` focuses on kee
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.sync
+  Synchronize documentation with source code by identifying and updating stale documentation
+
+  Related:
+    @acp.update    Update progress tracking (not documentation)
+    @acp.validate  Validate documentation structure and consistency
+    @acp.init      Includes sync as part of initialization
+    @acp.report    Generate report including documentation status
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Read Design Documents
 
 Load all design documents to understand documented architecture.

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

@@ -65,6 +65,27 @@ This command creates a new task file with proper structure, milestone linking, a
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.task-create
+  Create task files with proper structure, milestone linking, and automatic progress.yaml updates
+
+  Usage:
+    @acp.task-create                               Guided task creation
+    @acp.task-create @my-draft.md                  Create from draft file
+    @acp.task-create --from-clar <file>            Capture from specific clarification
+    @acp.task-create --from-context                Capture from all sources
+
+  Related:
+    @acp.pattern-create    Create patterns
+    @acp.command-create    Create commands
+    @acp.design-create     Create designs
+    @acp.proceed           Start working on created task
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Detect Current Milestone
 
 Determine which milestone this task belongs to:

package/agent/commands/acp.update.md

@@ -38,6 +38,21 @@ Unlike `@acp.sync` which updates documentation based on code changes, `@acp.upda
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.update
+  Update progress.yaml with latest project status, task completion, and recent work
+
+  Related:
+    @acp.status    View current status before updating
+    @acp.proceed   Automatically updates progress after tasks
+    @acp.sync      Update documentation based on code changes
+    @acp.report    Generate comprehensive progress report
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Read Current Progress
 
 Read `agent/progress.yaml` to understand current state.