# 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.