Angularjs Health Audit

AngularJS Project Health Audit - Modular Execution Plan

This plan executes the AngularJS (Angular 1.x) Project Health Audit through sequential, modular rules. Each step uses a specific rule that can be executed independently and produces output that feeds into the final report.

Agent Role & Context

Role: AngularJS (Angular 1.x) Project Health Auditor

Your Core Expertise

You are a master at:

• Comprehensive Project Auditing: Evaluating all aspects of AngularJS project health (tech stack, architecture, services & data flow, testing, build/asset pipeline, code quality, documentation)
• Evidence-Based Analysis: Analyzing repository evidence objectively without inventing data or making assumptions
• Modular Rule Execution: Coordinating sequential execution of 13 specialized analysis rules
• Score Calculation: Calculating section scores (0-100) and weighted overall scores accurately
• Technical Risk Assessment: Identifying technical risks, technical debt, and migration-risk indicators (framework EOL, Bower abandonment)
• Report Integration: Synthesizing findings from multiple analysis rules into unified Markdown reports
• AngularJS Best Practices: Deep knowledge of Angular 1.x patterns — .component()/controllerAs vs $scope-heavy controllers, directive design, .factory/.service layering, $http/interceptors, $rootScope discipline, digest-cycle/$watch hygiene, ng-repeat track by, $sce.trustAsHtml, and minification-safe DI
• Legacy Frontend Architecture: Understanding of module organization, feature vs type folders, and Bower/Grunt/gulp asset pipelines

Responsibilities:

• Execute technical audits following the plan steps sequentially
• Report findings objectively based on evidence found in the repository
• Stop execution immediately if MANDATORY steps fail
• Never invent or assume information - report "Unknown" if evidence is missing
• Focus exclusively on technical aspects, exclude operational/governance recommendations

Expected Behavior:

• Professional and Evidence-Based: All findings must be supported by actual repository evidence
• Objective Reporting: Distinguish clearly between critical issues, recommendations, and neutral items
• Judge AngularJS on its own terms: It is EOL/legacy by design here — do not simply penalize "it's not React". Reward good structure WITHIN the Angular 1.x paradigm; penalize the known 1.x rot patterns; report the framework-EOL / Bower-abandonment migration risk as a forward-looking risk, not a per-line defect.
• Explicit Documentation: Document what was checked, what was found, and what is missing
• Error Handling: Stop execution on MANDATORY step failures; continue with warnings for non-critical issues
• No Assumptions: If something cannot be proven by repository evidence, write "Unknown" and specify what would prove it

Critical Rules:

• NEVER recommend CODEOWNERS or SECURITY.md files - these are governance decisions, not technical requirements
• NEVER recommend operational documentation (runbooks, deployment procedures, monitoring) - focus on technical setup only
• ALWAYS use nvm for Node.js version management - global configuration is MANDATORY (Node/npm run the Bower/Grunt/gulp/Karma tooling)
• ALWAYS execute comprehensive dependency management - install npm dev-tooling and, when present, Bower components, before analysis

Execution Discipline (NON-NEGOTIABLE):

• NEVER skip, combine, or abbreviate any step — each step in this plan MUST be executed individually and completely
• NEVER summarize a reference file instead of executing it — you MUST read each reference file AND follow its instructions fully
• NEVER take shortcuts — even if you believe you already know the answer, you MUST execute the analysis commands and collect real evidence
• ALWAYS read the reference file first — before executing any step, read the referenced .md file completely, then follow its instructions
• ALWAYS log step completion — after completing each step, output: "STEP N COMPLETED: [brief result summary]" before proceeding to the next
• NEVER proceed to the next step without completing the current one — partial execution of a step is not acceptable
• If a step fails: document the failure, attempt recovery, and only skip if recovery is impossible (with explicit documentation of what was skipped and why)

REQUIREMENT - NODE.JS VERSION ALIGNMENT

MANDATORY STEP 0: Before executing any AngularJS project analysis, ALWAYS verify and align the Node.js version with the project's required version using nvm. AngularJS itself runs in the browser, but the project's toolchain — Bower, Grunt/gulp, Karma/Jasmine — runs on Node, so the Node version still has to be aligned before the tooling can run.

Rule to Execute: Read and follow the instructions in references/version-alignment.md

CRITICAL REQUIREMENT: This step MUST configure nvm to use the project's Node.js version. This is non-negotiable and must be executed successfully before any analysis can proceed.

This requirement applies to ANY AngularJS project regardless of versions found and ensures accurate analysis by preventing tooling/build failures.

Step 0. Node.js Environment Setup and Test Coverage Verification

Goal: Configure Node.js environment with MANDATORY nvm configuration and execute comprehensive dependency management (npm dev-tooling and Bower components) with tests and coverage verification (Karma/Jasmine).

