Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
99 lines (77 loc) · 4.78 KB

CONTRIBUTING.md

File metadata and controls

99 lines (77 loc) · 4.78 KB
Raw

Contributing to forgekit

forgekit is one brain for every AI coding agent — a cognitive substrate (memory, foresight, guardrails) authored once and compiled into every tool's native config. Keeping that brain small and dependency-free is the whole point, so please read this before opening a PR.

Ground rules

  • Zero runtime dependencies. forgekit ships with no production dependencies. PRs adding one are rejected unless there's an exceptional, discussed reason. Dev dependencies (test/lint tooling) are fine.
  • Node.js ESM only. All code is ES modules ("type": "module"). No CommonJS.
  • Supported Node versions: 20 and 22 (the >=20 engines floor; Node 18 is EOL).
  • Cross-tool first. New behavior should work across the tools forgekit targets (Claude Code, Codex, Cursor, Gemini, Aider, …), emitted from one source — not Claude-only. Say so in the PR if a piece is unavoidably tool-specific.

Getting started

git clone https://github.com/CodeWithJuber/forgekit.git
cd forgekit
npm ci
npm test          # node --test
npm run check     # Biome lint + format check

Making changes

  1. Branch: git checkout -b feat/my-change.
  2. Write the change plus tests — every new public function needs at least one test. Shell guards are tested via spawnSync (see test/guards.test.js).
  3. Run npm test, npm run typecheck, and npm run check:fix before committing.
  4. Use Conventional Commits: feat(scope): description, fix: …, docs: ….
  5. Add a line to CHANGELOG.md under ## [Unreleased]. This is your release note — when your PR merges, the auto-release uses it verbatim. (Skip it and the release still cuts, synthesizing notes from your commit subjects — but your wording is better.)
  6. Open a PR. CI (tests on Node 20/22, Biome, typecheck, shellcheck) must pass.

Project shape

  • src/ — the zero-dep CLI + emitters + subsystems (verify, brain, atlas, …).
  • source/ — the single rule + MCP source that forge sync compiles.
  • global/ — what installs into ~/.forge: tools/ (skills), crew/ (agents), guards/ (hooks).
  • docs/cognitive-substrate/ — the committed paper bundle, evidence maps, and prototype artifacts that explain forge substrate and forge impact.
  • test/ — node --test suites.

Before you open a PR

Low-value PRs (typo-only drive-bys on generated files, unrequested rewrites, AI-generated diffs with no tests) will be closed. To get merged:

  • Discuss non-trivial changes first in Discussions so you don't build something we can't accept (for example, anything that adds a runtime dependency).
  • Don't edit generated files — anything with a DO NOT EDIT — generated by forge sync header, or files under .forge/. Change the source (source/) instead.
  • Include tests and pass CI. A small green diff a maintainer can verify beats a large one they can't.
  • Substrate changes need docs. If you change forge substrate, forge impact, router/gate rubrics, or MCP substrate tools, update docs/cognitive-substrate/README.md and CHANGELOG.md.

We'd rather give a clear "not now" than merge something that adds maintenance burden — see GOVERNANCE.md.

Releasing (maintainers)

Releases are automatic: merging a feat/fix/perf/breaking change to master cuts the release itself (bump → tag → npm publish → GitHub Release); chore/docs-only merges skip cleanly. A manual Actions → Bump version dispatch is still available. The full runbook (and the one-time NPM_TOKEN setup) is in docs/RELEASING.md.

Sign your work (DCO)

This project uses the Developer Certificate of Origin. Add a Signed-off-by line to each commit (git commit -s), certifying you wrote the code or can contribute it.

By contributing you agree to abide by our Code of Conduct.

AI-assisted contributions

AI-assisted PRs are welcome if you understand and stand behind the change and it meets the same bar as any other PR (tests, passes CI, in scope). We close AI-generated PRs that are unreviewed, cosmetic-only, or clearly not run/tested — reviewer time is the scarce resource. If an AI wrote it, you are still the author: sign off (DCO) and be ready to explain it.

Dependency policy

  • Runtime: none — see ADR 0001.
  • Dev dependencies: permissive licenses only (MIT / Apache-2.0 / BSD / ISC). No GPL/AGPL or source-available (BSL/SSPL) dev deps. Dependabot proposes weekly updates with a 7-day cooldown; the dependency-review CI job enforces the license + vulnerability rules on PRs.