@lvlup-sw/axiom 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "axiom",
+  "version": "0.2.0",
+  "description": "Backend code quality skills for Claude Code. Six skills that audit, critique, harden, and simplify your architecture — the backend half of impeccable.",
+  "author": "lvlup-sw",
+  "license": "MIT",
+  "homepage": "https://github.com/lvlup-sw/axiom",
+  "skills": [
+    "skills/audit",
+    "skills/critique",
+    "skills/harden",
+    "skills/distill",
+    "skills/verify",
+    "skills/scan"
+  ]
+}

package/CLAUDE.md

@@ -0,0 +1,26 @@
+# Axiom
+
+Backend code quality skills. The other half of impeccable — same composable pattern, pointed at architecture instead of UI.
+
+## Skills
+
+| Skill | Purpose | Dimensions |
+|-------|---------|-----------|
+| `axiom:audit` | Comprehensive backend audit (orchestrator) | All |
+| `axiom:critique` | Architecture review: SOLID, coupling, dependencies | Architecture, Topology |
+| `axiom:harden` | Error handling, resilience, observability | Observability, Resilience |
+| `axiom:distill` | Dead code, vestigial patterns, simplification | Hygiene, Topology |
+| `axiom:verify` | Test quality, mock fidelity, contract drift | Test Fidelity, Contracts |
+| `axiom:scan` | Deterministic pattern detection (grep/structural) | Pluggable (any) |
+
+## Quality Dimensions
+
+Seven canonical dimensions (DIM-1 through DIM-7) defined in `skills/backend-quality/references/dimensions.md`.
+
+## Usage
+
+Run individual skills for targeted assessment, or `axiom:audit` for comprehensive analysis. All skills accept a `scope` argument (file, directory, or codebase).
+
+## Integration
+
+This plugin is standalone — no workflow dependencies. Workflow tools can consume findings via the standard finding format documented in `skills/backend-quality/references/findings-format.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 levelup software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lvlup-sw/axiom",
+  "version": "0.2.0",
+  "description": "Backend code quality skills for Claude Code",
+  "type": "module",
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "files": [
+    ".claude-plugin",
+    "skills",
+    "CLAUDE.md"
+  ],
+  "keywords": [
+    "claude-code-plugin",
+    "backend-quality",
+    "code-review",
+    "architecture",
+    "design-patterns"
+  ],
+  "author": {
+    "name": "LevelUp Software",
+    "email": "oss@lvlup.software"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/lvlup-sw/axiom",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lvlup-sw/axiom.git"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0",
+    "typescript": "^5.7.0",
+    "yaml": "^2.7.0"
+  }
+}

package/skills/audit/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: audit
+description: "Run a comprehensive backend quality audit across all seven dimensions. Orchestrates scan, critique, harden, distill, and verify skills, deduplicates findings, and produces a unified report with verdict. Use when assessing overall codebase health. Triggers: 'audit backend', 'full quality check', 'run audit', or /axiom:audit. Do NOT use for targeted checks — use individual skills instead."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: assessment
+  dimensions:
+    - all
+---
+
+# Audit — Comprehensive Backend Quality Assessment
+
+## Overview
+
+The anchor skill that orchestrates all other axiom skills to produce a comprehensive backend quality report. Runs deterministic checks and qualitative assessments across all 7 dimensions, deduplicates findings, computes per-dimension metrics, and delivers a unified verdict.
+
+## Triggers
+
+**Use when:**
+- Assessing overall codebase or module health
+- Preparing for a release or major refactor
+- Onboarding to understand existing technical debt
+- User says "audit", "full quality check", "assess quality"
+
+**Do NOT use when:**
+- Targeting a specific concern (use `axiom:critique`, `axiom:harden`, `axiom:distill`, or `axiom:verify` directly)
+- Running only deterministic checks (use `axiom:scan`)
+- Performing workflow-specific review (workflow tools orchestrate axiom, not the reverse)
+
+## Process
+
+### Step 1: Scope Resolution
+
+Determine the assessment scope from the `scope` argument:
+- **File:** Assess a single file
+- **Directory:** Assess all files in a directory (recursive)
+- **Codebase:** Assess the entire project (default: current working directory)
+
+Exclude by default: `node_modules/`, `dist/`, `.git/`, binary files, generated files.
+
+### Step 2: Deterministic Scan
+
+Run `axiom:scan` with `dimensions: all` for the resolved scope. This produces the mechanical findings that ground the qualitative assessment.
+
+### Step 3: Qualitative Assessment
+
+Run each specialized skill in sequence, passing the scope:
+
+1. **`axiom:critique`** — Architecture (DIM-6) + Topology (DIM-1)
+2. **`axiom:harden`** — Observability (DIM-2) + Resilience (DIM-7)
+3. **`axiom:distill`** — Hygiene (DIM-5) + Topology (DIM-1)
+4. **`axiom:verify`** — Test Fidelity (DIM-4) + Contracts (DIM-3)
+
+Each skill produces findings in the standard format: `@skills/backend-quality/references/findings-format.md`
+
+### Step 4: Deduplicate and Aggregate
+
+Merge findings from all skills using these rules:
+- **Same evidence + same dimension:** Merge into single finding (keep most detailed explanation)
+- **Same evidence + different dimensions:** Keep both (finding genuinely spans two concerns)
+- **Same pattern + different files:** Keep as separate findings
+- **Deterministic + qualitative for same issue:** Merge, mark as `deterministic: true`
+
+### Step 5: Coverage Check
+
+Verify all 7 dimensions were assessed. If any dimension has zero findings and zero checks:
+- **Warning:** "DIM-N ({name}) was not assessed — no checks or findings produced"
+- This may indicate the scope doesn't contain code relevant to that dimension
+
+### Step 6: Compute Verdict
+
+Apply the verdict exactly as defined in `@skills/backend-quality/references/scoring-model.md` (single source of truth). Do not redefine thresholds here; compute and report the inputs required by the model (HIGH/MEDIUM/LOW counts).
+
+Compute per-dimension metrics:
+- Pass rate (deterministic checks only)
+- Finding count (all findings)
+- Severity distribution (HIGH / MEDIUM / LOW)
+
+### Step 7: Produce Report
+
+Output the structured report per the template in `@skills/backend-quality/references/scoring-model.md`:
+
+```markdown
+# Backend Quality Report
+
+**Scope:** [assessed scope]
+**Verdict:** [CLEAN | NEEDS_ATTENTION]
+**Date:** [current date]
+
+## Summary
+[Per-dimension table with findings, severity counts, pass rates]
+
+## HIGH-Priority Findings
+[Findings requiring immediate attention]
+
+## MEDIUM-Priority Findings
+[Findings to address soon]
+
+## LOW-Priority Findings
+[Polish and minor items]
+
+## Dimensional Coverage
+[Which dimensions assessed, any gaps]
+
+## Recommendations
+[Top 3-5 prioritized action items]
+```
+
+## Error Handling
+
+- **Empty scope (no files to assess):** Return "Nothing to assess — no files found in scope" with verdict CLEAN
+- **Partial skill failure:** If one skill errors, continue with the remaining skills. Report the error in the output: "axiom:{skill} encountered an error: {message}. Results from other skills are still valid."
+- **Scope validation:** Verify file/directory exists before starting. If not found: "Scope not found: {path}"
+
+## Composition Guide
+
+For details on how audit discovers skills, handles deduplication, and formats reports, see `@skills/audit/references/composition-guide.md`.
+
+## References
+
+- Dimension taxonomy: `@skills/backend-quality/references/dimensions.md`
+- Finding format: `@skills/backend-quality/references/findings-format.md`
+- Scoring model: `@skills/backend-quality/references/scoring-model.md`
+- Composition details: `@skills/audit/references/composition-guide.md`

package/skills/audit/references/composition-guide.md

@@ -0,0 +1,105 @@
+# Audit Composition Guide
+
+How the `audit` skill orchestrates other axiom skills to produce a unified report.
+
+## Skill Discovery
+
+The audit skill invokes a fixed set of specialized skills:
+
+| Order | Skill | Dimensions Covered |
+|-------|-------|--------------------|
+| 1 | `axiom:scan` | All (deterministic) |
+| 2 | `axiom:critique` | Architecture, Topology |
+| 3 | `axiom:harden` | Observability, Resilience |
+| 4 | `axiom:distill` | Hygiene, Topology |
+| 5 | `axiom:verify` | Test Fidelity, Contracts |
+
+**Execution order matters:** `scan` runs first so specialized skills can reference its deterministic findings when layering qualitative assessment.
+
+## Finding Deduplication
+
+When aggregating findings from multiple skills, apply these rules in order:
+
+### Rule 1: Same Evidence + Same Dimension → Merge
+
+Two findings with identical `evidence` arrays and the same `dimension` are duplicates. Keep the one with the longer `explanation`. If lengths are equal, prefer the deterministic finding.
+
+### Rule 2: Same Evidence + Different Dimensions → Keep Both
+
+A single code location can violate multiple dimensions. For example, a lazy fallback constructor (DIM-1: Topology) may also be a silent error (DIM-2: Observability). Keep both findings — they represent genuinely different concerns.
+
+### Rule 3: Same Pattern + Different Files → Keep Separate
+
+The same anti-pattern in two different files is two separate findings. Each location needs independent attention.
+
+### Rule 4: Deterministic + Qualitative → Merge as Deterministic
+
+When `scan` and a qualitative skill both flag the same issue, merge them. The deterministic finding grounds the qualitative assessment. Set `deterministic: true` on the merged finding.
+
+## Coverage Matrix
+
+After deduplication, compute the coverage matrix:
+
+```text
+For each dimension (DIM-1 through DIM-7):
+  - deterministic_checks: count of scan checks run for this dimension
+  - qualitative_assessed: was a specialized skill invoked for this dimension?
+  - finding_count: total findings (post-dedup)
+  - severity_distribution: { HIGH: N, MEDIUM: N, LOW: N }
+```
+
+Flag dimensions with `deterministic_checks == 0 && finding_count == 0` as potentially unassessed.
+
+## Partial Failure Handling
+
+If a skill encounters an error during execution:
+
+1. **Catch the error** — do not abort the entire audit
+2. **Record the failure** — note which skill failed and why
+3. **Continue with remaining skills** — partial results are better than no results
+4. **Report the failure** — include a "Skill Failures" section in the report
+
+```markdown
+## Skill Failures
+
+- **axiom:critique** — Error: [error message]. Architecture and Topology dimensions may have incomplete coverage.
+```
+
+5. **Adjust coverage matrix** — mark the failed skill's dimensions as partially assessed
+
+## Report Assembly
+
+### Verdict Computation
+
+```typescript
+const HIGH_count = findings.filter(f => f.severity === 'HIGH').length;
+const MEDIUM_count = findings.filter(f => f.severity === 'MEDIUM').length;
+
+const verdict = (HIGH_count > 0 || MEDIUM_count > 5)
+  ? 'NEEDS_ATTENTION'
+  : 'CLEAN';
+```
+
+### Finding Ordering
+
+Within each severity tier, order findings by:
+1. Dimension (DIM-1 first, DIM-7 last)
+2. Evidence file path (alphabetical)
+3. Evidence line number (ascending)
+
+### Recommendations
+
+Generate 3-5 prioritized recommendations based on findings:
+1. Address all HIGH findings first
+2. Group related MEDIUM findings into themes
+3. Suggest targeted skill runs for dimensions with many findings
+4. If coverage gaps exist, recommend running specific skills
+
+## Consumer Integration
+
+Workflow tools that consume audit results should:
+
+1. Parse the verdict (CLEAN / NEEDS_ATTENTION)
+2. Map to their own status values (see scoring-model.md Consumer Mapping)
+3. Optionally extract individual findings for issue creation
+4. Use the coverage matrix to identify assessment gaps

package/skills/backend-quality/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: backend-quality
+description: "Core reference skill defining the backend quality dimension taxonomy, finding format, scoring model, and deterministic check catalog. Not user-invokable — referenced by all axiom skills as the shared foundation."
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: reference
+  dimensions:
+    - all
+---
+
+# Backend Quality — Foundation Reference
+
+This skill defines the shared foundation for all axiom backend quality skills. It is NOT user-invokable — it exists to be referenced by the specialized skills.
+
+## Dimension Taxonomy
+
+Seven canonical quality dimensions: `@skills/backend-quality/references/dimensions.md`
+
+| ID | Name | What it assesses |
+|----|------|-----------------|
+| DIM-1 | Topology | Dependency graphs, wiring, ambient state |
+| DIM-2 | Observability | Error visibility, logging, failure transparency |
+| DIM-3 | Contracts | Schema integrity, API consistency, type safety |
+| DIM-4 | Test Fidelity | Test-production divergence, mock quality |
+| DIM-5 | Hygiene | Dead code, vestigial patterns, evolutionary leftovers |
+| DIM-6 | Architecture | SOLID, coupling, cohesion, dependency direction |
+| DIM-7 | Resilience | Resource management, timeouts, failure handling |
+
+## Finding Format
+
+Standard schema for all skill output: `@skills/backend-quality/references/findings-format.md`
+
+## Scoring Model
+
+Verdict computation and health thresholds: `@skills/backend-quality/references/scoring-model.md`
+
+## Deterministic Checks
+
+Grep patterns and structural checks per dimension: `@skills/backend-quality/references/deterministic-checks.md`

package/skills/backend-quality/references/deterministic-checks.md

@@ -0,0 +1,151 @@
+# Deterministic Check Catalog
+
+Grep patterns and structural checks organized by dimension. The `scan` skill executes these checks mechanically. Other skills invoke `scan` for their dimensions, then layer qualitative assessment.
+
+Each check has: ID, pattern, what it detects, severity, and false-positive guidance.
+
+## DIM-1: Topology
+
+### T-1.1: Module-global mutable state
+- **Pattern:** `^(let|var)\s+\w+\s*[:=]` at file scope (not inside function/class body)
+- **Severity:** MEDIUM
+- **Detects:** Ambient state that can diverge across module boundaries
+- **False positives:** Intentional singletons with documented rationale; module-scoped constants that happen to use `let`
+
+### T-1.2: Lazy fallback constructors
+- **Pattern:** `if\s*\(\s*!\w+\s*\)\s*\{?\s*\w+\s*=\s*new\s`
+- **Severity:** HIGH
+- **Detects:** Degraded-mode instances created silently when wiring is missing
+- **False positives:** Intentional lazy initialization with logging/telemetry
+
+### T-1.3: Manual wiring functions
+- **Pattern:** `^export\s+(async\s+)?function\s+(configure|register|setup|init)\w+\s*\(`
+- **Severity:** MEDIUM
+- **Detects:** Manual dependency wiring that requires correct call order
+- **False positives:** Framework-required setup functions (e.g., Express middleware registration)
+
+## DIM-2: Observability
+
+### T-2.1: Empty catch blocks
+- **Pattern:** `catch\s*(\(\w*\))?\s*\{\s*\}`
+- **Severity:** HIGH
+- **Detects:** Errors swallowed silently with no handling
+- **False positives:** Intentional swallow with comment explaining rationale (rare, should be flagged for review)
+
+### T-2.2: Catch with only console.log
+- **Pattern:** `catch\s*\(\w+\)\s*\{\s*console\.(log|warn)\(`
+- **Severity:** MEDIUM
+- **Detects:** Error "handling" that only logs without context or recovery
+- **False positives:** Development-only logging in test helpers
+
+### T-2.3: Swallowed promise rejections
+- **Pattern:** `\.catch\(\s*\(\)\s*=>\s*\{?\s*\}?\s*\)`
+- **Severity:** HIGH
+- **Detects:** Promise rejections silently ignored
+- **False positives:** Intentional fire-and-forget with documented rationale
+
+## DIM-3: Contracts
+
+### T-3.1: Unsafe type assertions
+- **Pattern:** `\bas\s+(?!const\b)\w+`
+- **Severity:** MEDIUM
+- **Detects:** Type assertions that bypass TypeScript's type checking
+- **False positives:** Assertions after validated guards (e.g., `as Foo` after `instanceof Foo` check)
+
+### T-3.2: Non-null assertions
+- **Pattern:** `\w+!\.` or `\w+!\[`
+- **Severity:** MEDIUM
+- **Detects:** Non-null assertions that assume a value exists without checking
+- **False positives:** Assertions after explicit null checks in the same scope
+
+### T-3.3: Schema-type divergence (manual check)
+- **Execution:** manual (excluded from deterministic scan)
+- **Pattern:** Compare Zod schemas against TypeScript interfaces for missing/extra fields
+- **Severity:** HIGH
+- **Detects:** Runtime schema doesn't match compile-time types
+- **False positives:** Intentional partial schemas (e.g., input validation that accepts a subset)
+
+## DIM-4: Test Fidelity
+
+### T-4.1: Skipped tests
+- **Pattern:** `(describe|it|test)\.(skip|todo)\(`
+- **Severity:** MEDIUM
+- **Detects:** Tests that are disabled without tracked resolution
+- **False positives:** Tests with linked issue references (`// TODO(#123)`)
+
+### T-4.2: Mock-heavy tests
+- **Pattern:** Count `vi\.mock|jest\.mock|sinon\.stub` per test file; flag if >3
+- **Severity:** MEDIUM
+- **Detects:** Over-isolation that hides integration behavior
+- **False positives:** Tests for modules with many infrastructure boundaries
+
+### T-4.3: Test setup divergence (manual check)
+- **Execution:** manual (excluded from deterministic scan)
+- **Pattern:** Compare test factory/setup functions against production initialization code
+- **Severity:** HIGH
+- **Detects:** Test wiring that doesn't match production wiring
+- **False positives:** Intentional test-only configuration (e.g., in-memory DB for speed)
+
+## DIM-5: Hygiene
+
+### T-5.1: Commented-out code blocks
+- **Pattern:** `^\s*\/\/\s*(function|class|const|let|var|if|for|while|return|export)\s` (3+ consecutive lines)
+- **Severity:** MEDIUM
+- **Detects:** Code preserved in comments instead of version control
+- **False positives:** Documentation examples that happen to look like commented code
+
+### T-5.2: Unused exports
+- **Pattern:** Cross-reference `export` declarations against `import` statements project-wide
+- **Severity:** LOW
+- **Detects:** Exported symbols with no consumers
+- **False positives:** Public API surface intentionally exported for external consumers
+
+### T-5.3: Unreachable code
+- **Pattern:** Code after unconditional `return`, `throw`, `break`, or `continue`
+- **Severity:** MEDIUM
+- **Detects:** Dead code that can never execute
+- **False positives:** Generated code with defensive returns
+
+## DIM-6: Architecture
+
+### T-6.1: Circular imports
+- **Pattern:** Build import graph; detect cycles
+- **Severity:** HIGH
+- **Detects:** Circular dependencies between modules
+- **False positives:** Type-only imports that don't create runtime cycles
+
+### T-6.2: God objects
+- **Pattern:** Files with >500 lines or classes/objects with >10 exported members
+- **Severity:** MEDIUM
+- **Detects:** Modules with too many responsibilities
+- **False positives:** Intentional facades or barrel files
+
+### T-6.3: Dependency direction violations
+- **Pattern:** Core/domain modules importing from infrastructure/CLI/UI modules
+- **Severity:** MEDIUM
+- **Detects:** Inverted dependency direction (core depends on periphery)
+- **False positives:** Requires project-specific layer definitions to assess accurately
+
+## DIM-7: Resilience
+
+### T-7.1: Unbounded collections
+- **Pattern:** `new\s+(Map|Set|Array)\s*\(` without nearby `.delete`, `.clear`, or size check
+- **Severity:** HIGH
+- **Detects:** Collections that grow without bound
+- **False positives:** Collections with short, bounded lifetimes (e.g., within a request handler)
+
+### T-7.2: Missing timeouts
+- **Pattern:** `fetch\(` or `http\.(get|post|put)` without `signal`, `timeout`, or `AbortController`
+- **Severity:** MEDIUM
+- **Detects:** External calls that could hang indefinitely
+- **False positives:** Calls to localhost services with guaranteed fast response
+
+### T-7.3: Unbounded retry loops
+- **Pattern:** `while\s*\(.*retry` or `for\s*\(.*attempt` without max limit
+- **Severity:** HIGH
+- **Detects:** Retry logic that could loop forever
+- **False positives:** Loops with break conditions that aren't pattern-matched
+
+## Extensibility
+
+Projects can add custom checks via `.axiom/checks.md` at the repo root. Format matches this file — one section per dimension, each check with pattern, severity, description, and false-positive guidance. Custom checks are loaded alongside the built-in catalog by the `scan` skill.