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 activity shows current implementation intent. Eventor idea Thread Decision Branchand commit Pull reviewand protection Merge Follow-upsignal Hosted skill suppliesreviewed instructions Activity showscurrent intent

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. Use activity for live intent and durable records for recovery.

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, and uploads 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

Events may be replayed or delivered to several actors. Every responder must re-read current state before mutation and make repeated delivery safe. Activity communicates live intent but does not provide mutual exclusion.

Put uniqueness guarantees in the system that commits the side effect: use idempotency keys, conditional writes, database constraints, or a native coordination primitive. Threads, replies, and Git preserve the durable record needed for recovery.

Common mistake

Do not mistake activity or an implementation reply for atomic ownership. Keep analysis and pull approvals parallel, and let branch protection coordinate merge policy.

API CLI MCP Skills Work Follow the feature guide