Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / organization-work-management

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 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

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

TriggerConsequenceGuard
A company is archived while agents or runs are activeWakeups 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 issuesTask 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 companyPlanning 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 workProject 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 treeChild 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 sourceCode 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 recordsProject 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 remainAccess 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 providerProject 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 agentThe 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 mappingA 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

FileWhy to read it
server/…/companies.tsShows company creation, lifecycle changes, budget policy updates, spend totals, and managed issue-prefix behavior.
ui/…/CompanyContext.tsxShows how the web application selects and preserves the active company.
server/…/projects.tsShows how projects connect goals, workspaces, metrics, references, plugin bindings, and project-linked skills.
packages/…/goals.tsDefines the goal tree used to express company intent.
packages/…/projects.tsDefines the project work area and its company relationship.
packages/…/issues.tsDefines the task record and its links to planning and ownership.
server/…/dashboard.tsShows how company work becomes a board-level summary.
server/…/company-search.tsShows the shared discovery model across work and collaboration records.
server/…/company-artifacts.tsShows how issue outputs become a company-wide artifact view.
server/…/board-chat.tsShows how board conversation uses a durable company issue.
ui/…/CompanySkills.tsxShows skill discovery, installation, versions, agent enablement, and sharing controls.
ui/…/CompanyImport.tsxShows package preview, transfer recovery, asynchronous import jobs, and post-import activation.