Tasks Overview

Create, run, and manage tasks in Zenflow for AI-driven code changes.

What is a Task?

A task is a discrete unit of work that an AI agent executes within an isolated workspace. Tasks can range from quick fixes to full feature implementations, with workflows that adapt to scope and complexity.

Task isolation

Every task runs in its own Git worktree with a dedicated branch, ensuring parallel execution without conflicts.

Creating a Task

1. Describe the work

   Write a clear, outcome-focused description:

   "Add OAuth for Google and GitHub."
   "Fix checkout bug causing duplicate charges."
   "Refactor billing module to reduce duplication."
   

   Focus on what needs to happen, not implementation details.

2. Choose a workflow

   Select the workflow that matches your task’s scope:

   • Quick Change: Fast, minimal planning
   • Fix Bug: Investigation → solution → implementation
   • Spec and Build: Technical spec before coding
   • Full SDD: PRD → spec → staged implementation
3. Configure the workspace

   Choose the source branch and agent settings. Each task creates an isolated worktree at .zenflow/tasks/{task_id}.

4. Create or Create and Run

   Save the task for later or immediately start the agent.

Task States

Tasks move through these states:

State	Description
Draft	Created but not started
Running	Agent actively working
Paused	Waiting for human input or review
Review	Changes ready for review
Completed	Work merged or accepted
Archived	Task removed from active view

Task Actions

Run / Resume

Start or continue agent execution on the task.

Pause

Stop the agent and wait for human intervention.

Open in IDE

Launch your editor directly in the task’s worktree directory.

View Changes

See all file modifications made by the agent.

Commit

Save uncommitted changes (from manual edits) into the task branch.

Create PR

Push the branch and open a pull request on GitHub/GitLab.

Archive

Remove the task from active view and clean up the worktree.

Parallel Execution

Zenflow supports running multiple tasks simultaneously:

• Each task has its own worktree and branch
• Agents don’t interfere with each other
• You can start new tasks while others complete
• Disk space scales with active task count

Monitor your .zenflow/tasks/ directory size. Each worktree is a full copy of working files. Archive completed tasks regularly.

Task Artifacts

Depending on the workflow, tasks generate artifacts in .zenflow/tasks/{task_id}:

• plan.md - Execution steps and progress
• spec.md - Technical specification
• investigation.md - Bug analysis (Fix Bug workflow)
• solution.md - Proposed fix (Fix Bug workflow)
• requirements.md - PRD (Full SDD workflow)

Next Steps

Git Worktrees

Understanding task isolation

Tracking Changes

Monitor and review agent modifications

Blast Agents

Run multiple agents in parallel

Archiving

Clean up completed tasks