Projects — ProxifAI Docs

A project is a goal-shaped container for issues. It’s owned by a team, optionally led by a person, has its own date range, and exposes two independent signals — Status (where it is in its lifecycle) and Health (whether it’s on track). The two are separate fields and can move independently.

Anatomy of a project

Field	Type	Notes
`name`, `description`, `key`	strings	`key` is an optional short prefix for issue identifiers within the project
`teamId`	required	Projects are team-scoped
`leadId`	nullable	A user designated as project lead
`status`	enum	Six values — see below
`health`	enum	Four values — see below
`priority`	shared `Priority` enum	Same five values as issues (urgent/high/medium/low/none)
`startDate`, `targetDate`	nullable dates
`progress`	int (0–100)	Computed from issue completion

Source: type Project struct in models.go.

Status (lifecycle)

Six values from ProjectStatus:

Status	Meaning
`backlog`	Idea on the list; not yet planned
`planned`	Scoped and scheduled — start date in the future
`in_progress`	Active work
`paused`	Temporarily on hold; can resume
`completed`	Delivered
`cancelled`	Won’t ship; kept for history

Status changes by hand (a lead/admin moves it) or via automation (e.g. a workflow that flips to in_progress when the first sub-issue starts).

Health (signal, independent of lifecycle)

Four values from ProjectHealth — what most other tools cram into status, ProxifAI keeps separate:

Health	When
`on_track`	Default for active projects with no warning signs
`at_risk`	Schedule slipping or scope ballooning, but recoverable
`off_track`	Won’t make the target date without intervention
`no_updates`	The lead hasn’t pushed an update recently — surface it for follow-up

Health is set explicitly by the lead (or automation). A project can be in_progress + at_risk, paused + on_track, etc.

Status and Health both filter the project list and feed the Roadmap bars. Confusing the two is the most common mistake — keep them in your head as “where is this project in its lifecycle” vs “is the lead happy about how it’s going”.

Creating a project

From the UI

Plan → Projects → New. Pick the owning team, set name, description, optional key, optional dates and lead.

From the CLI

pfai project create "OIDC Login" \
  --team backend --lead alice \
  --target-date 2026-06-30 --priority high

pfai project ls, pfai project view <id>, pfai project update <id> --status in_progress --health at_risk.

Progress tracking

progress is computed from linked issues — done issues divided by total non-cancelled issues, expressed as 0–100. The number updates as issues move; the lead doesn’t manage it manually.

The project dashboard layers on top:

Open vs closed breakdown by priority, label, or assignee
Burndown against targetDate (if set) — projected completion based on velocity
Activity — recent commits, PRs, agent runs, status/health changes

Linking to repositories

Projects are linked to native forge repositories via the LinkNativeRepoToProject endpoint. Once linked:

The project page shows recent commits, PRs, and releases from those repos
Issues created in the project surface on the repo’s issue tab
PRs with Closes #<number> against an issue in this project auto-update the issue

Manage links from Project Settings → Repositories or:

pfai project repos add <project-id> <owner>/<repo>
pfai project repos rm  <project-id> <owner>/<repo>

API: PUT /api/v1/forge/{owner}/{repo}/link with {projectId} body.

A repo can be linked to multiple projects, and a project can link to multiple repos.

Project leads and permissions

The leadId is informational + a default notification target. Permissions on the project flow from team membership and org-level roles, not the lead pointer. Anyone with team write access can edit the project; the lead is just who gets pinged when health degrades or status changes.

Settings

Under Project Settings:

Rename, change description, key, dates
Update status, health, priority manually
Manage linked repositories
Archive (soft-delete; data preserved, hidden from default lists)
Transfer to a different team

pfai project archive <id> does the same. Archived projects are read-only and excluded from progress rollups.

REST endpoints

Method · Path	Purpose
`GET /api/v1/projects?team=&status=&health=...`	List with filters
`POST /api/v1/projects`	Create
`GET /api/v1/projects/{id}`	Read
`PATCH /api/v1/projects/{id}`	Update — `status`, `health`, dates, lead, priority all settable here
`DELETE /api/v1/projects/{id}`	Soft-delete (archive)
`GET /api/v1/projects/{id}/issues`	Issues in this project
`GET /api/v1/projects/{id}/repos`	Linked repos