chore: remove unused GitHub workflow (#13071)

This commit is contained in:
Lifei Zhou
2026-10-22 22:18:29 +00:00
committed by GitHub
parent b89ab563a0
commit 9d408a446c
18 changed files with 4 additions and 3463 deletions
-44
View File
@@ -1,44 +0,0 @@
version: "1.0.0"
title: GitHub PR Code Review
description: Perform a code review of a GitHub pull request.
parameters:
- key: pr_directory
input_type: string
requirement: required
description: Path to the directory with pr.md and pr.diff
- key: instructions
input_type: string
requirement: required
description: Specific instructions for the code review.
extensions:
- type: builtin
name: developer
- type: stdio
name: code_review
cmd: uv
args:
- run
- '{{ recipe_dir }}/../scripts/pr-review-mcp.py'
prompt: |
Review the code changes downloaded from a GitHub pull request.
The PR metadata is located at {{ pr_directory }}/pr.md.
The proposed diff you are to review is located at {{ pr_directory }}/pr.diff.
The base branch is checked out in the working directory.
Use the tools you have to review the diff and examine the code changes and context.
Use the code review tools to add feedback on specific parts of the diff.
There is no need to call the finish_review tool unless absolutely necessary to add
summary content not covered by inline comments.
Be concise with your comments. Just a few sentences per comment at most, with no
extra formatting. Just the gist of the problem is enough.
** Important **
Don't add nit-pick comments and avoid matters of opinion.
Adhere closely to the code review instructions below.
Don't add add feedback outside the scope of the instructions below.
# Code review instructions
{{ instructions }}
-67
View File
@@ -1,67 +0,0 @@
# This is a reusable workflow that builds the CLI for multiple platforms.
#
# Platform Build Strategy:
# - Linux standard (x86_64 + aarch64): Builds inside manylinux_2_28 container for glibc 2.28+ compat
# - Linux Vulkan: Uses native Ubuntu 24.04 runners for newer Vulkan headers/tooling
# - Linux musl: Uses native Ubuntu 22.04 runners with reduced features for musl compatibility
# - macOS: Uses bundle-macos.yml to package CLI artifacts without Desktop
# - Windows: Uses bundle-windows.yml to package CLI artifacts without Desktop
on:
workflow_call:
inputs:
version:
required: false
default: ""
type: string
ref:
type: string
required: false
default: ""
name: "Reusable workflow to build CLI"
jobs:
build-cli-macos:
strategy:
fail-fast: false
matrix:
target:
- x86_64-apple-darwin
- aarch64-apple-darwin
uses: ./.github/workflows/bundle-macos.yml
permissions:
contents: read
with:
version: ${{ inputs.version }}
ref: ${{ inputs.ref }}
target: ${{ matrix.target }}
signing: false
package_cli: true
package_desktop: false
build-cli-windows:
strategy:
fail-fast: false
matrix:
windows_variant:
- standard
- cuda
uses: ./.github/workflows/bundle-windows.yml
permissions:
contents: read
with:
version: ${{ inputs.version }}
ref: ${{ inputs.ref }}
signing: false
package_cli: true
package_desktop: false
windows_variant: ${{ matrix.windows_variant }}
build-cli-linux:
uses: ./.github/workflows/build-cli-linux.yml
permissions:
contents: read
with:
version: ${{ inputs.version }}
ref: ${{ inputs.ref }}
package_desktop: false
-210
View File
@@ -1,210 +0,0 @@
name: Code Review
on:
workflow_dispatch:
inputs:
pr_number:
description: 'PR number to review'
required: true
type: number
oidc_proxy_url:
description: 'OIDC proxy URL (overrides repo variable)'
required: false
type: string
review_instructions:
description: 'Instructions for the code review'
required: false
default: 'Review the changes for correctness'
type: string
# pull_request_target:
# types: [opened, synchronize, reopened]
concurrency:
group: code-review-${{ github.event.pull_request.number || github.event.inputs.pr_number }}
cancel-in-progress: true
jobs:
prepare:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
pull-requests: read
steps:
- name: Mint OIDC token
id: oidc
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
TOKEN_AUDIENCE: goose-oidc-proxy
with:
script: |
const token = await core.getIDToken(process.env.TOKEN_AUDIENCE);
core.setOutput('token', token);
core.setSecret(token);
- name: Gather PR metadata and diff
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
PR_NUMBER=${{ github.event.pull_request.number || github.event.inputs.pr_number }}
mkdir -p /tmp/code-review
gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json title --jq '.title' > /tmp/code-review/title.txt
gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json body --jq '.body // "(no description)"' > /tmp/code-review/body.txt
gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefOid --jq '.headRefOid' > /tmp/code-review/commit_id.txt
gh pr diff "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" > /tmp/code-review/pr.diff
TITLE=$(cat /tmp/code-review/title.txt)
BODY=$(cat /tmp/code-review/body.txt)
printf '# %s\n\n## Description\n\n%s\n' "$TITLE" "$BODY" > /tmp/code-review/pr.md
- name: Write OIDC token to file
run: echo "$OIDC_TOKEN" > /tmp/code-review/oidc-token.txt
env:
OIDC_TOKEN: ${{ steps.oidc.outputs.token }}
- name: Upload review inputs
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: code-review-inputs
path: /tmp/code-review/
retention-days: 1
review:
needs: prepare
runs-on: ubuntu-latest
permissions: {}
timeout-minutes: 15
container:
image: ghcr.io/aaif-goose/goose:latest
options: --user root
env:
HOME: /tmp/goose-home
steps:
- name: Checkout base branch
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install tools
run: |
apt-get update
apt-get install -y ripgrep jq
- name: Download review inputs
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: code-review-inputs
path: /tmp/code-review
- name: Install custom provider and run goose review
env:
GOOSE_PROVIDER: anthropic-oidc-proxy
GOOSE_MODEL: ${{ vars.GOOSE_CODE_REVIEW_MODEL || 'claude-opus-4-6' }}
OIDC_PROXY_URL: ${{ github.event.inputs.oidc_proxy_url || vars.OIDC_PROXY_URL }}
REVIEW_INSTRUCTIONS: ${{ github.event.inputs.review_instructions || 'Review the changes for correctness' }}
run: |
ANTHROPIC_OIDC_PROXY_API_KEY=$(cat /tmp/code-review/oidc-token.txt)
export ANTHROPIC_OIDC_PROXY_API_KEY
rm /tmp/code-review/oidc-token.txt
mkdir -p "$HOME/.local/share/goose/sessions"
mkdir -p "$HOME/.config/goose/custom_providers"
cp oidc-proxy/anthropic-oidc-proxy.json "$HOME/.config/goose/custom_providers/"
goose run \
--recipe .github/recipes/code-review.yaml \
--params pr_directory=/tmp/code-review \
--params instructions="$REVIEW_INSTRUCTIONS"
- name: Upload review output
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: code-review-output
path: |
/tmp/conclusion.json
/tmp/comments.json
if-no-files-found: ignore
retention-days: 30
submit:
needs: [prepare, review]
runs-on: ubuntu-latest
permissions:
pull-requests: write
if: always() && needs.review.result == 'success'
steps:
- name: Download review inputs
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: code-review-inputs
path: /tmp/inputs
- name: Download review output
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: code-review-output
path: /tmp/output
- name: Submit review
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR_NUMBER: ${{ github.event.pull_request.number || github.event.inputs.pr_number }}
run: |
CONCLUSION="/tmp/output/conclusion.json"
COMMENTS="/tmp/output/comments.json"
COMMIT_ID=$(cat /tmp/inputs/commit_id.txt)
if [ ! -f "$COMMENTS" ]; then
echo "No comments produced, skipping review submission."
exit 0
fi
if [ ! -f "$CONCLUSION" ]; then
echo '{"body":"","event":"COMMENT"}' > "$CONCLUSION"
fi
jq -n \
--arg commit_id "$COMMIT_ID" \
--slurpfile conclusion "$CONCLUSION" \
--slurpfile comments "$COMMENTS" \
'{
commit_id: $commit_id,
event: $conclusion[0].event,
comments: $comments[0]
}
| if $conclusion[0].body != "" then .body = $conclusion[0].body else . end
' > /tmp/review-payload.json
if gh api \
--method POST \
-H "Accept: application/vnd.github+json" \
"repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
--input /tmp/review-payload.json; then
echo "Review submitted with inline comments."
exit 0
fi
echo "Inline comments failed, folding into review body."
jq -n \
--arg commit_id "$COMMIT_ID" \
--slurpfile conclusion "$CONCLUSION" \
--slurpfile comments "$COMMENTS" \
'{
commit_id: $commit_id,
body: (
$conclusion[0].body + "\n\n---\n\n## Inline Comments\n\n" +
([$comments[0][] |
"### `" + .path + "` (line " + (.line | tostring) + ")\n\n" + .body
] | join("\n\n---\n\n"))
),
event: $conclusion[0].event
}' \
| gh api \
--method POST \
-H "Accept: application/vnd.github+json" \
"repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
--input -
-304
View File
@@ -1,304 +0,0 @@
# Automatically updates the CLI Commands Guide when CLI commands or options
# change between releases.
#
# Triggers: Manual (for testing) or on release (production)
# Testing: Use dry_run mode to review outputs without creating PRs
# See: documentation/automation/cli-command-tracking/TESTING.md
name: Update CLI Documentation
on:
workflow_dispatch: # Manual trigger for testing
inputs:
old_version:
description: 'Previous version (e.g., v1.14.0). Leave empty to auto-detect.'
required: false
type: string
new_version:
description: 'New version (e.g., v1.15.0). Leave empty to use HEAD.'
required: false
type: string
dry_run:
description: 'Dry run mode - generate files but do not create PR'
required: false
type: boolean
default: true
# Automatic triggering on releases
# Uses edited to catch when release-action updates the release with artifacts
release:
types: [edited]
permissions:
contents: write # Create branches and commit files
pull-requests: write # Create PRs
jobs:
update-docs:
name: Update CLI Documentation
runs-on: ubuntu-latest
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0 # Fetch all history for version comparison
fetch-tags: true # Fetch all tags so we can checkout version tags
- name: Fetch upstream tags (for forks)
if: github.repository != 'aaif-goose/goose'
run: |
# Add upstream remote and fetch tags (only needed when testing in forks)
git remote add upstream https://github.com/aaif-goose/goose.git || git remote set-url upstream https://github.com/aaif-goose/goose.git
git fetch upstream --tags --force
echo "✅ Fetched tags from upstream (fork mode)"
echo "Total tags available: $(git tag | wc -l)"
- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y jq ripgrep
- name: Set up Rust
uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2.0.0
with:
toolchain: stable
- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.11'
- name: Set up Node.js
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '20'
- name: Install goose CLI
run: |
mkdir -p /home/runner/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \
| CONFIGURE=false GOOSE_BIN_DIR=/home/runner/.local/bin bash
echo "/home/runner/.local/bin" >> $GITHUB_PATH
goose --version
- name: Configure goose for CI
env:
GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }}
GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }}
run: |
mkdir -p ~/.config/goose
cat <<EOF > ~/.config/goose/config.yaml
GOOSE_PROVIDER: $GOOSE_PROVIDER
GOOSE_MODEL: $GOOSE_MODEL
keyring: false
EOF
# Also export into the job environment so later steps can log the values
echo "GOOSE_PROVIDER=$GOOSE_PROVIDER" >> "$GITHUB_ENV"
echo "GOOSE_MODEL=$GOOSE_MODEL" >> "$GITHUB_ENV"
echo "✅ Created goose config:"
cat ~/.config/goose/config.yaml
- name: Determine versions to compare
id: versions
env:
GH_TOKEN: ${{ github.token }}
INPUT_OLD_VERSION: ${{ github.event.inputs.old_version }}
INPUT_NEW_VERSION: ${{ github.event.inputs.new_version }}
EVENT_NAME: ${{ github.event_name }}
RELEASE_TAG: ${{ github.event.release.tag_name }}
run: |
get_previous_release() {
gh release list --limit 2 --json tagName --jq '.[].tagName' | sed -n '2p'
}
if [ -n "$INPUT_OLD_VERSION" ]; then
OLD_VERSION="$INPUT_OLD_VERSION"
else
OLD_VERSION=$(get_previous_release)
fi
if [ -n "$INPUT_NEW_VERSION" ]; then
NEW_VERSION="$INPUT_NEW_VERSION"
elif [ "$EVENT_NAME" = "release" ]; then
NEW_VERSION="$RELEASE_TAG"
else
NEW_VERSION="HEAD" # For testing unreleased changes
fi
if [ -z "$OLD_VERSION" ] || [ -z "$NEW_VERSION" ]; then
echo "Error: Could not determine versions to compare"
exit 1
fi
echo "old_version=$OLD_VERSION" >> $GITHUB_OUTPUT
echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
echo "OLD_VERSION=$OLD_VERSION" >> $GITHUB_ENV
echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
echo "✅ Comparing $OLD_VERSION → $NEW_VERSION"
- name: Extract and compare CLI structures
id: extract
timeout-minutes: 30 # Building goose takes time
working-directory: documentation/automation/cli-command-tracking
env:
GOOSE_REPO: ${{ github.workspace }}
run: |
set -o pipefail # Ensure pipeline failures are caught
mkdir -p output
./scripts/run-pipeline.sh "$OLD_VERSION" "$NEW_VERSION" 2>&1 | tee output/pipeline.log
HAS_CHANGES=$(jq -r '.has_changes' output/cli-changes.json)
echo "has_changes=$HAS_CHANGES" >> $GITHUB_OUTPUT
if [ "$HAS_CHANGES" = "false" ]; then
echo "✅ No changes detected"
else
echo "✅ Changes detected"
fi
- name: Update goose-cli-commands.md (AI synthesis)
if: steps.extract.outputs.has_changes == 'true'
timeout-minutes: 10
working-directory: documentation/automation/cli-command-tracking/output
env:
CLI_COMMANDS_PATH: ${{ github.workspace }}/documentation/docs/guides/goose-cli-commands.md
run: |
echo "🔍 Environment diagnostics:"
echo " GOOSE_PROVIDER: $GOOSE_PROVIDER"
echo " GOOSE_MODEL: $GOOSE_MODEL"
echo " ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:0:8}..." # Show first 8 chars only
echo " CLI_COMMANDS_PATH: $CLI_COMMANDS_PATH"
echo " HOME: $HOME"
echo " PATH: $PATH"
echo ""
echo "📁 Goose config file:"
cat ~/.config/goose/config.yaml || echo "Config file not found!"
echo ""
echo "📁 Current directory:"
pwd
ls -la
echo ""
echo "🤖 Applying changes to goose-cli-commands.md..."
goose run --recipe ../recipes/update-cli-commands.yaml
- name: Upload automation outputs
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: cli-docs-update-${{ steps.versions.outputs.old_version }}-to-${{ steps.versions.outputs.new_version }}
path: |
documentation/automation/cli-command-tracking/output/*.json
documentation/automation/cli-command-tracking/output/*.md
documentation/automation/cli-command-tracking/output/*.log
retention-days: 30
- name: Create Pull Request
if: |
steps.extract.outputs.has_changes == 'true' &&
(github.event.inputs.dry_run != 'true' || github.event_name == 'release')
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
with:
branch: docs/auto-cli-commands-${{ steps.versions.outputs.new_version }}
delete-branch: true
commit-message: |
docs: Update CLI commands for ${{ steps.versions.outputs.new_version }}
Automated update based on CLI changes between ${{ steps.versions.outputs.old_version }} and ${{ steps.versions.outputs.new_version }}.
title: "docs: Update CLI Commands Guide for ${{ steps.versions.outputs.new_version }}"
body: |
## Summary
This PR updates the CLI Commands Guide based on command and option changes detected between **${{ steps.versions.outputs.old_version }}** and **${{ steps.versions.outputs.new_version }}**.
### Type of Change
- [x] Documentation
### AI Assistance
- [x] This PR was created or reviewed with AI assistance
#### 🤖 Automation Details
- **Workflow**: docs-update-cli-ref.yml
- **Triggered by**: ${{ github.event_name }}
- **Previous version**: ${{ steps.versions.outputs.old_version }}
- **New version**: ${{ steps.versions.outputs.new_version }}
#### 📋 Changes Detected
Review the workflow artifacts for detailed change analysis:
- cli-changes.json - Structured diff of changes
- cli-changes.md - Human-readable change documentation
- update-summary.md - Summary of documentation updates applied
Download artifacts from the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
### ✅ Review Checklist
- [ ] Verify all CLI changes are accurately documented
- [ ] Check that examples are updated correctly
- [ ] Ensure new commands are in the correct sections
- [ ] Confirm no unintended changes were made
### 🔗 Related
- Release: ${{ github.event.release.html_url || 'N/A' }}
---
*This PR was automatically generated by the CLI Documentation Automation workflow.*
labels: |
documentation
automated
cli-commands
- name: Workflow summary
if: always()
env:
OLD_VERSION: ${{ steps.versions.outputs.old_version }}
NEW_VERSION: ${{ steps.versions.outputs.new_version }}
HAS_CHANGES: ${{ steps.extract.outputs.has_changes }}
DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
run: |
echo "## 📊 CLI Documentation Update Summary" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Version Comparison**: $OLD_VERSION → $NEW_VERSION" >> $GITHUB_STEP_SUMMARY
echo "**Changes Detected**: $HAS_CHANGES" >> $GITHUB_STEP_SUMMARY
echo "**Dry Run Mode**: $DRY_RUN" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
if [ "$HAS_CHANGES" = "true" ]; then
echo "### ✅ Documentation Updated" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "The CLI Commands Guide has been updated to reflect changes in $NEW_VERSION." >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
if [ "$DRY_RUN" = "true" ]; then
echo "**Note**: Running in dry-run mode - no PR was created. Review the artifacts to see the generated changes." >> $GITHUB_STEP_SUMMARY
else
echo "A pull request has been created with the documentation updates." >> $GITHUB_STEP_SUMMARY
fi
else
echo "### ℹ️ No Changes Needed" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "No CLI command changes were detected between $OLD_VERSION and $NEW_VERSION." >> $GITHUB_STEP_SUMMARY
fi
echo "" >> $GITHUB_STEP_SUMMARY
echo "### 📦 Artifacts" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "Download the workflow artifacts to review:" >> $GITHUB_STEP_SUMMARY
echo "- Extracted CLI structures" >> $GITHUB_STEP_SUMMARY
echo "- Change detection results" >> $GITHUB_STEP_SUMMARY
echo "- Human-readable change documentation" >> $GITHUB_STEP_SUMMARY
echo "- Documentation update summary" >> $GITHUB_STEP_SUMMARY
-242
View File
@@ -1,242 +0,0 @@
name: goose Issue Solver
on:
issue_comment:
types: [created]
workflow_dispatch:
inputs:
issue_number:
description: 'Issue number to solve'
required: true
type: string
env:
GOOSE_RECIPE: |
version: "1.0.0"
title: "Solve GitHub Issue"
description: "Solve GitHub issue #${ISSUE_NUMBER}"
extensions:
- type: builtin
name: developer
- type: platform
name: todo
instructions: |
Write code like a senior goose contributor.
Principles:
- Search first: `rg "keyword" -l` to find existing patterns. Copy them exactly.
- Deletion is a feature: ask "can I delete code instead of adding?"
- Complete changes: update ALL usages when changing a type. No exceptions.
- When changing message types, update ALL provider format functions.
- When changing ACP request/response types, run `just generate-acp-types`.
- Your context degrades. The TODO is your memory. Update it after each step.
Types:
- `PathBuf` for paths, never `String`
- Enums for finite sets, never string comparisons
- `Vec<T>` not `Option<Vec<T>>` - empty vec is the "none" case
- Don't return `Result` if failure is meaningless
- `#[serde(default)]` on new struct fields
Patterns:
- Early returns, not nested if-else
- Extract to utility if code appears 3+ times
- Scope locks tightly: extract data, release lock, then I/O
- Log and continue for non-critical failures
- Error messages must say HOW to fix, not just what's wrong
- Use `#[cfg(target_os = "...")]` for platform-specific code
Testing:
- Bug fix: write failing test FIRST, then fix
- Delete tests when deleting features
- No tests for trivial code
Don't:
- Create abstractions unless required
- Add backward compat shims - update callers
- Write WHAT comments (keep WHY comments)
- Add checks the OS will do anyway
prompt: |
Solve GitHub issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}
The issue is saved at /tmp/issue.json
Trigger comment:
${TRIGGER_COMMENT}
Write this to your TODO immediately and update as you progress:
## Phase 1: Understand
- [ ] Read /tmp/issue.json
- [ ] Write all requirements (explicit + implicit) to /tmp/requirements.md
- [ ] Read AGENTS.md if it exists
## Phase 2: Research
- [ ] `rg "keyword" -l` to find relevant files and similar patterns
- [ ] `analyze path="crates/" focus="SymbolName"` to trace type/function usage
- [ ] Read 2-3 similar implementations to copy their patterns
- [ ] List all files that need changes in TODO
## Phase 3: Plan
- [ ] Decide on implementation approach
- [ ] If changing >5 files or public APIs, write plan to /tmp/plan.md first
- [ ] Update TODO with specific changes to make
## Phase 4: Implement
- [ ] Implement minimal fix per /tmp/requirements.md
- [ ] Before adding anything, check: is it in the requirements? If not, don't.
- [ ] No .github/, no lock files, no secrets
## Phase 5: Verify
- [ ] source bin/activate-hermit
- [ ] cargo check
- [ ] cargo test (affected crates)
- [ ] cargo fmt
- [ ] cargo clippy --all-targets -- -D warnings
- [ ] Fix failures, retry up to 3 times
## Phase 6: Confirm (MANDATORY)
- [ ] Reread /tmp/issue.json
- [ ] Reread /tmp/requirements.md
- [ ] Confirm all requirements met, nothing extra added
- [ ] Write a summary of changes to /tmp/issue_summary.txt
The Phase 6 "Reread" steps MUST appear in your updated TODO. Skipping them is failure.
Only write /tmp/issue_summary.txt if the fix is complete and verified.
Run `git add` for any new files required for the fix.
Do NOT commit. Leave changes in the working directory for the workflow to handle.
permissions:
contents: write
pull-requests: write
issues: write
concurrency:
group: goose-issue-${{ github.event.issue.number || github.event.inputs.issue_number }}
cancel-in-progress: false
jobs:
solve-issue:
if: |
github.event_name == 'workflow_dispatch' ||
(!github.event.issue.pull_request &&
startsWith(github.event.comment.body, '/goose') &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
runs-on: ubuntu-latest
timeout-minutes: 30
container:
image: ghcr.io/aaif-goose/goose:latest
options: --user root
env:
GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }}
GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
HOME: /tmp/goose-home
steps:
- name: Acknowledge trigger
if: github.event_name == 'issue_comment'
run: |
curl -sL -X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
"https://api.github.com/repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" \
-d '{"content":"eyes"}'
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: main
fetch-depth: 1
- name: Install tools
run: |
apt-get update
apt-get install -y jq gettext curl build-essential pkg-config libssl-dev
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
apt-get update
apt-get install -y gh
- name: Get issue details (issue_comment)
if: github.event_name == 'issue_comment'
env:
ISSUE_JSON: ${{ toJSON(github.event.issue) }}
run: printenv ISSUE_JSON > /tmp/issue.json
- name: Get issue details (workflow_dispatch)
if: github.event_name == 'workflow_dispatch'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh api /repos/${{ github.repository }}/issues/${{ github.event.inputs.issue_number }} > /tmp/issue.json
- name: Set issue outputs
id: issue
run: |
echo "number=$(jq -r '.number' /tmp/issue.json)" >> $GITHUB_OUTPUT
# SECURITY: Use random delimiter to prevent injection if title contains our delimiter
DELIMITER="EOF_$(openssl rand -hex 8)"
echo "title<<$DELIMITER" >> $GITHUB_OUTPUT
jq -r '.title' /tmp/issue.json >> $GITHUB_OUTPUT
echo "$DELIMITER" >> $GITHUB_OUTPUT
- name: Run goose
id: goose
env:
ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
ISSUE_TITLE: ${{ steps.issue.outputs.title }}
TRIGGER_COMMENT: ${{ github.event.comment.body || 'Triggered via workflow_dispatch' }}
run: |
mkdir -p $HOME/.local/share/goose/sessions
mkdir -p $HOME/.config/goose
git config --global --add safe.directory "$GITHUB_WORKSPACE"
echo "$GOOSE_RECIPE" | envsubst '$ISSUE_NUMBER $ISSUE_TITLE $TRIGGER_COMMENT' > /tmp/recipe.yaml
goose run --recipe /tmp/recipe.yaml
if [ -n "$(git status --porcelain)" ] && [ -f /tmp/issue_summary.txt ]; then
echo "has_changes=true" >> $GITHUB_OUTPUT
# SECURITY: Use random delimiter to prevent injection if summary contains our delimiter
SUMMARY_DELIMITER="EOF_$(openssl rand -hex 8)"
echo "summary<<$SUMMARY_DELIMITER" >> $GITHUB_OUTPUT
cat /tmp/issue_summary.txt >> $GITHUB_OUTPUT
echo "$SUMMARY_DELIMITER" >> $GITHUB_OUTPUT
else
echo "has_changes=false" >> $GITHUB_OUTPUT
fi
- name: Verify no workflow changes
if: steps.goose.outputs.has_changes == 'true'
run: |
if git diff --name-only | grep -q "^\.github/"; then
echo "::error::Changes to .github/ are not allowed"
git checkout -- .github/
fi
- name: Create Pull Request
if: steps.goose.outputs.has_changes == 'true'
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
with:
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: "fix: ${{ steps.issue.outputs.title }}"
title: "fix: ${{ steps.issue.outputs.title }}"
branch: goose/issue-${{ steps.issue.outputs.number }}
delete-branch: true
draft: true
labels: goose-generated
body: |
Closes #${{ steps.issue.outputs.number }}
## Summary
${{ steps.goose.outputs.summary || 'See commits for details.' }}
---
*Generated by goose Issue Solver*
-323
View File
@@ -1,323 +0,0 @@
# goose PR Reviewer
#
# Automated PR review using goose AI agent.
#
# Trigger: Comment "/goose [optional instructions]" on a PR (OWNER/MEMBER only)
#
# Examples:
# /goose
# /goose focus on security implications
# /goose check error handling in src/auth/
#
# Required Secrets:
# - ANTHROPIC_API_KEY: API key for Anthropic
#
# Optional Variables:
# - GOOSE_PROVIDER: LLM provider (default: anthropic)
# - GOOSE_MODEL: Model name (default: claude-opus-4-5)
#
# Security:
# - PR content could prompt-inject the agent; only trigger on PRs you trust.
# - Do not add workflow_dispatch: API calls fetch mutable data, enabling TOCTOU attacks.
name: goose PR Reviewer
on:
issue_comment:
types: [created]
env:
GOOSE_RECIPE: |
version: "1.0.0"
title: "Review Pull Request"
description: "Review PR #${PR_NUMBER}"
extensions:
- type: builtin
name: developer
- type: platform
name: todo
instructions: |
You are a code reviewer. Evaluate code, don't implement changes. Be constructive, specific, and verify claims with evidence.
## Issue Categories
- 🔴 BLOCKING: Must fix. Requires HIGH confidence + code evidence.
- 🟡 WARNING: Should fix. MEDIUM+ confidence.
- 🟢 SUGGESTION: Nice to have. Can be speculative if labeled.
- ✅ HIGHLIGHT: Good practices to acknowledge.
## Core Review Lens: "Succeed Fast" Detection
LLM code often compiles quickly while avoiding proper design. Ask these questions:
**Necessity**: Do we need this?
- New function? Could an existing one take an extra parameter?
- New struct? Search `rg "struct Similar"` - does one exist?
- New dependency? Many tools (gh, python) are pre-installed.
**Types & Options**: Is the type system being used correctly?
- Option<T>: Why optional? If .unwrap() is nearby, it should be required.
- Option<bool>: Rarely needed. Consider if None vs Some(false) distinction matters.
- Manual JSON parsing: Use typed structs, not field extraction.
- Many casts/assertions: The types are probably wrong.
- Use builders: Prefer `Foo::builder()` over manual struct construction when available.
- Generated types: Use API/SDK-provided types. Don't redefine what's already generated.
- Path types: Use PathBuf for paths, not String. Use centralized path utilities.
**Duplication & State**: Is there one source of truth?
- Similar code nearby? Factor it out.
- Shadow state (settings in multiple places)? Consolidate.
- Singleton caching config? What if config changes?
**Error Handling**: Are errors handled or hidden?
- .ok(), .unwrap_or_default(), catch-and-log: Should this propagate?
## Code Hygiene
- AI-generated artifacts: Verbose comments like "// Helper function to..." may be LLM leftovers. Delete if obvious.
- Comments restating code: Delete. "Code speaks for itself."
- Comments that lie: Dangerous. Fix or delete.
- TODOs without owners: Create issue or delete.
- Tests setting env vars: `rg "env::set_var" -g "*test*"` = flaky tests.
- Tests not testing behavior: "What bug would this catch?"
Ref: https://engineering.block.xyz/blog/the-high-cost-of-free-testing
## Security (especially workflows)
- TOCTOU: Use event payload, not API calls.
- Heredoc injection: User content may contain delimiter.
- Feature auto-enable: Must respect user toggles.
## Architectural Smell (be specific about why)
- Brittle: Too many special cases, hardcoded assumptions.
- Wrong layer: Routes should be thin. Clients shouldn't know implementation details.
- Not independent: Multiple booleans → should be enum.
- Cumbersome: Simpler approach exists? Extend existing APIs.
- Naming confusion: Similar functions should return similarly-named types (not FooResult vs ResultFoo).
- Scope creep: Changes unrelated to PR's stated purpose.
## Anti-hallucination
- Search with rg before claiming something is "missing"
- Before claiming UI/frontend changes are needed, trace the actual data flow
- Say "I couldn't verify" not "this is wrong"
- 2 verified issues are better than 10 speculative ones
## Language Note
These guidelines are primarily Rust-focused. For TypeScript/frontend changes (ui/desktop/),
apply the same rigor with language-appropriate patterns (e.g., discriminated unions,
optional chaining, React key uniqueness). Review all code equally thoroughly.
If the approach is fundamentally wrong, reject it. Don't polish bad code.
prompt: |
Review PR #${PR_NUMBER}: ${PR_TITLE}
The PR metadata is saved at /tmp/pr.json
The PR diff is saved at /tmp/pr.diff
The PR branch is already checked out. You are in the repository directory.
Use the codebase to understand context - explore with analyze, rg, and file reads.
Reviewer instructions from trigger:
${REVIEW_INSTRUCTIONS}
FIRST ACTION: Call todo_write with this entire checklist. Your memory degrades - the TODO is your only reliable memory. Update it frequently.
## Budget Guidance
You have 15 minutes. Allocate effort wisely:
- Phase 1 (Understand): ~20% - Don't over-explore, get the gist
- Phase 2 (Evaluate): ~30% - This is where design issues surface
- Phase 3 (Verify): ~30% - Only if approach is sound, skip if fundamentally flawed
- Phase 4 (Report): ~20% - Prioritize and write concisely
For large diffs (>500 lines): Focus on architecture over line-by-line review.
Aim for 3-7 high-quality findings, not exhaustive coverage.
## PR Understanding
- Intent: [fill after Phase 1]
- Approach: [fill after Phase 1]
- Evaluation: [fill after Phase 2 - is this the right approach?]
## Phase 1: Understand
- [ ] Read /tmp/pr.json for PR description and context
- [ ] Read /tmp/pr.diff for the actual changes
- [ ] Read AGENTS.md if it exists
- [ ] Note reviewer instructions: ${REVIEW_INSTRUCTIONS}
- [ ] Summarize: What is this PR trying to accomplish?
## Phase 2: Evaluate (Empathize, then Challenge)
First, empathize with the author's choices:
- [ ] Trace the data/control flow through the changes
- [ ] Why did the author choose this approach?
- [ ] What constraints were they working under?
Then, challenge the approach:
- [ ] Architectural fit: Does this fit naturally, or is there awkward "pretending"?
- [ ] Alternatives: Could existing APIs/patterns be extended instead of adding new code?
- [ ] Consistency: Do names/types match similar code? Search with: rg "similar_name" --type rust
- [ ] Necessity: Is all this code needed? Could parameters/fields be removed?
- [ ] State and intent: If this enables/disables features, does it respect user preferences?
- [ ] Simpler path: Is there a way to achieve this with less code?
If fundamental design issues are found, note them and consider skipping detailed verification.
## Phase 3: Verify (only if approach is sound)
- [ ] Review for correctness and logic errors
- [ ] Check for security vulnerabilities
- [ ] Assess error handling
- [ ] Look for performance issues
- [ ] Verify edge cases are handled
- [ ] For each issue, add to Issues Found below with confidence level
Note: Do NOT run cargo check, cargo test, cargo fmt, or other build commands.
CI pipelines already validate those automatically. Focus on code review only.
## Phase 4: Report
- [ ] Prioritize findings: 🔴 Blocking > 🟡 Warning > 🟢 Suggestion
- [ ] Verify all 🔴 BLOCKING issues have HIGH confidence + code evidence
- [ ] Write review to /tmp/pr_review.md
- [ ] Be concise - quality over quantity
## Issues Found
[Add issues here as you find them, format: [HIGH/MED/LOW] [file:line] description - evidence]
---
Format your review in /tmp/pr_review.md as:
**Summary**: [1-2 sentence overview of what this PR does and your assessment]
Only include sections below if they have content. Omit empty sections entirely.
**🔴 Blocking Issues**
[Issues that must be fixed before merge. Each must have file:line and evidence.]
**🟡 Warnings**
[Issues that should be addressed]
**🟢 Suggestions**
[Optional improvements]
**✅ Highlights**
[Good practices observed in this PR]
---
*Review generated by goose*
Only write /tmp/pr_review.md when the review is complete.
Do NOT make any changes to the codebase.
permissions:
contents: read
pull-requests: write
concurrency:
group: goose-pr-review-${{ github.event.issue.number }}
cancel-in-progress: true
jobs:
review-pr:
if: |
github.event.issue.pull_request &&
startsWith(github.event.comment.body, '/goose') &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
runs-on: ubuntu-latest
timeout-minutes: 15
container:
image: ghcr.io/aaif-goose/goose:latest
options: --user root
env:
GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }}
GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
HOME: /tmp/goose-home
steps:
- name: Acknowledge trigger
run: |
curl -sL -X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
"https://api.github.com/repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" \
-d '{"content":"eyes"}'
- name: Checkout PR
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: refs/pull/${{ github.event.issue.number }}/head
fetch-depth: 1
- name: Install tools
run: |
apt-get update
apt-get install -y gettext curl ripgrep
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
apt-get update
apt-get install -y gh
- name: Get PR diff
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr diff ${{ github.event.issue.number }} --repo ${{ github.repository }} > /tmp/pr.diff
- name: Extract review instructions
id: instructions
env:
COMMENT_BODY: ${{ github.event.comment.body }}
run: |
if [ -n "$COMMENT_BODY" ]; then
INSTRUCTIONS=$(echo "$COMMENT_BODY" | sed 's|^/goose||' | sed 's|^[[:space:]]*||' | sed 's|[[:space:]]*$||')
fi
if [ -z "$INSTRUCTIONS" ]; then
INSTRUCTIONS="No specific instructions - perform a general code review."
fi
# SECURITY: Use random delimiter to prevent injection if comment contains our delimiter
DELIMITER="EOF_$(openssl rand -hex 8)"
echo "instructions<<$DELIMITER" >> $GITHUB_OUTPUT
echo "$INSTRUCTIONS" >> $GITHUB_OUTPUT
echo "$DELIMITER" >> $GITHUB_OUTPUT
- name: Run goose review
id: goose
env:
PR_NUMBER: ${{ github.event.issue.number }}
PR_TITLE: ${{ github.event.issue.title }}
PR_BODY: ${{ github.event.issue.body }}
REVIEW_INSTRUCTIONS: ${{ steps.instructions.outputs.instructions }}
# SECURITY: Pass issue JSON via environment variable to avoid heredoc injection
# (GHSA-mm8p-57gq-3xj6) - user-controlled content could terminate heredoc early
ISSUE_JSON: ${{ toJson(github.event.issue) }}
run: |
mkdir -p $HOME/.local/share/goose/sessions
mkdir -p $HOME/.config/goose
git config --global --add safe.directory "$GITHUB_WORKSPACE"
# SECURITY: Use printf with env var instead of heredoc to prevent injection
printf '%s' "$ISSUE_JSON" > /tmp/pr.json
echo "$GOOSE_RECIPE" | envsubst '$PR_NUMBER $PR_TITLE $PR_BODY $REVIEW_INSTRUCTIONS' > /tmp/recipe.yaml
goose run --recipe /tmp/recipe.yaml
if [ -f /tmp/pr_review.md ]; then
echo "has_review=true" >> $GITHUB_OUTPUT
else
echo "has_review=false" >> $GITHUB_OUTPUT
fi
- name: Post review comment
if: steps.goose.outputs.has_review == 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr comment ${{ github.event.issue.number }} --repo ${{ github.repository }} --body-file /tmp/pr_review.md
- name: Post failure comment
if: failure() || steps.goose.outputs.has_review != 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr comment ${{ github.event.issue.number }} --repo ${{ github.repository }} --body "⚠️ goose PR review could not be completed. Check the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details."
-57
View File
@@ -1,57 +0,0 @@
# Documentation Automation
This directory contains automated pipelines for keeping goose documentation synchronized with code changes.
## Overview
Each automation project tracks specific types of changes and updates corresponding documentation:
| Project | Status | Tracks | Updates |
|---------|--------|--------|---------|
| cli-command-tracking | 🔮 Planned | CLI commands & options | CLI documentation |
| provider-tracking | 🔮 Planned | Supported AI providers | Provider documentation |
| extension-tracking | 🔮 Planned | Built-in extensions | Extension documentation |
## Architecture
Each automation project follows a consistent pattern:
```
project-name/
├── README.md # Project-specific documentation
├── TESTING.md # How to test this automation
├── config/ # Configuration files
├── scripts/ # Deterministic extraction/diff scripts
└── recipes/ # AI-powered synthesis/update recipes
```
### Design Principles
1. **Modular**: Each project is self-contained
2. **Testable**: Clear inputs/outputs at each stage
3. **Transparent**: Intermediate files can be inspected
4. **Reusable**: Common patterns across projects
### Hybrid Approach
- **Shell scripts**: Deterministic extraction and comparison
- **AI recipes**: Synthesis and documentation updates
## GitHub Actions Integration
Automation projects can be triggered via GitHub Actions workflows in `.github/workflows/`.
See individual project TESTING.md files for workflow usage.
## Adding New Automations
When creating a new automation project:
1. Create a subdirectory: `documentation/automation/your-project/`
2. Follow the standard structure (README, TESTING, config, scripts, recipes)
3. Create corresponding GitHub Actions workflow (if needed)
4. Update this README with the new project
## Questions?
For project-specific questions, see the README in each project directory.
@@ -1,28 +0,0 @@
# Output directory - generated files
output/
# Python cache
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
# Virtual environments
venv/
env/
ENV/
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# OS
.DS_Store
Thumbs.db
# Logs
*.log
@@ -1,336 +0,0 @@
# CLI Command Tracking
Automated pipeline for detecting and documenting CLI command changes between goose releases.
## Overview
This automation keeps the [CLI Commands Guide](https://goose-docs.ai/docs/guides/goose-cli-commands) synchronized with code changes by:
1. **Extracting** CLI structure from goose binary using `--help` output (deterministic)
2. **Detecting** changes between versions (deterministic diff)
3. **Synthesizing** human-readable change documentation (AI-powered)
4. **Updating** the CLI Commands Guide (AI-powered)
The automation runs automatically on new releases via GitHub Actions, or can be run manually for testing.
## Quick Start
### Automated (GitHub Actions)
The automation runs automatically when a new release is published. See [TESTING.md](./TESTING.md) for testing instructions.
### Manual (Local Testing)
```bash
# Set the goose repository path
export GOOSE_REPO=/path/to/goose
# Run the complete pipeline with auto-detected versions
./scripts/run-pipeline.sh
# Or specify versions explicitly
./scripts/run-pipeline.sh v1.17.0 v1.19.0
# Or run individual steps:
# 1. Extract CLI structures
./scripts/extract-cli-structure.sh v1.17.0 > output/old-cli-structure.json
./scripts/extract-cli-structure.sh v1.19.0 > output/new-cli-structure.json
# 2. Detect changes
python3 scripts/diff-cli-structures.py output/old-cli-structure.json \
output/new-cli-structure.json \
> output/cli-changes.json
# 3. Generate human-readable change documentation
cd output && goose run --recipe ../recipes/synthesize-cli-changes.yaml
# 4. Update goose-cli-commands.md
cd output && goose run --recipe ../recipes/update-cli-commands.yaml
```
### Version Detection
The pipeline automatically detects versions when not specified:
- **Old version**: Second-most-recent release tag (via `gh release list`)
- **New version**: Most recent release tag, or `RELEASE_TAG` env var (for CI)
- **Fallback**: Uses git tags if `gh` CLI not available
To test unreleased changes, explicitly pass `HEAD`:
```bash
./scripts/run-pipeline.sh v1.19.0 HEAD
```
## Architecture
### Modular Pipeline Design
The automation uses a **hybrid approach**: deterministic scripts for data extraction/diffing, AI recipes for analysis and documentation updates.
```
┌─────────────────────────────────────────────────────────────────┐
│ EXTRACTION (Deterministic) │
├─────────────────────────────────────────────────────────────────┤
│ extract-cli-structure.sh → extract-cli-structure.py │
│ ↓ │
│ cli-structure.json (commands, options, subcommands, aliases) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ DIFFING (Deterministic) │
├─────────────────────────────────────────────────────────────────┤
│ diff-cli-structures.py │
│ ↓ │
│ cli-changes.json (added, removed, modified commands/options) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ SYNTHESIS (AI-Powered) │
├─────────────────────────────────────────────────────────────────┤
│ synthesize-cli-changes.yaml │
│ ↓ │
│ cli-changes.md (human-readable) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ UPDATE (AI-Powered) │
├─────────────────────────────────────────────────────────────────┤
│ update-cli-commands.yaml │
│ ↓ │
│ goose-cli-commands.md (updated) + update-summary.md │
└─────────────────────────────────────────────────────────────────┘
```
### Why This Design?
**Scripts handle deterministic tasks:**
- Building goose from specific git tags
- Running `--help` commands and parsing output
- JSON structure comparison
- No interpretation or inference - direct extraction
**AI recipes handle synthesis and updates:**
- Analyzing changes and explaining implications
- Generating migration guidance and examples
- Updating documentation with proper formatting and context
**Benefits:**
- **Reliability**: Extraction is deterministic and reproducible
- **Testability**: Each stage has clear inputs/outputs
- **Maintainability**: Easy to update individual components
- **Transparency**: Intermediate files can be inspected
### Data Flow
All stages communicate via JSON/Markdown files in the `output/` directory:
| File | Producer | Consumer | Purpose |
|------|----------|----------|---------|
| `old-cli-structure.json` | `extract-cli-structure.sh` | `diff-cli-structures.py` | Previous version CLI structure |
| `new-cli-structure.json` | `extract-cli-structure.sh` | `diff-cli-structures.py` | Current version CLI structure |
| `cli-changes.json` | `diff-cli-structures.py` | `synthesize-cli-changes.yaml` | Detected changes (structured) |
| `cli-changes.md` | `synthesize-cli-changes.yaml` | `update-cli-commands.yaml` | Human-readable change documentation |
| `update-summary.md` | `update-cli-commands.yaml` | Human review | Summary of documentation updates |
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GOOSE_REPO` | Yes (local) | - | Path to goose repository root |
| `CLI_COMMANDS_PATH` | No | `$GOOSE_REPO/documentation/docs/guides/goose-cli-commands.md` | Full path to target doc file |
| `RELEASE_TAG` | No | - | Used by GitHub Actions to specify the new version |
**Example:**
```bash
export GOOSE_REPO=/Users/you/goose
# CLI_COMMANDS_PATH is auto-constructed from GOOSE_REPO
```
### Skipped Commands
Some commands are intentionally excluded from extraction and documentation tracking. These are configured in `config/skip-commands.json`:
```json
{
"description": "Commands to skip during extraction (not documented intentionally)",
"skip_commands": [
{
"name": "term",
"reason": "Terminal integration documented via @goose/@g aliases"
}
]
}
```
To add or remove skipped commands, edit the config file - no code changes required.
## Scripts
### `extract-cli-structure.sh`
Builds goose from a specific git tag and extracts CLI structure using `--help` output.
**Usage:**
```bash
./scripts/extract-cli-structure.sh [version] > output/cli-structure.json
```
**Arguments:**
- `version` (optional): Git tag or commit to extract from (default: HEAD)
**Output:** JSON with complete command tree including options, subcommands, aliases
**Example:**
```bash
# Extract from current code
./scripts/extract-cli-structure.sh HEAD > output/new-cli-structure.json
# Extract from specific version
./scripts/extract-cli-structure.sh v1.15.0 > output/old-cli-structure.json
```
### `diff-cli-structures.py`
Compares two CLI structure files and outputs detected changes.
**Usage:**
```bash
python3 scripts/diff-cli-structures.py <old-file> <new-file> > output/cli-changes.json
```
**Arguments:**
- `old-file`: Path to old CLI structure JSON
- `new-file`: Path to new CLI structure JSON
**Output:** JSON with categorized changes:
- `commands.added`: New commands
- `commands.removed`: Deleted commands
- `commands.modified`: Changed commands (options, description, aliases)
- `breaking_changes`: Categorized breaking changes
**Example:**
```bash
python3 scripts/diff-cli-structures.py \
output/old-cli-structure.json \
output/new-cli-structure.json \
> output/cli-changes.json
```
## Recipes
### `synthesize-cli-changes.yaml`
Analyzes detected changes and generates human-readable documentation.
**Inputs:**
- `output/cli-changes.json` - Detected changes from diff script
- `output/old-cli-structure.json` - Previous version structure
- `output/new-cli-structure.json` - Current version structure
**Output:**
- `output/cli-changes.md` - Human-readable change documentation with:
- Breaking changes with migration guidance
- New commands with usage examples
- Modified commands with details
- Non-breaking changes summary
**Usage:**
```bash
cd output
goose run --recipe ../recipes/synthesize-cli-changes.yaml
```
### `update-cli-commands.yaml`
Updates the CLI Commands Guide based on synthesized changes.
**Inputs:**
- `output/cli-changes.md` - Change documentation from synthesis recipe
- `goose-cli-commands.md` - Target documentation file (path from `CLI_COMMANDS_PATH` or `GOOSE_REPO` env var)
**Outputs:**
- Updated `goose-cli-commands.md` with changes applied
- `output/update-summary.md` - Summary of changes for review
**Usage:**
```bash
export CLI_COMMANDS_PATH=/path/to/goose-cli-commands.md
cd output
goose run --recipe ../recipes/update-cli-commands.yaml
```
## Directory Structure
```
cli-command-tracking/
├── README.md # This file
├── TESTING.md # Testing guide for GitHub Actions workflow
├── .gitignore # Excludes output/ directory
├── config/ # Configuration files
│ └── skip-commands.json # Commands to exclude from tracking
├── scripts/ # Extraction and diff scripts
│ ├── extract-cli-structure.sh # Wrapper that builds goose and runs Python
│ ├── extract-cli-structure.py # Python script to parse --help output
│ ├── diff-cli-structures.py # Compare structures and detect changes
│ └── run-pipeline.sh # End-to-end pipeline runner
├── recipes/ # AI recipes
│ ├── synthesize-cli-changes.yaml # Generate change docs
│ └── update-cli-commands.yaml # Update documentation
├── .github/workflows/ # GitHub Actions workflow
│ └── docs-update-cli-ref.yml # Workflow definition
└── output/ # Generated files (gitignored)
├── old-cli-structure.json # Previous version structure
├── new-cli-structure.json # Current version structure
├── cli-changes.json # Detected changes (structured)
├── cli-changes.md # Change documentation (human-readable)
├── update-summary.md # Documentation update summary
└── pipeline.log # Pipeline execution log
```
## GitHub Actions Workflow
The automation runs via `.github/workflows/docs-update-cli-ref.yml`:
- **Trigger**: Automatically on new releases, or manually for testing
- **Process**: Builds goose for both versions, extracts CLI structures, detects changes, updates documentation
- **Output**: Creates a PR with updated `goose-cli-commands.md` if changes detected
- **Testing**: See [TESTING.md](./TESTING.md) for detailed testing instructions
## What Gets Tracked
### Commands
- ✅ Commands added/removed
- ✅ Command descriptions changed
- ✅ Command aliases added/removed
- ✅ Subcommands added/removed
### Options
- ✅ Options added/removed
- ✅ Option help text changed
- ✅ Default values changed
- ✅ Possible values changed (enums)
- ✅ Short/long flags changed
### Breaking Changes (Auto-Categorized)
- Command removed (high severity)
- Option removed (high severity)
- Option renamed (high severity)
- Default value changed (medium severity)
- Enum values removed (high severity)
- Alias removed (medium severity)
## Maintenance
When modifying the automation:
1. **Test locally first**: Run `./scripts/run-pipeline.sh` with test versions
2. **Verify outputs**: Check generated files against actual CLI changes
3. **Test in fork**: Use GitHub Actions workflow with dry-run mode
4. **Document changes**: Update this README with design decisions
## Related Documentation
- [TESTING.md](./TESTING.md) - How to test the GitHub Actions workflow
- [Automation Overview](../README.md) - All automation projects
- [CLI Commands Guide](../../docs/guides/goose-cli-commands.md) - Target documentation
@@ -1,382 +0,0 @@
# Testing Guide
This guide explains how to test the CLI command tracking automation locally and in GitHub Actions.
## Prerequisites
- Python 3.7+
- Rust toolchain (for building goose)
- jq (for JSON processing)
- goose CLI installed (for running recipes)
- Git with access to goose repository
## Local Testing
### Step 1: Set Up Environment
```bash
cd /path/to/cli-command-tracking
# Set the goose repository path
export GOOSE_REPO=/path/to/goose
# Create output directory
mkdir -p output
```
### Step 2: Test Extraction Script
Test the extraction with a specific version:
```bash
# Test with a release version
./scripts/extract-cli-structure.sh v1.19.0 > output/test-extraction.json
# Verify output
jq '.version, .commands | length' output/test-extraction.json
# Inspect a specific command
jq '.commands[] | select(.name == "session")' output/test-extraction.json
# Verify skipped commands are excluded
jq '.commands[].name' output/test-extraction.json | grep -v term
```
**Expected output:**
- Valid JSON structure
- Version number extracted correctly
- All commands captured (14+ commands, excluding skipped ones like `term`)
- Subcommands nested properly
- Options parsed with all fields
**Common issues:**
- Rust not installed: Install via rustup
- Build fails: Check Cargo.toml dependencies
- Timeout errors: Increase timeout in script if needed
- Keychain prompt: See "Keychain Access" section below
### Step 3: Test Diff Script
Compare two CLI structures:
```bash
# Extract from two versions
./scripts/extract-cli-structure.sh v1.14.0 > output/old-cli-structure.json
./scripts/extract-cli-structure.sh v1.15.0 > output/new-cli-structure.json
# Run diff
python3 scripts/diff-cli-structures.py \
output/old-cli-structure.json \
output/new-cli-structure.json \
> output/cli-changes.json
# Check results
jq '.has_changes, .summary' output/cli-changes.json
# View specific changes
jq '.changes.commands.added' output/cli-changes.json
jq '.changes.commands.modified[0]' output/cli-changes.json
jq '.breaking_changes' output/cli-changes.json
```
**Expected output:**
- `has_changes: true` if versions differ
- Summary with counts of changes
- Detailed changes in structured format
- Breaking changes categorized
### Step 4: Test AI Synthesis Recipe
Generate human-readable documentation:
```bash
cd output
# Run synthesis recipe
goose run --recipe ../recipes/synthesize-cli-changes.yaml
# Check output
ls -lh cli-changes.md
head -50 cli-changes.md
```
**Expected output:**
- `cli-changes.md` file created
- Markdown formatted properly
- Breaking changes listed first
- Examples provided for complex changes
- When testing AI workflows, ensure any content sent via the `store_comment` tool does not contain triple-backtick code fences (```), even though regular backticks in markdown files like `cli-changes.md` are allowed.
### Step 5: Test Documentation Update Recipe
Update the actual documentation:
```bash
cd output
# Set path to documentation file
export CLI_COMMANDS_PATH=/path/to/goose/documentation/docs/guides/goose-cli-commands.md
# Run update recipe
goose run --recipe ../recipes/update-cli-commands.yaml
# Check outputs
ls -lh update-summary.md
cat update-summary.md
# Verify documentation was updated
git diff $CLI_COMMANDS_PATH
```
### Step 6: Test Full Pipeline
Run the complete end-to-end pipeline:
```bash
cd /path/to/cli-command-tracking
# Set documentation path (optional - only needed for update step)
export CLI_COMMANDS_PATH=/path/to/goose/documentation/docs/guides/goose-cli-commands.md
# Run pipeline
./scripts/run-pipeline.sh v1.14.0 v1.15.0
# Check all outputs
ls -lh output/
```
**Expected output:**
- All intermediate files created
- Pipeline completes without errors
- Summary shows changes detected
- `cli-changes.md` generated
## GitHub Actions Testing
### Test in Fork
1. **Fork the repository** (if not already done)
2. **Copy automation files** to your fork:
```bash
cp -r /path/to/cli-command-tracking \
/path/to/forked-goose/documentation/automation/
cp /path/to/goose/.github/workflows/docs-update-cli-ref.yml \
/path/to/forked-goose/.github/workflows/
```
3. **Set up secrets** in your fork:
- Go to Settings → Secrets and variables → Actions
- Add `ANTHROPIC_API_KEY` secret
4. **Set up variables** (optional):
- Add `GOOSE_PROVIDER` variable (default: anthropic)
- Add `GOOSE_MODEL` variable (default: claude-opus-4-5)
5. **Trigger workflow manually**:
- Go to Actions → "Update CLI Documentation"
- Click "Run workflow"
- Set `dry_run: true` for testing
- Optionally specify versions to compare
### Dry Run Mode
Test without creating PR:
1. Trigger workflow with `dry_run: true`
2. Review outputs in workflow logs
3. Download artifacts to inspect generated files
4. Validate changes are correct
### Workflow Inputs
| Input | Description | Default |
|-------|-------------|---------|
| `old_version` | Previous version tag | Auto-detect from releases |
| `new_version` | New version tag | HEAD |
| `dry_run` | Generate files but don't create PR | true |
### Reviewing Artifacts
After workflow runs:
1. Go to the workflow run page
2. Download the artifacts ZIP
3. Extract and review:
- `old-cli-structure.json` - Previous CLI structure
- `new-cli-structure.json` - New CLI structure
- `cli-changes.json` - Detected changes
- `cli-changes.md` - Human-readable documentation
- `pipeline.log` - Execution log
## Testing with Known Changes
To validate the automation works correctly, test with versions that have known CLI changes.
### Finding Test Versions
```bash
cd /path/to/goose
# Check git history for CLI changes
git log --oneline --all -- crates/goose-cli/src/cli.rs | head -20
# Look for commits that added/removed/modified commands
git show <commit-hash>:crates/goose-cli/src/cli.rs | grep "enum Command" -A 30
```
### Test Case: New Command Added
If you know a version added a new command:
```bash
./scripts/run-pipeline.sh v1.13.0 v1.14.0
jq '.changes.commands.added' output/cli-changes.json
```
### Test Case: Option Modified
If you know a version modified options:
```bash
./scripts/run-pipeline.sh v1.14.0 v1.15.0
jq '.changes.commands.modified' output/cli-changes.json
```
### Test Case: No Changes
Test with same version (should show no changes):
```bash
./scripts/run-pipeline.sh v1.14.0 v1.14.0
jq '.has_changes' output/cli-changes.json
# Should output: false
```
## Validation Checklist
Before considering the automation complete:
### Extraction Script
- [ ] Handles all command types (simple, with subcommands, with aliases)
- [ ] Parses all option types (short, long, with values, flags)
- [ ] Captures defaults and possible values
- [ ] Works with commands that have no description
- [ ] Handles nested subcommands (2+ levels)
- [ ] Builds goose from git tags correctly
### Diff Script
- [ ] Detects added commands
- [ ] Detects removed commands
- [ ] Detects modified options
- [ ] Detects changed help text
- [ ] Detects changed defaults
- [ ] Detects changed possible values
- [ ] Categorizes breaking changes correctly
### AI Recipes
- [ ] Generates readable documentation
- [ ] Provides migration guidance
- [ ] Uses correct markdown formatting
- [ ] Avoids backticks (security constraint)
- [ ] Includes relevant examples
- [ ] Uses text_editor tool to write files
### Pipeline
- [ ] Runs end-to-end without errors
- [ ] Handles "no changes" case
- [ ] Creates all expected output files
- [ ] Filters goose session output correctly
### GitHub Actions
- [ ] Workflow triggers correctly
- [ ] Builds goose for both versions
- [ ] Uploads artifacts
- [ ] Creates PR when changes detected
- [ ] Respects dry_run mode
- [ ] Works in forks (fetches upstream tags)
## Troubleshooting
### Keychain Access (macOS)
On macOS, running `goose --help` or `goose --version` may prompt for keychain access. This happens because goose tries to access stored credentials on startup.
**Local workaround:** Allow the keychain access when prompted.
**CI consideration:** GitHub Actions runners don't have a keychain, so this may need to be handled. Check existing goose workflows for patterns - there may be a `keyring: false` config option or environment variable to disable credential loading.
**TODO:** Investigate if this blocks CI execution and document the solution.
### Build fails for old version
Some old versions may have different dependencies:
```bash
# Check if version exists
git tag | grep v1.14.0
# Try building manually
git worktree add /tmp/goose-test v1.14.0
cd /tmp/goose-test
cargo build --release
```
### Extraction timeout
Increase timeout in `extract-cli-structure.py`:
```python
result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) # Increase from 10
```
### Diff shows unexpected changes
Check if help text formatting changed:
```bash
# Compare raw help output
./old-goose session --help > old-help.txt
./new-goose session --help > new-help.txt
diff old-help.txt new-help.txt
```
### AI recipe fails
Check input files exist and are valid:
```bash
ls -lh output/cli-changes.json output/old-cli-structure.json output/new-cli-structure.json
jq empty output/cli-changes.json # Validates JSON
```
### Workflow fails in fork
Ensure:
- `ANTHROPIC_API_KEY` secret is set
- Upstream tags are fetched (workflow does this automatically)
- Rust toolchain is available
## Manual Verification
After automation runs, manually verify:
1. **Accuracy**: Do detected changes match actual CLI changes?
2. **Completeness**: Are all changes captured?
3. **Documentation**: Is the updated documentation accurate and clear?
4. **Examples**: Do all examples still work?
5. **Style**: Is formatting consistent with existing docs?
## Test Data
Keep test data for regression testing:
```bash
# Save known-good outputs
mkdir -p test-data
cp output/cli-changes.json test-data/v1.14.0-to-v1.15.0-changes.json
cp output/cli-changes.md test-data/v1.14.0-to-v1.15.0-changes.md
```
Use these to verify future changes don't break existing functionality.
@@ -1,9 +0,0 @@
{
"description": "Commands to skip during extraction (not documented intentionally)",
"skip_commands": [
{
"name": "term",
"reason": "Terminal integration documented via @goose/@g aliases"
}
]
}
@@ -1,208 +0,0 @@
version: "2"
title: "Synthesize CLI Changes"
description: "Generate human-readable documentation for CLI command changes between two versions"
extensions:
- type: builtin
name: developer
instructions: |
You are a technical documentation specialist creating release notes for CLI command changes.
## Your Task
Analyze the CLI changes between two goose versions and generate clear, user-focused
documentation explaining what changed and why it matters.
## Input Files
You have access to THREE data sources:
1. **cli-changes.json** - The diff (what changed):
- commands: added, removed, modified
- breaking_changes: categorized breaking changes
- summary: high-level statistics
2. **old-cli-structure.json** - Before state (for context):
- Complete command structure from old version
3. **new-cli-structure.json** - After state (for context):
- Complete command structure from new version
## Output Format
Create a Markdown file (cli-changes.md) with this structure:
# CLI Command Changes
**From**: {old_version}
**To**: {new_version}
**Analyzed**: {timestamp}
## Summary
Brief overview of changes (2-3 sentences).
- Commands added: X
- Commands removed: X
- Commands modified: X
- Breaking changes: X
## Breaking Changes
⚠️ **Important**: These changes may break existing scripts or workflows.
List all breaking changes with migration guidance:
### Command Removed: **command-name**
- **Impact**: Users can no longer use this command
- **Migration**: Use **alternative-command** instead
- **Example**:
# Old way
goose old-command --option value
# New way
goose new-command --option value
### Option Removed: **--option-name** from **command**
- **Impact**: Scripts using this option will fail
- **Migration**: Use **--new-option** instead or adjust workflow
### Default Value Changed: **--option** in **command**
- **Old default**: value1
- **New default**: value2
- **Impact**: Behavior changes when option is omitted
- **Migration**: Explicitly specify the value if you need the old behavior
## New Commands
Commands added in this release:
### **command-name**
- **Description**: What this command does
- **Usage**: goose command-name [OPTIONS]
- **Purpose**: Why this command was added
- **Key Options**:
- **--option1**: Description
- **--option2**: Description
- **Example**:
goose command-name --option1 value
## Removed Commands
Commands removed in this release:
### **command-name**
- **Reason**: Why it was removed (infer from context)
- **Alternative**: What to use instead
- **Migration**: How to update existing usage
## Modified Commands
Commands with changes in this release:
### **command-name**
**Changes**:
#### Description Updated
- **Old**: Previous description
- **New**: New description
- **Impact**: Clarifies command purpose
#### New Options
- **--new-option** VALUE: Description and purpose
#### Removed Options
- **--old-option**: Was used for X, now use **--new-option** instead
#### Modified Options
- **--option-name**:
- Help text updated for clarity
- Default changed from X to Y
- Possible values expanded: added Z
#### Aliases Changed
- Added alias: **x**
- Removed alias: **y**
## Non-Breaking Changes
Changes that don't break existing usage:
- New optional options added
- Help text clarifications
- New aliases added
- Expanded enum values (new possible values)
## Analysis Guidelines
1. **Focus on User Impact**: Explain changes from user perspective, not implementation details
2. **Prioritize Breaking Changes**: These go first and need clear migration guidance
3. **Provide Examples**: Show before/after for breaking changes
4. **Infer Intent**: Use command names, descriptions, and option names to understand why changes were made
5. **Be Specific**: Include concrete details about what changed
6. **Group Related Changes**: If multiple options changed in one command, group them together
7. **Explain Implications**: Don't just list changes, explain what they mean for users
8. **Suggest Alternatives**: For removed features, suggest what to use instead
9. **Skip Trivial Changes**: Don't document minor help text formatting changes
10. **Use Context**: Reference old and new structures to understand relationships
## Special Cases
- **Empty changes arrays**: If a category has no changes, skip that section entirely
- **Commands with no description**: Some commands (like **diagnostics**) have empty about fields - this is normal
- **Alias changes**: Removing aliases might break user muscle memory, note this in breaking changes
- **Default value changes**: These can be subtle breaking changes if users rely on defaults
- **Enum expansions**: Adding new possible values is non-breaking, but removing them is breaking
## File Locations
- Input 1: ./cli-changes.json (the diff)
- Input 2: ./old-cli-structure.json (before state)
- Input 3: ./new-cli-structure.json (after state)
- Output: ./cli-changes.md
Start by reading all THREE input files, then generate the CLI changes documentation.
prompt: |
Please analyze the CLI changes and generate comprehensive release notes.
Steps:
1. Read all THREE input files (cli-changes.json, old-cli-structure.json, new-cli-structure.json)
2. Analyze the changes
3. Write the documentation to ./cli-changes.md using the text_editor tool
Focus on:
- User impact (how does this affect CLI users and scripts?)
- Breaking vs non-breaking changes
- Migration guidance for breaking changes
- Clear, actionable documentation
- Examples for complex changes
IMPORTANT: You MUST use the text_editor tool to write the output to ./cli-changes.md
@@ -1,222 +0,0 @@
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)
- 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?
@@ -1,355 +0,0 @@
#!/usr/bin/env python3
"""
Compare two CLI structure JSON files and output detected changes.
Usage:
./diff-cli-structures.py <old-file> <new-file> > output/cli-changes.json
Example:
./diff-cli-structures.py output/cli-structure-v1.14.0.json \
output/cli-structure-v1.15.0.json \
> output/cli-changes.json
"""
import sys
import json
from datetime import datetime, timezone
from typing import Dict, List
def get_command_path(command: Dict, parent_path: str = "") -> str:
"""Get the full path of a command (e.g., 'session list')."""
if parent_path:
return f"{parent_path} {command['name']}"
return command['name']
def flatten_commands(commands: List[Dict], parent_path: str = "") -> Dict[str, Dict]:
"""
Flatten nested command structure into a dict keyed by full command path.
Returns:
Dict mapping command path to command data
"""
result = {}
for cmd in commands:
cmd_path = get_command_path(cmd, parent_path)
# Store command without subcommands to avoid recursion in comparisons
cmd_copy = cmd.copy()
subcommands = cmd_copy.pop('subcommands', [])
result[cmd_path] = cmd_copy
# Recursively flatten subcommands
if subcommands:
result.update(flatten_commands(subcommands, cmd_path))
return result
def compare_options(old_opts: List[Dict], new_opts: List[Dict]) -> Dict:
"""
Compare two lists of options and detect changes.
Returns dict with: added, removed, modified
"""
# Create dicts keyed by long flag (or short if no long)
old_opts_dict = {opt.get('long') or opt.get('short'): opt for opt in old_opts}
new_opts_dict = {opt.get('long') or opt.get('short'): opt for opt in new_opts}
old_keys = set(old_opts_dict.keys())
new_keys = set(new_opts_dict.keys())
added = []
removed = []
modified = []
# Find added options
for key in new_keys - old_keys:
added.append(new_opts_dict[key])
# Find removed options
for key in old_keys - new_keys:
removed.append(old_opts_dict[key])
# Find modified options
for key in old_keys & new_keys:
old_opt = old_opts_dict[key]
new_opt = new_opts_dict[key]
changes = {}
# Check each field for changes
if old_opt.get('short') != new_opt.get('short'):
changes['short'] = {'old': old_opt.get('short'), 'new': new_opt.get('short')}
if old_opt.get('long') != new_opt.get('long'):
changes['long'] = {'old': old_opt.get('long'), 'new': new_opt.get('long')}
if old_opt.get('value_name') != new_opt.get('value_name'):
changes['value_name'] = {'old': old_opt.get('value_name'), 'new': new_opt.get('value_name')}
if old_opt.get('help') != new_opt.get('help'):
changes['help'] = {'old': old_opt.get('help'), 'new': new_opt.get('help')}
if old_opt.get('default') != new_opt.get('default'):
changes['default'] = {'old': old_opt.get('default'), 'new': new_opt.get('default')}
if old_opt.get('possible_values') != new_opt.get('possible_values'):
changes['possible_values'] = {'old': old_opt.get('possible_values'), 'new': new_opt.get('possible_values')}
if changes:
modified.append({
'option': key,
'changes': changes
})
return {
'added': added,
'removed': removed,
'modified': modified
}
def compare_commands(old_cmds: Dict[str, Dict], new_cmds: Dict[str, Dict]) -> Dict:
"""
Compare two command dictionaries and detect changes.
Returns dict with: added, removed, modified
"""
old_paths = set(old_cmds.keys())
new_paths = set(new_cmds.keys())
added = []
removed = []
modified = []
# Find added commands
for path in new_paths - old_paths:
added.append({
'command': path,
'data': new_cmds[path]
})
# Find removed commands
for path in old_paths - new_paths:
removed.append({
'command': path,
'data': old_cmds[path]
})
# Find modified commands
for path in old_paths & new_paths:
old_cmd = old_cmds[path]
new_cmd = new_cmds[path]
changes = {}
# Check about text
if old_cmd.get('about') != new_cmd.get('about'):
changes['about'] = {
'old': old_cmd.get('about'),
'new': new_cmd.get('about')
}
# Check aliases
old_aliases = set(old_cmd.get('aliases', []))
new_aliases = set(new_cmd.get('aliases', []))
if old_aliases != new_aliases:
changes['aliases'] = {
'old': sorted(old_aliases),
'new': sorted(new_aliases),
'added': sorted(new_aliases - old_aliases),
'removed': sorted(old_aliases - new_aliases)
}
# Check usage
if old_cmd.get('usage') != new_cmd.get('usage'):
changes['usage'] = {
'old': old_cmd.get('usage'),
'new': new_cmd.get('usage')
}
# Check options
option_changes = compare_options(
old_cmd.get('options', []),
new_cmd.get('options', [])
)
if any(option_changes.values()):
changes['options'] = option_changes
if changes:
modified.append({
'command': path,
'changes': changes
})
return {
'added': added,
'removed': removed,
'modified': modified
}
def categorize_breaking_changes(changes: Dict) -> List[Dict]:
"""
Identify changes that are likely breaking changes.
Returns list of breaking change descriptions.
"""
breaking = []
# Removed commands are breaking
for item in changes['commands']['removed']:
breaking.append({
'type': 'command_removed',
'command': item['command'],
'severity': 'high',
'description': f"Command '{item['command']}' was removed"
})
# Check modified commands for breaking changes
for item in changes['commands']['modified']:
cmd = item['command']
cmd_changes = item['changes']
# Removed options are breaking
if 'options' in cmd_changes:
for opt in cmd_changes['options']['removed']:
opt_name = f"--{opt.get('long')}" if opt.get('long') else f"-{opt.get('short')}"
breaking.append({
'type': 'option_removed',
'command': cmd,
'option': opt_name,
'severity': 'high',
'description': f"Option '{opt_name}' removed from '{cmd}'"
})
# Changed option flags are breaking
for mod in cmd_changes['options']['modified']:
if 'short' in mod['changes'] or 'long' in mod['changes']:
breaking.append({
'type': 'option_renamed',
'command': cmd,
'option': mod['option'],
'severity': 'high',
'description': f"Option flags changed in '{cmd}': {mod['option']}"
})
# Changed default values might be breaking
if 'default' in mod['changes']:
breaking.append({
'type': 'default_changed',
'command': cmd,
'option': mod['option'],
'severity': 'medium',
'description': f"Default value changed for '{cmd} --{mod['option']}'"
})
# Removed possible values are breaking
if 'possible_values' in mod['changes']:
old_vals = set(mod['changes']['possible_values']['old'] or [])
new_vals = set(mod['changes']['possible_values']['new'] or [])
removed_vals = old_vals - new_vals
if removed_vals:
breaking.append({
'type': 'enum_values_removed',
'command': cmd,
'option': mod['option'],
'severity': 'high',
'description': f"Possible values removed from '{cmd} --{mod['option']}': {', '.join(removed_vals)}"
})
# Removed aliases might be breaking (users might rely on them)
if 'aliases' in cmd_changes and cmd_changes['aliases']['removed']:
for alias in cmd_changes['aliases']['removed']:
breaking.append({
'type': 'alias_removed',
'command': cmd,
'alias': alias,
'severity': 'medium',
'description': f"Alias '{alias}' removed from '{cmd}'"
})
return breaking
def main():
if len(sys.argv) != 3:
print("Usage: diff-cli-structures.py <old-file> <new-file>", file=sys.stderr)
print("Example: diff-cli-structures.py old.json new.json", file=sys.stderr)
sys.exit(1)
old_file = sys.argv[1]
new_file = sys.argv[2]
# Load JSON files
try:
with open(old_file, 'r') as f:
old_data = json.load(f)
except Exception as e:
print(f"Error reading {old_file}: {e}", file=sys.stderr)
sys.exit(1)
try:
with open(new_file, 'r') as f:
new_data = json.load(f)
except Exception as e:
print(f"Error reading {new_file}: {e}", file=sys.stderr)
sys.exit(1)
print(f"Comparing {old_data['version']} → {new_data['version']}...", file=sys.stderr)
# Flatten command structures
old_commands = flatten_commands(old_data['commands'])
new_commands = flatten_commands(new_data['commands'])
print(f"Old version: {len(old_commands)} commands", file=sys.stderr)
print(f"New version: {len(new_commands)} commands", file=sys.stderr)
# Compare commands
command_changes = compare_commands(old_commands, new_commands)
# Categorize breaking changes
breaking_changes = categorize_breaking_changes({'commands': command_changes})
# Determine if there are any changes
has_changes = (
len(command_changes['added']) > 0 or
len(command_changes['removed']) > 0 or
len(command_changes['modified']) > 0
)
# Build output
now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
output = {
'old_version': old_data['version'],
'new_version': new_data['version'],
'compared_at': now,
'has_changes': has_changes,
'summary': {
'commands_added': len(command_changes['added']),
'commands_removed': len(command_changes['removed']),
'commands_modified': len(command_changes['modified']),
'breaking_changes': len([b for b in breaking_changes if b['severity'] == 'high'])
},
'changes': {
'commands': command_changes
},
'breaking_changes': breaking_changes
}
# Output JSON
print(json.dumps(output, indent=2))
# Print summary to stderr
print(f"\nSummary:", file=sys.stderr)
print(f" Commands added: {output['summary']['commands_added']}", file=sys.stderr)
print(f" Commands removed: {output['summary']['commands_removed']}", file=sys.stderr)
print(f" Commands modified: {output['summary']['commands_modified']}", file=sys.stderr)
print(f" Breaking changes: {output['summary']['breaking_changes']}", file=sys.stderr)
if __name__ == '__main__':
main()
@@ -1,363 +0,0 @@
#!/usr/bin/env python3
"""
Extract CLI command structure from goose binary using --help output.
Usage:
./extract-cli-structure.py <goose-binary-path> > output/cli-structure.json
Example:
./extract-cli-structure.py /path/to/goose > output/new-cli-structure.json
"""
import sys
import subprocess
import json
import re
import os
from datetime import datetime, timezone
from typing import Dict, List, Optional, Tuple
def load_skip_commands() -> List[str]:
"""Load the list of commands to skip from config file."""
script_dir = os.path.dirname(os.path.abspath(__file__))
config_path = os.path.join(script_dir, '..', 'config', 'skip-commands.json')
try:
with open(config_path, 'r') as f:
config = json.load(f)
return [cmd['name'] for cmd in config.get('skip_commands', [])]
except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
print(f"Warning: Could not load skip-commands.json: {e}", file=sys.stderr)
return []
SKIP_COMMANDS = load_skip_commands()
def run_help_command(binary_path: str, command_path: List[str], short: bool = False) -> str:
"""
Run --help or -h on a command and return the output.
Args:
binary_path: Path to goose binary
command_path: List of command parts (e.g., ['session', 'list'])
short: If True, use -h instead of --help
Returns:
Help text output
"""
cmd = [binary_path] + command_path + (['-h'] if short else ['--help'])
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
return result.stdout
except subprocess.TimeoutExpired:
print(f"Warning: Command timed out: {' '.join(cmd)}", file=sys.stderr)
return ""
except Exception as e:
print(f"Warning: Failed to run {' '.join(cmd)}: {e}", file=sys.stderr)
return ""
def parse_usage_line(help_text: str) -> Optional[str]:
"""Extract the usage line from help text."""
match = re.search(r'^Usage:\s*(.+)$', help_text, re.MULTILINE)
return match.group(1).strip() if match else None
def parse_about(help_text: str) -> str:
"""Extract the command description (first line before Usage)."""
lines = help_text.strip().split('\n')
# Find the Usage: line
usage_index = -1
for i, line in enumerate(lines):
if line.strip().startswith('Usage:'):
usage_index = i
break
# If Usage is found, look for description before it
if usage_index > 0:
for i in range(usage_index):
line = lines[i].strip()
if line and not line.startswith('Options:') and not line.startswith('Commands:'):
return line
return ""
def parse_aliases(help_text: str) -> List[str]:
"""Extract command aliases from help text."""
# Look for "[aliases: x, y]" pattern in the first few lines
match = re.search(r'\[aliases?:\s*([^\]]+)\]', help_text[:500])
if match:
aliases_str = match.group(1)
return [a.strip() for a in aliases_str.split(',')]
return []
def parse_options(help_text: str) -> List[Dict]:
"""
Parse options from the Options: section of help text.
Returns list of option dicts with: short, long, value_name, help, default, possible_values
"""
options = []
# Find the Options: section - goes until Commands: section or end of text
# Note: clap help has blank lines between options, so we can't stop at ^$
options_match = re.search(r'^Options:\s*\n(.+?)(?=^Commands:\s*$|\Z)',
help_text, re.MULTILINE | re.DOTALL)
if not options_match:
return options
options_text = options_match.group(1)
# Split into individual option blocks
# Each option starts with whitespace followed by a dash (short or long flag)
# Use lookahead to split at lines that start a new option
option_blocks = re.split(r'\n(?=\s+-)', options_text)
for block in option_blocks:
block = block.strip()
if not block or not block.startswith('-'):
continue
option = parse_option_block(block)
if option:
options.append(option)
return options
def parse_option_block(block: str) -> Optional[Dict]:
"""Parse a single option block into structured data."""
lines = block.split('\n')
if not lines:
return None
# First line has the flags, optional value name, and sometimes inline help (common clap output)
first_line = lines[0].strip()
inline_help = None
# Split on 2+ spaces to separate flags from inline help text.
# Example: "-o, --output <FILE> Write output to file"
parts = re.split(r'\s{2,}', first_line, maxsplit=1)
flags_part = parts[0]
if len(parts) == 2:
inline_help = parts[1].strip() or None
# Extract short flag (e.g., -f)
short_match = re.search(r'-([a-zA-Z])\b', flags_part)
short = short_match.group(1) if short_match else None
# Extract long flag (e.g., --format)
long_match = re.search(r'--([a-z][a-z0-9-]*)', flags_part)
long = long_match.group(1) if long_match else None
# Extract value_name (e.g., <FORMAT>)
value_name_match = re.search(r'<([^>]+)>', flags_part)
value_name = value_name_match.group(1) if value_name_match else None
# Collect help text from subsequent indented lines
help_lines = []
for line in lines[1:]:
line = line.strip()
if line and not line.startswith('['):
help_lines.append(line)
elif line.startswith('['):
# This might be [default: ...] or [possible values: ...]
break
help_text = ' '.join(help_lines)
if inline_help:
help_text = f"{inline_help} {help_text}".strip() if help_text else inline_help
# Extract default value
default = None
default_match = re.search(r'\[default:\s*([^\]]+)\]', block)
if default_match:
default = default_match.group(1).strip()
# Extract possible values
possible_values = None
possible_match = re.search(r'\[possible values:\s*([^\]]+)\]', block)
if possible_match:
values_str = possible_match.group(1)
possible_values = [v.strip() for v in values_str.split(',')]
return {
'short': short,
'long': long,
'value_name': value_name,
'help': help_text if help_text else None,
'default': default,
'possible_values': possible_values
}
def parse_subcommands(help_text: str) -> List[Tuple[str, List[str]]]:
"""
Extract subcommand names and their aliases from the Commands: section.
Returns:
List of tuples: (command_name, [aliases])
"""
commands = []
# Find the Commands: section
commands_match = re.search(r'^Commands:\s*$(.+?)(?:^Options:|\Z)',
help_text, re.MULTILINE | re.DOTALL)
if not commands_match:
return commands
commands_text = commands_match.group(1)
# Each command line starts with the command name (not indented or minimally indented)
for raw_line in commands_text.split('\n'):
# Preserve indentation to avoid mis-parsing wrapped description lines.
# In clap help, actual command entries are typically not indented.
if not raw_line.strip():
continue
if raw_line.startswith(' ') or raw_line.startswith('\t'):
continue
line = raw_line.strip()
# Extract command name (first word)
parts = line.split()
if parts and not parts[0].startswith('-'):
command_name = parts[0]
# Skip "help" command as it's auto-generated
if command_name == 'help':
continue
# Extract aliases from [aliases: x, y] pattern
aliases = []
alias_match = re.search(r'\[aliases?:\s*([^\]]+)\]', line)
if alias_match:
aliases_str = alias_match.group(1)
aliases = [a.strip() for a in aliases_str.split(',')]
commands.append((command_name, aliases))
return commands
def extract_command_structure(binary_path: str, command_path: List[str] = None,
parent_aliases: List[str] = None) -> Dict:
"""
Recursively extract command structure starting from a command path.
Args:
binary_path: Path to goose binary
command_path: Current command path (e.g., ['session', 'list'])
parent_aliases: Aliases passed from parent (since they appear in parent's help)
Returns:
Dict with command structure
"""
if command_path is None:
command_path = []
# Get both short and long help
help_text_long = run_help_command(binary_path, command_path, short=False)
if not help_text_long:
return None
# Parse command info
command_name = command_path[-1] if command_path else "goose"
about = parse_about(help_text_long)
# Use parent_aliases if provided, otherwise try to parse from own help
aliases = parent_aliases if parent_aliases is not None else parse_aliases(help_text_long)
usage = parse_usage_line(help_text_long)
options = parse_options(help_text_long)
# Get subcommands with their aliases and recursively process them
subcommand_info = parse_subcommands(help_text_long)
subcommands = []
for subcommand_name, subcommand_aliases in subcommand_info:
# Skip commands in the skip list
if subcommand_name in SKIP_COMMANDS:
print(f"Skipping command: {subcommand_name}", file=sys.stderr)
continue
sub_path = command_path + [subcommand_name]
sub_structure = extract_command_structure(binary_path, sub_path, subcommand_aliases)
if sub_structure:
subcommands.append(sub_structure)
return {
'name': command_name,
'about': about,
'aliases': aliases,
'usage': usage,
'options': options,
'subcommands': subcommands
}
def extract_version(binary_path: str) -> str:
"""Extract version from goose --version."""
try:
result = subprocess.run([binary_path, '--version'],
capture_output=True, text=True, timeout=5)
# Output is typically "goose 1.15.0" or similar
version_match = re.search(r'(\d+\.\d+\.\d+)', result.stdout)
return version_match.group(1) if version_match else "unknown"
except Exception as e:
print(f"Warning: Could not extract version: {e}", file=sys.stderr)
return "unknown"
def main():
if len(sys.argv) < 2:
print("Usage: extract-cli-structure.py <goose-binary-path> [source-version]", file=sys.stderr)
print("Example: extract-cli-structure.py /usr/local/bin/goose v1.15.0", file=sys.stderr)
sys.exit(1)
binary_path = sys.argv[1]
source_version = sys.argv[2] if len(sys.argv) > 2 else None
# Verify binary exists and is executable
try:
result = subprocess.run([binary_path, '--version'],
capture_output=True, timeout=5)
if result.returncode != 0:
print(f"Error: {binary_path} is not a valid goose binary", file=sys.stderr)
sys.exit(1)
except Exception as e:
print(f"Error: Cannot execute {binary_path}: {e}", file=sys.stderr)
sys.exit(1)
print("Extracting CLI structure...", file=sys.stderr)
# Extract version
version = extract_version(binary_path)
print(f"Version: {version}", file=sys.stderr)
# Extract root command structure (recursively includes all subcommands)
root_structure = extract_command_structure(binary_path, [])
# Build output JSON
# Use timezone-aware UTC datetime (Python 3.7+)
now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
output = {
'version': version,
'source_version': source_version or version,
'extracted_at': now,
'binary_path': binary_path,
'commands': root_structure['subcommands'] if root_structure else []
}
# Output JSON
print(json.dumps(output, indent=2))
print("Extraction complete!", file=sys.stderr)
if __name__ == '__main__':
main()
@@ -1,115 +0,0 @@
#!/bin/bash
# Extract CLI command structure from goose at a specific version
# Usage: ./extract-cli-structure.sh <version>
# Example: ./extract-cli-structure.sh v1.15.0
#
# For tagged releases (v*), downloads pre-built binary from GitHub releases.
# For HEAD or non-release refs, builds from source.
set -e
set -o pipefail
VERSION=${1:-"HEAD"}
GOOSE_REPO=${GOOSE_REPO:-"$HOME/Development/goose"}
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# Create a temporary directory
TEMP_DIR=$(mktemp -d)
trap "rm -rf $TEMP_DIR" EXIT
# Check if version is a release tag (starts with 'v' followed by numbers)
is_release_tag() {
[[ "$1" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
}
# Download pre-built binary for a release version
download_release_binary() {
local version=$1
local safe_version=${version//\//-}
local bin_dir="$TEMP_DIR/bin"
mkdir -p "$bin_dir"
echo "Downloading goose $version from GitHub releases..." >&2
# Use the official download script with custom bin dir and specific version
curl -fsSL "https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh" | \
CONFIGURE=false GOOSE_BIN_DIR="$bin_dir" GOOSE_VERSION="$version" bash >&2 2>&1 || {
echo "Error: Failed to download goose $version" >&2
return 1
}
echo "$bin_dir/goose"
}
# Build goose from source
build_from_source() {
local version=$1
local safe_version=${version//\//-}
if [ ! -d "$GOOSE_REPO" ]; then
echo "Error: GOOSE_REPO directory not found: $GOOSE_REPO" >&2
exit 1
fi
cd "$GOOSE_REPO"
if [ "$version" = "HEAD" ]; then
echo "Building goose from HEAD..." >&2
cargo build --release --quiet >&2 2>&1 || {
echo "Error: Failed to build goose from HEAD" >&2
return 1
}
echo "$GOOSE_REPO/target/release/goose"
else
# Verify version exists
if ! git rev-parse "$version" >/dev/null 2>&1; then
echo "Error: Version $version not found in git history" >&2
return 1
fi
echo "Building goose from $version..." >&2
# Create a worktree for the version
local worktree_dir="$TEMP_DIR/goose-$safe_version"
git worktree add --quiet "$worktree_dir" "$version" >&2 2>&1 || {
echo "Error: Failed to create worktree for $version" >&2
return 1
}
cd "$worktree_dir"
cargo build --release --quiet >&2 2>&1 || {
echo "Error: Failed to build goose from $version" >&2
cd "$GOOSE_REPO"
git worktree remove "$worktree_dir" 2>/dev/null || true
return 1
}
# Clean up worktree but keep the binary accessible
local bin_path="$worktree_dir/target/release/goose"
local temp_bin="$TEMP_DIR/goose-$safe_version-bin"
cp "$bin_path" "$temp_bin"
cd "$GOOSE_REPO"
git worktree remove "$worktree_dir" 2>/dev/null || true
echo "$temp_bin"
fi
}
# Get the goose binary
if is_release_tag "$VERSION"; then
GOOSE_BIN=$(download_release_binary "$VERSION")
else
GOOSE_BIN=$(build_from_source "$VERSION")
fi
if [ -z "$GOOSE_BIN" ] || [ ! -x "$GOOSE_BIN" ]; then
echo "Error: Goose binary not found or not executable" >&2
exit 1
fi
echo "Using binary: $GOOSE_BIN" >&2
echo "Binary version: $($GOOSE_BIN --version 2>&1)" >&2
# Run the Python extraction script
python3 "$SCRIPT_DIR/extract-cli-structure.py" "$GOOSE_BIN" "$VERSION"
@@ -1,194 +0,0 @@
#!/bin/bash
# End-to-end pipeline for CLI command tracking
# Usage: ./run-pipeline.sh [old_version] [new_version]
# Example: ./run-pipeline.sh v1.17.0 v1.19.0
#
# Version detection:
# - If old_version not provided: uses the second-most-recent release tag
# - If new_version not provided: uses the most recent release tag (or RELEASE_TAG env var)
# - HEAD is only used when explicitly passed for testing unreleased changes
set -e
GOOSE_REPO=${GOOSE_REPO:-"$HOME/Development/goose"}
# Function to get release tags using gh CLI
get_latest_release() {
if command -v gh &> /dev/null; then
gh release list --repo aaif-goose/goose --limit 1 --json tagName --jq '.[0].tagName' 2>/dev/null
else
# Fallback: get latest version tag from git
cd "$GOOSE_REPO" && git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
fi
}
get_previous_release() {
if command -v gh &> /dev/null; then
gh release list --repo aaif-goose/goose --limit 2 --json tagName --jq '.[].tagName' 2>/dev/null | sed -n '2p'
else
# Fallback: get second-latest version tag from git
cd "$GOOSE_REPO" && git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sed -n '2p'
fi
}
# Determine versions
if [ -n "$1" ]; then
OLD_VERSION="$1"
else
OLD_VERSION=$(get_previous_release)
if [ -z "$OLD_VERSION" ]; then
echo "Error: Could not determine previous release version" >&2
exit 1
fi
fi
if [ -n "$2" ]; then
NEW_VERSION="$2"
elif [ -n "$RELEASE_TAG" ]; then
# Used by GitHub Actions release trigger
NEW_VERSION="$RELEASE_TAG"
else
NEW_VERSION=$(get_latest_release)
if [ -z "$NEW_VERSION" ]; then
echo "Error: Could not determine latest release version" >&2
exit 1
fi
fi
echo "=========================================="
echo "CLI Command Documentation Pipeline"
echo "=========================================="
echo "Old Version: $OLD_VERSION"
echo "New Version: $NEW_VERSION"
echo ""
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# Change to output directory
OUTPUT_DIR="$SCRIPT_DIR/../output"
mkdir -p "$OUTPUT_DIR"
cd "$OUTPUT_DIR"
# Use a per-run temp directory for logs to avoid collisions
LOG_DIR=$(mktemp -d)
trap 'rm -rf "$LOG_DIR"' EXIT
echo "Step 1: Extracting CLI structure from $OLD_VERSION..."
if ! ../scripts/extract-cli-structure.sh "$OLD_VERSION" > old-cli-structure.json 2>"$LOG_DIR/extract-old.log"; then
echo "✗ Failed to extract CLI structure from $OLD_VERSION" >&2
echo "Error output:" >&2
cat "$LOG_DIR/extract-old.log" >&2
exit 1
fi
echo "✓ Extracted $(jq '.commands | length' old-cli-structure.json) commands"
echo ""
echo "Step 2: Extracting CLI structure from $NEW_VERSION..."
if ! ../scripts/extract-cli-structure.sh "$NEW_VERSION" > new-cli-structure.json 2>"$LOG_DIR/extract-new.log"; then
echo "✗ Failed to extract CLI structure from $NEW_VERSION" >&2
echo "Error output:" >&2
cat "$LOG_DIR/extract-new.log" >&2
exit 1
fi
echo "✓ Extracted $(jq '.commands | length' new-cli-structure.json) commands"
echo ""
echo "Step 3: Comparing CLI structures..."
python3 ../scripts/diff-cli-structures.py old-cli-structure.json new-cli-structure.json > cli-changes.json 2>"$LOG_DIR/diff.log"
HAS_CHANGES=$(jq -r '.has_changes' cli-changes.json)
echo "✓ Comparison complete. Has changes: $HAS_CHANGES"
if [ "$HAS_CHANGES" = "true" ]; then
echo ""
echo "Changes detected:"
echo " - Commands added: $(jq '.summary.commands_added' cli-changes.json)"
echo " - Commands removed: $(jq '.summary.commands_removed' cli-changes.json)"
echo " - Commands modified: $(jq '.summary.commands_modified' cli-changes.json)"
echo " - Breaking changes: $(jq '.summary.breaking_changes' cli-changes.json)"
echo ""
echo "Step 4: Synthesizing CLI changes documentation..."
# Run goose and capture output, filtering out session logs
goose run --recipe ../recipes/synthesize-cli-changes.yaml 2>&1 | \
sed -E 's/\x1B\[[0-9;]*[mK]//g' | \
grep -v "^starting session" | \
grep -v "^ session id:" | \
grep -v "^ working directory:" | \
grep -v "^─── text_editor" | \
grep -v "^path:" | \
grep -v "^command:" | \
grep -v "^Closing session" | \
grep -v "^Loading recipe:" | \
grep -v "^Description:" | \
cat -s > cli-changes.md.tmp
# If the pipeline fails, surface the goose error (grep can exit 1 when it matches nothing)
if [ ${PIPESTATUS[0]} -ne 0 ]; then
echo "✗ Failed to synthesize CLI changes (goose run failed)" >&2
exit 1
fi
# Check if we got meaningful content
if [ -s cli-changes.md.tmp ] && grep -q "# CLI Command Changes" cli-changes.md.tmp; then
mv cli-changes.md.tmp cli-changes.md
echo "✓ Generated cli-changes.md ($(wc -l < cli-changes.md) lines)"
elif [ -f cli-changes.md ] && [ -s cli-changes.md ]; then
# File was written directly by goose
rm -f cli-changes.md.tmp
echo "✓ Generated cli-changes.md ($(wc -l < cli-changes.md) lines)"
else
echo "✗ Failed to generate cli-changes.md"
rm -f cli-changes.md.tmp
exit 1
fi
echo ""
echo "Step 5: Updating CLI commands documentation..."
# Set environment variables for the update recipe
export CLI_COMMANDS_PATH="${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md"
# Run the update recipe
goose run --recipe ../recipes/update-cli-commands.yaml 2>&1 | \
sed -E 's/\x1B\[[0-9;]*[mK]//g' | \
grep -v "^starting session" | \
grep -v "^ session id:" | \
grep -v "^ working directory:" | \
grep -v "^─── text_editor" | \
grep -v "^path:" | \
grep -v "^command:" | \
grep -v "^Closing session" | \
grep -v "^Loading recipe:" | \
grep -v "^Description:" | \
cat -s
if [ ${PIPESTATUS[0]} -ne 0 ]; then
echo "✗ Failed to update documentation (goose run failed)" >&2
exit 1
fi
echo "✓ Documentation update complete"
echo ""
echo "=========================================="
echo "Pipeline Complete!"
echo "=========================================="
echo ""
echo "Output files:"
echo " - old-cli-structure.json"
echo " - new-cli-structure.json"
echo " - cli-changes.json"
echo " - cli-changes.md"
echo ""
echo "Review the changes to the CLI commands documentation."
else
echo ""
echo "=========================================="
echo "No Changes Detected"
echo "=========================================="
echo ""
echo "No CLI changes between $OLD_VERSION and $NEW_VERSION."
echo "Documentation update not needed."
fi
@@ -15,7 +15,7 @@ We embraced this reality and put goose to work on its own backlog.
<!--truncate-->
We actually used goose pre-1.0 to help us build goose 1.0. The original goose was a Python CLI, but we needed to move quickly to Rust, Electron, and an [MCP-native](https://modelcontextprotocol.io) architecture. goose helped us make that transition. Using it to triage issues and review changes felt like a natural extension, so we embedded goose directly into a [GitHub Action](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml).
We actually used goose pre-1.0 to help us build goose 1.0. The original goose was a Python CLI, but we needed to move quickly to Rust, Electron, and an [MCP-native](https://modelcontextprotocol.io) architecture. goose helped us make that transition. Using it to triage issues and review changes felt like a natural extension, so we embedded goose directly into a [GitHub Action](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml).
:::note Credit
That GitHub Action workflow was built by [Tyler Longwell](https://github.com/tlongwell-block), who took an idea we had been exploring manually and turned it into something any maintainer could trigger with a single comment.
@@ -59,7 +59,7 @@ Maintainers summon goose with `/goose` followed by a prompt as a comment on an i
But there's more happening under the hood than a simple prompt like "/goose fix this."
The workflow uses a [recipe](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml#L14-L78) that defines phases to ensure goose actually accomplishes the job and doesn't do more than we ask it to.
The workflow uses a [recipe](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml#L14-L78) that defines phases to ensure goose actually accomplishes the job and doesn't do more than we ask it to.
| Phase | What goose does | Why it matters |
| ---------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
@@ -70,7 +70,7 @@ The workflow uses a [recipe](https://github.com/aaif-goose/goose/blob/main/.gith
| Verify | Run tests and linters | Catches obvious failures before a human sees the PR |
| Confirm | Reread the original issue and requirements | Prevents the AI from declaring victory while forgetting half the task |
The [recipe](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml) also gives goose access to the [TODO extension](/docs/mcp/todo-mcp), a built-in tool that acts as external memory. The phases tell goose *what* to do. The TODO helps goose *remember* what it's doing. As goose reads through the codebase and builds a solution, its context window fills up and earlier instructions can be compressed or lost. The TODO persists, so goose can always check what it's done and what's left.
The [recipe](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml) also gives goose access to the [TODO extension](/docs/mcp/todo-mcp), a built-in tool that acts as external memory. The phases tell goose *what* to do. The TODO helps goose *remember* what it's doing. As goose reads through the codebase and builds a solution, its context window fills up and earlier instructions can be compressed or lost. The TODO persists, so goose can always check what it's done and what's left.
The workflow also enforces guardrails around who can invoke `/goose`, which files it's allowed to touch, and the requirement that a maintainer review and approve every PR.
@@ -80,7 +80,7 @@ The future we're aiming for isn't one where AI replaces maintainers. It's one wh
If that becomes the norm, open source scales differently.
The [GitHub Action workflow](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml) is public for anyone who wants to explore this pattern in their own CI pipeline.
The [GitHub Action workflow](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml) is public for anyone who wants to explore this pattern in their own CI pipeline.
<head>
<meta property="og:title" content="How We Use goose to Maintain goose" />