gantt-board/scripts/README.md

# Gantt Board CLI

A comprehensive command-line interface for managing tasks, projects, and sprints in the Gantt Board system.

## Scripts

- `task.sh` - Full CRUD operations for tasks
- `project.sh` - Project management
- `sprint.sh` - Sprint management

## Installation

1. Make scripts executable:
```bash
chmod +x task.sh project.sh sprint.sh
```

2. Ensure dependencies are installed:
```bash
brew install jq
```

## Configuration

Scripts use the following defaults:
- **Supabase URL**: `https://qnatchrjlpehiijwtreh.supabase.co`
- **Default Project**: OpenClaw iOS
- **Default Assignee**: Max

## Task Management (`task.sh`)

### Create Task

```bash
# Minimal task
./task.sh create --title "Fix bug"

# Full task with all fields
./task.sh create \
  --title "Implement OAuth" \
  --description "Add OAuth2 login support" \
  --type task \
  --status todo \
  --priority high \
  --project "Gantt Board" \
  --sprint "current" \
  --assignee "Max" \
  --due-date "2026-03-01" \
  --tags "auth,security" \
  --comments "Starting implementation"

# Create from JSON file
./task.sh create --file task.json

# Interactive mode
./task.sh create --interactive

# Auto-create project if not found
./task.sh create --title "New Feature" --project "New Project" --auto-create
```

### List Tasks

```bash
# List all tasks
./task.sh list

# Filter by status
./task.sh list --status todo

# Filter by priority
./task.sh list --priority high

# Filter by project (auto-resolves name)
./task.sh list --project "Gantt Board"

# Filter by assignee
./task.sh list --assignee "Max"

# Filter by type
./task.sh list --type bug

# JSON output
./task.sh list --json

# Limit results
./task.sh list --limit 10
```

### Get Task

```bash
./task.sh get <task-id>
```

### Update Task

```bash
# Update status
./task.sh update <task-id> --status in-progress

# Update multiple fields
./task.sh update <task-id> \
  --status done \
  --priority low \
  --add-comment "Task completed"

# Update assignee
./task.sh update <task-id> --assignee "Matt"

# Clear tags
./task.sh update <task-id> --clear-tags

# Update tags
./task.sh update <task-id> --tags "new-tag,another-tag"
```

### Delete Task

```bash
./task.sh delete <task-id>
```

### Bulk Create

```bash
# From JSON file
./task.sh bulk-create tasks.json

# With auto-create for projects
./task.sh bulk-create tasks.json --auto-create
```

**JSON Format:**
```json
[
  {
    "title": "Task 1",
    "description": "Description",
    "type": "task",
    "status": "todo",
    "priority": "high",
    "project": "Project Name",
    "sprint": "Sprint 1",
    "assignee": "Max",
    "due_date": "2026-03-01",
    "tags": "tag1,tag2",
    "comments": "Initial comment"
  }
]
```

## Project Management (`project.sh`)

### Create Project

```bash
./project.sh create --name "New Project" --description "Project description" --color "#3b82f6"
```

### List Projects

```bash
# List all projects
./project.sh list

# JSON output
./project.sh list --json
```

### Get Project

```bash
# By ID
./project.sh get <project-id>

# By name (auto-resolves)
./project.sh get "Gantt Board"
```

### Update Project

```bash
./project.sh update <project-id-or-name> \
  --name "Updated Name" \
  --description "Updated description" \
  --color "#ff0000"
```

### Delete Project

```bash
./project.sh delete <project-id-or-name>
```

## Sprint Management (`sprint.sh`)

### Create Sprint

```bash
./sprint.sh create \
  --name "Sprint 3" \
  --project "Gantt Board" \
  --goal "Complete API integration" \
  --start-date "2026-02-24" \
  --end-date "2026-03-07"
```

### List Sprints

```bash
# List all sprints
./sprint.sh list

# List active sprints
./sprint.sh list --active

# Filter by project
./sprint.sh list --project "Gantt Board"

# JSON output
./sprint.sh list --json
```