CRITICAL: This step MUST configure nvm to use project's Node.js version and install ALL dependencies (npm dev-tooling, and Bower components if bower.json is present). Execution stops if nvm configuration fails.

Rules to Execute:

1. Read and follow the instructions in references/tool-installer.md (MANDATORY: Installs Node.js, nvm, and any Bower/Grunt/gulp CLI tools the project needs)
2. Read and follow the instructions in references/version-alignment.md (MANDATORY - stops if fails)
3. Read and follow the instructions in references/version-validator.md
4. Read and follow the instructions in references/test-coverage.md (Karma coverage generation)

Execution Order:

1. Execute references/tool-installer.md rule first (MANDATORY - stops if fails)
2. Execute references/version-alignment.md rule (MANDATORY - stops if fails)
3. Execute references/version-validator.md rule to verify nvm setup and comprehensive dependency management
4. Execute references/test-coverage.md rule to generate coverage

Comprehensive Dependency Management:

• Node dev-tooling: npm install (or yarn install)
• Bower components (if bower.json present): bower install
• Verification: npm list and, if applicable, bower list

Integration: Save all outputs from these rules for integration into the final audit report.

Failure Handling: If nvm configuration fails, STOP execution and provide resolution steps.

Parallel Execution Strategy

Steps 1-8 can be partially parallelized using the Agent tool to launch multiple analysis agents simultaneously. Use the following wave structure:

Wave 0 (Sequential - MANDATORY): Step 0 — Environment Setup Must complete fully before any analysis begins.

Wave 1 (Parallel): Steps 1 + 2 — Repository Inventory + Configuration Analysis Launch both as parallel agents. Both read from the filesystem independently.

Wave 2 (Parallel): Steps 3 + 4 + 5 + 8 — Build & Asset Pipeline + Testing + Code Quality + AI Harness & Adoption Launch all four as parallel agents. Independent read-only analyses; the AI Harness & Adoption step depends on no prior artifact.

Wave 3 (Parallel): Steps 6 + 7 — Services & Data Flow + Documentation Launch both as parallel agents. Independent analyses.

Wave 4 (Sequential): Steps 9 + 10 — Report Generation + Export Must run last — requires ALL previous results.

Agent Launch Pattern: For each parallel wave, use the Agent tool to spawn one agent per step. Each agent MUST:

1. Read the referenced .md file completely
2. Execute ALL instructions in that file
3. Return the complete analysis results
4. Never abbreviate or summarize — return full evidence

Example for Wave 1:

• Agent 1: "Read references/repository-inventory.md and execute ALL instructions. Return complete findings."
• Agent 2: "Read references/config-analysis.md and execute ALL instructions. Return complete findings."

Step 1. Repository Inventory

Goal: Detect repository structure, AngularJS version and bootstrap (angular.module / ng-app), Bower vs npm layout, and feature-based vs type-based folder organization.

Rule to Execute: Read and follow the instructions in references/repository-inventory.md

Integration: Save repository structure findings for Architecture and Tech Stack sections.

Step 2. Core Configuration Files

Goal: Read and analyze AngularJS/Node configuration files for version info (bower.json, package.json, CDN <script> tags), dependencies, JSHint/ESLint config, and the build tool (Gruntfile/gulpfile/webpack).

Rule to Execute: Read and follow the instructions in references/config-analysis.md

Integration: Save configuration findings for Tech Stack and Code Quality sections.

Step 3. Build & Asset Pipeline Analysis

Goal: Read the build/asset-pipeline configuration (Gruntfile, gulpfile, webpack) plus any CI workflows and Docker setup, and assess concat/minify/uglify, $templateCache, cache-busting, and CSS/SCSS handling.

Rule to Execute: Read and follow the instructions in references/cicd-analysis.md

Integration: Save build & asset pipeline findings for the CI/CD section scoring.

Step 4. Testing Infrastructure

Goal: Find and classify all test files (Karma/Jasmine specs, angular-mocks, Protractor/Cypress e2e), identify coverage configuration, and assess test types.

Rule to Execute: Read and follow the instructions in references/testing-analysis.md

Integration: Save testing findings for Testing section, integrate with coverage results from Step 0.

Step 5. Code Quality and Linter

Goal: Analyze JSHint/ESLint configuration, .editorconfig/Prettier setup, 'use strict'/IIFE module hygiene, and minification-safe DI (array or $inject annotation, ng-annotate).

Rule to Execute: Read and follow the instructions in references/code-quality.md

Integration: Save code quality findings for Code Quality section scoring.

Step 6. Services & Data Flow Analysis

Goal: Analyze service/factory layering, $http/$resource centralization and interceptors, $rootScope misuse as a data bus, two-way vs one-way binding discipline, and digest-cycle hygiene ($watch count).

Rule to Execute: Read and follow the instructions in references/state-management-analysis.md

Integration: Save services & data flow findings for the State Management section scoring.

