Skip to content

Team workflows & diagrams

Visual references for how a team collaborates in TOVIO day to day — from a fresh clone through individual changes, feature stacks shared across developers, code review, and release. Prose lives on clone and sync, propose and review, lane protection, and the everyday guides (lanes, commit, land). This page is the map.

How to read these

Rectangles are states or artifacts, rounded shapes are actions, diamonds are decisions, and dashed lines are network / cross-developer boundaries. Two team-specific ideas recur: lanes are shared landing targets (not per-developer workspaces), and conflicts are data that flow between teammates — they don't halt anyone's local loop.

1. Team topology at a glance

Every developer keeps a local replica using the full, sparse, partial, shallow, or lazy profile that fits their work. The Forge is a landing target and audit surface, not the source of truth for in-flight work.

flowchart LR
    subgraph FORGE[" Forge (built + tested) "]
        F[("policy manifest<br/>protected lanes<br/>proposals & reviews<br/>audit log")]
    end
    subgraph DEVS[" Developers (offline-first local replicas) "]
        A["Alice<br/>chg:a1 → chg:a2"]
        B["Bob<br/>chg:b1"]
        C["Carol<br/>chg:c1 → chg:c2 → chg:c3"]
    end
    subgraph CI[" CI runners / agents "]
        R["build-check<br/>other required_checks<br/>required plugins"]
    end
    A <-. "tovio sync" .-> F
    B <-. "tovio sync" .-> F
    C <-. "tovio sync" .-> F
    R <-. "scoped token" .-> F
    A <-. "peer sync (optional)" .-> B
    classDef srv fill:#eef,stroke:#557;
    class F,R srv;

Prose: Clone and sync · Offline & distributed.

2. Onboarding a new teammate

A clone is complete unless you narrow it — --sparse, --depth, --blobless, or --blob-limit each trade completeness for speed. Either way, protected files arrive as ciphertext and stay that way until clearance is resolved from the attribute-derived keys.

sequenceDiagram
    participant Dev as New teammate
    participant CLI as tovio-cli
    participant Forge as Forge
    Dev->>CLI: tovio clone forge.example.dev:7743 acme-api ./acme-api --sparse "src/**"
    CLI->>Forge: fetch history + refs (sparse)
    Forge-->>CLI: change objects, CRDT refs, policy manifest
    CLI-->>Dev: cloned (protected paths remain encrypted)
    Dev->>CLI: tovio sync (materialize working set)
    CLI-->>Dev: readable paths decrypted per identity
    Dev->>CLI: tovio access check config/production/api-keys.env
    CLI-->>Dev: needs role=senior AND clearance=secrets

Prose: Clone and sync · Permissions.

3. The team daily loop

Each teammate stays in their own stack of changes, syncs at natural pauses, and lands via the shared gate. Nobody is ever blocked by anyone else's unresolved conflict.

flowchart LR
    subgraph LOCAL[" Local (each developer) "]
        E["edit<br/>(auto-tracked)"] --> CM["tovio commit -m"] --> N["next change<br/>auto-started"]
        N --> E
        CM --> S{"pause point?"}
    end
    S -- yes --> SY["tovio sync"]
    SY --> REM(("remote /<br/>teammates"))
    REM --> SY
    SY --> LOCAL
    CM --> PR["tovio change propose --remote forge.example.dev:7743"]
    PR --> REV["review loop<br/>(approve / request-changes)"]
    REV --> LD["tovio land --into main"]
    LD --> MAIN(["main advances"])
    MAIN --> CASC[["cascade rebases everyone's<br/>dependent stacks — IDs preserved"]]

Prose: Branching, committing & merging workflows · Everyday guides.

4. Two teammates edit the same file — no "diverged" error

Lane refs are CRDT pointers; divergence reconciles automatically. A real content fork becomes a stored conflict object on one side — data, not a halt.

sequenceDiagram
    participant Alice as Alice
    participant Bob as Bob
    participant Forge as Forge
    Alice->>Alice: edit oauth.ts and commit chg-a1
    Bob->>Bob: edit oauth.ts and commit chg-b1
    Alice->>Forge: tovio sync (push chg-a1)
    Bob->>Forge: tovio sync
    Forge-->>Bob: pull chg-a1, CRDT refs converge
    Bob->>Bob: typed 3-way merge overlaps with chg-b1
    Note over Bob: conflict stored on chg-b1 at oauth.ts — Bob keeps working (isolate)
    Bob->>Bob: tovio resolve src/auth/oauth.ts --ours
    Bob->>Forge: tovio sync (push resolution and chg-b1)

