Manage Taskboard

Manage Taskboard

Use taskctl for every project, issue, relation, and comment operation. Consume its JSON output. Use the exact issue identifier returned by the taskboard or supplied in the prompt. Never assume, derive, or rewrite an identifier prefix.

Open only the relevant section of references/cli.md when command syntax is needed.

Select the CLI and active service

• Use the exact taskctl binary and Taskboard URL supplied by the task or injected runtime. Do not replace them with a global CLI, the default port, or another board.
• On macOS, when no binary is injected and the desktop app is installed, use '/Applications/Codex Taskboard.app/Contents/Resources/bin/taskctl' issue get ID --json. Keep the single quotes because the path contains a space. The packaged wrapper reads the active launcher runtime; do not search the filesystem for another CLI or reconstruct the tokenized URL.
• On Linux, when no binary is injected and Codex was started by the desktop app, use taskctl issue get ID --json. The desktop app adds its packaged wrapper to the managed Codex PATH; do not search the filesystem for another CLI or reconstruct the tokenized URL.
• If that exact command reaches a sandbox restriction on the loopback service, retry the same command with the required permission. Do not switch binaries or endpoints.

Terminology: local companion

In this product, companion means the device-local loopback service used for cloud mode (Codex/Git/Skill/MCP, path mapping, Basic Auth proxy). Related names: local companion, loopback companion, CODEX_TASKBOARD_COMPANION_URL, cloud-companion.json, LOCAL_COMPANION_REQUIRED.

When writing Chinese, keep the English word or use 本地 companion / 本地配套服务 / 环回代理. Never translate as 伴侣 or invent 伴侣 API. Ordinary task/comment/attachment HTTP routes (/api/tasks, /api/comments, /api/attachments, …) are the Taskboard HTTP API (or local server API)—not “companion API”.

Core workflow

1. For an existing issue, first run issue get and comment list. Also run attachment list --task. On the first handoff, omit --after and read the full results. Keep the separate nextCursor from each list. When the same task resumes, run issue get again, then pass each saved cursor to its matching list with --after so only new or modified entries are returned. Comment lists include the attachments on returned comments; use attachment list --comment with its own cursor when a known comment attachment list can grow. Read the description and latest comments before deciding whether to start. Treat comments as current requirements, including returned work. If they say to wait, not execute, or not start now, stop and report without changing the status.
2. Treat backlog as not approved for execution. Unless the user explicitly authorizes that issue, do not claim it, move it to another status, or perform task work; its assignee alone is not authorization. If work may start, claim it before reading code, downloading attachments, analyzing the implementation, or doing any other task work. Move a claimable todo to in_progress with its current version; do not continue until the move succeeds. If it is already in_progress, continue only when it is bound to the current conversation. Never move an issue claimed by another conversation.
3. If the move conflicts because the version is stale, run issue get and comment list again. Retry once with the latest version only when the issue is still a claimable todo, is not bound to another conversation, is not archived, and its description and latest comments are unchanged. If it was claimed, its status or requirements changed, it is archived, the service is unavailable, a permanent API error occurs, or the retry fails, stop and report. Never loop or take over another agent's claim.
4. For a new durable requirement, run context current. Treat its project as a workspace match only when project.workspacePath is the current directory or one of its ancestors. An unmatched local project is the documented fallback, not proof that the requirement belongs in the global project. If the user named a target project or the working directory identifies one, run project list, select that exact project by id or name, and stop to ask if the result is ambiguous. Search existing project issues before creating one in that confirmed project, then pass its explicit id to issue create. Update a matching issue instead of creating a duplicate. Use the fallback only when the user explicitly wants the global project. Do not track trivial requests.
5. Execute only the requested work in the issue's branch or worktree when one is bound.
6. Verify the requested operation path. Add a comment with the changes, verification result, outcome, and remaining risks. Read the issue again, then move it to in_review with its current version.
7. Move an issue to done only after the user explicitly accepts it or asks to complete it. Use blocked when work cannot continue and canceled when it will not continue.

Other operations

• Run taskctl project readme get [PROJECT_ID] to inspect project architecture, constraints, and conventions before planning or executing complex tasks.
• Keep the project README focused on root overview and conventions; store detailed multi-page documentation in the local repository's docs/ folder.
• Preserve existing issue scope when adding requirements or acceptance details.
• Add only relations that the work requires. Use parent for contained work, blocks or blocked_by for dependencies, and related for close association.
• Let taskctl read CODEX_THREAD_ID for controller attribution. Outside Codex, pass the exact conversation ID with --thread-id. This value alone is not a complete task binding.
• Any issue that the current conversation claims or continues must store a complete threadBinding: threadId, codexProjectId, codexProjectKind, codexHostId, and workspacePath. For an unbound local issue launched with injected Taskboard context, use the current CODEX_THREAD_ID, the injected project id and workspace path, local project kind, and local host id. Pass all five explicit --binding-* options on the claim and every later issue move that retains ownership. If any identity field is unavailable, stop before moving the issue to in_progress; never create a legacy binding containing only threadId.
• When an issue already has a complete threadBinding, preserve its exact five saved values on every status write. Do not rebuild or replace it from the current context, and never take over a binding owned by another conversation.
• Use the latest returned version with --if-version for concurrent updates. On conflict, read the issue again and reconcile before retrying.
• Download and inspect an inline ![alt](api/attachments/<id>/content) image only when it is needed to understand the requirement.