Community contributions are welcome. You can help improve Replica by reporting bugs, suggesting improvements, updating documentation, or submitting pull requests. You do not need to work at GitHub to contribute.
Please follow our Code of Conduct when participating.
This repository contains several projects with independent development and validation workflows.
The shared contributor guides apply to every project. Agents should also read the root instructions and any instructions in the area they are changing.
- Search existing issues and pull requests before proposing a change.
- Open an issue before starting a substantial product, architecture, security, or dependency change. Describe who needs the change, the outcome they need, and what the first version will not cover.
- Small bug fixes and documentation corrections may go directly to a pull request when the intended behavior is clear.
- Keep each contribution focused on one complete user flow or maintenance outcome.
Do not disclose a suspected vulnerability in a public issue or pull request. Follow the private reporting instructions in Security.
For bugs, describe what you expected, what happened, and how to reproduce the problem. Include relevant versions and error messages, but remove credentials and private information.
For improvements, explain the problem you want to solve and who would benefit. Discuss substantial changes with maintainers in an issue before starting implementation.
Replica Hub uses a devcontainer so contributors run the same Ruby, Node, SQLite, GitHub CLI, and Chromium versions.
-
Install Docker or another Docker-compatible container runtime.
-
Fork and clone the repository.
-
Start the devcontainer:
cd hub bin/devcontainer up -
Start Rails, Vite, and Solid Queue:
bin/devcontainer dev
Run Ruby and Node commands inside the container:
bin/devcontainer exec COMMANDSee Hub development for the full local workflow. Local GitHub integration requires a private development GitHub App and test repositories. Never install that App on production repositories.
Replica Starter requires npm and a Node.js version matching engines.node in starter/package.json:
node --version
cd starter
npm ci
npm run typecheck
npm test
npm run buildUpdate starter skills and context templates directly under starter/.agents/. Keep authored context in consuming repositories separate from those shared files. For starter-copy, static context library/link and plugin setup checks, run node --test scripts/create-prototype-repo.test.mjs scripts/setup-replica-plugin.test.mjs from the repository root. These checks do not verify agent authoring, semantic preservation or activation behavior; use the setup skill's real-host evaluation protocol for that evidence.
Reuse an existing compatible Node.js installation. If it is unavailable on macOS or Linux, get approval before installing nodenv, node-build, or Node.js, or changing shell configuration. The starter installer does not install them.
The shared build action requires npm, Chromium, and a Node.js version matching engines.node in actions/build/package.json:
cd actions/build
npm ci --ignore-scripts
npx playwright install chromium
npm run lint
npm testThe learning package requires Node.js 24, npm, and Git:
cd packages/learning
npm ci
npm run schema:check
npm test
npm run demonpm ci also installs the optional Copilot SDK, which labels review comments; the tests replace it with a stand-in, so they need no Copilot access. After changing a schema in contracts/v1, run npm run schema:generate and commit the regenerated src/contracts-validators.cjs. Hub's npm run lint lints and checks the formatting of this package. A new memory provider must pass the conformance suite described in the package guide.
For agent-assisted rendered checks, interaction tests, screenshots and reviews, use the browser canvas first. Follow browser validation guidance and Repository MCP configuration for the isolated Playwright MCP fallback only when the canvas is unavailable for a required check. Keep existing automated suites, CI and build-artifact capture drivers unchanged; they run without the Copilot canvas host.
Read the shared coding conventions and existing documentation for the area you are changing before editing code.
- For Hub changes, follow the existing system boundaries in Hub architecture.
- For Hub changes, follow the Rails, TypeScript, interface, and test rules in Hub coding conventions.
- Use Storybook for Hub presentation work and add or update a colocated story for each meaningful visual change. See Storybook.
- Follow the shared documentation conventions for prose, labels, errors, and code comments.
Follow the shared testing and review guide. For Hub code changes, run a focused test while developing, then run the complete Hub suite when the change is stable. Run this command from hub/:
bin/devcontainer exec bin/ciUseful focused commands include:
| Goal | Command |
|---|---|
| Rails test | bin/devcontainer exec bin/rails test PATH |
| TypeScript test | bin/devcontainer exec npm test -- PATH |
| Type check | bin/devcontainer exec npm run typecheck |
| Storybook build | bin/devcontainer exec npm run storybook:build |
| Prose review | bin/review-prose |
From the repository root, run hub/bin/review-prose to include changed prose across all projects. Hub and build-action dependency updates must satisfy the shared dependency policy. See Hub testing and operations for the complete Hub check and review workflow.
Use Conventional Commits for commit messages and PR titles: type(optional-scope): short description. For example, fix(hub): retain prototype history or docs: clarify contribution rules. Choose a type that reflects the change, such as feat, fix, docs, refactor, or test. These are conventions for contributors and agents; CI does not enforce PR titles.
Keep commits focused on logical changes so reviewers can follow the PR commit by commit. Use additional commits to respond to review feedback.
Use the PR template. Write short, simple English paragraphs for someone reading about the change for the first time. Explain why it is needed and what becomes different for users, operators, or contributors. Introduce necessary technical terms rather than relying on jargon. Link the issue when applicable.
Include an accurate Mermaid diagram when it makes a proposed flow or system boundary easier to understand. Before/after diagrams are especially useful when an existing flow changes. Use familiar labels, make clear what changes and what stays the same, and leave diagrams out when a sentence explains the proposal better.
Include screenshots or recordings for meaningful interface changes. Omit validation sections and checklists from the PR description. Do not repeat passing test or CI results. Leave statements such as "CI is green" and "tests passed" out of the description; GitHub displays the checks.
Still run the relevant checks before opening the PR. Mention only known verification gaps that affect the change, such as a required check that could not run or behavior that remains unverified. Describe the actual gap, not whether the agent drafting the description ran tests itself.
Maintainers may ask for revisions before merging. Contributions are reviewed for correctness, fit with the project's direction, and ongoing maintenance needs. Not every proposal or pull request will be accepted.
By submitting a contribution, you agree that it will be licensed under the project's MIT License.