Agent Studio
Projects & Repositories

Projects, repositories and branches

A workspace groups related projects. Each project represents one repository. Branches and revisions identify the source behind its tasks and documents.

This page describes the target relationship model reviewed on 25 September 2026. Implementation of provenance, branch views and scaffolding is being rolled out; the diagram is not a claim that every surface already enforces the whole model.

Inspect project context
Relationship map

One project, one repository, visible branch context

Workspaces organise projects. A repository project identifies its Git repository; branch context identifies the revision used by a surface. A local checkout is a working copy of that repository.

  1. Top-level surface

    Workspace

    Organises related projects and provides navigation and ordering.

    Product Engineering
  2. Exactly one owner

    Project

    Identifies a Git repository and configures its branch roles.

    PROJ-001 · Agent Studio
  3. Canonical content and history

    Git repository

    Stores documentation, prompts, branches and revisions.

    Repository layerFiles · branches · commits
    Presentation layerWiki · render · search
    agent-studio.git

The branch context identifies the source of Wiki pages, prompts and task bases. Check the displayed branch when comparing knowledge with running software.

developWorking branch
WikiPromptsNew task baseProject Hub
mainRelease branch
Released appRelease manifestRelease historySeparate from Wiki source
Integration and release

Integrate checked work. Tag a verified release.

The release step promotes the integration branch with its recorded review state. An immutable version tag identifies a checked revision.

  1. 01Task cardstask/*

    Bounded work carries its diff, checks and review evidence.

  2. 02Integration branchdevelop

    Revisions join develop after configured gates pass. Human acceptance may still be pending.

  3. 03Release mergedevelop → main

    The dialog shows accepted, unreviewed, escalated and unattributed work before confirmation.

  4. 04Release branchmain

    A main revision records released code. A separate version tag identifies an immutable release.

  5. 05Version tagv<semver>

    A checked main SHA is recorded with a version tag and release manifest. A Stable reference checkout can later move to another revision.

Integration can precede human acceptance. Configured gates run before integration. Human review then evaluates the recorded evidence; release promotion is a separate decision.

Projects configure branch roles

Working and release branches are project settings. develop and main are examples; a version tag records an immutable release revision.

Workingdevelop
Default source for Wiki, Prompts and new task bases.
Releasemain
Release branch promoted from the integration branch.
Stable releasev<semver>
An immutable version tag identifies one checked main revision.
Tasktask/AGT-1984
Isolated execution branch created from a task base.
Vieweduser choice
Temporary read context for a surface such as the Wiki.

A repository structure for project knowledge

Docs are repository files. The Wiki renders and searches those files.

  • repository/
  • README.md
  • docs/# canonical content
  • README.md# Wiki landing page
  • concepts/
  • operations/
  • prompts/# prompt catalogue
  • .agent-studio/# project hints, no secrets

Data ownership

Git stores content

Docs, prompt files, history and branch provenance.

Wiki presents content

Tree, rendering, search, metadata and explicit editing.

Application stores tasks

Lifecycle records linked to repository, base branch and revision.

Registry stores local state

Absolute paths, refresh timestamps and credential references.

Reviewed 25 September 2026 against the project relationship model (AGT-1984). This diagram distinguishes the repository model from branch-context controls whose availability varies by product surface.

One project, one repository

Represent a product spanning several repositories as related projects in one workspace. A checkout path is replaceable infrastructure; it should not serve as the lasting identity of a repository.

Workspace

Groups projects for navigation and coordination.

Project

Declares the repository, branch roles, checkouts and URLs.

Repository

Stores source, documents, prompts and revision history.

Identify the branch and revision

The model assigns roles to branches: the working branch supplies new work and knowledge; a task branch holds isolated changes; a viewed branch selects a temporary reading context. Record the resolved revision as well as the branch name.

  • Task history should retain its original repository, base branch and revision when project defaults change.
  • A project URL should identify the branch or release it represents explicitly.

Separate running and working revisions

The application can run from a qualified release while development continues on develop. A dedicated Wiki checkout is intended to read the working branch independently of the running application and task worktrees. Check the provenance shown by your installed version.

Integration, release and Stable

After automatic delivery gates, work can join develop before human acceptance. Promotion moves a specified candidate to main with a manifest of included work. An immutable v<semver> tag and build evidence identify a qualified Stable release.

Read the branch workflow

Repository content and local configuration

The target structure keeps canonical documentation under docs/ and prompts under prompts/. The Wiki presents repository content. Optional .agent-studio/project.json hints should contain neither secrets nor absolute local paths. Check scaffold availability before relying on automatic creation.