# 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](/docs/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`:

```text
git@github.com:acme/api.git
https://github.com/acme/api
ssh://git@github.com/acme/api.git
```

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

1. The key, when the agent passes `project`.
2. 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.
3. 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](/docs/groups) 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.