Manage Taskboard

Use taskctl for every project, issue, and comment operation. Read references/cli.md before choosing a command or option.

Prerequisites

The local Taskboard service must be running. Default address is http://127.0.0.1:47823, override with the environment variable CODEX_TASKBOARD_URL. Start it from the Taskboard repo root with npm start (run npm install first if dependencies are missing). The SQLite database lives at .data/taskboard.sqlite. If taskctl reports the service unavailable (exit code 3), start the service before retrying.

Before first use: set <TASKCTL_CLI_PATH> in your project rules (absolute path to taskctl.mjs in the Taskboard repo). If you've linked it globally you can just call taskctl directly.

Workflow

1. Search for an existing issue before creating one. Use context current, then list the project issues and compare their identifiers, titles, descriptions, and status.
   • If an issue already tracks the same requirement, append the new requirement or acceptance detail to that issue without discarding its existing scope.
   • If the work depends on, blocks, is blocked by, or is closely related to another issue, add the matching issue relation.
   • Use a parent/sub-issue relation when one requirement is a contained part of a larger issue. A child has one parent; a parent may have many sub-issues.
   • Create a new issue only when no existing issue reasonably tracks the requirement.
   • Do not create, append, or relate a tiny or trivial request that does not benefit from durable tracking.
2. Before executing an issue, read the latest issue content and all comments. Treat comments as part of the current requirements, especially when completed work has been returned for changes.
   • In a description or comment, ![alt](/api/attachments/<id>/content) marks an inline image at that exact position in the text.
   • When understanding that image is necessary, use attachment download to save it locally, then inspect the saved file with an available image-viewing tool.
3. Create or update issues with the CLI; consume its JSON output. Issues created through taskctl are assigned to Codex Agent by default (a server-side actor record). Later CLI updates do not change the assignee.
4. Attribute every issue, relation, or comment mutation to the current Trae Work conversation by passing --thread-id ID explicitly. Trae Work does not set CODEX_THREAD_ID, so the explicit flag is required on every write command. Read commands do not require a thread id.
5. To claim a todo issue, move it to in_progress with --if-version from the latest read before starting implementation. If this claim reports a version conflict or a new read shows that its status changed, skip the issue and do not implement it.
6. Include --if-version <version> on every concurrent update, using the version returned by the latest read.
7. Before requesting review, verify the requested work and acceptance criteria.
8. After implementation and self-verification, add a comment summarizing the key changes, verification, result, and remaining risks; then move the issue to in_review. Never move it directly to done.
9. Move an issue from in_review to done only when the user explicitly confirms acceptance or explicitly asks to mark it complete. Self-verification alone is not sufficient.
10. Move work that cannot continue to blocked, and work that will not continue to canceled.

For version conflicts outside the initial claim, read the issue again, reconcile the newer state, and retry with its current version.