crowdtime-cli 0.1.0__py3-none-any.whl

crowdtime_cli/skills/crowdtime/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: crowdtime
+description: "CrowdTime CLI time tracking assistant. Use this skill whenever the user mentions time tracking, logging hours, starting or stopping timers, managing projects or tasks, generating time reports, checking work status, or anything related to the CrowdTime CLI tool (ct/crowdtime commands). Also trigger when users mention timesheets, billable hours, weekly summaries, project budgets, or want to track what they worked on. Even if they don't say 'CrowdTime' explicitly — if they're talking about tracking time, logging work, or checking hours in a context where the CrowdTime CLI is available, use this skill."
+---
+
+# CrowdTime CLI
+
+CrowdTime is an AI-powered time tracking CLI. The primary commands are `crowdtime` and `ct` (short alias). This skill teaches you how to use the CLI to help users track time, manage projects, and generate reports.
+
+## Before Using Any Command
+
+Check if the CLI is installed and authenticated:
+
+```bash
+ct auth whoami
+```
+
+If not authenticated, guide the user through setup:
+```bash
+ct config set server.url https://api.crowdtime.lat  # or http://localhost:8001 for local dev
+ct auth login                          # Opens browser for Google OAuth (default)
+ct auth login --token <their-api-token>  # Or provide a token directly
+ct auth login --no-browser             # Prompt for token (headless environments)
+ct org switch <org-slug>
+```
+
+## Core Commands Quick Reference
+
+### Status (default command)
+```bash
+ct              # Full dashboard: running timer, today's entries, weekly breakdown
+ct status       # Same as bare ct
+ct s            # Short alias
+ct s --json     # Machine-readable output
+```
+
+### Timers
+```bash
+ct timer start "description" -p project-slug -t "task name"  # Start a timer
+ct timer stop                                     # Stop the running timer
+ct timer status                                   # Check running timer
+ct timer switch "new task" -p other-project       # Stop current, start new (atomic)
+ct timer discard                                  # Discard without saving
+
+# Short aliases
+ct ts "working on API" -p backend    # timer start
+ct tx                                # timer stop
+ct t                                 # timer status
+```
+
+### Logging Time
+
+**Options MUST come BEFORE positional arguments (duration, description).**
+
+```bash
+# Log time entries (all equivalent):
+ct log -p project-slug 2h "code review"
+ct log -p project-slug -t "Design" -d yesterday 2h30m "meeting"
+ct log -p project-slug -b 1:30 "design work"
+
+# Short alias — `ct l`:
+ct l -p project-slug 2h "code review"
+ct l -p project-slug -t "Research" -d yesterday 2h30m "meeting"
+```
+
+Other log commands:
+```bash
+ct log list --week                                  # This week's entries
+ct log list --json                                  # JSON output
+ct log edit <entry-id> --duration 3h               # Edit an entry
+ct log edit <entry-id> --task "Research"            # Change task
+ct log delete <entry-id>                           # Delete an entry
+
+# Short aliases
+ct ll                                # log list (today)
+ct ll --week                         # log list this week
+ct ll --month                        # log list this month
+ct ll --json                         # log list as JSON
+```
+
+**Duration formats**: `2h`, `2h30m`, `2:30`, `150m`, `0.25d` (1 day = 8h), or plain number (hours)
+
+**Date formats**: `today`, `yesterday`, `monday`..`sunday`, `last friday`, `2026-03-10`, `3/10`
+
+### Clients
+```bash
+ct clients list                     # List all clients
+ct clients show <id>                # Client details
+ct clients create "Acme Corp"       # Create a client
+ct clients create "Acme" --contact "John" --email john@acme.com
+ct clients archive <id>             # Archive a client
+```
+
+### Projects
+```bash
+ct projects list                    # List all projects
+ct projects show <id>               # Project details
+ct projects create "New Project" --client "Acme" --budget 100 -b
+ct projects archive <id>            # Archive a project
+ct projects switch <slug>           # Set default project
+
+# Short alias
+ct p                                # projects list
+ct p -a                             # include archived
+```
+
+**Note:** `--client` on `projects create` accepts a client name. If the client doesn't exist yet, it will be auto-created.
+
+### Tasks
+```bash
+ct tasks list                       # List all org tasks
+ct tasks list -p project-slug       # Filter by project
+ct tasks create "Code Review" -p project-slug -b   # Create and assign to project
+```
+
+**Note:** `tasks create -p` creates the task at the org level AND assigns it to the specified project. The `-t` flag on `ct log create` and `ct timer start` accepts task names — if the task doesn't exist, it will be auto-created and assigned to the project.
+
+### Reports
+```bash
+ct report --week                    # This week (default)
+ct report --month                   # This month
+ct report --today                   # Today
+ct report --from 2026-03-01 --to 2026-03-15 -p project-slug
+ct report -g day                    # Group by day (also: project, task, client)
+ct report -f csv                    # Output as CSV (also: table, json, markdown)
+ct report projects --month          # Project breakdown
+ct report team --week               # Team utilization
+
+# Short alias
+ct r --week                         # report this week
+```
+
+### AI Features
+```bash
+ct ai suggest                            # Get AI suggestions based on your patterns
+ct ai summarize --week                   # Weekly summary
+ct ai summarize --for standup            # Formatted for standup
+ct ai summarize --for slack --copy       # Formatted for Slack, copied to clipboard
+```
+
+### Favorites
+```bash
+ct favorites list                        # List saved templates
+ct favorites create "Daily standup" -p meetings -t standup
+ct favorites start <id>                  # Start timer from template
+ct favorites delete <id>
+```
+
+### Organizations
+```bash
+ct org list                             # List your organizations
+ct org switch <slug>                    # Switch active organization
+ct org members                          # List members
+ct org invite user@example.com -r member
+```
+
+### Configuration
+```bash
+ct config list                          # Show all config
+ct config set server.url https://...    # Set server URL
+ct config set defaults.project myproj   # Set default project
+ct config set defaults.daily_target 7h  # Set daily target
+ct config edit                          # Open in editor
+```
+
+## Common Workflows
+
+Read `references/workflows.md` for detailed multi-step workflow patterns including:
+- Daily time tracking routines
+- End-of-week reporting
+- Project setup and management
+- Bulk time entry for past days
+- Team management and timesheets
+
+## Complete Command Reference
+
+Read `references/commands.md` for the full reference of every command, subcommand, flag, and option available in the CLI.
+
+## Guidelines for Helping Users
+
+1. **Always check status first** — run `ct s --json` to understand current state (running timer, today's entries) before suggesting actions
+2. **Always use explicit commands** — always construct the full `ct log`, `ct timer start`, etc. commands with proper flags. Never use magic routing (`ct "natural language"`) or `ct ai parse` — you are an LLM fully capable of constructing the correct command yourself
+3. **Always ask for the project if missing** — if the user asks to log time without specifying a project, ASK them which project before running the command. Run `ct p --json` to list available projects and present them as options. Never log time without a project unless the user has a default set (check `ct config get defaults.project`). If there's only one project available, use it automatically without asking
+4. **Project identifiers** — the `-p` flag on `ct log`, `ct timer start`, etc. accepts a project **slug** (e.g. `crowdtime-dev`) or **UUID** — NOT the display name. Get the slug or UUID from `ct p --json` first
+5. **Task identifiers** — the `-t` flag accepts a task **name** or **UUID**. The CLI will auto-resolve names to UUIDs. If a task doesn't exist, it will be auto-created and assigned to the project. **Prefer using tasks when logging time** — they make reports and summaries much more useful. If the user doesn't specify a task but describes their work (e.g. "code review", "meeting", "design"), suggest an appropriate task name
+6. **Flag ordering for `ct log` / `ct l`** — ALL options (`-p`, `-d`, `-b`, `-t`) MUST come BEFORE the positional arguments (duration, description). Example: `ct log -p myproject -t "Research" -d yesterday 2h "description"`. Getting this wrong causes errors
+7. **Use `--json` for parsing** — when you need to process output programmatically, add `--json` to any command
+8. **Respect running timers** — check `ct t --json` before starting a new timer; use `ct timer switch` to atomically swap
+9. **Default project** — if the user frequently logs to the same project, suggest `ct projects switch <slug>` to set a default
+10. **Date intelligence** — the CLI understands natural dates; use `yesterday`, `last friday`, etc. rather than computing ISO dates
+11. **Confirm destructive actions** — `delete`, `discard`, and `archive` commands ask for confirmation; use `--force` only when the user explicitly wants to skip
+12. **Output formats** — `ct report` supports `table`, `json`, `csv`, and `markdown` via `--format`; suggest `csv` for spreadsheet export, `markdown` for docs
+13. **Ask for details when vague** — if the user's request is ambiguous (e.g. "log 2 hours" with no description or project), ask them for the missing context rather than guessing. It's better to ask one clarifying question than to log something wrong that needs to be edited or deleted