---
name: pearing-thread-workflow
description: Coordinate agentic software engineering work through pearing repo threads and replies. Use when the user wants to plan, review, iterate, implement, and verify work on the pearing platform with pearing-cli.
---

# pearing Thread Workflow Skill

Use `pearing` repo threads and replies as the system of record for planning, review, and implementation.

## Purpose

- keep the full reasoning trail in `pearing`
- avoid local-only markdown planning files for active work
- make plan/review/revise/implement loops visible to other agents

## Local environment

- the user should create a `pearing.env` file in the same folder as this skill
- `pearing.env` should define:
  - `PEARING_API_URL`
  - `PEARING_API_TOKEN`
- `pearing-cli` can load the env file directly with the `-E`/`--env` flag instead of manually exporting the variables

Example `pearing.env`:

```bash
PEARING_API_URL=https://example.com/api
PEARING_API_TOKEN=your-token-here
```

Usage:

```bash
pearing-cli --env pearing.env list-threads teams/platform/website
pearing-cli -E pearing.env get-self
```

## Core model

- create one thread per change, discussion, or task
- use the thread title and body for the top-level goal and context
- use replies for iterative work; refine replies in-place (creating versions) rather than adding new replies for small changes

## Reply kinds

- `comment`
- `proposal`
- `review`
- `decision`
- `implementation`

## Operating rules

- refine existing replies in-place instead of creating new replies for small revisions
  - updating a proposal, review, or implementation creates a new version of that reply
  - the version history is preserved automatically — previous versions remain accessible
  - this keeps threads focused and avoids bloat from incremental refinement replies
- use new sibling replies only for genuinely competing approaches or distinct topics
- use child replies for focused review on one proposal
- use a `decision` reply when a branch is chosen
- use `implementation` replies for code changes and concrete work updates
- when reviewing a pull, leave the reply in the relevant thread branch and also submit or update the pull review on the pull itself
- when you open a pull or update an existing pull, re-run `pearing-cli get-pull-protection` and verify the pull still satisfies protections before you call it ready
- do not do proposal, review, or implementation work on threads marked `draft`; wait until the thread is moved to `open`

## Markdown formatting

All thread bodies, reply bodies, and pull descriptions are rendered as markdown. Use proper formatting:

- use single backticks for inline code such as identifiers, type or function names, file paths, CLI commands and flags, API routes, and SQL keywords or expressions when referenced within prose
- use triple-backtick fenced code blocks with a language tag for block or multi-line content such as code snippets, CLI examples, SQL queries, configuration, JSON, logs, file lists, or other structured output
- prefer specific language tags (```rust```, ```sql```, ```bash```, ```text```) over bare ``` fences
- only literal code or structured output belongs in code fences; keep prose, bullet lists, and narrative text as normal markdown

## Current activity

- at the start of each task or turn, update your current activity to say what you are actively doing
- at the end of the task or turn, update it again to say what you are now waiting for or expecting next
- keep the text short, concrete, and tied to the actual pearing work item

Examples:

```bash
pearing-cli update-user-activity self \
  --activity="Writing a proposal for thread 136 user activity"
pearing-cli update-user-activity self \
  --activity="Waiting for feedback on proposal for thread 136 user activity"
```

The point is to keep other users and agents informed in real time:
- what you are doing now
- what you are blocked on or waiting for next

## Status rules

- update reply status as discussion converges:
  - `open`
  - `accepted`
  - `rejected`
- update thread status when the work state changes:
  - `open`
  - `draft`
  - `closed`
  - `done`

A thread in `draft` is still being fleshed out and is not ready for active agent work.

## Link rules

- attach commit, pull, branch, or path references with repeated `--link=kind:target`
- `kind` must not contain `:`
- `target` may contain additional `:`

Examples:

```bash
--link=commit:e9ce311
--link=pull:17
--link=branch:feature/git-auth
--link=path:src/web/repo.rs
```

## CLI patterns

Create a thread:

```bash
pearing-cli create-thread teams/platform/website \
  --title="Add Git HTTP password auth" \
  --body="Goal: allow password auth for Git smart-HTTP without changing API auth."
```

Create a proposal reply:

```bash
pearing-cli create-reply teams/platform/website \
  THREAD_NUMBER \
  --kind=proposal \
  --title="Token-first Basic auth fallback" \
  --body="Check API token first, then fallback to username/email + password."
```

Create a review reply:

```bash
pearing-cli create-reply teams/platform/website \
  THREAD_NUMBER \
  --kind=review \
  --body="Do not sniff token-like values by length. Check the database verbatim."
```

Create a pull review:

```bash
pearing-cli create-pull-review teams/platform/website \
  17 \
  --status approved \
  --body="LGTM. Leaving the corresponding review reply in the linked thread."
```

Check pull protections after opening or updating a pull:

```bash
pearing-cli get-pull-protection teams/platform/website 17
```

Create an implementation reply from stdin:

```bash
printf '%s\n' \
  'Implemented Git smart-HTTP password fallback.' \
  'Added regression coverage for inactive and expired token behavior.' \
| pearing-cli create-reply teams/platform/website \
    THREAD_NUMBER \
    --kind=implementation \
    --body=- \
    --link=commit:e9ce311
```

Update a reply:

```bash
pearing-cli update-reply teams/platform/website \
  THREAD_NUMBER \
  REPLY_NUMBER \
  --status=accepted \
  --link=pull:17
```

Inspect the tree:

```bash
pearing-cli get-thread-tree teams/platform/website THREAD_NUMBER
pearing-cli list-replies teams/platform/website THREAD_NUMBER
pearing-cli get-reply teams/platform/website THREAD_NUMBER REPLY_NUMBER
```

Close out the thread:

```bash
pearing-cli update-thread teams/platform/website THREAD_NUMBER --status=done
```

## Recommended loop

1. Create the thread with the goal and constraints.
2. Add one or more proposal replies.
3. Add review and comment replies under those proposals. Refine proposals in-place based on feedback (creates new versions).
4. Add a decision reply once a direction is chosen.
5. Add implementation replies with commit or pull links.
6. When you open or update a pull, re-run `pearing-cli get-pull-protection` and verify the pull still satisfies protections.
7. Update the thread status to reflect the final state.

## Mentions

When creating threads, replies, and pulls, mention relevant users and teams so they receive notifications.

- use `@username` to mention a specific user
- use `@team/slug` to mention an entire team
- mention the user who assigned the work, reviewers, and anyone whose input is needed
- only mention users or teams that are relevant to the content — do not mention unnecessarily

## Collaboration expectations

- proposal agents should add concrete alternatives, not vague summaries
- reviewer agents should reply in the relevant thread branch for the work they are reviewing
- when reviewing a pull, reviewer agents should also submit or update the pull review on the pull itself
- implementation agents should link commits and pulls back to the relevant reply branch
- preserve the branch structure so another agent can understand how the work converged