Cooperation Patterns

Cooperation Patterns

Pizarra is most valuable when a team is designed deliberately. These patterns show how to turn specialist terminal workers into a controlled autonomous system. Every name and path below is synthetic.

Pattern 1: parallel implementation and review

Use a workflow when independent branches can proceed after a shared foundation:

tiza wf create release-1 release
tiza wf step release-1 builder "Build the candidate" --after 0 --eta 2h
tiza wf step release-1 tester "Run system and upgrade tests" --after 1 --eta 90m
tiza wf step release-1 reviewer "Review security and compatibility" --after 1 --eta 90m
tiza wf step release-1 console "Approve the release" --after 2,3
tiza wf set release-1 strict on
tiza wf start release-1

flowchart LR
    B[1 Build] --> T[2 Test]
    B --> R[3 Review]
    T --> H[4 Human approval]
    R --> H

Loading

Why it works:

• the build has one owner;
• test and review activate together;
• the next topological level waits for both branches;
• each active team-owned step creates one linked task, while the console gate receives a human notice without a task;
• strict mode requires completion evidence; and
• the console-owned final step is a real human gate.

The engine coordinates the protocol; it does not pretend to execute or validate the tests described in the evidence.

Pattern 2: independent defect recovery

Suppose the reviewer finds a mismatch after the build step was already closed:

tiza wf error release-1 "The candidate manifest does not match the packaged files." --step 1

The workflow halts immediately, including unrelated active work. The builder repairs and tests:

tiza wf fixed release-1 "Regenerated the manifest from a clean build and compared every digest."

The fixer cannot approve the repair. Another authorized party verifies it:

tiza wf verify release-1 ok "Rebuilt independently and reproduced the manifest."

A failed check is equally explicit:

tiza wf verify release-1 fail "The package still contains one unlisted asset."

The step returns to error and the plan remains halted. This pattern prevents self-certification and silent resumption.

Pattern 3: a human decision boundary

Assign a step to console whenever technical completion is not the same as authorization:

tiza wf step migration operator "Prepare migration and rollback plan" --after 0
tiza wf step migration tester "Rehearse on an isolated copy" --after 1
tiza wf step migration console "Approve production migration" --after 2

Only the console identity can close a console-owned step. This is suitable for:

• release approval;
• production change windows;
• destructive maintenance;
• accepting a risk exception;
• publishing an artifact; or
• final sign-off after independent review.

Pattern 4: tasks for interrupts, workflows for plans

Use tasks for work that does not need dependency execution:

tiza task add builder "Investigate the failed nightly build" --milestone reliability
tiza task note 41 "Reproduced on a clean checkout."
tiza task assign 41 reviewer
tiza task done 41

Use a workflow when order, parallelism, evidence, recovery, or a human gate matters.

A workflow projects actionable steps into tasks, so owners still work from one task board. Do not manually bypass a linked task's workflow gate.

Pattern 5: durable delegation by speciality

Define stable teams around responsibility instead of spawning anonymous work:

Team	Speciality	Typical authority
builder	Implements and performs local checks	Task and workflow work scoped by membership
tester	Reproduces behavior and runs system tests	Evidence, defect reporting
reviewer	Reviews design, security, and compatibility	Independent verification
operator	Deployment and service health	Narrow fleet and operational authority
console	Human supervision and approval	Master control identity
pzweb	Browser control adapter	Explicit delegated command families

A contextual delivery can tell each team its role, current project, applicable rules, tasks, active workflow step, administrators, and reply commands. The hub creates that envelope from durable state; senders do not need to reproduce the context in every message.

Pattern 6: a project with application ownership

Use registries when several systems contribute to one objective:

tiza project boss atlas operator
tiza app add gateway --team builder --repo https://example.invalid/gateway.git \
  --purpose "Receives and validates client requests"
tiza app project gateway atlas --role "Public entry point"
tiza group add atlas-team builder tester reviewer
tiza group boss atlas-team operator
tiza group project atlas-team atlas

The application has one responsible team but can have a different role in each project. Its manual and change history remain available to the team.

Use reserved example domains in documentation; production repository URLs and paths belong only in private configuration.

Pattern 7: remote specialists behind NAT

For a remote host that cannot accept inbound connections, prefer reverse dial:

Create the authoritative team through the console identity. Start inbox-only so the intermediate state cannot launch a local session, then enable reverse dial:

tiza team add reviewer "Independent review and verification" --session -
tiza team set reviewer secret --file /run/secrets/pizarra-reviewer
tiza team set reviewer dial on

Endpoint:

[pizarra]
host = 10.0.0.10
port = 7010
secret = <unique-reviewer-secret>
self = reviewer

[daemon]
dial = on
state = /var/lib/pizarra/tiza.state

[session:reviewer]
tmux_session = pizarra-reviewer
launch = <interactive-terminal-program>
workdir = /srv/reviewer/project

The daemon maintains the outbound connection and deduplicates terminal injection with its persistent receipt state. Keep the network private and encrypted independently; the native protocol itself is cleartext.

Pattern 8: inbox-only services

Not every identity needs a terminal:

tiza team add audit-view "Reads scoped operational messages" --session -
tiza team set audit-view secret --file /run/secrets/pizarra-audit-view

Messages are durable and available through:

TIZA_CONF=/etc/pizarra/agents/audit-view.conf tiza inbox --keep
TIZA_CONF=/etc/pizarra/agents/audit-view.conf tiza inbox

Use inbox-only identities for narrowly scoped consumers. Grant wider watch or administrative capability only when it is operationally necessary.

Design checklist

• Give every identity one clear speciality.
• Use a unique credential and configuration file per identity.
• Prefer small explicit delegated capability sets.
• Use tasks for independent work and workflows for coordinated plans.
• Make joins and human approval gates visible in the graph.
• Require evidence where completion quality matters.
• Separate the fixer from the verifier.
• Record progress as task notes so humans and stall detection see it.
• Prefer reverse dial for remote teams.
• Keep production paths, credentials, messages, and stores outside Git.
• Design the operating-system account boundary alongside the Pizarra role boundary.

Continue with Organization Model, Messaging and Inbox, Tasks, and Workflow Engine.