Projects
A project is where a team's work lives. Initiatives, plans, and bugs roll up to one. The team's repository binds to one. The default sandbox profile for runs is set on one.
A project is where a team's work lives. Initiatives belong to a project. Plans and bugs roll up to a project. The team's repository binds to one. The default sandbox profile for the project's chats and flows is set on one. Every other record in the SDLC area has a project somewhere in its lineage.
If your company runs one product team, you might have one project. If your company runs several teams or several products, you'll usually have one project per team. A workspace can hold a handful of projects (for a single-team org) or many (for a portfolio company with many products).
How a project sits in the work model
The project is the cross-cutting structural container. It rolls up into portfolios above and holds initiatives below; it grants access through teams and direct members; it binds a repository and a default sandbox profile that its runs use. Here is the shape of those relationships in one picture.
How it looks in practice
A worked example, with realistic values.
Sarah Chen runs the Analytics team at a B2B SaaS company. They build and ship the customer-facing analytics product, called Insights. Sarah creates a project for it.
| Field | Value |
|---|---|
| Name | Insights |
| Description | Customer-facing analytics. Reporting, dashboards, exports. |
| Owner | Sarah Chen |
| Status | Active |
| Repository | orcette/insights |
| Default branch | main |
| Default sandbox profile | Analytics-Node20 |
| Color and icon | Cyan / insights |
Now look at how the project connects to the rest of Sarah's workspace.
Upstream. The Insights project rolls up into two portfolios: Q4 Launches (Marcus Reed's quarterly rollup, where leadership tracks every customer-facing launch scheduled for the quarter) and Enterprise Tier (the long-running product-line rollup that groups every project shipping enterprise-tier capabilities). Both are M:N: Insights is in both lists; each portfolio includes Insights alongside other projects.
Downstream. Inside the Insights project are seven active initiatives: CSV Export on the Reporting Page, Dashboard Performance, New Visualization Library, Per-Customer Branding, Scheduled Report Email, Workspace-Level Filters, and Mobile-Optimized Viewer. Each initiative carries plans and bugs underneath; the Initiatives tab on the project is where Sarah's team works.
Access. Sarah is the owner (full read and write). The Analytics team is linked to the project; that gives Sarah's six engineers access automatically. A contractor working on the visualization library has a direct grant on the Members tab with a Viewer role. A platform admin has read access on the project through their admin scope but cannot write to it directly (admin scope bypasses reads, not writes).
Configuration. The Analytics-Node20 sandbox profile is what every chat and flow launched from a record in this project uses by default, unless an initiative or a launch picks a different one. The orcette/insights repo is what the sandbox clones when a run starts; the agent edits in the sandbox and opens pull requests back to GitHub authored as the person who triggered the run.
When to create a new project
Most teams arrive at one project per delivery team, since the project is the unit a sandbox profile, a repository, and a team's day-to-day work all bind to. Two patterns work well.
Per delivery team. One project for each engineering team your org runs. The team links to the project for access; the project's repo is the codebase the team works in; the default sandbox profile is the team's chosen runtime and image. The Initiatives grid on the project is the team's queue.
Per product line within a team. A single team that ships across multiple codebases or product surfaces sometimes finds it cleaner to give each surface its own project. The team links to all of them; the team members see each project's work separately on its detail page; the cross-project roadmap on the workspace dashboard rolls them up.
A pattern that does not usually scale well: one project per initiative. The project is meant to be long-lived; initiatives come and go inside it. If you're tempted to create a project for one piece of work, an initiative inside an existing project is almost always the right answer.
When you create one
The flow is short:
- Open SDLC, click into Projects, and click New project. The drawer slides in from the right.
- Enter a name. The only required field. Has to be unique within your workspace; an existing name returns a duplicate-name error inline.
- Add an optional description, start date, target date, color, and icon. The color comes from a small set of named options (Brand / Green / Red / Yellow / Blue / Neutral); the icon is a single emoji you type in.
- Pick the repository if the project has one. Either bring your own from GitHub (paste in
owner/repoand optionally a default branch), or have the platform create a new repo on the fly using your tenant's GitHub binding. A project with no repository is fine; it just won't be able to run flows that need to clone code. - Click Create. You become the owner; the project lands at status Active; the rail chip appears in your SDLC sidebar under Projects.
If your workspace has hit its project quota, the Create button returns an inline error: Project limit reached. Your plan includes N active project(s). You currently have N active project(s). Open Plan and Usage to review limits or request an upgrade. Soft-deleted projects count against the quota; restore one or upgrade your plan before creating a new one. The link at the bottom of the message goes straight to Settings → Plan and Usage.
When you create the project, you become its owner. The owner has full read and write access to everything in the project regardless of any other membership. Other people get access through the four paths covered below.
Statuses
Four:
- Active is the default and where a project sits while work is happening.
- Paused is for a project on hold; no new work expected for now, but you want it to keep showing up so you remember it's there.
- Completed is for work that finished and you want to keep around as history.
- Archived is for projects you want to retire from the day-to-day lists without deleting.
Status is a label, not a state machine
An initiative, a plan, or a bug runs through a real workflow with transitions the server enforces (you cannot move a plan from "draft" to "complete" without going through "in progress"). A project is the container those records live in, and the conventional move (active → paused → completed → archived) is something your team adopts rather than the platform enforcing. The flexibility is useful: a project temporarily set to "paused" for a planning quarter does not need a special transition to come back to "active" when work resumes.
Soft-delete and the trash view
Soft-delete is a separate concern from status. A deleted project still exists; it is filtered out of the default Projects list and most cross-entity queries.
To reach the trash, open the Projects list and click the Trash toggle in the toolbar. The list switches to deleted-only mode; each row carries a "Deleted" badge and an updated row-action menu with Restore and Delete permanently instead of the normal edit actions.
Restoring is a one-click move (a confirmation dialog asks if you mean it); the project flips back to active and reappears in the normal list with all its initiatives, members, and configuration intact. The portfolio and team links stay through the soft-delete cycle, so a restored project lands back exactly where it was.
Hard-deleting
Hard-deleting a project is only allowed from the trash view (you have to soft-delete first), and the hard-delete is blocked if the project still has active initiatives. That second guard is there to keep you from losing real work you forgot about. To proceed, either reassign the initiatives to a different project or soft-delete them too before hard-deleting the parent.
Who can read and write a project
Reads every project in the tenant. Writing requires one of the next three.
Full read and write. One owner per project; ownership is transferable.
Added to the project's Members tab with a role.
Member of a team that's linked to the project. Access flows through.
A workspace admin with the right scope reads every project in the tenant. Write access does not bypass on admin scope; an admin who wants to edit a project either needs to be the owner, a direct member, or part of a team linked to the project. This asymmetry is deliberate: admins see everything for support and audit, but a project's records are not silently editable by people outside the project's membership.
The project owner has full read and write access. There is exactly one owner at a time; ownership is transferable. The current owner (or a workspace admin with the membership-manage scope) hands off ownership from the Members tab; the new owner takes the structural row and the old owner stays in the member list with their previous role (or is removed if you choose).
A direct grant through the Members tab is the way to give one person specific access without setting up a team. Useful for contractors, consultants, or an executive sponsor who needs to read a project but is not on the team.
A team link is what most teams settle into for ongoing work. Set up a team, link it to the project, and team membership flows through to project access automatically. Add or remove someone from the team and their project access adjusts without anyone touching the project's Members tab directly. The team-link path is the one to use as your team grows.
A note about portfolios: a project that is grouped under a portfolio gets nothing extra from the grouping. Portfolio membership and project membership are independent. The portfolio is a rollup convenience, not an access path. See Portfolios for the model.
The detail page
Six tabs in the order they appear on the project detail page.
Overview carries the project's description, the portfolio chips (which portfolios this project rolls up to), and a few high-level counts.
Initiatives lists the initiatives scoped to this project as a filterable grid. This is the daily-work surface for a project.
Goals lists the goals scoped to this project, including the OKR tree if your team uses one. Goals support work but don't own it; key results point at initiatives in the project or at portfolios.
Members holds the people with direct grants on the project, plus the owner row. Add a member with the role you want them to have, change someone's role inline, remove a member who no longer needs access, or transfer ownership to a teammate. The owner appears as a structural row with no role chip; the owner does not need one.
Teams shows the teams linked to the project. The link itself is managed from the team's detail page in Settings; this tab is read-only on the project side so you can see who has access through which teams without leaving the project.
Settings holds the editable fields (name, description, color, icon, dates), the default sandbox profile, the soft-delete action, and the hard-delete action (which only appears if the project has been soft-deleted and has no active initiatives).
Managing members
The Members tab covers the lifecycle of a person's direct access to a project. The four moves you'll make most often:
- Add a member. Click Add member, pick a person, pick a role. The role determines what they can do in the project (read-only, read-and-write, full admin) per your workspace's roles configuration.
- Change a role. A role chip is inline-editable; click it, pick a new role from the menu. The change applies immediately.
- Remove a member. The row's kebab menu has Remove. The owner cannot be removed directly; transfer ownership first.
- Transfer ownership. The owner's row carries a Transfer ownership action. Pick the new owner from the member list; the new owner takes the structural row, and you stay in the member list with whatever role you choose (or are removed entirely if you choose). The transfer is recorded in the audit log.
Where you see project work in the platform's surfaces
The project's Initiatives tab is the canonical per-project view. For the broader interface (boards across all projects, the cross-project roadmap, the workspace-wide grid), the project shows up as a filter, not as a separate surface.
The kanban board
The Initiatives kanban board at the workspace level draws from every project's initiatives. Apply a Project filter to scope the board to a single project; the columns stay the same (the initiative-workflow statuses) and only the cards from the picked project show. The same pattern works on the bugs board and the sprints board.
The cross-project roadmap
The cross-project roadmap on the workspace dashboard shows initiative bars across projects on a time axis. Apply a Project filter to scope it; the lanes collapse to the picked project's initiatives.
The workspace-wide grid
The workspace-wide Initiatives grid lists every initiative across every project, with the project as a column you can sort, filter, and group on.
Why the platform uses a filter rather than separate per-project surfaces
This pattern (workspace-wide surfaces with project as a filter) is intentional. Leaders and PMs working across several projects do not have to remember which surface is per-project versus cross-project, and the URL bar carries the filter so a single-project view is shareable as a link.
Settings worth knowing about
Two settings on a project that materially shape what runs there.
Default sandbox profile. Every agent run needs a sandbox profile. A project can have a default, set in Settings, and any flow or chat launched from a record in the project picks up that default if no closer profile is set. This is how a workspace with many projects keeps the right team's flows running on the right image, with the right tools and the right runtime, without anyone choosing each time. Pick the profile in the project's Settings tab; the cascade follows from there.
Repository. The project's GitHub repo and default branch are what the sandbox clones when a run starts. Changing these mid-project is supported (the next run uses the new values) but you would usually not need to; the binding is set once.