tasklist

name	tasklist
description	Maintain a project's canonical TASKS.md or an opted-in studio portfolio task register with permanent IDs, ownership, lifecycle dates, and source provenance. Use to list, add, update, complete, or cancel tasks, view tasks across registered projects, or import selected action items from project artifacts. Do not use for planning the work itself or silently turn every proposed action into a task.
allowed-tools	["Read","Write","Edit","Glob","Grep","AskUserQuestion"]

/as:tasklist — Canonical Project or Studio Task Register

Harness note: use /as:<skill> on Claude Code and $<skill> on Codex. Resolve <skill-root> as the directory containing this loaded SKILL.md and <plugin-root> as the plugin root that contains skills/, and use equivalent native tools when host tool names differ.

Own exactly one resolved TASKS.md: either a project's register or an opted-in studio portfolio register. Give every action a permanent identity, explicit lifecycle, and traceable source. This skill manages actions; /as:workplan may define future work, but it is neither required nor invoked implicitly.

Usage

/as:tasklist list
/as:tasklist add Coordinate reflected ceiling plan with electrical — owner: Sam — due: 2026-08-03
/as:tasklist update T0012 owner: Priya due: 2026-08-07
/as:tasklist complete T0012
/as:tasklist cancel T0014 reason: superseded by T0018
/as:tasklist import meetings/YYYY-MM-DD-owner-review.md#A3

Hard rules

1. One canonical register. Read and write only the register returned by canonical context resolution. Project mode uses the selected project's TASKS.md; portfolio task mode uses the studio-root TASKS.md. They are never simultaneously writable for the same studio.
2. Permanent identity. IDs use T0001, T0002, and so on. Never delete, reuse, or renumber an ID. Allocate max(all parseable IDs) + 1, including completed and cancelled rows; gaps stay gaps.
3. Preserve history. Updating or closing a task keeps its ID, source, created date, and earlier lifecycle events. Append a dated history entry; do not erase the prior state.
4. No silent promotion. A plan unit, meeting action, site follow-up, or decision consequence remains a proposal until the user selects it for import. Preview candidates before mutation.
5. Provenance is exact. In project mode, file sources are project-relative. In portfolio mode, store a studio-relative link beginning with the selected registered project path so the link resolves from the studio register. Every source includes a stable heading/item ID, or uses the canonical direct-instruction token conversation:YYYY-MM-DD#instruction-N. Never invent a file or persist an absolute machine path.
6. No silent duplicates. Normalize a source within the selected project, then compare Project ID (in portfolio mode), normalized source path, and exact source item together. For conversation instructions, compare Project ID when applicable plus the complete canonical token. That normalized provenance key is the deduplication key. If it already exists, show link, update, or new and wait for the user's choice.
7. Malformed means blocked, not empty. Preserve a malformed register byte-for-byte. Report the path and parse problem, and block every mutation until the user authorizes repair. Listing may report parseable content and the failure, but must not claim completeness.
8. Harness neutral. Cross-skill invocation, agents, git history, structured question tools, and /as:workplan are optional conveniences, never runtime requirements.

Resolve canonical context

Resolve a typed target once before any operation. /as:tasklist with no arguments means list; do not require an argument and do not open a confirmation gate for a read-only list.

1. Run the shared resolver and follow skills/project/references/context-resolution.md. Its typed result and validated choices are authoritative; do not reimplement manifest or filesystem validation in prose.
2. If a project is resolved, read its Project ID. If an owning studio is also explicitly resolved, read Task register from STUDIO.md and confirm the project is a matching registered descendant:
   • project mode returns project-register at <project-root>/TASKS.md;
   • portfolio mode returns portfolio-filter at <studio-root>/TASKS.md, filtered to the Project ID. A standalone project with no owning studio uses project mode.
3. For studio-picker, select the sole choice or use one structured gate listing validated projects plus All projects. Do not ask the same question first in prose.
4. For no-projects, offer /as:studio create-project; for no-context, ask for a project/studio path or offer /as:studio; for invalid, stop. Never create a register at an inferred directory.

All-project targets

• In project mode, All projects is a read-only merged view of each eligible project's TASKS.md. Validate each register independently, preserve local IDs, and display them as <project-id>:<task-id> (for example 2401:T0007). Never persist the merged view or renumber a task.
• In portfolio mode, All projects is the unfiltered studio-root register. A selected project is a Project ID filter on that same file.
• An add/import from an all-project view must first select one eligible project. An update/complete/cancel in project mode must resolve one exact <project-id>:TNNNN and mutate only that project's register. A read-only merged view itself is never a mutation target.

Register contract

Create TASKS.md only after a valid target has been resolved and the first mutation is previewed and confirmed. Project mode uses bundled templates/tasks.md; portfolio mode uses templates/portfolio-tasks.md. Resolve templates relative to this skill's own directory. If bundled-resource resolution is unavailable, reproduce the applicable schema rather than searching unrelated installed copies.

The task table has these required columns:

Field	Contract
ID	Permanent TNNNN identifier
Description	One observable action
Owner	Named person, role, or Unassigned
Due	YYYY-MM-DD or —
Status	open, in-progress, blocked, completed, or cancelled
Created	YYYY-MM-DD
Updated	YYYY-MM-DD
Completed	YYYY-MM-DD or —
Cancelled	YYYY-MM-DD or —
Source	Canonically relative Markdown link with an exact heading/stable item ID, or conversation:YYYY-MM-DD#instruction-N
Related	Optional plan-unit or decision link, otherwise —

The portfolio schema adds Project ID immediately after ID. Every value must match one eligible active or on-hold project in the current studio manifest. File links are relative to the studio register and begin with that project's registered path; validation also confirms they remain within that project. Portfolio task IDs remain permanent across the studio; project-filtered views never change them.

Lifecycle history lives under ## History, one append-only bullet per change:

- 2026-07-21 — T0007 created as `open` from source item `meetings/YYYY-MM-DD-owner-review.md#A3`.
- 2026-07-23 — T0007 owner changed from Sam to Priya; status changed from `open` to `in-progress`.
- 2026-07-28 — T0007 completed.

Treat missing required columns, duplicate IDs, invalid IDs or statuses, unparseable required dates, or a task row whose Source is neither a valid project-relative item link nor a valid canonical conversation token as malformed. Do not normalize or rewrite such a file without authorization.

Operations

List

1. Resolve the target, then read and validate the entire canonical register or every register in a read-only merged view.
2. Show tasks grouped by project when more than one project is visible, then by status, preserving ID order. Apply user filters for project, owner, due date, or status when supplied.
3. In a project-mode merged view, qualify each ID as <project-id>:<task-id> and label missing or malformed registers independently; one malformed project must not make another project appear empty.
4. Report malformed content explicitly. Listing is read-only.

Add

1. Require one resolved project identity even when writing the portfolio register. Parse the requested description, owner, due date, source, and optional related link. Ask only for missing information that materially changes the task; Unassigned, —, and the current date are valid explicit defaults. For a direct instruction with no file source, allocate the next unused conversation:YYYY-MM-DD#instruction-N token for that date and show it in the preview.
2. Validate the full register and run the normalized source-path plus source-item duplicate check.
3. Preview the exact proposed row. Wait for confirmation.
4. Allocate the next monotonic ID, append the row, and append its creation history event.

Update

1. Require an existing task ID and show its current values.
2. Preview field changes. Do not change ID, Created, Source, Completed, or Cancelled through a routine update.
3. On confirmation, change only selected mutable fields, set Updated to today, and append a history event naming old and new values.
4. Updating a completed or cancelled task preserves its closure date and history. Reopening is a separate explicitly confirmed lifecycle change; never clear historical closure dates.

Complete

1. Show the selected task and preview Status: completed, Updated: today, and Completed: today.
2. On confirmation, preserve all identity and provenance fields, apply those values, and append a completion history event.
3. If already completed, report it without rewriting. A cancelled task requires explicit reopen approval before completion.

Cancel

1. Require a short cancellation reason and show the selected task.
2. Preview Status: cancelled, Updated: today, and Cancelled: today.
3. On confirmation, preserve all identity and provenance fields and append the reason to the cancellation history event.
4. If already cancelled, report it without rewriting. Never delete the row.

Confirmed import

Imports may read any user-specified artifact. Common sources are plans/, meetings/, site-reports/, and decisions/, but none is required.

1. Read the named source and identify candidate actions without changing TASKS.md.
2. Label candidates by their existing stable item ID. If the source has no stable item ID, propose one or cite the nearest heading plus an unambiguous item label; do not fabricate a false anchor.
3. Preview description, owner, due date, normalized source path/item, and optional plan-unit or decision link for every candidate.
4. Ask the user to select individual candidates. “Import all” is allowed only when the preview is visible and the user explicitly confirms it.
5. Before appending each selected candidate, compare the normalized project-relative source path plus exact source item against every task, regardless of status.
6. For a match, show the existing ID and offer:
   • link — keep the existing task and report its ID;
   • update — preview authorized mutable-field changes to that task;
   • new — create a distinct task only after the user confirms why it is separate.
7. Validate again, allocate IDs monotonically, append only confirmed rows, and record an import history event for each.

If direct invocation of another skill is unavailable, preserve the source and print the exact /as:tasklist import <path>#<item> command. Never claim an import occurred without reading the resulting TASKS.md.

Repair boundary

When TASKS.md is malformed:

1. Stop all add, update, complete, cancel, and import mutations.
2. Report each detectable problem and retain the original file.
3. Offer a repair preview that shows every proposed change.
4. Repair only after explicit authorization. Prefer the smallest correction; never renumber IDs, delete rows, or infer missing lifecycle facts.
5. If a required fact cannot be recovered, keep the original row in a clearly labeled quarantine section and ask the user how to resolve it.

Completion response

After a mutation, re-read the canonical register and report the project identity, affected permanent IDs, resulting statuses, and source links relative to the owning project or studio as appropriate. After a read-only operation, state that no files changed.