### Get Sprint

```bash
# By ID
./sprint.sh get <sprint-id>

# By name
./sprint.sh get "Sprint 1"
```

### Update Sprint

```bash
./sprint.sh update <sprint-id-or-name> \
  --name "Updated Sprint" \
  --goal "Updated goal" \
  --status active \
  --start-date "2026-02-25" \
  --end-date "2026-03-10"
```

### Close Sprint

```bash
./sprint.sh close <sprint-id-or-name>
```

### Delete Sprint

```bash
./sprint.sh delete <sprint-id-or-name>
```

## Name Resolution

All scripts support automatic name-to-ID resolution:

- **Projects**: "Gantt Board" → `68d05855-a399-44a4-9c36-3ee78257c2c9`
- **Sprints**: "Sprint 1" → `b2c3d4e5-0001-0000-0000-000000000001`
- **Assignees**: 
  - "Max" → `9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa`
  - "Matt" → `0a3e400c-3932-48ae-9b65-f3f9c6f26fe9`
- **Special**: Use "current" for the most recent active sprint

## Task Types

- `task` - Standard task
- `bug` - Bug fix
- `research` - Research spike
- `plan` - Planning task
- `idea` - Idea/backlog item

## Task Statuses

- `open` - Newly created
- `todo` - Ready to start
- `blocked` - Blocked
- `in-progress` - Currently working
- `review` - Ready for review
- `validate` - Needs validation
- `done` - Completed

## Priorities

- `low`
- `medium`
- `high`
- `urgent`

## Examples

### Daily Workflow

```bash
# Create a new task
./task.sh create --title "Fix login bug" --type bug --priority urgent --project "Gantt Board"

# List my high priority tasks
./task.sh list --assignee "Max" --priority high

# Update task status
./task.sh update <task-id> --status in-progress

# Add progress comment
./task.sh update <task-id> --add-comment "Working on reproduction steps"

# Mark as done
./task.sh update <task-id> --status done --add-comment "Fixed in commit abc123"
```

### Sprint Planning

```bash
# Create new sprint
./sprint.sh create --name "Sprint 5" --project "Gantt Board" --start-date 2026-03-01 --end-date 2026-03-14

# Create multiple tasks for the sprint
./task.sh bulk-create sprint-tasks.json

# Close previous sprint
./sprint.sh close "Sprint 4"
```

### Project Setup

```bash
# Create new project
./project.sh create --name "Mobile App" --description "iOS and Android app" --color "#8b5cf6"

# Create initial sprint
./sprint.sh create --name "Sprint 1" --project "Mobile App" --goal "MVP release"

# Create starter tasks
./task.sh create --title "Setup repo" --project "Mobile App" --sprint "Sprint 1"
./task.sh create --title "Design system" --project "Mobile App" --sprint "Sprint 1"
```

## Exit Codes

- `0` - Success
- `1` - Error (invalid input, API failure, not found)

## Environment Variables

Scripts use hardcoded configuration at the top of each file. To customize, edit:
- `SUPABASE_URL` - Supabase instance URL
- `SERVICE_KEY` - Supabase service role key
- `DEFAULT_PROJECT_ID` - Default project for tasks
- `DEFAULT_ASSIGNEE_ID` - Default assignee for tasks
- `MATT_ID` - Matt's user ID

## Troubleshooting

### "Project not found"
- Use `--auto-create` flag to create project automatically
- Check project name spelling
- Use `./project.sh list` to see available projects

### "Sprint not found"
- Use "current" to reference the most recent active sprint
- Check sprint name with `./sprint.sh list`

### "jq parse error"
- Ensure `jq` is installed: `brew install jq`
- Check JSON file syntax

### Empty response on create
- This is normal - Supabase returns empty on successful POST
- Check list command to verify creation: `./task.sh list --limit 5`

## License

Part of the OpenClaw Gantt Board project.