Organization work management
Paperclip organizes work inside a company boundary. A company brings people and agents together with goals, projects, issues, collaboration records, reusable knowledge, cost controls, and shared views of current work.
Company scope
The company is the main product boundary for work. Company-owned records use this context, and each request must stay inside the selected and authorized company.
Company boundary
A company has its own profile, lifecycle state, issue identifier prefix, budget policy, and membership list. Members can be users or agents. The same boundary covers projects, goals, issues, documents, artifacts, activity, and connected external records.
Company setup creates the basic operating context for work. It provides an execution environment and can provision bundled agents. Company settings can later change budget policy and other resources that support execution. server/…/companies.ts• L258-307
Company status controls whether normal work can proceed. Archiving cancels queued wakeups and active runs and asks active agents to stop. Reactivation restores agents paused by the archive action without removing other pause reasons. Lifecycle changes also notify the systems that schedule or deliver company work. server/…/companies.ts• L66-115 server/…/companies.ts• L346-403 server/…/companies.ts• L497-551
On a managed instance, a company rename can derive a new issue prefix and re-key the company's issue identifiers. The change is coordinated under a company lock so the name, prefix, and task links remain aligned. server/…/companies.ts• L200-256 server/…/companies.ts• L344-391
References: server/…/companies.ts• L66-115 server/…/companies.ts• L193-256 server/…/companies.ts• L258-307 server/…/companies.ts• L310-495 server/…/companies.ts• L497-551
Company administration
Company administration provides the controls that shape how the company works. It covers company identity, hiring approval, interaction governance, observability, budget settings, and lifecycle actions. These controls change company operation without changing the meaning of its work records.
Connections add company-scoped controls for decision behavior, prompt protection, and optional fast responses. Together, these settings define the operating rules used by the company's people and agents.
References: ui/…/CompanySettings.tsx• L216-240 ui/…/CompanySettings.tsx• L342-418 ui/…/CompanyConnections.tsx• L10-44
Company selection
The web application works on one selected company at a time. The selected company supplies the context for pages such as the dashboard, projects, goals, issues, artifacts, and search. Selection is separate from authorization: server routes still check company access before they read or change data.
References: ui/…/CompanyContext.tsx• L104-198 server/…/companies.ts• L353-361 server/…/projects.ts• L118-143
Company portability
Company portability turns selected company work into a package that can be reviewed, downloaded, and restored. Import can target a new company or an existing one. The operator can preview changes, choose collision rules, resolve names, and decide which imported agents or routines remain paused until review.
The apply step runs as a server-side job. The import surface can resume watching that job after a reload and can resume large transfers from verified parts. This makes portability a controlled transfer of company context rather than a direct copy of raw records.
References: ui/…/CompanyImport.tsx• L763-917 ui/…/CompanyImport.tsx• L1279-1422 ui/…/CompanyImport.tsx• L1641-1800 ui/…/CompanyImport.test.tsx• L866-1180
Work hierarchy
Paperclip connects strategic intent to visible work. Goals express desired results. Projects provide shared work areas. Issues provide the task records that people or agents can own and move forward.
Organizational structure
Agents belong to a company and can report to another agent. This creates the operating hierarchy used to represent team leads and their members. Reusable catalog teams can seed a company with a working group and preserve or remap its hierarchy.
The Projects, goals, and teams page explains this structure in more detail. It covers memberships, folders, and catalog-provided definitions.
References: packages/…/agents.ts• L14-45 server/…/teams-catalog.ts• L740-800 ui/…/TeamCatalog.tsx• L642-777
Goals and projects
Goals form a company-scoped planning tree. Projects sit below that planning layer and can support more than one goal. The project model checks that linked goals belong to the same company, then keeps the full goal relationship set aligned with the older single-goal view. server/…/projects.ts• L509-545 server/…/projects.ts• L674-716 server/…/projects.ts• L997-1078
Projects provide shared areas for planned work. They have a status, lead, target date, visibility, and task and budget summaries. Project lists derive task counts from project issues and show active billed-budget policies for each project. A private project creates a narrower boundary inside the company. Each user can also have a private personal project for work that is visible only to explicitly granted people and agents. Its issue tree follows that boundary while assigned people and agents retain access needed to do their work. server/…/projects.ts• L84-144 server/…/projects.ts• L111-150 server/…/projects.ts• L429-507 server/…/projects.ts• L1054-1078
Projects also have readable references. The product avoids resolving an ambiguous short name to an arbitrary project. Plugin-managed projects remain part of the same company project model while an external plugin supplies their declaration or operations. server/…/projects.ts• L614-642 server/…/projects.ts• L788-946 server/…/projects.ts• L1462-1502
The Projects, goals, and teams page covers the planning tree and company organization model in detail.
References: packages/…/goals.ts• L12-28 packages/…/projects.ts• L7-30 packages/…/project_goals.ts• L6-20 server/…/projects.ts• L429-545 server/…/projects.ts• L674-716 server/…/projects.ts• L788-946 server/…/projects.ts• L997-1090 server/…/projects.ts• L1462-1502
Project workspaces
Project workspaces connect planned work to a code repository, local folder, or managed remote work area. A project can have several workspaces, but one primary workspace supplies the project's main code context. Workspace changes preserve a usable primary source and can refresh project-linked knowledge when repository details change. server/…/projects.ts• L289-425 server/…/projects.ts• L1135-1240 server/…/projects.ts• L1241-1402
Workspace runtime controls support services and jobs that belong to the project workspace. These controls have their own runtime state. Stopping a workspace runtime does not pause issue work or its wake schedule. A project keeps the workspace storage provider selected at creation, which prevents later changes from detaching its work area from the provider that owns it. server/…/projects.ts• L1005-1019
References: server/…/projects.ts• L240-425 server/…/projects.ts• L922-967 server/…/projects.ts• L1005-1019 server/…/projects.ts• L1114-1460
Issues and boards
An issue is the product's task record. It can belong to a company, project, and goal. It can also have a parent, an assignee, a responsible user, a priority, and a work status. These links show both the task and its place in the larger plan.
The board is the human control point for company work. Board operators can create and manage work, review activity, and use the company dashboard. The Conference Room keeps its long-running conversation on a standing Board Operations issue, so board discussion has a durable work record.
References: packages/…/issues.ts• L22-77 server/…/board-chat.ts• L148-205 server/…/board-chat.ts• L353-380
Organizational responsibilities
Organizational responsibilities make ownership explicit across the company work model. Projects identify a lead, while issues identify the people or agents that execute work and the user responsible for it. These relationships let planning, execution, and review use the same accountability model.
The Organizational responsibilities page explains responsibility assignments and the boundaries between company, team, project, and issue ownership.
References: packages/…/agents.ts• L14-45 packages/…/issues.ts• L22-77 server/…/projects.ts• L84-144
Work visibility
Work visibility combines focused work pages with company-wide views. The dashboard summarizes current health. Activity traces changes. Search helps people find the records that support a decision.
Dashboard summary
The company dashboard turns current company state into an operating summary. It shows agent state, task load, blocked work, spend against budget, pending approvals, recent runs, and recent activity. It uses the same issue visibility rules as other work views so hidden or internal records do not distort the summary.
References: server/…/dashboard.ts• L26-48 server/…/dashboard.ts• L188-210 ui/…/Dashboard.tsx• L306-461 server/…/issue-visibility.ts• L4-10
Activity timeline
Activity is the company record of meaningful changes and actions. A company timeline can narrow events by goal, project, issue, user, or time range. Activity records link changes to users, agents, runs, or system actions, which lets the board trace why work changed.
References: server/…/activity.ts• L175-271 server/…/companies.ts• L394-446
Company search
Company search provides one discovery surface for tasks, comments, documents, artifacts, agents, and projects. It returns filtered matches and links back to the source record. Search is a visibility aid rather than a second work model, so it keeps the same company and issue visibility boundaries.
References: server/…/company-search.ts• L416-429 server/…/company-search.ts• L557-583 server/…/company-search.ts• L704-735 ui/…/Search.tsx• L62-83
Work-product collaboration
Work includes reasoning and outputs as well as task state. Documents, comments, attachments, and other products remain linked to issues so people can review results and find the context later.
Artifacts and work products
Artifacts provide a company-wide view of issue outputs. They bring together issue documents, work-product records, and file attachments. Each item points back to the issue and, when present, its project.
An issue work product is a named output with a provider, status, review state, health state, and optional link or summary. The Work products and conversations page explains how these outputs relate to documents, comments, annotations, files, and external objects.
References: packages/…/issue_work_products.ts• L18-43 server/…/company-artifacts.ts• L318-347 server/…/company-artifacts.ts• L723-770 ui/…/Artifacts.tsx• L64-79
Conversations
Issue comments provide the conversational record for a task. They support human and agent participation and remain attached to the issue that gives the discussion its purpose. This makes conversation part of work visibility rather than a detached chat log.
The Work products and conversations page covers comments, documents, annotations, files, and external objects in more detail.
References: server/…/board-chat.ts• L152-205 server/…/board-chat.ts• L353-380 server/…/company-search.ts• L613-669 server/…/activity.ts• L341-347
Skills and knowledge sources
Skills give a company reusable knowledge and behavior that agents can use across work. A company skill catalog makes this knowledge visible as a managed resource instead of hidden instructions attached to one task.
Company skill catalog
The company skill catalog provides one place to install, discover, create, import, and review reusable skills. Skills can come from company content, catalog content, GitHub, a URL, or a local source. They can be organized in folders, scanned from project workspaces, and attached to agents.
Installation and agent use are separate states. Installing adds a skill to the company library. Enabling it for an agent determines who can use it. Protected or read-only skills can be copied or forked so their source remains unchanged.
The Skills and knowledge sources page explains source provenance, snapshots, versions, sharing, and access boundaries in more detail.
References: ui/…/CompanySkills.tsx• L270-290 ui/…/CompanySkills.tsx• L655-746 ui/…/CompanySkills.tsx• L1394-1626 ui/…/CompanySkills.tsx• L1938-2251 ui/…/CompanySkills.test.tsx• L667-722 ui/…/CompanySkills.test.tsx• L1004-1145
Company integrations
External chat integrations extend company work into systems where teams already communicate. They preserve company context while allowing messages, task updates, and review signals to move between Paperclip and external chat.
External chat
Slack and GitHub chat connections provide another access path to company work. Inbound events and published updates still resolve to company-scoped records, so external chat does not create a second work model.
The Chat integrations page explains connection management, authorization, inbound events, task updates, reviews, and conversation state.
References: .greptile-internal/…/knowledge-base-docs-steering.json• L14
Company work flow
The company model connects setup, planning, execution, collaboration, and review. Each stage keeps the company context so a user can move from intent to work and then to evidence.
This diagram shows how company context turns planning into assigned work and then into visible outputs.
flowchart TD
Company[Company boundary] --> Structure[Teams and agent hierarchy]
Company --> Goals[Goals]
Goals --> Projects[Projects]
Projects --> Issues[Issues and task relations]
Goals --> Issues
Structure --> Issues
Issues --> Collaboration[Comments and documents]
Issues --> Outputs[Artifacts and work products]
Issues --> Activity[Activity and timeline]
Projects --> Search[Company search]
Collaboration --> Search
Outputs --> Search
Issues --> Dashboard[Dashboard summary]
Activity --> Dashboard
Company --> Skills[Skills and knowledge sources]
Company --> Chat[External chat integrations]
Chat --> Issues
When a company is created, the board can establish its working group. Goals and projects give that group a plan. Issues carry the work, and assignments connect each task to a responsible user or agent. Outputs and conversations stay attached to the issue, while dashboards, activity, search, skills, and chat provide different ways to inspect or support the same records.
References: server/…/companies.ts• L258-307 server/…/teams-catalog.ts• L841-962 packages/…/issues.ts• L22-77 server/…/dashboard.ts• L188-210 server/…/company-search.ts• L557-735
Related pages
- Projects, goals, and teams explains the planning tree, team structure, memberships, folders, and catalog definitions.
- Work products and conversations explains artifacts, documents, comments, annotations, external objects, files, and collaboration search.
- Skills and knowledge sources explains skill catalogs, source provenance, snapshots, versions, and access boundaries.
- Budgets and cost controls explains budgets, spend, policy, and cost control behavior.
- Organizational responsibilities explains ownership across company, team, project, and issue work.
- Chat integrations explains how external chat systems connect company work with conversations outside Paperclip.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep company identifiers aligned across route paths, query keys, resource links, and authorization checks.
- Keep company status changes aligned with wakeups, agent lifecycle, run dispatch, chat notices, and other delivery work.
- Keep managed-company rename behavior aligned with issue prefix re-keying and user-facing task links.
- Keep company budget settings aligned with budget policy, accounting activity, spend totals, and dashboard values.
- Keep project goal validation, the full goal relationship set, and the legacy single-goal field aligned.
- Keep project list task counts and budget summaries aligned with issue filters and active project budget policies.
- Keep project visibility aligned with issue privacy propagation, assignment access, and project access checks.
- Keep project references, short-name collision handling, and canonical links aligned.
- Keep primary workspace selection aligned with project code context, repository changes, and project-linked skill sources.
- Keep workspace runtime controls separate from issue lifecycle and wake scheduling.
- Keep project deletion aligned with retained workspace access policy and unsettled execution charges.
- Keep plugin-managed project storage bindings aligned with plugin declarations, project updates, and dependent workspace records.
- Keep issue visibility rules aligned between task lists, dashboard counts, search, artifacts, and activity.
- Keep skill installation separate from agent enablement and keep protected sources separate from editable copies.
- Keep external chat connection scope, authorization, and conversation mapping aligned with the target company and work record.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A company is archived while agents or runs are active | Wakeups are cancelled and active execution stops until the company is reactivated. | Archive handling cancels queued work, records the pause reason, and fences active agent stops. |
| A managed company is renamed without re-keying its issues | Task identifiers no longer match the company prefix and old links can fail. | The rename path locks the company and re-keys issue identifiers in the same update flow. |
| A project links to a goal from another company | Planning shows a false cross-company relationship. | Project creation and update validate every goal against the project company. |
| A project list counts conversation issues as task work | Project task summaries overstate work owned by the project. | List metrics exclude conversation-agent issues from the task count. |
| A private project changes without updating its issue tree | Child work can remain visible outside the project boundary. | Project updates propagate privacy through related issues while preserving assignment access. |
| A project has no valid workspace source | Code context and workspace operations cannot provide a usable work area. | Workspace creation and update require a local path, repository, or valid managed reference. |
| A workspace source changes without refreshing dependent records | Project code context or linked skills can point to stale source data. | Workspace mutations preserve the primary workspace and refresh or retire dependent records. |
| A project is deleted while retained workspace policy or unsettled execution charges remain | Access rules or cost records can lose their project owner. | Deletion is blocked until retained workspace access is cleaned up and admitted charges settle. |
| A plugin-backed project changes storage provider | Project workspaces can detach from the provider that owns their storage. | Project updates reject provider changes and retain the existing storage binding. |
| A skill is installed but not enabled for an agent | The agent cannot use knowledge that appears in the company library. | Installation and agent attachment remain separate actions. |
| An external chat event has no valid company mapping | A message or task update can be dropped or attached to the wrong work record. | Connection and authorization checks resolve the target company before processing. |
Key files
| File | Why to read it |
|---|---|
| server/…/companies.ts | Shows company creation, lifecycle changes, budget policy updates, spend totals, and managed issue-prefix behavior. |
| ui/…/CompanyContext.tsx | Shows how the web application selects and preserves the active company. |
| server/…/projects.ts | Shows how projects connect goals, workspaces, metrics, references, plugin bindings, and project-linked skills. |
| packages/…/goals.ts | Defines the goal tree used to express company intent. |
| packages/…/projects.ts | Defines the project work area and its company relationship. |
| packages/…/issues.ts | Defines the task record and its links to planning and ownership. |
| server/…/dashboard.ts | Shows how company work becomes a board-level summary. |
| server/…/company-search.ts | Shows the shared discovery model across work and collaboration records. |
| server/…/company-artifacts.ts | Shows how issue outputs become a company-wide artifact view. |
| server/…/board-chat.ts | Shows how board conversation uses a durable company issue. |
| ui/…/CompanySkills.tsx | Shows skill discovery, installation, versions, agent enablement, and sharing controls. |
| ui/…/CompanyImport.tsx | Shows package preview, transfer recovery, asynchronous import jobs, and post-import activation. |