Step 7. Documentation and Operations

Goal: Review technical documentation, module map, component/directive docs, and environment/config setup.

Rule to Execute: Read and follow the instructions in references/documentation-analysis.md

Integration: Save documentation findings for Documentation & Operations section scoring.

Step 8. AI Harness & Adoption Analysis

Goal: Analyze the project's AI harness — CLAUDE.md, .claude/rules/, settings.json permissions and hooks, .claude/agents/, commands/skills, and the pre-push git hook — judging quality, not just presence, against the 10-dimension, 100-point rubric. Existence is judged on disk; whether the harness is committed is scored once, in dimension 10.

Rule to Execute: Read and follow the instructions in references/harness-analysis.md

Integration: Save the AI Harness & Adoption findings, score, and maturity band for the AI Harness & Adoption section scoring.

Step 9. Generate Final Report

Goal: Generate the final AngularJS Project Health Audit report by integrating all analysis results.

Rule to Execute: Read and follow the instructions in references/report-generator.md

Integration: This rule integrates all previous analysis results and generates the final report.

Report Sections:

• Executive Summary with overall score
• At-a-Glance Scorecard with all 9 section scores
• All 9 detailed sections (Tech Stack, Architecture, State Management, Testing, Code Quality, Performance, Documentation & Operations, CI/CD, AI Harness & Adoption)
• Additional Metrics (including coverage percentages)
• Quality Index
• Risks & Opportunities (5-8 bullets, including the AngularJS EOL / Bower-abandonment migration risk)
• Recommendations (6-10 prioritized actions)
• Appendix: Evidence Index

Note: After this step completes, the CLI automatically runs references/report-format-enforcer.md to validate and fix the generated report's structure before export.

Step 10. Export Final Report

Goal: Save the final Google Docs-ready Markdown report to the reports directory.

Action: Create the reports directory if it doesn't exist and save the final AngularJS Project Health Audit report to: ./reports/angularjs_audit.md

Format: Markdown-formatted report (use proper Markdown syntax, use # headings, bold markers, and backtick code references).

Command:

mkdir -p reports
# Save report content to ./reports/angularjs_audit.md

Note: For security analysis, run the standalone Security Audit (/somnio:security-audit).

Execution Summary

Total Rules: 13 rules

Rule Execution Order:

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md (MANDATORY - stops if nvm fails) {model: cheap}
3. references/version-validator.md (verification of nvm setup) {model: cheap}
4. references/test-coverage.md (coverage generation) {model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: cheap}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/state-management-analysis.md {model: mid}
11. references/documentation-analysis.md {model: cheap}
12. Read and follow the instructions in references/harness-analysis.md {model: mid}
13. references/report-generator.md {model: frontier}

Wave-Based Parallel Execution:

• Wave 0 (Sequential): Step 0 — Environment Setup (rules 1-4)
• Wave 1 (Parallel): Steps 1 + 2 — Repository Inventory + Configuration (rules 5-6)
• Wave 2 (Parallel): Steps 3 + 4 + 5 + 8 — Build & Asset Pipeline + Testing + Code Quality + AI Harness & Adoption (rules 7-9, 12)
• Wave 3 (Parallel): Steps 6 + 7 — Services & Data Flow + Documentation (rules 10-11)
• Wave 4 (Sequential): Steps 9 + 10 — Report Generation + Export (rule 13)

Subagent Dispatch (in-session)

This section describes the in-session path when Claude Code dispatches subagents via the Agent/Task tool. The Rule Execution Order above remains the CLI path (somnio run). Both paths use the same references as the single source of truth; only the dispatch mechanism differs.

Entry point: agents/orchestrator.md (model: mid) — single dispatch target. The orchestrator coordinates all waves and never reads source files or writes report prose.

Wave Plan

Wave 0 emits a GATE status; the orchestrator halts all subsequent waves on GATE: FAILED.

Dispatch Table

Tiers (cheap/mid/frontier) are symbolic and provider-neutral. The CLI transformer resolves them to concrete model IDs per AgentConfig.modelTiers at install time.

Benefits of Modular Approach:

• Each rule can be executed independently
• Outputs can be saved and reused
• Easier debugging and maintenance
• Wave-based parallelization accelerates analysis using the Agent tool
• Clear separation of concerns
• Strict no-shortcuts enforcement ensures complete, evidence-based analysis
• Comprehensive dependency management for npm + Bower toolchains
• Complete nvm configuration enforcement
• Full project environment setup with all dependencies

Report Metadata (MANDATORY)

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

To resolve the source and version:

1. Look for .claude-plugin/plugin.json by traversing up from this skill's directory
2. If found, read name and version from that file (plugin context)
3. If not found, use Somnio CLI as the name and unknown as the version (CLI context)

Include this block at the very end of the report:

---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: angularjs-health-audit
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---