OS Collaborative Development Model

Purpose

This document defines how Prox OS is built by a human architecture owner and a set of scoped AI coding agents across GitHub Issues, pull requests, branches, worktrees, architecture docs, and quality gates.

Prox OS is not a normal website. It is a browser-based desktop OS shell with a runtime host, window manager, app registry, official OS apps, iframe apps, mock/API boundaries, a docs app, a UI workshop, and future agent-facing contracts. Development must optimize for parallel progress without allowing agents to overwrite each other, bypass architecture boundaries, or let docs drift away from the code.

Why Prox OS Needs an AI-native Development Model

Prox OS depends on AI-readable docs as much as on TypeScript source. AGENTS.md sets strong rules, docs/start-here/context-pack.md routes agents to the right context, architecture docs describe boundaries, roadmap docs preserve intent, and the docs app mirrors root docs for browsing.

This means the repository is a development system:

• Code implements behavior.
• Docs preserve intent, constraints, and current architecture observations.
• Issues and PRs can become scoped work packets.
• Branches and worktrees isolate parallel agents.
• Quality gates keep generated work reviewable.
• The human owner remains accountable for direction and merge decisions.

Human-as-Architect, Agents-as-Workers

The human owner or architecture director is responsible for:

• Product direction.
• Architecture boundaries.
• Task slicing and priority.
• Final review.
• Merge and release decisions.
• Roadmap judgment.
• Deciding when a future idea becomes current implementation scope.

AI agents are responsible for:

• Scoped implementation.
• Documentation updates tied to the change.
• Storybook or UI Workshop examples when UI primitives change.
• Local refactors inside allowed paths.
• Tests and quality checks.
• Migration helpers and safety notes when explicitly requested.
• Summaries of changed files, commands run, risks, and follow-ups.

Agents may propose architecture, but they should not silently set core architecture direction. Core protocol, runtime, auth, billing, database, deployment, and permission work requires explicit human review.

Repository Boundaries

The following boundaries are especially important for parallel agent work:

State boundaries:

• Zustand is for local OS UI, window, display, and browser shell state.
• TanStack Query is for remote/server-shaped state.
• Browser persistence keys should use documented helpers and canonical keys.
• MSW and mock API boundaries are collaboration buffers between shell/UI work and backend/API work.
• Runtime app launches must flow through registered manifests, not scattered hardcoded routes.

Serial vs Parallel Work

Core principle:

Leaf work can be parallelized. Core protocol work must be serialized.

Parallelism is safest when each worker owns a leaf surface with disjoint paths. Serialization is required when a change alters shared contracts, registries, runtime semantics, root tooling, or broad package boundaries.

Leaf Work Can Be Parallelized

Good parallel work candidates:

• One agent develops one independent app.
• One agent develops one independent package.
• One agent updates docs.
• One agent adds Storybook or UI Workshop coverage.
• One agent writes tests for a scoped feature.
• One agent builds a mock API skeleton.
• One agent fixes lint, typecheck, or build errors in a narrow ownership area.
• One agent cleans architecture diagrams or indexes.

Parallel work still needs branch isolation, allowed paths, forbidden paths, and a merge plan.

Core Protocol Work Must Be Serialized

Avoid parallel edits when multiple agents would touch:

• packages/contracts/app-contract.
• Window manager or shell runtime routing.
• App registry composition.
• Design tokens.
• Router/runtime boundaries.
• Shared UI package refactors.
• Root package scripts, package manager config, Nx config, or dependency graph rules.
• Database schema or migrations.
• Cloudflare deployment, custom domains, Access policies, or secrets.
• Large file moves or package extraction.

If core work blocks leaf work, land or approve the core change first, then let leaf tasks rebase and continue.

Agent Pre-flight Impact Check

Every agent should run a pre-flight impact check before editing files. The goal is to make conflict risk visible before work starts.

Check:

• What is the task goal?
• Which paths are allowed?
• Which paths are forbidden?
• Does the task touch shared contracts?
• Does it touch root scripts or workspace config?
• Does it touch dependency graph or package boundaries?
• Does it touch app registry or route groups?
• Does it require a migration?
• Does it require docs updates?
• Does it require Storybook or UI Workshop coverage?
• Which quality commands are required?
• Could it conflict with another parallel branch?

Template:

## Agent Pre-flight Checklist

- Task ID:
- Branch:
- Scope:
- Allowed paths:
- Forbidden paths:
- Shared contracts touched: yes/no
- Registry touched: yes/no
- Root config touched: yes/no
- Docs required: yes/no
- Tests required: yes/no
- Storybook required: yes/no
- Expected conflict risk: low/medium/high
- Merge order requirement:

Prompt Batch Triage

When a human provides several prompts or a large mixed prompt, do not turn it into one broad patch by default.

Process:

