onboard-contributor

name	onboard-contributor
description	Use when a new person or their AI agent wants to start contributing to The For Good Project and asks how to claim work or where to begin. Gets them from zero to a running work loop with a single paste-this-to-your-agent block. The runner scripts own claiming, labels, PR routing, and review status transitions; this skill only helps someone run one correctly.

Onboard a contributor: paste-this-and-go

The runner scripts already automate contributing here, so do not hand-claim issues or juggle status labels. Run scripts/start_work.sh; it claims available work, runs an agent in a fresh throwaway git worktree, and moves the issue through the status lifecycle described in docs/AUTOMATION.md. For review, run scripts/review_work.sh; it reviews open PRs in fresh worktrees and owns the adversarial-review check.

When to use

• Someone new says "I've got write access, now what?" or "how do I actually pick up work?"
• A contributor wants to lend spare tokens or compute without micromanaging GitHub.
• You're helping a person configure Claude Code, codex, or hermes to work the queue.

Choose the right path

You have	Do this
Write/triage access plus a terminal and AI CLI	Autopilot: run scripts/start_work.sh — the scripts do the claiming and PR routing for you.
Write access but no AI CLI	Manual claim: use the GitHub UI to assign yourself, move status: available to status: claimed, do one issue, and open a PR that says Closes #<n> unless the issue is a Discover stream root.
No write access	Fork + PR: follow AGENTS.md. You can still contribute, but the upstream queue runner cannot claim issues without permission.

Prerequisites

• git, gh authenticated with gh auth status, and jq on PATH.
• One agent CLI: claude (default), codex, or hermes.
• On macOS, install GNU timeout as gtimeout with brew install coreutils; without timeout/gtimeout, AGENT_TIMEOUT cannot stop a hung agent.
• For adversarial review of your own PRs, a second GitHub identity or GitHub App token with write access, supplied as REVIEW_GITHUB_TOKEN.

The paste-this-to-your-agent block

You're helping me contribute to The For Good Project
(github.com/thecolab-ai/the-for-good-project), a commons where people and AI
agents research real NZ social problems to a cited, honest standard.

Do this, checking with me only if something genuinely needs a human decision:
1. Confirm my tooling: git, gh (run `gh auth status`), jq, and one of
   claude/codex/hermes on PATH.
2. If I don't have the repo, clone it and cd in:
   gh repo clone thecolab-ai/the-for-good-project && cd the-for-good-project
   If I do not have write/triage access, follow AGENTS.md's fork + PR path
   instead; the upstream runner cannot claim issues without permission.
3. Read CONTRIBUTING.md, docs/METHOD.md, AGENTS.md, and docs/AUTOMATION.md.
   Follow the project method: cite every claim, verify surprising or
   load-bearing claims with two independent sources where possible, mark
   confidence High/Medium/Low, end with what would change the conclusion, never
   invent sources or publish personal data, and respect the human gates.
4. Run the work loop:
   scripts/start_work.sh
   It picks up your assigned rework first, otherwise claims the next available
   issue, creates a fresh worktree, gives the issue to the agent, and moves the
   issue to in-review once the PR is open. The script owns status labels,
   assignees, rework routing, and PR detection. Do not hand-edit labels or push
   anything past the adversarial review gate.

   Common options:
   - One task then stop:       MAX=1 scripts/start_work.sh
   - Only one stage:           STAGE=research scripts/start_work.sh
   - A specific CLI:           scripts/start_work.sh codex
   - A specific model:         scripts/start_work.sh codex --model gpt-5.5
   - Stop when queue is empty: POLL_SECONDS=0 scripts/start_work.sh
   - Dry run:                  DRY_RUN=1 scripts/start_work.sh
5. When it opens a PR, show me the PR URL and a two-line summary.

To review instead of produce

Adversarial review must be by a different identity than the PR author: branch protection requires a non-author approval, and review_work.sh refuses to review a PR authored by the reviewer identity.

REVIEW_GITHUB_TOKEN=<second-account-or-bot-PAT-with-write> scripts/review_work.sh

review_work.sh claims an open PR with review: claimed, checks out the PR head in a fresh worktree, asks the agent to review the change, posts the review, sets the required for-good/adversarial-review status check, and merges on PASS by default. Useful options:

REVIEW_GITHUB_TOKEN=<token> scripts/review_work.sh codex
REVIEW_GITHUB_TOKEN=<token> scripts/review_work.sh hermes --model <name>
REVIEW_GITHUB_TOKEN=<token> AUTO_MERGE=0 scripts/review_work.sh
PR=7 scripts/review_work.sh
MAX=1 POLL_SECONDS=0 scripts/review_work.sh

If you run without REVIEW_GITHUB_TOKEN, the script reviews as the currently authenticated gh user and skips PRs authored by that same identity.

What not to do

• Do not self-review; the script refuses it and branch protection blocks it.
• Do not hand-manage labels while the loop runs; the scripts and issue-status.yml own status transitions.
• Do not bypass the adversarial review gate or admin-merge your own work.
• Do not use the agent review loop on PRs labelled review: human-only; those are for human maintainers.
• Do not run start_work.sh on synthesis draft rework. Synthesis branches are routed through synthesize_work.sh.

Non-goals

This skill only onboards contributors and points them at the existing runner scripts. It does not change the queue contract, runner scripts, status labels, review requirements, merge rules, or human gates. Those are governance and ADR-level decisions, not a skill edit.