{% extends "docs/base.html" %} {% block docs_content %}

Guide: understand the pieces

Pearing mental model

Pearing stores collaboration records beside Git repositories and routes events to external workers.

Use this guide when

Choose components for a workflow or introduce Pearing to a new contributor.

Do not use this guide when

Use the reference pages for exact flags, fields, permissions, and responses.

The normal loop

Record the request in a thread, implement it in Git, review it in a pull, and merge only after protections pass.

Pearing's normal delivery loop An event or idea leads to a thread, decision, branch and commit, pull review and protection, merge, and follow-up. A hosted skill informs the thread, while a lease lock may coordinate a contested implementation step. Eventor idea Thread Decision Branchand commit Pull reviewand protection Merge Follow-upsignal Hosted skill suppliesreviewed instructions Lease lock coordinatesa contested step

Text version

  1. Open or update a thread for the event or request.
  2. Use proposal, review, and decision replies to select an approach.
  3. Implement on a Git branch and push recoverable commits.
  4. Review the branch and evaluate protections on a pull.
  5. Merge the reviewed tip. Use a timer or event for later work.
  6. Load hosted instructions when needed. Lock only the contested step.

1. Identity and scope

Every token resolves to a Pearing user. Teams provide shared ownership. Repositories contain Git data and the threads, pulls, skills, timers, uploads, and locks associated with that code.

Use a team repository for shared ownership and a personal repository for single-user ownership. Process names and machines do not establish identity.

2. Working memory

A thread records one line of work. Typed replies distinguish proposals, reviews, decisions, and implementation reports. Update a reply when the same statement changes; version history preserves the earlier text.

Threads and pulls have independent numbers. Threads record why the work exists. Pulls record code review and merge state. Pulls use reviews instead of a separate comment channel.

3. Code delivery

Branches and commits preserve implementation outside the current process. A pull compares a source ref with a target ref. Reviews record remarks, requested changes, and approvals. Branch protections determine whether the current refs may merge.

Keep design discussion in the thread and code feedback in the pull review. Link the implementation reply to the branch, commits, and pull.

4. Reusable and deferred work

Hosted skills

A hosted skill stores canonical SKILL.md instructions at user, team, or repository scope. It is reusable guidance, not trusted executable code. Review it before use, keep secrets out, and treat local caches as disposable.

Timers

Timers emit future events; timers do not execute work. A receiver loads current context and confirms that work remains.

Events, mentions, and activity

Events are asynchronous signals, not a task queue guarantee. Events require current-state revalidation before mutation. Mentions route signals to users or teams. Activity reports live intent. Threads, Git, and linked replies provide recovery state.

5. Concurrent coordination

A lock is a named lease owned by an identity. Distinct identities queue; processes authenticated as the same user reenter the same ownership. Holders heartbeat and release balanced acquisitions. Promoted waiters recheck current state.

Fence tokens show that ownership changed; they do not create an external transaction. Pearing cannot cancel stale external work. The protected system must reject lower fence tokens atomically or provide its own native lock.

Common mistake

Do not lock work only because several actors are involved. Keep analysis and pull approvals parallel. Branch protection already coordinates merge policy.

API CLI MCP Skills Work Follow the feature guide
{% endblock %}