How to Contribute to Archify: A Complete Guide for Open-Source Contributors

You can contribute to Archify by filing bug reports, submitting feature proposals, adding real-world diagram showcases, or opening pull requests that follow the project's stability-first philosophy—every change must be reproducible, well-tested, and evidence-backed.

Archify is a Node-based agent skill that generates trustworthy, interactive system diagrams from code or descriptions. Learning how to contribute to Archify means understanding its architecture, respecting its strict testing requirements, and following its structured contribution workflow. This guide walks you through everything you need to know based on the official source code in tt-a1i/archify.

Understand Archify's Core Architecture

Before diving into contributions, familiarize yourself with the six key components that make up the project:

Component	Role	Key Path
Renderer Package	Generates SVG/HTML diagrams from typed JSON IR. Requires Node ≥ 18.	archify/
CLI / CLI Seam	Public entry points (archify render, archify validate, archify compare). All cross-renderer contracts live here.	archify/bin/archify.mjs
Schemas & Validators	Typed JSON schemas for the five diagram modes; deterministic validation receipts.	archify/schemas/README.md
Skill Contract	Defines the agent-skill contract.	archify/SKILL.md
Build Scripts	Rebuilds documentation artifacts (gallery, guide, start page, zip archive).	scripts/*.mjs, scripts/*.sh
Examples & Proof Lab	Real-world scenarios that double as integration tests.	examples/*.html, docs/gallery.html

All modifications must keep the CLI seam stable and pass the full test matrix (Node 18-24) before merging.

Choose Your Contribution Path

The CONTRIBUTING.md file outlines four distinct ways to contribute to Archify:

• Bug reports – Use the bug-report form for renderer, validator, or viewer issues.
• Showcase submissions – Submit real-world diagrams via the showcase form.
• Feature proposals – Open an issue first to clarify contracts and non-goals before any large refactor.
• Security vulnerabilities – Use GitHub's private security reporting workflow; never post exploit details publicly.

Critical policy: Never include secrets, personal data, or proprietary code in any issue, PR, or fixture. This warning appears explicitly at line 12 of CONTRIBUTING.md.

Set Up Your Local Development Environment

Contributing requires a clean Node.js environment. Run these commands from the repository root:

cd archify               # enter the renderer package

npm ci                   # install exact lock-file dependencies

npm test                 # run the full test suite (matches Node 18-24 CI)

As noted in CONTRIBUTING.md lines 24-25, run the narrowest relevant test first, then the full suite before opening a PR.

Fix Bugs or Add Features: The Stability-First Workflow

Archify's contribution process follows a strict evidence-based methodology:

1. Create a minimal reproducer – Build a tiny, redacted JSON file that triggers the failure (CONTRIBUTING.md lines 28-33).
2. Write a regression test – Assert the current failure, then implement your fix.
3. Run the complete test matrix – Verify no side effects have been introduced.

This approach ensures that every contribution to Archify is reproducible and well-tested.

Update Documentation and Static Artifacts

If your change touches schemas, CLI flags, or example diagrams, you must rebuild the static assets. Execute these commands as specified in CONTRIBUTING.md lines 48-55:

node scripts/build-gallery.mjs docs
node scripts/build-guide.mjs docs/guide.html
node scripts/build-start.mjs docs/start.html
node scripts/build-readme-showcase.mjs
node scripts/build-zip.sh /tmp/archify-contrib.zip

Skipping this step will cause documentation drift and likely block your PR.

Prepare and Submit Your Pull Request

Archify PRs must follow a focused, single-behavior philosophy:

• Keep changes tightly scoped to one behavior or related slice.
• Fill in the standard PR template at .github/PULL_REQUEST_TEMPLATE.md.
• Include exact commands run (npm test, rebuilt artifact commands).
• Attach before/after screenshots only when visual differences are the subject.
• Provide clear "passed/failed/skipped" visual-review status.

Run one final verification from the repo root (CONTRIBUTING.md lines 60-66):

cd archify
npm test

Essential Contributor Commands

# Complete workflow from clone to PR

git clone https://github.com/tt-a1i/archify.git
cd archify/archify
npm ci

# Run specific failing test

npm test -- -t "<test-name>"

# Full validation before push

npm test

# Documentation rebuild (when schemas or examples change)

node scripts/build-gallery.mjs docs
node scripts/build-zip.sh /tmp/archify.zip

# Commit and push (no auto-commit policy)

git add .
git commit -m "fix: correct JSON validation error for XYZ"
git push origin your-branch

These commands mirror the Quick start section in the README (lines 95-103).

Key Files Every Contributor Should Know

File	Purpose
CONTRIBUTING.md	Full contribution policy, bug-report templates, PR workflow
README.md	Project overview, quick-start install commands
archify/SKILL.md	Agent-skill contract, CLI contract, validation receipts
archify/schemas/README.md	JSON schema definitions for all diagram modes
archify/bin/archify.mjs	Main CLI entry point with render, validate, compare, deliver commands
scripts/build-*.mjs, scripts/build-zip.sh	Documentation and distributable generation
examples/	Integration tests and proof-lab artifacts

Summary

• Contributing to Archify requires understanding its six-component architecture and stability-first philosophy.
• All changes must pass the Node 18-24 test matrix and preserve CLI seam stability.
• Choose the appropriate contribution path: bug reports, showcases, features, or security disclosures.
• Always rebuild documentation artifacts when schemas or examples change.
• Follow the focused PR template and never include sensitive data in submissions.

Frequently Asked Questions

What is Archify's stability-first philosophy?

Every contribution must be reproducible, well-tested, and evidence-backed. This means creating minimal reproducers, writing regression tests, and passing the full Node 18-24 test matrix before merge. The philosophy is embedded throughout CONTRIBUTING.md and enforced in PR reviews.

Can I contribute without deep Node.js experience?

Yes, but you need Node ≥ 18 installed. The test suite (npm test) guides you through validation. Start with documentation improvements or diagram showcases before tackling renderer code in archify/bin/archify.mjs.

What happens if I forget to rebuild documentation artifacts?

Your PR will likely be blocked. Changes to schemas, CLI flags, or examples require running the build scripts in scripts/ to regenerate docs/gallery.html, docs/guide.html, and other static assets. The CI enforces this through the commands listed in CONTRIBUTING.md lines 48-55.

How do I report a security vulnerability privately?

Use GitHub's private security reporting workflow. Never post exploit details in public issues, comments, or PRs. Archify's security policy prioritizes responsible disclosure to protect users of the diagram generation tooling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}