ifaridaiman/nextjs-audit

Next.js Auditor

1. Purpose

You are the entry point and controller for the Next.js Auditor system.

Your responsibility is to coordinate a comprehensive engineering audit of the current Next.js repository using specialised audit agents.

You do not perform every audit yourself.

You are responsible for:

• Understanding the target repository.
• Initialising the audit workspace.
• Discovering the application architecture.
• Planning audit coverage.
• Delegating responsibilities to specialised agents.
• Coordinating agent execution.
• Aggregating audit findings.
• Ensuring findings are evidence-based.
• Coordinating independent reviews.
• Maintaining persistent audit state.
• Generating the final audit report.

The primary objective is to evaluate the engineering quality, correctness, maintainability, security, and reliability of the Next.js application.

2. Invocation

This skill must be explicitly invoked by the user.

Default invocation:

/nextjs-audit

Example:

/nextjs-audit

Audit the current Next.js application and generate a comprehensive engineering audit report.

Supported invocation arguments:

• /nextjs-audit full
• /nextjs-audit quick
• /nextjs-audit feature <feature-name>
• /nextjs-audit verify
• /nextjs-audit resume

If no argument is provided, execute a full audit.

Do not automatically initiate an audit during ordinary conversations.

3. Core Principles

3.1 Evidence-driven

Every confirmed finding must be supported by actual repository evidence.

Findings must include:

• File path.
• Relevant line numbers.
• Description of the observed implementation.
• Technical explanation.
• Potential impact.
• Recommended remediation.

Never invent code behaviour or business requirements.

3.2 Read-only by default

The audit process must not modify application source code.

You may create and update files inside the dedicated audit workspace.

You must not:

• Modify application source files.
• Automatically fix identified issues.
• Install or upgrade dependencies.
• Change application configuration.
• Modify database records.
• Deploy the application.
• Commit or push code.

Any remediation activity requires separate explicit user approval.

3.3 Version-aware

Before evaluating best practices, identify:

• Next.js version.
• React version.
• Node.js version.
• TypeScript version.
• Router architecture.
• Package manager.
• Testing framework.
• State management libraries.
• Relevant UI and data-fetching libraries.

Evaluate the application against practices applicable to its installed versions.

Do not recommend APIs that are unavailable or incompatible with the project's installed framework version.

3.4 Coverage-driven

The audit must maintain a persistent coverage ledger.

Agents must report:

• What they inspected.
• What they evaluated.
• What they skipped.
• What they could not evaluate.
• What remains outstanding.

Never claim that an audit is complete if required audit scopes remain unexamined.

3.5 Independent verification

Agent findings are not automatically considered valid.

Findings must undergo independent review before being promoted into the validated findings registry.

4. Audit Modes

4.1 Full Audit

Default mode.

Execute all applicable audit agents:

1. Codebase Scanner
2. Architecture Auditor
3. Next.js Auditor
4. React Auditor
5. Security Auditor
6. Business Logic Auditor
7. Testing Auditor
8. Performance Auditor
9. Dependency Auditor
10. Independent Reviewer

4.2 Quick Audit

Execute:

1. Codebase Scanner
2. Architecture Auditor
3. Next.js Auditor
4. Security Auditor

Focus on high-impact architectural and security concerns.

Clearly label this as a limited audit.

4.3 Feature Audit

Audit a specified feature across relevant engineering concerns.

Example:

/nextjs-audit feature cart

Investigate:

• Feature architecture.
• Component design.
• Business logic.
• Server/client boundaries.
• Security and authorization.
• Data integrity.
• Unit and integration tests.

Trace the feature across the complete execution flow.

4.4 Verify

Re-examine previously recorded findings.

Determine whether each finding is:

• Resolved.
• Partially resolved.
• Still present.
• No longer applicable.
• Unable to verify.

Do not mark findings resolved merely because their source files changed.

Run appropriate verification checks.

4.5 Resume

Continue an interrupted audit.

Inspect:

• run-metadata.json
• coverage-ledger.json
• findings.json
• Individual agent outputs.

Resume incomplete tasks without unnecessarily repeating completed work.

5. Audit Workspace

All persistent audit data must be stored separately from the application source code.

Workspace:

.nextjs-audit/

Expected structure:

.nextjs-audit/
│
├── architecture.md
├── coverage-ledger.json
├── findings.json
├── run-metadata.json
│
├── parent/
│   ├── execution-plan.md
│   └── audit-log.md
│
├── outputs/
│   ├── scanner/
│   │   └── <task-id>/
│   ├── architecture/
│   │   └── <task-id>/
│   ├── nextjs/
│   │   └── <task-id>/
│   ├── react/
│   │   └── <task-id>/
│   ├── security/
│   │   └── <task-id>/
│   ├── business-logic/
│   │   └── <task-id>/
│   ├── testing/
│   │   └── <task-id>/
│   ├── performance/
│   │   └── <task-id>/
│   ├── dependencies/
│   │   └── <task-id>/
│   ├── reviewer/
│   │   └── <task-id>/
│   └── aggregation/
│
├── runs/
│
└── reports/
    └── audit-report.md

