t1k-cocos-rushtank-task-conventions

Task Conventions (Tool-Agnostic)

SSOT for HOW a task is written — naming, description, effort, scheduling, subtask shape. Tool-neutral: nothing here names a storage tool. The mechanics of writing to a tool live in .claude/task-config.json → providers.<active>; the policy (state machine, dependency, ready-query, guarded-write) lives in rules/t1k-cocos-rushtank-task-management.md. Applies to tasks created by agent/tool and manually by a human.

1. Naming format

[ACTION-DOMAIN] Short task name

Prefix fully UPPERCASE, wrapped in [ ], exactly the form [ACTION-DOMAIN].
No fixed prefix list — pick the action + domain that fit the task.
The prefix must reflect the main action and the primary scope. Actor prefixes ([DEV], [AI], [PROGRAMMER]) are ❌ — actors, not actions or scopes. A scope-only [GAMEPLAY] is ❌ — missing action. [FIX-GAMEPLAY], [UPDATE-MAP], [VERIFY-QA] = ✅.

2. Action

Pick exactly one main action (this set is authoritative — do not invent new ones):

ADD — add a new feature, file, or asset
UPDATE — update, adjust, or modify
FIX — fix a bug
DELETE / REMOVE — delete or remove
REFACTOR — restructure code
OPTIMIZE / PERF — optimize performance
VERIFY / TEST — verify or confirm
IMPLEMENT — implement a design/spec

3. Domain (scope)

Domain is not a key from a fixed list — it is inferred from the task content to identify the most appropriate primary scope. Ask: which system does this task affect most? under which topic would someone look for it? — not “which domain in the list fits?”

A task spanning multiple domains takes the most impacted / primary one. Never combine two domains into one prefix.
Domain is a single short UPPERCASE word reflecting the technical/business scope.

4. Task name

Short and concise — not a sentence.
No detailed description in the name; details belong in the description field.
Classification is carried by the prefix, never by the tool’s native tag/label feature (§7).

5. Description

If a Game Design (GD) doc or any spec is available, analyze and synthesize the relevant parts into the description. Include:

Objective — what needs to be done and why.
Scope — which systems/modules are affected.
Requirements — criteria to meet (from GD/spec).
Reference — path/file/section in the source document, if any.

Rules:

Do not copy-paste raw GD text. Synthesize; drop irrelevant parts.
No GD/spec available ⇒ still write a short description from the task name + context.
Markdown, concise, readable. Never leave the description empty when information exists.
Never include absolute user paths — no C:\Users\…, /home/…, or personal download folders.
Reference paths must be project-relative — e.g. Client/assets/script/utils/iap/IAPCrypto.js. Exact path unknown ⇒ describe the location conceptually.
Never reference a plan/spec file that is not pushed to git (personal plan files, downloaded specs). Extract the relevant content and write it directly into the description instead.

6. Effort estimates & scheduling

Effort must match the plan timeline (M (6h), S (2h), L (10h)). Do not default every task to 8 hours.
A task over 8 hours is split into subtasks so each part is ≤ 8h (10h → 6h + 4h).
Schedule dates from actual effort, packing each work day toward ~8h; combine small tasks on the same day when possible. Respect weekends and non-working days.
Effort/due reach the tool via the provider’s create operation ($EFFORT / $DUE); a provider lacking the field just omits it — sizing/splitting still applies.

7. Subtask

[AB] [ACTION-DOMAIN] Subtask content

[AB] = the first letter of each component of the parent prefix, e.g. [UPDATE-GAMEPLAY] → [UG].

Rules:

Must start with the parent prefix abbreviation, then the subtask’s own [ACTION-DOMAIN].
Exactly one space between [AB] and [ACTION-DOMAIN].
Subtask names are short, like parent names. All prefixes inferred from context.

Tree depth & effort ceiling

The tree is EXACTLY two levels: parent → subtask. A subtask MUST NOT have subtasks. No third level, ever — even when the tool allows arbitrary nesting.
Every subtask ≤ 8h. An over-8h subtask becomes two sibling subtasks, never a nested level.
A parent has no effort ceiling — its effort is the sum of its subtasks. A 39h parent with eight ≤8h subtasks is correct.
A parent whose own effort is ≤ 8h may stand alone without subtasks.
Split along a real seam (a distinct deliverable, file group, or verification target), not by cutting hours arbitrarily. Each half must be independently checkable.
Before creating, verify: every subtask ≤ 8h · subtask efforts sum to the parent’s · no subtask has children.

8. Tags / labels

Do not use the storage tool’s native tag/label feature for classification. The prefix in the task name is the only classifier. Do not pass tags on create unless the user explicitly asks.

A task’s real context often lives in a linked spec, doc, or file rather than the description. When one is present:

Surface the link URL to the user.
Do NOT auto-download or auto-read it — ask first (AskUserQuestion). Read the content only after the user confirms.
Where that link is stored is provider-specific (providers.<active>.fields.specLink); the ask-before-reading behavior is universal.

10. Agent instructions

Apply §1–§9 in order when creating or reading a task: analyze context for action + domain (§2–§3, never an actor prefix), name per §1, synthesize the description per §5, apply §7 to every subtask, size/schedule per §6, never pass native tags (§8) unless asked. Full numbered checklist, worked domain-analysis examples, and the correct-vs-wrong naming table: docs/cocos-rushtank-task-conventions.md.

rules/t1k-cocos-rushtank-task-management.md — the neutral policy (states, dependency, ready-query, guarded-write, tool precedence). This file is its §1 in full.
.claude/task-config.json — active provider + how each neutral operation reaches the tool.
skills/t1k-cocos-rushtank-task-framework/SKILL.md — user-facing entry point.