Planning Hierarchy

Every piece of work flows through four levels: initiative, project, issue, and local task. The first three live in Linear and are the source of truth for what gets built and why. Local tasks are ephemeral execution state that agents create and discard—they capture how the work gets done, one commit at a time.

I use my own blog/cc-menubar/ to monitor local tasks.

Initiative Linear Initiative Project Linear Project Issue Linear Issue Task Local execution

Initiative

The top-level goal, written as a PRD. An initiative describes ongoing work—like my website or the Mock Machines app— and contains multiple projects that deliver it. There is a catch all "Useful Tools" initiative for miscellaneous work. The intent is that the PRD should be human authored, or in practice closely edited to ensure it accurately reflects the desired outcome.

Project

A time-bound deliverable within an initiative, also written as a PRD. Each project is a significant chunk of work—a chapter, a major feature, a migration—that can be planned and shipped independently. Like initiatives, project descriptions are human-owned.

Issue

The plannable unit of work. A human writes the what, the acceptance criteria and constraints. The /feature-dev-linear skill can also be used for larger feature work, and steps the dev through a more in depth discovery process and exploration of alternatives. An agent helps decompose the issue into a task checklist with validation steps. Issues are the handoff point: human intent in, agent execution plan out.

Task

Agent-created execution state that lives in ~/.claude/tasks/, not in Linear. Each local task maps to a single commit. Tasks are created when an agent decomposes an issue, and they are discarded once the work is merged. They exist to give agents tractable, atomic units of work without cluttering the human-readable project tracker.