# Project pack: Plane @ d9726d5

Facts about **Plane** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Plane is an open-source project tracker, a Jira and Linear alternative. You break work into issues, group them into cycles (sprints) and modules, and view them as lists, boards, calendars or timelines. It also has pages for notes and a public API, and you can run it yourself or use the hosted version.

## Version and source
- Repository: https://github.com/makeplane/plane
- Pinned commit: `d9726d5c9615756135f3d6cd512ece8e2dd42902`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/makeplane/plane/archive/d9726d5c9615756135f3d6cd512ece8e2dd42902.zip
- Official docs: https://developers.plane.so
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/makeplane/plane bespoke-plane
  cd bespoke-plane
  git checkout --detach d9726d5c9615756135f3d6cd512ece8e2dd42902
  # Prepare development requirements and local configuration first.
  corepack enable
  pnpm install
  ./setup.sh
  docker compose -f docker-compose-local.yml up -d
  pnpm dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh
  chmod +x setup.sh
  ./setup.sh
  # choose 1 (Install), then 2 (Start), and open http://localhost
  ```

- Needs: Docker with 4 GB or more of memory; Node 22 and pnpm plus Python 3.12 for development
- Develop: `pnpm dev`
- Test: `pnpm check`
- Check/lint: `pnpm check:lint`
- Build: `pnpm build`
- Stack: typescript, python (React, Next.js, Django, Django REST Framework, Celery, Turborepo, pnpm). Difficulty for a non-developer with an AI: **advanced**. A large monorepo with several web apps, a Django API and background workers. Workspace settings, labels and views need no code. New features touch the web app and API together.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **workspace-setup** [settings]: Your own workflow stages, labels and who can do what. → `Workspace and Project settings (states, labels, estimates, members)`
- **views-and-cycles** [settings]: Saved filters, sprints and roadmaps for different audiences. → `Views, Cycles, Modules in each project`
- **api-and-webhooks** [extend]: Connect Plane to scripts, chat and other tools. → `Settings → API tokens and Webhooks; developers.plane.so`
- **web-ui** [code]: New screens and layouts. → `apps/web/ and packages/ui`
- **api-models** [code]: New fields and endpoints. → `apps/api/plane/db/models and apps/api/plane/app/views`

## Must keep working
- Django migrations in apps/api. Add new ones; never edit old ones.
- Authentication and workspace permissions.
- Background workers (Celery) that send notifications and process imports.

## Staying updatable
Prefer workspace settings, the API and webhooks. If you change code, keep it in new modules and avoid the enterprise folders.

## Data, costs and safety
- Personal data: **yes**. Stored in: Postgres database plus an uploads store (Docker volumes). Back up the Postgres volume and the uploads volume together.
- Service: Email (SMTP) (optional, usually free to a few dollars): Invitations and notifications.
- Service: File storage (built-in MinIO-style store or S3) (optional, free locally): Attachments and images.
- Setting `SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Django secret used to sign sessions. Never paste it into an AI chat.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Postgres connection string. Contains a password.
- Setting `WEB_URL`: The address people use to reach Plane.
- Treat SECRET_KEY and database passwords as secrets and keep them out of Git and chats.
- Review the setup script before running it and keep the stack behind HTTPS if public.

---

# Customising Plane

Plane is a big monorepo, so begin with settings, views and the API. Change source code only for something those cannot do.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Main web app | apps/web/ |
| Admin console and public space | apps/admin/ and apps/space/ |
| Django API and models | apps/api/plane/ (db/models, app/views, bgtasks) |
| Real-time server | apps/live/ |
| Shared UI, editor and types | packages/ui, packages/editor, packages/types |
| Deployments | deployments/ and docker-compose*.yml |

## Use the gentlest change first

1. **Settings (no code):** states, labels, estimates, views, cycles and roles.
2. **Extend:** API tokens and webhooks to connect other tools.
3. **Code:** new fields, screens and background jobs, in new files where possible.

## Recipes

- **New field on issues:** add the model field and a Django migration, expose it in the serializer, then add it to the issue form and list in `apps/web`.
- **New notification rule:** look in `apps/api/plane/bgtasks` and keep it as its own task.

## Running and checking your changes

- Start the local stack with `docker compose -f docker-compose-local.yml up -d`, then `pnpm dev`.
- `pnpm check` runs types, lint and format across packages.
- Create, edit, move and delete an issue to check nothing broke.

## Pitfalls

- Run migrations after pulling or changing models.
- Don't commit `.env` files.
- Plane has a heavy first build. Allow time and memory.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/plane/d9726d5/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/plane/d9726d5/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/plane/d9726d5/r2/SKILL.md)