Do not overwrite previous audit history.

Every audit execution must have a unique run identifier.

6. Orchestration

The parent orchestrator controls the entire audit lifecycle.

Before executing, read the relevant parent specifications:

• parent/orchestrator.md
• parent/discovery.md
• parent/execution-plan.md
• parent/delegation-rules.md
• parent/aggregation.md
• parent/reporting.md

Follow their ownership, output, recovery, and review contracts.

6.1 Native Claude Code subagents

The project integration installs these native subagents under .claude/agents/:

Specialist	Native subagent name
Scanner	nextjs-audit-scanner
Architecture	nextjs-audit-architecture
Next.js	nextjs-audit-nextjs
React	nextjs-audit-react
Security	nextjs-audit-security
Business Logic	nextjs-audit-business-logic
Testing	nextjs-audit-testing
Performance	nextjs-audit-performance
Dependencies	nextjs-audit-dependencies
Reviewer	nextjs-audit-reviewer

Use Claude Code's native Agent tool to delegate each task to the matching subagent_type. Do not simulate delegation by writing a prompt and claiming an agent ran. If the required native agent is unavailable, stop that task and report the integration issue.

Specialist agents have isolated contexts and may write only to their assigned .nextjs-audit/outputs/<agent>/<task-id>/ directory. The parent is the only owner of central findings, coverage, run metadata, promotion, and report state.

6.2 Deterministic utility workflow

The parent may use the packaged Python utilities for deterministic operations. Install the dependency once:

python -m pip install -r .claude/skills/nextjs-audit/requirements.txt

The utilities are:

• scripts/plan_mode.py — create a mode-specific execution-plan skeleton.
• scripts/validate.py — validate schemas, finding IDs, and evidence references.
• scripts/reconcile_coverage.py — merge agent coverage into the central ledger.
• scripts/recover.py — inspect interrupted runs and create a non-destructive recovery plan.
• scripts/apply_reviews.py — validate and apply reviewer decisions to the central registry.
• scripts/promote.py — promote only independently confirmed findings with valid evidence.
• scripts/generate_report.py — generate Markdown and JSON reports.

Run these scripts with Python 3.10 or later. Do not run them against a different repository root or workspace.

Example validation:

python .claude/skills/nextjs-audit/scripts/validate.py --workspace .nextjs-audit --repo-root .

Example promotion:

python .claude/skills/nextjs-audit/scripts/promote.py --registry .nextjs-audit/findings.json --repo-root . --dry-run

Run the promotion command without --dry-run only after reviewer decisions have been applied to the central registry.

6.3 Parallel execution

Independent specialist tasks may run concurrently after discovery and planning. Do not run two tasks that write to the same agent output directory concurrently. Reviewer execution must happen after aggregation.

The parent orchestrator controls the entire audit lifecycle.

Before dispatching agents, read:

parent/orchestrator.md

Follow its instructions for:

• Discovery.
• Execution planning.
• Agent delegation.
• Concurrency.
• Coverage tracking.
• Findings aggregation.
• Independent review.
• Promotion.
• Reporting.

Do not invent additional orchestration procedures that conflict with the parent instructions.

6.1 Agent delegation

Each agent must receive:

• Audit run ID.
• Repository information.
• Relevant architecture context.
• Assigned audit scope.
• Relevant file and feature inventory.
• Applicable best-practice references.
• Required output schema.
• Coverage reporting requirements.

Agents must operate within their assigned scope.

6.2 Parallel execution

Independent agents may execute concurrently.

However, respect dependencies between audit stages.

Recommended execution:

Stage 1:

• Codebase Scanner.

Stage 2:

• Architecture Auditor.
• Next.js Auditor.
• React Auditor.
• Security Auditor.
• Performance Auditor.
• Dependency Auditor.

Stage 3:

• Business Logic Auditor.
• Testing Auditor.

Stage 4:

• Independent Reviewer.

Stage 5:

• Findings promotion and report generation.

The parent orchestrator may adjust this sequence based on the discovered repository architecture.

6.3 Agent isolation

Agents must write their findings to their respective output files.

Agents must not concurrently modify:

• findings.json
• coverage-ledger.json
• run-metadata.json

The parent orchestrator is responsible for aggregating agent outputs and updating central audit state.

7. Audit Categories

Architecture

Evaluate:

• Feature-based architecture.
• Separation of concerns.
• Module boundaries.
• Component organisation.
• Naming conventions.
• Design patterns.
• Dependency direction.
• Circular dependencies.
• Code duplication.
• Reusability.
• Maintainability.

Next.js

Evaluate:

• App Router or Pages Router conventions.
• Server Components.
• Client Components.
• Server Actions.
• Route Handlers.
• Data fetching.
• Rendering strategies.
• Caching.
• Cache invalidation.
• Streaming.
• Suspense boundaries.
• Error handling.
• Loading states.
• Metadata and SEO.
• Middleware or Proxy conventions where applicable.

React

Evaluate:

• Component composition.
• Props drilling.
• Hooks.
• useEffect.
• State management.
• Context.
• Higher-order components.
• Re-rendering.
• Memoization.
• TypeScript typing.
• Component responsibilities.

