Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (91 loc) · 4.96 KB

CONTRIBUTING.md

File metadata and controls

125 lines (91 loc) · 4.96 KB
Raw

Contributing to Forge

Forge is a shared knowledge base. Contributions are welcome from anyone — and every change is reviewed before it lands. This document explains the one contribution path and the single HARD RULE that governs it.

The one rule: No project-specific content ever enters Forge. No project names, no people's names, no local currency, no private file paths, no proprietary schema/field names, no business logic. Learnings must read as universal principles. A CI check enforces this on every PR — but write clean from the start; don't lean on it.

How knowledge gets in: fork → fold → PR

Forge's /forge cycle has an outgoing motion called fold — it absorbs learnings from your local membrane (~/.claude/learnings, ~/.claude/memory) into the Forge repo, genericizes them, commits, and pushes.

Fold pushes straight to origin/main. That's correct for your own clone — but it means you cannot fold directly into this repo, and you shouldn't want to: direct pushes to main are blocked. Instead, fold into a fork and open a PR.

1. Fork this repo

Use the GitHub Fork button. You now own your-username/forge.

2. Point your membrane at the fork

In your global rules (~/.claude/CLAUDE.md), set:

forge-path: /path/to/your/fork/of/forge

Clone your fork there and git remote add upstream the canonical repo so you can keep in sync:

# git -C /path/to/your/fork remote add upstream git@github.com:forge-arcana/forge.git

3. Run the cycle

/forge

Fold scans your membrane for Forge-worthy: yes learnings, genericizes them, presents the PLAN table, and — on your approval — commits and pushes to your fork. The PLAN table is your first quality gate; you decide what's worth sharing and confirm it's stripped of project specifics.

4. Open a Pull Request

From your fork to forge-arcana/forge:main. Describe what principle you're adding or changing — not where it came from. (If your commit message names a project or person, the purity check will flag it.)

5. Review and merge

A maintainer reviews every PR. The Fold Purity CI check must pass and the change must read as a universal principle. Approved PRs are squash-merged.

What makes a good contribution

  • A universal principle, not a war story. "Bind OAuth state to the browser session, not just sign it" — good. "We had a CSRF bug in the admin dashboard" — no.
  • Genericized. Strip the project, the people, the currency, the private paths, the proprietary identifiers.
  • Earns its place. Forge is curated, not a dumping ground. /purge periodically removes stale and duplicate knowledge; new entries should be worth keeping.

What will get a PR rejected

  • Any project-specific detail (the purity check catches most; reviewers catch the rest).
  • AI/agent attribution in commits (Co-Authored-By: Claude, "Generated by …"). Commits look like normal human commits.
  • Edits to /forge or /purge from a fold — these are protected skills and are never absorbed through the cycle.

Maintainer notes — branch protection

To keep "every change is reviewed" true, protect main so nothing reaches it except through an approved PR. Configure in Settings → Branches → Add branch ruleset (or with the gh CLI below):

Setting Value Why
Require a pull request before merging on No direct pushes to main.
Required approvals ≥ 1 A human (you) approves every change.
Dismiss stale approvals on new commits on A re-push re-opens review.
Require status checks to pass on → select Fold Purity The leak gate is mandatory, not advisory.
Require branches up to date before merging on PRs are tested against current main.
Require conversation resolution on No merging over unaddressed review comments.
Restrict who can push maintainers only Defense in depth.

Set it with the GitHub CLI (adjust owner/repo):

# gh api -X PUT repos/forge-arcana/forge/branches/main/protection \
#   -H "Accept: application/vnd.github+json" \
#   -f "required_pull_request_reviews[required_approving_review_count]=1" \
#   -F "required_pull_request_reviews[dismiss_stale_reviews]=true" \
#   -F "required_status_checks[strict]=true" \
#   -f "required_status_checks[checks][][context]=Scan changed learnings/memory for leaks" \
#   -F "enforce_admins=false" \
#   -F "restrictions=null"

The self-tension: your own fold vs. branch protection

Branch protection blocks your fold's direct push to main too. Pick one:

  • Stay exempt — leave enforce_admins=false (above). You keep folding directly to main; the world goes through PRs. Faster for you; the honor system applies to your own commits.
  • Eat your own dogfood — set enforce_admins=true. Your fold pushes to a branch and you self-PR. Slower, but every change — including yours — passes the same gate. Recommended once there are other contributors.