Skip to main content

Architecture Standards

Architecture Standards turn the Documents workspace into a reviewed source of truth for engineering standards, Architecture Decision Records (ADRs), and Requests for Change (RFCs). The module keeps the human-facing discussion and the machine-readable enforcement contract together: teams write standards in Markdown, add structured standard_item blocks where automation is needed, and let Qarion generate reviewable artifacts for repositories and delivery pipelines.

Use this module when you need to:

  • Publish standards that should guide implementation and review.
  • Record ADRs that explain significant architectural decisions.
  • Run RFCs before changing a standard, architecture, or delivery practice.
  • Generate or roll out configuration artifacts such as linter, pre-commit, CI/CD, repository policy, or agent-facing instruction files.
  • Track standards history, exceptions, and Git-backed diffs in one place.

Workspace Model​

Each space has an Architecture Standards workspace with seeded sections for:

  • Standards - current engineering, data, platform, and architecture rules.
  • ADRs - accepted decisions and their context.
  • RFCs - open or closed proposals that collect discussion before a decision.

Standards pages use the same authoring lifecycle as regular Documents pages: draft, comment, submit, review, publish, and revise. Published pages are the current source of truth. Draft pages remain visible as in-progress work until they are submitted and published.

Revision history is retained for every page. When generated artifacts, validation results, or exceptions point back to a standard, they include source page and revision metadata so reviewers can understand exactly which standard produced the output.

Standard Items​

Standard items are the core automation unit. They are small YAML blocks embedded inside a human-readable standards page. The surrounding Markdown should explain the rationale, examples, and operating guidance. The standard_item block captures the structured contract that Qarion can search, retrieve, validate, and compile into artifacts.

kind: standard_item
id: python.ruff-tooling
title: Python projects use Ruff with Python 3.11 defaults
statement: Python code must use Ruff for formatting, linting, import sorting, and Python 3.11 compatibility.
severity: error
applies_to: ["python", "pyproject.toml"]
tags: ["python", "ruff", "formatting", "linting"]
rule:
  type: pyproject.ruff
  line_length: 88
  indent_width: 4
  target_version: py311
artifact_targets: ["ruff", "pyproject", "pre-commit"]
examples:
  compliant:
    - "tool.ruff.line-length = 88"

Standard Item Fields​

FieldPurpose
kindMust be standard_item.
idStable item identifier, for example python.ruff-tooling.
titleShort human-readable name.
statementThe rule or expectation to apply.
severityinfo, warning, or error. Legacy labels such as high normalize to the closest supported severity.
applies_toTechnologies, paths, file types, or components in scope.
tagsSearch and grouping labels.
ruleStructured rule details used by validation or artifact generation.
artifact_targetsTarget artifact families such as ruff, eslint, pre-commit, github-actions, or helm.
examplesOptional examples grouped by label.

Keep IDs stable after publication. If a standard is replaced, publish a new revision or a new item and explain the migration path in the page.

Constraint Validation​

Qarion derives repository validation checks from supported standard_item.rule types. Authors should keep validation intent inside the standard_item block so the item remains the single source for search, exceptions, artifacts, and drift checks.

V1 derivation supports:

