test-repo/skills/gantt-tasks/SKILL.md

---
name: gantt-tasks
description: Full CRUD operations for Gantt Board tasks including comments, attachments, and sprint management. Uses Gantt Board API with machine token authentication.
---

# gantt-tasks

**Module Skill** - Complete task management for Gantt Board via API.

## Purpose

Provides all operations needed to work with Gantt Board tasks: create, read, update, delete, comments, attachments, and sprint queries. Used by orchestrator skills and agents.

## Authentication

Uses **machine token** for server-to-server API calls:

```bash
export GANTT_MACHINE_TOKEN="50cd5e8fe3f895353f97c9ee64052c0b689b4eedf79259746413734d0a163cf8"
export GANTT_API_URL="https://gantt-board.vercel.app/api"
```

**Architecture:** Skills → API (with machine token) → Database

This follows the API-centric pattern where all business logic lives in API routes.

## Usage

```bash
source ~/.agents/skills/gantt-tasks/lib/tasks.sh

# Create task
TASK_ID=$(task_create --title "Fix bug" --project "Gantt Board" --sprint current)

# Add comment
task_add_comment "$TASK_ID" "Starting work on this"

# Attach file
task_attach_file "$TASK_ID" "/path/to/file.md"
```

## Functions

### Task CRUD

#### `task_create([options])`

Create a new task.

**Options:**
- `--title` - Task title (required)
- `--description` - Task description (optional)
- `--type` - Task type: feature, bug, research, task (default: task)
- `--status` - Status: open, todo, in-progress, review, done (default: open)
- `--priority` - Priority: low, medium, high, critical (default: medium)
- `--project` - Project name or ID (optional, auto-detects "current")
- `--sprint` - Sprint name or ID, or "current" for current sprint (optional)
- `--assignee` - Assignee name or ID (default: Max)
- `--due-date` - Due date YYYY-MM-DD (optional)
- `--tags` - Tags as comma-separated string (optional)

**Returns:** Task ID on success

**Example:**
```bash
TASK_ID=$(task_create \
    --title "Research API options" \
    --description "Compare REST vs GraphQL" \
    --type research \
    --priority high \
    --sprint current \
    --tags "api,research")
```

#### `task_get(TASK_ID)`

Get full task details including comments.

**Parameters:**
- `TASK_ID` - Task UUID

**Returns:** Task JSON

**Example:**
```bash
task=$(task_get "a1b2c3d4-...")
echo "$task" | jq -r '.title'
```

#### `task_update(TASK_ID, [options])`

Update task fields.

**Parameters:**
- `TASK_ID` - Task UUID
- Options same as task_create (except project/sprint usually fixed)

**Example:**
```bash
task_update "$TASK_ID" --status in-progress --priority critical
```

#### `task_delete(TASK_ID)`

Delete a task (permanent).

**Example:**
```bash
task_delete "$TASK_ID"
```

#### `task_list([filters])`

List tasks with optional filters.

**Filters:**
- `--status` - Filter by status (comma-separated: open,todo,in-progress)
- `--project` - Filter by project name/ID
- `--sprint` - Filter by sprint name/ID or "current"
- `--assignee` - Filter by assignee
- `--priority` - Filter by priority
- `--json` - Output as JSON

**Example:**
```bash
# List current sprint tasks
task_list --sprint current --status open,todo,in-progress

# List my high priority tasks
task_list --assignee Max --priority high
```

### Comments

#### `task_add_comment(TASK_ID, TEXT, [OPTIONS])`

Add a comment to a task.

**Parameters:**
- `TASK_ID` - Task UUID
- `TEXT` - Comment text (supports markdown)
- `--checklist` - Include checklist format automatically
- `--status` - Add status prefix (in-progress, review, etc.)

**Example:**
```bash
# Simple comment
task_add_comment "$TASK_ID" "Found the issue in line 42"

# Checklist comment with status
task_add_comment "$TASK_ID" \
    "Fixed the bug\n\nNow testing..." \
    --checklist \
    --status in-progress
```

#### `task_update_comment(TASK_ID, COMMENT_ID, TEXT)`

Update an existing comment (for progress tracking).

**Parameters:**
- `TASK_ID` - Task UUID
- `COMMENT_ID` - Comment UUID to update
- `TEXT` - New comment text

**Example:**
```bash
# Update progress comment
COMMENT_ID=$(echo "$TASK" | jq -r '.comments[-1].id')

task_update_comment "$TASK_ID" "$COMMENT_ID" \
    "## $(date +%Y-%m-%d) 🔄 In Progress\n\n### ✅ Completed\n- [x] Phase 1\n\n### 🔄 In Progress\n- [ ] Phase 2"
```

