Skip to content

feat(plane): read Plane work item relations with issue-graph plane - #53

Open
amitav13 wants to merge 4 commits into
vercel-labs:mainfrom
amitav13:feat/plane
Open

amitav13 wants to merge 4 commits into
vercel-labs:mainfrom
amitav13:feat/plane

Conversation

@amitav13

@amitav13 amitav13 commented Nov 8, 2026

Copy link
Copy Markdown

Problem

issue-graph reads GitHub and Linear, but teams that track work in Plane can't map blockers, epics, and linked PRs before they start work.

Changes

  • issue-graph plane <PROJ-123|url|uuid> reads a work item neighborhood, and --project UUID|IDENTIFIER captures a whole project. Both use the existing work graph, Markdown and JSON output, dashboard, --cluster/--clusters, and --github.
  • Relations come from Plane's v1 relations endpoint, because the blocking and ordering types are only available there. blocking/blocked_by, start_before/start_after, and finish_before/finish_after each become one directed edge, with the same evidence ID from either side. duplicate and relates_to are undirected, and unknown types keep their native name.
  • The reader pages the workspace work item list (v2, 100 per page) before crawling. That list gives each item's project, parent, and state, so children, parents, and items in other projects resolve without extra requests, and each crawled item costs two requests (relations and links). Plane's v2 list ignores id and id__in filters, so items can't be fetched in batches by ID. When the workspace is larger than --max-pages, the reader falls back to per-item lookups and records that in the report's index coverage.
  • Plane Cloud allows 60 requests per minute per key. The REST reader keeps a client-side budget of 50 per minute (PLANE_REQUESTS_PER_MINUTE), honors Retry-After on 429, and prints one note when it starts pacing.
  • Auth is PLANE_API_KEY sent in the X-API-Key header. Self-hosted Plane works through PLANE_API_URL and PLANE_WEB_URL, which must use https except on localhost. Only GET requests are sent.
  • Plane's cancelled state group is stored as canceled, so the dashboard's existing state colors apply.
  • resolveGithubAttachments now accepts any report with the fields it reads (GithubResolvableReport), so Plane reports can use it. Linear behavior is unchanged.
  • New export issue-graph/transport/plane. Docs page /docs/plane, plus README, bundled skill, schema, and an Unreleased changelog section above the release markers.

Not included: browser login (Plane OAuth needs a registered app), Plane's v2-only implements relations, and text mentions.

Visual proof

Fixture output:

$ issue-graph plane ENG-12 --depth 0
# Plane graph · fixture / Engine

Coverage: complete within requested scope · 1 nodes · depth 0

## ENG-12 · Mount the engine behind the staff check

Status: In Progress

https://app.plane.so/fixture/browse/ENG-12/

- ← parent: ENG-10
- ← blocks: ENG-11
- → blocks: ENG-13
- → finishes before: ENG-13
- Link: feat: mount the engine · https://github.com/acme/app/pull/412

Live test against a private Plane Cloud workspace of 170 work items:

  • One neighborhood at depth 1 read 8 items in 5.5 s.

  • A project capture of 80 of 155 items took 193 s at the default budget, with no failed or partial reads. It found 168 blocks, 57 parent, and 3 relates_to edges, plus 19 links. The open count (98) matched Plane's own filtered total.

  • Help, README, docs, and the bundled skill agree

  • Generated content was refreshed from its source

  • Packaging changes were checked against the installed archive (pnpm test:package)

  • A release PR changes the package.json version and the matching CHANGELOG.md notes (not a release PR)

Checks: pnpm lint, pnpm typecheck, pnpm test (956 passed, 58 new), pnpm build, pnpm check:docs, pnpm test:package.

🤖 Generated with Claude Code

Add a Plane provider next to Linear. `issue-graph plane <PROJ-123|url|uuid>`
reads a work item neighborhood and `--project ID|IDENTIFIER` captures a whole
project, both rendered in the existing dashboard.

- Reads the workspace work item list first, so parents, children and
  cross-project items resolve without per-item lookups. Each crawled item then
  costs two requests: v1 relations and v2 links.
- Maps blocking/blocked_by, duplicate, relates_to, start/finish ordering and
  unknown relation types into the shared work graph, with matching evidence
  from both sides of a relation.
- Paces requests to PLANE_REQUESTS_PER_MINUTE (default 50; Plane Cloud allows
  60), honors Retry-After on 429, and supports self-hosted Plane through
  PLANE_API_URL and PLANE_WEB_URL.
- Normalizes Plane's `cancelled` state group to the shared `canceled`.
- `--github` reuses the Linear GitHub link resolver, now typed structurally.
@vercel

vercel Bot commented Nov 8, 2026

Copy link
Copy Markdown

@amitav13 is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

Comment thread src/transports/plane.ts Resolved
Comment thread src/transports/plane.ts Resolved
- Request `fields=all` on v2 work item lists. Without it Plane omits
  `description_html`, so indexed work items reached JSON reports and
  `--cluster` prompts without descriptions.
- Read pending and snoozed intake requests per intake-enabled project (v1
  intake list, one request per project) and add them to the index. Plane
  leaves them out of every work item list and 404s them by ID, so project
  captures skipped them, open counts were low, and linked requests showed
  as unavailable. They link to the project's intake page.
Comment thread src/plane.ts Resolved
- A 403 from the intake list of an intake-enabled project now marks intake
  coverage incomplete. Only 404 (intake removed) and 402 (not in the plan)
  still count as having no requests, because a 403 can hide requests the
  key cannot see.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant