# Task > Manage the project task backlog as plain markdown files in tasks. Use for broad backlog work including create, list, query, update, triage, implement, audit, finish, defer, archive, lint, split, or repair tasks. - **Type:** Skill - **Install:** `agentstack add skill-theafh-ai-modules-task` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [theafh](https://agentstack.voostack.com/s/theafh) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [theafh](https://github.com/theafh) - **Source:** https://github.com/theafh/ai-modules/tree/main/plugins/ai_dev/skills/task ## Install ```sh agentstack add skill-theafh-ai-modules-task ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # task The task skill is the hub and source of truth of the `task_*` family: the **project-local backlog** that manages a project's upcoming work and todos as plain-markdown task files living next to the code. The concept behind the whole system: every task file is written to be **self-sufficient** — the file alone is enough to implement the work from, including in a later session with no memory of the task's creation. That sufficiency is a floor, never a filter: at implementation time the implementer draws on everything actually available — the codebase, the project's standing instructions, the user in the loop. Activate this skill when the user: - Asks to create, write, capture, file, or add a task / todo / backlog item. - Asks to list, show, find, or query existing tasks. - Asks to update, edit, refine, or expand a task. - Says a task is done, finished, implemented, shipped, or completed — move it to archive with status `finished`. - Says a task should be dropped, parked, deferred, or shelved — move it to archive with status `deferred`. - Asks to lint, audit, or health-check the tasks directory. - Mentions the project's tasks, todos, or backlog in any way that implies persisting upcoming work as files rather than chat state. The wiki skill captures durable knowledge (concepts, procedures, references). The task skill captures *upcoming work* on this project. When a user message is about recording what they learned or how something works, route to `wiki` instead. When they want to track what still needs doing, this skill is right. ```text / ├── CHARTER.md? # optional hard project-purpose guardrail ├── ARCHITECTURE.md? # optional descriptive project architecture ├── FEATURES.md? # optional behaviour ledger ├── TESTING.md? # optional project-specific testing notes └── tasks/ ├── _.md # open tasks ├── _.md └── archive/ ├── _.md # finished + deferred tasks └── _.md ``` The filing convention has one canonical split: material directly about the task system lives under `tasks/`, and project-wide standing material lives at the repo root as optional `UPPERCASE.md` docs. The task tree stays intentionally two layers — `tasks/` for live work, `tasks/archive/` for closed work. No further task nesting. Scope sits in the filename, not in a folder. A bare project with only `tasks/` remains complete. Resolve the project root from the base `` step, then gate each optional standing-doc read with POSIX `test -f "$root/.md"`. On a hit, the consuming skill or agent reads the doc for the purpose named at its touchpoint; on a miss, it continues unchanged and raises no missing-doc error. `CHARTER.md` is the top guard: any skill or agent about to write or change task content validates the proposed content against the charter's boundaries and invariants and stops on a violation. The softer docs inform work without blocking it: `FEATURES.md` and `ARCHITECTURE.md` provide prior-art and design context for task creation, `TESTING.md` provides project-specific testing details for implementation and audit, and `ARCHITECTURE.md` is refreshed during finish when completed work extends the design. `_.md`. One underscore — exactly one — separates scope from name. Inside each side, words use `-`. Both sides are lowercase `a-z 0-9 -`. Examples: - `wiki-fix_split-page-anatomy.md` - `tasks-skill_initial-implementation.md` - `auth_session-token-rotation.md` - `infra_grafana-dashboard-cleanup.md` Pick `scope` from the project's natural shared groupings — a skill family, sub-project, module, topic, feature area, or service. Pick `name` to be compact, unique within the tasks tree (open *and* archive), and self-explanatory at a glance. Before creating, list the tasks directory and `archive/` once to confirm the chosen name does not collide. Every task carries this YAML frontmatter: ```yaml --- description: One-line compact summary of what this task delivers. scope: plugins/ai_dev/skills/task created: 2026-05-28T19:49:23 updated: 2026-05-28T19:49:23 status: open reported-by: default_user --- ``` Fields: - `description` — compact one-liner. Compose to roughly 180 characters; the linter warns above 200, and that gap is headroom for a later broadening edit rather than length to write at. The body carries the full context. - `scope` — either a relative path under the project root pointing at the directory the task targets (unquoted; e.g. `scope: plugins/ai_dev/skills/task`), or a short descriptive label when no single directory fits (quoted; e.g. `scope: "project xyz"`). The linter resolves an unquoted value against the project root and blocks if the path is missing or escapes the root; a quoted value is accepted as text. Paths win when one fits — the filesystem stays the source of truth. - `created` — ISO 8601 datetime, set once when the task is created. - `updated` — ISO 8601 datetime, bumped on every edit and on every status change. See `` for the legacy-backfill exception. - `status` — one of: - `open` — created and not yet checked. - `checked` — `task_check` ran and found blocking issues, either directly or as the gate inside `task_auto_check`. - `ready` — implementation-ready, either from a clean `task_check` verdict, from `task_auto_check` reaching that verdict, or from the user declaring readiness through the apply-findings update flow. - `implemented` — `task_implement` built the work. - `audited` — `task_audit` confirmed every body item, acceptance check, and required test over a current `implemented` task. - `finished` — closed out as done and archived. - `deferred` — parked or dropped and archived. - `reported-by` — the user who created the task, written by the create path and resolved via ``. See `` for legacy backfill. - `implemented-by` — the user who built the work, written by `task_implement` when it stamps `implemented`, required on `implemented`, `audited`, and `finished`, and resolved via ``. Deferred tasks omit it because they were never implemented. See `` for legacy backfill. Status matches location: `open`, `checked`, `ready`, `implemented`, and `audited` live in `tasks/`; `finished` and `deferred` live in `tasks/archive/`. Resolve a recorded user name by reading `git config user.name`; when that is empty or the project is not a git repo, ask the user which name to record; when the ask goes unanswered, write the literal string `default_user`. Obtain the timestamp by running the shell command below and copy its output verbatim — the model has no clock, so a hand-written time is a guess: ```bash date +%Y-%m-%dT%H:%M:%S # local time, e.g. 2026-05-28T19:49:23 ``` Both `created` (set once, on a fresh task) and `updated` (bumped on every edit, status change, and archive move) take their value from this command's output. When creating several tasks in one turn, run `date` once and reuse the captured value across the batch rather than re-running it per file. Each stage records the furthest lifecycle point it establishes: `task_create` writes `open`; `task_check` writes `ready` on a clean verdict and `checked` when blocking findings remain; `task_auto_check` edits the task body and reuses `task_check` for those `ready` / `checked` stamps; the apply-findings update flow writes `ready` only when the user declares readiness before implementation; `task_implement` writes `implemented`; `task_audit` writes `audited` only for a clean, complete verdict over a current `implemented`; `task_finish` writes `finished` for done work or `deferred` for parked work. Before a stage writes a status that could move a task backward, read the current status and compare it to the target. The guarded writers are exactly `task_check` and `task_implement`: `task_check` may otherwise overwrite `implemented`, `audited`, or `finished` with `checked` or `ready`, and `task_implement` may otherwise overwrite `audited` or `finished` with `implemented`. On a regression, warn, name the current→target move, and ask the user to confirm the move is intended unless the session context already makes that intent clear, then proceed only when confirmed. Forward moves, same-status stamps, `task_check` revising `ready` back to `checked`, and parking as `deferred` proceed without this guard. Task bodies are **100% CommonMark-standard markdown**. The YAML frontmatter at the top is the only allowed extension. The linter blocks on non-standard syntax so the tasks tree stays portable to any renderer and the filesystem stays the source of truth: - **No footnotes.** `[^name]` references and `[^name]: …` definitions are non-standard. Place attribution inline as a normal markdown link next to the claim. - **No wikilinks.** `[[target]]` is an Obsidian extension. Use `[text](relative-path.md)` for cross-references. - **Local cross-references are standard markdown links.** Relative `.md` links to other task files (under `tasks/` or `tasks/archive/`) must resolve on disk — the linter blocks broken targets. - **Link to another task file when the cross-reference carries weight.** Add a link when it marks a **dependency** (this task builds on, extends, or must follow the other), when reading the linked task would **change how this task is implemented** (it defines a rubric, format, or interface this task consumes), or when the **linked file will be co-edited** (a shared region, a coordinated double-edit, or competing mechanisms to reconcile). The settling test: would reading the linked task, or knowing it exists, change how you implement this task or edit this file? Keep the link when yes; leave out a relatedness-only reference — a bare "see also" / "distinct from" / "pairs with", or a reverse-duplicate pointer whose relationship the linked side already states — since reading the target changes nothing about the work. - **Locate referenced content by a verbatim label — the soft-pointer rule.** Anchor every pointer to an exact, greppable string in the target — a heading, a pseudo-XML tag, a symbol or rule name, or a short quoted phrase — together with the file path, so the reference resolves by search and fails loudly (grep finds nothing) once the target is reworded rather than landing the reader on stale, plausible-looking wrong code. The label carries the whole reference and must be verbatim-greppable: a vague description like "the matchers block" does not qualify. Give extent, when useful, as size — "the ~10-line guard block" — never as position. Keep position claims out: a `:N` suffix on a file path, a bare `line N`, and an `around lines N–M` range each carry a number that rots silently as the file evolves. Simplicity, single-topic scope, and standard tooling beat every non-standard extension. The body starts with a single `# Title` H1 on the first non-blank line, followed by the rest of the task content. Write the body to be **self-sufficient**: the file carries everything the work needs that the project itself does not already hold, while whatever exists at implementation time — the codebase, the project's standing instructions, the user in the loop — stays in play and gets used. Self-sufficiency is what lets a task outlive its origins: the conversation that created it is the one context guaranteed to be gone by then. Corollary: content a standing project instruction already mandates is cited from the task, with the rule's text staying in its source document. Fill these sections: - **Goal** — what the task delivers and the user-visible outcome. - **Context** — pointers to the relevant files, modules, prior decisions, related tasks, links. - **Approach** — the intended implementation path, plus any constraints or non-goals. - **Acceptance** — the contract of concrete checks that say the task is done (a staged fixture the new behaviour is proven on, a file state to inspect, a measurement to record). Every item honours the contract: - **Deliverable items flip.** Each item is false today and flipped true by the work, verifiable mechanically — a command to run, a file state to inspect, a behaviour to observe. - **Edit items supersede the stale passage.** When the task changes an existing artifact, at least one item checks that the prior passage is superseded and one canonical statement remains, rather than only checking that the new content appears somewhere. - **Task-specific gates only.** Every item's outcome changes with this task's work. The project's standing instructions own the generic gates — `make lint`, a deploy dry-run, the full test suite — which run at their standing moments; name a gate only when the task changes what it verifies, such as a new lint rule proven on a staged fixture or a new scenario added to a suite. - **Implementer-runnable.** Every item verifies through steps the implementer runs alone; an action the project's standing instructions gate on the user stays out of acceptance. - **Measured, with a fail branch.** Stochastic or empirical work names its measurement protocol — run count, fixed denominator, baseline — and the recorded measurement is the deliverable; the item states what happens when the hypothesis fails rather than gating on the hoped-for direction. - **Enumerate.** Prefer a list of independently verifiable items over one compound check. Write the body positive and action-oriented: the primary carrier of every section is what the work does — Goal, Approach, and Acceptance lead with the action taken and what "done" looks like. Negatives earn their place where they carry content of their own: a genuine non-goal, a guardrail, or the task-specific gate the **Acceptance** contract defines. Keep rejected-option debate out of the body: a brief non-goal or guardrail stays, while the rationale for options weighed and rejected lives in the change's commit or pull-request description, or in the wiki when it is durable design knowledge. Frame the body as current state to target — what exists, what is not there yet, and the state the work reaches — and let **Rewrite in place, don't append** define the target when an existing passage is affected. Further rules govern the body's structure: - **State once.** Each rule, constraint, or decision appears in exactly one place in the body; Goal, Approach, and Acceptance point at that statement rather than re-wording it, so the sections stay in agreement as the task evolves. - **Decide or label.** Resolve what you can derive before the file is written: exhaust the material available at authoring time — cited skills, the codebase, and the project's standing knowledge — and decide any fork answerable from that material. When one decision genuinely needs input that material cannot provide, label it explicitly ("Open decision:"), list the options, and name the default an implementer takes without further input; one labeled open decision is the ceiling. - **Illustrate.** The general statement carries each rule or requirement; specific cases, incident histories, and dated references stay brief illustrations supporting it. A body whose meaning lives only in an example has its altitude inverted. - **Redact by generalizing.** Keep user-specific and sensitive detail out by default: generalize rather than embedding absolute or home filesystem paths, secrets and credentials, personally identifiable data, and incidental product, project, tool, or person names. Repo-specific detail enters only when the user explicitly asks for it or the work genuinely needs it, and the body surfaces that choice rather than adding it silently. - **Compact only to the implementable floor.** Write compactly while a one-shot implementer can still act without re-deriving dropped detail. Stop compression when it would stack clauses until the logic between them is lost, name an edit site without the shape of the change, or give a rule without the one example that fixes its meaning. Test the floor with this question: would this file, plus the project, let an implementer produce the intended change without filling a gap from outside? - **Rewrit … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [theafh](https://github.com/theafh) - **Source:** [theafh/ai-modules](https://github.com/theafh/ai-modules) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-theafh-ai-modules-task - Seller: https://agentstack.voostack.com/s/theafh - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.