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

> Contribute to the Archify open-source project by filing bug reports, proposing features, or submitting pull requests. Follow our stability-first philosophy for impactful contributions. Learn how today!

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

---

**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`](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) |

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`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md) file outlines four distinct ways to contribute to Archify:

- **Bug reports** – Use the [bug-report form](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml) for renderer, validator, or viewer issues.
- **Showcase submissions** – Submit real-world diagrams via the [showcase form](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/showcase.yml).
- **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`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md).

## Set Up Your Local Development Environment

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

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

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

```bash
cd archify
npm test

```

## Essential Contributor Commands

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md) | Full contribution policy, bug-report templates, PR workflow |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Project overview, quick-start install commands |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Agent-skill contract, CLI contract, validation receipts |
| [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery.html), [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html), and other static assets. The CI enforces this through the commands listed in [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/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.