1. Split the prompt into independent tasks.
2. Identify likely touched paths for each task.
3. Mark conflict risk.
4. Assign parallelizable tasks to separate branches.
5. Run non-parallelizable tasks serially.
6. Serialize core protocol, root config, registry, and design token changes.
7. Give every task acceptance criteria.
8. After each task, report changed files, commands run, risks, and follow-ups.
9. If the prompt is too broad, write a task plan first instead of editing the whole repository.

Template:

| Task | Scope | Paths | Conflict Risk | Parallelizable | Branch | Merge Order |
| ---- | ----- | ----- | ------------- | -------------- | ------ | ----------- |

See AI Prompt Batching for the maintainer-facing batching playbook.

Local Git Worktree Strategy

Recommended local parallel setup:

git worktree add ../prox-os-task-a -b agent/task-a-short-scope
git worktree add ../prox-os-task-b -b agent/task-b-short-scope
git worktree add ../prox-os-docs -b docs/os-collaboration-model

Then open each worktree in a separate Codex, Cursor, Warp tab, or terminal agent session. Each worker should run from its own worktree and branch.

Rules:

• One agent per branch.
• Prefer one worktree per active agent.
• Do not let multiple agents write in the same working tree.
• Do not let multiple agents work directly on main.
• Rebase or merge the latest main before final review.
• Open a draft PR for large or uncertain work.
• Require human review for core protocol, registry, runtime, design token, database, deployment, auth, payment, permission, or root tooling changes.

Branch Naming Rules

Use names that reveal ownership and scope:

• agent/<task-id>-<short-scope>
• docs/<topic>
• app/<app-name>
• pkg/<package-name>
• fix/<issue-id>-<short-desc>

For temporary local branches, a tool-specific prefix such as codex/<scope> is also acceptable when it does not conflict with existing refs.

Pull Request Requirements

Every PR should state:

• What changed.
• Why it changed.
• Files touched.
• Architecture impact.
• Docs updated.
• Tests and quality commands run.
• Screenshots or browser notes if UI changed.
• Risk level.
• Follow-ups.

See Branch and Merge Rules for a copyable PR template and merge protocol.

Merge Order for Parallel Agent Work

Default merge order after parallel work:

1. Docs-only changes.
2. Isolated leaf apps.
3. Isolated packages.
4. Shared UI additions.
5. App registry changes.
6. App contract changes.
7. OS Shell runtime changes.
8. Root config and tooling changes.

This order is a heuristic, not a law. Dependency direction wins. If a shared contract is required by leaf branches, merge the reviewed contract first and rebase dependent branches.

Documentation Update Rules

Update docs in the same branch when a change affects:

• Package boundaries.
• App registration or route groups.
• Window or shell runtime semantics.
• State ownership.
• API routes, mock API, OpenAPI, or data flow.
• Design tokens or shared UI posture.
• Deployment, domains, Access, or environment assumptions.
• AI agent workflow, task splitting, prompt templates, or quality gates.

Root docs/ is canonical. Run pnpm docs:sync when the docs app content should be updated.

Quality Gates

Default non-trivial code changes should run:

pnpm lint
pnpm typecheck
pnpm arch:check
pnpm check:cjk

Structural refactors, package moves, app extraction, state model changes, API boundary changes, or large UI splits should also run:

pnpm check:file-size

Docs-only changes should at least run pnpm docs:sync and pnpm check:cjk. Run broader checks when docs changed architecture rules, generated docs app content, package references, or scripts.

See Quality Gates for task-specific guidance.

Relationship with Deployment Docs

Development docs focus on how work is scoped, split, reviewed, and merged. Deployment docs focus on environments, Cloudflare targets, Pages/Workers, domains, Access boundaries, preview/prod behavior, and release commands.

Use docs/operations/deployment for deployment posture and operations/deployment.md for the short command surface. Do not bury AI agent workflow in deployment docs, and do not move Cloudflare deployment details into development docs.

GitHub Issues as Future Agent Task Queue

Future direction: GitHub Issues can become a task queue for Codex, Cursor, and future local agents. This is not fully automated today.

An agent-ready issue should include:

• Scope.
• Allowed paths.
• Forbidden paths.
• Acceptance criteria.
• Required reading.
• Quality commands.
• Risk level.
• Human reviewer.

Candidate labels:

• area:docs
• area:app
• area:os-shell
• area:api-worker
• area:ui
• risk:low
• risk:high
• agent-ready
• human-review-required

Low-risk docs and leaf app work can become increasingly automated. High-risk protocol, runtime, deployment, auth, payment, database, and permission work must remain human-reviewed and should not auto-merge.

Future Agent Swarm Direction

Future local orchestration may allow a human owner or Architect AI to assign issues across local Codex windows, Cursor sessions, terminal agents, CI, and an Integrator AI. The durable model should remain the same:

Issue or prompt
  -> task triage
  -> scoped branch/worktree
  -> agent execution
  -> quality gates
  -> PR summary
  -> integration review
  -> human merge decision

Do not treat this future direction as current automation. Today, the safe implementation is manual branch/worktree isolation with clear summaries and human review.