Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
110 lines (90 loc) · 4.06 KB

CONTRIBUTING.md

File metadata and controls

110 lines (90 loc) · 4.06 KB
Raw

Contributing to brainstack

Thanks for wanting to make the brain better. This project is small and opinionated on purpose — read the rules before opening a PR.

Ground rules

  1. Hermes-first. brainstack is built for Hermes Agent. Skills ship in Agent Skills format (which Hermes loads natively) but must carry the metadata.hermes frontmatter block - tags and related_skills - that makes them first-class Hermes skills.
  2. Generic by construction. brainstack ships zero personal content: no real names, companies, vaults, or notes. If your contribution embeds a specific person's context, it does not belong here.
  3. Plain files only. Markdown skills, Python scripts, shell. No build step, no SaaS dependency, no telemetry, no lock-in.
  4. English only. The audience is global.
  5. MIT. By contributing you agree your work is MIT-licensed.

Decisions and versions

  • Every structural change gets a changelog entry (CHANGELOG.md, Keep a Changelog format) - if it changes behavior, it is notable.
  • Every decision with alternatives considered gets an ADR in docs/adr/ (format: Status / Context / Decision / Consequences). Copy docs/adr/adr-001-*.md as the shape. A rule enforced by the stack deserves a record, not just a diff.
  • Version bumps follow docs/RELEASING.md (SemVer: MAJOR breaks the contract, MINOR adds compatibly, PATCH fixes). Bump VERSION, tag, and release together - the tag is the contract.
  • Breaking changes update ARCHITECTURE.md. The architecture doc is the contract; if a skill or template contradicts it, the doc wins and the code is the bug.

Structure

skills/<name>/SKILL.md     Agent Skills format, one skill per concern
bin/                       CLI scripts (Python 3.10+, stdlib-first)
vault-template/            Folder skeleton + note templates + schemas
docs/                      Design docs and decisions

Adding a skill

  1. Read ARCHITECTURE.md — new skills must fit the existing model (capture / memory / retrieval / consolidation), not fight it.
  2. Copy the structure of an existing skill. Frontmatter requirements:
---
name: my-skill
description: Use when <trigger>. <one-line behavior>.
version: 1.0.0
license: MIT
metadata:
  hermes:
    tags: [second-brain, <topic>]
    related_skills: [<in-repo skill names>]
---
  • name: lowercase, hyphens, ≤ 64 chars.
  • description: starts with "Use when", ≤ 1024 chars, ASCII-safe.
  • metadata.hermes: tags + related_skills (reference only in-repo skills).
  • Body: # Title → ## When to Use → actionable body → ## Common Pitfalls → ## Verification Checklist.
  1. Every skill needs a Verification Checklist (Definition of Done) — unverifiable skills rot.
  2. Wire it into setup (the skills manifest) and, if relevant, the README table.

Adding a script

  • Python 3.10+, stdlib-first. If you need a dependency, prefer a documented venv install inside the script's docstring, not a global requirement.
  • Every script must be idempotent where possible and print --dry-run support for anything destructive.
  • Config comes from environment variables (see .env.example), never hardcoded paths.

Validation

# frontmatter check for every skill
python3 - <<'EOF'
import yaml, re, pathlib
for p in pathlib.Path("skills").glob("*/SKILL.md"):
    c = p.read_text()
    assert c.startswith("---"), p
    m = re.search(r"\n---\s*\n", c[3:])
    fm = yaml.safe_load(c[3:m.start()+3])
    assert fm.get("name") and fm.get("description"), p
    assert len(fm["description"]) <= 1024, p
    assert len(c) <= 100_000, p
print("all skills OK")
EOF

Pull requests

  • One concern per PR. Small PRs merge fast; big ones get split.
  • Update docs when behavior changes (ARCHITECTURE.md is the contract).
  • Reference the issue or the design decision that motivates the change.

Code of conduct

Be constructive. This is a free, MIT project built by volunteers — treat maintainers and contributors the way you'd want to be treated.