# danielletto2020/vibe-rules architecture

> Architecture diagram of the GitHub repository danielletto2020/vibe-rules, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielletto2020/vibe-rules
- Repository: https://github.com/danielletto2020/vibe-rules

## Overview

#### Purpose and delivery model
`vibe-rules` is a Claude Code marketplace repository delivering composable engineering-standard plugins. It combines path-scoped written rules with executable hooks (“locks”) that block or escalate risky actions. Marketplace discovery begins at `.claude-plugin/marketplace.json`; each installable unit is independently declared, for example `plugins/std-core/.claude-plugin/plugin.json`.

#### Primary entry points
Users install `std-core`, then invoke Claude commands for project lifecycle: setup, update, diagnostics, and project-local rules. Command definitions are `plugins/std-core/commands/setup.md`, `plugins/std-core/commands/update.md`, and `plugins/std-core/commands/doctor.md`. The setup implementation is shell-based (`plugins/std-core/scripts/std-setup.sh`) and detects a target repository’s technology, configures plugins/settings, links rules, and preserves explicit profile/manual choices on repeat runs.

#### Module architecture and rule loading
The repository is a catalog of technology and process modules: core enforcement, quality gates, policy, language/framework rules, messaging, data stores, and operations. Modules keep manifests beside path-triggered rule documents, e.g. `plugins/std-js-typescript/.claude-plugin/plugin.json` and `plugins/std-js-typescript/rules/20-boundaries.md`; `plugins/std-sql-postgres/rules/10-migrations.md` is another domain example. Rules are linked into the consumer project because Claude plugins do not natively distribute `.claude/rules`; `plugins/std-core/scripts/std-link.sh` resolves plugin locations dynamically after updates.

#### Core enforcement boundary
`std-core` supplies hooks and shell guards that execute independently of model compliance. Hook registration is at `plugins/std-core/hooks/hooks.json`; major enforcement scripts include `plugins/std-core/scripts/guard-bash.sh`, `plugins/std-core/scripts/guard-secrets.sh`, and `plugins/std-core/scripts/guard-infra.sh`. These form a boundary around tool use: destructive shell operations, secret exposure, protected infrastructure/configuration edits, dependency changes, and test changes are denied or require escalation. They are safeguards rather than a sandbox; real isolation is delegated to a development container template at `templates/devcontainer/compose.yml`.

#### Contextual standardization flow
Rules load according to timing and file paths rather than as one global prompt. After edits, `plugins/std-core/scripts/rules-recheck.sh` identifies applicable modules and prompts review of the changed file within edit scope. For new files, `plugins/std-core/scripts/code-siblings.sh` finds comparable project files to establish local conventions. Session-level validation is handled by `plugins/std-core/scripts/session-check.sh`; this detects broken links and missing prerequisites such as `jq` rather than silently disabling protection.

#### Quality-gate pipeline
`std-gauntlet` is an optional, independently installable quality system: specification → independently derived tests → mutation testing → metrics/diff coverage → human review items. Its execution orchestrator is `plugins/std-gauntlet/scripts/gauntlet.sh`, invoked through `plugins/std-gauntlet/commands/run.md`. It maintains non-regressing quality/debt thresholds through `plugins/std-gauntlet/scripts/ratchet.sh`; `plugins/std-gauntlet/scripts/guard-commit.sh` prevents commits after source changes invalidate the last successful gate run. Profiles and lifecycle choices originate in `plugins/std-core/profiles/profiles.json`.

#### Organization policy and repository validation
`std-policy` optionally evaluates a private organization-supplied policy without publishing its contents; enforcement is `plugins/std-policy/scripts/guard-policy.sh`, and the public schema example is `plugins/std-policy/configs/policy.example.json`. Repository CI runs GitHub Actions from `.github/workflows/validate.yml`, backed by `tests/run.sh`. Tests validate module metadata, hook decisions, secret handling, profiles, links, gates, and publishing behavior. Releases are performed by `tools/publish.sh`, with version work in `tools/bump.sh`.

