xo-project

Sample xo-project: the canonical .xo/

sample-project/
└── .xo/               committed with the project; travels through git and backups
    ├── project.json     identity and description
    ├── todos.json       session-scoped todos
    ├── workitems.json   durable work items, optionally adopted from GitHub issues
    └── peers.json       who the project is shared with

What each file is

Schemas live in services/cowork_agent/visualizer/schema/. Every store document is stamped with $schema and schema from birth, so a reader can dispatch on the version without guessing.

agent.json is the one optional member. An agent adapter writes it when the folder is attached to an agent backend; its presence is the signal, and XO Space never creates it on its own.

When a project gets this structure

• Scaffolded: project_layout.scaffold_project, used by POST /api/files/mkdir with scaffold: true and by agent creation. The template adds the work tier (AGENTS.md, PROJECT.md, memory/, …) beside it.
• Cloned through the API: POST /api/xo-projects.
• Auto-cloned by project sharing, when a repository shared with this Space is cloned into the root.
• Cloned or copied by hand into the projects root: the watcher adds .xo/ on its next tick.

The rules

• Additive only. Missing files are created; an existing file is never rewritten, repaired or reformatted, including one that does not parse.
• Never blocks. A read-only folder or a symlinked .xo is reported and skipped; nothing raises into the caller.
• Only .xo/. A cloned repository gains .xo/ and nothing else.
• A former projects root is not a project. A .xo/ that holds space.json or projects.json is left alone.

What differs between projects

pid, owner_user_id and created_at are minted per project; this sample uses placeholders, and the test checks their shape before comparing. name and display_name are the folder name unless a person typed a display name at creation. description is empty unless one was typed. A git block (remote_url, default_branch) is added to project.json once the git refresher has recorded the project's provenance.

What is not here

Machine-local state (stats, the timeline, the session index, the GitHub issue mirror, work-item claims) lives outside the project under ~/.quirq/projects/<pid>/, keyed by the pid in project.json.

Changing the structure

1. Change services/xo_structure.py, and the owning store and schema if a document's shape changes.
2. Change this sample to match. tests/test_xo_structure.py fails until the code, the sample and the schemas agree.
3. Existing projects gain a new file automatically on their next check. An existing file is never rewritten, so changing the shape of a document that already exists needs a migration in its store.

Tracking this sample in git

In a project, .xo/ is committed like any other file. This repository is the exception: its own .gitignore ignores .xo/ directories so the checkout's .xo/ stays local, which also hides this sample. Add a new sample file with git add -f tests/fixtures/xo-project/.xo. Once tracked, edits show up in git status as usual.