amelnagdy/guard-skills

1. This repository is a content-first skills package for coding agents, not an application runtime. Its architecture is centered on a small set of reusable “guard” skills that act as second-pass review gates over agent-generated work.

2. The root package is defined by README.md, LICENSE, skills.sh.json, and the skills/ directory. The README explains the public contract: install the package with the Skills CLI, then invoke a specific guard on a diff or task output before merge or release.

3. The main functional subsystems are the five skill bundles:

- clean-code-guard

- test-guard

- docs-guard

- wp-guard

- woo-guard

Each bundle targets a different failure domain: general code quality, test quality, documentation accuracy, WordPress-specific safety, and WooCommerce-specific correctness.

4. Each skill follows the same internal shape, which is the key architectural pattern in the repo:

- SKILL.md as the entry point and short operating contract

- agents/openai.yaml as agent metadata

- references/ as deeper, topic-specific guidance loaded only when needed

This creates a progressive disclosure model: the top-level skill stays lightweight, while detailed rules live in references.

5. The primary data flow is agent output → guard review → corrective feedback. The repo is designed for reactive use: an external coding agent produces code, tests, or docs; the chosen guard is then applied to the produced diff; the guard returns review findings before the changes are shipped.

6. The boundary between packages is semantic, not technical. clean-code-guard is cross-cutting and language-agnostic, while the other four are domain-specialized overlays. woo-guard explicitly builds on WordPress concerns and extends them into WooCommerce/H POS/order and money-handling rules.

7. The reference files are the repository’s knowledge base. They encode the review heuristics, checklists, and source citations that make each guard useful. For example, docs-guard includes verification-oriented references, while wp-guard and woo-guard contain security, i18n, checkout, and compatibility guidance.

8. There is no executable product code, no server, no build pipeline, and no runtime infrastructure in this repo. Its implementation surface is entirely static content: Markdown guidance plus lightweight YAML agent descriptors. That means the architecture diagram should emphasize package composition and review workflow, not application deployment.

9. The repo is intended to be consumed through the Skills CLI and supported agents such as Claude Code, Codex, Cursor, and OpenCode. The README shows installation modes at package, single-skill, agent-specific, and global scope, which indicates that distribution is externalized through the CLI rather than bundled tooling in this repo.

10. External service usage is minimal and limited to the package ecosystem. The README links to skills.sh for installation and package discovery, but the repository itself does not depend on network services, APIs, or credentials at runtime. That keeps the trust boundary simple: content is inspectable and self-contained.

11. The repo’s validation posture is also part of the architecture. The README describes maintainers using skillspector and local validation before publishing, reinforcing that correctness is enforced by repository inspection and metadata validation, not by executable tests inside the repo.

12. For diagramming purposes, the most accurate mental model is:

- a root package shell

- five independently installable guard modules

- each module containing a small entrypoint, agent metadata, and reference corpus

- an external agent/CLI consumer that loads the right skill and applies it to code, tests, or docs before release

13. In short, this repository is a modular rule-pack library for AI code review, optimized for small entrypoints, deferred detail loading, and clear domain separation. Its main architectural concern is not data processing but how quality checks are packaged, selected, and applied across different kinds of generated work.