Main entry points: [`plugins/std-gauntlet/scripts/gauntlet.sh`](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/gauntlet.sh) (Quality-gate pipeline), [`plugins/std-core/scripts/std-setup.sh`](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/std-setup.sh) (Setup implementation), [`plugins/std-core/scripts/std-link.sh`](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/std-link.sh) (Rule linker), [`plugins/std-core/scripts/guard-bash.sh`](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/guard-bash.sh) (Tool-use guards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_marketplace["Marketplace"]
  node_marketplace_manifest["Marketplace catalog<br/>discovery manifest<br/>[marketplace.json]"]
end

subgraph group_core["std-core"]
  node_core_manifest["std-core plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_lifecycle_commands["Lifecycle commands<br/>Claude commands<br/>[setup.md]"]
  node_setup_script["Setup implementation<br/>shell workflow<br/>[std-setup.sh]"]
  node_rule_linker["Rule linker<br/>shell workflow<br/>[std-link.sh]"]
  node_hook_registry["Hook registration<br/>hook manifest<br/>[hooks.json]"]
  node_tool_guards["Tool-use guards<br/>enforcement scripts<br/>[guard-bash.sh]"]
  node_context_checks["Contextual checks<br/>session and edit hooks<br/>[rules-recheck.sh]"]
  node_devcontainer["Development container<br/>isolation template<br/>[compose.yml]"]
end

subgraph group_modules["Composable modules"]
  node_module_catalog["Technology modules<br/>plugin catalog<br/>[plugin.json]"]
  node_path_rules["Path-scoped rules<br/>rule documents<br/>[20-boundaries.md]"]
  node_postgres_rules["Postgres rules<br/>domain rules<br/>[10-migrations.md]"]
end

subgraph group_quality["Quality and policy"]
  node_profiles["Profiles and lifecycle choices<br/>profile configuration<br/>[profiles.json]"]
  node_gauntlet_command["Gauntlet command<br/>Claude command<br/>[run.md]"]
  node_gauntlet_pipeline["Quality-gate pipeline<br/>orchestrator<br/>[gauntlet.sh]"]
  node_quality_ratchet["Quality ratchet<br/>threshold guard<br/>[ratchet.sh]"]
  node_commit_guard["Commit freshness guard<br/>commit hook<br/>[guard-commit.sh]"]
  node_policy_guard["Organization policy guard<br/>policy enforcement<br/>[guard-policy.sh]"]
end

subgraph group_delivery["Validation and release"]
  node_ci_validation["Repository CI<br/>GitHub Actions workflow<br/>[validate.yml]"]
  node_test_runner["Validation suite<br/>shell test runner<br/>[run.sh]"]
  node_release_tools["Release tooling<br/>publish workflow<br/>[publish.sh]"]
end

node_marketplace_manifest -->|"discovers"| node_core_manifest
node_core_manifest -->|"provides"| node_lifecycle_commands
node_lifecycle_commands -->|"setup invokes"| node_setup_script
node_setup_script -->|"applies choices from"| node_profiles
node_setup_script -->|"configures"| node_rule_linker
node_rule_linker -->|"links into consumer repo"| node_path_rules
node_rule_linker -->|"links into consumer repo"| node_postgres_rules
node_hook_registry -->|"registers"| node_tool_guards
node_hook_registry -->|"registers"| node_context_checks
node_context_checks -.->|"rechecks after edits"| node_path_rules
node_tool_guards -.->|"complemented by isolation"| node_devcontainer
node_module_catalog -->|"contains"| node_path_rules
node_profiles -->|"configures"| node_gauntlet_pipeline
node_gauntlet_command -->|"invokes"| node_gauntlet_pipeline
node_gauntlet_pipeline -->|"enforces thresholds"| node_quality_ratchet
node_gauntlet_pipeline -->|"records successful gate"| node_commit_guard
node_policy_guard -.->|"adds optional policy enforcement"| node_tool_guards
node_ci_validation -->|"runs"| node_test_runner
node_release_tools -->|"publishes catalog artifacts"| node_marketplace_manifest

click node_marketplace_manifest "https://github.com/danielletto2020/vibe-rules/blob/main/.claude-plugin/marketplace.json"
click node_core_manifest "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/.claude-plugin/plugin.json"
click node_lifecycle_commands "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/commands/setup.md"
click node_setup_script "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/std-setup.sh"
click node_rule_linker "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/std-link.sh"
click node_hook_registry "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/hooks/hooks.json"
click node_tool_guards "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/guard-bash.sh"
click node_context_checks "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/rules-recheck.sh"
click node_devcontainer "https://github.com/danielletto2020/vibe-rules/blob/main/templates/devcontainer/compose.yml"
click node_module_catalog "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-js-typescript/.claude-plugin/plugin.json"
click node_path_rules "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-js-typescript/rules/20-boundaries.md"
click node_postgres_rules "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-sql-postgres/rules/10-migrations.md"
click node_profiles "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/profiles/profiles.json"
click node_gauntlet_command "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/commands/run.md"
click node_gauntlet_pipeline "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/gauntlet.sh"
click node_quality_ratchet "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/ratchet.sh"
click node_commit_guard "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/guard-commit.sh"
click node_policy_guard "https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-policy/scripts/guard-policy.sh"
click node_ci_validation "https://github.com/danielletto2020/vibe-rules/blob/main/.github/workflows/validate.yml"
click node_test_runner "https://github.com/danielletto2020/vibe-rules/blob/main/tests/run.sh"
click node_release_tools "https://github.com/danielletto2020/vibe-rules/blob/main/tools/publish.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_marketplace_manifest toneBlue
class node_core_manifest,node_lifecycle_commands,node_setup_script,node_rule_linker,node_hook_registry,node_tool_guards,node_context_checks,node_devcontainer toneAmber
class node_module_catalog,node_path_rules,node_postgres_rules toneMint
class node_profiles,node_gauntlet_command,node_gauntlet_pipeline,node_quality_ratchet,node_commit_guard,node_policy_guard toneRose
class node_ci_validation,node_test_runner,node_release_tools toneIndigo
```

## Components

### Marketplace

- [Marketplace catalog](https://github.com/danielletto2020/vibe-rules/blob/main/.claude-plugin/marketplace.json): discovery manifest · Lists installable plugins. · `.claude-plugin/marketplace.json`

### std-core

- [std-core plugin](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/.claude-plugin/plugin.json): plugin manifest · Primary installed lifecycle plugin. · `plugins/std-core/.claude-plugin/plugin.json`
- [Lifecycle commands](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/commands/setup.md): Claude commands · Setup, update, diagnostics, and local-rule workflows. · `plugins/std-core/commands/setup.md`
- [Setup implementation](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/std-setup.sh): shell workflow · Detects technology, configures choices, and preserves explicit selections. · `plugins/std-core/scripts/std-setup.sh`
- [Rule linker](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/std-link.sh): shell workflow · Links module rules into consumer projects after plugin updates. · `plugins/std-core/scripts/std-link.sh`
- [Hook registration](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/hooks/hooks.json): hook manifest · `plugins/std-core/hooks/hooks.json`
- [Tool-use guards](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/guard-bash.sh): enforcement scripts · Block or escalate risky shell, secret, and infrastructure actions. · `plugins/std-core/scripts/guard-bash.sh`
- [Contextual checks](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/scripts/rules-recheck.sh): session and edit hooks · Rechecks applicable rules, finds siblings, and verifies prerequisites. · `plugins/std-core/scripts/rules-recheck.sh`
- [Development container](https://github.com/danielletto2020/vibe-rules/blob/main/templates/devcontainer/compose.yml): isolation template · Provides real execution isolation beyond guards. · `templates/devcontainer/compose.yml`

### Composable modules

- [Technology modules](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-js-typescript/.claude-plugin/plugin.json): plugin catalog · Path-scoped language, framework, data, messaging, and operations standards. · `plugins/std-js-typescript/.claude-plugin/plugin.json`
- [Path-scoped rules](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-js-typescript/rules/20-boundaries.md): rule documents · Rules activate by changed paths and timing. · `plugins/std-js-typescript/rules/20-boundaries.md`
- [Postgres rules](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-sql-postgres/rules/10-migrations.md): domain rules · `plugins/std-sql-postgres/rules/10-migrations.md`

### Quality and policy

- [Profiles and lifecycle choices](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-core/profiles/profiles.json): profile configuration · Shared source for setup and quality-gate choices. · `plugins/std-core/profiles/profiles.json`
- [Gauntlet command](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/commands/run.md): Claude command · Starts the optional quality-gate workflow. · `plugins/std-gauntlet/commands/run.md`
- [Quality-gate pipeline](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/gauntlet.sh): orchestrator · Runs specification, independent tests, mutation, metrics, and review stages. · `plugins/std-gauntlet/scripts/gauntlet.sh`
- [Quality ratchet](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/ratchet.sh): threshold guard · Maintains non-regressing quality and debt thresholds. · `plugins/std-gauntlet/scripts/ratchet.sh`
- [Commit freshness guard](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-gauntlet/scripts/guard-commit.sh): commit hook · Blocks commits when source changes invalidate the last gate run. · `plugins/std-gauntlet/scripts/guard-commit.sh`
- [Organization policy guard](https://github.com/danielletto2020/vibe-rules/blob/main/plugins/std-policy/scripts/guard-policy.sh): policy enforcement · Evaluates private organization policy against a public schema. · `plugins/std-policy/scripts/guard-policy.sh`

### Validation and release

- [Repository CI](https://github.com/danielletto2020/vibe-rules/blob/main/.github/workflows/validate.yml): GitHub Actions workflow · Validates metadata, hooks, links, profiles, gates, and publishing. · `.github/workflows/validate.yml`
- [Validation suite](https://github.com/danielletto2020/vibe-rules/blob/main/tests/run.sh): shell test runner · `tests/run.sh`
- [Release tooling](https://github.com/danielletto2020/vibe-rules/blob/main/tools/publish.sh): publish workflow · Bumps versions and publishes marketplace artifacts. · `tools/publish.sh`

## Connections

- Marketplace catalog → std-core plugin: discovers
- std-core plugin → Lifecycle commands: provides
- Lifecycle commands → Setup implementation: setup invokes
- Setup implementation → Profiles and lifecycle choices: applies choices from
- Setup implementation → Rule linker: configures
- Rule linker → Path-scoped rules: links into consumer repo
- Rule linker → Postgres rules: links into consumer repo
- Hook registration → Tool-use guards: registers
- Hook registration → Contextual checks: registers
- Contextual checks → Path-scoped rules: rechecks after edits
- Tool-use guards → Development container: complemented by isolation
- Technology modules → Path-scoped rules: contains
- Profiles and lifecycle choices → Quality-gate pipeline: configures
- Gauntlet command → Quality-gate pipeline: invokes
- Quality-gate pipeline → Quality ratchet: enforces thresholds
- Quality-gate pipeline → Commit freshness guard: records successful gate
- Organization policy guard → Tool-use guards: adds optional policy enforcement
- Repository CI → Validation suite: runs
- Release tooling → Marketplace catalog: publishes catalog artifacts