docs: add contributor onboarding guide

CONTRIBUTING.md

@@ -2,6 +2,11 @@
 
 We work in public. If you can read this, you can help.
 
+New here? Start with the
+[contributor onboarding guide](CONTRIBUTOR_ONBOARDING.md) for how to claim work,
+which setup to use for each work area, communication norms, ownership, and Slack
+welcome templates.
+
 ## How we work
 
 **Issues** = "this needs to happen." If you can scope it, you can claim it.

CONTRIBUTOR_ONBOARDING.md

@@ -0,0 +1,119 @@
+# Contributor onboarding
+
+Welcome to Opportunity Hack. This repo is the public operating board for work that
+helps nonprofits, mentors, judges, sponsors, and hackathon volunteers ship more
+reliably.
+
+## Start here
+
+1. Read the [README](README.md) for the current roadmap.
+2. Read [CONTRIBUTING.md](CONTRIBUTING.md) for how issues, PRs, and reviews work.
+3. Join [Slack](https://slack.ohack.dev) and say hello in `#contributors`.
+4. Pick a small issue labeled [`good-first-task`](../../issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-task).
+5. Comment with "I'd like to take this" and a 1-2 sentence plan.
+
+Wait for a maintainer to assign the issue before doing a large amount of work. If
+you are only fixing a typo or clarifying a document, it is fine to open a small PR
+and explain the change.
+
+## How to claim work
+
+Use this comment format when claiming an issue:
+
+```text
+I'd like to take this.
+
+Plan:
+- What I will change
+- How I will verify it
+- Any question or dependency I need answered first
+```
+
+If the issue is labeled `help-wanted`, start with a design comment instead of a
+PR. Those issues are usually larger or less defined.
+
+## Development environments
+
+Most work in this repo falls into one of these areas:
+
+| Area | Typical work | Local setup |
+| --- | --- | --- |
+| Ops docs | README, contributor docs, issue bodies, sponsor/community plans | Any editor plus Git |
+| Bootstrap scripts | `scripts/setup.sh`, labels, milestones, issue creation | `gh`, `jq`, Bash |
+| Product planning | PRDs, SRDs, UX flows, product decisions | Markdown and GitHub Issues |
+| Website or app work | Future Next.js, FastAPI, Postgres, Cloudflare work | Follow the linked repo setup |
+
+For this repo, validate shell changes with:
+
+```bash
+bash -n scripts/setup.sh
+```
+
+For documentation-only changes, run:
+
+```bash
+git diff --check
+```
+
+When a task points to another codebase, follow that repository's setup and test
+instructions instead of guessing from this ops repo.
+
+## Communication norms
+
+- Keep planning and decisions in public GitHub issues or discussions.
+- Use Slack for quick questions, pairing, and finding the right owner.
+- Ask early when you are blocked for more than a day.
+- Prefer small PRs that reviewers can understand in one sitting.
+- If you use AI tools, make sure you understand and can explain the work.
+
+## Who owns what
+
+| Area | First place to ask |
+| --- | --- |
+| Contributor pipeline, Slack, and community rituals | `#contributors` |
+| Hackathon mentors, judges, and event operations | Relevant GitHub issue, then Slack |
+| Product planning and technical architecture | Issue discussion before PR |
+| Sponsorship, nonprofit intake, and outreach | Issue owner or maintainer tagged on the task |
+| Repo labels, milestones, setup scripts, and project board | Maintainers in this repo |
+
+If you do not know the owner, ask in `#contributors` with a link to the issue.
+
+## Welcome message template
+
+```text
+Welcome to Opportunity Hack, <name>!
+
+Glad to have you here. A good first path is:
+1. Read https://github.com/opportunity-hack/ops/blob/main/CONTRIBUTOR_ONBOARDING.md
+2. Pick a good-first-task issue
+3. Comment with your plan before you start
+
+If you share your background or what kind of work you want to do, we can point you
+to an issue that fits.
+```
+
+## Suggested Slack pinned posts
+
+Pin these in `#contributors`:
+
+```text
+Start here:
+https://github.com/opportunity-hack/ops/blob/main/CONTRIBUTOR_ONBOARDING.md
+```
+
+```text
+Good first tasks:
+https://github.com/opportunity-hack/ops/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-task
+```
+
+```text
+How to claim work:
+Comment on the issue with "I'd like to take this" plus a 1-2 sentence plan.
+Wait for assignment before doing large work.
+```
+
+```text
+Office hours:
+Post questions here any time. If you are blocked for more than a day, ask for help
+with a link to the issue or PR.
+```

README.md

@@ -26,6 +26,10 @@ See the [project board](../../projects) for everything.
 
 Comment on an issue to claim it. We'll respond within a few days.
 
+New contributors can follow the one-page
+[contributor onboarding guide](./CONTRIBUTOR_ONBOARDING.md) for how to claim work,
+set up for different task areas, and ask for help.
+
 ## Roadmap
 
 The short version of where we're headed: