npm package: @kmgeon/taskflow
Description: <div align="center">
Latest version: 0.1.4

<div align="center">

# TaskFlow

### Two commands. Idea to code.

**Document-driven vibe coding.**

[Concepts](#concepts) · [Getting Started](#getting-started) · [How It Works](#how-it-works) · [CLI Reference](#cli-reference) · [Skills](#skills) · [Architecture](#architecture)

</div>

---

```bash
/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.

```markdown
# 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."**

```markdown
# 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.

```yaml
# .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

```bash
npm install @kmgeon/taskflow
```

### Project Setup

```bash
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](https://github.com/anthropics/claude-code), [ralph-loop](https://github.com/anthropics/claude-code))
- `.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

```bash
# 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](https://github.com/anthropics/claude-code)** — Brainstorming, systematic debugging, TDD, code review workflows
- **[ralph-loop](https://github.com/anthropics/claude-code)** — Autonomous loop that repeats a prompt until completion

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