Prose: Conflict workflows · Resolve conflicts.

5. Feature stack shared across developers

A feature is often a stack of changes, sometimes crossing developers. IDs stay stable through amend, rebase, and land — so review, resolutions, and references never lose their anchor.

flowchart TB
    subgraph ALICE[" Alice's stack "]
        A1["chg:a1 — schema"]
        A2["chg:a2 — API"]
        A1 --> A2
    end
    subgraph BOB[" Bob's stack (on top of Alice) "]
        B1["chg:b1 — UI (depends on chg:a2)"]
    end
    A2 -. "shared via sync" .-> B1
    A2 --> LD1{"land my-lane → main"}
    LD1 --> CASC1[["cascade:<br/>chg:a2 rebased,<br/>chg:b1 rebased,<br/>all IDs preserved"]]
    CASC1 --> A2R["chg:a2 (new parent)"]
    CASC1 --> B1R["chg:b1 (new parent)"]

Prose: Change model — stacks · Land a change.

6. The proposal lifecycle across the team

A proposal (prop:…) is a small state machine over a pinned Change ID and the decisions cast against it. Amending a proposed change re-opens review — every live approval is invalidated, with no exemption for a trivial edit — but the Change ID never changes.

stateDiagram-v2
    [*] --> draft
    draft --> open: tovio change propose
    open --> open: amend (approvals invalidated, IDs kept)
    open --> approved: all required approvals
    open --> open: request-changes (blocks land)
    approved --> open: amend (every approval invalidated)
    approved --> landed: tovio land --into main
    open --> closed: withdrawn
    approved --> closed: withdrawn
    landed --> [*]
    closed --> [*]

Prose: Propose and review.

7. The protected-lane land gate — team edition

Everything a team cares about composes into one refuse-or-land decision. Anything blocking produces a structured reason and the next step.

flowchart TD
    L["tovio land my-lane --into main"] --> G1{"conflict-free?"}
    G1 -- no --> B1[["✗ resolve first"]]
    G1 -- yes --> G2{"required_checks pass?<br/>+ semantic_check gate"}
    G2 -- no --> B2[["✗ check failed"]]
    G2 -- yes --> G3{"proposal approved?<br/>no open request-changes?"}
    G3 -- no --> B3[["✗ review pending / blocked"]]
    G3 -- yes --> G4{"cleared-reviewer coverage<br/>for protected paths?"}
    G4 -- no --> B4[["✗ needs cleared reviewer<br/>(policy id shown, never the path)"]]
    G4 -- yes --> G5{"write_policy satisfied?"}
    G5 -- no --> B5[["✗ not authorized to land here"]]
    G5 -- yes --> G6{"required plugins (pre-land) pass?"}
    G6 -- no --> B6[["✗ plugin blocked<br/>(TVO-PLUGIN-009)"]]
    G6 -- yes --> OK([✓ landed + cascade])
    classDef stop fill:#fdd,stroke:#c33,color:#600;
    class B1,B2,B3,B4,B5,B6 stop;

Prose: Lane protection · Plugin workflows → land gates.

8. Redacted review — files the reviewer can't read

The Forge object store holds ciphertext for policy-protected payloads. The authorized review projection shows bounded redacted metadata to an uncleared reviewer; a cleared reviewer must cover those paths.

sequenceDiagram
    participant Rev as Reviewer (no clearance)
    participant Forge as Forge
    participant Cleared as Cleared reviewer
    Rev->>Forge: tovio review chg:007 --proposal prop:009 --remote forge.example.dev:7743
    Forge-->>Rev: readable files: full diff
    Forge-->>Rev: protected files: path + added/modified/removed only
    Rev->>Forge: --approve (covers readable subset)
    Cleared->>Forge: tovio review chg:007 --proposal prop:009 --remote forge.example.dev:7743
    Forge-->>Cleared: decrypts protected files with attribute keys
    Cleared->>Forge: --approve (covers protected paths)
    Forge-->>Cleared: cleared-reviewer coverage satisfied

Prose: Propose and review — redacted files · Lane protection — cleared reviewer.

9. request-changes and amend — the review ping-pong