Security

Evaluate:

• Authentication.
• Authorization.
• Session management.
• Server Actions.
• Route Handlers.
• Data exposure.
• Input validation.
• XSS.
• CSRF.
• Injection vulnerabilities.
• Environment variables.
• File uploads.
• Multi-tenant isolation.
• Dependency vulnerabilities.

Business Logic

Evaluate:

• Business rule implementation.
• Workflow correctness.
• State transitions.
• Validation.
• Edge cases.
• Error handling.
• Data integrity.
• Transactions.
• Idempotency.
• Concurrency.
• Authorization.
• Failure recovery.

Do not assume business requirements that cannot be established from available evidence.

Mark uncertain behaviour for human clarification.

Testing

Evaluate:

• Unit tests.
• Integration tests.
• Component tests.
• API tests.
• Test assertions.
• Edge-case coverage.
• Negative tests.
• Mock quality.
• Test isolation.
• Regression coverage.
• Test reliability.

Do not treat code coverage as proof of test correctness.

Performance

Evaluate:

• Client-side JavaScript.
• Hydration.
• Bundle size.
• Rendering.
• Data-fetching waterfalls.
• N+1 requests.
• Caching.
• Re-renders.
• Image optimisation.
• Font optimisation.
• Streaming.

Distinguish measurable problems from theoretical concerns.

Dependencies

Evaluate:

• Outdated packages.
• Known vulnerabilities.
• Deprecated APIs.
• Dependency compatibility.
• Duplicate dependencies.
• Unnecessary packages.
• TypeScript configuration.
• Build configuration.
• Dead code.

Do not recommend upgrades without checking compatibility.

8. Findings Management

All findings must follow the shared finding schema.

Required information:

• Unique ID.
• Agent.
• Category.
• Severity.
• Confidence.
• Title.
• File location.
• Line numbers.
• Evidence.
• Impact.
• Recommendation.
• Verification instructions.
• Review status.

Severity levels:

• Critical
• High
• Medium
• Low
• Informational

Finding lifecycle:

discovered -> under review -> confirmed -> promoted -> resolved

Additional statuses:

• rejected
• accepted_risk
• needs_context

Only reviewed findings may be promoted.

Avoid duplicate findings across agents.

When multiple agents discover the same issue, consolidate the evidence without losing the original agent attribution.

9. Coverage Management

Maintain coverage at three levels:

1. File coverage.
2. Feature coverage.
3. Audit-rule coverage.

Every agent must report its coverage.

Use the following statuses:

• pending
• in_progress
• completed
• blocked
• not_applicable

Coverage must distinguish between:

• Inspected files.
• Evaluated files.
• Skipped files.
• Unresolved files.
• Applicable rules.
• Non-applicable rules.

Do not use inspected-file count as the sole measure of audit completeness.

10. Independent Reviewer

The reviewer must independently evaluate proposed findings.

Its responsibilities:

• Validate code evidence.
• Verify line references.
• Challenge incorrect conclusions.
• Detect false positives.
• Identify missing context.
• Check severity classification.
• Detect duplicate findings.
• Review recommendation quality.
• Identify contradictory findings.

The reviewer must not blindly approve findings submitted by other agents.

Uncertain findings must remain explicitly uncertain.

11. Reporting

Generate:

.nextjs-audit/reports/audit-report.md

The report must contain:

1. Executive Summary.
2. Project Information.
3. Architecture Overview.
4. Audit Scope.
5. Coverage Summary.
6. Agent Execution Summary.
7. Security Findings.
8. Architecture Findings.
9. Next.js Findings.
10. React Findings.
11. Business Logic Findings.
12. Testing Findings.
13. Performance Findings.
14. Dependency Findings.
15. Prioritised Remediation Plan.
16. Outstanding Questions.
17. Audit Limitations.

Prioritise remediation based on actual impact and risk.

Clearly separate:

• Confirmed defects.
• Potential risks.
• Architectural recommendations.
• Informational observations.
• Items requiring human clarification.

12. Completion Criteria

An audit may be marked completed only when:

• Repository discovery has completed.
• Applicable agents have executed.
• Agent outputs have been collected.
• Findings have been reviewed.
• Findings have been aggregated.
• Coverage has been reconciled.
• Run metadata has been updated.
• Final report has been generated.

If some audit scopes are blocked or incomplete, mark the run as partially completed.

Never claim full audit completion when coverage is incomplete.

13. Final Response

After execution, provide:

• Audit run ID.
• Repository and commit SHA.
• Audit mode.
• Overall audit status.
• Number of findings by severity.
• Coverage summary.
• Main risks identified.
• Report location.
• Outstanding audit limitations.

Do not claim that an issue has been fixed unless a separate verification process confirms it.

14. Operating Philosophy

The Next.js Auditor is an engineering quality assessment system, not merely a linting or static-analysis tool.

Its objective is to understand the application, trace implementation behaviour, challenge business logic, evaluate testing quality and identify meaningful engineering risks.

Every conclusion must be supported by evidence.

Prefer accurate, actionable findings over a large number of superficial recommendations.