planpage
Connect an agent

Agents and access

Projects and folders

How projects group documents, how linking a repository lets agents find the right project, and what happens the first time an agent works in a new folder.

Projects

A project collects the documents for one piece of work, usually one repository. Every document belongs to a project, and every project belongs to a workspace. Documents are numbered within their project, as in "#12".

Your projects are listed in the sidebar and on the Projects page. To create one, click New project, give it a name, and optionally a repository URL. Owners, admins, reviewers and members can create projects; viewers can't.

Pick a repository from GitHub

If the workspace has the GitHub app installed, New project lists the repositories it's installed on. Type to filter the list, then click a repository or move to it with the arrow keys and press Enter. planpage fills in Repository URL, and fills in Name with the repository's name unless you've already typed one.

If GitHub isn't connected yet, New project shows a Connect GitHub box in place of the repository field instead. Owners and admins can click Install on GitHub right there; everyone else is told who can. Click Enter a repository URL instead to type a URL without installing the app.

The list is ordered so the likely choice comes first:

  1. repositories no project in the workspace uses yet, most recently pushed first,
  2. archived repositories,
  3. repositories already linked to a project, tagged "Linked to" and the project's name. You can still pick one; two projects can share a repository.

For a GitLab or Bitbucket repository, or a GitHub repository the app isn't installed on, click Enter a URL instead and type the URL. Editing the URL by hand also clears the picked repository.

Everyone who can create projects in the workspace sees every repository the app is installed on, including private ones.

If the workspace hasn't installed the app, owners and admins see an Install on GitHub link. After installing, GitHub sends them back to the form with the list filled in. Other members see a note that an owner or admin can install the app in Workspace settings → Integrations. Either way, you can type a URL as before.

Each project has its own page with Documents, Activity and Project settings tabs. Under Project settings you can rename the project and change its repository URL.

Right-click a project in the sidebar, on the Projects page or in Workspace settings → Projects, or use the ⋯ beside it, for its menu: Open, Copy link, New document here, Write a brief, Rename, Link repository (or Change repository) and Archive. You see the items your role allows.

A project's Repository URL is how agents find it. When an agent starts work in a folder, it reads the folder's git remote and calls resolve_project. planpage compares the remote with each project's repository URL and returns the match.

The comparison ignores the differences between remote formats, so these all match the same project:

  • https://github.com/acme/api
  • https://github.com/acme/api.git
  • git@github.com:acme/api.git

Use an https or git@ URL. One project links to one repository. The GitHub integration uses the same URL to decide which pull requests can link to the project's plans; see GitHub.

The first time in a folder

If no project matches the folder's remote, the agent doesn't guess. It tells you planpage doesn't know where this folder's plans go yet and asks you to choose:

  • one of your existing projects, listed with their workspaces, or
  • a new project, with a name suggested from the repository or folder. When the remote is a GitHub repository the workspace's app is installed on, resolve_project returns its name as suggested_name and the agent uses that.

Then it remembers your answer:

  • For a new project, it calls create_project with the repository URL set. You can choose which workspace it goes in; whoami lists every workspace the connection can reach, including empty ones.
  • For an existing project, it calls link_repository, which saves the remote on the project.

From then on resolve_project finds the project and the agent doesn't ask again. If the project is already linked to a different repository, the agent asks you before replacing the link, or suggests a separate project for this repository.

A folder with no git remote can't be remembered. The agent asks once per session. It can call list_repositories to offer the repositories the workspace's GitHub app is installed on, most recently pushed first, each marked with the project already linked to it. whoami shows, for each workspace, whether the app is installed and how many repositories it covers.

Archive a project

Owners and admins can archive a project from Project settings, with the Archived checkbox in Workspace settings → Projects, or with Archive in the project's menu, which asks first. Archiving hides the project from the sidebar and from agents' project lists. Its documents stay readable, nothing is deleted, and you can restore it in the same places.

Delete a project

Owners and admins delete a project from Workspace settings → Projects: click Delete… on its row, then Move to Trash. In your personal workspace you can delete your own projects.

The project and every document in it disappear for everyone straight away: from lists, search, the Inbox, share links, guests and agents. Anyone with the document open is disconnected.

Deleted projects wait in Trash, at the bottom of the same page, for 30 days. Restore brings the project back as it was, share links included. Delete now deletes it for good at once. After 30 days planpage deletes it for good automatically, with every version, comment, review and activity entry. Agents can archive projects but can't delete them.