| name | taskvision-annotations |
| description | Use when writing or editing TODO/NOTE-style source comments in a TaskVision-managed repository. Teaches the tag vocabulary, inline status tokens, `tv:` directives, and the task/context/review annotation classes so agents stay compatible with the TaskVision tree, sidecar stores, and AI context exports. DO NOT USE for editing `.taskvision/*.json` directly — those files are owned by the extension. |
TaskVision Annotation Convention
TaskVision parses source comments into a task tree and a structured AI handoff bundle. Every annotation an agent writes must be parseable by the extension, otherwise it is invisible to humans, sidecars, and downstream agents.
When to use
- Adding a new task, follow-up, blocker, or idea in source.
- Recording a constraint / invariant / decision next to the code it governs.
- Leaving a review / verify / risk note tied to an active agent session.
- Updating an existing TaskVision annotation's status or directives.
Do not use this skill to edit .taskvision/tasks-meta.json, .taskvision/context-index.json, or .taskvision/change-sessions/*.json. Those are written by TaskVision commands.
Annotation grammar
Every annotation is a single comment line with this token order:
<COMMENT-PREFIX> <TAG> [<status>] <body text> [tv:ctx=...|tv:review=...] [tv:task=...] [tv:session=...] [tv:id=...]
Rules:
<COMMENT-PREFIX> is the language's normal single-line comment marker (//, #, <!--, --, ;, ...).<TAG> MUST be one of: TODO, FIXME, XXX, NOTE, IDEA, [ ], [x]. Use TODO/FIXME for work, NOTE/IDEA for context or review notes, [ ]/[x] for markdown checkboxes.[<status>] is REQUIRED for tasks and SHOULD be present for context/review notes. Allowed values: todo, doing, blocked, paused, review, done, wontdo, idea.tv: directives are optional but, when present, MUST keep the tail order ctx/review → task → session → id.<body text> is the human-readable summary. Keep it on the same line.- Keep human-readable text directly after
TAG [status]; machine fields belong at the end.
The three annotation classes
| Class | Required tag(s) | Required directives | Example |
|---|
task | TODO, FIXME, XXX, [ ], [x] | [tv:id=task....] only when tracked | // TODO [doing] refactor cache invalidation [tv:id=task.cache.123abc] |
context | NOTE (or IDEA) with [idea] | [tv:ctx=<kind>]; [tv:id=ctx....] when tracked | // NOTE [idea] cache writes must stay synchronous [tv:ctx=invariant] [tv:id=ctx.cache.456def] |
review | NOTE with [review] | [tv:review=<kind>] and [tv:session=...] | // NOTE [review] verify retry path under timeout [tv:review=verify] [tv:task=task.cache.123abc] [tv:session=sess.20260308.codex.001] |
tv:ctx allowed kinds: must-read, constraint, invariant, business-rule, pitfall, do-not-touch, entrypoint, example, decision, terminology.
tv:review allowed kinds: changed, why, risk, verify, blocked, followup.
Stable IDs
- Stable IDs look like
task.<slug>.<6-hex> or ctx.<slug>.<6-hex>.
- If you are creating a new task or context anchor and you do not have an ID, omit
tv:id. TaskVision writes stable IDs only when the annotation needs durable tracking, such as sidecar metadata, task/context links, non-lightweight task states, context anchors, or AI context export.
- Never invent an ID with random hex. Never reuse another annotation's stable ID.
- When updating an existing annotation, preserve its
tv:id exactly.
Status semantics (only what an agent must respect)
- Use
review instead of done whenever code changed but verification is incomplete.
- Do not flip
blocked, paused, or wontdo to an active state without saying why in the body or in a review annotation.
- For markdown checkboxes the implicit status is:
[ ] → todo, [x] → done. Adding an explicit [status] overrides the implicit value.
- Plain
TODO without a status is treated as todo. Always write the status explicitly to make changes auditable.
Choosing between context and review
- Use
context when the note is a long-lived fact about the code (constraint, invariant, decision, pitfall). It belongs next to the code forever.
- Use
review when the note is scoped to an in-progress session (verify this, why this changed, risk to watch, followup). It expires when the session closes.
- A
review annotation MUST carry tv:session=.... Ask the user (or call TaskVision: Start Agent Session) to obtain a session ID before writing review notes.
Self-check before writing
- Does the line start with the file's normal comment marker?
- Is the tag one of the allowed values?
- Is the status one of the allowed values, or correctly omitted (only for plain
[ ]/[x])?
- Are
tv: tokens at the line tail in the order ctx|review, task, session, id?
- Is the body text a single line, no trailing block-comment terminator?
- Did you avoid touching any
.taskvision/*.json file?
If all six pass, the annotation will round-trip cleanly through the TaskVision tree and the AI context export.
Examples
- [ ] update README quick start
- [x] migrate jest config
Hand-off contract
After writing or editing TaskVision annotations:
- Tell the user (or the next agent) which stable IDs you touched and why.
- Suggest running
TaskVision: Sync Data Model if you added new annotations without tv:id, or TaskVision: Export AI Context if downstream agents need the refreshed bundle.
- Do not modify sidecar JSON or generated
ai-context.{md,json} files yourself.
