Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (88 loc) · 5.97 KB

CONTRIBUTING.md

File metadata and controls

128 lines (88 loc) · 5.97 KB
Raw

Contributing to Spotlight

Spotlight is runtime-agnostic by design. Every subsystem is structured as a drop-in: add one directory or one table entry, and Spotlight picks it up. No central registration, no build step.

This doc is the entry point. It points at the per-subsystem contracts.

Before you start

  • Read docs/structure.md to understand the layout.
  • Read AGENTS.md — the runtime contract every skill and agent speaks.
  • Run bash tests/smoke.sh — if it passes on your machine, your environment is ready.
  • Check docs/plans/ for any active work-in-progress.

Ways to contribute

Add a new runtime (agent harness)

A runtime is an agent CLI or SDK (pi, Claude Code, Gemini, Codex, OpenCode, etc.) that can read AGENTS.md and dispatch the 13 verbs.

  1. Add the runtime as a choice in the local configurator: a radio card in install/configure.html (cloud or local section) plus the matching handling in install/setup_server.py (normalize(), validate_choices, build_setup_config). The configurator carries choices only — no version strings.
  2. Add the install/launch logic to install-spotlight.sh. Version pins live ONLY in install-spotlight.sh and VALIDATED_DEPENDENCIES.md — never duplicate them in the configurator.
  3. Write docs/runtimes.md addition — brief wiring notes, verb mapping specifics, sensitive-mode handling.
  4. Run bash tests/smoke.sh and bash tests/eval.sh to confirm consistency, plus the installer/configurator checks below.

Add a new external tool integration

An integration is a specific external OSINT tool (dev-browser, Junkipedia, OSINT Navigator, etc.).

  1. mkdir integrations/<id>/
  2. Write integrations/<id>/manifest.json per the contract in integrations/README.md.
  3. Write integrations/<id>/integration.md — when to use, verb calls, output format, sensitive-mode behavior.
  4. Add a row to the routing table in skills/integrations/SKILL.md.
  5. Optional: add a checkbox to the Plug-ins section of the local configurator (install/configure.html, wired through install/setup_server.py) so journalists see it during install.
  6. Run python3 integrations/preflight.py --text — your new integration should appear.

Passive feed sources

Passive feed-source code moved to Mycroft. Do not add new monitoring feeds to Spotlight.

If you need a new passive source:

  1. Add it to Mycroft's monitoring service.
  2. Update Spotlight's monitoring references only if the orchestrator needs to know the source exists.
  3. Keep Spotlight focused on recommendation, approval, and cross-tool linkage.

Add a new skill

A skill is a methodology playbook, not a tool — things like "how to investigate a person" or "how to archive evidence."

  1. mkdir skills/<id>/
  2. Write skills/<id>/SKILL.md with YAML frontmatter: 
    ---
name: <id>
description: <one-liner>
version: "1.0"
invocable_by: [investigator | fact-checker | orchestrator | user]
requires: [<other-skill-id>]  # optional
---
  3. Add a row to the skill registry in AGENTS.md.
  4. Reference the skill from skills/spotlight/SKILL.md or another orchestrator as appropriate.
  5. Update docs/structure.md skill count.
  6. Run bash tests/smoke.sh — the skill-count check should now pass at the new total.

Testing

bash tests/smoke.sh   # structural + cleanliness checks (fast, <2s)
bash tests/eval.sh    # contract compliance + sample data validation

CI runs both on every push + PR. Don't merge unless both are green.

When touching install-spotlight.sh, also run:

bash tests/install-spotlight-check.sh   # bash -n + fragment assertions + landing-page checks
bash tests/install-spotlight-smoke.sh   # --headless --dry-run combo matrix

When touching the configurator (install/setup_server.py or install/configure.html):

python3 tests/configurator-server-check.py

(See .github/workflows/ci.yml for the canonical test commands.)

Coding standards

  • No new Claude-specific syntax in skills or agents. Use the 13 abstract verbs from AGENTS.md. The smoke test greps for WebFetch, WebSearch, Agent(, Skill(, allowedTools, maxTurns, etc. and fails if any appear.
  • Every skill has YAML frontmatter with at least name, description, version, invocable_by.
  • Every integration manifest declares env_vars (empty array if none required) and requires_key.
  • Generated files (scripts, JSON) must be validated. tests/eval.sh runs jsonschema on sample case files; add fixtures for new schemas.
  • No hardcoded personal emails or paths in committed code. Use env vars ($UNPAYWALL_EMAIL, etc.) or configurable placeholders.

Commit messages

Short, imperative subject (50 chars) + blank line + body explaining the "why" (not the "what"). For breaking changes, lead the subject with !:.

Skip the Claude co-author trailer in PR commits — it's fine on main but noisy in PR review.

PR process

  1. Fork + branch from main.
  2. Keep PRs focused — one concern per PR. Splitting is better than bundling.
  3. Fill out .github/PULL_REQUEST_TEMPLATE.md (auto-prompted on PR creation).
  4. CI must pass (tests/smoke.sh + tests/eval.sh).
  5. For new runtimes / integrations / skills: include a brief docs/ addition + update the relevant registry.
  6. Reviewer merges via squash-and-merge to keep main history linear.

Security

If you find a security issue (credential leak pattern, API key exposure, arbitrary-code-execution in generated scripts, etc.), email [email protected] before filing a public issue. We'll coordinate disclosure.

Do NOT open a public issue for anything that could enable an attacker.

Attribution

Non-trivial methodology contributions deserve attribution in the affected skill's frontmatter (attribution: field) and in LICENSE. We take journalism-methodology provenance seriously.

Questions

  • General: open a GitHub Discussion
  • Bugs: use the bug report issue template
  • Features: use the feature request template
  • Security: [email protected]