Skip to content

Commit 097149c

Browse files
author
docs-generator[bot]
committed
Update docs based on PR #2533
Auto-generated by Q
1 parent 60e5f54 commit 097149c

File tree

4 files changed

+310
-0
lines changed

4 files changed

+310
-0
lines changed

‎docs/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,7 @@
44

55
- [The Agent Format](./agent-format.md)
66
- [Built-in Tools](./built-in-tools.md)
7+
- [Slash Commands](./slash-commands.md)
8+
- [To-Do List Functionality](./todo-list-functionality.md)
79
- [Knowledge Management](./knowledge-management.md)
810
- [Profile to Agent Migration](./legacy-profile-to-agent-migration.md)

‎docs/built-in-tools.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Amazon Q CLI includes several built-in tools that agents can use. This document
88
- [`report_issue`](#report_issue-tool) — Open a GitHub issue template.
99
- [`knowledge`](#knowledge-tool) — Store and retrieve information in a knowledge base.
1010
- [`thinking`](#thinking-tool) — Internal reasoning mechanism.
11+
- [`todo_list`](#todo_list-tool) — Create and manage to-do lists for multi-step tasks.
1112
- [`use_aws`](#use_aws-tool) — Make AWS CLI API calls.
1213

1314
## Execute_bash Tool
@@ -102,6 +103,29 @@ An internal reasoning mechanism that improves the quality of complex tasks by br
102103

103104
This tool has no configuration options.
104105

106+
## Todo_list Tool
107+
108+
A tool for creating and managing to-do lists for multi-step tasks. This tool is automatically used by Q when handling complex requests that require multiple steps.
109+
110+
### Key Features
111+
- **Automatic creation**: Q creates to-do lists for multi-step tasks before beginning work
112+
- **Progress tracking**: Tasks are marked as completed as Q works through them
113+
- **Context preservation**: Important information and modified files are tracked
114+
- **Persistence**: To-do lists are saved locally and can be resumed across sessions
115+
116+
### Commands
117+
The tool supports five main commands:
118+
- `create` - Create a new to-do list with tasks and description
119+
- `complete` - Mark tasks as completed and update context
120+
- `load` - Load an existing to-do list by ID
121+
- `add` - Add new tasks to an existing to-do list
122+
- `remove` - Remove tasks from an existing to-do list
123+
124+
### Storage
125+
To-do lists are stored locally in `.amazonq/cli-todo-lists/` within the current working directory.
126+
127+
This tool has no configuration options and is trusted by default.
128+
105129
## Use_aws Tool
106130

107131
Make AWS CLI API calls with the specified service, operation, and parameters.

‎docs/slash-commands.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Slash Commands
2+
3+
Slash commands provide quick access to specific Q CLI functionality during chat sessions. Commands are prefixed with `/` and can be used at any time during a conversation.
4+
5+
## New: To-Do List Management (`/todos`)
6+
7+
The `/todos` command allows you to view, manage, and resume to-do lists created by Q during multi-step tasks.
8+
9+
### `/todos resume`
10+
Select and resume work on an existing to-do list. Q will load the selected list and continue working on incomplete tasks.
11+
12+
**Usage:**
13+
```
14+
/todos resume
15+
```
16+
17+
Opens an interactive selector showing all available to-do lists with their completion status:
18+
- ✓ (green) indicates completed to-do lists
19+
- ✗ (red) indicates in-progress to-do lists with completion count (e.g., "2/5")
20+
21+
### `/todos view`
22+
View the contents of a to-do list without resuming work on it.
23+
24+
**Usage:**
25+
```
26+
/todos view
27+
```
28+
29+
Displays the selected to-do list with:
30+
- Task descriptions
31+
- Completion status (☐ for incomplete, ■ for complete)
32+
- Overall progress
33+
34+
### `/todos delete`
35+
Delete one or more to-do lists.
36+
37+
**Usage:**
38+
```
39+
/todos delete # Delete a single selected to-do list
40+
/todos delete --all # Delete all to-do lists
41+
```
42+
43+
The `--all` flag will delete all to-do lists without prompting for selection.
44+
45+
### `/todos clear-finished`
46+
Remove all completed to-do lists (where all tasks are marked as complete).
47+
48+
**Usage:**
49+
```
50+
/todos clear-finished
51+
```
52+
53+
This command automatically identifies and removes only fully completed to-do lists, leaving in-progress lists intact.
54+
55+
## Other Available Commands
56+
57+
Q CLI includes many other slash commands for various functionality:
58+
59+
### Basic Commands
60+
- `/help` - Show help information
61+
- `/clear` - Clear the conversation
62+
- `/quit` - Exit the chat session
63+
64+
### Agent Management
65+
- `/agent` - Agent-related commands
66+
- `/agent list` - List available agents
67+
- `/agent create` - Create a new agent
68+
- `/agent delete` - Delete an agent
69+
70+
### Tool Management
71+
- `/tools` - Show available tools
72+
- `/tools trust` - Trust specific tools
73+
- `/tools untrust` - Untrust specific tools
74+
75+
### Context Management
76+
- `/context` - Context-related commands
77+
- `/context show` - Show current context
78+
- `/context add` - Add context
79+
- `/context clear` - Clear context
80+
81+
### Session Management
82+
- `/save` - Save current conversation
83+
- `/load` - Load a saved conversation
84+
- `/compact` - Compact conversation history
85+
86+
### Other Features
87+
- `/model` - Model selection
88+
- `/usage` - Show usage information
89+
- `/subscribe` - Subscription management
90+
91+
## Interactive Selection
92+
93+
Most `/todos` commands use an interactive fuzzy selector that allows you to:
94+
- Type to filter to-do lists by description
95+
- Use arrow keys to navigate
96+
- Press Enter to select
97+
- Press Escape to cancel
98+
99+
The selector displays to-do lists with their completion status and description for easy identification.
100+
101+
## Integration with Q's Workflow
102+
103+
- Q automatically creates to-do lists when given multi-step tasks
104+
- To-do lists persist across chat sessions
105+
- Use `/todos resume` to continue interrupted work
106+
- To-do list IDs are included in conversation summaries for seamless resumption
107+
108+
## Storage Location
109+
110+
To-do lists are stored locally in:
111+
```
112+
.amazonq/cli-todo-lists/
113+
```
114+
115+
This directory is created automatically in your current working directory when needed.

‎docs/todo-list-functionality.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# To-Do List Functionality
2+
3+
Amazon Q CLI includes built-in to-do list functionality that allows Q to create, manage, and track multi-step tasks. This feature helps organize complex workflows and provides persistence across chat sessions.
4+
5+
## Overview
6+
7+
The to-do list functionality consists of two main components:
8+
9+
1. **`todo_list` tool** - A built-in tool that Q uses to create and manage to-do lists
10+
2. **`/todos` slash command** - User commands for viewing and managing existing to-do lists
11+
12+
## The todo_list Tool
13+
14+
The `todo_list` tool is automatically available to all agents and is trusted by default. Q uses this tool to:
15+
16+
- Create structured to-do lists for multi-step tasks
17+
- Mark tasks as completed as work progresses
18+
- Track context and modified files for each task
19+
- Load and resume existing to-do lists
20+
21+
### Tool Commands
22+
23+
#### `create`
24+
Creates a new to-do list with specified tasks and description.
25+
26+
**Parameters:**
27+
- `tasks` (required): Array of distinct task descriptions
28+
- `todo_list_description` (required): Brief summary of the to-do list
29+
30+
#### `complete`
31+
Marks tasks as completed and updates context.
32+
33+
**Parameters:**
34+
- `completed_indices` (required): Array of 0-indexed task numbers to mark complete
35+
- `context_update` (required): Important context about completed tasks
36+
- `modified_files` (optional): Array of file paths that were modified
37+
- `current_id` (required): ID of the currently loaded to-do list
38+
39+
#### `load`
40+
Loads an existing to-do list by ID.
41+
42+
**Parameters:**
43+
- `load_id` (required): ID of the to-do list to load
44+
45+
#### `add`
46+
Adds new tasks to an existing to-do list.
47+
48+
**Parameters:**
49+
- `new_tasks` (required): Array of new task descriptions
50+
- `insert_indices` (required): Array of 0-indexed positions to insert tasks
51+
- `new_description` (optional): Updated description for the to-do list
52+
- `current_id` (required): ID of the currently loaded to-do list
53+
54+
#### `remove`
55+
Removes tasks from an existing to-do list.
56+
57+
**Parameters:**
58+
- `remove_indices` (required): Array of 0-indexed positions of tasks to remove
59+
- `new_description` (optional): Updated description for the to-do list
60+
- `current_id` (required): ID of the currently loaded to-do list
61+
62+
### Tool Behavior
63+
64+
- Q automatically creates to-do lists when given multi-step tasks
65+
- Tasks are marked as completed immediately after Q finishes each step
66+
- The tool displays progress visually with checkboxes (☐ for incomplete, ■ for complete)
67+
- To-do lists are stored locally in `.amazonq/cli-todo-lists/`
68+
- Each to-do list has a unique timestamp-based ID
69+
70+
## User Commands (/todos)
71+
72+
Users can manage their to-do lists using the `/todos` slash command with various subcommands.
73+
74+
### `/todos resume`
75+
76+
Allows you to select and resume work on an existing to-do list. Q will load the selected list and continue working on incomplete tasks.
77+
78+
**Usage:**
79+
```
80+
/todos resume
81+
```
82+
83+
This opens an interactive selector showing all available to-do lists with their completion status.
84+
85+
### `/todos view`
86+
87+
View the contents of a to-do list without resuming work on it.
88+
89+
**Usage:**
90+
```
91+
/todos view
92+
```
93+
94+
This opens an interactive selector and displays the selected to-do list with all tasks and their completion status.
95+
96+
### `/todos delete`
97+
98+
Delete one or more to-do lists.
99+
100+
**Usage:**
101+
```
102+
/todos delete # Delete a single selected to-do list
103+
/todos delete --all # Delete all to-do lists
104+
```
105+
106+
### `/todos clear-finished`
107+
108+
Remove all completed to-do lists (where all tasks are marked as complete).
109+
110+
**Usage:**
111+
```
112+
/todos clear-finished
113+
```
114+
115+
## Storage and Persistence
116+
117+
### Local Storage
118+
To-do lists are stored locally in the current working directory under:
119+
```
120+
.amazonq/cli-todo-lists/
121+
```
122+
123+
Each to-do list is saved as a JSON file named with its unique ID (e.g., `1693234567890.json`).
124+
125+
### Data Structure
126+
Each to-do list contains:
127+
- **tasks**: Array of task descriptions
128+
- **completed**: Array of boolean values indicating completion status
129+
- **description**: Brief summary of the to-do list
130+
- **context**: Array of context updates from completed tasks
131+
- **modified_files**: Array of file paths that were modified during task execution
132+
- **id**: Unique identifier for the to-do list
133+
134+
### Conversation Integration
135+
To-do list IDs are automatically included in conversation summaries, allowing Q to resume work on to-do lists when conversations are loaded from history.
136+
137+
## Best Practices
138+
139+
### For Users
140+
- Use `/todos resume` to continue work on incomplete tasks
141+
- Regularly use `/todos clear-finished` to clean up completed lists
142+
- Use `/todos view` to check progress without resuming work
143+
144+
### For Q's Usage
145+
- Create to-do lists for any multi-step task before beginning work
146+
- Mark tasks as completed immediately after finishing each step
147+
- Provide meaningful context updates when completing tasks
148+
- Track modified files to maintain a record of changes
149+
150+
## Example Workflow
151+
152+
1. User asks Q to implement a new feature
153+
2. Q creates a to-do list with steps like:
154+
- Analyze requirements
155+
- Create necessary files
156+
- Implement core functionality
157+
- Add tests
158+
- Update documentation
159+
3. Q works through tasks, marking each as complete with context
160+
4. User can check progress with `/todos view`
161+
5. If interrupted, user can resume with `/todos resume`
162+
6. When finished, user can clean up with `/todos clear-finished`
163+
164+
## Limitations
165+
166+
- To-do lists are stored locally and not synchronized across different working directories
167+
- The interactive selectors require terminal support for user input
168+
- Very long task descriptions may be truncated in the display
169+
- No built-in backup or export functionality for to-do lists

0 commit comments

Comments
 (0)