[docs] Add contribution scaffolder script

[mvanhorn]

Contribution Type

• Recipe (/recipes)
• Schema (/schemas)
• Dashboard (/dashboards)
• Integration (/integrations)
• Skill (/skills)
• Repo improvement (docs, CI, templates)

What does this do?

node scripts/new-contribution.mjs generates a complete, correctly structured contribution folder from the category's existing _template/, so starting a contribution is one command instead of copy the right template, rename the folder, hand-author metadata.json, and remember which extra fields your category needs.

Why

Today CONTRIBUTING.md says "Check the _template/ folder in each category for a starter README", and the rest is manual. A contributor has to pick one of seven _template/ directories, copy it, rename it, and hand-write a metadata.json with nine required fields plus category-conditional extras (learning_order for extensions, requires_primitives / requires_skills when depending on other contributions).

Getting any of that wrong is not a soft failure, it is a rule failure in the automated review: folder structure, required files, metadata validity, category-specific artifacts, and README completeness are all mechanically checked. The contributor finds out after opening a PR.

That lands hardest on exactly the people CONTRIBUTING.md goes out of its way to invite. The "Not a Developer? You Can Still Contribute" path and the mentor model bring in contributors least likely to hand-assemble a seven-way template choice and a conditional JSON manifest correctly.

The pattern is well established elsewhere: Home Assistant ships python3 -m script.scaffold integration, and npm standardises on create-* initializers. The .github/ISSUE_TEMPLATE/ directory here already shows the same instinct on the issue side; this is the PR-side equivalent.

Design decisions

Three choices are load-bearing:

The _template/ folders stay the source of truth. The script copies from them rather than embedding template text, so a maintainer editing a template automatically changes generator output. There is no second copy of the prose to drift. It deliberately does not modify any _template/ folder.

Non-interactive first. Every value has a flag, so the AI clients this project targets can drive it directly. Interactive prompts are the fallback when a required flag is absent and stdin is a TTY.

It refuses to do damage. Scaffolding onto an existing folder exits without writing. --force is deliberately not implemented. Declared dependencies are validated as slugs and checked to exist, so a typo like --requires-skills meeting-triage fails immediately rather than producing metadata and README links that the review rules then reject.

Testing

node --test scripts/*.test.mjs covers 15 cases: a scaffold in each of the seven categories asserting the artifacts that category requires, extension learning_order and tool-audit link, skills emitting a plain-text skill file, schemas emitting SQL with the required grant line, requires_skills written to metadata and linked from the README, invalid difficulty exiting without writing, refusing an existing target, and rejecting both malformed and nonexistent dependency slugs.

I also generated a scaffold in all seven categories and checked each result against the rules in .github/workflows/ob1-gate-v2.yml (folder structure, required files, metadata schema, category artifacts, README sections). All seven satisfied them. CI remains authoritative.

Notes

Community extensions can omit --learning-order; per extensions/_template/AGENT_SPEC.md only curated learning-path extensions set it. Supplied --requires-primitives merge with the template's mandatory primitives rather than replacing them.

The generated primitive README includes the placeholder dependency reference as plain text rather than a relative link, so a fresh scaffold does not ship a link that resolves nowhere.

Requirements

Node.js 18 or newer. Nothing else: zero runtime dependencies, built-ins only (node:fs, node:path, node:readline/promises, node:util), matching the existing scripts/update-readme-contributions.mjs. No root package.json is added and no _template/ folder is modified.

AI was used for assistance. I ran the tests and the scaffolds shown above myself and verified the output against the repository's review rules.

Checklist

• I've read CONTRIBUTING.md
• No credentials, API keys, or secrets are included
• The new script is documented in scripts/README.md with usage, flags, and exit codes

The remaining template items describe a contribution folder, which this PR does not add. Marking them honestly rather than ticking them:

• README.md / metadata.json required fields: not applicable, no contribution folder is added here. The script's job is to produce those correctly, which the tests and the seven-category check above cover.
• Declared skill or primitive dependency: not applicable.
• Tested on my own Open Brain instance: not applicable, this is repository tooling and does not touch a running Open Brain. I tested the script itself, as described under Testing.

[github-actions]

Hey @mvanhorn — welcome to Open Brain Source! 👋

Thanks for submitting your first PR. The automated review will run shortly and check things like metadata, folder structure, and README completeness. If anything needs fixing, the review comment will tell you exactly what.

Once the automated checks pass, a human admin will review for quality and clarity. Expect a response within a few days.

If you have questions, check out CONTRIBUTING.md or open an issue.