Orbitmap Logo | Docs

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
Download as Markdown