AgentLayer▸docs
Use it

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 create scaffolds projects/<slug>/ with a README and a tasks/ folder. The two-letter task prefix derives from the slug automatically.
  • project archive retires 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 optional issue_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.
FieldValues
IDTwo-letter project prefix plus a three-digit number. Globally unique. The agent assigns them
Typetask · bug · idea · epic
Statusopen · active · blocked · done · cancelled. Transitions are validated
PriorityP0 drop everything · P1 this week · P2 this sprint · P3 backlog
HorizonThe period the task is planned for. See Horizon
IssueThe GitHub issue the task was handed off to, as its URL. Empty until a hand-off
ThreadAppend-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.

horizonLane
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
laterLater
emptyNot 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-004

task 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-004 shows a task as a card and /task bd-004 done closes it, both without a model turn.
  • Task ids in replies open their file on a click.
  • /today lists 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.

On this page