Projects, Workspaces and Repositories
These pages use three words with exact meanings. A repository holds your workspace’s history, a workspace is where you work, and a project is one body of work inside that workspace. Each word means one thing only, so the instructions on every page point to the right place.
| Term | What it is | Example |
|---|---|---|
| Repository | The git remote that stores your workspace’s files and history, such as a private repository on GitHub | example-consulting/example-consulting-biz-os |
| Workspace | The repository loaded on your computer and opened in Claude Code | The example-consulting-biz-os folder open in VS Code |
| Project | A folder of work with its own identifier, inside a workspace | Domains/15 Education & Training/P012 Spring Workshop/ |
A workspace contains many projects, and a project is never called a workspace or a repository.
Repository
Section titled “Repository”The repository is the git remote that your workspace pushes to and pulls from. It holds every committed file and the full history of changes, so it is your backup and the way you move work between computers. /night and /sync push your work to it, and /day pulls the latest changes from it.
Your work reaches the repository through git’s origin remote. Keep the repository private, because it holds your company context files, your project records and your client folders.
/update uses a second remote, called upstream, which points to the AI Business OS template that new engine versions come from. If PRIMA Project Management is installed, /update also uses a remote called prima-upstream. /update only reads from these two remotes, so your work never goes to either of them.
Workspace
Section titled “Workspace”A workspace is the repository loaded on your computer and opened in Claude Code. It is the folder you open in VS Code each morning, with .claude/ at the top and your domains beneath it. Claude Code reads the workspace’s instructions when the session starts, and every file Claude writes lands somewhere inside it.
One workspace serves one organisation. If you also manage a workspace for someone else, such as a client or a colleague, that workspace has its own folder and its own repository. Open the folder for the organisation you are working for, because Claude follows the instructions of whichever workspace is open.
The Workspace Identity
Section titled “The Workspace Identity”Every workspace records who it belongs to in the workspace block of .claude/state/state.json. /setup fills it in from your answers.
| Field | What it holds |
|---|---|
name |
Your organisation’s name |
id |
A short identifier in lower case with hyphens, such as example-consulting-biz-os |
type |
client, personal or internal. /setup sets client by default, or personal if you set up the workspace for yourself |
githubRepo |
The repository address you gave during /setup, or empty if you answered none |
The same details appear in the Workspace Identity section at the top of .claude/CLAUDE.md.
The identity protects your pushes. Before /sync pushes, Claude compares githubRepo with the address of the origin remote. If they do not match, Claude stops and pushes nothing. The check stops one workspace’s files from reaching another workspace’s repository when you work with more than one. In the base AI Business OS, only /sync runs this check, and /night pushes to origin without it. PRIMA Project Management adds the check to its own /night.
Project
Section titled “Project”A project is a body of work with an objective and an end, such as a campaign, an audit or a workshop. Each project has a folder inside a domain and an entry in the project register, .claude/state/state.json. You create projects with /newproject.
Project Identifiers
Section titled “Project Identifiers”Every project has an identifier that never changes and is never reused. A new workspace numbers its projects P001, P002, P003 and so on. The sequence runs across the whole workspace, so the project after P011 in Marketing is P012, whatever domain it belongs to.
If the register already uses another format, such as PRJ-0012, /newproject continues that format and never changes an existing identifier. If it finds more than one format, it stops and asks you which one new projects should use.
The Project Folder
Section titled “The Project Folder”The folder name is the identifier, a space and the project name in Title Case, such as P012 Spring Workshop. /newproject creates three files in it.
| File | Purpose |
|---|---|
CLAUDE.md |
Instructions for Claude that apply to this project only |
AGENTS.md |
A short pointer that sends other AI tools to the CLAUDE.md file |
PRD.md |
The project’s requirements, built from the PRD template |
The project’s entry in the register records its status, priority, category, due date and folder path. The status is one of in-progress, paused, overdue and archived, and the State Files and Validation page lists every field.
What Is Not a Project
Section titled “What Is Not a Project”Not every folder is a project. Reference subfolders in a domain, such as 02.3 Budgets, hold standing material that never finishes, so they have no identifier and no entry in the register. A client folder created with /newclient, such as Domains/01 Clients/Harbour-Dental/, is not a project either. Work for that client that has an objective and an end becomes a project, created with /newproject and the client category.
How the Three Fit Together
Section titled “How the Three Fit Together”Repository (git remote, for example on GitHub) ▲ push │ pull │ ▼Workspace (the folder open in Claude Code)├── .claude/state/state.json The project register└── Domains/ ├── 07 Marketing/ │ └── P011 Autumn Newsletter/ Project └── 15 Education & Training/ └── P012 Spring Workshop/ Project