83 lines
2.6 KiB
Plaintext
83 lines
2.6 KiB
Plaintext
# AGENTS.txt - Development Preferences and Patterns
|
|
|
|
This file documents preferences and patterns for AI agents working on this project.
|
|
|
|
## CLI Command Alias Preferences
|
|
|
|
When implementing CLI commands, follow these patterns:
|
|
|
|
### Command Aliases
|
|
- Prefer short aliases for common commands:
|
|
- `list` → `ls` (Unix-style listing)
|
|
- `add` → `a` (quick task creation)
|
|
- `edit` → `e` (quick editing)
|
|
- `complete` → `c`, `done` (task completion)
|
|
- `delete` → `rm`, `del` (Unix-style removal)
|
|
- `open` → `o` (quick opening)
|
|
- `show` → `view`, `s` (viewing details)
|
|
|
|
### Option/Flag Aliases
|
|
- Use single letter flags where possible:
|
|
- `--due-date` → `-d`
|
|
- `--project` → `-p`
|
|
- `--priority` → `-pr`
|
|
- `--tag` → `-t`
|
|
- `--all` → `-a`
|
|
- `--force` → `-f`
|
|
- `--browser` → `-b`
|
|
- `--content` → `-c`
|
|
- `--limit` → `-l`
|
|
|
|
### Design Principles
|
|
- Follow Unix CLI conventions where applicable
|
|
- Provide both full and abbreviated forms for all commands
|
|
- Single-letter aliases for the most frequently used operations
|
|
- Intuitive mappings (e.g., `rm` for delete, `ls` for list)
|
|
- Consistent patterns across different modules
|
|
|
|
## Project Structure Patterns
|
|
|
|
### Services
|
|
- Place API clients in `src/services/<service_name>/`
|
|
- Include authentication in `auth.py`
|
|
- Main client logic in `client.py`
|
|
- Exports in `__init__.py`
|
|
|
|
### CLI Commands
|
|
- Group related commands in `src/cli/<service_name>.py`
|
|
- Register with main CLI in `src/cli/__init__.py`
|
|
- Use Click for command framework
|
|
|
|
### Utilities
|
|
- Shared utilities in `src/utils/`
|
|
- Service-specific utilities in `src/utils/<service_name>_utils.py`
|
|
|
|
### Token Storage
|
|
- Store auth tokens in `~/.local/share/gtd-terminal-tools/`
|
|
- Use project name consistently across services
|
|
|
|
## TickTick Integration Notes
|
|
|
|
### Authentication
|
|
- Uses OAuth2 flow with client credentials
|
|
- Tokens cached in `~/.local/share/gtd-terminal-tools/ticktick_tokens.json`
|
|
- Environment variables: `TICKTICK_CLIENT_ID`, `TICKTICK_CLIENT_SECRET`, `TICKTICK_REDIRECT_URI`
|
|
|
|
### Command Usage Examples
|
|
```bash
|
|
# List tasks
|
|
ticktick ls -p "Work" # List by project
|
|
ticktick ls -d today # List by due date
|
|
ticktick ls -pr high # List by priority
|
|
|
|
# Task operations
|
|
ticktick a "Buy groceries" -d tomorrow -p "Personal"
|
|
ticktick e 123 --title "Updated task"
|
|
ticktick c 123 # Complete task
|
|
ticktick rm 123 -f # Force delete task
|
|
ticktick o 123 # Open in browser/app
|
|
```
|
|
|
|
## Future Development
|
|
|
|
When adding new services or commands, follow these established patterns for consistency. |