TaskFlow

Two commands. Idea to code.

Document-driven vibe coding.

Concepts · Getting Started · How It Works · CLI Reference · Skills · Architecture

/t-create    # Tell AI what to build
task run     # AI builds it

That's it.

Philosophy

Write docs, not code.

You describe what you want. AI brainstorms with you, writes the spec, and implements everything. Your job is to think and approve — not to type boilerplate.

Three principles:

1. Document-first — Every feature starts as a TRD (Task Requirements Document). No code is written until the spec is approved. Decisions are captured in markdown, not lost in Slack threads or your head.

2. Automated execution — Once a spec is approved, AI decomposes it into tasks and implements them one by one. You don't manage tickets. You don't assign priorities. The system handles it.

3. File-based, Git-native — No database. No cloud dependency. Everything is markdown files in .taskflow/, versioned with Git. Fork it, diff it, review it — it's just text.

Your idea → TRD (markdown) → Tasks (markdown) → Code (automated)

Concepts

TaskFlow is built around four core concepts. Understanding them makes the entire system click.

PRD — Product Requirements Document

What you're building, for whom, and why.

PRD is the highest-level document. It captures the full product vision: target users, pain points, feature list, success metrics, and scope boundaries. Think of it as the "what and why" document.

# MyApp — PRD
## Target Users
## Problems & Solutions
## Feature Requirements (Must-Have / Nice-to-Have)
## Non-functional Requirements
## Milestones

In TaskFlow, PRDs are created interactively with the /prd skill and stored in .taskflow/prd.md. A PRD can span multiple features — it's the big picture.

TRD — Task Requirements Document

How to build a specific feature.

A TRD zooms into one feature from the PRD (or a standalone idea) and defines the technical approach. It includes architecture decisions, data models, API design, user scenarios, success criteria, and risks.

The key difference: PRD says "we need authentication." TRD says "we'll use Supabase Auth with JWT, refresh tokens stored in httpOnly cookies, middleware on /api/ routes."*

# Auth System — TRD
## Overview (chosen approach + rationale)
## User Scenarios
## Technical Design (architecture, data model, API, UI)
## Dependencies
## Success Criteria
## Risks

TRDs are created with the /t-create skill — which includes a brainstorming phase where AI proposes 2-3 approaches before writing. Each TRD is saved as .taskflow/trd-{feature-name}.md.

One TRD = one feature = one unit of work for task run.

Task — Implementation Unit

A single, concrete piece of work that can be completed in under 4 hours.

Tasks are auto-generated by task run when it decomposes a TRD. Each task has a title, description, priority, dependencies, and status. You don't create tasks manually — the system handles it.

# .taskflow/tasks/task-003.md
---
id: '003'
title: Implement auth middleware
status: InProgress
priority: 9
group: auth system
dependencies:
  - '001'
  - '002'