Rule typeDerived checks
pyproject.ruffline_length, indent_width, and target_version checks in pyproject.toml.
eslint.required_pluginsOne contains check per required_entries value in frontend/eslint.config.js.
precommit.required_repositoriesOne contains check per required_repos value in .pre-commit-config.yaml.
snowpark.*Static Python checks for Snowpark session creation, credentials, local materialization, DataFrame pushdown, nearby tests, and scan scope.
snowflake.*Static Snowflake SQL/DDL checks for naming, DDL, security, tasks/streams, performance, and scan scope.
bigquery.*Static BigQuery SQL/DDL checks for naming, DDL, security, partitioning, performance, and scan scope.
agentic.instructionsStructural checks for canonical AGENTS.md guidance, accepted agents.md casing, and companion files such as CLAUDE.md, .cursorrules, and .cursor/rules/*.md(c).

Validation results include whether the check passed, the actual value, the expected value, whether the target file exists, and the source item and page revision that produced the derived constraint.

Agentic Instruction Standards​

Agentic standards define how repository-aware assistants should work inside a codebase. Use agentic.instructions items when a team wants reviewed guidance for AGENTS.md, Claude instructions, Cursor rules, or similar agent-facing files.

kind: standard_item
id: agentic.repository-operations
title: Agent workflows follow repository operating standards
statement: Agent-facing files must explain edits, testing, tools, approvals, and sensitive operations.
severity: warning
applies_to: ["AGENTS.md", "CLAUDE.md", ".cursor/rules"]
tags: ["agentic", "codex", "claude", "cursor", "operations"]
artifact_targets: ["agentic", "agents-md"]
rule:
  type: agentic.instructions
  required_sections:
    - Working with the repo
    - File edits and ownership
    - Testing and verification
    - Skills and tools
    - Sensitive operations
  skill_policies:
    - name: imagegen
      when: Use only for bitmap image generation or editing.
      guidance: Prefer repo-native assets when the requested output belongs in code.
  operation_policies:
    - name: mutating commands
      guidance: Explain edits before changing tracked files.
  generate_common_companions: true

Deterministic generation creates AGENTS.md and, when requested, companion files such as CLAUDE.md and .cursor/rules/qarion-agentic-standards.mdc. Repository validation treats AGENTS.md as canonical, accepts lowercase agents.md with a warning, and allows companion files to either include the required guidance directly or clearly defer to AGENTS.md.

RFCs and Polls​

RFCs are proposal documents. They do not approve a change by themselves. Once an RFC is accepted, the accepted change should be reflected in a published Standard or ADR.

For RFCs that require a vote, describe the voting rules directly in the RFC body before the poll. For example:

## Voting rules

- Voting window: 5 business days.
- Eligible voters: platform architecture team and service owners.
- Passing threshold: at least 60% approve and no unresolved security objection.
- Tie breaker: the architecture owner decides after recording rationale.

```poll
id: POLL_ID
```

Polls can be single-choice or multi-choice, can inherit page access, and can grant direct view, vote, or edit permissions to users and teams. Editors can close polls manually and inspect voter breakdowns when poll permissions allow it.

Diagrams​

Architecture Standards pages support both Mermaid and editable Draw.io diagrams. Use Mermaid for lightweight diagrams that should stay close to the Markdown source:

Use Draw.io diagrams when the diagram needs richer visual editing. Attach or insert the Draw.io diagram from the document editor, then keep the surrounding text clear enough that reviewers can understand the decision without opening the diagram editor.

Standards Artifacts​

Architecture Standards can generate configuration artifacts from published standards:

  • Deterministic artifacts come from standard_artifact blocks embedded in a standards page.
  • Agentic standards can deterministically generate AGENTS.md and companion files for common assistant tools.
  • Snowpark standards can deterministically generate scripts/validate_snowpark_standards.py; run it with python scripts/validate_snowpark_standards.py . from pre-commit or GitHub Actions when the page targets those artifact families.
  • AI previews draft artifacts from standard_item blocks and page context.
  • Deterministic validation checks run before users apply AI proposals.
  • Applied artifacts are stored as page attachments and can also be written to a managed standards artifact repository.
  • Rollout preview and apply actions compare managed artifacts against selected repositories and can create provider merge requests.

Review generated artifacts before applying them, especially when they affect linting, pre-commit, CI/CD, repository policy, deployment, or security files.

Git and Repository Rollout​

Qarion does not need to replace your operational Git provider. Existing GitHub, GitLab, Bitbucket, Azure DevOps, or other deployment repositories can remain the source for builds and releases.

Use the managed standards artifact repository as a governance and review surface:

  1. Generate or preview artifacts from a standards page.
  2. Review the proposed files and validation checks.
  3. Preview the managed repository diff.
  4. Roll out selected artifacts to target repositories.
  5. Review and merge provider merge requests when supported.

This keeps architecture governance linked to source standards while still working with the delivery process your engineering teams already use.

For existing spaces that predate new seeded standards pages, administrators can run python scripts/backfill_standards_templates.py --dry-run to review missing pages and then rerun without --dry-run to create only missing template slugs.

Exceptions​

When a repository, component, path, or asset cannot comply with a standards item, file an exception from the standards inventory. Exceptions capture:

  • Scope, such as paths, assets, or components.
  • Reason and business justification.
  • Optional expiry date.
  • Review decision and reviewer notes.
  • Source page and revision metadata.

Exception statuses are pending, approved, rejected, cancelled, revoked, and expired. Active exceptions remain linked to the standard item and are marked stale if the source standard revision changes.

  1. Draft an RFC when the team needs discussion before changing architecture or delivery practice.
  2. Add diagrams, examples, and poll voting rules when they help reviewers decide.
  3. Publish an ADR when the decision is accepted.
  4. Update or create the Standard with one or more standard_item blocks.
  5. Preview AI or deterministic artifacts from the standard.
  6. Review validation checks and save only the artifacts you want.
  7. Preview repository diffs and roll out through merge requests.
  8. File exceptions for scoped non-compliance and review them before expiry.