Development

This page is for people who want to contribute to Argus itself — fixing review rules, improving docs, or running the project locally. If you only use Argus, you can skip this page.

Prerequisites

• Git — to clone the repository and create pull requests
• Python 3 — the test and tooling scripts are written in Python
• make — optional but recommended (it runs the common commands; see Commands)
• A GitHub account — to open issues and PRs

The big idea: Argus is just Markdown

Argus’s review behavior is defined entirely by AGENTS.md and SKILL.md — any AI agent that reads Markdown can apply them. The composite action injects those rules into an LLM prompt at review time; there’s no npm install or build step to run reviews. A stdlib-only Python toolchain under tools/ provides local validation, reports, and quality gates.

• AGENTS.md — the agent’s identity, hard rules, and review dimensions
• SKILL.md — the detailed review skill with trigger phrases and per-framework rules

Why this matters: contributing is mostly editing Markdown and validating that the structure stays correct. You don’t need to run a server or understand a framework.

Local setup

git clone https://github.com/cgartlab/argus.git   # download the repository
cd argus                                          # go into the folder

That’s it. You can now run make validate to see if the project is healthy.

What to contribute

Important: for new review rules, new severity assignments, or breaking changes, open an issue first. Direct PRs without prior discussion may be closed.

File conventions

• AGENTS.md — behavioral rules; never removed or weakened
• SKILL.md — skill definition with trigger phrases; description must have 3+ real-world trigger phrases
• .github/actions/argus-review/action.yml — the composite action wrapping OpenCode CLI + rule injection
• VERSION — a single line with the semantic version
• All Markdown files — no emoji decorations in headings or lists

Branch naming

fix/<desc>      # bug fixes — e.g. fix/flag-empty-alt
feat/<desc>     # new features — e.g. feat/svelte-5-rules
docs/<desc>     # documentation only — e.g. docs/typo-fixes
chore/<desc>    # refactor, format, tooling — e.g. chore/format-tools

Fixture regression tests

What is a fixture? In testing, a “fixture” is a fixed sample input paired with the exact output you expect. Argus’s fixtures are small, deliberately broken code files (like a CSS file with hardcoded colors) paired with a .expected file listing what the review should find.

Why this matters: fixtures are how Argus proves its rules work. Every time you change a rule, you update or add a fixture — then the test suite checks that the rule produces the expected findings. This catches regressions (“I fixed rule A and accidentally broke rule B”) before they reach users.

The tests/fixtures/ suite covers four categories:

Run them in static mode (no API key needed):

make test-fixtures    # run the whole suite

Or directly with flags:

python3 tools/run_fixture_tests.py --dry-run                     # check .expected files are valid
python3 tools/run_fixture_tests.py --category design-tokens      # only one category
python3 tools/run_fixture_tests.py --fixture bad-hardcoded-colors --verbose  # one fixture, verbose output
python3 tools/run_fixture_tests.py --json                        # machine-readable output

Rule: every rule change must be accompanied by a fixture update — CI verifies that input and .expected file counts match per category.

Adding a new review rule

1. Identify the review dimension (token, a11y, dark mode, etc.)
2. Assign a severity with a rationale (why P1 and not P2?)
3. Add the rule to SKILL.md under the correct dimension, with wrong/right code examples
4. Add it to the review checklist in AGENTS.md
5. Add a fixture pair (input + .expected) and run make test-fixtures
6. Verify the composite action still works (dynamic loading means no action change needed)
7. Update VERSION if the change is meaningful

Composite action maintenance

.github/actions/argus-review/action.yml is the integration point for automated reviews:

• Dynamic rule injection — AGENTS.md and SKILL.md are read at runtime and written to $GITHUB_ENV as PROMPT
• No hardcoded prompt — updating the rule files changes review behavior for all consumer repositories
• Update action.yml when adding steps, changing PROMPT construction, or updating the model/CLI installation
• Do NOT update action.yml for rule changes — edit AGENTS.md or SKILL.md only

Release process

make bump-patch   # update VERSION + CHANGELOG + site version markers, stage files
make test         # validate + fixture tests (full pre-release check)
make release      # release-gate → tag → push → triggers release workflow

Pushing a v* tag triggers the release workflow (.github/workflows/release.yml), which:

1. Validates versioning consistency (VERSION ↔ CHANGELOG.md)
2. Builds the full archive (dist/argus-v{VERSION}.tar.gz + .zip)
3. Builds the skill package (dist/argus-skill-v{VERSION}.zip)
4. Creates a GitHub Release with all artifacts
5. Publishes the skill package to SkillHub when SKILLHUB_API_KEY is configured

Pull request checklist

Before you open a PR, confirm:

• AGENTS.md and SKILL.md remain consistent with each other
• .github/actions/argus-review/action.yml is consistent with AGENTS.md and SKILL.md
• VERSION bumped if this is a meaningful change
• No emoji decorations in prose
• SKILL.md description has 3+ trigger phrases
• New review rules have severity assigned with rationale