Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
104 lines (77 loc) · 3.33 KB

CONTRIBUTING.md

File metadata and controls

104 lines (77 loc) · 3.33 KB

Contributing to create-opc-wiki

Thanks for considering a contribution. This package is a scaffolder for personal LLM wikis on the Karpathy pattern. Keep contributions aligned with that pattern — simple, composable, no surprises — and the semver-stable surface in STABILITY.md.

Development setup

git clone https://github.com/MackDing/create-opc-wiki
cd create-opc-wiki
npm install
npm run build
npm run test:smoke   # 60+ assertions, no network required
npm run test:e2e     # real npm install + MCP boot + site build (needs network)

Node 20+ required (engines.node >= 20).

Adding a new AI agent rule target

Say you want to add support for a new agent, e.g. foo-agent which reads .foo/rules.md.

  1. src/agents.ts — add an entry to AGENT_TARGETS and extend AgentKey.
  2. templates/scripts/sync-agent-rules.sh — add a case branch that writes the file.
  3. docs/INSTALL-FOR-AGENTS.md — add a section with the paste-in one-liner.
  4. README.md — add a row to the "Install in any AI agent" table.
  5. agents.json — add foo to supported_agents.
  6. scripts/smoke-scaffold.mjs — add an assertion that the agent's file is written when requested.

Run npm run test:smoke and npm run test:e2e. Both must pass.

Adding a new source recipe

  1. templates/recipes/<source>.md — new recipe file. Follow the shape of existing recipes (arXiv, X, YouTube, RSS, podcast).
  2. templates/recipes/_index.md — add a row.
  3. templates/agent-rules/main.md.tpl — add an example /wiki-ingest line under "## Recipes".

Running the CLI locally without publishing

npm run build
node dist/cli.js /tmp/test --yes --agents=claude

Or symlink for repeated runs:

npm link
create-opc-wiki /tmp/test --yes
npm unlink -g create-opc-wiki

Semver scope

Before changing any of the following, check STABILITY.md — they are under semver and breaking changes need a major bump and a deprecation window:

  • CLI flag names, types, behavior
  • Generated file paths in the scaffolded vault
  • Frontmatter schema (required fields on wiki pages)
  • MCP tool names, parameter schemas, return shapes
  • --json output shape

Template prose, skill prose, recipe prose, visual design of the generated site, and internal dist/api.js are not under semver.

Tests

  • npm run test:smoke — fast (no network), runs in every CI job.
  • npm run test:e2e — slow (real npm install), runs in one CI job on Ubuntu. Skipped if OFFLINE=1.

New code should be covered by at least the smoke test. If you add a user-facing flag or a generated file path, add an assertion for it.

Submitting a PR

  1. Fork, branch off main.
  2. Keep the PR focused — one concern per PR.
  3. Include a line in CHANGELOG.md under ## [Unreleased] (create the section if missing).
  4. Fill out the PR template.
  5. CI must be green (3 OSes × 2 Node versions for smoke; Ubuntu for e2e).

Code style

  • Prettier-ish default. No config opinions beyond what the existing code uses.
  • TypeScript strict. No any unless genuinely unavoidable.
  • Small files. If a source file passes ~300 lines, split it.

Questions

Open a GitHub issue. For security concerns, see SECURITY.md.