Tasks
Markdown-native task management. One file per task, YAML frontmatter, threads as callouts, a generated board.
Projects and tasks are files. There is no database to sync, nothing to export, and Obsidian renders all of it.
Projects
The project skill has three playbooks:
project createscaffoldsprojects/<slug>/with a README and atasks/folder. The two-letter task prefix derives from the slug automatically.project archiveretires one cleanly: it moves the folder to the archive, strips references from active docs, banners the README, and recompiles the index.project handoff <id>hands a task's work to the team. It drafts a GitHub issue on the repo the project's README names (issues_repo, plus optionalissue_labels), opens it once you approve the draft, and links the task to it. The issue becomes the record of the work, and sync offers to close the task when the issue closes.
Tasks
Each task lives at projects/<slug>/tasks/<id>-<slug>.md:
---
schema: 1
id: bd-004
title: "Write blog post: Why Bun is a joy for local TS scripts"
type: task
status: open
priority: P2
project: blog-dev
assignee: [ada]
labels: []
created: 2026-04-21
updated: 2026-07-24
due:
horizon: 2026-W30
depends_on: []
---
## Description
...
## Checklist
- [ ] ...
## Thread
> [!quote] Ada · 2026-07-24
> Let's frame it around the postinstall story.
> [!info] Ace · 2026-07-24
> Drafted an outline in the description.| Field | Values |
|---|---|
| ID | Two-letter project prefix plus a three-digit number. Globally unique. The agent assigns them |
| Type | task · bug · idea · epic |
| Status | open · active · blocked · done · cancelled. Transitions are validated |
| Priority | P0 drop everything · P1 this week · P2 this sprint · P3 backlog |
| Horizon | The period the task is planned for. See Horizon |
| Issue | The GitHub issue the task was handed off to, as its URL. Empty until a hand-off |
| Thread | Append-only. [!quote] for you, [!info] for the agent (Ace in the example), [!warning] for automated actions |
Closed tasks move to tasks/archive/ on the next sync so the active folder stays scannable.
Horizon
horizon is when a task is planned, stored as the period itself. It decides the lane the task shows in on the attention pages.
horizon | Lane |
|---|---|
2026-10-05 (a day) | Today on that day; carried over once it has passed |
2026-W41 (an ISO week) | This week; carried over after it |
2026-10 (a month) | This month; carried over after it |
later | Later |
| empty | Not planned |
Set it by saying today, week, next-week, month, or later.
Driving them
Inside a session, the agent uses the task_* MCP tools (query, get, create, update, close, thread, scan). Outside a session, the same operations are on the CLI:
bun "<plugin root>/src/cli.ts" task query --status=active
bun "<plugin root>/src/cli.ts" task create --project=blog-dev --title="Draft launch post" --description="Outline and first draft" --priority=P1
bun "<plugin root>/src/cli.ts" task close bd-004task query prints each task's frontmatter with its filePath, so a script can link the file without looking each one up.
Claude Code adds three shortcuts, from the plugin's mods:
/task bd-004shows a task as a card and/task bd-004 donecloses it, both without a model turn.- Task ids in replies open their file on a click.
/todaylists what's overdue and due today, with the last sync.
The board
projects/TASKS.md is generated from task frontmatter on every mutation: daily, weekly, monthly, and yearly goals at the top, then active tasks grouped by project, blocked, overdue, stale, and recently closed. It loads into every session, so the agent always knows the board. Never edit it by hand: tasks change through the task tools, and the goals at the top through the goals skill.