architecture-guardian

Architecture Guardian

A language-agnostic Agent Skill for evidence-based software architecture audits. It discovers the stack and domain, traces use cases, and evaluates boundaries, invariants, dependencies, and design choices without requiring patterns by default.

Español · Alpha · MIT License · Report feedback

This project is experimental. Audit quality depends on the agent, model, repository context, and tools available. Verify findings against source code and project requirements.

What it does

• Audits Hexagonal and Clean Architecture, DDD, CQRS, event-driven systems, SOLID, and relevant patterns across languages and technologies.
• Discovers domain concepts from requirements, contracts, tests, and code, then traces representative use cases through their effects and failure paths.
• Separates confirmed defects, potential risks, assumptions, unknowns, and optional improvements.
• Recommends existing project checks without installing dependencies or running commands automatically.
• Includes no executable scripts. Its manual behavioral fixtures live in references/skill-evaluation.md.

Quick start

Copy the entire architecture-guardian directory, including SKILL.md, references/, and templates/, into a skills directory recognized by your agent. See the platform-specific locations below. Then ask the agent to audit a repository in Audit mode, or explicitly request Review or Refactor mode.

Example prompt:

Use Architecture Guardian in Audit mode. Discover the stack and domain,
trace the main use cases, and report evidence-backed architectural findings.
Do not execute commands or modify files.

Platform support

Agent Skills portability is about the format and instructions. It does not mean every model or product automatically discovers the skill, reads its references, or supports the same tools. Installation paths and feature availability can change.

The platform paths above are based on vendor documentation, not end-to-end tests of this skill. Other products from Anthropic, Google, OpenAI, or DeepSeek are not covered merely because they share a model provider.

Official documentation: Agent Skills specification · OpenCode · Claude Code · Gemini CLI · ChatGPT Skills · OpenAI Skills API · Codex · DeepSeek Deep Code

How to evaluate

1. Provide a representative repository or a fixture from references/skill-evaluation.md.
2. Record the skill version, platform, model, project stack, scope, and relevant output.
3. Check evidence, finding/status/count consistency, severity rationale, and whether uninspected areas remain explicitly unknown.
4. Do not treat a recommendation as verified behavior. Confirm claims against source, tests, documentation, or authorized checks.
5. When a defect appears, add a regression fixture before changing the skill and rerun affected scenarios.

Architecture guidance is portable; commands, conventions, and static-analysis rules must match the detected stack. When evidence or ecosystem knowledge is missing, the agent should say so instead of inventing rules.

Validation status

• Structure: quick_validate.py passed with Python 3.11 and PyYAML 6.0.3 in the prior validation run.
• Manual fixtures: A–F passed a manual self-evaluation against their expected outcomes. This is not an independent multi-model/platform evaluation.
• Cursor field evaluation: two runs on one TypeScript/MongoDB application improved finding counts, statuses, and optional-improvement classification. The second report still ambiguously offered MongoDB bulkWrite as an alternative to an atomic multi-document replacement. Fixture G therefore partially passes; see the evaluation criteria.
• Additional project report: a TypeScript/Express/Sequelize audit had consistent executive counts and useful domain/use-case traces. It exposed calibration issues around unstated normalization rules, overlapping findings, and severity for an unwired module. Regression fixture H now covers these cases; it has not yet been rerun in an agent harness. The pasted report did not identify its platform/model, so it is not counted as a platform-specific test.

Versioning

This repository distributes instructions and references rather than a runtime package. Releases are identified by Git tags and GitHub Releases; the skill itself has no executable version field.

Use Semantic Versioning with prerelease identifiers:

• v0.1.0-alpha.1: first public alpha.
• v0.1.0-alpha.2, v0.1.0-alpha.3: subsequent alpha feedback and fixes.
• v0.1.0-beta.1: feature set is stable enough for broader validation.
• v1.0.0: intended workflow and compatibility claims have acceptance criteria and have been validated sufficiently for a stable release.

For each release, update CHANGELOG.md, create an annotated tag on the reviewed commit, and publish matching notes as a GitHub prerelease until v1.0.0.

Contributing

Use the contribution guide. Please do not include proprietary source code, credentials, customer data, or other sensitive project information in public audit feedback.