Architecture Quality Assess

Architecture Quality Assessment

Static-analysis pipeline that scores a codebase's architecture (0-100) and reports violations with file:line detail and fix recommendations. Analysis-only — never edits code. Supports Python and JS/TS projects (Next.js, React, Vue, Express, NestJS, FastAPI, Django, Flask).

Workflow

1. Run the assessment:

   bash ~/.claude/skills/architecture-quality-assess/skill.sh [PROJECT_PATH] [OPTIONS]
   

   The project root must contain a manifest (package.json, requirements.txt, or pyproject.toml) or project detection fails.

2. CLI options (verified against scripts/assess.py --help — trust this table over older docs):

   Option	Meaning	Default
   project_path	Directory to analyze	.
   --format {markdown,json,tasks,all}	Report format(s)	markdown
   --output, -o	Output file path	<project>/architecture-assessment.{md,json}
   --severity {critical,high,medium,low}	Minimum severity reported	low
   --verbose, -v	Detailed progress	off
   --no-cache	Force full re-parse	caching on
   --list-analyzers	List analyzers and exit	—

   Caution: README.md mentions --incremental, --cache, --generate-tasks, and --config; those flags do NOT exist in assess.py. Use --format tasks for the task list.

3. Read the report (architecture-assessment.md in the project root): overall score, then violations by severity (critical → low), each with file, line, and recommendation. Exit code is 1 when critical violations exist — usable directly as a CI gate (--format json --severity critical).

4. Optional follow-ups:

   • --format tasks (or all) writes architecture-refactoring-tasks.md, consumable by /start-phase-execute and /pm-db import.
   • Drift detection runs automatically when memory-bank/systemPatterns.md / systemArchitecture.md exist in the project.

What it analyzes

Seven analyzers: project/framework detection, layer separation (Clean Architecture), SOLID (all 5 principles), design patterns and anti-patterns, coupling metrics + circular dependencies, code organization, and memory-bank drift.

Workflow verify (diverse-lens false-positive reduction)

scripts/assess.py's pattern-matching can collide with unrelated same-named constructs (e.g. an Express router's .delete() HTTP-verb method matching an "ORM usage" pattern) or produce dependency-graph artifacts (e.g. a module reported as depending on itself). For a lower-false- positive report, wrap its output in the diverse-lens verify graph: workflows/architecture-quality-assess-verify.js, invoked via Workflow({ scriptPath: '~/.claude/workflows/architecture-quality-assess-verify.js' }) (never by name — see docs/graph-orchestration.md §6). It does not re-analyze anything; it takes assess.py's own violations as input, one grounding agent per file re-reads the real code, then three distinct-lens verifiers (correctness / security / reproduces — reinterpreted for architecture: does the pattern-match hold, does it cross a real security/data boundary, does tracing the actual code/import path confirm it) each try to REFUTE every violation, defaulting to refuted under uncertainty. A violation reaches the report only on majority non-refutation (FRS FR-14).

assess.py <path> --format json currently errors on a pre-existing bug unrelated to this workflow (lib/reporters/json_reporter.py reads a SOLIDMetrics attribute that doesn't exist — already failing tests/test_integration.py::test_json_report_generation in this skill's own baseline suite). Until that's fixed independently, obtain the violations array by calling the same orchestrator the CLI uses, bypassing only the broken reporter:

cd skills/architecture-quality-assess && python3 -c "
import sys, json; sys.path.insert(0, '.')
from pathlib import Path
from scripts.assess import AssessmentOrchestrator
p = Path('<project_path>').resolve()
orch = AssessmentOrchestrator(project_path=p, verbose=False, cache_enabled=False)
result = orch.run()
print(json.dumps([v.to_dict() for v in result.violations]))
"

then pass that array as args.violations (plus repo_root and project_path) to the workflow.

When to use the plain analyzer vs the verify graph: plain assess.py for routine scans/CI gates where a human triages the report anyway; the verify graph (one grounding agent per file plus 3 verifier agents per violation, bounded by args.max_findings, default 15, per FRS FR-17) when the violation set feeds an automated gate or a report acted on without re-checking each line.

Measured on the skill's own fixtures (tests/fixtures/{django-app,express-api,nextjs-app-router, python-fastapi}): the raw analyzer produced exactly 2 violations across all four fixtures (1 per app that had any), and both were false positives — a self-referential "circular dependency" that was a dependency-graph artifact, and an "ORM usage" match that was actually Express's router.delete() HTTP-verb method in a fixture with no database layer at all. The verify pass refuted both, unanimously (3/3 lenses each). Full methodology and numbers: ~/.claude/job-queue/feature-graph-orchestration/docs/planning/task-updates/task-15-diverse-lens-verify.md.

Docs and references (read on demand)

• README.md (this dir) — user guide: use cases, score/severity/metric interpretation, .architecture-assess.json config basics, skill integrations (memory-bank, pm-db, document-hub), GitHub Actions CI example, troubleshooting, best practices, FAQ.
• USAGE_GUIDE.md (this dir) — command walkthroughs and workflow scripts: pre-refactor assessment, CI quality gate, weekly review, self-analysis.
• references/analysis-details.md — per-analyzer violation heuristics (SOLID rules, pattern/anti-pattern catalog, coupling thresholds, drift detection) with example output. Read when explaining why something was flagged.
• references/report-formats.md — full markdown/JSON report schemas and generated task-list format. Read when parsing JSON output or wiring CI checks.
• references/operations.md — optional deps (networkx, tree-sitter), full config-file schema, performance/caching notes, extra troubleshooting/FAQ, changelog. Read for setup or slow analysis.