taskpile — AI-native project tracking

A central hub that aggregates markdown-based tickets across many projects so AI coding tools (Claude Code, Cursor, Windsurf, …) can read and edit them natively while you still get a Jira-style cross-project view.

Tickets live as .md files inside each project's repo. The hub is a thin layer over Backlog.md that adds aggregation, capability discovery, recipes, routines, and AI-context auto-loading.

Why

If you run lots of AI-driven side projects, you've probably hit this:

• Trello/Jira/Notion + AI = LLM tax. Every ticket lookup is an API call, OAuth, summarization round-trip.
• Plain markdown TODOs = no cross-project view, no kanban, decisions evaporate.
• Building a custom ticket system = you don't want to.

So: keep tickets as markdown files in each repo (so the LLM working on the code reads/edits them natively), and add a tiny hub for the cross-project view + AI conventions.

Read docs/PHILOSOPHY.md for the full bet.

What you get

• Tickets as markdown in each project (powered by Backlog.md, MIT, ~5.5k★).
• Cross-project hub — taskpile sync walks all tracked projects, builds a unified index.
• AI auto-loads context — every Claude Code session in a tracked project starts with @backlog/CURRENT, @backlog/INDEX.md, @.claude/CAPABILITIES.md already in context. Refreshed via SessionStart hook.
• Milestones — group tickets into v1/v2/v3, see release progress per project + globally.
• Recipes — recurring task templates (taskpile recur run weekly-scenario).
• Routines — pattern for cron-driven autonomous AI work (uses Claude Code's /schedule skill — no scheduler built).
• Confluence-like docs — backlog/docs/ (architecture notes) + backlog/decisions/ (ADRs), surfaced in INDEX.
• Capability discovery — auto-generated CAPABILITIES.md per project tells the LLM exactly which skills, commands, MCP servers, and workflows are available there.

Install

Requires Node 18+, Backlog.md, and Claude Code.

git clone https://github.com/<you>/taskpile.git
cd taskpile
npm install
npm i -g backlog.md
chmod +x bin/taskpile bin/taskpile-*
# Optional: alias for ergonomics
echo 'alias taskpile="node /absolute/path/to/taskpile/bin/taskpile"' >> ~/.zshrc

Quickstart

1. Onboard your first project

taskpile init /path/to/your-project --slug=myproj --name="My Project" --tags=python,llm

This:

• Runs backlog init (if needed) — creates <project>/backlog/ w/ Backlog.md scaffolding.
• Registers the project in projects.yml.
• Adds the Backlog.md MCP server to Claude Code (claude mcp add).
• Writes <project>/.claude/settings.json SessionStart hook that auto-refreshes context every Claude Code session.
• Augments <project>/CLAUDE.md with @-includes for ticket state.
• Generates first INDEX.md, CURRENT, and CAPABILITIES.md.

2. Use it

Inside a tracked project:

backlog task create "Title" --priority high --milestone milestone-v1
backlog task edit task-3 --status "In Progress"
backlog board                 # ascii kanban
backlog browser               # web kanban

From the hub:

taskpile sync                                  # all tickets, all projects
taskpile sync --status=in_progress             # active across all
taskpile sync --milestone=milestone-v1         # one release
taskpile sync --json                           # machine-readable
taskpile sync --write-index                    # regenerate INDEX/CURRENT/CAPABILITIES

In a Claude Code session inside a tracked project, just ask:

"what's next?" → reads INDEX.md, picks highest-priority unblocked ticket "what milestone are we on?" → reads INDEX By-milestone section "what can you do here?" → reads CAPABILITIES.md "create new scenario for this week" → invokes recipe via taskpile recur run

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Hub (this repo)                                             │
│  ─ projects.yml      registry of tracked projects            │
│  ─ INDEX.md          cross-project digest (auto-generated)   │
│  ─ recipes/          hub-level recipe templates              │
│  ─ bin/taskpile*          dispatcher + sync + recur + capabilities│
│  ─ .claude/skills/   global ticket conventions               │
└─────────────▲────────────────────▲─────────────────▲─────────┘
              │                    │                 │
              │  reads             │  reads          │  reads
              │                    │                 │
┌─────────────┴────────┐ ┌─────────┴────────┐ ┌──────┴─────────┐
│ Project A            │ │ Project B        │ │ Project C      │
│ backlog/             │ │ backlog/         │ │ backlog/       │
│  ├── tasks/          │ │  ├── tasks/      │ │  ├── tasks/    │
│  ├── milestones/     │ │  ├── milestones/ │ │  ├── ...       │
│  ├── docs/           │ │  ├── docs/       │ │                │
│  ├── decisions/      │ │  └── recipes/    │ │                │
│  ├── recipes/        │ │                  │ │                │
│  ├── INDEX.md ◀──auto│ │ INDEX.md ◀──auto │ │ INDEX.md       │
│  └── CURRENT ◀──auto │ │ CURRENT ◀──auto  │ │ CURRENT        │
│ .claude/             │ │ .claude/         │ │ .claude/       │
│  └── CAPABILITIES.md │ │  └── CAPABS...   │ │  └── CAPABS... │
│ CLAUDE.md            │ │ CLAUDE.md        │ │ CLAUDE.md      │
└──────────────────────┘ └──────────────────┘ └────────────────┘

Source of truth = the markdown files in each project's backlog/. Hub = derived view + glue + conventions. Wipe the hub, lose nothing.

Key files

File	Purpose
projects.yml	Registry of tracked projects
bin/taskpile	Single-entry dispatcher (sync, recur, capabilities, init)
bin/taskpile-sync	Aggregate tickets + write INDEX.md / CURRENT
bin/taskpile-recur	Clone a recipe template into a project's backlog
bin/taskpile-capabilities	Generate <project>/.claude/CAPABILITIES.md
bin/taskpile-init	Onboard a new project end-to-end
recipes/	Hub-level recipe templates (cross-project)
.claude/skills/tickets/SKILL.md	Global ticket conventions for LLMs
docs/PHILOSOPHY.md	Why this exists, what it improves
docs/ticket-schema.md	Long-term schema reference
docs/mvp-roadmap.md	Phased build plan (current = phase 1)

Recipes vs routines

	Recipe	Routine
Trigger	Manual (taskpile recur run)	Cron via Claude Code /schedule
Supervision	Always	Autonomous
Output	New ticket	New ticket + chained automation
When	Default	Verifiable, cheap-to-discard outputs

Hard rule: routines never auto-mark Done. Always end at To Do or In Progress for human review.

Comparison

	This	Trello/Jira/Notion + AI	Backlog.md alone	Plain markdown TODOs
LLM read tickets	Native FS	API call	Native FS	Native FS
Cross-project view	Yes	Yes	No	No
Kanban / web UI	Yes (per-proj)	Yes	Yes (per-proj)	No
AI context auto-load	Yes	No	Partial (MCP)	No
Milestones	Yes	Yes	Yes	No
Recurring task templates	Recipes	Manual	No	No
ADRs first-class	Yes	Workaround	Yes	No
Lock-in	None	High	None	None
Cost	Free	$$$	Free	Free

Roadmap

v0.1 (current) — CLI hub, INDEX/CURRENT/CAPABILITIES auto-generation, recipes, milestones, ADRs, single-entry dispatcher, project onboarding.

v0.2 — SQLite/FTS5 cache + cross-project unified web dashboard (drag-drop kanban across all projects, metrics: cycle time, throughput, AI-vs-human authored ratio).

v0.3 — Real-time file watcher (chokidar), live UI updates, project ticket ↔ code-file links + bidirectional grep.

v0.4 — Stop-hook auto-appends Claude Code session summary to active ticket. Acceptance-criteria as machine-checkable shell commands.

v0.5 — Cross-project dependency graph, blocked-detection, "what's the next unblocked thing across all my projects" command.

See docs/mvp-roadmap.md for full plan.

What's next to make it more "AI + Scrum + human ready"

Open ideas (PRs welcome):

• Sprint / iteration support — iteration frontmatter field, INDEX section "current sprint", burn-down.
• Stand-up summary — taskpile standup produces "yesterday / today / blockers" from work-log entries since last invocation. Useful for daily reviews and weekly demos.
• Estimation + actuals — estimate (story points or hours) and actual fields, INDEX shows variance for retro.
• Retro logs — backlog/retros/ dir + skill for AI to draft retro from work-log + decisions since last retro.
• AI-vs-human authored metric — already capturable via assignee field; v0.2 dashboard surfaces the ratio per sprint.
• Cross-project blocking graph — <project>:TASK-N syntax in dependencies field, taskpile sequence resolves order across repos.
• Slash commands — /ticket new, /ticket pick, /ticket done, /ticket plan as project-local commands in .claude/commands/.
• Ticket → code links — files: [path1, path2] frontmatter, taskpile grep <id> ripgreps the listed paths.
• Backwards capability links — # TICKET: TASK-3 comment in code, taskpile backlinks <id> finds them.
• Schema lint — taskpile lint validates frontmatter against JSON Schema, runs in pre-commit hook.
• Templates per epic / label — backlog/templates/<label>.md, auto-applied when creating tickets with that label.
• Time-bounded view modes — taskpile sync --since=7d (rolling window), useful for weekly review meetings.
• Multi-tool agents — Cursor, Windsurf, Codex same MCP. Validate they all pick up the conventions correctly. Add per-tool skill variants if needed.
• Plugin packaging — npm i -g @victor/taskpile so users install via npm directly.

License

MIT — see LICENSE.

Acknowledgements

• Backlog.md — the per-project ticket substrate this is built on.
• Anthropic Claude Code — the AI tool whose context model shaped the design.