taskflow-assistant

Helps you manage your own work tasks and projects in a local TaskFlow instance, from any folder. One MCP server, two ways to use it:

Where	How	Section
Claude Desktop, Chat	MCP server registered in claude_desktop_config.json + one uploaded skill	Claude Desktop (Chat)
Claude Code (terminal, IDE extensions, the desktop app's Code tab where available)	A Claude Code plugin: MCP server + agent + five slash-command skills	Claude Code plugin

A Claude Code plugin does not load in Chat: Chat ignores a plugin's local MCP servers, agents and bin/ executables (see the plugin support table), so Chat needs the separate setup below.

Claude Desktop (Chat)

Needs the .NET 10 runtime on PATH, Claude Desktop, and TaskFlow running with the Projects API.

1. Stop any running TaskFlow server (disable taskflow in /mcp in Claude Code, and quit Claude Desktop completely), then publish the server: ./build.ps1. The build stops and lists the blocking processes (PID and parent) if a server is still running, and a failed build leaves the old plugin/bin in place.
2. Quit Claude Desktop completely (tray icon > Quit). It rewrites its config while running, so the script refuses to edit it while the app is open. Quitting also stops the server process Claude Desktop started, which would otherwise block the build.
3. Register the server: ./scripts/install-claude-desktop.ps1 (add -ApiUrl http://host:port if TaskFlow is not on localhost:8081; -DryRun previews, -Uninstall removes). It merges a taskflow entry into %APPDATA%\Claude\claude_desktop_config.json, keeps your other settings and saves a timestamped backup next to it.
4. Start Claude Desktop. In a chat, the + menu's connectors list should show taskflow with 15 tools. If not, open Settings > Developer in Claude Desktop (log locations differ between the Microsoft Store and installer versions; on the Store version no MCP log files appeared under %APPDATA%\Claude\logs). You can also confirm the app started the server with Get-CimInstance Win32_Process -Filter "Name='dotnet.exe'" | Where-Object CommandLine -match 'TaskFlow.Mcp.dll'.
5. Package and upload the skill: ./scripts/package-chat-skill.ps1, then in Claude Desktop go to Customize > Skills > + > Upload a skill and choose dist/taskflow-assistant-skill.zip.

Chat applies the skill automatically when your request fits ("plan my day", "turn these notes into tasks", "draft my weekly update", "stand-up"); there are no slash commands in Chat. Skills need code execution enabled for your account; if your organization disables it, paste chat/taskflow-assistant/SKILL.md into a Project's instructions instead. The skill lives in chat/taskflow-assistant/ and mirrors the plugin's five skills, restricted to the frontmatter keys Chat accepts.

Claude Code plugin

A Claude Code plugin for the terminal and IDEs.

It bundles:

• An MCP server (src/TaskFlow.Mcp, C# / .NET 10, stdio) wrapping the TaskFlow REST API.
• An agent, work-task-assistant, for delegated task work.
• Five skills for interactive workflows (all user-invoked, nothing runs on its own):

Command	What it does
/taskflow-assistant:plan-my-day [date or project]	Reviews the journal (parents with open subtasks shown as uncounted context), overdue/due-soon/stale tasks, proposes a focus list, plans what you confirm
/taskflow-assistant:capture-tasks [notes]	Turns notes into tasks (project, priority, due date), creates them after you confirm
/taskflow-assistant:weekly-review [from] [to]	Summarizes the week and drafts a status update
/taskflow-assistant:journal-log [what happened]	Logs progress to the journal, linked to the right task
/taskflow-assistant:standup	Builds the weekday stand-up: last working day's completed work (Friday on Mondays and weekends), today's plan, overdue; grouped by project, read-only

Local use only: it talks to your Docker TaskFlow stack (http://localhost:8081 by default) and has no auth, hosting or deployment story.

Requirements

• Claude Code (checked with 2.1.292) and the .NET 10 runtime on PATH (dotnet).
• A running TaskFlow with the Projects API (TaskFlow PR #221) and the journal update fix (#224; without it, update_journal with summary returns a 500 on days that have planned tasks). Both are merged to main. Start it with docker compose up -d --build in the TaskFlow repo.

Install

./build.ps1                                   # publishes the server into plugin/bin (gitignored)
claude plugin marketplace add C:\code\taskflow-assistant
claude plugin install taskflow-assistant@taskflow-assistant   # user scope: every project in Claude Code

Stop running TaskFlow servers before ./build.ps1: disable taskflow in /mcp, or quit Claude Desktop. If one is still running, the build stops and lists each blocking process id and its parent; no files change. A failed build also leaves the old plugin/bin in place.

This is for Claude Code only. The Chat part of Claude Desktop does not read it; use the Chat setup.

Add the marketplace from the local path (as above). Claude Code then loads the plugin in place, so the published plugin/bin is found and your edits apply on the next session or /reload-plugins. A copy installed from GitHub would not contain plugin/bin.

The API URL comes from the plugin's api_url setting (default http://localhost:8081), which is passed to the server as TASKFLOW_API_URL. A blank or malformed value falls back to the default. Change it with /plugin configure taskflow-assistant.

Check it: claude mcp list should show plugin:taskflow-assistant:taskflow ... Connected.

Tools

Fifteen tools, deliberately consolidated around workflows rather than one per endpoint. Tasks and projects are referred to by name; ids are returned for follow-up calls.

Area	Tools
Projects	list_projects, save_project (create / rename / archive), project_status
Tasks	list_tasks (views: open, overdue, due_soon, stale, unassigned, today, blocked, completed, all; completedFrom, completedTo, plannedDate; paging; concise/detailed), get_task, create_tasks (batch, partial failures reported, possible-duplicate warnings), update_task (merge, complete/reopen, project move, start with status=inprogress, block/unblock with blockedReason, plan on a day with journalDate), update_tasks (up to 25 updates in one call, same fields as update_task, failures reported per item), delete_task, add_task_note
Journal	get_journal (creates the day's entry if missing; shows a parent with an open subtask planned that day as an uncounted Context: line, with the subtasks beneath it; unplanned subtasks via list_tasks; log lines read `[task #id
Review	weekly_review (read-only)

Behaviors worth knowing:

• The TaskFlow task PUT is full-replace; update_task reads the task, merges your changes and sends the full body. With a project, it resolves the project before saving, so an unknown or ambiguous project changes nothing; if assigning fails after the save, the error says the task fields were saved and to retry only the project change.
• create_tasks flags a new task whose title equals an existing open or done task (ignoring case and extra spaces), or an earlier task in the same call, with ! Possible duplicate of #id "Title" (open|done). The task is still created. The check is best-effort: if existing tasks cannot be read, tasks are created anyway and the report ends with "Duplicate check skipped". Matching is exact after normalizing, not fuzzy.
• update_journal with append=true reads the day's summary and saves it plus a blank line plus the new text; it fails without saving when the total would exceed 10000 characters. It reads then writes, so an edit made in between (for example in the web app) is overwritten, and a retried append adds the text twice.
• update_tasks runs each item like update_task. Items are independent; if the API cannot be reached, the remaining items are reported as not attempted. If an item's project change fails after its fields were saved, its x line says so; retry only the project change.
• Statuses are Draft, Todo, InProgress, Blocked and Completed. Only a Todo task can be started, only a Todo or InProgress task can be blocked, and tasks cannot be created as Blocked. Detailed output shows Started: <date> UTC when the API reports a start time. Blocked tasks still count as open and are shown as blocked: <reason> (Nd); project_status and weekly_review list them in their own group.
• update_task re-sends the task's status on every PUT, so a Blocked task stays Blocked. An omitted blockedReason keeps the stored reason; an empty string clears it (the task stays Blocked); status=todo on a Blocked task unblocks it and restores its previous status (Todo or InProgress), and on an InProgress task moves it back to Todo.
• Blocked support needs the TaskFlow API change #311 deployed. This plugin ships prompts that rely on it, so do not publish or tag a release until #311 is live on your API. The server is published with build.ps1 into plugin/bin, so the plugin version and the server ship together.
• InProgress support needs the TaskFlow API change #351 deployed. This release must not be published or tagged until #351 is live on your API.
• update_task / update_tasks accept journalDate (today, tomorrow or yyyy-MM-dd, today or later) to plan a task on a day in the same call; it is separate from dueDate. Omitting it leaves the planned day unchanged, and update cannot un-plan a task (use set_journal_todos with remove). yesterday is rejected locally and earlier dates by the API, and a task with open subtasks cannot be planned (Blocked counts as open), so plan its subtasks instead; a completed task cannot be planned onto a different day. The reported planned day is read back from the API; if it cannot be confirmed, the result says so.
• journalDate on update needs the TaskFlow API change #352 (PR #377) deployed. This release must not be published or tagged until it is live on your API.
• TaskFlow refuses some changes with a rule code: planning a task with open subtasks (TASK_PLAN_HAS_OPEN_SUBTASKS), an open child under a Completed parent (TASK_PARENT_COMPLETED_NOT_ALLOWED), changing the status of a parent with open subtasks (TASK_PARENT_STATUS_DERIVED), and planning a completed task onto a different day (TASK_PLAN_COMPLETED_NOT_ALLOWED). The error shows the API message and code plus one line of next-step guidance; in update_tasks, create_tasks and set_journal_todos the other items still go through. The planning rule needs the TaskFlow API change #387 deployed, so do not publish or tag a release until it is live on your API.
• Your local UTC offset is sent with writes, because the API's "past day" rules depend on it.
• API errors (code + message, validation lists) are returned to Claude as tool errors so it can recover. Server 5xx errors are summarized without leaking stack traces.
• The API has no filtering or paging, so views, paging and aggregation happen in the server. Results are compact by default to stay under Claude Code's MCP output limits (warning at 10k tokens, cap 25k).

Develop

dotnet test TaskFlow.Assistant.sln
dotnet format TaskFlow.Assistant.sln --verify-no-changes
claude plugin validate ./plugin
claude plugin validate .                      # the marketplace
claude --plugin-dir ./plugin                  # try it for one session without installing

Tests stub the HTTP layer; a reflection test also guards the tool surface (exact tool set, every tool and parameter described, read-only/destructive flags).

Building features with feature-factory

Open Claude Code in this repo (on main it creates a feature/ branch for you; otherwise use a feature/ or bugfix/ branch) and ask it to build a feature, or run /feature-factory <issue-number>. It walks the issue through research, story, brief (with documentation advisor input), build, verification and a PR, with three approval stops (story, brief, final review). A story groomed with /groom-issue skips the story stop. An issue that explicitly says it is blocked by, or depends on, an unfinished issue or PR in another repo (for example a TaskFlow API change) stops the run until you say "proceed anyway".

It needs the user-level agents story-writer, codebase-researcher and spec-writer in ~/.claude/agents/. The skill is .claude/skills/feature-factory/SKILL.md and its agents are in .claude/agents/.

Known issues

• Subagents cannot ask questions mid-run, so the agent proposes and reports rather than confirming; the interactive confirm-then-write flows live in the skills.

Sources

Built from the official docs, checked 2026-10-09 against Claude Code 2.1.292:

• Plugins: https://code.claude.com/docs/en/plugins, manifest reference, create, loading, create a marketplace
• Subagents, Skills, MCP
• Claude Desktop Chat: Connect to local MCP servers, MCPB (not used: a config-file entry was chosen over a one-click extension), plugin support by surface, Using Skills in Claude
• MCP C# SDK: https://github.com/modelcontextprotocol/csharp-sdk (ModelContextProtocol 2.2.0; docs/concepts)
• Tool design: Anthropic, Writing tools for agents

Deliberate choices and deviations:

• Skills use disable-model-invocation: true: they write data, and keeping them out of Claude's context until invoked keeps the plugin's always-on cost small (~360 tokens, per claude plugin details).
• Plugin-bundled MCP tools are named mcp__plugin_taskflow-assistant_taskflow__<tool> (verified); the agent and skills use that form. The agent's tools uses the server-level name.
• Only McpException messages reach the model (the SDK replaces other exceptions with a generic message), so every API failure is translated to one.