# How to Contribute to Archify: A Complete Guide to the Agent-First Workflow

> Learn how to contribute to Archify with our complete guide. Follow the agent-first workflow for reviewable changes, asset generation, and pull requests. Get started today.

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

---

**To contribute to Archify, select the appropriate contribution path, prepare a reviewable change with local validation, generate required assets, and submit a pull request that follows the repository's impact classification and review contracts.**

Contributing to the **tt-a1i/archify** repository follows a structured, agent-first workflow defined in [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md) and [`REVIEWING.md`](https://github.com/tt-a1i/archify/blob/main/REVIEWING.md). Whether you are reporting a renderer defect, submitting a showcase diagram, or modifying schema contracts, understanding how to contribute to Archify ensures your changes meet the repository's compatibility and review standards. This guide provides the exact file paths, validation commands, and submission requirements needed to move from local development to merged contribution.

## Choose Your Contribution Path

 Archify organizes contributions into five distinct categories. Selecting the correct path determines whether you need to open an issue first or can proceed directly to a pull request.

- **Renderer, validator, or Viewer defect.** For bugs in the rendering pipeline or UI components, use the **bug-report form** located at [`.github/ISSUE_TEMPLATE/bug-report.yml`](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml) before submitting code changes.
 
- **Reproducible real-world diagram.** To propose a new showcase diagram that demonstrates Archify capabilities, use the **showcase form** at [`.github/ISSUE_TEMPLATE/showcase.yml`](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/showcase.yml).

- **Schema, defaults, or acceptance rules.** For changes affecting broad product behavior or contract modifications, open a standard issue first to agree on scope, then link it in your PR description (see lines 21‑25 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md)).

- **Small documentation or test fixes.** For minor documentation updates, typo corrections, or small test adjustments, submit a direct PR with a minimal reproduction. No preceding issue is required for these low-risk changes.

- **Security vulnerability.** Any security-related problems must follow the process outlined in [`SECURITY.md`](https://github.com/tt-a1i/archify/blob/main/SECURITY.md). **Never** include secrets, credentials, or private data in fixtures or logs, as emphasized in line 13 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md).

## Prepare a Reviewable Change

A reviewable change in Archify is one that passes local validation, includes generated assets, and provides clear documentation of impact. Follow these steps to ensure your contribution meets the repository's technical bar.

### 1. Synchronize with Main

Start from the latest `main` branch to avoid merge conflicts:

```bash
git checkout main && git pull

```

### 2. Run Local Validation

For most code changes, the repository defines a single test command that validates viewers, brand marks, validators, and release identity. As specified in [`package.json`](https://github.com/tt-a1i/archify/blob/main/package.json) at script line 27, run:

```bash
cd archify
npm ci
npm test

```

This executes the full suite that CI will enforce, including checks for viewer integrity and brand mark consistency.

### 3. Document the Change Clearly

Your PR description must explain the current-main trigger, the intended outcome, and the change’s value (see lines 21‑25 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md)). Additionally, list:

- Changed behavior and affected callers that remain stable
- Any compatibility impact or breaking changes
- The specific checks you ran and links to CI results (lines 27‑30 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md))

### 4. Label Impact Using the PR Template

The repository provides a ready-made template at [`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/tt-a1i/archify/blob/main/.github/PULL_REQUEST_TEMPLATE.md). Fill in the **Impact** table according to the contribution guide (lines 31‑36 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md)), classifying whether the change affects the Viewer, validators, schema, or release identity.

### 5. Regenerate Required Assets

If you modified Viewer source files, you must regenerate compiled assets before submission:

```bash
npm run generate:viewer   # see package.json script line 15

npm run check:viewer      # verify freshness

```

If you changed brand-mark assets or validators, run the respective generation scripts:

```bash
node scripts/generate-brand-marks.mjs
node scripts/generate-validators.mjs

```

### 6. Submit the Pull Request

Push your branch and open the PR against `main`. The **CodeRabbit** bot will automatically add review comments based on the criteria in lines 22‑30 of [`REVIEWING.md`](https://github.com/tt-a1i/archify/blob/main/REVIEWING.md). Respond to bot requests by re-running the relevant checks and updating your PR description with new evidence links.

## Submit and Navigate Review

After opening your PR, the repository's branch protection rules enforce that **all required CI checks must pass** before merge. Ensure your PR description includes:

- Evidence links to the CI run
- Screenshots (if the change is visual)
- Reproducible JSON inputs for diagram-related fixes

Example minimal reproduction for a bug report:

```json
{
  "meta": { "visual_preset": "signal-flow" },
  "nodes": [{ "id": "browser", "type": "client" }],
  "edges": [{ "source": "browser", "target": "api" }]
}

```

Save this as [`bug-repro.json`](https://github.com/tt-a1i/archify/blob/main/bug-repro.json) and validate locally:

```bash
node archify/bin/archify.mjs validate bug-repro.json --json

```

## Post-Submission Verification

Before your contribution can merge, verify the following:

- **CI status:** All required checks passed (branch protection enforces this).
- **Breaking changes:** Confirm you did not introduce breaking schema changes unless a migration path is documented (see lines 44‑48 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md)).
- **Final disposition:** Wait for a maintainer to give the final **“Ready”** disposition, as defined in line 39 of [`REVIEWING.md`](https://github.com/tt-a1i/archify/blob/main/REVIEWING.md).

## Summary

- **Select the correct path:** Use issue templates for bugs and showcases, open issues for schema changes, and direct PRs for small docs fixes.
- **Validate locally:** Run `npm test` from the `archify` directory to ensure viewers, validators, and brand marks pass before pushing.
- **Generate assets:** Execute `npm run generate:viewer` (and related scripts) whenever you touch Viewer or validator source files.
- **Document impact:** Fill out the PR template’s Impact table and cite the checks you ran, linking to CI results.
- **Respect security:** Never commit secrets or credentials, and follow [`SECURITY.md`](https://github.com/tt-a1i/archify/blob/main/SECURITY.md) for vulnerability reports.
- **Await bot and maintainer review:** Respond to CodeRabbit comments and wait for the maintainer “Ready” signal.

## Frequently Asked Questions

### What is the fastest way to report a bug in Archify?

Use the **bug-report form** at [`.github/ISSUE_TEMPLATE/bug-report.yml`](https://github.com/tt-a1i/archify/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml) for renderer or Viewer defects. Include a minimal reproducible JSON fixture and the validation output from `node archify/bin/archify.mjs validate`.

### Do I need to open an issue before submitting a pull request?

It depends on the change category. Small documentation or test fixes can go directly to PR. Schema changes, new acceptance rules, or product behavior modifications require an agreed-upon issue first. Refer to the contribution path table in [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md) to confirm your workflow.

### What automated checks run on Archify pull requests?

The `npm test` command (defined at line 27 of [`package.json`](https://github.com/tt-a1i/archify/blob/main/package.json)) validates viewers, brand marks, validators, and release identity. Additionally, the **CodeRabbit** bot scans code changes during review (lines 22‑30 of [`REVIEWING.md`](https://github.com/tt-a1i/archify/blob/main/REVIEWING.md)) and posts automated comments that contributors must address.

### How do I handle breaking schema changes when contributing to Archify?

Breaking schema changes are permitted only when a migration path is fully documented. Per lines 44‑48 of [`CONTRIBUTING.md`](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md), you must list compatibility impact in your PR description and ensure the change does not break existing diagram contracts without notice. If unsure, open an issue first to discuss the migration strategy with maintainers.