Projects, goals, and teams
Paperclip gives a company a shared way to turn intent into organized work. Goals describe desired outcomes. Projects give related tasks a home. Agent hierarchies and catalog team definitions provide the people and operating shape that carry the work forward. Folders and personal memberships then help each user find the part of that company work that matters to them.
Planning model
Planning is company-scoped and links strategy to execution. A goal can sit in a hierarchy, a project can support one or more goals, and tasks connect the plan to work that an agent or person can perform.
Planning relationships
Goals form a tree through parent goals. Each goal can have an owning agent and a state such as planned, active, achieved, or cancelled. Projects have their own status, lead agent, target date, decision owner, and company context. A project can contribute to more than one outcome through its goal references, and every linked goal must belong to the same company. packages/…/goals.ts• L12-28 packages/…/projects.ts• L7-30 packages/…/project.ts• L78-114 server/…/projects.ts• L391-518 server/…/projects.ts• L509-545 server/…/projects.ts• L674-716 server/…/projects.ts• L997-1089
The main relationship is directional: goals explain why the company is doing work, while projects organize what the company is doing. Tasks then provide the smaller units of work below a project or goal. This lets a reader move from a broad goal to the project and task records that show progress. docs/…/goals-and-projects.md• L6-10 docs/…/goals-and-projects.md• L48-50
This diagram shows how company intent becomes an operating work area and then a task.
flowchart TD
Company[Company] --> Goal[Goal hierarchy]
Goal --> Project[Project]
Goal --> Task[Task]
Project --> Task
Team[Agent hierarchy] --> Task
Project --> Workspace[Project workspace]
References: packages/…/goals.ts• L12-28 packages/…/projects.ts• L7-30 packages/…/project.ts• L78-114 server/…/projects.ts• L391-518 server/…/projects.ts• L509-545 server/…/projects.ts• L674-716 server/…/projects.ts• L997-1089 docs/…/goals-and-projects.md• L6-10
Projects
Projects are company work areas for a deliverable. They collect related tasks and planning links while providing the code or work context that agents use when they act on project work.
Project work areas
A project carries its name, description, status, lead agent, target date, decision owner, visual identity, pause state, and optional budget or execution policy. It can also carry environment bindings for project work. The decision owner is an active company user who receives ownerless decision work. A project can also be managed by a plugin. These fields describe the project at a high level; the related task records remain the place for individual work. Plugin-managed projects can be created or restored from a plugin declaration while keeping a link to their managing plugin. packages/…/projects.ts• L7-30 packages/…/project.ts• L78-114 server/…/projects.ts• L391-578 server/…/projects.ts• L603-611 server/…/projects.ts• L788-946
Each user can also have a personal private project for private tasks. The service creates this project only when needed, gives the user privacy ownership, and grants that user access in the same transaction-safe flow. It uses the company’s default project storage policy, so private work still has a valid execution context without becoming a shared company work area. server/…/projects.ts• L90-149
Projects can be public or private. A private project has an access boundary for named company users and agents. Its privacy owner and permitted principals define who can read it, while company and project authorization still apply to every request. This access model is separate from the personal choice to join or star a project. server/…/projects.ts• L189-245 server/…/projects.ts• L521-669 server/…/projects.ts• L90-149
The project record can expose a derived codebase view. It identifies the selected workspace and effective local folder, using a managed checkout when no local folder is available. It can also show current runtime services, the selected workspace provider, and whether a project is managed by a plugin. Project list data includes lightweight task and active-budget signals, so a company can scan work areas without opening each project. server/…/projects.ts• L289-427 server/…/projects.ts• L429-507
Project workspaces connect a project to a local path, repository, or managed remote workspace. A project can have several workspaces and one can be primary. The primary workspace gives project-scoped execution a default place to work, while workspace runtime controls can start, stop, restart, or run configured workspace actions. Repository selection can also create or update the project workspaces that represent the chosen repositories. packages/…/project_workspaces.ts• L14-44 docs/…/goals-and-projects.md• L100-115 server/…/projects.ts• L320-335 server/…/projects.ts• L671-1072 server/…/projects.ts• L1155-1460
The API checks the workspace source before it stores the workspace. Local and repository-backed workspaces need a usable path or repository, while managed remote workspaces need a remote reference or repository. Instance policy can also prevent local paths, and execution environments must be valid for the company. These checks keep project execution context consistent with the way the instance runs work. server/…/projects.ts• L104-113 server/…/projects.ts• L391-425 server/…/projects.ts• L680-715 server/…/projects.ts• L717-760 server/…/projects.ts• L1155-1239 server/…/projects.ts• L1241-1402
Project creation is safe to retry when the caller supplies an idempotency key. The server ties that key to the actor and company, returns the earlier project for the same inputs, and rejects a reused key with different inputs. Goal links are checked against the company before the project is saved, and project names are adjusted when needed to keep short references unique. A project’s workspace storage choice remains fixed after creation. server/…/projects.ts• L391-519 server/…/projects.ts• L509-545 server/…/projects.ts• L674-716 server/…/projects.ts• L997-1019
References: packages/…/projects.ts• L7-30 packages/…/project_workspaces.ts• L14-44 server/…/projects.ts• L104-113 server/…/projects.ts• L189-245 server/…/projects.ts• L320-425 server/…/projects.ts• L391-519 server/…/projects.ts• L521-669 server/…/projects.ts• L671-1072 server/…/projects.ts• L90-149 server/…/projects.ts• L289-427 server/…/projects.ts• L429-507 server/…/projects.ts• L509-545 server/…/projects.ts• L603-611 server/…/projects.ts• L674-716 server/…/projects.ts• L788-946 server/…/projects.ts• L997-1019 server/…/projects.ts• L1114-1133 server/…/projects.ts• L1155-1460
Project views
The project list gives an actor a view of projects that they can read. It shows active projects by default and can include archived projects when requested. Summary discovery applies authorization before it fills a page, so denied projects do not consume page slots or leak through cursors. The discovery response stays small, while the project detail view brings together a project summary, tasks, overview fields, workspaces, configuration, budget, membership actions, and plugin-provided operations. server/…/projects.ts• L735-770 server/…/projects.ts• L337-363 ui/…/ProjectDetail.tsx• L359-433 ui/…/ProjectDetail.tsx• L846-935
The project page keeps the planning record close to its execution context. A user can move from project tasks to workspace controls without leaving the project, and can open a goal-linked project from the goal detail view. The page keeps a canonical project reference in the URL, syncs the selected company from the resolved project, and redirects older or short forms to the selected tab. ui/…/ProjectDetail.tsx• L327-371 ui/…/ProjectDetail.tsx• L439-540 ui/…/GoalDetail.tsx• L111-117 ui/…/GoalDetail.tsx• L207-223
Project detail tabs expose the main kinds of project work:
- Tasks show issues for the project and live run state.
- Workspaces show project work areas when isolated workspaces are enabled and the project has usable workspace summaries.
- Configuration edits project identity and operating settings, including archive state.
- Budget shows and updates the project budget policy.
- Plugin operations and plugin tabs expose work supplied by project plugins.
The page also exposes a project summary and toolbar extension points. A plugin-managed project can show its source and plugin operations without changing the core project tabs. ui/…/ProjectDetail.tsx• L726-864 ui/…/ProjectDetail.tsx• L868-935
The detail page keeps personal membership state visible without changing project authorization. A user who left a project sees a notice and can rejoin, while starring remains a personal navigation choice. Budget changes refresh the project, list, dashboard, and budget views so the same policy is visible across the product. ui/…/ProjectDetail.tsx• L374-377 ui/…/ProjectDetail.tsx• L632-648 ui/…/ProjectDetail.tsx• L691-803
References: server/…/projects.ts• L735-770 server/…/projects.ts• L337-363 ui/…/ProjectDetail.tsx• L327-433 ui/…/ProjectDetail.tsx• L439-540 ui/…/ProjectDetail.tsx• L632-648 ui/…/ProjectDetail.tsx• L691-803 ui/…/ProjectDetail.tsx• L846-935 ui/…/GoalDetail.tsx• L111-117 ui/…/GoalDetail.tsx• L207-223
Project references
Project mentions provide stable project links inside markdown. A project:// link carries a project identity and can carry a normalized color hint. Shared parsing can recover unique project IDs for other parts of the product that need to connect written content to project records. packages/…/project-mentions.ts• L1-24 packages/…/project-mentions.ts• L71-101 packages/…/project-mentions.ts• L233-243
Project URLs can also use a short reference. The API resolves that reference within the selected company and rejects an ambiguous match instead of choosing a project by accident. Project names are adjusted when needed so their short references remain usable. A caller can use the project ID when a short reference is not unique. server/…/projects.ts• L614-642 server/…/projects.ts• L1462-1502 server/…/projects.ts• L135-166
References: packages/…/project-mentions.ts• L1-24 packages/…/project-mentions.ts• L71-101 packages/…/project-mentions.ts• L233-243 server/…/projects.ts• L614-642 server/…/projects.ts• L1462-1502 server/…/projects.ts• L135-166
Goals
Goals are the planning layer for company outcomes. Their hierarchy lets a company keep broad intent visible while breaking it into smaller goals that can be owned and connected to project work.
Goal hierarchy
Each goal belongs to a company and may point to a parent goal. Its level, status, description, and owning agent provide the context needed to understand the outcome and who is responsible for it. The hierarchy is exposed as a tree in the goals view and as sub-goals in a goal detail view. packages/…/goals.ts• L12-28 ui/…/Goals.tsx• L23-59 ui/…/GoalDetail.tsx• L111-205
Projects linked to a goal appear beside its child goals. This gives a goal page two related views: the next layer of intent and the work areas that support the current outcome. ui/…/GoalDetail.tsx• L68-117 ui/…/GoalDetail.tsx• L179-223
References: packages/…/goals.ts• L12-28 ui/…/GoalDetail.tsx• L68-117 ui/…/GoalDetail.tsx• L179-223
Goal views
The goals page is a company-scoped tree with a direct action to create a goal. The goal detail page allows inline editing of the title and description, shows status and level, and uses tabs for sub-goals and linked projects. packages/…/goals.ts• L12-28 packages/…/goal.ts• L3-14 server/…/goals.ts• L14-79 ui/…/Goals.tsx• L14-59 ui/…/GoalDetail.tsx• L68-224
References: packages/…/goals.ts• L12-28 packages/…/goal.ts• L3-14 server/…/goals.ts• L14-79 ui/…/Goals.tsx• L14-59 ui/…/GoalDetail.tsx• L68-117
Teams
Paperclip represents an operating team through company agents and their reporting relationships. A catalog team is a reusable definition that can add a coordinated set of agents and related company work to an existing company.
Agent hierarchy
The company agent hierarchy gives teams their reporting shape. Catalog definitions identify root agents and other members. During installation, root agents can attach to an existing company manager, or the package can be used as a full-company group when the definition allows it. server/…/teams-catalog.ts• L745-800 ui/…/TeamCatalog.tsx• L493-523 ui/…/TeamCatalog.tsx• L1465-1545
Company controls can require board approval before new agents are added and can set governance for issue-thread interaction resolution. These controls shape how a team enters the company and how its work interactions are handled. packages/…/company.ts• L17-35
The hierarchy matters because it preserves responsibility as a reusable team moves into a company. The catalog preview shows root agents and members before import, so the operator can choose where the new group belongs rather than discovering the reporting shape after installation. A team marked for a company root can instead be used as a full-organization package with no target manager. ui/…/TeamCatalog.tsx• L493-523 ui/…/TeamCatalog.tsx• L1465-1545
References: packages/…/company.ts• L17-35 server/…/teams-catalog.ts• L745-800 ui/…/TeamCatalog.tsx• L493-523 ui/…/TeamCatalog.tsx• L1465-1545
Catalog team definitions
A catalog team definition describes a packaged group rather than only a list of agents. It includes the team kind, category, description, recommended company types, agent and project slugs, counts, root agents, required skills, environment inputs, source references, trust level, compatibility, and content hash. This metadata lets the product explain the package before it changes company state. packages/…/teams-catalog.ts• L76-110 packages/…/teams-catalog.ts• L78-113
Definitions may be bundled or optional. Their trust and compatibility information tells the operator whether the package contains only text, includes static assets, contains executable scripts, or needs external sources. A definition can also expose its files for review, with TEAM.md as its entry point. The catalog UI marks invalid packages as blocked and marks installed packages as current or out of date from server-provided installation state. packages/…/teams-catalog.ts• L10-32 packages/…/teams-catalog.ts• L76-107 server/…/teams-catalog.ts• L265-348 ui/…/TeamCatalog.tsx• L671-859 ui/…/TeamCatalog.tsx• L2348-2363
References: server/…/teams-catalog.ts• L192-221 server/…/teams-catalog.ts• L265-348 packages/…/teams-catalog.ts• L76-110 packages/…/teams-catalog.ts• L78-113 ui/…/TeamCatalog.tsx• L671-859 ui/…/TeamCatalog.tsx• L2348-2363
Catalog installation flow
Catalog installation is a review-first flow. The operator chooses a target manager when needed, reviews source policy and prerequisite skills, inspects the import plan, and then installs the selected company package. The preview can show name collisions, adapter choices, required secret or environment inputs, and the planned agents, projects, and starter tasks. ui/…/TeamCatalog.tsx• L865-1062 ui/…/TeamCatalog.tsx• L1094-1429 ui/…/TeamCatalog.tsx• L1767-2019
The server checks compatibility, trust, and source requirements before import. It uses the company portability flow to apply the package, records catalog provenance on imported entities, and reports warnings for unresolved or separately installed skills. Later, the catalog can compare the installed origin hash with the current package hash and mark a present team as out of date. server/…/teams-catalog.ts• L769-811 server/…/teams-catalog.ts• L841-1025
The browser separates preview from install. Preview describes the same target, collision, and source decisions that install will apply. Install can add adapter overrides and entered environment values, while required inputs or unavailable adapters block the action. If the single install request fails after partial work, the UI tells the operator that the state is not rolled back and points them to the activity log. ui/…/TeamCatalog.tsx• L977-1037 ui/…/TeamCatalog.tsx• L1143-1221 ui/…/TeamCatalog.tsx• L1247-1277 ui/…/TeamCatalog.tsx• L1365-1379
The catalog keeps installed teams in a separate installed group and preserves search and filter state while the operator moves between the list, detail view, and package files. On small screens it changes from a split view to a list followed by a detail sheet-like view. ui/…/TeamCatalog.tsx• L2260-2384 ui/…/TeamCatalog.tsx• L2486-2623
This diagram shows the relationship between catalog metadata, operator review, and company records.
flowchart LR
Catalog[Catalog definition] --> Browse[Browse and inspect]
Browse --> Preview[Preview company import]
Preview --> Policy[Source and skill checks]
Policy --> Install[Install package]
Install --> Agents[Company agents]
Install --> Projects[Company projects]
Install --> Tasks[Starter tasks]
Install --> Provenance[Catalog provenance]
Provenance --> Updates[Out-of-date status]
References: server/…/teams-catalog.ts• L65-120 server/…/teams-catalog.ts• L841-1025 ui/…/TeamCatalog.tsx• L865-1062 ui/…/TeamCatalog.tsx• L1094-1429 ui/…/TeamCatalog.tsx• L1767-2019 ui/…/TeamCatalog.tsx• L2260-2623
Folders
Folders are navigation and grouping records for company routines and installed skills. They do not replace goals or projects. Their purpose is to make a large set of reusable operating resources easier to browse and move.
Folder organization
Folders are company-scoped and typed as either routine or skill folders. They can be nested, have a stable path and position, and report item counts. Unfiled items remain visible as a separate system choice, so placing an item in a folder is not required for it to remain discoverable. packages/…/folders.ts• L15-53 packages/…/folder.ts• L1-28 server/…/folders.ts• L159-175
Skill folders include distinct system-managed areas for personal skills, project skills, and bundled skills. These areas connect folder navigation to user-owned resources and project or catalog content. System-managed and bundled folders are read-only, while company folders can be created, renamed, recolored, nested, moved, and deleted. server/…/folders.ts• L178-212 server/…/folders.ts• L460-576 ui/…/SkillFolderTree.tsx• L280-409
References: packages/…/folders.ts• L15-53 packages/…/folder.ts• L1-28 server/…/folders.ts• L159-212 server/…/folders.ts• L460-576 ui/…/SkillFolderTree.tsx• L280-409
Folder views
The folder UI presents a desktop rail and a mobile sheet. Both show counts, nested paths, the all and unfiled views, and the system namespaces. Users can create folders, move items, create subfolders while moving an item, and manage editable folders without exposing controls for protected areas. ui/…/FolderControls.tsx• L156-264 ui/…/FolderControls.tsx• L528-604 ui/…/SkillFolderTree.tsx• L125-469 ui/…/SkillFolderTree.tsx• L812-1021
References: packages/…/folders.ts• L15-53 packages/…/folder.ts• L1-58 server/…/folders.ts• L26-171 server/…/folders.ts• L159-243 server/…/folders.ts• L300-399 ui/…/FolderControls.tsx• L609-736
Memberships
Memberships serve two different purposes. Project access memberships protect private project records, while resource memberships give a user a personal view of shared projects or agents.
Project access memberships
Project access memberships name the users and agents who can read a private project. The privacy owner or an administrator manages this list, and every principal must belong to the same company. The privacy owner remains protected from removal so the project always has an accountable owner. server/…/projects.ts• L189-245 server/…/projects.ts• L581-669 server/…/projects.ts• L90-149
This authorization state is checked before project detail, workspace, repository, and runtime data are returned. It is not the same as joining or starring a project for personal navigation. server/…/projects.ts• L337-389 server/…/projects.ts• L671-795
References: server/…/projects.ts• L189-245 server/…/projects.ts• L337-389 server/…/projects.ts• L581-669 server/…/projects.ts• L671-795 server/…/projects.ts• L90-149
Resource membership state
A project membership has a joined or left state and may have a star time. Starring a resource implies that the user joined it. Leaving a resource clears its star, so the personal navigation state cannot point to a resource the user has left. packages/…/project_memberships.ts• L5-30 server/…/resource-memberships.ts• L253-343
Membership state is separate from visibility and authorization. The project list first shows resources the actor may read, then uses the current user's membership snapshot to group joined and left projects. The server also checks that the user updates only their own membership and that the company access is active. server/…/projects.ts• L337-363 server/…/resource-memberships.ts• L60-97 server/…/resource-memberships.ts• L107-173 ui/…/Projects.tsx• L105-118
References: packages/…/project_memberships.ts• L5-30 server/…/projects.ts• L337-363 server/…/resource-memberships.ts• L60-97 server/…/resource-memberships.ts• L107-173 ui/…/Projects.tsx• L105-118
Membership views
The projects page exposes join, leave, and star actions on each project. Project detail keeps the same actions available and shows a notice when the user left the current project. The UI applies the change optimistically, restores the previous snapshot after an error, and refreshes the server view when the request settles. ui/…/Projects.tsx• L205-271 ui/…/ProjectDetail.tsx• L691-803 ui/…/useResourceMemberships.ts• L43-99 ui/…/useResourceMemberships.ts• L147-198
References: packages/…/project_memberships.ts• L5-30 server/…/resource-memberships.ts• L56-130 server/…/resource-memberships.ts• L176-251 ui/…/resourceMemberships.ts• L8-20 ui/…/useResourceMemberships.ts• L101-198 ui/…/ProjectDetail.tsx• L691-803
API and UI surfaces
The API and web UI expose the same company work model at different levels. API routes enforce company access and return resource records. Pages turn those records into planning trees, work lists, detail views, and operator workflows.
API resource surfaces
The main API entry points are grouped by company or resource. Creation and list routes use a company identifier. Detail, update, and delete routes use the resource identifier after the server confirms access. Project identifiers can also be short references when the server can resolve them uniquely within the company.
| Area | Main API surface | Product purpose |
|---|---|---|
| Goals | /api/companies/{companyId}/goals, /api/goals/{goalId} | List, inspect, create, update, and remove goals. |
| Projects | /api/companies/{companyId}/projects, /api/projects/{projectId} | Discover, inspect, create, update, archive, and remove projects. |
| Project access | /api/projects/{projectId}/access-members | Read and manage the users and agents allowed to access a private project. |
| Project repositories | /api/companies/{companyId}/project-repositories, /api/projects/{projectId}/repositories | Select the repositories that become project workspaces. |
| Project environments | /api/companies/{companyId}/project-environments | Show execution environments available for project work. |
| Git authorization | /api/projects/{projectId}/git-authorization | Read or set the signed-in user’s project repository authorization. |
| Workspaces | /api/projects/{projectId}/workspaces | Manage project code and work locations. |
| Workspace runtime | /api/projects/{projectId}/workspaces/{workspaceId}/runtime-services/{action} | Start, stop, restart, or run configured workspace actions. |
| Project objects | /api/projects/{projectId}/external-object-summary | Show external records linked to a project when the feature is enabled. |
| Folders | /api/companies/{companyId}/folders | List and manage routine or skill folder trees and item placement. |
| Memberships | /api/companies/{companyId}/resource-memberships/me/... | Read and change the current user's project and agent membership state. |
| Team catalog | /api/teams/catalog, /api/companies/{companyId}/teams/catalog/... | Browse definitions, inspect files, preview imports, install teams, and read installed status. |
The route layer validates request shapes and checks company or resource access before it calls the relevant service. Project routes also resolve short project references within a company and reject ambiguous names. Project discovery filters unauthorized records before it builds a public page. Project writes validate goal, privacy, workspace source, decision-owner membership, environment bindings, and execution environment rules. Workspace changes and runtime controls apply extra policy checks because they can affect execution environments and running services. Catalog installation adds a stronger permission check because it can create agents and import company work. server/…/goals.ts• L14-79 server/…/projects.ts• L135-245 server/…/projects.ts• L297-519 server/…/projects.ts• L521-669 server/…/projects.ts• L671-1072 server/…/folders.ts• L26-49 server/…/teams-catalog.ts• L88-120
References: server/…/goals.ts• L14-79 server/…/projects.ts• L135-245 server/…/projects.ts• L297-519 server/…/projects.ts• L521-669 server/…/projects.ts• L671-1072 server/…/folders.ts• L26-49 server/…/teams-catalog.ts• L88-120
UI resource surfaces
The web application provides focused pages for the same model. The page choice depends on whether the reader is planning outcomes, inspecting a work area, organizing reusable resources, or installing a team package.
| UI surface | Main role |
|---|---|
| Goals | Browse the goal tree and open a goal with its sub-goals and linked projects. |
| Projects | Browse company projects and open a project work area. |
| Project detail | Review the summary, tasks, project fields, workspaces, configuration, budget, memberships, and extensions. |
| Team catalog | Search and filter definitions, inspect hierarchy and files, preview an import, and install or reinstall a team. |
| Folder rail and mobile sheet | Browse routine or skill folders, filter by location, and move or manage folder items. |
| Membership controls | Join, leave, or star projects and agents for a personal navigation view. |
The Organization work management page gives the company-wide context for these surfaces. The Work products and conversations page covers the documents, comments, artifacts, and external records that attach to the tasks inside projects. The Skills and knowledge sources page covers the skill resources that catalog teams and folders organize. The Chat integrations page covers chat surfaces that connect company work to external conversations.
References: ui/…/Goals.tsx• L14-59 ui/…/Projects.tsx• L79-284 ui/…/ProjectDetail.tsx• L327-433 ui/…/ProjectDetail.tsx• L691-935 ui/…/TeamCatalog.tsx• L2260-2626 ui/…/SkillFolderTree.tsx• L125-469 ui/…/useResourceMemberships.ts• L139-198
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the legacy project goal link and the multi-goal references consistent. Goal detail, project payloads, and catalog imports must agree on which projects appear under a goal, and project writes must reject goals from another company.
- Keep project names, derived short references, reference resolution, and
project://markdown mentions aligned. A name change must not silently break links or open an ambiguous project. - Keep private project visibility, privacy ownership, access members, and every project read path aligned. A user or agent granted access must be able to use the same project, workspace, repository, and runtime surfaces.
- Keep personal private project creation aligned with privacy ownership, access membership, default storage policy, and concurrency protection. A user must not receive duplicate parking projects or lose access to the one that already exists.
- Keep project creation idempotency inputs and activity receipts aligned. A retry with the same key must return the same project, while a reused key with different inputs must not create or select another project.
- Keep project environment bindings aligned with secret normalization, protected-key warnings, and post-save synchronization. A project must not report a saved binding that execution cannot resolve.
- Keep project workspace identity aligned across primary-workspace selection, effective codebase selection, execution context, workspace detail views, repository selection, and runtime control routes. A project must retain one usable primary workspace when workspaces change.
- Keep workspace source rules aligned across project creation, repository selection, workspace updates, and instance environment policy. A project must not store a workspace shape that later execution cannot use.
- Keep the decision-owner rule aligned across project create and update, company membership state, and ownerless decision work. Only an active company user must receive a project’s decision work.
- Keep project storage provider selection aligned across project creation, execution workspace policy updates, and project environment changes. A project must not switch storage after work depends on the original provider.
- Keep list-level task counts and project budgets aligned with the active project filters. A summary card must not describe a different project set from the list.
- Keep catalog content hashes and imported provenance aligned. A change to how provenance is written can make installed teams appear current or stale incorrectly.
- Keep catalog preview and install request shapes aligned. The preview must describe the same collision, source, manager, skill, adapter, and environment decisions that the install applies.
- Keep company agent-approval and interaction-governance fields aligned with the team creation and issue-thread flows that consume them.
- Keep folder kind and system namespace checks aligned between folder routes, item moves, and the folder tree. A routine item must not enter a skill tree, and protected catalog or project areas must remain read-only.
- Keep membership state rules aligned between server updates and optimistic UI state. Starred resources must remain joined, and leaving must remove the star.
- Keep company access checks aligned with resource-level project filtering and membership updates. A selected company or resource URL must not become an authorization shortcut, and short project references must resolve only inside that company.
- Keep workspace source rules and runtime policy checks aligned across project create, workspace update, and runtime control requests. A local path or command that the instance policy forbids must not enter project state through another route.
- Keep project route aliases and detail-page tab redirects aligned. A short reference or legacy tab path must resolve to the same project and preserve the intended view.
- Keep isolated-workspace availability checks aligned with the project detail tab. The UI must not expose a workspace view when the instance or project has no usable workspace data.
- Keep project budget updates aligned with project, company, and dashboard summaries. A saved policy must invalidate every view that reports the project budget.
- Keep catalog risk labels, source-policy choices, and browser install limits aligned. A package marked installable in the catalog must not contain a source the browser flow cannot handle.
- Keep installed-team grouping and out-of-date state aligned with catalog provenance. Reinstall and update signals must use the current company installation state.
- Keep responsive catalog routes and filter query state aligned. Selecting a team or file must not reset the active search or filter context.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A project uses a stale or ambiguous short reference | The UI can open the wrong project or fail to resolve the intended one | Resolve short references within the company and reject ambiguous matches. |
| A project name changes without preserving its link contract | Existing project:// references or short URLs can stop resolving to the intended project | Keep derived project references and mention parsing tied to the project identity. |
| A project links to a missing goal or to a goal in another company | The write can fail with an unclear database error or expose a cross-company planning link | Validate every goal reference against the project company before saving the link set. |
| A private project has a missing owner or an invalid access principal | The project can become inaccessible or expose work to a user or agent outside the company | Require a company principal, protect the privacy owner, and check project authorization before each read. |
| A personal private project is created concurrently for the same user | The user can receive duplicate private parking projects or inconsistent access state | Use the company-and-user identity with transaction locking and the unique project rule before adding access. |
| A discovery page is built before project authorization filters run | A denied project can consume a page slot or leak its identity through paging | Apply the per-project access decision before returning summaries or cursors. |
| A project creation retry reuses an idempotency key with different inputs | The caller can mistake a different project for the requested one or create duplicate work | Store an input fingerprint and reject a key whose inputs differ. |
| A project assigns decision work to an inactive or outside-company user | Ownerless decisions can go to a user who cannot act on them | Allow only board users to set the decision owner and require active company membership. |
| A project stores an invalid environment binding | Project runs can fail or use a value that the instance policy should reject | Normalize bindings, check protected keys, and synchronize the saved project target. |
| A project workspace has no valid source | The workspace cannot provide a code or work location for project execution | Require a local path or repository for local and repository-backed sources. Require a remote reference or repository for managed remote sources. |
| An instance forbids local folders but a project write includes one | The project stores a path that the selected execution mode cannot use | Reject workspace paths when managed-sandbox-only policy is active. |
| A project workspace has no usable local path when a workspace command needs one | Project runtime control cannot run the requested action | Require a local workspace path before running workspace commands. |
| A runtime command does not match its configured job or service | A job may be started as a service or a service may be run as a one-shot job | Enforce the action allowed by the selected workspace command kind. |
| A caller bypasses project or runtime access checks | An actor can read a project or change its running workspace services outside its authorization boundary | Filter project lists and guard detail, workspace, and runtime operations before mutation or response. |
| A project is deleted while retained task workspaces or unsettled execution charges remain | Deletion can remove the project context needed by active work or billing settlement | Block deletion until retained workspaces are cleaned up and admitted charges have settled. |
| A catalog definition is incompatible, invalid, unsafe, or blocked by source policy | Installation stops or produces an incomplete team setup | Preview and prepare the source before import, then reject preparation errors. |
| The preview and install options differ | The operator can approve one import plan while the server applies another | Build both requests from the same target, collision, source, skill, adapter, and environment decisions. |
| Required team inputs or a usable agent adapter are missing | Install is blocked or creates agents that cannot run as intended | Require required values and an enabled adapter before the install request. |
| An install fails after some entities are imported | The company can contain partial team state that the operator assumes was rolled back | Report the partial-state condition and direct the operator to the activity log before retrying. |
| An installed catalog team has a changed content hash | The company can run an older definition without knowing that an update exists | Store catalog provenance and compare installed origin hashes with the current catalog hash. |
| A company agent or interaction policy is not enforced by its consuming flow | A team can be added without required approval or use the wrong interaction handling | Apply company governance at the agent-creation and interaction-resolution boundaries. |
| A user changes membership for another user or an inactive company | Personal navigation state can be changed outside its ownership boundary | Require a board user, require self-membership, and verify active company access. |
| A folder move crosses kinds, enters its own subtree, or targets a protected namespace | The folder tree can become invalid or system content can be changed | Validate folder kind, ancestry, depth, and system-managed status before mutation. |
| A project route alias and detail-page redirect use different project identity rules | A user can lose the intended tab or see stale project data after canonicalization | Resolve the route reference in the company context and redirect only after the fetched project confirms its canonical identity. |
| The workspace tab is shown without isolated-workspace support or usable summaries | The project page offers a view that cannot load meaningful workspace data | Gate the tab on instance settings and loaded project workspace summaries. |
| A budget mutation updates only the detail view | Project lists or dashboards can show an old budget state | Invalidate project detail, project list, budget overview, and dashboard data after a policy change. |
| A catalog filter or team-file route drops query state | The operator loses search context and can review or install the wrong package | Preserve catalog filter parameters across team and file navigation. |
Key files
| File | Why to read it |
|---|---|
| packages/…/company.ts | Defines company-level agent approval and interaction governance settings. |
| packages/…/goals.ts | Defines the company goal tree and goal ownership fields. |
| packages/…/projects.ts | Defines the project work area and its planning fields. |
| packages/…/project_goals.ts | Shows the project-to-goal relationship used for multi-goal support. |
| packages/…/project_workspaces.ts | Defines the repository, path, remote, and primary-workspace context. |
| packages/…/project_memberships.ts | Defines personal project join and star state. |
| packages/…/folders.ts | Defines nested routine and skill folder organization. |
| packages/…/project-mentions.ts | Defines stable project links and project ID extraction from markdown. |
| server/…/projects.ts | Assembles project goals, private access, decision ownership, personal private projects, workspaces, codebase context, list metrics, name resolution, runtime state, repository selection, environment bindings, idempotent project relationships, deletion guards, and plugin-managed projects. |
| server/…/projects.ts | Shows project and workspace API boundaries, short-reference resolution, access checks, private project membership, decision-owner validation, source validation, environment policy, environment binding checks, idempotent creation, and runtime control checks. |
| server/…/goals.ts | Shows the goal API lifecycle. |
| server/…/teams-catalog.ts | Shows catalog browse, preview, install, and installed-state routes. |
| server/…/teams-catalog.ts | Explains the high-level catalog import and provenance flow. |
| server/…/folders.ts | Explains folder hierarchy, system namespaces, and item placement rules. |
| server/…/resource-memberships.ts | Explains personal membership state and its access policy. |
| ui/…/ProjectDetail.tsx | Shows the project detail surface that joins summary, tasks, workspaces, configuration, budget, memberships, and plugin extensions. |
| ui/…/GoalDetail.tsx | Shows how goal hierarchy and linked projects meet in the UI. |
| ui/…/TeamCatalog.tsx | Shows catalog discovery, risk review, responsive browsing, installation preview, adapter and environment choices, and update status. |
| ui/…/SkillFolderTree.tsx | Shows folder navigation and protected system namespaces. |
| ui/…/useResourceMemberships.ts | Shows how personal membership and star state reach project and agent views. |