request-changes is a hard block. Amending re-opens the proposal at the same Change ID, so history, resolutions, and links all stay attached.

sequenceDiagram
    participant A as Author
    participant Fg as Forge
    participant R as Reviewer
    A->>Fg: tovio change propose chg-007 --remote forge.example.dev:7743
    Fg-->>R: prop-009 open
    R->>Fg: --request-changes please add test
    Fg-->>A: land blocked on prop-009
    A->>A: edit and tovio commit --amend (same chg-007)
    A->>Fg: tovio sync
    Fg-->>R: prop-009 re-opened (prior approvals invalidated)
    R->>Fg: --approve
    Fg-->>A: approved, landing gate now clear

Prose: Propose and review — amending.

10. Isolate — don't let a teammate's conflict break your build

If Bob's unresolved conflict is upstream of your work, sync --isolate materializes those paths at the last-known-clean version. Your tree builds; the conflict stays flagged; when Bob resolves, your workspace auto-updates.

flowchart LR
    S["tovio sync"] --> D{"teammate's change<br/>has unresolved conflict<br/>your work depends on?"}
    D -- no --> OK([✓ synced])
    D -- yes --> BLOCK[["✗ would break your build"]]
    BLOCK --> C1["Option A: notify + wait<br/>tovio change notify chg:xxx"]
    BLOCK --> C2["Option B: tovio sync --isolate<br/>use last-known-clean; auto-update on resolve"]
    C2 --> WORK([✓ build green; conflict still flagged])

Prose: Clone and sync — isolate · Conflict workflows.

11. Release flow — cutting release-x.y from main

A release line is just another protected lane pointing at a landed change. Cherry-picks preserve Change IDs and carry their recorded resolutions.

flowchart LR
    MAIN(["lane: main<br/>@ chg:m42"]) --> CUT["tovio lane release-1.4<br/>(from the current tip)"]
    CUT --> REL(["lane: release-1.4"])
    subgraph HOTFIX[" Hotfix "]
        H1["chg:h1 (author)"] --> HP["tovio change propose --remote ..."]
        HP --> HR["review"] --> HLR["tovio land --into release-1.4"]
    end
    HLR --> REL
    HLR --> BACK["tovio land --into main<br/>(carry-forward)"]
    BACK --> MAIN
    classDef ptr fill:#eef,stroke:#557;
    class MAIN,REL ptr;

Prose: Lane protection · Branching workflows.

12. CI, agents, and required checks

Runners and agents authenticate with scoped tokens and post structured check results the land gate can read. Same protocol as a human land; only the identity and scope differ.

sequenceDiagram
    participant Dev as Developer
    participant Fg as Forge
    participant CI as CI runner (scoped token)
    Dev->>Fg: tovio change propose chg:007
    Fg-->>CI: prop:009 opened — run required_checks
    CI->>CI: build-check + any other required_checks, plugins
    CI->>Fg: post check results (structured)
    alt all pass
        Fg-->>Dev: gate green — land eligible
    else any fail
        Fg-->>Dev: gate red — structured reason (path, rule, next step)
    end

Prose: Agents & integrations · Plugin workflows.

13. End-to-end: a full team feature ships

The whole team-scale flow on one page — from clone through a shared feature stack, review, cascade, and release carry-forward.

sequenceDiagram
    participant Alice as Alice
    participant Bob as Bob
    participant Fg as Forge
    participant CI as CI
    participant Rel as release-1.4

    Alice->>Fg: tovio clone and sync
    Alice->>Alice: chg-a1 schema, chg-a2 API
    Alice->>Fg: sync (share stack)
    Bob->>Fg: sync (pull chg-a1, chg-a2)
    Bob->>Bob: chg-b1 UI on top of chg-a2
    Bob->>Fg: sync and tovio change propose chg-b1
    Alice->>Fg: tovio change propose chg-a1, chg-a2
    Fg-->>CI: run the declared required_checks + plugins
    CI-->>Fg: all green
    Fg-->>Alice: approvals collected (incl. cleared reviewer)
    Alice->>Fg: tovio land my-lane --into main
    Fg-->>Fg: cascade chg-a2, chg-b1 rebased (IDs preserved)
    Alice->>Fg: tovio land my-lane --into main
    Bob->>Fg: tovio land my-lane --into main
    Fg-->>Rel: tovio land my-lane --into release-1.4
    Fg-->>Fg: carry-forward land onto main

Where to go next

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure