@kmgeon/taskflow 0.1.3

package/README.md

@@ -0,0 +1,374 @@
+<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.

package/bin/task-mcp.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const entry = resolve(root, "src/mcp/index.ts");
+const tsx = resolve(root, "node_modules/.bin/tsx");
+
+const child = spawn(tsx, [entry], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+
+child.on("exit", (code) => {
+  process.exit(code ?? 0);
+});

package/bin/task.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const entry = resolve(root, "src/cli/index.ts");
+const tsx = resolve(root, "node_modules/.bin/tsx");
+
+try {
+  execFileSync(tsx, [entry, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+} catch (error) {
+  process.exitCode = error.status ?? 1;
+}

package/docs/clean-code.md

@@ -0,0 +1,29 @@
+# Clean Code Guidelines
+
+## Principles
+- **Single Responsibility**: One function/module = one job
+- **DRY**: Extract only when duplicated 3+ times. Premature abstraction is worse than duplication
+- **KISS**: Simplest solution that works. No over-engineering
+- **YAGNI**: Don't build what you don't need yet
+
+## Functions
+- Max 20 lines per function (guideline, not hard rule)
+- Max 3 parameters. Use an options object for more
+- Name functions with verbs: `createTask`, `parseMarkdown`, `validateInput`
+- Early return over nested conditionals
+
+## Error Handling
+- Use custom error classes per domain (`TaskNotFoundError`, `ValidationError`)
+- Let errors bubble up — catch only at boundaries (API routes, CLI commands)
+- Never swallow errors silently
+
+## Types
+- Prefer `type` over `interface` for consistency (unless extending)
+- Use Zod schemas as single source of truth; derive types with `z.infer<>`
+- Avoid `any` — use `unknown` and narrow
+
+## Code Smells to Avoid
+- God files (>300 lines) — split by responsibility
+- Boolean parameters — use named options or separate functions
+- Magic strings/numbers — use constants or enums
+- Commented-out code — delete it, git has history

package/docs/git.md

@@ -0,0 +1,36 @@
+# Git Conventions
+
+## Branch Naming
+```
+feat/{description}      # New feature
+fix/{description}       # Bug fix
+refactor/{description}  # Refactoring
+docs/{description}      # Documentation
+chore/{description}     # Maintenance
+```
+
+## Commit Messages
+Follow Conventional Commits:
+```
+type(scope): description
+
+feat(kanban): add drag-and-drop task reordering
+fix(cli): handle missing config file gracefully
+refactor(core): extract task validation logic
+test(prd): add parser edge case coverage
+```
+
+### Types
+- `feat` — new feature
+- `fix` — bug fix
+- `refactor` — code restructuring (no behavior change)
+- `test` — adding/updating tests
+- `docs` — documentation only
+- `chore` — build, deps, config changes
+- `style` — formatting (no logic change)
+
+## Rules
+- Commit small, atomic changes
+- Never commit secrets, `.env` files, or credentials
+- Keep commits buildable — don't break the build mid-branch
+- Squash WIP commits before PR

package/docs/guideline.md

@@ -0,0 +1,25 @@
+# Project Guideline
+
+## Naming Conventions
+- **Files**: kebab-case (`parse-prd-flow.ts`)
+- **Components**: PascalCase (`TaskCard.tsx`)
+- **Functions/Variables**: camelCase
+- **Types/Interfaces**: PascalCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Test files**: `*.test.ts` or `__tests__/*.test.ts` (co-located)
+
+## Import Conventions
+- Use path alias (`@/*` etc.) when available — avoid deep relative paths
+- Group imports: external → internal → relative
+- No circular imports between modules/features
+
+## Module Structure
+- Keep modules self-contained: co-locate related code (logic, types, tests)
+- Separate concerns by layer (API, UI, business logic)
+- Shared code belongs in `lib/` or `utils/` — not inside a feature module
+
+## General Principles
+- Prefer composition over inheritance
+- Keep public API surface small — export only what's needed
+- Avoid god files (>300 lines) — split by responsibility
+- Configuration and constants belong in dedicated files, not scattered inline

package/docs/security.md

@@ -0,0 +1,32 @@
+# Security Guidelines
+
+## Authentication & Authorization
+- All API routes must verify authentication
+- Validate user session on every request — never trust client-side auth state
+- Use row-level or resource-level access control for data isolation
+
+## Input Validation
+- Validate ALL external input with schemas at the boundary
+- Never trust query params, request bodies, or URL params directly
+- Sanitize user-generated content before rendering (XSS prevention)
+
+## Secrets Management
+- Store secrets in environment variables only
+- Never commit `.env`, API keys, or credentials
+- Use `.env.local` for local development (ensure it's in `.gitignore`)
+
+## API Security
+- Use parameterized queries — never concatenate user input into queries
+- Rate limit public endpoints
+- Return generic error messages to clients — log details server-side
+
+## Dependencies
+- Keep dependencies up to date
+- Review new dependencies before adding (check maintenance, size, security)
+- Run security audits periodically
+
+## What to Never Do
+- Expose internal error stacks to clients
+- Store passwords in plain text
+- Use `eval()` or dynamic code execution with user input
+- Disable strict type checks for convenience

package/docs/step-by-step.md

@@ -0,0 +1,29 @@
+# Step-by-Step Development Workflow
+
+## Before Writing Code
+1. **Understand the requirement** — Read the task/PRD thoroughly
+2. **Check existing code** — Search for related implementations before creating new ones
+3. **Plan the approach** — Identify which files to modify and what tests to write
+
+## Implementation Flow
+1. **Write the test** — Define expected behavior first
+2. **Write minimal code** — Just enough to pass the test
+3. **Refactor** — Clean up while tests stay green
+4. **Verify** — Run full test suite (`npm run test`)
+5. **Type check** — Run `npm run typecheck`
+6. **Lint** — Run `npm run lint`
+
+## PR Checklist
+- [ ] Tests pass (`npm run test`)
+- [ ] Type check passes (`npm run typecheck`)
+- [ ] No lint errors (`npm run lint`)
+- [ ] New code has test coverage
+- [ ] Commit messages follow conventions
+- [ ] No secrets or .env files committed
+
+## Debugging
+1. Read the error message carefully
+2. Reproduce the issue with a test
+3. Identify root cause (don't just patch symptoms)
+4. Fix and verify the test passes
+5. Check for similar issues elsewhere