Project Relationship Model
One workspace holds many projects. Each project is exactly one Git repository. Branches supply Wiki, Prompts, Tasks, URLs and the Project Hub, so every surface can answer which branch its data came from.
This is the relationship spine of Agent Studio, documented as product proof: how workspaces, projects, repositories and branches relate, why a checkout is never an identity, and how the running branch stays separate from the working branch that supplies knowledge.
One Project, One Repository
The product has one durable relationship spine. A workspace contains related projects; a project represents exactly one canonical Git repository; a repository has many branches and checkouts; and a branch supplies Wiki, Prompts, Tasks, URLs and Project Hub context. Identity flows in that direction and never bends back on itself.
Workspace
Organises related projects with navigation and ordering; a project belongs to exactly one workspace.
Project
Represents one canonical repository and declares its branch roles, checkout configuration and URLs.
Repository
The single source of Docs, Wiki content, Prompts, branches and revisions behind the project.
- A project cannot aggregate several repositories. A multi-repository product is represented by several related projects in one workspace.
- Moving a project between workspaces does not change its repository identity.
- A checkout path is replaceable infrastructure. It must never become the stable identity of a project or repository.
- Branch-bound content is never returned without branch and revision provenance, even when a compact surface chooses not to show it.
Branches Supply Every Surface
Projects declare branch roles rather than hard-coded names, and the branching model resolves those roles to real branches. Every branch-dependent response carries the same context envelope — branch, role, revision, repository and freshness — so Wiki, Prompts, Tasks, URLs and the Project Hub speak one branch-context vocabulary instead of a different badge language per surface.
Working
develop — default knowledge, prompts and new task bases.
Task
task/AGT-1984 — an isolated execution branch created from a task base.
Viewed
A temporary read context for a surface such as the Wiki or Git View.
- Working branch (for example develop) is the default source for Wiki, Prompts and new task bases.
- A task stores its base branch when created; starting it may create a task branch from that exact revision, and changing the project default later does not rewrite historical provenance.
- A URL stores its represented branch explicitly. No URL branch is inferred from whichever checkout happens to be active.
- Branch names alone are insufficient for review or caching; the resolved revision is always part of the provenance.
Running Branch vs Working Branch
Agent Studio commonly runs from stable or main while work continues on develop. That divergence is deliberate: the running branch is what the live product instance represents, while the working branch supplies knowledge and new work. An isolated Wiki checkout keeps knowledge on the working branch even when the backend process was launched from the running checkout.
Running
stable — the branch the running or released product instance represents.
Working
develop — Wiki, Prompts and new task bases resolve here.
Isolated Wiki checkout
A separate checkout keeps knowledge on develop without touching the running or task checkouts.
- The running branch must not leak into knowledge resolution just because the backend was launched from that checkout.
- Wiki content comes from the configured working branch unless a person explicitly changes the viewed branch.
- The Wiki checkout, runner checkout and task worktrees are separate roles; a refresh or branch switch in one must not mutate another.
- Divergence is shown as calm, inspectable information, not an acute warning.
Release the Integration Stream, Freeze Stable Points
Agent Studio uses develop as a fast integration stream. A manual release promotes that visible graph to main and says plainly what comes with it: accepted work, cards still in review, escalations and unattributed commits. Main is the continuous released line; only an explicit tag on a verified main revision is a stable freeze point.
develop
One shared integration graph for completed task work and dependent follow-ups.
main
The continuously released line, promoted with a transparent manifest instead of a clean-story shortcut.
stable tag
A deliberate freeze of one verified main revision with durable evidence and rollback context.
- Task integration and human acceptance are separate facts. Work may already be on develop while its evidence is still being reviewed.
- The develop-to-main dialog recalculates the exact Git range and shows every included task and unattributed commit before confirmation.
- A stable tag records one exact main SHA, its checks, evidence, actor and rollback predecessor. A running checkout is not stable evidence by itself.
- Merge-after-acceptance is deliberately not the default: it would turn human review into an integration queue, leave dependent work on stale bases and reveal coupling later.
Every Project Starts Ready for Knowledge
New repository-backed projects receive a small, valid, intentionally empty structure, and existing repositories get an opt-in scaffold that never overwrites files. Docs are the canonical repository content; the Wiki is their product presentation, not a competing content store. Prompt discovery begins at prompts/, and tasks stay application-owned while always linking back to repository, base branch and revision.
Git owns content
Docs, prompt files, history and branch provenance.
Wiki owns presentation
Navigation tree, rendering, search, metadata and explicit editing.
Application owns tasks
Lifecycle records linked to repository, base branch and revision.
- docs/ holds canonical content with a README landing page; the Wiki renders it instead of forking a second wiki/ folder.
- prompts/ is the prompt catalogue root that prompt discovery starts from.
- .agent-studio/project.json carries optional project hints with no secrets and no absolute paths.
- Local paths, credentials and machine-specific checkout state live in the project registry, never in the repository.