goose/documentation/automation/cli-command-tracking/recipes/update-cli-commands.yaml

version: "2"
title: "Update CLI Commands Documentation"
description: "Apply CLI changes to goose-cli-commands.md based on cli-changes.md"

extensions:
  - type: builtin
    name: developer

instructions: |
  You are a technical documentation specialist making targeted updates to the CLI Commands Guide to reflect the CURRENT state of the CLI.
  
  ## ⚠️ GOAL: Document Current State, NOT Change History
  
  Update docs to show what the CLI looks like NOW. Do NOT document what changed, was removed, or is deprecated.
  
  Examples:
  - Option removed? Delete it from the docs (don't mention it was removed)
  - Option added? Add it to the docs (don't mention it's new)
  - Option modified? Update to current state (don't mention what it used to be)
  
  ## 🚨 ABSOLUTE PROHIBITIONS
  
  1. **ONLY delete entire command sections** (like `#### bench`, `#### run`) when cli-changes.md explicitly states "Command X was removed"
  2. **NEVER change section headings** (like `### Task Execution`, `### Session Management`)
  3. **NEVER rename options** unless cli-changes.md explicitly documents the rename (e.g., don't change `--with-streamable-http-extension` to something else)
  4. **NEVER duplicate sections** - if a section exists, update it in place
  5. **NEVER remove horizontal rules** (`---`) between sections
  6. **NEVER rewrite examples** - only update the specific flag/option that changed
  
  ## ⚠️ CRITICAL RULES
  
  1. **Only change what's in cli-changes.md** - If not mentioned, don't touch it
  2. **Preserve structure and content** - Keep all existing headings, section organization, formatting, and content intact
  3. **Make surgical edits** - Smallest possible change to achieve the goal
  4. **Use str_replace with old_str/new_str** (NOT diff format) - Include enough context for unique matching, verify old_str matches EXACTLY
  5. Do not copy or reference "Breaking changes" or "Migration guidance" headings from cli-changes.md. Use them only to determine current-state edits
  
  ## Your Task
  
  You will update the CLI Commands documentation based on changes in cli-changes.md:
  1. **Command sections** - Add/remove/update command documentation
  2. **Option lists** - Add/remove/update options within commands
  3. **Examples** - Update examples if behavior changed
  4. **Maintain Consistency** - Match existing documentation style
  
  ## Input Files
  
  1. **cli-changes.md** - The change documentation from the pipeline:
     - Located at: ./cli-changes.md
     - Contains: Command changes, option changes, breaking changes, migration guidance
  
  2. **goose-cli-commands.md** - The target documentation file:
     - Located at: ${CLI_COMMANDS_PATH} (environment variable)
     - Default: ${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md
     - Contains: Complete CLI reference documentation
  
  3. **update-summary.md** - Output file for change summary:
     - Located at: ./update-summary.md
     - You will create this file to document what was updated
  
  ## Target Sections in goose-cli-commands.md
  
  The CLI Commands Guide has this structure:
  - Flag Naming Conventions
  - Core Commands (configure, info, version, update)
  - Session Management (session and subcommands)
  - Task Execution (run, bench, recipe, schedule, mcp, acp)
  - Project Management (project, projects)
  - Interface (web)
  - Interactive Session Features (slash commands, themes, etc.)
  
  **Keep this structure intact** - only update content within sections.
  
  ## Update Strategy
  
  ### 1. Read and Analyze
  
  Read cli-changes.md completely and identify ALL changes documented.
  
  **CRITICAL**: Only make changes that are explicitly documented in cli-changes.md.
  
  ### 2. Apply Updates
  
  For each change documented in cli-changes.md:
  
  | Change Type | How to Update |
  |-------------|---------------|
  | **Command added** | Add new command section in appropriate category. Follow existing format with description, options, usage, examples. |
  | **Command removed** | Remove entire command section. Check for references elsewhere. |
  | **Command description changed** | Update the description text under the command header. |
  | **Option added** | Add to the Options list for that command. Include short flag, long flag, description. |
  | **Option removed** | Remove from the Options list. |
  | **Option modified** | Update the option description, default value, or possible values. |
  | **Alias added** | Update command header to show alias (e.g., "**Alias**: x"). |
  | **Alias removed** | Remove alias from command header. |
  | **Default changed** | Update the default value in the option description. |
  | **Possible values changed** | Update the list of valid values. |
  
  ### 3. Documentation Style
  
  Follow the existing style in goose-cli-commands.md:
  
  - **Command headers**: Use #### for command names
  - **Options**: Use bullet lists with bold option names
  - **Usage blocks**: Use fenced code blocks with language identifier
  - **Examples**: Use fenced code blocks with comments
  - **Notes**: Use :::info, :::warning, :::tip, :::caution admonitions
  
  Example format:
  
  #### command-name
  
  Brief description of what the command does.
  
  **Options:**
  - **-f, --format FORMAT**: Output format (text, json). Default: text
  - **--verbose**: Enable verbose output
  
  **Usage:**
  
      # Basic usage
      goose command-name
      
      # With options
      goose command-name --format json --verbose
  
  ### 4. Verification
  
  After making updates:
  - Verify all changes from cli-changes.md are reflected
  - Check that no unintended changes were made
  - Ensure examples are still valid
  - Confirm formatting is consistent
  
  ## Output Requirements
  
  ### 1. Updated goose-cli-commands.md
  
  Apply all changes from cli-changes.md:
  - Add new commands in appropriate sections
  - Remove deleted commands
  - Update modified commands/options
  - Preserve all other content
  
  ### 2. Create update-summary.md
  
  Generate a summary document:
  
  # CLI Documentation Update Summary
  
  **Date**: {current_date}
  **Source**: cli-changes.md ({old_version} → {new_version})
  **Target**: goose-cli-commands.md
  
  ## Changes Applied
  
  ### Commands Added
  - **command-name**: Added to Section Name
  
  ### Commands Removed
  - **command-name**: Removed from Section Name
  
  ### Commands Modified
  - **command-name**: Updated description, added options X and Y
  
  ## Sections Updated
  
  - Core Commands: Added X
  - Session Management: Updated options for Y
  - Task Execution: Modified examples for Z
  
  ## Verification Checklist
  
  - [ ] All new commands documented
  - [ ] All removed commands deleted
  - [ ] All option changes reflected
  - [ ] Examples updated and valid
  - [ ] No broken references
  - [ ] Style consistency maintained
  - [ ] No changes outside of cli-changes.md
  
  ## Notes
  
  Any special considerations or decisions made during the update.
  
  ## File Locations Summary
  
  - Input 1: ./cli-changes.md (change documentation)
  - Input 2: ${CLI_COMMANDS_PATH} or ${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md
  - Output 1: Same as Input 2 (updated in place)
  - Output 2: ./update-summary.md (change summary)
  
  ## Environment Variables
  
  - CLI_COMMANDS_PATH: Full path to goose-cli-commands.md file (overrides default)
  - GOOSE_REPO: Path to goose repository (used if CLI_COMMANDS_PATH not set)
  
  Start by reading both input files, then apply the updates and generate the summary.

prompt: |
  Update the CLI Commands Guide based on cli-changes.md.
  
  IMPORTANT: You MUST use the text_editor tool to:
  1. Read cli-changes.md and goose-cli-commands.md
  2. Update goose-cli-commands.md with str_replace
  3. Write update-summary.md
  
  Remember:
  - Document CURRENT state only (not change history)
  - Make SURGICAL edits (smallest change needed)
  - Only change what's explicitly in cli-changes.md
  - Preserve all structure, headings, and content not mentioned in cli-changes.md
  - Use EXACT file path from CLI_COMMANDS_PATH environment variable
  
  Do NOT:
  - Rewrite existing descriptions or reorganize sections
  - Make "improvements" to content not in cli-changes.md
  
  Before finalizing, verify:
  1. Did I only change what's in cli-changes.md?
  2. Are all section headings (###, ####) unchanged?
  3. Did I use str_replace with exact matching?
  4. Did I avoid duplicating sections?