TaskPlanner

View saved version →

---
name: board
description: Show the TaskPlanner board for the current repository. Use when the user asks to open, show, or look at the task board, kanban, or what is in progress. In Claude Code the board pane opens directly and this skill does not run.
---

# Show the TaskPlanner Board

1. Determine the absolute active repository root and pass it as `workspace_root` on every MCP call.
2. If the host renders MCP Apps (Cursor, Claude Desktop chat, VS Code), call `taskplanner_board_visual` to show the interactive board.
3. Otherwise call `taskplanner_board` and show the counts per state, then the In Progress and Next tasks with ID, priority, and title.
4. If MCP is unavailable or cannot access the repository, read `.tasks/config.json`, then count the `##` task sections in each configured state file.

Do not alter the board while showing it.

View saved version →

---
name: continue-task
description: Resume a TaskPlanner task that is already In Progress. Use when the user asks to continue, resume, finish, or inspect active TaskPlanner work.
---

# Continue an In-Progress TaskPlanner Task

1. Run the sibling `taskplanner` skill's version preflight once.
2. Prefer `taskplanner_list` for In Progress and `taskplanner_get` for details, passing the absolute repository as `workspace_root`.
3. If MCP cannot access the repository, read the In Progress file from the state mapping in `.tasks/config.json` and parse complete task sections directly.
4. If none exist, suggest `next-task`; if several exist, ask which to resume.
5. Follow the selected task's existing plan. Add a required missing plan before coding.
6. Implement and verify the remaining work.
7. Condense the plan, move the task to Done, add a top `.tasks/WORK_LOG.md` entry when present, and update `CHANGELOG.md` when required.

Never change task IDs or modify unrelated task sections.

View saved version →

---
name: initialize-taskplanner
description: Initialize TaskPlanner in a repository. Use for install, setup, initialize, create-board, or first-time TaskPlanner requests; create the .tasks board, managed agent instructions, version metadata, and optional README attribution without overwriting existing project content.
---

# Initialize TaskPlanner

<!-- TASKPLANNER:VERSION:3.0.18 -->

1. Locate the active repository root. If `.tasks/config.json` already exists, do not replace the board; follow the sibling `update-taskplanner` skill instead.
2. Create `.tasks/` and `config.json` with schema `version: 2`, `taskplannerVersion` set to the version in this skill's `TASKPLANNER:VERSION` marker, `readmeAttribution: true`, `idPrefix: "TASK"`, `nextId: 1`, the five default states, priorities P0-P4, empty tags, top insertion, required AI plans, and priority sorting.
3. Create missing state files with `# <State>` headings and create `WORK_LOG.md` with a short completion-log heading/template. Never overwrite an existing file.
4. Apply the managed synchronization rules from the sibling `update-taskplanner` skill to `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and an existing root README.
5. Verify every required board file exists and the stored `taskplannerVersion` matches that marker.

README attribution is voluntary. Do not create a README solely for it, do not duplicate the managed block, and preserve all content outside TaskPlanner markers.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: list-tasks
description: List TaskPlanner tasks from the repository board, grouped or filtered by state. Use for board summaries, status checks, backlog queries, and finding current work.
---

# List TaskPlanner Tasks

1. Run the sibling `taskplanner` skill's version preflight once.
2. Determine the absolute active repository root.
3. Prefer `taskplanner_board` with `include_tasks: true`, passing `workspace_root`. For a state/text filter, prefer `taskplanner_list`.
4. If MCP is unavailable or cannot access the repository, read `.tasks/config.json`, then parse the configured state files by `##` task sections.
5. Show ID, title, priority, and assignee; omit descriptions unless requested and highlight In Progress work.

Do not alter the board while listing it.

View saved version →

---
name: next-task
description: Select and implement the highest-priority TaskPlanner task from Next or Backlog. Use when the user asks to start, pick, or complete the next planned task.
---

# Start the Next TaskPlanner Task

1. Run the sibling `taskplanner` skill's version preflight once.
2. Prefer `taskplanner_list` for Next, then Backlog, always passing the absolute repository as `workspace_root`. If MCP cannot access the repository, read and parse the configured state files directly.
3. Select the highest priority task and identify it to the user.
4. Move its complete section to In Progress with `taskplanner_move` or a direct cut/insert.
5. Read `.tasks/config.json`; when `aiPlanRequired` is true, add a concise `### Plan` before coding.
6. Implement and verify the task.
7. Condense the plan, move the task to Done, add a top `.tasks/WORK_LOG.md` entry when present, and update `CHANGELOG.md` when required.

Never change task IDs or modify unrelated task sections.

View saved version →

---
name: taskplanner
description: Manage tasks stored in .tasks markdown files. Use when the user mentions tasks, backlog, planning, priorities, sprints, or asks to create, implement, update, list, or move TaskPlanner tasks. Prefer TaskPlanner MCP tools when they can access the active workspace and otherwise operate on the files directly.
---

# TaskPlanner

<!-- TASKPLANNER:VERSION:3.0.18 -->

TaskPlanner stores a git-tracked board in `.tasks/`. Use MCP tools when available, always passing the absolute active repository as `workspace_root`. If a tool is unavailable or cannot see that repository, use the direct file workflow below without blocking the user.

## Version preflight

Run this once before the first TaskPlanner operation in a Codex/Cursor task:

1. Read `.tasks/config.json` and compare `taskplannerVersion` with the embedded version above. Strip SemVer build metadata such as `+codex.*` before comparing.
2. If the stored value is missing, malformed, or older, follow the sibling `update-taskplanner` skill before continuing.
3. If equal, continue without writes, except when the `upgradeChecks` array in the config is missing or lacks `"3.0"`: then run the sibling `update-taskplanner` skill's **Upgrading to 3.0** checks first.
4. If the stored value is newer, warn that the installed plugin is older and do not downgrade managed files.

