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

You can contribute to Archify by filing bug reports, submitting diagram showcases, proposing features, or opening pull requests that pass the full Node 18-24 test matrix while respecting the project's stability-first philosophy.

Archify is a Node-based agent skill that generates trustworthy, interactive system diagrams from code or descriptions. Whether you're fixing a renderer bug, adding a new diagram mode, or showcasing real-world usage, this guide walks you through how to contribute to the Archify project with confidence and precision.

Understand the Core Architecture First

Before touching any code, familiarize yourself with the component layout. Every contribution to Archify must keep the CLI seam stable and pass the full test matrix.

Component	Role	Key Path
Renderer Package	Generates SVG/HTML diagrams from typed JSON IR. Runs on 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

The archify/bin/archify.mjs file serves as the primary CLI entry point. Any modification to commands or flags must preserve backward compatibility.

Choose Your Contribution Path

Archify provides structured templates for different contribution types. Pick the path that matches your goal:

• Bug / renderer, validator, or viewer issue — file a report using the bug-report form
• Showcase a real-world diagram — submit via the showcase form
• Feature or behavior change — open an issue first to clarify contracts and non-goals before any large refactor
• Security vulnerability — use GitHub's private security reporting workflow; do not post exploit details publicly

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

Set Up Your Local Development Environment

Contributing to Archify requires Node.js 18 or higher. The project uses lock-file exact dependencies to ensure reproducibility.

# Clone the repository

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

# Enter the renderer package directory

cd archify

# Install exact dependencies from lock file

npm ci

# Run the full test suite (must pass on Node 18-24)

npm test

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

Fix a Bug or Add a Feature

The Archify project follows a rigorous stability-first workflow for code changes:

Step 1: Create a Minimal Reproducer

Build a tiny, redacted JSON fixture that still triggers the failure. As documented in CONTRIBUTING.md lines 28-33, this reproducer becomes your regression test foundation.

Step 2: Write the Regression Test

Assert the current failure explicitly, then implement your fix. This test-first approach ensures the bug stays fixed.

Step 3: Validate Against the Full Matrix

Run the complete test suite to catch side effects. A fix that breaks another diagram mode is not acceptable.

# Run a single failing test by name

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

# After fixing, run everything

npm test

Rebuild Documentation and Static Artifacts

If your change touches schemas, CLI flags, or example diagrams, you must regenerate the static assets. The build scripts live in scripts/ and are referenced in CONTRIBUTING.md lines 48-55:

# Rebuild the visual gallery

node scripts/build-gallery.mjs docs

# Regenerate the guide HTML

node scripts/build-guide.mjs docs/guide.html

# Update the start page

node scripts/build-start.mjs docs/start.html

# Refresh README showcase section

node scripts/build-readme-showcase.mjs

# Create the distributable ZIP archive

node scripts/build-zip.sh /tmp/archify-contrib.zip

Skipping these steps will cause CI failures on your pull request.

Submit a Pull Request That Gets Merged

Per CONTRIBUTING.md lines 60-66, your PR must meet strict quality standards:

• Scope: Keep the PR focused on one behavior or a tightly related slice
• Template: Fill in .github/PULL_REQUEST_TEMPLATE.md completely
• Evidence: Include exact commands run (npm test, rebuild commands)
• Visuals: Provide before/after screenshots only when visual differences are the subject
• Status: Mark "passed/failed/skipped" for visual-review fields

Final validation command:

cd archify
npm test

License and Contribution Rights

By submitting a pull request to contribute to the Archify project, you agree that your contribution is licensed under the project's MIT License (CONTRIBUTING.md line 71). Only submit work you own or have explicit rights to contribute.

Summary

• Archify is a Node-based diagram generator with strict stability requirements
• The core components are the Renderer Package, CLI seam, Schemas, and Skill Contract
• Use the appropriate GitHub issue template for bugs, showcases, or features
• Development requires Node 18+, npm ci for deps, and npm test for validation
• Every code change needs a minimal reproducer and regression test
• Documentation changes require running build scripts in scripts/
• PRs must be focused, templated, and fully tested across Node 18-24

Frequently Asked Questions

What Node.js versions does Archify support?

Archify officially supports Node 18 through Node 24. The CI test matrix validates every PR against this range. Running npm test locally should pass on any of these versions before you submit.

Can I contribute a new diagram type or visualization mode?

Yes, but open an issue first. New diagram modes affect the JSON schemas in archify/schemas/README.md, the CLI contracts in archify/SKILL.md, and potentially the renderer engine. The maintainers need to clarify contracts and non-goals before you invest significant effort.

What should I do if I find a security vulnerability in Archify?

Use GitHub's private security reporting workflow. Do not post exploit details in public issues, discussions, or pull requests. The security policy prioritizes responsible disclosure to protect users of the agent skill.

Why does my PR fail CI even though npm test passes locally?

Likely causes: Node version mismatch, missing documentation rebuild, or uncommitted artifact changes. Ensure you're on Node 18-24, run all relevant scripts/build-*.mjs commands, and check that no generated files in docs/ are out of sync with your source changes.

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