create-task

name	create-task
description	Use when creating an octomux task to dispatch autonomous Claude Code agents for building features, fixing bugs, or any code changes

Create an octomux task

Dispatch an autonomous Claude Code agent to work on a feature, bugfix, or code change via octomux.

Delegate the exploration — do NOT do it yourself. Do not read the repo's code, README, or git diffs to figure out how the work should be done — that is the worker's job. The worker explores the real code and owns the implementation. Your task description is a goal-oriented brief: the WHAT and WHY plus verifiable acceptance criteria, hard constraints, non-goals, and orientation pointers — never a step-by-step procedure ("edit file X, then Y"). Gather only the minimum needed to dispatch: the repo path, base branch, and (if given) ticket details. A step plan you write without reading the code is stale and constrains a capable worker. (See the goal-oriented brief shape in Step 5.)

Steps

1. Understand the goal:

   • Ask the user what they want built/fixed, or infer from context (e.g. a Linear/Jira ticket URL, a bug description, a feature request)
   • If given a ticket URL or key (e.g. BAC-843, PROJ-843), fetch the ticket details. Ticket keys match [A-Z][A-Z0-9]+-\d+. Decide tracker (Linear vs Jira) using the rules below.

   How to decide which tracker the key belongs to:

   • Full URL with linear.app/ → Linear.
   • Full URL with *.atlassian.net/ → Jira.
   • Bare key (e.g. BAC-123):
     • Call mcp__plugin_linear_linear__list_teams() and check whether the key prefix matches a Linear team's key → Linear.
     • Otherwise treat as Jira.
   • If ambiguous (both could match), prefer defaultTracker from ~/.octomux/settings.json.
   • The configured trackers and their defaults are the source of truth — run octomux list-integrations --json to see enabled Jira/Linear integrations with their base_url, default_project, and default_team_key (secrets are masked).

   Fetching Linear issue details:

   1. Extract the issue key (e.g. BAC-843).
   2. Use Linear MCP tools:
      • mcp__plugin_linear_linear__get_issue({ query: '<issue-key>' }) to fetch title, description, state, labels, priority, team, project.
   3. Map fields to the prompt template:
      • title → task title + What section
      • description → Context section (extract acceptance criteria if present)
      • labels[].name / priority → urgency hints in Why section
      • team.key + team.id + project.id + id (issue UUID) → ref metadata (Step 6a below)
      • state → ignored (octomux owns workflow state)
   4. Branch naming uses the same convention: feat/BAC-123-add-position-sync.

   Fetching Jira ticket details:

   1. Extract the ticket key from the URL (e.g., PROJ-843 from https://your-company.atlassian.net/browse/PROJ-843)
   2. Use Atlassian MCP tools:
      • getAccessibleAtlassianResources() to get cloudId
      • getJiraIssue(cloudId, issueKey, fields=["summary","description","priority","labels","status"]) to get ticket details
   3. Map fields to the prompt template:
      • summary -> title + What section
      • description -> Context section (extract acceptance criteria if embedded)
      • priority / labels -> inform urgency in Why section
   4. If the description contains acceptance criteria (bullet lists, checkboxes), extract them verbatim for the Acceptance Criteria section

   For the default base URL / project key / team key when inferring a URL or assuming a project/team, read the enabled integration's config via octomux list-integrations --json (base_url / default_project for Jira, default_team_key for Linear). Fall back to the legacy defaultJiraBaseUrl / defaultJiraProjectKey / defaultLinearTeamKey keys in ~/.octomux/settings.json only when no matching integration is configured.

2. Resolve the repo:

   • Query recent repos via CLI:

     octomux recent-repos
     

   • If the repo is ambiguous, ask the user

3. Detect base branch:

   octomux default-branch --repo-path <resolved_path>
   

4. Generate the branch name: Follow GitHub/conventional branch naming best practices. The branch name doubles as the worktree directory name.

   Format: <type>/<scope> where:

   • <type> = feat, fix, chore, refactor, docs, test, perf (match the nature of the work)
   • <scope> = kebab-case short description (max ~40 chars, no task ID suffix)

   From a Jira ticket (e.g. PROJ-123 — substitute your project key):

   feat/PROJ-123-add-position-sync
   fix/PROJ-456-decimal-exponent-bloat
   

   From a GitHub issue (e.g. #42):

   feat/42-websocket-real-time-updates
   fix/42-terminal-resize-bug
   

   Without a ticket/issue:

   fix/tmux-session-leak
   feat/cli-arg-parsing
   chore/cleanup-packaging
   refactor/split-task-runner
   perf/optimize-ui-rendering
   

   Pass it via --branch:

   --branch 'fix/tmux-session-leak'
   

5. Craft the initial prompt (a goal-oriented brief — WHAT/WHY, not HOW): Write the brief about outcomes and boundaries, not procedure. Use this shape:

   • Goal — 1–2 sentences: the outcome/capability that should exist when done.
   • Why / Context — intent and how it fits, so the worker makes sound tradeoffs.
   • Acceptance criteria — VERIFIABLE: passing tests / build+lint green / concrete example cases / an end-to-end check that proves it works; state the evidence to show.
   • Hard constraints — non-negotiables (don't break API X, no new deps, follow CLAUDE.md).
   • Non-goals — explicitly what NOT to touch (prevents scope-creep).
   • Pointers — orientation only ("follow the pattern in src/auth/") — NEVER a step list.
   • Standard instructions: Run tests before finishing. Follow conventional commits. Keep changes minimal and focused.

   Put your precision into the acceptance criteria, not into steps. Do NOT enumerate implementation steps or files-to-edit — the worker reads the code and decides that. A vague brief is bad, but so is a prescriptive one; be specific about the goal and boundaries, silent about the procedure.

   Always append this to the end of the prompt:

   When finished, output a structured summary:
   ## Done
   - **Changes:** <file count> files changed
   - **Tests:** <pass/fail summary>
   - **Commits:** <commit messages>
   

6. Create the task:

   octomux create-task \
     --title '<title>' \
     --description '<description>' \
     --repo-path '<resolved_path>' \
     --branch '<branch_name>' \
     --base-branch '<detected_branch>' \
     --initial-prompt '<crafted_prompt>'
   

6a. Link the source ticket (if applicable):

If the source was a Linear issue, immediately link it with the cached metadata so the status-sync handler doesn't need to refetch the team on every column change:

octomux task-ref-add <task-id> linear BAC-843 \
  --url 'https://linear.app/ostium-labs/issue/BAC-843' \
  --metadata '{"team_key":"BAC","team_id":"<uuid>","issue_id":"<uuid>","project_id":null}'

team_id, issue_id, and project_id come from the get_issue response. The handler falls back to a runtime lookup if metadata is missing, but caching is faster and rate-limit-friendly.

If the source was a Jira issue, link it without metadata:

octomux task-ref-add <task-id> jira PROJ-843 \
  --url 'https://your-company.atlassian.net/browse/PROJ-843'

7. Report:
   • Print the task ID returned by the CLI
   • Tell the user to monitor via octomux list-tasks or the dashboard
   • Or via CLI: octomux list-tasks

Forking an existing task

Use --fork-from <task-id> to start a new task from the branch of an existing task. The new task gets its own worktree and its own branch; the source task is left untouched.

octomux create-task \
  --fork-from ABC123XYZ \
  --title 'Try a different approach' \
  --description 'Explore alternative implementation on top of ABC123XYZ' \
  --branch 'feat/try-alt-approach' \
  --initial-prompt 'Continue from the current state. Consider a simpler approach to ...'

What it does:

• Sets --base-branch to agents/<task-id> — you MUST NOT pass --base-branch yourself (the two flags are mutually exclusive and the CLI will error).
• Inherits --repo-path from the source task if you don't pass one.
• All other flags (--title, --description, --branch, --initial-prompt, etc.) behave exactly as usual.

Dirty source warning:

If the source task's worktree has uncommitted changes, the CLI prints a warning to stderr like:

Warning: Source task ABC123XYZ has uncommitted changes; fork starts from last commit 1a2b3c4. Those changes will not be in the fork.

The fork proceeds anyway — but expect to re-apply any uncommitted work manually if you need it in the fork. If you want those changes in the fork, commit them in the source first.

Refusal cases (the CLI exits non-zero):

• Source task does not exist.
• Source's status is draft (task was never started, so there's no branch yet).
• Source's run_mode is scratch or none (task runs in the repo directory with no branch to fork from).
• Both --fork-from and --base-branch are passed (mutually exclusive).

Notes

• The octomux server must be running (start with octomux start)
• Tasks start immediately by default — agents begin working right away
• Each task gets its own git worktree and tmux session for isolation
• Keep titles short (under 60 chars) and descriptive
• Initial prompts should be specific and actionable
• Monitor tasks via octomux list-tasks or the dashboard
• To create PRs for completed tasks, use the create-pr skill