Update docs based on PR #2533

.github/workflows/docs-generator.yaml

@@ -0,0 +1,65 @@
+name: docs-generator
+
+on:
+  # workflow_dispatch:
+  #   inputs:
+  #     pr_number:
+  #       description: 'Number of PR to document'
+  #       required: true
+  #       type: string
+  push:
+
+jobs:
+  generate_docs:
+    runs-on: ubuntu-latest
+    env:
+      AMAZON_Q_SIGV4: 1
+      CHAT_DOWNLOAD_ROLE_ARN: ${{ secrets.CHAT_DOWNLOAD_ROLE_ARN }}
+      CHAT_BUILD_BUCKET_NAME: ${{ secrets.CHAT_BUILD_BUCKET_NAME }}
+      PR_FILE: "pr-contents.txt"
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GIT_HASH: "latest"
+      TEST_PR_NUMBER: 2533
+    permissions:
+      id-token: write
+      contents: write
+      pull-requests: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Fetch main branch
+      run: git fetch origin main:main
+
+    - name: Configure AWS credentials
+      uses: aws-actions/configure-aws-credentials@v4
+      with:
+        role-to-assume: ${{ secrets.AWS_TB_ROLE }}
+        aws-region: us-east-1
+
+    - name: Make scripts executable
+      run: |
+        chmod +x docs-generation/setup_amazon_q.sh
+        chmod +x docs-generation/create-docs-pr.sh
+        chmod +x docs-generation/read-pr.sh
+        chmod +x docs-generation/update-docs.sh
+
+    - name: Run setup script
+      run: bash docs-generation/setup_amazon_q.sh
+
+    - name: Generate PR contents file
+      run: bash docs-generation/read-pr.sh ${{ env.TEST_PR_NUMBER }}
+
+    - name: Update docs
+      run: bash docs-generation/update-docs.sh
+
+    - name: Create PR
+      if: success()
+      run: bash docs-generation/create-docs-pr.sh ${{ env.TEST_PR_NUMBER }}
+
+
+
+
+
+

docs-generation/create-docs-pr.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+set -e
+
+PR_NUMBER=$1
+BRANCH_NAME="docs-update-for-pr-$PR_NUMBER"
+
+# Ensure we have changes to merge
+if [ -z "$(git status --porcelain)" ]; then
+    echo "No changes to commit"
+    exit 0
+fi
+
+git config user.name "docs-generator[bot]"
+git config user.email "docs-generator[bot]@amazon.com"
+
+# Create branch and push
+git checkout -b "$BRANCH_NAME"
+git add .
+git commit -m "Update docs based on PR #$PR_NUMBER
+
+Auto-generated by Q"
+
+git push origin "$BRANCH_NAME"
+
+# Create PR
+gh pr create \
+  --title "Update docs based on PR #$PR_NUMBER" \
+  --body "Auto-generated documentation updates based on changes in PR #$PR_NUMBER" \
+  --base main \
+  --head "$BRANCH_NAME"

docs-generation/read-pr.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -e
+
+PR_NUMBER=$1
+
+# Add PR information
+echo "====== PR Information ======\n" > $PR_FILE
+gh pr view $PR_NUMBER --json title,body --jq '"Title: " + .title + "\nDescription: " + .body' >> $PR_FILE
+
+# Include PR diffs
+echo -e "\n====== PR Diffs ======\n" >> $PR_FILE
+gh pr diff $PR_NUMBER >> $PR_FILE
+
+
+
+
+
+

