implementation-task-spec
Use when you create an implementation board task directly - the required fields, one-role-one-deliverable rule, and dependency ordering
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- implementation-task-spec
- category
- pm
- description
- Use when you create an implementation board task directly - the required fields, one-role-one-deliverable rule, and dependency ordering
03 SKILL.md 正文
Implementation Task Spec
Overview
An implementation task is a self-contained unit of work for one developer role. The recurring failures are bundling two layers into one task, cutting one feature into many small tasks, and vague, untestable acceptance criteria.
Core principle: One task = one role = one feature in one repository. Not smaller, not larger.
Sizing — how many tasks
A board task is not free. Each one is a separate agent run that starts cold and re-reads the repository and the spec, and each one gets its own branch, pull request, code review, security review, QA pass and release. Five small tasks on one feature pay that five times and make the agents rediscover each other's work; one task pays it once and keeps the whole feature in one context.
- Default: one task per feature, per repository (per
componentin a monorepo), per role. Everything the same developer does in the same codebase for the same feature — its endpoints, its screens, its validation, its tests, its copy — is one task with one checklist. - Split only at a real boundary:
- a different repository or a different developer role (backend / frontend / mobile / data / game) — those run in different workspaces;
- an unrelated feature, even in the same repository;
- a part the stakeholder wants shipped, approved or prioritised on its own (a Should/Could they may never start);
- a refactor or migration that must land before the feature — its own task,
blocked_byin front; - a change too large to review in one diff — over ~1,000 changed lines. Then cut it into two or three vertical slices that each work on their own, never into steps.
- Never split by endpoint, screen, file, CRUD verb, acceptance criterion, or step ("create the model", "add the handler", "write the tests" are one task).
- Merge check before the first
create_board_task: write the list of tasks you are about to open. Any two with the same feature, repository and role become one, and their criteria one checklist. - Several small asks in one message for the same repository and role (three copy fixes on the same page, two tweaks to the same form) are one task with one criterion each, unless they are unrelated features or the stakeholder asked for them separately.
create_board_task fields
| Field | Value |
|---|---|
| task_type | task (user-visible feature or change) · bug (existing behaviour is wrong) · technical (no user-facing behaviour: refactor, infra, CI, backend-internal) · analiz (investigation → system-architect, see analiz-task-spec) · design (a screen designed before it is built — the type assigns the ui-designer itself, so pass no assignee; the human approves it in analiz_review). A missing design system is never a hand-written design task: request_design_system opens it (Design brief below). Spell the argument task_type — type is silently ignored and the task is created as the default type. |
| column | backlog by default (stakeholder reviews before start); todo only if told to start immediately |
| assignee | one responsible developer role — REQUIRED: pass assignee: "<role>" (e.g. backend-developer) so that agent is dispatched. An unassigned task sits idle. Use list_team for valid names. |
| title | action-object ("Add task export endpoint", "Fix checkout price rounding") |
| description | PRODUCT only: user story ("As [persona], I want [capability], so that [outcome]") + context + out-of-scope + analiz reference if any |
| technical_description | TECHNICAL only: endpoints/files/schema touched, approach, constraints, interfaces consumed and produced. BEFORE filling it, verify every file and endpoint name against the actual repository: get_repo_tree for the layout, codebase_search/grep_code for the handler/route/symbol you are naming. Never write a path or endpoint you did not see — an invented path sends the developer to a file that does not exist. |
| acceptance_criteria | array of strings, one observable Given/When/Then per item, incl. error cases (see acceptance-criteria-gwt). About the PRODUCT only — never a board step ("moved to ready_for_qa", "PR opened", "QA notified"); those are dropped when the task is created |
| repository | which codebase the work touches — plain name ("acme-web") or UUID. Resolve with list_repositories. Omitting it silently files the task against the default repository. |
| project | which initiative it belongs to — plain name ("Acme") or UUID. Resolve with list_projects; create_project first if the initiative is new. |
| derived_from | the analiz task this work came out of, e.g. ["A-12"]. Set it whenever an analysis exists. The spec and plan are DOCUMENTS on that analiz task — never a docs/ commit — and this reference is what feeds them into the developer's run and lets them re-read the plan with list_task_documents A-12. |
| blocked_by | task keys that must be FINISHED before anyone starts this one, e.g. ["T-1"]. Enforced: the board parks this task in blocked while any of them is open and picks it up automatically when the last one lands. A design task counts as finished only once RELEASED — the designer releases it after approval, once its hand-off and follow-up tasks exist — and blocking on it is also what hands this task's runs its approved documents. |
| deploy_depends_on | task keys that must be LIVE IN PRODUCTION before this one may be released. Enforced at release time, and written into this task's before_deploy runbook automatically. |
| before_deploy / after_deploy / rollback_plan | what has to happen around the deploy — a migration to run first, a flag to flip after, how to undo it. Posted on the card automatically when the release is dispatched and when it lands. Put them here, not in a comment: a comment is not read at deploy time. |
Rules
- Verify names before writing them. Everything in
technical_descriptionthat names a file, endpoint, table or symbol comes fromget_repo_tree+codebase_search/grep_codeoutput, not from memory or plausibility. If you cannot find it, say what you looked for and leave the naming to the developer instead of guessing. - One field, one home.
description,technical_descriptionandacceptance_criteriaare three separate board fields, each rendered in its own section of the task. Never write acceptance criteria or technical detail intodescription— a pasted copy is what QA then reads instead of the real checklist, and it silently goes stale when the real field is edited. - Criteria describe the product, not the board. A column move, a PR, a comment, a hand-off, an assignment, opening the next task — none of these is a criterion, and the create/update tools drop them. Every criterion must be checkable from the running product (or the delivered document) alone, without reading the card's history.
- Criteria are structured, not prose. Pass
acceptance_criteria: ["Given …, When …, Then …", …]— each item becomes a checkbox the implementer ticks withset_criterion_completedand that QA and you then rule on withreview_criterion. A criteria block written as markdown text produces a task with an EMPTY checklist, so the task can never be verified complete. - Tag repository and project. Both accept names, so there is no reason to skip them and no reason to ask the stakeholder — look them up. To file a task that already exists, use
update_board_taskwithproject. - One role, one feature. Never bundle backend + frontend in one task — and never cut one role's work on one feature in one repository into several tasks (Sizing above).
- Creation-only fields.
derived_fromcan only be set bycreate_board_task—update_board_taskhas no such field and silently ignores it;task_typetoo, unlessupdate_board_task's schema lists it.assigneecan be set or corrected on an existing task withupdate_board_task. Fix a wrong one the update tool cannot change bydelete_board_task+create_board_task(noforceneeded in backlog/todo). - Secrets. Never ask the stakeholder for a third-party API key in chat. If a task needs one configured, say so in
before_deploy("needsX_API_KEYconfigured for <env>") and tell the human where to set it — not a comment, which nobody reads at deploy time. - Duplicate guard.
create_board_taskreturnscreated:falsewith the existing task when an open one has a near-identical title. Report "already on the board as T-n", not "created" — passallow_duplicate: trueonly for genuinely different work that happens to share a title.
Design brief (UI work)
Replaces a one-line "follow the existing design system" guess. Put this block in the description of any task that touches a screen a user sees:
Design brief
- Surface: marketing page | app screen | component change
- Audience & tone: <who>; <3 adjectives> e.g. "freelance designers; calm, precise, premium"
- Content language: <the product audience's language, e.g. English> — not TaskTrooper's UI locale
- Visual direction: follow the existing design system (v<N> from get_design_system) | design system comes first: D-<n> (request_design_system) | new: colours <names/hex>, fonts <names>, logo <attached> — "new" or unclear means a screen design task comes first: D-<n>
- References: <URL> — borrow <layout | palette | tone>, not the whole look
- Content: real copy per section (headline, subhead, CTA labels, empty/error messages). Copy you drafted is marked "draft copy".
- Primary action per view: <one>
- States: loading / empty / error / success for <which data views>
- Responsive notes: <anything non-obvious at 360px>
- Attachments: <files added with attach_task_file>
Procedure:
- Detect an existing design system before asking.
get_design_systemfor the repository first — an approved design system there means "follow the existing design system (v<N>)", no question. Nothing there (nobase, nolayer) and the work touches UI:request_design_system—scope: "project"with theproject.idget_design_systemreturned, orscope: "repository"for a repository in no project — with the brief's audience, tone, visual direction and references innotes. It opens the design-system task the project's Design System tab opens, intodolike an analiz — the ui-designer derives it from the code that exists, or creates it from the brief when there is none, and the human approves it in analiz_review before anything is built on it — or returns the one already open (created: false). Every UI task you create isblocked_byits returned key, and the brief's Visual direction line reads "design system comes first: D-<n>". Never hand-write a design task for a design system. - Design first when the look is new or unclear. When Visual direction is "new", the brief cannot say what the screen should look like, or the screen is new and no existing screen shows the pattern, the design comes before the build: create a screen design task first —
task_type: "design", noassignee,repository,project, the design brief and the screens it covers indescription, andblocked_bythe design-system task when you just requested one — then the implementation task(s) withblocked_bythat design task. That alone hands the developer the approved mockups and the hand-off spec, and holds the task until the designer has written the hand-off and released the design;derived_fromstays for an analiz task. Write "screen design task comes first: D-<n>" on the brief's Visual direction line. A change that follows an existing screen in the existing design system needs no design task. - Draft real copy yourself, in the content language. Never leave lorem ipsum, and never block the task on copy — the human corrects it at backlog approval or human_uat.
- Files the human uploads in chat (mockup, logo, screenshot) go on the task with
attach_task_fileand get one descriptive line in the brief, since the text survives even where an attachment doesn't render. - UI acceptance-criteria templates:
- "Given the page at 360, 768, 1024 and 1440 px wide, When it renders, Then there is no horizontal scroll and nothing overflows (the browser_set_viewport report lists no overflowing elements)"
- "Given <list> has no items, When the page loads, Then it shows '<exact empty-state copy>' and a '<CTA label>' button"
- "Given saving fails, When I press Save, Then '<exact error copy>' appears beside the form and my input is kept"
- Ordering is an argument, not a sentence. analiz (if needed) → design (if needed) → backend → frontend/mobile → qa. Declare each cross-task dependency with
blocked_by(nobody starts this until those are done) and, where the order also applies to shipping,deploy_depends_on(this is not released until those are live). Both point the same way: this task comes after the ones you list. A "Depends on: …" line in the description is worth writing for the human, but it enforces nothing on its own, and a cycle is refused at creation. - Ordered tasks still all go on the board. A blocked task parks itself and is picked up automatically when its blocker lands, so there is no reason to hold work in
backlogto fake an order. - Point at the analysis. If the work came out of an analiz task, set
derived_from. The architect normally does this; when you create the task yourself, you do. - Architect-created tasks: most implementation tasks are created by the system-architect after the human approves an analiz — you write tasks directly only for clear, small, no-analiz work.
Worked Example
create_board_task(
title: "Add task export endpoint",
task_type: "task",
column: "backlog",
assignee: "backend-developer",
repository: "tasktrooper",
project: "Task export",
description: "As a project member, I want to export my project's tasks to CSV, so that I can share them.
Out of scope: the web download button (separate frontend task). Depends on: none.",
derived_from: ["A-12"],
technical_description: "New GET /api/v1/projects/:id/tasks/export in internal/adapter/http/handler_task.go.
Streams text/csv, reuses repository.Service.ListTasks. No schema change.
Ref: the implementation plan attached to analiz task A-12.",
acceptance_criteria: [
"Given a member of the project, When they GET /api/v1/projects/:id/tasks/export, Then they get 200 + text/csv with header id,title,status,created_at",
"Given a user without access to the project, When they GET the same URL, Then they get 403 and no data is returned",
"Given an invalid project id, When they GET the endpoint, Then they get 400"
]
)
The web download-button task is a SEPARATE frontend task, and its order is declared rather than described:
create_board_task(
title: "Add export button to the project board",
assignee: "frontend-developer",
repository: "tasktrooper-web",
derived_from: ["A-12"],
blocked_by: ["T-1"], # the endpoint task — nobody starts this until it is done
deploy_depends_on: ["T-1"], # and it must not ship before the endpoint is live
...
)
Common Mistakes
- "Add export API and button" → two tasks (two roles, two repositories).
- "Add export endpoint", "Add export filters", "Add export tests" for the same backend → one task; that split triples the runs, reviews and releases for one feature.
- One task per acceptance criterion or per screen of the same flow.
- Aspirational AC ("works well").
- No assignee, or a role that can't do the work.
- An "Acceptance Criteria" heading inside
description→ the checklist is empty; passacceptance_criteriainstead. - Technical detail written into both
descriptionandtechnical_description→ keep it intechnical_descriptiononly. - An order stated only as "Depends on: the backend task" → nothing enforces it; pass
blocked_by/deploy_depends_on. - A task created out of an analysis with no
derived_from→ the developer has no route to the spec, because the spec is a document on the analiz task and not a file in the repo.
Red Flags
- AC mentions two layers/repos.
- Two tasks you are about to create share feature, repository and assignee → merge them.
- A chain of
blocked_bybetween tasks with the same repository and assignee → usually one task cut into steps. - No error/auth criterion.
- The created task comes back with an empty
acceptance_criteriaarray → you wrote them as prose. Fix it withupdate_board_task.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns