Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
54 lines (36 loc) · 2.6 KB

CONTRIBUTING.md

File metadata and controls

54 lines (36 loc) · 2.6 KB
Raw

Contributing to agentify

Thank you for considering a contribution. Agentify has three distinct contribution surfaces, and each has its own bar.

1. Knowledge base contributions (agentify/knowledge/)

The knowledge base is the core asset of this project. It grounds every generated design in authoritative sources.

To propose a new source or update an existing document:

  • Open an issue using the "Knowledge source proposal" template first.
  • Acceptable sources: vendor engineering guides from model providers, peer-reviewed papers or widely cited arXiv surveys, standards bodies (OWASP, NIST, Linux Foundation, OpenTelemetry, W3C), cloud provider well-architected frameworks, and university course material.
  • Not acceptable as primary sources: personal blog posts (unless from a recognized practitioner and corroborated), marketing content, or uncited claims.
  • Every knowledge document follows the same structure: Principles, When to apply, Citations.
  • Every claim needs a citation. Update knowledge/SOURCES.md with the source, its URL, and the retrieval date.

2. Engine contributions (agentify/renderers/, agentify/schemas/)

The diagram engine is vendored from Archify (MIT). Keep these rules:

  • Preserve existing license attribution.
  • Renderers are deterministic: identical JSON in, identical HTML out. Golden tests enforce this.
  • Schema changes require regenerating validators: npm run generate:validators.
  • New node types need: a schema entry, renderer support, a test, and an example.
  • Run the full suite before opening a PR: cd agentify && npm test.

3. Example contributions (examples/)

Example design documents are the project gallery. A new example must:

  • Be generated by the skill itself (not hand-written), then reviewed.
  • Pass the enterprise bar: every component justified, NFRs stated, security and observability and cost sections present, citations included.
  • Render cleanly: node agentify/bin/agentify.mjs check <file>.html.

Style rules (enforced by CI)

  • No em dashes anywhere in the repository: code, docs, examples, comments, strings. Use commas, colons, parentheses, or separate sentences.
  • Markdown documents use sentence case headings.
  • Keep generated HTML self-contained: no external network requests, no CDN references.

Development workflow

git clone https://github.com/<you>/agentify
cd agentify/agentify
npm install
npm test

PRs should be focused (one concern per PR), include tests where behavior changes, and describe what was verified manually.

Code of conduct

This project follows the Contributor Covenant. Be excellent to each other.