Skip to content

Organisations and projects

An organisation holds your team and its connections; a project holds one spec with its Main, its workstreams and, optionally, one repository.

Organisations

An organisation is your team in SpecsGraph. It holds what applies to everyone: members and their roles, teams, invitations, Git connections (GitHub App installs and GitLab tokens), the access token policy and billing.

The organisation's slug is the first segment of every URL, as in /northwind/.... A person can belong to several organisations and switches between them from the user menu.

Belongs to the organisationBelongs to a project
Members, roles, teams and invitationsMain, the agreed spec
Git connections: GitHub App installs, GitLab tokensWorkstreams (WS-n) and tasks (T-n)
The access token policyOptionally, one Git repository it publishes to
Billing; see Plans and billingIts settings: General, Teams and Git

Projects

A project is one spec, addressed by a short key inside its organisation, such as shop or identity. It has a name, a description and:

  • Main, the agreed spec, which is read-only;
  • its workstreams (WS-n) and tasks (T-n), numbered per project;
  • optionally one Git repository it publishes to.

Admins and Owners create projects.

One project or several

Split a system into several projects when parts of it are owned and released separately. Keep one project when a change often touches several parts at once, because a task publishes within one project.

Project settings

SectionWhat it holdsWho
GeneralName, description and archive; the tracker link template (https, contains {key}, for example https://example.atlassian.net/browse/{key}); and the Ready rule.Admin and Owner
TeamsThe teams that may edit the project. With no team assigned, every Editor of the organisation may; with teams, only their members plus Admins and Owners. Everyone else reads.Admin and Owner
GitThe repository, base branch, spec folder (default .specsgraph) and publish mode (pull request or direct commit).Admin and Owner

The tracker link template turns a task's tracker key, such as KAN-43, into a link to the story in your tracker; see Tasks and publishing. The Git section is covered in Connect GitHub or GitLab and Branches and pull requests.

The Ready rule

A task is marked Ready by a person, never by an agent. The project's Ready rule says who that person may be.

RuleWho may mark a task Ready
Any (the default)Any person, including the person who accepted the changes.
Not the accepterSomeone else. A person who accepted a revision whose change the task carries is refused, and the app offers Ask for Ready, which notifies the project's Editors.

Tip

Use Not the accepter in projects of more than two people, so a second person marks every task Ready.

Archived projects

Archiving a project makes it read-only: its spec, workstreams, tasks and threads stay readable, and nothing can be edited or published. Restoring it makes it editable again.

Next steps