**Auto-format:**
If `--checklist` is passed, formats as:
```markdown
## [YYYY-MM-DD HH:MM] 🔄 [STATUS]

### ✅ Completed
- [x] Previous item

### 🔄 In Progress
- [x] Current item: [TEXT]

### 📋 Remaining
- [ ] Next step

### 📊 Progress: X/Y tasks complete
```

#### `task_reply_to_comment(TASK_ID, COMMENT_ID, TEXT)`

Reply to an existing comment.

**Example:**
```bash
task_reply_to_comment "$TASK_ID" "$COMMENT_ID" "Great point! I'll check that."
```

### Attachments

#### `task_attach_file(TASK_ID, FILE_PATH, [OPTIONS])`

Attach a file to a task.

**Parameters:**
- `TASK_ID` - Task UUID
- `FILE_PATH` - Path to file
- `--description` - Attachment description (optional)

**Example:**
```bash
# Attach markdown file
task_attach_file "$TASK_ID" "/tmp/plan.md" --description "Implementation plan"

# Attach any file type
task_attach_file "$TASK_ID" "/tmp/screenshot.png"
```

**Note:** Large files should be stored elsewhere and linked.

### Sprint Management

#### `sprint_get_current()`

Get the current sprint (contains today's date).

**Returns:** Sprint ID

**Example:**
```bash
SPRINT_ID=$(sprint_get_current)
echo "Current sprint: $SPRINT_ID"
```

#### `sprint_list([OPTIONS])`

List all sprints.

**Options:**
- `--active` - Only active sprints
- `--project` - Filter by project

**Example:**
```bash
sprint_list --active
```

### Project Resolution

#### `resolve_project_id(PROJECT_NAME)`

Convert project name to ID.

**Example:**
```bash
PROJECT_ID=$(resolve_project_id "Gantt Board")
```

#### `resolve_user_id(USER_NAME)`

Convert user name to ID.

**Example:**
```bash
USER_ID=$(resolve_user_id "Max")
```

## File Structure

```
~/.agents/skills/gantt-tasks/
├── SKILL.md              # This documentation
└── lib/
    └── tasks.sh          # All task functions
```

## Integration Example

Complete workflow:

```bash
# Set authentication
export GANTT_MACHINE_TOKEN="50cd5e8fe3f895353f97c9ee64052c0b689b4eedf79259746413734d0a163cf8"
export GANTT_API_URL="https://gantt-board.vercel.app/api"

source ~/.agents/skills/gantt-tasks/lib/tasks.sh

# 1. Create task
TASK_ID=$(task_create \
    --title "Research URL extraction options" \
    --type research \
    --priority high \
    --sprint current)

echo "Created task: $TASK_ID"

# 2. Add initial comment
task_add_comment "$TASK_ID" "Starting research phase" --checklist

# 3. Update with progress
task_update "$TASK_ID" --status in-progress
task_add_comment "$TASK_ID" "Evaluated 3 options:\n1. Scrapling\n2. Tavily\n3. web_fetch" \
    --checklist \
    --status in-progress

# 4. Attach recommendation
cat > /tmp/recommendation.md << 'EOF'
## Recommendation

Use Scrapling as primary, Tavily as fallback.

- Scrapling handles JavaScript sites
- Tavily fast for articles
- web_fetch for simple sites
EOF

task_attach_file "$TASK_ID" /tmp/recommendation.md --description "Research findings"

# 5. Mark ready for review
task_update "$TASK_ID" --status review
task_add_comment "$TASK_ID" "Research complete. Recommendation attached." \
    --checklist

echo "Task ready for review: https://gantt-board.vercel.app/tasks/$TASK_ID"
```

## CLI Alternative

For interactive/command-line use, use the Gantt Board CLI:

```bash
# Set auth for CLI
export GANTT_MACHINE_TOKEN="50cd5e8fe3f895353f97c9ee64052c0b689b4eedf79259746413734d0a163cf8"
export API_URL="https://gantt-board.vercel.app/api"

cd /Users/mattbruce/Documents/Projects/OpenClaw/Web/gantt-board

# Create task
./scripts/gantt.sh task create "Title" --type research --sprint current

# List tasks
./scripts/gantt.sh task list --sprint current --status in-progress

# Get task
./scripts/gantt.sh task get $TASK_ID

# Update task
./scripts/gantt.sh task update $TASK_ID --status review
```

**Note:** The skill library and CLI both use the same API endpoints with machine token authentication.

---

**Note:** This is a low-level module skill. Used by orchestrator skills, not directly by users.