docs-generation/setup_amazon_q.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+set -e
+# if git hash empty then set to latest auto
+sudo apt-get update
+sudo apt-get install -y curl wget unzip jq
+
+# Create AWS credentials from environment variables
+mkdir -p ~/.aws
+cat > ~/.aws/credentials << EOF
+[default]
+aws_access_key_id = ${AWS_ACCESS_KEY_ID}
+aws_secret_access_key = ${AWS_SECRET_ACCESS_KEY}
+aws_session_token = ${AWS_SESSION_TOKEN}
+EOF
+chmod 600 ~/.aws/credentials
+
+cat > ~/.aws/config << EOF
+[default]
+region = us-east-1
+EOF
+chmod 600 ~/.aws/config
+
+# Assume role and capture temporary credentials --> needed for s3 bucket access for build
+echo "Assuming AWS s3 role"
+TEMP_CREDENTIALS=$(aws sts assume-role --role-arn ${CHAT_DOWNLOAD_ROLE_ARN} --role-session-name S3AccessSession 2>/dev/null || echo '{}')
+QCHAT_ACCESSKEY=$(echo $TEMP_CREDENTIALS | jq -r '.Credentials.AccessKeyId')
+Q_SECRET_ACCESS_KEY=$(echo $TEMP_CREDENTIALS | jq -r '.Credentials.SecretAccessKey')
+Q_SESSION_TOKEN=$(echo $TEMP_CREDENTIALS | jq -r '.Credentials.SessionToken')
+
+# Download specific build from S3 based on commit hash
+echo "Downloading Amazon Q CLI build from S3..."
+S3_PREFIX="main/${GIT_HASH}/x86_64-unknown-linux-musl"
+echo "Downloading qchat.zip from s3://.../${S3_PREFIX}/qchat.zip"
+
+# Try download, if hash is invalid we fail.
+AWS_ACCESS_KEY_ID="$QCHAT_ACCESSKEY" AWS_SECRET_ACCESS_KEY="$Q_SECRET_ACCESS_KEY" AWS_SESSION_TOKEN="$Q_SESSION_TOKEN" \
+  aws s3 cp s3://${CHAT_BUILD_BUCKET_NAME}/${S3_PREFIX}/qchat.zip ./qchat.zip --region us-east-1
+
+# Handle the zip file, copy the qchat executable to /usr/local/bin + symlink from old code
+echo "Extracting qchat.zip..."
+unzip -q qchat.zip
+
+# move it to /usr/local/bin/qchat for path as qchat may not work otherwise
+if cp qchat /usr/local/bin/ && chmod +x /usr/local/bin/qchat; then
+    ln -sf /usr/local/bin/qchat /usr/local/bin/q
+    echo "qchat installed successfully"
+else
+    echo "ERROR: Failed to install qchat"
+    exit 1
+fi
+
+echo "Cleaning q zip"
+rm -f qchat.zip
+rm -rf qchat

docs-generation/update-docs.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+set -e
+
+if [ ! -f "$PR_FILE" ]; then
+    echo "PR file not found, aborting"
+    exit 1
+fi
+
+PROMPT="Before making any changes, read the 'docs' directory for the project's current
+documentation. Then read 'pr-contents.txt' to see the contents of the current PR.\n\n
+After reading both the directory and the PR file, update the files in the 'docs' directory 
+with new documentation reflecting the proposed changes in the PR. Make new files as appropriate."
+
+timeout 10m echo -e $PROMPT | qchat chat --non-interactive --trust-all-tools
+exit $?

docs/SUMMARY.md

@@ -4,5 +4,7 @@
 
 - [The Agent Format](./agent-format.md)
 - [Built-in Tools](./built-in-tools.md)
+- [Slash Commands Reference](./slash-commands.md)
+- [To-Do List Management](./todo-lists.md)
 - [Knowledge Management](./knowledge-management.md)
 - [Profile to Agent Migration](./legacy-profile-to-agent-migration.md)

docs/agent-file-locations.md

@@ -108,3 +108,23 @@ EOF
 ## Directory Creation
 
 Q CLI will automatically create the global agents directory (`~/.aws/amazonq/cli-agents/`) if it doesn't exist. However, you need to manually create the local agents directory (`.amazonq/cli-agents/`) in your workspace if you want to use local agents.
+
+## Related Local Storage
+
+In addition to agent configurations, Q CLI stores other workspace-specific data in the `.amazonq/` directory:
+
+### To-Do Lists
+To-do lists created by the `todo_list` tool are stored in:
+```
+.amazonq/cli-todo-lists/
+```
+
+These files persist across chat sessions and allow you to resume work on incomplete tasks using the `/todos` slash commands.
+
+### Legacy Configuration
+Legacy MCP server configurations may be stored in:
+```
+.amazonq/mcp.json
+```
+
+This file is used when agents have `useLegacyMcpJson` set to `true`.

