wip

AGENTS.txt

@@ -0,0 +1,83 @@
+# 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.