Skill

pearing Thread Workflow

Rendered directly from the published SKILL.md.

Back to skills docs Download SKILL.md
Frontmatter
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:

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

Usage:

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:

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:

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

CLI patterns

Create a thread:

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:

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:

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:

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:

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

Create an implementation reply from stdin:

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:

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

Inspect the tree:

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:

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