docs/built-in-tools.md

@@ -8,6 +8,7 @@ Amazon Q CLI includes several built-in tools that agents can use. This document
 - [`report_issue`](#report_issue-tool) — Open a GitHub issue template.
 - [`knowledge`](#knowledge-tool) — Store and retrieve information in a knowledge base.
 - [`thinking`](#thinking-tool) — Internal reasoning mechanism.
+- [`todo_list`](#todo_list-tool) — Create and manage to-do lists for multi-step tasks.
 - [`use_aws`](#use_aws-tool) — Make AWS CLI API calls.
 
 ## Execute_bash Tool
@@ -102,6 +103,71 @@ An internal reasoning mechanism that improves the quality of complex tasks by br
 
 This tool has no configuration options.
 
+## Todo_list Tool
+
+Create and manage to-do lists for multi-step tasks. This tool helps track progress on complex tasks by breaking them down into manageable steps and marking completion as work progresses.
+
+The tool automatically creates to-do lists when you give Amazon Q multi-step tasks and tracks completion status. To-do lists are stored locally in the `.amazonq/cli-todo-lists/` directory and persist across chat sessions.
+
+### Commands
+
+#### `create`
+Creates a new to-do list with specified tasks and description.
+
+**Required parameters:**
+- `tasks`: Array of distinct task descriptions
+- `todo_list_description`: Brief summary of the to-do list
+
+#### `complete`
+Marks specified tasks as completed and updates context.
+
+**Required parameters:**
+- `completed_indices`: Array of 0-indexed task numbers to mark complete
+- `context_update`: Important information about completed tasks
+- `current_id`: ID of the currently loaded to-do list
+
+**Optional parameters:**
+- `modified_files`: Array of file paths that were modified during the task
+
+#### `load`
+Loads an existing to-do list by ID.
+
+**Required parameters:**
+- `load_id`: ID of the to-do list to load
+
+#### `add`
+Adds new tasks to the current to-do list.
+
+**Required parameters:**
+- `new_tasks`: Array of new task descriptions
+- `insert_indices`: Array of 0-indexed positions where tasks should be inserted
+- `current_id`: ID of the currently loaded to-do list
+
+**Optional parameters:**
+- `new_description`: Updated description if tasks significantly change the goal
+
+#### `remove`
+Removes tasks from the current to-do list.
+
+**Required parameters:**
+- `remove_indices`: Array of 0-indexed positions of tasks to remove
+- `current_id`: ID of the currently loaded to-do list
+
+**Optional parameters:**
+- `new_description`: Updated description if removal significantly changes the goal
+
+### Configuration
+
+This tool has no configuration options and is trusted by default.
+
+### Usage Notes
+
+- To-do lists are automatically created when you give Amazon Q complex, multi-step tasks
+- Tasks should be marked as completed immediately after finishing each step
+- The tool tracks file modifications and important context for each completed task
+- To-do lists persist across chat sessions and can be resumed later
+- Use the `/todos` slash command to view, manage, and resume existing to-do lists
+
 ## Use_aws Tool
 
 Make AWS CLI API calls with the specified service, operation, and parameters.

docs/default-agent-behavior.md

@@ -49,10 +49,11 @@ If no agent is specified or found, Q CLI uses a built-in default agent with the
 The built-in default agent provides:
 
 ### Available Tools
-- **All tools**: Uses `"*"` wildcard to include all built-in tools and MCP server tools
+- **All tools**: Uses `"*"` wildcard to include all built-in tools (including `todo_list`) and MCP server tools
 
 ### Trusted Tools
 - **fs_read only**: Only the `fs_read` tool is pre-approved and won't prompt for permission
+- **todo_list**: The `todo_list` tool is also trusted by default for task management
 - All other tools will require user confirmation before execution
 
 ### Default Resources