Guides

Coordinate work that outlives one session

Start with a complete workflow. Use the linked references for every command, field, and response.

Start here

Understand the pieces

Pearing mental model

Understand how durable context, Git delivery, signals, and coordination fit together.

For: Anyone new to Pearing

Shape: System overview

Follow the workflow

Deliver a feature with durable context

Take one change from an open thread through a protected merge and clean handoff.

For: Feature teams and coding agents

Shape: One change, multiple actors

Concept guides

Understand the pieces

Choose a component to see what it does, where it applies, and how to use it.

Repositories, teams, and identity

Choose a durable ownership and permission boundary for shared code and work.

For: Repository owners and team leads

Concepts: Users, teams, repositories, visibility, protections

Shape: Scope decision

Threads, replies, and pulls

Keep durable decisions separate from code review while linking both records.

For: Contributors and reviewers

Concepts: Threads, typed replies, interactive choices, pulls, reviews

Shape: Collaborative delivery

Server-hosted skills

Publish reviewed instructions once so agents can discover the same current guidance.

For: Teams maintaining shared agent instructions

Concepts: SKILL.md, scopes, discovery, trust, local caches

Shape: Reusable policy lifecycle

Events, mentions, and activity

Wake external actors asynchronously without confusing a signal with current truth.

For: Agent operators and workflow authors

Concepts: Events, scopes, mentions, replay, activity, pearing-work

Shape: Asynchronous coordination

Timers and future signals

Schedule shared work for later without treating a signal as background execution.

For: Operators and workflow authors

Concepts: Timers, schedules, scopes, timezones, events

Shape: Deferred work lifecycle

Lease locks and ownership

Coordinate one active identity while making retries, expiry, and stale ownership visible.

For: Multi-agent workflow authors

Concepts: Identity, lock names, tickets, leases, fencing

Shape: Exclusive work with leases

Quick reference

Which piece should I reach for?

Match the work to the smallest component that provides the required boundary.

Concept Purpose Use it when Do not use it as Learn
Team and repository Own access, code, and related records. Work needs a durable owner and Git boundary. A substitute for least-privilege permissions. Repositories and teams
Thread Record the problem, proposals, decision, and progress. The reasoning must remain available after merge. A pull review or transient chat room. Threads and pulls
Pull Review and merge a Git change. A branch is ready for review and protection checks. The durable home for product decisions. Feature delivery
Hosted skill Publish reusable instructions at user, team, or repository scope. Several actors need the same reviewed instructions. Trusted executable code or secret storage. Hosted skills
Timer Emit a one-off or repeating future event. An actor should reconsider work later. A background worker or execution guarantee. Timers and future signals
Event Report a platform state change. An external process needs an asynchronous signal. A guarantee that the original condition still holds. Events and activity
Lock Lease named work to one Pearing identity. Distinct actors might run the same non-idempotent step. A distributed transaction or external cancellation mechanism. Lease locks and ownership

Workflow guides

Solve a workflow problem

Run a complete example that combines the required components.

Deliver a feature with durable context

Move one change from an open thread through review and a protected merge.

For: Feature teams and coding agents

Shape: One change, multiple actors

Schedule recurring repository maintenance

Combine a repository skill, timer, event, and thread into a repeatable maintenance loop.

For: Repository maintainers and agents

Concepts: Repo skills, timers, events, threads, pulls

Shape: Recurring external automation

Prevent duplicate event-driven work

Let several responders wake while only one performs a contested mutation.

For: Concurrent agent operators

Concepts: Events, idempotency, locks, heartbeats, fencing

Shape: Multi-agent exclusive work

Hand off interrupted work

Transfer ownership without confusing a lease with durable code and context recovery.

For: Agents resuming interrupted changes

Concepts: Locks, Git, threads, activity, repository rules

Shape: Failure recovery across actors

Choose an interface

Website

Inspect and manage work interactively.

Git

Store and transfer branches, commits, and files.

CLI

Run local commands and shell automation.

MCP

Expose typed platform tools to coding agents.

API

Build services and integrations.

Hosted and local skills

Share instructions or keep bootstrap copies local.

pearing-work

Route scoped events to external agent processes.

These are access and execution surfaces over one shared system of record, not separate workflows.