Projects

A project is the workspace for one product, service or initiative. Its sessions, tasks, goals, memories and documents live in it, along with the repositories, database and logs it's connected to and the people working on it. Giving each product its own project keeps its conversations, tracked work and knowledge in one place, separate from your other products.

You'll find all your projects under All projects in the sidebar, or View all projects in the project switcher at the top left.

The Projects page

The Projects page lists every project you can open. Each project card shows:

• the project's icon and name, and your role on it (Maintainer, Contributor, Reviewed Contributor or Viewer)
• the organization that owns it and how many members it has
• its description
• how many repositories it tracks, how many sessions it has, and how many open tasks (when there are any)
• a settings button that opens the project's Project settings

Click a card to open the project's Overview. See Project Overview.

When you sign in, DevSpec opens the last project you worked in, so you only need the Projects page to switch or to create a new one.

Create a project

Organization Owners and Admins create projects. The organization also needs money in its balance, because a project indexes code and runs background work that is charged to the balance. If the balance is empty, DevSpec asks you to add funds first. See Billing, usage and limits.

Creating a project is the first step of its setup. On the Projects page, click New project (on a phone, the + button). With no projects yet, the button reads Create Project. The first step, About the project, asks for:

1. A Project name (required) and, if you like, a Description.
2. Who can open it:
   • Available to everyone: every member of your organization can open it. This is the default.
   • Invite only: only the people you add can open it.
3. People: tick the people who should be on the project and choose each person's project role. The list includes your organization's members and people you've invited who haven't accepted yet; invitees join the project the moment they accept. Invite someone new invites someone to your organization from here, and they are ticked for this project.

Click Create project, and setup continues with the next step.

Every project belongs to your organization, not to you. You choose who can open it when you create the project. You set the project's icon later, in Project settings → General.

Set up a new project with the Setup guide

Project setup has four steps, listed beside each step with your progress:

1. About the project: done as soon as you create it. Go Back to it to rename the project or add people.
2. Connect a repository: give DevSpec access to GitHub and choose the repositories this project tracks, then pick each repository's tracking branch. See Repositories and GitHub.
3. Connect your agent (optional): connect the agent that works on your tasks, or see how to use one you've already connected with this project. See Connect your agent.
4. Start a session: open your first session in the project.

Three more connections are listed as "when you need them": Connect hosted deployment, Connect a database and Connect logs. None of them is required. See Delivery, Database and migrations and Logs.

You can use Skip for now on any step after the first. On the repository step you can also say the project doesn't have a repository yet (see "Start a project without a repository" below).

To come back to setup later, open Project settings → Setup guide. Until you've been through it, Maintainers also see a Continue setting up card on the project's Overview, with your progress and a Continue setup button. A Maintainer can dismiss that card for the whole project.

People who join a project by invitation don't set the project up: they set up their own profile, can connect their agent, and go straight to their first session.

Start a project without a repository

A project doesn't need code. If you're planning something that doesn't exist yet, or your work lives in documents, you can use sessions, tasks, goals, memories and Dev as normal without connecting a repository.

On the Connect a repository step of Project setup, click I don't have a repository yet. That completes the step and stops DevSpec asking you to connect one. It's reversible: click I have a repository to connect, or connect a repository at any time, and DevSpec picks everything up from there. Nothing you've created needs redoing.

If you use an agent in a folder with no repository, the agent can't tell which project the folder belongs to, because there's no git remote to recognize. Once you've said the project has no repository, the same step gives you a command that pins the folder to the project by writing a small file, .devspec/project.json, containing only the project's id:

{"project_id":"<your project id>"}

Run the command in the folder, or use your agent's project command (/devspec.project in Pi, /devspec:devspec.project in Claude Code, or /devspec-project in Antigravity CLI) with remember to write the file. The file holds nothing private, so it's safe to commit, and anyone who clones the folder gets the same pin.

To give Dev something to read, upload specs, PDFs and other files on the project's Resources page. See Documents and artifacts.

Who can open a project, and what they can do

Access to a project comes from two places: the person's organization role and their project role.

Each person on a project has one project role:

• Viewer: sees everything and takes part in the conversation, but can't change the record.
• Reviewed Contributor: proposes work and knowledge for a Maintainer to accept, and can start experiments on separate branches.
• Contributor: adds work and knowledge directly. Changes to agreed work need approval; knowledge edits depend on whose decision they affect.
• Maintainer: accepts proposals and manages the project, including settings, repositories and integrations. Undoing another Maintainer's decision needs that person's OK or the project lead's.

A project role isn't inherited from the organization role except as shown in the table. See Organizations, members and roles.

The project lead

Every project has one project lead, who is always one of its Maintainers. Alongside a decision's owner, the project lead can approve work that would change a Maintainer's protected decision. The lead can also decide confirmation requests. Being the lead isn't a separate role: the lead is a Maintainer with that job.

• Who it is. The person who creates a project leads it. The lead is marked Project lead on the Members page and wherever you open someone's card from their avatar, and the Members page shows who it is and its change history. Dev and your coding agents know the lead by name too.
• Handing it over. The lead can open the project's Members page and click Hand over to give it to another Maintainer of the project. The lead stays a Maintainer.
• Changing it from the organization. An organization Owner or Admin can change any project's lead from Organization settings → Projects, without being on the project, choosing anyone in the organization. If the person they choose isn't a Maintainer of that project yet, choosing them makes them one, and the screen says so before you confirm.
• Always a Maintainer. You can't change the lead's role or remove them from the project until someone else leads it.
• When the lead leaves. If the lead leaves the organization or closes their account, the project shows No project lead and the organization's Owners and Admins are asked to choose a new one. Nobody is chosen automatically, and anything that needs the project lead waits until then.

A change of lead notifies the new lead, the previous lead and the project's Maintainers, and appears in the project's history on the Members page and in Project pulse on the project's Overview. You can turn these notifications off under Project lead on your notification settings.

Add people to a project

The project's Members page (in the sidebar) lists everyone on the project with their role. People who have access through their organization role are marked via organization, and guests are marked guest of your organization. It also holds Project lead and Who can verify: by default, people whose project role allows verification can verify work, and a Maintainer can restrict that to named people here. See Who can verify work.

Project Maintainers and organization Owners and Admins can manage members:

• Add from organization: add people already in your organization, or invited and not yet accepted, and choose each person's role. On a project marked Available to everyone, organization Members are already Contributors; use this to make one a Maintainer.
• Invite someone: invite people by email address. A project Maintainer who isn't an organization Admin can invite people as Guests of the organization, to this project only. Organization Admins can also invite new organization Members and add them to other projects in the same step.
• The menu beside a person changes their role (Make Viewer, Make Reviewed Contributor, Make Contributor, Make Maintainer) or removes them (Remove from project).
• Pending invites lists invitations that haven't been accepted, with a Withdraw button.

Everyone else can see the list but can't change it.

What's in Project settings

Project settings holds a project's configuration. Open it from Project settings in the sidebar or the settings button on a project card. It's available on a desktop browser.

Everyone on the project can view the settings. Only Maintainers can change them; everyone else sees them read-only.

Delete a project

Only the organization's Owner can delete a project. Being an Admin, a Maintainer or the person who created the project isn't enough. Everyone else sees the Delete button disabled, with a note on how to find the Owner.

To delete a project:

1. Open Project settings → General.
2. Under Danger zone, click Delete.
3. Type the project's name to confirm, then click Delete project.

Deleting permanently removes the project, every tracked repository, database connection and session in it. It can't be undone.