---
Create Express middleware that validates JWT tokens on /api/* routes...

Task statuses: Todo → InProgress → Done (or Blocked)

Decompose — TRD to Tasks

The process of breaking a TRD into implementation tasks.

Decomposition happens automatically when you run task run. The AI reads your TRD and creates tasks that are:

• Small — each completable in under 4 hours
• Ordered — dependencies are explicit, implementation order is logical
• Isolated — each task has one clear purpose, testable independently
• Grouped — all tasks from one TRD share the same group name

TRD: Auth System
    │
    ├── task-001: Set up Supabase Auth client        (priority: 9)
    ├── task-002: Create login/signup API routes      (priority: 9, depends: 001)
    ├── task-003: Implement auth middleware           (priority: 9, depends: 001, 002)
    ├── task-004: Add refresh token rotation          (priority: 7, depends: 003)
    └── task-005: Write auth integration tests        (priority: 8, depends: 003)

After decomposition, Ralph Loop implements each task sequentially — writing code, running tests, updating status — until the entire feature is done.

Getting Started

Installation

npm install @kmgeon/taskflow

Project Setup

task init

This single command configures everything:

• .taskflow/ — Project data (TRDs, tasks, config)
• .claude/commands/ — Claude Code skills (symlinked for easy updates)
• .claude/settings.local.json — Plugins (superpowers, ralph-loop)
• .mcp.json — MCP server for task management tools
• CLAUDE.md — Project-level AI instructions
• docs/ — Development guidelines (clean code, TDD, security, etc.)

Skills are installed as symlinks from .claude/commands/ → .taskflow/.claude/commands/. This means:

• task init can update skill templates without overwriting your customizations
• You can edit skills in .taskflow/.claude/commands/ and they're instantly available
• Everything stays in version control

First Feature

# In Claude Code
/t-create

# In terminal
task run

How It Works

Step 1: /t-create — Define what to build

Run /t-create in Claude Code. The AI will guide you through a structured brainstorming process:

$ /t-create

? What do you want to build?
> User authentication with JWT and refresh tokens

? Who uses this feature?
  A. End users (login/logout)
  B. Admin users (user management)
  C. Both
> C

? Any technical constraints?
> Must work with existing Supabase setup

💡 Three approaches:

  A. (Recommended) Supabase Auth native — leverage built-in auth
     + Zero custom code for core auth
     - Limited customization

  B. Custom JWT + Supabase as DB only
     + Full control
     - More code to maintain

  C. NextAuth.js wrapper
     + Large ecosystem
     - Extra dependency

? Which approach: A

📝 Writing TRD section by section...
   ✔ Overview — approved
   ✔ User Scenarios — approved
   ✔ Technical Design — approved
   ✔ Success Criteria — approved

✅ TRD saved: .taskflow/trd-auth-system.md

The result is a detailed, approved spec — not a vague ticket.

Step 2: task run — Build it automatically

$ task run

📋 TRD list:

  1. auth system       (trd-auth-system.md)
  2. notification      (trd-notification.md)

? Select TRD to implement: 1

🚀 "auth system" — auto-implementation started.
✔ Ralph Loop configured.

  Next: Open Claude Code. The loop will begin automatically.
  Stop: /ralph-loop:cancel-ralph

Ralph Loop takes over:

1. Reads your TRD
2. Decomposes it into implementation tasks (via MCP create_task)
3. Picks the first task, sets status to InProgress, implements it
4. Marks it Done, picks the next one
5. Repeats until all tasks are complete

You can watch the progress:

$ task list

📋 Feature progress:

  ██████░░░░  auth system       60%  3/5 · 1 in progress
  ░░░░░░░░░░  notification       0%  0/3
  ██████████  onboarding       100%  done

CLI Reference

Core Workflow

| Command | Description | |:-------------|:-----------------------------------------------------------| | task init | Initialize project — installs skills, plugins, MCP config | | task run | Select a TRD and auto-implement all tasks via Ralph Loop |

Monitoring

| Command | Description | |:----------------------------|:---------------------------------------| | task list | Feature progress by group | | task list --detail | All individual tasks | | task list --detail <name> | Tasks for a specific feature group | | task board | Kanban board grouped by feature | | task board --detail | Full kanban with all tasks | | task tree | Dependency tree grouped by feature | | task tree --detail | Full dependency tree |

Task Management

| Command | Description | |:---------------------------------|:-------------------------| | task show <id> | View task details | | task set-status <id> <status> | Change task status |

Utilities

| Command | Description | |:----------------|:-----------------------------| | task ask | Ask AI about your project | | task advisor | Manage AI advisor database |

Skills

Skills are Claude Code slash commands that run inside your editor. Installed automatically by task init.

| Skill | Purpose | |:--------------|:-----------------------------------------| | /t-create | Brainstorm requirements → write TRD spec | | /prd | Interactive PRD (Product Requirements) | | /trd | Technical implementation plan from PRD |

Skills live in .taskflow/.claude/commands/ and are symlinked to .claude/commands/ so Claude Code can discover them. You can customize any skill by editing the markdown file directly.

Architecture

File Structure

.taskflow/
├── config.json                 # Project settings
├── trd-auth-system.md          # TRD specs (one per feature)
├── trd-notification.md
├── tasks/
│   ├── task-001.md             # Individual tasks (auto-generated)
│   ├── task-002.md
│   └── ...
├── .claude/
│   └── commands/
│       ├── t-create.md         # Skill: brainstorm + TRD
│       ├── prd.md              # Skill: PRD creation
│       └── trd.md              # Skill: technical plan
└── index/
    └── TASKS.md                # Auto-generated task index

.claude/
├── commands/                   # Symlinks → .taskflow/.claude/commands/
│   ├── t-create.md → ../../.taskflow/.claude/commands/t-create.md
│   └── ...
└── settings.local.json         # Plugins: superpowers, ralph-loop

.mcp.json                       # MCP server config (TaskFlow tools)
CLAUDE.md                       # Project instructions for AI

Data Flow

/t-create (Claude Code skill)
    │
    │  writes
    ▼
.taskflow/trd-*.md (spec)
    │
    │  task run reads
    ▼
Ralph Loop (auto-implementation)
    │
    │  creates via MCP
    ▼
.taskflow/tasks/task-*.md (tasks)
    │
    │  implements & updates status
    ▼
Working code

Plugin Integration

TaskFlow configures two Claude Code plugins at the project level:

• superpowers — Brainstorming, systematic debugging, TDD, code review workflows
• ralph-loop — Autonomous loop that repeats a prompt until completion

These are set in .claude/settings.local.json — project-scoped, not global.