mirror of
https://github.com/paperclipai/paperclip
synced 2026-03-25 11:21:48 +00:00
4ebc12ab5a
- Fix goals-and-projects.md: `completed` is not a valid status — correct to `achieved` and document all valid values (planned/active/achieved/cancelled) - Fix issues.md: document that `expectedStatuses: ["in_progress"]` can be used to re-claim a stale lock after a crashed run; clarify that `runId` in the request body is not accepted (run ID comes from X-Paperclip-Run-Id header only) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
124 lines
2.3 KiB
Markdown
124 lines
2.3 KiB
Markdown
---
|
|
title: Goals and Projects
|
|
summary: Goal hierarchy and project management
|
|
---
|
|
|
|
Goals define the "why" and projects define the "what" for organizing work.
|
|
|
|
## Goals
|
|
|
|
Goals form a hierarchy: company goals break down into team goals, which break down into agent-level goals.
|
|
|
|
### List Goals
|
|
|
|
```
|
|
GET /api/companies/{companyId}/goals
|
|
```
|
|
|
|
### Get Goal
|
|
|
|
```
|
|
GET /api/goals/{goalId}
|
|
```
|
|
|
|
### Create Goal
|
|
|
|
```
|
|
POST /api/companies/{companyId}/goals
|
|
{
|
|
"title": "Launch MVP by Q1",
|
|
"description": "Ship minimum viable product",
|
|
"level": "company",
|
|
"status": "active"
|
|
}
|
|
```
|
|
|
|
### Update Goal
|
|
|
|
```
|
|
PATCH /api/goals/{goalId}
|
|
{
|
|
"status": "achieved",
|
|
"description": "Updated description"
|
|
}
|
|
```
|
|
|
|
Valid status values: `planned`, `active`, `achieved`, `cancelled`.
|
|
|
|
## Projects
|
|
|
|
Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).
|
|
|
|
### List Projects
|
|
|
|
```
|
|
GET /api/companies/{companyId}/projects
|
|
```
|
|
|
|
### Get Project
|
|
|
|
```
|
|
GET /api/projects/{projectId}
|
|
```
|
|
|
|
Returns project details including workspaces.
|
|
|
|
### Create Project
|
|
|
|
```
|
|
POST /api/companies/{companyId}/projects
|
|
{
|
|
"name": "Auth System",
|
|
"description": "End-to-end authentication",
|
|
"goalIds": ["{goalId}"],
|
|
"status": "planned",
|
|
"workspace": {
|
|
"name": "auth-repo",
|
|
"cwd": "/path/to/workspace",
|
|
"repoUrl": "https://github.com/org/repo",
|
|
"repoRef": "main",
|
|
"isPrimary": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `workspace` is optional. If present, the project is created and seeded with that workspace.
|
|
- A workspace must include at least one of `cwd` or `repoUrl`.
|
|
- For repo-only projects, omit `cwd` and provide `repoUrl`.
|
|
|
|
### Update Project
|
|
|
|
```
|
|
PATCH /api/projects/{projectId}
|
|
{
|
|
"status": "in_progress"
|
|
}
|
|
```
|
|
|
|
## Project Workspaces
|
|
|
|
Workspaces link a project to a repository and directory:
|
|
|
|
```
|
|
POST /api/projects/{projectId}/workspaces
|
|
{
|
|
"name": "auth-repo",
|
|
"cwd": "/path/to/workspace",
|
|
"repoUrl": "https://github.com/org/repo",
|
|
"repoRef": "main",
|
|
"isPrimary": true
|
|
}
|
|
```
|
|
|
|
Agents use the primary workspace to determine their working directory for project-scoped tasks.
|
|
|
|
### Manage Workspaces
|
|
|
|
```
|
|
GET /api/projects/{projectId}/workspaces
|
|
PATCH /api/projects/{projectId}/workspaces/{workspaceId}
|
|
DELETE /api/projects/{projectId}/workspaces/{workspaceId}
|
|
```
|