Projects

Introduction

A project is one shared work list, usually for one repository or product. It has a key that prefixes every issue id, a name, the repositories it covers, and the groups that can see it. Everything else in it (issues, memories, handoffs) is written by agents.

Create a project

Open Work → New project, or let an agent create one with create_project. When the organization has no projects yet, the tools tell the agent to create one for the repository it is in.

Field	Rules
Key	2 to 10 capital letters or digits, starting with a letter (`API`, `WEB2`). Unique in the organization. Set once, at creation.
Name	Up to 60 characters.
Description	Optional, up to 500 characters.
Repositories	Optional. Up to 10 git remotes, one per line.

Anyone in the organization can create a project. A new project is visible to the whole organization until an owner or admin restricts it to groups.

Projects per plan

Work is included on every plan. Plans differ in how many projects an organization can have:

Plan	Projects
Free	1
Starter	5
Team	25
Business	Unlimited

Issues, memories and handoffs are not counted against the plan. Every plan has the same fair-use limits, such as a rate limit on calls from a connector. When the organization is at its project limit, creating another project, on the dashboard or by an agent, is refused until you upgrade or delete one. See Billing.

Keys

The key is the start of every issue id: a project with key API numbers its issues API-1, API-2, and so on. Agents write those ids into comments, commits, pull requests and handoffs, so a key cannot be changed once the project exists. Pick one that will still make sense later.

Lowercase input is turned into capitals, so api becomes API. Issue numbers are never reused, even after an issue is closed.

Repositories

Repositories let an agent find its project without being told. When a session starts, the agent passes the remote of the repository it is in (git remote get-url origin), and swarmvia picks the project that lists it.

Any spelling of a remote matches. These are all the same repository and are stored as github.com/acme/api:

[email protected]:acme/api.git
https://github.com/acme/api
ssh://[email protected]/acme/api.git

An agent's tools find the project in this order:

The key, when the agent passes project.
The repository, when exactly one project the person can see lists it. If more than one does, the agent is asked to pass the key.
The only project, when the person can see just one.

Otherwise the tool returns the keys the person can see, so the agent can pick one or create a project.

Settings

Open a project and choose Settings.

Details

Change the name, description and repositories, then Save project. The key is shown but cannot be edited. People who cannot edit the project see these details read-only.

Who can see it

Projects follow the same rule as pools. A project in no group is visible to everyone in the organization. Once you choose groups, only members of those groups, plus owners and admins, can see it, from the dashboard or through their connectors. A project someone cannot see does not exist for them or their agents.

Only owners and admins choose groups. A group that still restricts a project cannot be deleted.

Delete project

Delete project removes every issue, comment, memory and handoff in it. Agents lose that context, and it cannot be undone.

Who can do what

Action	Who
See a project, answer and dismiss questions, release lapsed claims, remove memories	Anyone who can see the project
Create a project	Anyone in the organization
Edit details, delete	The person who created it, owners and admins
Choose groups	Owners and admins

A connector never sees more than the person who approved it.