Local Markdown. Explicit approvals. Recoverable design history.
Get started · Why TaskFlow · Compare tools · Verification · 中文
Important
TaskFlow is a workflow convention, not an Agent. It does not select tools or take decisions itself. It may coordinate with host/harness hooks (Claude Code, Codex CLI, CodeBuddy, and dsh) for bounded bookkeeping and context summaries; hooks never write core documents and never approve. It gives humans and Agents a shared, inspectable place to record what a task means and how it changed.
When an Agent ships code, the code is visible. The decisions that made it safe are often not.
|
|
TaskFlowDocs/YYYY-MM-DD-short-slug/
├── prd.md # what / why / scope / acceptance
├── spec.md # how / contracts / trade-offs (large tasks only)
├── plan.md # approval / steps / verification / rollback
├── sessions.md # handoff and resume context (optional)
├── reference/ # evidence and research (optional)
└── old/vN/ # superseded logical versions (optional)
TaskFlow deliberately uses plain files. A human can read them, an Agent can load them, Git can diff them, and your project does not need another service to keep its task history.
TaskFlowDocs/repository-docs/index.md is the authoritative routing and check record for repository rules, repository guidance, and scoped personal rules. Repository-owned documents stay authoritative at their conventional source locations.
At SessionStart, TaskFlow deterministically refreshes index metadata for recognized documents and injects phase-applicable paths/status. The Agent reads the index first, follows its routes to authoritative sources, and records incorporated conclusions in the task Plan. The hook never copies policy text, edits source rules or core task documents, approves work, or mutates Git/hosting state.
Repository documents are authoritative. For non-trivial development, if CONTRIBUTING.md or CODE_STYLE.md is missing, TaskFlow derives the smallest evidence-based draft from the repository and asks up to three dependency-ordered questions for undecidable policy, then requires explicit user approval before the document becomes binding. ROADMAP.md is drafted only after the user confirms product direction; other governance documents are created only when the task needs them. Personal rules live directly in repository-docs/ and are limited to stricter or orthogonal personal habits and cannot replace, weaken, or conflict with repository guidance. They are local-only and stay out of Git; anything that must be shared becomes a repository-owned document. A material applicable-document change follows the same version gate as any other task-contract change.
For fork, remote, or pull-request work, TaskFlow records the configured remotes, intended target repository, base branch, local branch relationship, freshness limits, applicable host rules, and pre-PR checks. Remote names are not proof of role, and TaskFlow never silently adds or rewrites remotes, fetches, rebases, merges, pushes, opens PRs, or claims synchronization.
TaskFlow never writes a task document in the base working tree: each task runs on its own short-lived branch and its own working tree, created before the first task document rather than before the first edit. CONTRIBUTING.md states the branch rule; the Skill states the worktree rule.
Because every task appends to the one TaskFlowDocs/todo.md, TaskFlow ships a Git merge driver for it, installed per clone by hooks/session-start. Two branches that each added an entry, or that changed different entries, merge without a human; the same entry changed differently on both sides is still left as a real conflict. Todo IDs are derived from the goal rather than from a counter, so two branches cut from the same base cannot allocate the same ID. Merging a pull request in a hosting web UI runs server-side and does not use the driver, so that path falls back to an ordinary content conflict.
Before creating or updating a pull request, TaskFlow reads the applicable .github/pull_request_template.md, satisfies every required item, records the field mapping and verification in plan.md, and blocks PR mutation when a required item is missing or ambiguous.
Run bash hooks/repository-check [repo-root] for an opt-in, read-only readiness summary. It reports missing baseline governance and ambiguous branch/remote information as needs-user-input, and names any task artifact left uncommitted in the checkout — an uncommitted task directory follows you to whatever branch you check out next, so the next task inherits it. The task-artifact report never changes the exit code; it is not attached to automatic hooks. bash hooks/release-check [repo-root] is the same kind of report for a release: it compares the version literals in all four plugin manifests, the newest CHANGELOG.md section, and each README's claude plugin list sample, and confirms each marketplace ref resolves to the commit its sha names. It exits 2 on a mismatch and 3 when a manifest is missing; CI runs it on every change.
Any user correction or addition to an approved task is classified before documents change: wording or approach clarifications are work revisions that update only affected records and the Plan change log; changes to an approved goal, requirement, acceptance criterion, scope, or contract create a Task version and return to approval. TaskFlow never continues implementation using an outdated plan.
TaskFlow applies automatically only to repository development requests: features, fixes, refactors, tests, and configuration/build/CI changes. A release is the exception — it runs RELEASE.md directly on the base checkout, with no Todo item, task directory, branch, or PRD/Plan, and its record is the CHANGELOG.md section and the GitHub Release body. Read-only explanation, translation, status, research, review, and diagnosis do not create Todo or task documents; a later implementation request starts the workflow then. Explicitly invoking $taskflow opts planning or research into the workflow. For applicable requests, TaskFlowDocs/todo.md is the mandatory first record. An item moves from inbox to clarified, then is promoted into a task directory with prd.md, optional spec.md, and plan.md; it enters in_progress after approval and closes as done or cancelled.
After verification, TaskFlow moves the whole task directory to TaskFlowDocs/achieved/<task-id>/, updates the Todo item's task path and status to done, and verifies the active path is absent. If later work belongs to that achieved deliverable, it retrieves the directory to the active root, records the Todo source and reopen reason, creates a new Task version, and returns to approval before changing implementation. Achieved tasks are read-only; their old/vN/ history is read only when the current documents or a version summary require it.
Why not just rely on Git?
Git is excellent at mechanical history. TaskFlow adds semantic history: a task version changes only when an approved goal, requirement, acceptance criterion, scope, architecture/interface/data contract, compatibility decision, risk decision, or standard changes; wording or implementation-approach clarifications are work revisions that stay on the current version. The archived version answers what the previous proposal meant, not merely which lines changed.
| TaskFlow adds | TaskFlow deliberately avoids |
|---|---|
A shared clarify → approve → implement → verify → archive protocol |
Being an Agent or a task manager; proxies, daemons, or API gateways |
| Project-local Markdown as task facts | Hidden state in a hosted database or proprietary UI |
| Explicit state, approval, handoff, rollback, and recovery records | Replacing your editor, Git host, test runner, or other Skills |
| A semantic version boundary for material decisions | Forcing an Agent model, programming language, framework, or toolchain |
Before substantive work in any phase, the Agent inspects the Skills, tools, MCP servers, and Agents currently available in the host and freely decides whether any materially help. TaskFlow names its own artifacts, so a phase is matched to a capability by the concept class its artifact corresponds to, not by that artifact's TaskFlow name. TaskFlow requires no particular capability, provider, chain, category, or count. A capability selected for use is actually invoked or loaded through the host before its workflow or output is used; discovery or selection alone is not invocation. Outputs are reviewed before incorporation, and plan.md records only actual invocation attempts and their outcomes.
TaskFlow may also coordinate with host/harness hooks (Claude Code, Codex CLI, CodeBuddy, and dsh) for mechanical bookkeeping and cheap resume context. A hook may update Todo triage metadata and inject a derived session-start summary; it never creates, rewrites, or deletes prd.md/spec.md/plan.md/reference/index.md, and never approves. Single-command archive/version/reopen helpers consolidate transitions. Hosts without hooks run the same flow unchanged.
ordinary edit material decision change
───────────── ────────────────────────
keep current vN archive vN → create vN+1 → return to ready → approve
| This is a work revision | This creates a Task version |
|---|---|
| Wording, approach clarification within the approved design, typo, progress, test result | Goal, requirement, acceptance criterion, scope, architecture/interface/data contract, compatibility, risk, standard |
| Update current files + one Plan change-log line | Preserve the old version under old/vN/, then update current files |
| Git shows the edit | Git plus TaskFlow explain the decision |
TaskFlowDocs/2026-09-05-billing-export/
├── prd.md # current v2: CSV export added
├── spec.md # current v2 design
├── plan.md # v2 approval + verification
+ └── old/v1/
+ ├── version.md # why v1 was superseded
+ └── snapshot/ # v1 PRD / Spec / Plan recovery pointSomeone changes the export requirement midway through implementation. Instead of rewriting the only design document, TaskFlow preserves v1, records why v2 exists, and requires a new approval before implementation continues.
stateDiagram-v2
[*] --> planning
planning --> ready: PRD / Spec / Plan complete
ready --> in_progress: explicit approval
in_progress --> checking: implementation complete
checking --> completed: acceptance passes
planning --> blocked
in_progress --> blocked
blocked --> planning: input or condition resolved
in_progress --> ready: material change / new version
completed --> [*]
| State | Meaning |
|---|---|
planning |
Requirements, evidence, or design are being clarified. |
ready |
The current task documents are complete and waiting for approval. |
in_progress |
The approved plan is being implemented. |
checking |
Acceptance and quality checks are running. |
completed |
Verification passed; archive as read-only history. |
blocked |
A specific blocker is recorded with the required next input. |
TaskFlow ships as a Claude Code / Codex / CodeBuddy / dsh plugin: the hooks/, skill, and install wiring are all in one marketplace. No copying files or editing settings.json by hand.
Add the TaskFlow marketplace, then install the plugin:
claude plugin marketplace add hkwuks/TaskFlow
claude plugin install taskflow@taskflowThe marketplace catalog follows main, but its stable plugin entry is pinned to the published release tag and commit SHA. Refreshing the catalog therefore discovers a reviewed release instead of installing unreleased changes from main.
Tip
In-session, the same two steps are /plugin marketplace add hkwuks/TaskFlow then /plugin install taskflow@taskflow.
Verify it loaded:
claude plugin list
# taskflow@taskflow Version: 1.0.9 Status: ✔ enabledTo update an existing installation:
claude plugin marketplace update taskflow
claude plugin update taskflow@taskflow
claude plugin listAdd the same marketplace, then install the plugin:
codex plugin marketplace add hkwuks/TaskFlow
codex plugin add taskflow@taskflowCodex uses the same fixed release entry as Claude Code. The manifest version, Git tag, and pinned commit identify the installed stable build.
Verify it loaded:
codex plugin list
# taskflow@taskflow installed, enabledTo update an existing installation:
codex plugin marketplace upgrade
codex plugin add taskflow@taskflow
codex plugin listAdd the same marketplace, then install the plugin. These are CodeBuddy Code CLI commands — the CodeBuddy IDE client does not implement them:
codebuddy plugin marketplace add hkwuks/TaskFlow
codebuddy plugin install taskflow@taskflowCodeBuddy reads the catalog at .codebuddy-plugin/marketplace.json, which carries the same fixed release pin as the other hosts. The manifest wires the SessionStart hook through the CODEBUDDY_PLUGIN_ROOT variable its own bundled plugins use.
Verify it loaded:
codebuddy plugin list
# > taskflow@taskflow
# Version: 1.0.9
# Scope: user
# Status: enabledTo update an existing installation:
codebuddy plugin marketplace update taskflow
codebuddy plugin install taskflow@taskflow
codebuddy plugin listCodeBuddy reloads hooks, skills, and agents on /reload-plugins without a restart.
TaskFlow's repository root is a dsh plugin package, so the profile it is installed into picks it up as a bundle layer:
dsh plugin --profile web add dsh-taskflowInstalled from a checkout instead of the registry, point at the directory:
dsh plugin --profile web add <repo-root>The package declares dsh.bundle.patch, so dsh appends it to the profile's
dsh.profile.bundles itself — there is no profile YAML to write. Booting that
profile then mounts TaskFlow's skill and its SessionStart hook.
dsh wires the same hooks/session-start script the other hosts run, through
hooks/hooks-dsh.json and dsh's own Claude Code hook bridge. Two things about the
bridge shape the wiring, and both are visible in that file: taskflow's hook is
reached through dsh's interception seams rather than a plugin manifest, and the
command carries a CLAUDE_PLUGIN_ROOT prefix because the bridge substitutes that
variable inside the command string but does not export it — session-start picks
its output shape from the environment.
dsh's SessionStart sources are startup, resume, clear, and compact; there
is no fork, so the dsh matcher omits it.
dsh has no plugin marketplace, and dsh plugin add resolves through pnpm, so a
release is picked up with dsh plugin --profile web update.
For development or source inspection, point the marketplace at your checked-out copy instead of GitHub. This intentionally bypasses the stable remote pin, and the plugin and hooks then come from files you control:
# Claude Code
claude plugin marketplace add <repo-root>
claude plugin install taskflow@taskflow
# Codex CLI
codex plugin marketplace add <repo-root>
codex plugin add taskflow@taskflow
# CodeBuddy
codebuddy plugin marketplace add <repo-root>
codebuddy plugin install taskflow@taskflow
# dsh (no marketplace: the directory is the package)
dsh plugin --profile web add <repo-root>Once installed, tell your Agent:
Use $taskflow to plan, execute, verify, and archive this task.
Then: add ideas to TaskFlowDocs/todo.md; promote clarified items into prd.md, spec.md (when needed), and plan.md; review the task documents, record approval, then implement one planned step at a time using its checklist.
Tip
A small, obvious one-file change can still be a direct change with minimal verification. TaskFlow does not create documents merely to satisfy a process.
Note
Hooks are optional. The plugin installs a SessionStart hook that injects a short derived state summary (inbox items + active tasks) and the repository-document routes for the current phase, so the Agent does not re-read the whole tree. It never creates, rewrites, or deletes prd.md/spec.md/plan.md/reference/index.md, and never approves; the only files it writes are the selected task's sessions.md session index and the deterministic routing metadata in TaskFlowDocs/repository-docs/index.md. Hosts without hooks run the exact same flow.
For mechanical lifecycle edits, the Agent can explicitly run hooks/run-hook.cmd task intake|promote|state|progress|complete; these write commands are not event-bound hooks.
Every check is a plain script at the repository root — no service, no test framework, no language runtime except where the tooling needs one:
| Command | What it checks |
|---|---|
bash hooks/smoke-test |
Builds temporary TaskFlowDocs fixtures and drives the full lifecycle through the hooks. hooks/smoke-test-windows.ps1 is the Windows equivalent over PowerShell 5.1 and run-hook.cmd. |
bash hooks/repository-check . |
Read-only repository readiness: missing baseline governance and ambiguous branch/remote information, reported as needs-user-input. |
bash hooks/release-check . |
Every version literal a release has to move agrees, and each marketplace pin resolves to the commit its sha names. Exits 2 on a mismatch, 3 on a missing manifest. |
python3 evals/runner.py |
Offline routing evals against immutable sample task trees. The runner is repository tooling, so it is the one thing here that does need Python. |
.github/workflows/hooks.yml runs four jobs on every push to main and every pull request: smoke on an Ubuntu / macOS / Windows matrix, release, todo-merge-audit (no merge in the pushed range dropped a Todo entry), and evals. The smoke job deliberately installs no language runtime — the hooks carry none, so a hook that ever grew an interpreter dependency fails there rather than in a user's session.
CONTRIBUTING.md lists the checks required before a pull request, including hooks/smoke-test, the Skill validator, and git diff --check. RELEASE.md is the release checklist: the version literals a release must move, the two-commit ordering a release tag and its catalog pin have to follow, and the rollback rules. It runs on the base checkout rather than as a TaskFlow task.
The hooks themselves are documented in hooks/README.md — what each one may write, why they are extensionless bash with no language runtime, and the per-host wiring.
TaskFlow is not trying to replace specification-driven development, role-based multi-agent methods, or project management. It covers a specific missing layer: durable task facts, state boundaries, and recoverable decision history inside the repository.
| TaskFlow | Spec Kit | OpenSpec | BMAD-METHOD | Issue tracker / PM tool | |
|---|---|---|---|---|---|
| Primary concern | Task state and semantic history | Spec-driven workflow | Configurable spec/change workflow | Role-based Agent methodology | Ownership and coordination |
| Core unit | Local TaskFlowDocs directory | Specs and workflow artifacts | Specs and changes | Agents, roles, workflows | Tickets, cards, issues |
| Design recovery | Explicit old/vN/ archive |
Adoption/repository dependent | Project/Git practice dependent | Workflow/repository dependent | Usually activity history only |
| Agent interaction | Skill instructions + bounded host-hook coordination (Claude Code, Codex, CodeBuddy, dsh) | Tool/workflow conventions | Configurable workflow conventions | Role and orchestration patterns | Usually outside Agent context |
| Infrastructure | Markdown + filesystem + Git | Adopted repository tooling | Adopted repository tooling | Method assets + adopted tooling | Usually a hosted service |
| Use it with TaskFlow? | — | Generate specs, then route reviewed task facts into TaskFlow | Route reviewed specs/changes into TaskFlow | Keep role outputs as reviewed task references | Link a ticket to its task directory |
| Choose TaskFlow | You lose task context, overwrite designs, or struggle to resume work across sessions and Agents. |
| Choose Spec Kit / OpenSpec | You primarily need a broad or configurable spec-driven development workflow. |
| Choose BMAD-METHOD | You need a role-based multi-Agent delivery methodology. |
| Choose an issue tracker | You need prioritization, ownership, deadlines, and reports. |
| Combine them | Use external tools to coordinate work; use TaskFlow to preserve the decisions that make it recoverable. |
Note
This is a positioning comparison, not a benchmark or a claim of feature parity. Check each project's current documentation before adoption.
| Principle | In practice |
|---|---|
| One task, one source of truth | Keep the active task facts in one task directory. |
| Lightest useful artifact | Omit spec.md for a small, self-contained task. |
| Archive before replace | Capture the old logical version before a material update. |
| Approval is explicit | ready never silently becomes in_progress. |
| Verification is a fact | Record what was checked and the result in plan.md. |
| Tools stay optional | Other Skills can contribute; reviewed task artifacts remain authoritative. |
skills/taskflow/ # the workflow itself
├── SKILL.md # workflow entry point
├── agents/openai.yaml # display metadata and default prompt
└── references/
├── artifacts.md # templates and output routing
├── runtime.md # hook rules and host event maps
└── versioning-and-recovery.md # semantic versions and safe restoration
hooks/ # optional host/harness hooks — see hooks/README.md
├── session-start # SessionStart entry point
├── session-record # records the host session id in sessions.md
├── summarize-state # derives the state summary (shared logic)
├── repository-docs-context # syncs index metadata and derives routes
├── install-merge-driver # configures the repo-local Todo merge driver
├── merge-todo # the driver: merges todo.md by entry
├── task / archive / version / reopen # explicit lifecycle commands
├── release-check / todo-check # release literals; dropped Todo entries
├── hooks{,-codex,-codebuddy,-dsh}.json # one wiring file per host
└── run-hook.cmd # cross-platform launcher
evals/ # offline routing evals (runner.py + cases/, fixtures/)
tools/fixture-compare # byte-compares two smoke-test fixture runs
.claude-plugin/ .codex-plugin/ .codebuddy-plugin/ # host manifests and catalogs
dsh/ + package.json # dsh bundle plugin: mounts the skill and the hooks
.github/workflows/hooks.yml # CI: smoke matrix, release, todo audit, evals
Distributed under AGPL-3.0.