# Working with Tasks

Tasks are the core unit of work in Orbitmap. Each task has a title, description, status, optional agent instructions, and a log of all work performed.

## Creating Tasks

Create tasks from the Orbitmap web UI or directly via your agent.

**Via agent:**

```terminal
~/my-project

❯ HAL, create a task: "Add password reset
  flow with email verification"

HAL: Creating task...
✓ create_task()

Task created:
TS-k2so77 - Add password reset flow with
email verification
Status: todo

Want me to start working on it now?
```

**Via web UI:** Navigate to your project → Tasks → click "New Task". Fill in the title, description, and optionally assign it to an agent and add agent instructions.

**Agent instructions** are special - they're read by your AI agent before starting work on the task. Use them to specify implementation details, constraints, or references the agent should follow.

## Executing Tasks

The agent workflow for executing tasks follows a structured lifecycle:

1. **Check for in-progress work** - the agent looks for tasks already started
2. **Start a task** - picks the first `todo` task, reads its context, sets status to `in_progress`
3. **Do the work** - implements code, reads docs, makes decisions
4. **Log everything** - records code changes, decisions, blockers
5. **Finish** - sets status to `in_review` (default) or `done`

**Starting a task:**

```terminal
~/my-project

❯ run task TS-r2d2, HAL

HAL: Starting task TS-r2d2...
✓ start_task(task_id='TS-r2d2')

Task: Set up authentication flow
Description: Implement login/register using
Supabase Auth with email+password.

Agent instructions:
- Use the SupabaseAuth middleware pattern
- Follow the existing Items module as
  reference for controller structure
- Include Form Request validation

Reading project docs for auth context...
✓ get_document(id='doc-auth-spec')

Starting implementation...
```

**Picking the next available task automatically:**

```terminal
~/my-project

❯ what's my next task, HAL?
  Pick it up and start working.

HAL: Checking your queue...
✓ get_tasks(status='in_progress') → empty
✓ start_task()

Started: TS-c3po42 - Add user profile page
Reading task context and logs...
```

## Reviewing and Closing Tasks

When the agent finishes work, it logs a summary and sets the status:

```terminal
~/my-project

❯ make a commit and close this task, HAL

HAL: Committing changes...
✓ git add app/Http/Controllers/...
✓ git commit -m "[TS-c3po42] Add user
  profile page with avatar upload"

Logging work summary...
✓ log_work(task_id, type='code_change',
  content='Added ProfileController,
  profile Livewire component, avatar
  upload with S3 storage')

Setting task to review...
✓ update_task_status(task_id, 'in_review',
  delivery_status='on_branch')

Task TS-c3po42 is ready for review.
Branch: feature/user-profile
```

**Task statuses:**

| Status | Meaning |
|--------|---------|
| `backlog` | Planned but not prioritized |
| `todo` | Ready to be picked up |
| `in_progress` | Currently being worked on |
| `in_review` | Work complete, awaiting human verification |
| `review_changes` | Reviewer requested changes |
| `done` | Verified and closed |
| `blocked` | Cannot proceed - external dependency |

## Checking Your Backlog

```terminal
~/my-project

❯ what do I have to do, HAL?

HAL: Checking your task queue...
✓ get_tasks(status='todo,in_progress')

In Progress:
• TS-r2d2x1 - Set up authentication flow

Todo:
• TS-c3po42 - Add user profile page
• TS-walle3 - Write API documentation

❯ check the backlog too, HAL

✓ get_tasks(status='backlog')

Backlog (5 tasks):
• TS-neo001 - Dark mode support
• TS-neo002 - Export to CSV
• TS-neo003 - Email notification prefs
• TS-neo004 - Admin dashboard widgets
• TS-neo005 - Mobile responsive fixes
```