swe_guidelines: Instructions file for Claude Code

Working in this repository

This repository holds one guideline (architecture.md), a lens catalog derived from it (lenses/), Claude Code skills that apply the lenses (skills/), and the checkers that keep the three consistent (scripts/, Makefile).

Layout

• architecture.md is the source of truth. Every rule in a lens or a skill restates a sentence in it; nothing adds a rule the guideline does not state.
• lenses/<group>.md holds one group of lenses in the format lenses/README.md defines. Ids are <PREFIX>-NN; every lens cites Section title or Section title, Subsection, by title and never by number.
• skills/arch-review-<group>/SKILL.md is generated from skills/_template/review.SKILL.md; edit the template and run make gen-skills. The other skills are hand-written. The six scaffold skills share skills/_shared/scaffold-conventions.md; the other hand-written skills do not. skills/_shared/ops-skills/ holds the nine project-local operational skills as flat templates, one file each, with acme for the product; arch-scaffold-new copies them into a new tree, and make leaks, make links, and make lint hold them. They are not skills of this plugin, but a new tree runs them as skills, so scripts/check_skills.py reads their frontmatter and nothing else. It holds the same flat key: value lines a skill's frontmatter has. The name equals the file name. The description is one double-quoted string of at most 1024 characters, outside the plugin's description budget. allowed-tools is comma-separated, with no bare Bash, and each Bash entry is the Bash(cmd:*) prefix form or an exact Bash(make <target>). skills/arch-new-aspect is the one skill that edits this repository itself: it incorporates a new aspect into the guideline and cascades it through the lenses, skills, and docs, and names the release level.
• agents/arch-reviewer.md is the subagent arch-review-full fans out to. Its procedure and report shape mirror the review template, and scripts/check_agents.py holds the two together: the four decision words, the report block, and the count of procedure steps must agree. The sentence "Never edit, stage, or commit" is repeated in every review skill on purpose.
• .claude-plugin/ holds the plugin and marketplace manifests. The repository root is the plugin. plugin.json carries the one release version. scripts/check_version.py holds every copy to it: the marketplace manifest, the changelog's latest release heading, the pinned tags in README.md, docs/adopting.md, and checkers/README.md, and the arch-check package's version in checkers/pyproject.toml and checkers/src/arch_check/__init__.py.
• benchmark/ holds the harness that measures a subject against a rubric (.github/workflows/benchmark.yml runs every scenario on demand, never on push): run.py with its inline dependencies, the harness/ modules, the scenarios, the result schema, and serve.py. Every harness module imports the standard library only at import time, so the tests at tests/test_benchmark_*.py run with nothing installed; the provider clients, pyyaml, jsonschema, and websockets are imported inside the functions that use them. A run writes into benchmark/runs/, which git ignores: the repository is the manual, a run is a measurement. make benchmark runs the smoke scenario and is not part of make check, because a run calls paid APIs.
• checkers/ holds arch-check, the static checker that decides the mechanical lenses. It is its own Python package (checkers/src/arch_check/, Python 3.11, standard library only). A rule's id is the id of the lens it decides, and a rule is one module under rules/; checkers/README.md says how to add one. checkers/src/arch_check/lenses.py carries every lens id and severity, and tests/test_arch_check_framework.py holds it equal to lenses/*.md. The tests are tests/test_arch_check_*.py, on trees built with tests/arch_check_fixtures.py; they skip on Python 3.10.
• scripts/_common.py holds what the scripts share, the heading anchor rule above all: the generator that writes anchors and the checker that resolves them use the same function. It also holds the one list of the repository's Markdown (markdown_files), which every script that scans Markdown reads, and the argument parser every script uses, and the one fence rule (fenced_lines) every script that skips code blocks uses.
• scripts/check_lenses.py also holds every identifier a lens quotes to the section the lens cites: a backticked name the guideline uses must appear in that section. CROSS_REFERENCES lists the few deliberate exceptions. tests/ holds one pytest module per script, each on a small fixture tree, with a pass and a fail path per rule; make test runs them.