Skip to main content

Contributor quickstart

What lives here: the 15-minute path from "I want to contribute to bewith-docs" to a first merged PR.

For who: new collaborators on bewith-dev/bewith-docs — Baruch, future hires, anyone joining the platform repo. Not for product/feature onboarding (that's welcome.md).

Templates referenced below all live in docs/templates/.

Step 1 — One-time setup (10 min)​

a) Clone the repo​

cd ~/workspace        # or wherever you keep your repos
git clone git@github.com:bewith-dev/bewith-docs.git
cd bewith-docs

b) Install local git hooks​

bash scripts/install-git-hooks.sh

This catches issues (wrong branch names, oversized files, missing capability metadata) on your machine, before commit. Same checks run in CI, but local hooks save you a CI round-trip.

c) Install the bewith Claude Code plugin​

Follow install-bewith-plugin.md. Three slash commands from inside Claude Code. After this, every Claude session in every repo on your machine knows the platform's agents, skills, commands, hooks, and policies.

d) Authenticate the tools the task-lifecycle uses​

The task flow (/breakdown → state-sync → /continue → /done) talks to GitHub and ClickUp. Set both up once, or those commands fail with confusing auth errors:

  • GitHub CLI — /breakdown opens issues, /continue opens PRs, /done reads CI status, all via gh. Run gh auth login and confirm with gh auth status. (If gh ever acts as the wrong identity, a stray GITHUB_TOKEN is shadowing the keyring — unset GITHUB_TOKEN; the platform scripts already do this.)
  • ClickUp MCP — /breakdown reads the parent task and state-sync mirrors state to it through the ClickUp MCP server. Connect it in Claude Code's connectors/MCP settings. Without it, the ClickUp half of the flow errors unauthorized.

e) Read the load-bearing docs​

In this order, ~30 minutes total:

  1. docs/methodology/deterministic-ai.md — the 8 principles. Why the platform looks the way it does.
  2. docs/methodology/artifact-types.md — when to use a rule vs. hook vs. policy vs. agent vs. skill vs. command.
  3. CONTRIBUTING.md — the workflow (this doc is a fast-path; CONTRIBUTING.md is the complete reference).
  4. docs/methodology/session-safety.md — how to work in parallel without stomping anyone.

Step 2 — Your first PR​

Pick something small​

Good first PRs:

  • Fix a typo or broken link in a methodology doc.
  • Add a missing tag field to an artifact you noticed has none (pnpm capabilities finds them — pre-commit hook will catch missing metadata).
  • Document a workflow you already do as a new runbook under docs/runbooks/.
  • Propose a team rule you noticed in your past work using /share-rule (see propose-team-rule skill).

Skip these on your first PR until you've seen the workflow once:

  • A new agent (read _template.md, 15–25 KB target, sustained domain).
  • A new policy (read policy-engine.md).
  • A change to methodology docs (open an issue or /propose first).

Run the workflow​

git fetch origin master
git checkout -b <type>/<kebab-slug> origin/master
# ... make the change ...
git add <files>
git commit -m "type(scope): one-line summary"
git push -u origin <branch>
gh pr create        # or use the GitHub UI

Branch type prefixes:

PrefixWhen
feature/new-<artifact-type>-<name>A new platform artifact
feature/update-<artifact-type>-<name>Updating an existing artifact
fix/<short-desc>Bug fix
docs/<short-desc>Docs-only
chore/<short-desc>Tooling, housekeeping

Use the PR template​

The body is pre-populated from .github/pull_request_template.md. Fill every section — if one truly doesn't apply, write "N/A" with a reason. Reviewers and the AI code-reviewer agent both rely on the structure.

Step 3 — Review​

A code-owner (today: Ariel) reviews every PR. See CODEOWNERS for which paths require which owner.

What gets checked:

  • Right artifact shape per the decision tree
  • No duplication, no cycles
  • Metadata complete (tags, description, frontmatter)
  • English-only, no placeholder values
  • Worktree pattern if state-mutating
  • PR template sections filled

The code-reviewer Claude agent automatically runs the same checklist if you use Claude. The human reviewer has the final say.

Common gotchas​

SymptomCauseFix
branch-name-check.sh rejects your branchNaming pattern missSee branch prefixes table above
capability-index-check.sh rejects your commitNew artifact missing tags or descriptionAdd the frontmatter; pre-commit regenerates docs/capabilities.md
block-edit-on-master blocks an editYou're on master/main/develop/release/*git checkout -b <branch> first
Your PR has duplicate hooks firingYou're inside bewith-docs itself; plugin + project both run hooksExpected — see plugin install runbook "double-fire" section
Plugin doesn't show your latest artifactPlugin reads from your local clone; git pull was missinggit pull then /reload-plugins
CI fails on validate-pr for a path you didn't touchGenerated file drift (capabilities, lockfiles)Run the relevant generator (pnpm capabilities), commit the regenerated file
/breakdown fails with "label not found"Target repo wasn't seeded with the effort/urgency/domain vocabularybash scripts/sync-issue-labels.sh <owner/repo> once (idempotent), then retry — claude-init does this automatically when onboarding a repo
/breakdown or state-sync errors unauthorized (ClickUp)ClickUp MCP not connectedConnect it in Claude Code's MCP settings — see Step 1(d)

Where to ask​

  • Methodology question — open a discussion or /propose.
  • Bug in a hook or agent — open an issue with tag: hook-bug or tag: agent-bug.
  • Don't know if your idea belongs here vs. a consumer repo — ask Ariel in Slack #engineering, or /share-rule if it might be a team rule.

What's NOT here​

  • PRDs — those live in docs/prds/.
  • Application code — that lives in service repos (backend-api, singalong, etc.). This repo is platform-only.
  • Per-team configuration — those live in each consumer repo's own .claude/settings.json.

If you find yourself wanting to add something that doesn't fit either the methodology, an artifact type, or a planning doc shape — open a discussion before committing. We'd rather discuss the shape than have content land in the wrong place.

Cross-references​