Planning
Planning
Planning groups a project's tasks into sprints and epics (module planning). A sprint is a fixed window of work. An epic is a body of work larger than a sprint, such as a rework or a launch, which tasks point at.
In the sidebar under Projects → Planning. Needs: Projects and Tasks.
What you see
The screen has two tabs, Sprints and Epics, each with a count. Lists load ten at a time. Each list has a search box and filters, such as project and status. A project's sprints and epics also appear as Plans on the project's home page.
Sprints
Each row shows the sprint's name, its project's key, its status (planned, active or closed) and its window, from start date to end date. A planned sprint has Start. An active sprint has Close.
With no sprints yet, the screen says "No sprints". If there are no projects, it explains that a sprint belongs to a project.
Epics
Each row shows the epic's name and summary, its project's key, and whether it is open or closed. An open epic has Close.
What you can do
Plan a sprint
- On Sprints, press New sprint.
- Pick the Project, type a Name such as "Sprint 12", and set Starts and Ends if you know them.
- Press Create. The sprint starts as planned.
- Put tasks in it: an agent or the API sets a task's sprint (see Tasks).
The dialog asks before closing if you would lose what you typed.
Start a sprint
Press Start on a planned sprint. A project has one sprint running at a time, so starting one closes any other active sprint on the same project.
Close a sprint
- Press Close on the active sprint, then confirm.
- Planning opens the next sprint and moves every unfinished task into it. The next sprint is named after this one with the number raised by one ("Sprint 12" becomes "Sprint 13"). If both dates were set, it starts when this one ended and runs for the same length.
Nothing is dropped silently. Through the agent tools you can instead roll unfinished work into a sprint you choose, or leave it where it is.
Start and close an epic
- On Epics, press New epic.
- Pick the Project, type a Name (unique within the project) and an optional Summary.
- Press Create. Tasks join the epic when their epic is set. A picked idea can also become an epic from Ideas.
- When the work is done, press Close. A closed epic drops out of the list unless closed ones are asked for. Its tasks are not touched.
Goals and templates
These are reached through the agent tools and the API:
- Sprint goals: the outcomes a sprint is for, as distinct from what is in it. A task can sit under a goal.
- Task templates: a named set of tasks, each with its own description, priority, points and starting column. Applying a template creates its tasks on a project in one go, in the backlog or in a sprint. Template names are unique across the workspace.
- Sprint report: what a sprint committed, completed and carried over.
Who can do what
| Permission | Label | Lets you |
|---|---|---|
planning:read | View planning | Open Planning and see sprints, goals, epics, templates and sprint reports |
planning:write | Manage planning | Create, start, close, change and delete sprints, goals, epics and templates, and move tasks between sprints |
You see the sprints and epics of the projects you can see. To change them you also need editor level on the project, or to be its creator or an administrator. See People, roles and permissions.
What runs on its own
Nothing in this module runs on a schedule. Sprints start and close only when someone says so.
For agents
Agents can run a project's sprints end to end: open them, set goals, apply templates, start them, close them and move unfinished work. Changes go through your approval rules. Deleting a sprint, goal, epic or template is classed as destructive: under the default approval policy a person is asked first. Deleting a sprint keeps its tasks and sends them back to the backlog; deleting an epic keeps its tasks outside any epic. See Agents and approvals.
Read (read-only): planning.activeSprint, planning.sprints, planning.sprintReport, planning.goals, planning.epics, planning.templates.
Sprints: planning.createSprint, planning.updateSprint, planning.startSprint, planning.closeSprint, planning.rolloverTasks, planning.removeSprint.
Goals: planning.addGoal, planning.updateGoal, planning.removeGoal.
Epics: planning.createEpic, planning.updateEpic, planning.closeEpic, planning.removeEpic.
Templates: planning.createTemplate, planning.updateTemplate, planning.removeTemplate, planning.applyTemplate.
Over MCP the same tools are named planning__sprints, planning__closeSprint and so on. See API keys and MCP access.