From 83a570235f87801a5abde39535d517bb4d23ce24 Mon Sep 17 00:00:00 2001 From: Advait Paliwal Date: Fri, 27 Mar 2026 12:09:09 -0700 Subject: [PATCH] docs: add contributor guide and repo skill --- CONTRIBUTING.md | 114 +++++++++++++++++++++++++++++++++++ README.md | 8 ++- package.json | 1 + skills/contributing/SKILL.md | 28 +++++++++ 4 files changed, 149 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 skills/contributing/SKILL.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..77cd88c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,114 @@ +# Contributing to Feynman + +Feynman is a research-first CLI built on Pi and alphaXiv. This guide is for humans and agents contributing code, prompts, skills, docs, installers, or workflow behavior to the repository. + +## Quick Links + +- GitHub: https://github.com/getcompanion-ai/feynman +- Docs: https://feynman.is/docs +- Repo agent contract: [AGENTS.md](AGENTS.md) +- Issues: https://github.com/getcompanion-ai/feynman/issues + +## What Goes Where + +- CLI/runtime code: `src/` +- Bundled prompt templates: `prompts/` +- Bundled Pi skills: `skills/` +- Bundled Pi subagent prompts: `.feynman/agents/` +- Docs site: `website/` +- Build/release scripts: `scripts/` +- Generated research artifacts: `outputs/`, `papers/`, `notes/` + +If you need to change how bundled subagents behave, edit `.feynman/agents/*.md`. Do not duplicate that behavior in `AGENTS.md`. + +## Before You Open a PR + +1. Start from the latest `main`. +2. Use Node.js `20.19.0` or newer. The repo expects `.nvmrc`, `package.json` engines, `website/package.json` engines, and the runtime version guard to stay aligned. +3. Install dependencies from the repo root: + +```bash +nvm use || nvm install +npm install +``` + +4. Run the required checks before asking for review: + +```bash +npm test +npm run typecheck +npm run build +``` + +5. If you changed the docs site, also validate the website: + +```bash +cd website +npm install +npm run build +``` + +6. Keep the PR focused. Do not mix unrelated cleanup with the real change. +7. Add or update tests when behavior changes. +8. Update docs, prompts, or skills when the user-facing workflow changes. + +## Contribution Rules + +- Bugs, docs fixes, installer fixes, and focused workflow improvements are good PRs. +- Large feature changes should start with an issue or a concrete implementation discussion before code lands. +- Avoid refactor-only PRs unless they are necessary to unblock a real fix or requested by a maintainer. +- Do not silently change release behavior, installer behavior, or runtime defaults without documenting the reason in the PR. +- Use American English in docs, comments, prompts, UI copy, and examples. + +## Repo-Specific Checks + +### Prompt and skill changes + +- New workflows usually live in `prompts/*.md`. +- New reusable capabilities usually live in `skills//SKILL.md`. +- Keep skill files concise. Put detailed operational rules in the prompt or in focused reference files only when needed. +- If a new workflow should be invokable from the CLI, make sure its prompt frontmatter includes the correct metadata and that the command works through the normal prompt discovery path. + +### Agent and artifact conventions + +- `AGENTS.md` is the repo-level contract for workspace conventions, handoffs, provenance, and output naming. +- Long-running research flows should write plan artifacts to `outputs/.plans/` and use `CHANGELOG.md` as a lab notebook when the work is substantial. +- Do not update `CHANGELOG.md` for trivial one-shot changes. + +### Release and versioning discipline + +- The curl installer and release docs point users at tagged releases, not arbitrary commits on `main`. +- If you ship user-visible fixes after a tag, do not leave the repo in a state where `main` and the latest release advertise the same version string while containing different behavior. +- When changing release-sensitive behavior, check the version story across: + - `.nvmrc` + - `package.json` + - `website/package.json` + - `scripts/check-node-version.mjs` + - install docs in `README.md` and `website/src/content/docs/getting-started/installation.md` + +## AI-Assisted Contributions + +AI-assisted PRs are fine. The contributor is still responsible for the diff. + +- Understand the code you are submitting. +- Run the local checks yourself instead of assuming generated code is correct. +- Include enough context in the PR description for a reviewer to understand the change quickly. +- If an agent updated prompts or skills, verify the instructions match the actual repo behavior. + +## Review Expectations + +- Explain what changed and why. +- Call out tradeoffs, follow-up work, and anything intentionally not handled. +- Include screenshots for UI changes. +- Resolve review comments you addressed before requesting review again. + +## Good First Areas + +Useful contributions usually land in one of these areas: + +- installation and upgrade reliability +- research workflow quality +- model/provider setup ergonomics +- docs clarity +- preview and export stability +- packaging and release hygiene diff --git a/README.md b/README.md index bb67de6..7e9a54c 100644 --- a/README.md +++ b/README.md @@ -136,12 +136,16 @@ Built on [Pi](https://github.com/badlogic/pi-mono) for the agent runtime, [alpha ### Contributing +See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide. + ```bash git clone https://github.com/getcompanion-ai/feynman.git cd feynman nvm use || nvm install -pnpm install -pnpm start +npm install +npm test +npm run typecheck +npm run build ``` [Docs](https://feynman.is/docs) ยท [MIT License](LICENSE) diff --git a/package.json b/package.json index c0abd52..bfe66b7 100644 --- a/package.json +++ b/package.json @@ -26,6 +26,7 @@ "scripts/", "skills/", "AGENTS.md", + "CONTRIBUTING.md", "README.md", ".env.example" ], diff --git a/skills/contributing/SKILL.md b/skills/contributing/SKILL.md new file mode 100644 index 0000000..f1806c7 --- /dev/null +++ b/skills/contributing/SKILL.md @@ -0,0 +1,28 @@ +--- +name: contributing +description: Contribute changes to the Feynman repository itself. Use when the task is to add features, fix bugs, update prompts or skills, change install or release behavior, improve docs, or prepare a focused PR against this repo. +--- + +# Contributing + +Read `CONTRIBUTING.md` first, then `AGENTS.md` for repo-level agent conventions. + +Use this skill when working on Feynman itself, especially for: + +- CLI or runtime changes in `src/` +- prompt changes in `prompts/` +- bundled skill changes in `skills/` +- subagent behavior changes in `.feynman/agents/` +- install, packaging, or release changes in `scripts/`, `README.md`, or website docs + +Minimum local checks before claiming the repo change is done: + +```bash +npm test +npm run typecheck +npm run build +``` + +If the docs site changed, also validate `website/`. + +When changing release-sensitive behavior, verify that `.nvmrc`, package `engines`, runtime guards, and install docs stay aligned.