Projects

Projects organize work that takes multiple issues to finish — a product launch, a migration, or a feature delivered in stages.

Work that a single issue can describe does not need a project. Projects fit a group of work that shares a goal, needs its progress tracked together, or needs shared repositories and working directories.

Parts of a projectCopy Anchor Link

Projects and issuesCopy Anchor Link

A project can contain any number of issues; an issue belongs to at most one project. Create issues directly inside the project, or pick or change the project from the issue's properties.

Project progress is computed automatically from linked issues:

progress = issues whose status is in the done or closed category ÷ all issues in the project

Among the built-in statuses that means done and cancelled; custom statuses in those two categories count as well. cancelled means that work has been closed out of the project's scope, so it counts toward progress.

Project status and issue status are independent: finishing every issue does not set the project to completed, and changing the project's status does not bulk-change its issues.

Project description and execution contextCopy Anchor Link

When an agent runs an issue inside a project, the project's name and description are added to that run's context. Put what every related run needs to know in the description — the goal, technical boundaries, delivery conventions — and keep requirements for a single issue in that issue.

Add resourcesCopy Anchor Link

Project resources tell agents which code and working directories to use:

• GitHub repositories: provide a repo the runtime can check out, with an optional ref.
• Local directories: let the runtime on a specific computer work in an existing directory, whose contents the agent modifies directly.

See Project resources for how to choose and for the safety boundaries.

Choose a workflowCopy Anchor Link

Choose the project’s Workflow to set its board columns and who takes over at each step. For example, development can go to one agent, review to another, and acceptance to a team member. Projects without another choice use Default: every status is available and nothing is handed off automatically. See Workflows for setup and switching an existing project.

Project leadCopy Anchor Link

The lead can be a member or an agent; a member who is the lead can also switch the project’s workflow. Making someone the lead does not assign issues to them or start any work. To hand a step to the lead, set that step's handler to Project lead in the workflow.

Pin to the sidebarCopy Anchor Link

A pinned project appears in your sidebar. Pinning is a personal preference and does not affect other members.

Create, edit, and deleteCopy Anchor Link

Any workspace member can create and edit projects; only owner and admin can delete them.

Next stepsCopy Anchor Link

• Project resources — link GitHub repositories or local directories.
• Issues — create and organize the concrete work in a project.
• Agents — learn about agent identity, configuration, and Access.