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

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 and 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 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.

• 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).

• 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. Never include secrets, credentials, or private data in fixtures or logs, as emphasized in line 13 of 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:

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 at script line 27, run:

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). 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)

4. Label Impact Using the PR Template

The repository provides a ready-made template at .github/PULL_REQUEST_TEMPLATE.md. Fill in the Impact table according to the contribution guide (lines 31‑36 of 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:

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:

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. 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:

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

Save this as bug-repro.json and validate locally:

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).
• Final disposition: Wait for a maintainer to give the final “Ready” disposition, as defined in line 39 of 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 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 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 to confirm your workflow.

What automated checks run on Archify pull requests?

The npm test command (defined at line 27 of 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) 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, 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.

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