> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erstan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Group related agent tasks under team or company-wide projects.

Projects organize related [tasks](/tasks/overview) so a team can track a stream of agent work as one initiative. Use them for month-end close, AR collections sprints, vendor onboarding, implementation work, or any recurring body of work where tasks, subtasks, scheduled runs, and reviews need a shared label.

Projects are task containers, not agent definitions. Agents still live in the [Agents library](/agents/overview), teams still control membership, and tasks still carry the actual run, review, and approval history.

## Where projects fit

| Layer         | What it controls                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Workspace** | The account boundary and available members, connectors, models, and teams.                                                     |
| **Team**      | The working group that owns tasks, agents, content, members, labels, and settings.                                             |
| **Project**   | A named workstream inside a team, or company-wide across teams, used to group tasks and schedules.                             |
| **Task**      | One unit of work, usually backed by an agent run, with status, assignees, reviewers, comments, files, approvals, and subtasks. |

Most projects are scoped to one team. A **company-wide** project can be assigned to tasks from multiple teams when the workstream crosses team boundaries.

## Project fields

Each project has a small set of fields so it stays easy to scan and filter.

| Field           | Purpose                                                                  |
| --------------- | ------------------------------------------------------------------------ |
| **Name**        | Required, unique within the project scope, and limited to 40 characters. |
| **Brief**       | Optional context for the workstream, up to 1200 characters.              |
| **Color**       | Optional visual marker used wherever the project appears.                |
| **Lead**        | Optional workspace member responsible for the project.                   |
| **Target date** | Optional date for planned completion or review.                          |
| **Status**      | Active, Completed, or Archived.                                          |
| **Scope**       | Team-scoped or company-wide.                                             |

<Tip>
  Keep project names short and outcome-oriented, such as "July Close", "AP Cleanup", or "Q3 Collections". Put operating detail in the brief.
</Tip>

## Using projects with tasks

When you create or edit a task, choose a project that is assignable to that task's team. Task lists and boards can then filter, group, and search by project.

Subtasks inherit the parent task's project when you do not choose a different project. This keeps delegated work grouped with the original request unless you deliberately move it.

Recurring task schedules can also carry a project. Each occurrence keeps that project assignment as long as the project remains active and assignable.

<Warning>
  Archived projects cannot be assigned to new tasks. Existing tasks keep their project history, but new and recurring work should move to an active project.
</Warning>

## Creating and managing projects

Create projects from the team or workspace project controls, depending on the surface you are using.

<Steps>
  <Step title="Choose a team context">
    Start from the team that owns the work. If the project should be available across teams, create it as company-wide.
  </Step>

  <Step title="Set the project details">
    Add the name, optional brief, color, lead, target date, and sort order.
  </Step>

  <Step title="Assign tasks">
    Set the project on new tasks, existing tasks, and recurring schedules that belong to the workstream.
  </Step>

  <Step title="Review progress">
    Use project filters in Tasks, or open the project summary to see total, completed, active, failed, queued, review, and schedule counts.
  </Step>
</Steps>

Owners, admins, and members with the right team access can see projects available to their teams. Managing project details requires access to the owning team or workspace admin permissions.

## Archiving, restoring, and deleting

Use **Archive** when a project is no longer active but should remain available for historical filtering. Archived projects can be restored later.

Deleting is stricter: a project can be deleted only when it has no tasks and no recurring schedules. If it has ever been used for real work, archive it instead.

Changing a project from team-scoped to company-wide, or moving it between teams, is blocked after tasks or schedules use it. That prevents old task history from silently changing scope.

## Agent and API usage

Agents resolve project IDs with the Erstan tool `er_project_list` before creating or updating tasks. This is the safe pattern:

1. List assignable projects for the current workspace and team context.
2. Match by project name or user intent.
3. Pass the resolved `projectId` into `er_task_create` or `er_task_update`.

The public API exposes the same project model through authenticated routes:

| Route                                       | Use                                                                   |
| ------------------------------------------- | --------------------------------------------------------------------- |
| `GET /v1/workspaces/{workspaceId}/projects` | List projects visible in a workspace.                                 |
| `GET /v1/teams/{teamId}/projects`           | List projects for a team, optionally including company-wide projects. |
| `POST /v1/teams/{teamId}/projects`          | Create a team or company-wide project.                                |
| `GET /v1/tasks/options/projects`            | List assignable projects for task forms and tools.                    |
| `GET /v1/projects/{projectId}/summary`      | Read project details and task counts.                                 |
| `PATCH /v1/projects/{projectId}`            | Update project fields.                                                |
| `POST /v1/projects/{projectId}/archive`     | Archive a project.                                                    |
| `POST /v1/projects/{projectId}/restore`     | Restore an archived project.                                          |
| `DELETE /v1/projects/{projectId}`           | Delete an unused project.                                             |

## Next steps

<CardGroup cols={2}>
  <Card title="Tasks overview" icon="list-checks" href="/tasks/overview">
    Track the task work that projects group together.
  </Card>

  <Card title="Working with tasks" icon="panel-right-open" href="/tasks/working-with-tasks">
    Assign tasks, subtasks, labels, participants, dates, and projects.
  </Card>

  <Card title="Teams overview" icon="users" href="/teams/overview">
    Understand how team scope controls project visibility.
  </Card>

  <Card title="Tools by Erstan" icon="wrench" href="/tools/by-erstan">
    See the task and project tools agents can call.
  </Card>
</CardGroup>