Workspaces and projects

Workspaces#

A workspace is the top-level container for your team. It holds what applies to everyone: members and their roles, workspace settings, and the connection to GitHub. Most teams need exactly one. In the examples across these docs, the workspace is called Northwind Commerce.

The self-hosted edition does not count seats. SpecsGraph Cloud, which is coming soon, will count the people who can sign in to a workspace, never agents or projects; see Cloud plans.

Projects#

A project is one system graph published to one repository. It has its own contexts, glossary, actors, requirements, workstreams and decision log. When a proposal in the project is approved, SpecsGraph commits the change into that project's repository, inside its spec folder.

A project usually maps to one product or system your team ships. Northwind Commerce has a single project, Shop, that covers all seven contexts from Identity to Analytics and publishes to the northwind/shop repository.

Projects in a monorepo#

Several projects can publish to the same repository as long as each one writes to its own folder. Point each project's spec folder at the part of the tree it describes, for example apps/shop/specsgraph and apps/warehouse/specsgraph. A project only writes inside its own folder, so commits from one project never touch another project's files.

Before you split a monorepo into several projects, check the language. If the apps share contexts and most glossary terms, one project with one folder at the root is easier to keep consistent. Split when the systems have separate teams and their own vocabulary.

One system, several repositories#

The opposite case is just as common: one system whose services live in many repositories. Keep it as one project, so its contexts, glossary and requirement IDs stay in one graph, and publish that project to a single repository, such as a shared architecture repository or the repository of the core context.

• Agents working in the other repositories still read the whole graph over MCP, with a token limited to that project.
• Commits in every repository cite requirement IDs as usual, so the history links back to the same spec.
• Split into several projects only when the teams and their vocabulary differ, as described above.

Create a project#

1. 01

   Connect GitHub

   A project publishes to a repository, so the workspace needs your GitHub App installed with access to that repository. An Admin or Owner does this once per workspace. See Connect GitHub.

2. 02

   Name the project and pick a key

   Choose a name people will recognize, such as Shop, and a short project key such as shop. The key identifies the project in URLs, so keep it short and lowercase.

3. 03

   Choose the repository and base branch

   Pick a repository the GitHub App can see. The base branch defaults to the repository's default branch. SpecsGraph starts a spec/ branch from it for each proposal and opens pull requests against it.

4. 04

   Set the spec folder

   This is the folder SpecsGraph writes into. The default is specsgraph at the repository root. Change it in a monorepo, or when a folder with that name already exists for another purpose.

5. 05

   Create the project

   The project starts with an empty graph. Nothing is written to the repository until the first proposal is approved, so you can sketch contexts and argue about names before anything shows up in Git.

Project settings#

A change to the repository, base branch or spec folder applies to the next change SpecsGraph publishes. Files that were already published stay where they are; move or remove them in an ordinary pull request if you need to.

Change the spec through SpecsGraph rather than by editing files in the spec folder by hand. Spec files in your repository explains how SpecsGraph treats that folder.

Several projects in one workspace#

Add a project for each separate system with its own team and language. One system spread over several repositories stays one project, as described above. Projects in a workspace share members, settings and the GitHub connection, but not their graphs: a glossary term in one project does not appear in another, and requirement IDs are unique within a project.

When two systems talk to each other, model the other system as an external actor instead of merging the graphs. If Northwind later adds a separate Warehouse project, Shop's Fulfilment context lists Warehouse as an external system it calls. See Actors.

Archive a project#

Archive a project when the system it describes is retired or replaced. An archived project is read-only. Its graph, proposals, decisions and history stay visible to everyone in the workspace, agents can still read it, but nobody can open new proposals and SpecsGraph stops publishing to its repository.

Archiving never deletes files from your repository. The last published spec stays in the spec folder, next to the code it describes. An Admin or Owner can restore the project later and the team picks up where it left off.

Delete a workspace#

Deleting the whole workspace is an Owner action. It commits nothing to your repositories, so published spec files stay where they are. Export the workspace first from Workspace settings, then Export if you want to keep proposals and history.

Next steps#

• Connect GitHub so your projects can publish to their repositories.
• The system graph shows how to find your way around a project.
• Members and roles covers who can create, change and archive projects.