Writing Standards

Standards are Python functions that evaluate a repository and return a compliance result.

Structure

Every standard must define an evaluate function that receives a project object:

def evaluate(project):
    files = project.list_files()

    if "README.md" in files:
        return {
            "passed": True,
            "score": 100,
            "message": "README found",
            "details": {},
        }

    return {
        "passed": False,
        "score": 0,
        "message": "No README found",
        "details": {},
    }

Return value

The evaluate function must return a dictionary with:

Key	Type	Description
passed	bool	Whether the standard passed
score	int	Score from 0 to 100
message	str	Human-readable result summary
details	dict	Additional data (shown in execution details)

Available API

The project object provides methods to query the repository. See the full ProjectContext API reference.

Criteria filters

Standards can be filtered to run only on specific events, branches, or languages:

• Events — push, pull_request, tag
• Branch filter — regex pattern matched against the event ref (e.g., ^refs/heads/main$)
• Languages — only run if the project uses specific languages

Leaving a filter empty means "match all."

Test cases

Each standard can have test cases that validate the logic with mock data. Test cases define:

• Input — mock data for ProjectContext methods (e.g., list_files, get_file_content)
• Expected — expected passed and score values

Run tests from the standard editor to verify your logic before deploying.