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

> Contribute to Archify by reporting bugs, showcasing diagrams, proposing features, or submitting pull requests. Follow our stability-first philosophy and help improve this open-source project.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-13

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) |
| **Skill Contract** | Defines the agent-skill contract. | [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml)
- **Showcase a real-world diagram** — submit via the [showcase form](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/showcase.yml)
- **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`](https://github.com/tt-a1i/archify/blob/main/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.

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md) lines 48-55:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/.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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), the CLI contracts in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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.