Contribution guide

Make one focused change that can be reviewed.

Contribute primitives, Plays, documentation, schemas, tests, or platform fixes through the real repository workflow. No points, fake rankings, or automatic-publish promise replaces maintainer review.

Read CONTRIBUTING.md

Local setup

Clone, install, validate

The public repository is an npm workspace. Run the source-controlled scripts instead of obsolete website CLI examples.

Terminal

git clone https://github.com/frootai/frootai.git
cd frootai
npm install

# Validate canonical primitives
npm run validate:primitives

# Run repository consistency validation
npm run validate

# Run FAI Protocol conformance
npm run test:conformance

Primitive paths

Use the repository scaffolder

Agent

agents/*.agent.md

A scoped specialist with explicit tools, boundaries, and compatible architecture context.

node scripts/scaffold-primitive.js agent

Instruction

instructions/*.instructions.md

Repository guidance with description and an applyTo glob.

node scripts/scaffold-primitive.js instruction

Skill

skills/<name>/SKILL.md

Reusable procedure whose name matches its folder and whose steps are testable.

node scripts/scaffold-primitive.js skill

Hook

hooks/<name>/hooks.json

Lifecycle automation with a valid event and an existing script.

node scripts/scaffold-primitive.js hook

Pull-request workflow

From branch to maintainer review

CI can validate structure and tests. It does not replace review or guarantee publication to every channel.

Fork and branch

Create a focused `feat/*`, `fix/*`, or `docs/*` branch. Never push directly to main.

Scaffold or edit

Use the repository scaffold script for primitives, or make a bounded change to an existing artifact.

Validate locally

Run primitive validation, consistency checks, and the tests relevant to the touched area.

Open a PR

Explain behavior, evidence, risk, validation, and any remaining limitations.

Address review

Work with maintainers and keep the branch focused until required checks pass.

Before opening a PR

A reviewable change has evidence

File and folder names follow the repository convention.
Required frontmatter or JSON fields are present and parse correctly.
No secrets, API keys, tokens, or connection strings are committed.
WAF and FAI Protocol claims are supported by the artifact, not only prose.
Documentation describes setup, behavior, boundaries, and validation.
Relevant tests and generation checks pass locally.

Ready to contribute?

Start with source and a focused issue.

Issues Community Pull requests