Sharing an epic across projects

How to make one epic serve several projects, change it, and take a project out of it again (ADR-0028).

What sharing does

Sharing an epic gives each project you pick its own copy of the epic, with the same name and objective. Each copy is numbered in its own project (SPR-3 in one, OWL-9 in another), and the copies list each other as neighbours.

  • Name and objective stay in step. Change either on one copy and every copy changes.
  • Tasks stay per project. A task only ever uses its own project's copy of the epic, so each project's board and counts show only that project's tasks.
  • Sharing again is harmless. Sharing with a project that already holds a copy changes nothing.
  • A group holds at most 25 projects, the epic's own included.
  • A name clash is refused. When a project you picked already has an epic of the same name (capitals don't matter), nothing is shared and Sparrow answers 409, naming the epic. Rename or delete one of them first.

Who can share

You can share an epic, change a shared epic or unshare it when you own every project involved: the epic's own project, each project you pick, and each project already in the group. A project has one owner, so in practice these are projects with the same owner; handing a project to another member also hands over its part in every shared epic. Admins can do all of it across any projects.

Being a member isn't enough. When you lack ownership, Sparrow answers 403 with a message such as You don't own OWL: you must own every project involved to share an epic, naming the projects you don't own. The dashboard shows it in its error message.

Share an epic in the dashboard

  1. Open the project and its Epics tab.
  2. Click Share on the epic. The button shows only when you own the project and another project you own could take the epic.
  3. Pick the projects, then confirm.

A shared epic shows a chip listing the projects it's shared with. Opening the epic's edit dialog says that your change reaches every project in the group.

Share an epic through the MCP server

An agent calls share_epic with the epic's ID and the keys of the projects to share it with. It answers with the epic and its neighbours. It calls unshare_epic with the epic's ID and one project's key to unshare. Both act as you, so they need the same ownership (see Agents and the MCP server).

Change a shared epic

Changing the name or objective needs the owner of every project in the group, because it reaches every copy; a member of one project gets 403. Should another change reach a copy meanwhile, Sparrow answers 409 and changes nothing: reload the epic and try again.

Delete a shared epic

Any member can delete their project's copy. Only that copy goes: the other projects keep theirs, and this project's tasks stay, with no epic. A copy left on its own is no longer shared.

Unshare an epic

Unsharing takes one project out of the group and keeps its copy as a standalone epic, with its tasks and its number, no longer mirrored. It takes the owner of every project in the group. When one copy is left, it's no longer shared either.

See Projects, epics, tasks and tags for what an epic is.