The installed skill bundle is authoritative. Never query GitHub or invoke a marketplace update.

## Board files

Use the `states` mapping in `.tasks/config.json`; defaults are Backlog (`BACKLOG.md`), Next (`NEXT.md`), In Progress (`IN_PROGRESS.md`), Done (`DONE.md`), and Rejected (`REJECTED.md`). `WORK_LOG.md` is an optional completion log, not a state.

Each task is a complete section from its `## ID: Title` heading through its trailing `---` separator:

```markdown
## TASK-001: Task title
**Priority:** P1 | **Tags:** tag1, tag2

Description.

### Plan

- Step 1

---
```

## MCP path

Prefer `taskplanner_board`, `taskplanner_list`, `taskplanner_get`, `taskplanner_create`, `taskplanner_move`, and `taskplanner_update`. Use `taskplanner_board_visual` only when the host renders MCP Apps.

## Direct file path

- List by reading configured state files and parsing `##` sections.
- Create by reading `idPrefix` and `nextId`, generating the padded ID, incrementing and saving `nextId`, then inserting one complete section at the configured top/bottom position.
- Update only the selected task section; preserve its ID and every unrelated section.
- Move by cutting the complete section, including its separator, from the source state file and inserting it into the target state file.
- Preserve user configuration choices and all content outside the selected task or TaskPlanner marker blocks.

## Implementing work

1. Select the highest-priority task from Next, then Backlog, unless the user chose one.
2. Move it to In Progress before substantive implementation.
3. When `aiPlanRequired` is true, add a concise `### Plan` before coding.
4. Implement and verify the work.
5. Condense the plan to a done-summary and move the task to Done.
6. Add one short entry at the top of `.tasks/WORK_LOG.md` when it exists.
7. Add a `CHANGELOG.md` entry under `## [Unreleased]` when repository guidance requires it.

Never change task IDs or modify unrelated task sections.

View saved version →

---
name: update-taskplanner
description: Synchronize an existing TaskPlanner project with the installed skill version. Use for update, upgrade, migrate, refresh, or sync requests and for the TaskPlanner version preflight; update only TaskPlanner-owned marker blocks and safe config defaults without changing tasks or user choices.
---

# Update TaskPlanner Project

<!-- TASKPLANNER:VERSION:3.0.18 -->

## Compare versions

1. Read `.tasks/config.json`. The numeric `version` is only the task-file schema; never use it as the installed product version.
2. Compare `taskplannerVersion` with the version in this skill's `TASKPLANNER:VERSION` marker, stripping SemVer build metadata such as `+codex.*`.
3. Missing/malformed stored value is legacy: synchronize once. Installed newer: synchronize. Equal: no synchronization unless the user explicitly requested a refresh. Installed older: warn and do not downgrade.
4. Whatever the comparison says, run **Upgrading to 3.0** below when it is still pending. The VS Code/Cursor extension records the new `taskplannerVersion` on its own, without those checks, so the version cannot tell whether they ran.

The installed package is authoritative. Do not query GitHub or run plugin/marketplace upgrades.

## Synchronize managed content

Perform every step before recording the new version:

1. Add missing safe defaults (`readmeAttribution: true` and other absent TaskPlanner config defaults) while preserving task states, IDs, priorities, tags, insertion/sort choices, and unknown user fields. Do not change schema `version` except for a defined schema migration.
2. Generate the TaskPlanner workflow from the current config and upsert exactly one block between `<!-- TASKPLANNER:START -->` and `<!-- TASKPLANNER:END -->` in `AGENTS.md`, `CLAUDE.md`, and `.cursorrules`. Create a missing instruction file, but preserve every byte of user content outside the markers.
3. When `readmeAttribution` is true and a root `README.md` exists, upsert exactly this block; never create a README for it:

```markdown
<!-- TASKPLANNER:ATTRIBUTION:START -->
This project uses [TaskPlanner](https://github.com/smekai/taskplanner) for task planning.
<!-- TASKPLANNER:ATTRIBUTION:END -->
```

4. When attribution is false, leave any existing attribution untouched and do not insert one.
5. Never rewrite task sections, state files, or content outside managed markers.
6. Only after all writes succeed, set `taskplannerVersion` to the marker version and save config. On failure, leave the previous value so a later invocation retries.

## Upgrading to 3.0

These checks are tracked on their own, in the `upgradeChecks` array of `.tasks/config.json`, not by `taskplannerVersion`. Run them when that array is missing or does not contain `"3.0"`, and on every explicit update, upgrade or refresh request even when it does. Task files, IDs and the config schema need no change. Change nothing outside the managed markers unless the user agrees.

1. **Duplicate MCP server.** If `.mcp.json` lists a server that runs `@smekai/taskplanner` (for example `npx -y @smekai/taskplanner`), and this session already has TaskPlanner tools from the installed plugin (tool names with a plugin prefix, such as `mcp__plugin_taskplanner_…`), tell the user the tools load twice and offer to remove that one entry. On a yes, remove only that entry and keep the rest of the file; if no servers remain, offer to delete the file. Without the plugin's tools, keep the entry: it is how this host reaches TaskPlanner.
2. **Removed tool.** 3.0 removed `taskplanner_board_data`. Search the instruction files and `.cursor/`, `.claude/` and `.codex/` for it. The managed blocks are regenerated anyway; for mentions outside them, list each place and suggest `taskplanner_board` for a text overview or `taskplanner_board_visual` for the interactive board. Edit them only on a yes.
3. Tell the user what changed and what they chose to keep, in two or three lines. If neit

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.