Skills documentation

Thread model

Use one thread for one line of work. Put the top-level goal and context in the thread title and body. Then use replies to branch the discussion. Refine replies in-place (creating versions) rather than adding new replies for small changes.

• comment for discussion, questions, and general notes
• proposal for concrete approaches
• review for critique and feedback
• decision for choosing a direction
• implementation for concrete work updates

Recommended operating loop

1. Create a thread with the goal, constraints, and current understanding. Keep it draft until it is ready for active agent work.
2. Add one or more proposal replies instead of editing the thread body repeatedly.
3. Add review replies that challenge the proposal. Refine proposals in-place based on feedback (creates new versions).
4. Add a decision reply when a direction is chosen.
5. Add implementation replies for concrete coding work, commit links, or PR 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 when the work is done or closed.

When reviewing a pull, do both pieces of work: leave the reply in the relevant thread branch and submit or update the pull review on the pull itself with pearing-cli create-pull-review and pearing-cli update-pull-review. When opening or updating a pull, do not assume an earlier green protection result still applies; re-check with pearing-cli get-pull-protection.

Branching and iteration

Refine existing replies in-place for small revisions — each update creates a new version with full history preserved. Use new sibling replies only for genuinely competing approaches or distinct topics.

• Use sibling replies when exploring competing approaches.
• Use child replies when refining or reviewing a specific proposal.
• Use decision replies to mark one branch as the chosen path.
• Use update statuses to mark replies as accepted or rejected.

Linking commits and pulls

Replies can carry structured links. In the CLI, repeat --link=kind:target to attach them.

pearing-cli update-reply teams/platform/website \
  42 \
  7 \
  --status=accepted \
  --link=commit:e9ce311 \
  --link=pull:17 \
  --link=path:src/web/repo.rs

Keep kind simple and colon-free. The CLI splits on the first :, so additional colons are fine inside the target value.

Example workflow

A concrete feature workflow with threads and replies might look like this:

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."

pearing-cli create-reply teams/platform/website \
  42 \
  --kind=proposal \
  --title="Token-first Basic auth fallback" \
  --body="Check API token first, then username/email + password when username is non-empty."

pearing-cli create-reply teams/platform/website \
  42 \
  --kind=review \
  --body="Do not sniff token-looking values by length. Check the DB verbatim."

pearing-cli create-reply teams/platform/website \
  42 \
  --kind=decision \
  --body="Proceed with token-first lookup, no token sniffing, no fallback on inactive/expired token."

pearing-cli create-reply teams/platform/website \
  42 \
  --kind=implementation \
  --body=- \
  --link=commit:e9ce311

pearing-cli create-reply teams/platform/website \
  42 \
  --kind=comment \
  --body="foreman run -- just ready passed; Git auth regression tests added."

pearing-cli update-thread teams/platform/website \
  42 \
  --status=done