Initial commit

2025-11-29 18:03:09 +08:00
commit 1876a4de0d
8 changed files with 830 additions and 0 deletions
--- a/commands/calc.md
+++ b/commands/calc.md
@@ -0,0 +1,129 @@
+---
+description: Calculate date/time differences (Claude should use date command directly)
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+# calc - Calculate date/time differences
+
+Calculate the difference between two dates or times using natural language expressions.
+
+## For Claude Code
+
+**If you are Claude**: DO NOT invoke this slash command. Use unix timestamp arithmetic via Bash tool:
+
+```bash
+date1=$(date -d "first date" +%s)
+date2=$(date -d "second date" +%s)
+diff=$((date2 - date1))
+echo "Difference: $diff seconds"
+```
+
+See the Implementation section below for the full calculation pattern.
+
+## For Users
+
+### Usage
+
+```bash
+/datetime:calc
+```
+
+The command will interactively ask for two date/time expressions, then calculate the difference.
+
+## What it does
+
+1. **Asks for first date/time**: Accepts natural language expression (e.g., "tomorrow", "2024-12-01", "next Monday")
+2. **Asks for second date/time**: Accepts natural language expression
+3. **Calculates difference**: Shows the time between the two dates in multiple units
+4. **Human-readable output**: Displays results as days, hours, minutes, and seconds
+
+The calculation uses unix timestamps internally for accuracy across timezones and DST boundaries.
+
+## Implementation
+
+**Convert dates to unix timestamps:**
+```bash
+date1_ts=$(date -d "first expression" +%s)
+date2_ts=$(date -d "second expression" +%s)
+```
+
+**Calculate difference:**
+```bash
+diff_seconds=$((date2_ts - date1_ts))
+diff_days=$((diff_seconds / 86400))
+diff_hours=$(((diff_seconds % 86400) / 3600))
+diff_minutes=$(((diff_seconds % 3600) / 60))
+diff_secs=$((diff_seconds % 60))
+```
+
+**Display result:**
+```bash
+echo "Difference: ${diff_days}d ${diff_hours}h ${diff_minutes}m ${diff_secs}s"
+echo "Total: ${diff_seconds} seconds"
+```
+
+## Examples
+
+```bash
+# Days until deadline
+/datetime:calc
+→ First date/time: today
+→ Second date/time: 2024-12-15
+→ Difference: 32d 0h 0m 0s (32 days)
+→ Total: 2764800 seconds
+
+# Time since event
+/datetime:calc
+→ First date/time: 2024-11-01
+→ Second date/time: today
+→ Difference: 12d 0h 0m 0s (12 days)
+→ Total: 1036800 seconds
+
+# Hours between meetings
+/datetime:calc
+→ First date/time: today 14:00
+→ Second date/time: tomorrow 10:30
+→ Difference: 0d 20h 30m 0s
+→ Total: 73800 seconds
+
+# Working days remaining
+/datetime:calc
+→ First date/time: today
+→ Second date/time: next Friday
+→ Difference: 2d 0h 0m 0s (2 days)
+→ Total: 172800 seconds
+```
+
+## Common calculations
+
+**Academic deadlines:**
+- "today" to "2024-12-20" - Days until assignment due
+- "today" to "next Friday 23:59" - Time to weekly submission
+
+**Project milestones:**
+- "2024-11-13" to "2024-12-01" - Sprint duration
+- "last Monday" to "today" - Week progress
+
+**Event planning:**
+- "today" to "25 Dec" - Days until event
+- "9:00" to "17:00" - Meeting duration (same day)
+
+**Time tracking:**
+- "yesterday" to "today" - Daily intervals
+- "1 week ago" to "today" - Weekly reviews
+
+## When to use
+
+- Calculate days remaining until assignment deadlines
+- Track time elapsed on projects or sprints
+- Plan event schedules and milestones
+- Verify working time between meetings
+- Calculate age or duration of events
+- Estimate remaining time for deliverables
+- Academic semester/week planning
+
+## Related commands
+
+- `/datetime:now` - Get current date/time
+- `/datetime:parse` - Parse natural language date expressions
--- a/commands/now.md
+++ b/commands/now.md
@@ -0,0 +1,92 @@
+---
+description: Get current date and time (Claude should use date command directly)
+argument-hint: [format]
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+# now - Get current date and time
+
+Get the current date and time in a standardized format.
+
+## For Claude Code
+
+**If you are Claude**: DO NOT invoke this slash command. Use the `date` command directly via Bash tool:
+
+```bash
+date '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+See the Implementation section below for the exact command pattern.
+
+## For Users
+
+### Usage
+
+```bash
+/datetime:now
+/datetime:now [format]
+```
+
+## What it does
+
+1. **No arguments**: Returns current date/time in standard format
+   - Format: `YYYY-MM-DD HH:MM:SS (DayName)`
+   - Example: `2024-11-13 16:45:30 (Wednesday)`
+
+2. **With format argument**: Returns current date/time in custom format
+   - Uses `date` command format strings
+   - Example: `/datetime:now "%B %d, %Y"` → `November 13, 2024`
+
+## Implementation
+
+**Standard format:**
+```bash
+date '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+**Custom format:**
+```bash
+date '+[format-string]'
+```
+
+## Common format strings
+
+- `%Y-%m-%d` - Date only (2024-11-13)
+- `%H:%M:%S` - Time only (16:45:30)
+- `%A` - Full day name (Wednesday)
+- `%B %d, %Y` - Formatted date (November 13, 2024)
+- `%V` - Week number (45)
+- `+%s` - Unix timestamp (1699896330)
+
+## Examples
+
+```bash
+# Standard output
+/datetime:now
+→ 2024-11-13 16:45:30 (Wednesday)
+
+# Custom format - date only
+/datetime:now "%Y-%m-%d"
+→ 2024-11-13
+
+# Week number
+/datetime:now "%V"
+→ 45
+
+# Unix timestamp
+/datetime:now "+%s"
+→ 1699896330
+```
+
+## When to use
+
+- Verify current date/time before making temporal decisions
+- Get current week number for academic week mapping
+- Generate timestamps for logging or calculations
+- When <env> context date may be outdated
+
+## Related commands
+
+- `/datetime:parse` - Parse natural language date expressions
+- `/datetime:calc` - Calculate date differences
--- a/commands/parse.md
+++ b/commands/parse.md
@@ -0,0 +1,135 @@
+---
+description: Parse natural language date/time expressions (Claude should use date command directly)
+argument-hint: <expression> [format]
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+# parse - Parse natural language date/time expressions
+
+Parse natural language date and time expressions into standardized format.
+
+## For Claude Code
+
+**If you are Claude**: DO NOT invoke this slash command. Use the `date` command directly via Bash tool:
+
+```bash
+date -d "expression" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+See the Implementation section below for the exact command pattern.
+
+## For Users
+
+### Usage
+
+```bash
+/datetime:parse <expression>
+/datetime:parse <expression> [format]
+```
+
+## What it does
+
+1. **Standard format**: Parses natural language and returns standardized date/time
+   - Format: `YYYY-MM-DD HH:MM:SS (DayName)`
+   - Example: `/datetime:parse "tomorrow"` → `2025-11-14 00:00:00 (Friday)`
+
+2. **Custom format**: Parse and return in custom format
+   - Uses `date` command format strings
+   - Example: `/datetime:parse "next Monday" "%Y-%m-%d"` → `2025-11-17`
+
+## Implementation
+
+**Standard format:**
+```bash
+date -d "<expression>" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+**Custom format:**
+```bash
+date -d "<expression>" '+[format-string]'
+```
+
+**Important: "in" prefix handling**
+- User says: "in 3 days"
+- Command needs: `date -d "3 days"`
+- Strip "in" prefix before passing to `date -d`
+
+## Natural language expressions
+
+**Relative dates:**
+- `tomorrow`, `yesterday`
+- `3 days`, `2 weeks`, `1 month`, `6 months`
+- `next Monday`, `last Friday`
+- `next week`, `last month`
+
+**Specific dates:**
+- `Nov 13`, `November 13`, `13 Nov 2025`
+- `2025-11-13`, `13/11/2025`
+
+**Combined expressions:**
+- `tomorrow at 3pm` → `2025-11-14 15:00:00 (Friday)`
+- `next Monday at 14:30` → `2025-11-17 14:30:00 (Monday)`
+- `3 days at noon` → `2025-11-16 12:00:00 (Sunday)`
+
+**Week navigation:**
+- `monday`, `tuesday` (next occurrence)
+- `next monday`, `last tuesday`
+
+## Examples
+
+```bash
+# Tomorrow
+/datetime:parse "tomorrow"
+→ 2025-11-14 00:00:00 (Friday)
+
+# Relative days (strip "in" if present)
+/datetime:parse "3 days"
+→ 2025-11-16 00:00:00 (Sunday)
+
+# Next week day
+/datetime:parse "next Monday"
+→ 2025-11-17 00:00:00 (Monday)
+
+# With time
+/datetime:parse "tomorrow at 3pm"
+→ 2025-11-14 15:00:00 (Friday)
+
+# Specific date
+/datetime:parse "Nov 15"
+→ 2025-11-15 00:00:00 (Saturday)
+
+# Custom format - date only
+/datetime:parse "next week" "%Y-%m-%d"
+→ 2025-11-20
+
+# Unix timestamp for calculations
+/datetime:parse "3 days" "+%s"
+→ 1731715200
+```
+
+## Error handling
+
+If the expression is invalid, `date` will return an error:
+```bash
+date -d "invalid expression"
+→ date: invalid date 'invalid expression'
+```
+
+Common mistakes:
+- `in 3 days` → Remove "in", use `3 days`
+- `3d` → Use full words: `3 days`
+- `next week monday` → Use `next monday` or `monday next week`
+
+## When to use
+
+- ANY time user mentions dates, times, or temporal concepts
+- Converting user's natural language into concrete dates
+- Calculating deadlines from relative expressions
+- Validating date inputs before processing
+- Don't guess dates - always verify with this command
+
+## Related commands
+
+- `/datetime:now` - Get current date and time
+- `/datetime:calc` - Calculate date differences