Skip to content

Commit 588c5c5

Browse files
author
docs-generator[bot]
committed
Update docs based on PR #2533
Auto-generated by Q
1 parent c7f7591 commit 588c5c5

File tree

6 files changed

+415
-3
lines changed

6 files changed

+415
-3
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 Quick Reference](./todo-quick-reference.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: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Amazon Q CLI includes several built-in tools that agents can use. This document
99
- [`knowledge`](#knowledge-tool) — Store and retrieve information in a knowledge base.
1010
- [`thinking`](#thinking-tool) — Internal reasoning mechanism.
1111
- [`use_aws`](#use_aws-tool) — Make AWS CLI API calls.
12+
- [`todo_list`](#todo_list-tool) — Create and manage to-do lists.
1213

1314
## Execute_bash Tool
1415

@@ -126,6 +127,82 @@ Make AWS CLI API calls with the specified service, operation, and parameters.
126127
| `allowedServices` | array of strings | `[]` | List of AWS services that can be accessed without prompting |
127128
| `deniedServices` | array of strings | `[]` | List of AWS services to deny. Deny rules are evaluated before allow rules |
128129

130+
## Todo_list Tool
131+
132+
Create and manage to-do lists that persist across chat sessions. This tool allows Amazon Q to break down complex tasks into manageable steps and track progress as tasks are completed.
133+
134+
### Key Features
135+
136+
- **Automatic Task Creation**: Q automatically creates to-do lists when given multi-step tasks
137+
- **Progress Tracking**: Tasks are marked as completed as Q works through them
138+
- **Persistent Storage**: To-do lists are saved locally and persist across sessions
139+
- **Context Tracking**: Important information and modified files are tracked with each task
140+
- **Resume Functionality**: Users can resume incomplete to-do lists from previous sessions
141+
142+
### Commands
143+
144+
#### `create`
145+
Creates a new to-do list with specified tasks and description.
146+
147+
**Parameters:**
148+
- `tasks` (required): Array of distinct task descriptions
149+
- `todo_list_description` (required): Brief summary of the to-do list
150+
151+
#### `complete`
152+
Marks tasks as completed and updates context information.
153+
154+
**Parameters:**
155+
- `completed_indices` (required): Array of 0-indexed task numbers to mark as complete
156+
- `context_update` (required): Important context about completed tasks
157+
- `modified_files` (optional): Array of file paths that were modified
158+
- `current_id` (required): ID of the currently loaded to-do list
159+
160+
#### `load`
161+
Loads an existing to-do list by ID.
162+
163+
**Parameters:**
164+
- `load_id` (required): ID of the to-do list to load
165+
166+
#### `add`
167+
Adds new tasks to an existing to-do list.
168+
169+
**Parameters:**
170+
- `new_tasks` (required): Array of new task descriptions
171+
- `insert_indices` (required): Array of 0-indexed positions to insert tasks
172+
- `new_description` (optional): Updated description for the to-do list
173+
- `current_id` (required): ID of the currently loaded to-do list
174+
175+
#### `remove`
176+
Removes tasks from an existing to-do list.
177+
178+
**Parameters:**
179+
- `remove_indices` (required): Array of 0-indexed positions of tasks to remove
180+
- `new_description` (optional): Updated description for the to-do list
181+
- `current_id` (required): ID of the currently loaded to-do list
182+
183+
### Storage Location
184+
185+
To-do lists are stored locally in the current working directory under:
186+
```
187+
.amazonq/cli-todo-lists/
188+
```
189+
190+
Each to-do list is saved as a JSON file with a timestamp-based ID.
191+
192+
### Usage Patterns
193+
194+
**Automatic Creation**: When you give Q a complex task, it will automatically create a to-do list before starting work:
195+
```
196+
User: "Set up a new React project with TypeScript and testing"
197+
Q: [Creates to-do list with steps like "Initialize project", "Configure TypeScript", "Set up testing framework", etc.]
198+
```
199+
200+
**Progress Tracking**: Q marks tasks as completed immediately after finishing them, providing visual feedback on progress.
201+
202+
**Context Preservation**: Each completed task includes context about what was accomplished and which files were modified, helping maintain continuity across sessions.
203+
204+
This tool has no configuration options and is trusted by default.
205+
129206
## Using Tool Settings in Agent Configuration
130207

131208
Tool settings are specified in the `toolsSettings` section of the agent configuration file. Each tool's settings are specified using the tool's name as the key.
@@ -162,5 +239,5 @@ Tools can be explicitly allowed in the `allowedTools` section of the agent confi
162239
If a tool is not in the `allowedTools` list, the user will be prompted for permission when the tool is used unless an allowed `toolSettings` configuration is set.
163240

164241
Some tools have default permission behaviors:
165-
- `fs_read` and `report_issue` are trusted by default
242+
- `fs_read`, `report_issue`, and `todo_list` are trusted by default
166243
- `execute_bash`, `fs_write`, and `use_aws` prompt for permission by default, but can be configured to allow specific commands/paths/services

‎docs/default-agent-behavior.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ If no agent is specified or found, Q CLI uses a built-in default agent with the
3434
"name": "default",
3535
"description": "Default agent",
3636
"tools": ["*"],
37-
"allowedTools": ["fs_read"],
37+
"allowedTools": ["fs_read", "todo_list"],
3838
"resources": [
3939
"file://AmazonQ.md",
4040
"file://README.md",
@@ -52,7 +52,7 @@ The built-in default agent provides:
5252
- **All tools**: Uses `"*"` wildcard to include all built-in tools and MCP server tools
5353

5454
### Trusted Tools
55-
- **fs_read only**: Only the `fs_read` tool is pre-approved and won't prompt for permission
55+
- **fs_read and todo_list**: Only the `fs_read` and `todo_list` tools are pre-approved and won't prompt for permission
5656
- All other tools will require user confirmation before execution
5757

5858
### Default Resources

‎docs/introduction.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,11 @@ Welcome to the supplementary Amazon Q CLI Developer documentation.
44
This documentation supplements [the primary Amazon Q CLI documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html).
55

66
These docs are experimental, work in progress, and subject to change. As of now, they do not represent latest stable builds, instead documenting the functionality of development builds.
7+
8+
## Key Features Covered
9+
10+
- **Agent Configuration**: Learn how to create and configure custom agents with specific tools, resources, and behaviors
11+
- **Built-in Tools**: Comprehensive guide to all available tools including file operations, AWS integration, and task management
12+
- **Slash Commands**: Direct system commands for managing to-do lists, knowledge bases, and other features
13+
- **Knowledge Management**: Persistent knowledge bases with semantic search capabilities
14+
- **Migration Guide**: How to migrate from legacy profiles to the new agent system

‎docs/slash-commands.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Slash Commands
2+
3+
Amazon Q CLI provides several slash commands that allow you to interact with the system and manage your workflow without sending messages to the AI model. These commands are prefixed with `/` and provide direct access to various features.
4+
5+
## Available Commands
6+
7+
### `/todos` - To-Do List Management
8+
9+
The `/todos` command provides comprehensive management of to-do lists created by Amazon Q. When Q breaks down complex tasks into manageable steps, you can use these commands to view, resume, and manage your to-do lists.
10+
11+
#### `/todos resume`
12+
13+
Resume working on a selected to-do list. This command presents a fuzzy-searchable list of all incomplete to-do lists and allows you to select one to continue working on.
14+
15+
**Usage:**
16+
```
17+
/todos resume
18+
```
19+
20+
**Behavior:**
21+
- Displays all incomplete to-do lists with progress indicators
22+
- Allows fuzzy search to quickly find specific lists
23+
- Automatically loads the selected to-do list and prompts Q to continue working
24+
- Shows completion status (e.g., "3/7 tasks completed")
25+
26+
#### `/todos view`
27+
28+
View the details of a selected to-do list without resuming work on it.
29+
30+
**Usage:**
31+
```
32+
/todos view
33+
```
34+
35+
**Features:**
36+
- Browse all to-do lists (both complete and incomplete)
37+
- View full task lists with completion status
38+
- See task descriptions and context
39+
- Non-destructive viewing (doesn't change current session state)
40+
41+
#### `/todos delete`
42+
43+
Delete one or more to-do lists.
44+
45+
**Usage:**
46+
```
47+
/todos delete # Delete a single selected list
48+
/todos delete --all # Delete all to-do lists
49+
```
50+
51+
**Options:**
52+
- Without `--all`: Presents a selection interface to choose which list to delete
53+
- With `--all`: Deletes all to-do lists after confirmation
54+
- Deletion is permanent and cannot be undone
55+
56+
#### `/todos clear-finished`
57+
58+
Remove all completed to-do lists while preserving incomplete ones.
59+
60+
**Usage:**
61+
```
62+
/todos clear-finished
63+
```
64+
65+
**Behavior:**
66+
- Automatically identifies to-do lists where all tasks are marked complete
67+
- Removes only fully completed lists
68+
- Preserves any lists with remaining tasks
69+
- Provides feedback on how many lists were cleared
70+
71+
### `/knowledge` - Knowledge Base Management
72+
73+
The `/knowledge` command provides persistent knowledge base functionality with semantic search capabilities. For complete documentation, see the [Knowledge Management guide](./knowledge-management.md).
74+
75+
#### Quick Reference
76+
77+
| Command | Purpose |
78+
|---------|---------|
79+
| `/knowledge show` | Display all knowledge base entries |
80+
| `/knowledge add <name> <path>` | Add files/directories to knowledge base |
81+
| `/knowledge remove <identifier>` | Remove entries by name, path, or ID |
82+
| `/knowledge update <path>` | Update existing entry with new content |
83+
| `/knowledge clear` | Remove all entries (with confirmation) |
84+
| `/knowledge status` | View indexing operation status |
85+
| `/knowledge cancel [id]` | Cancel background operations |
86+
87+
**Example Usage:**
88+
```
89+
/knowledge add "project-docs" ./docs --include "**/*.md"
90+
/knowledge show
91+
/knowledge remove "old-project"
92+
```
93+
94+
### Other Slash Commands
95+
96+
Additional slash commands are available for various system functions:
97+
98+
- `/save` - Save current conversation
99+
- `/load` - Load a saved conversation
100+
- `/subscribe` - Manage subscription settings
101+
102+
## To-Do List Display Format
103+
104+
When viewing to-do lists, they are displayed with clear visual indicators:
105+
106+
- **Incomplete tasks**: `☐ Task description`
107+
- **Completed tasks**: `■ Task description` (green, italicized)
108+
- **Progress indicators**: `(3/7)` showing completed vs total tasks
109+
- **Status symbols**:
110+
- `✗` (red) for incomplete lists
111+
- `✓` (green) for completed lists
112+
113+
## Integration with Chat Sessions
114+
115+
### Automatic Creation
116+
When you give Amazon Q a complex, multi-step task, it will automatically:
117+
1. Create a to-do list using the `todo_list` tool
118+
2. Display the list to you
119+
3. Begin working through tasks sequentially
120+
4. Mark tasks as complete as it finishes them
121+
122+
### Session Persistence
123+
To-do lists persist across chat sessions:
124+
- Lists are saved locally in `.amazonq/cli-todo-lists/`
125+
- You can resume work on incomplete lists in new sessions
126+
- Context and progress are preserved between sessions
127+
- Conversation summaries include to-do list IDs for continuity
128+
129+
### Resume Workflow
130+
When resuming a to-do list:
131+
1. Use `/todos resume` to select a list
132+
2. Q automatically loads the list context
133+
3. Q reviews completed tasks and remaining work
134+
4. Q continues from where it left off
135+
136+
## Best Practices
137+
138+
### For Users
139+
- **Use descriptive task requests**: Clear, detailed requests help Q create better to-do lists
140+
- **Let Q manage the lists**: Avoid manually editing to-do list files
141+
- **Regular cleanup**: Use `/todos clear-finished` to remove completed lists
142+
- **Resume incomplete work**: Check for incomplete lists when starting new sessions
143+
144+
### For Complex Projects
145+
- **Break down large tasks**: Give Q specific, focused objectives for better to-do list creation
146+
- **Provide context**: Include relevant background information when requesting complex tasks
147+
- **Review progress**: Use `/todos view` to check progress without disrupting current work
148+
- **Organize by project**: Consider using separate chat sessions for different projects
149+
150+
## Storage and File Management
151+
152+
### Local Storage
153+
- **Location**: `.amazonq/cli-todo-lists/` in your current working directory
154+
- **Format**: JSON files with timestamp-based IDs
155+
- **Automatic creation**: Directory is created automatically when needed
156+
157+
### File Structure
158+
Each to-do list contains:
159+
- Task descriptions and completion status
160+
- Context updates from completed tasks
161+
- List of modified files
162+
- Unique identifier and creation metadata
163+
164+
### Cleanup
165+
- Use slash commands rather than manually deleting files
166+
- The system handles file management automatically
167+
- Backup important project directories if needed
168+
169+
## Troubleshooting
170+
171+
### Common Issues
172+
173+
**"No to-do lists to resume"**
174+
- This means no incomplete to-do lists exist
175+
- Create new tasks by giving Q complex, multi-step requests
176+
- Check if lists were accidentally deleted
177+
178+
**Lists not appearing**
179+
- Ensure you're in the correct working directory
180+
- To-do lists are stored relative to where they were created
181+
- Check `.amazonq/cli-todo-lists/` exists and contains files
182+
183+
**Cannot resume a list**
184+
- The to-do list file may be corrupted
185+
- Try `/todos view` to see if the list displays correctly
186+
- Consider deleting corrupted lists and recreating tasks
187+
188+
**Performance with many lists**
189+
- Use `/todos clear-finished` regularly to remove completed lists
190+
- Consider organizing work into separate project directories
191+
- Delete old, irrelevant lists to improve performance
192+
193+
### Getting Help
194+
195+
If you encounter issues with to-do list functionality:
196+
1. Check that the `.amazonq/cli-todo-lists/` directory exists and is writable
197+
2. Verify you're in the correct working directory
198+
3. Try creating a simple test to-do list to verify functionality
199+
4. Use `/todos view` to inspect existing lists for corruption

0 commit comments

Comments
 (0)