Imported from vaibhav-nampalliwar/audit_node_skill (skills/audit-orchestration/SKILL.md). Install upstream with npx skills add vaibhav-nampalliwar/audit_node_skill --skill audit-orchestration. Copyright stays with the author.

Audit Orchestration

Purpose

Turn one audit request into a safe, traceable, complete audit run. This skill is the control plane: it determines what is applicable, sequences independently owned skills, records coverage and state, and ensures that the resulting evidence can be normalized, scored, reported, compared, and repaired. It does not reinterpret raw scanner output, execute specialist scans itself, or alter the audited project.

Responsibilities

• Validate the audit request against the shared audit-request contract.
• Allocate an immutable UTC run identifier and create a run manifest before work starts.
• Invoke project discovery, framework detection, and execution preflight before selecting audit modules.
• Build a per-service applicability and execution plan using the shared decision engine and audit profile.
• Dispatch only applicable specialist skills and preserve each skill's tool-run ownership.
• Track every requested check as passed, completed_with_findings, failed, timed_out, unavailable, blocked, skipped_by_policy, or not_applicable.
• Route raw evidence through finding intelligence before requesting scoring, repair planning, comparison, or report rendering.
• Enforce required gates and report completeness without converting unavailable work into a pass.
• Produce no source-code, dependency, configuration, or deployment changes.

Scope

This skill governs an audit from request intake through delivery of the run artifacts. It supports local, pull-request, scheduled, release, and multi-service modes. It owns orchestration state, coverage accounting, dependency ordering, and safe retries.

It does not own linting, source review, dependency scanning, secret scanning, container scanning, dynamic API testing, runtime diagnostics, load testing, severity assignment, score arithmetic, report rendering, repair generation, or CI configuration authoring. Those capabilities remain with their named skills.

Supported Frameworks

The coordinator supports any project recognized by Framework Signatures, including Node.js JavaScript and TypeScript services; Express, NestJS, and Fastify backends; React, Next.js, and Vite frontends; npm, pnpm, Yarn, and Bun workspaces; Dockerized services; and monorepos. A framework is supported only after the detection skill emits evidence for it; unknown frameworks receive generic Node.js checks and explicit reduced-coverage status.

Invocation Rules

Invoke this skill when the request asks for any of the following:

• A complete, full-stack, security, quality, release, or health audit.
• A coordinated audit across a repository, workspace, monorepo, or services.
• A profile-driven run such as local-fast, pull-request, scheduled-deep, or release.
• Consolidated reports, a health score, an executive summary, history comparison, or repair context that depends on several audit modules.

Do not invoke it for one narrow task such as scan dependencies, find secrets, or review a Dockerfile; invoke that specialist skill directly. Do not begin a dynamic scan, build, deploy, load test, or repair merely because this skill was invoked. The plan must establish applicability, authority, and prerequisites first.

Preconditions

• The requester has identified a repository or working directory that may be read.
• The agent can write only to the approved report/artifact location when artifact generation is requested.
• The request identifies an audit profile or permits the safe default profile defined in Audit Profiles.
• Dynamic targets, if any, are explicitly authorized as non-production and include an owner, base URL, time limit, rate limit, and stop condition.
• Required credentials, tokens, and network access are available through approved secret handling; missing credentials are recorded, never requested in a report.
• No unresolved request asks the agent to auto-fix dependencies, delete files, deploy software, or expose secrets.

Inputs

Accept a validated AuditRequest conforming to Audit Request Schema. At minimum it contains the repository root or roots and requested profile. When available, also accept:

• Service selectors, include/exclude paths, and a monorepo strategy.
• Audit mode: local-fast, pre-commit, pull-request, scheduled-deep, or release.
• Approved report root and retention environment.
• Baseline run identifier or comparison policy.
• Tool allowlist, time budget, concurrency cap, and offline/network policy.
• Non-production dynamic-target authorization and safety limits.
• Declared quality thresholds or explicitly approved overrides.

Treat missing optional data according to Common Rules, recording each default in the run manifest.

Outputs

Produce the following governed artifacts, all linked by the run identifier:

• ProjectManifest and CapabilityProfile from the discovery and detection skills.
• AuditPlan conforming to Audit Plan Schema.
• Run manifest with request digest, profile, policy version, timestamps, service inventory, planned checks, and authority decisions.
• ToolRun index conforming to Tool Run Schema, including status and artifact references for every planned check.
• Coverage summary identifying completed, skipped, blocked, unavailable, and failed checks by service and category.
• Dispatch inputs for finding intelligence, health scoring, report comparison, repair planning, report generation, and CI/CD integration when requested.

The coordinator may emit a Markdown execution summary, but it must not claim a security conclusion before finding intelligence and health scoring complete.

Execution Workflow

1. Validate the request, resolve repository roots without traversing outside them, select the profile, and allocate a UTC timestamp plus collision-safe short run ID.
2. Create the immutable run manifest with status in_progress. Record assumptions, requested scope, policy versions, report root, and safety authority before executing a check.
3. Invoke Project Discovery for each root. If it finds multiple services or workspaces, preserve service boundaries; never collapse their findings into one anonymous project.
4. Invoke Framework Detection using the discovery manifest. Merge only evidence-backed capabilities into the CapabilityProfile.
5. Invoke Execution Preflight. Incorporate tool availability, credentials, target authorization, write authority, and resource limits into the plan.
6. Evaluate Applicability Matrix and Decision Engine per service. Mark every inapplicable check not_applicable and every forbidden check skipped_by_policy with a reason.
7. Build an ordered AuditPlan. Run independent read-only evidence skills in parallel only when their file access, target use, tool cache, and resource budgets do not conflict. Preserve the required dependency order: discovery, detection, preflight, evidence collection, finding intelligence, scoring/comparison/repair planning, rendering, then CI/CD handoff.
8. Dispatch evidence owners: static analysis, quality and test assessment, frontend audit, backend audit, dependency security, secret scanning, container security, API security, runtime analysis, and performance testing. Each must return ToolRun records and raw artifact references.
9. Update the manifest immediately after each result. A tool that reports findings is completed_with_findings, not failed. A failed command, timeout, missing executable, denied credential, or unauthorized target receives its distinct status and reason.
10. Invoke Finding Intelligence only after all reachable evidence owners have returned or their time budgets expire. Do not score raw, duplicate, or unredacted scanner output.
11. Invoke Health Scoring. If a compatible baseline exists and comparison is requested, invoke Report Comparison before final rendering.
12. Invoke Repair Planning when findings need remediation context (fix-context.md). Then invoke Report Generation to render immutable artifacts and AI-ready Markdown summaries.
13. Mark the run completed only when all planned checks have terminal statuses and required summary artifacts exist. Mark it completed_with_limitations if required coverage is blocked, unavailable, failed, or timed out. Retain the immutable manifest even when the run cannot complete.

Decision Tree

1. Is the request valid and the root readable?
   • No: create no audit artifacts outside the approved location; return a blocked intake result with the exact missing input.
   • Yes: create the run manifest.
2. Does discovery find a Node package manifest or a declared Node service?
   • No: finish with not_applicable for Node-specific checks and a clear reduced-scope summary.
   • Yes: detect frameworks and workspaces.
3. Is a check applicable according to detected evidence?
   • No: mark not_applicable with the rule and evidence.
   • Yes: continue.
4. Does preflight authorize and prepare the check?
   • No authority: mark skipped_by_policy or blocked.
   • Missing tool or credential: mark unavailable or blocked.
   • Yes: dispatch its owning skill.
5. Did the specialist return parseable evidence?
   • Yes: send it to finding intelligence.
   • No findings but successful execution: record passed.
   • Findings present: record completed_with_findings.
   • Command failure: record failed or timed_out; do not infer a pass.
6. Are all mandatory profile checks terminal?
   • No: wait only within the budget; then finalize limitations.
   • Yes: normalize, score, compare if eligible, plan repairs, and render.
7. Does a hard release gate fail?
   • Yes: report not_release_ready even if the numerical score is high.
   • No: report the score and readiness decision defined by the scoring skill.

Validation Rules

• Validate every input and output against its published JSON schema before handing it to another skill.
• Use UTC ISO 8601 timestamps, stable service IDs, and unique run IDs.
• A planned check must have exactly one terminal status and a non-empty reason when that status is not passed or completed_with_findings.
• A ToolRun must retain the owning skill, tool version when known, redacted command, start/end times, exit state, and artifact references.
• Require a ProjectManifest, CapabilityProfile, AuditPlan, ToolRun index, normalized findings, health score, and summary report for a complete full-audit profile.
• Validate that report paths remain under the approved report root and that reports contain no raw secret values.
• Reject a plan that runs ZAP, k6, Clinic, deployment, or image execution without documented safety authority.

Error Handling

• Invalid request: stop before execution and return validation errors with supported input examples.
• Missing manifest: mark Node-specific work not_applicable; do not fabricate a project type.
• Ambiguous workspace layout: retain each candidate service as unconfirmed, run only root-safe checks, and flag discovery limitations.
• Tool unavailable: record unavailable with install guidance in the tool run; do not install globally or mutate package manifests.
• Credential or network denial: record blocked with the capability requested, never the credential value.
• Command timeout: record timed_out, preserve partial redacted artifacts, and avoid automatic unbounded retry.
• Malformed tool output: record failed parsing separately from tool execution, attach the safely retained raw artifact, and exclude it from confidence credits.
• Downstream rendering failure: preserve normalized evidence and score, mark report generation failed, and return artifact paths that remain valid.

Success Criteria

• The run has a valid manifest, plan, terminal status for every planned check, and an explicit coverage summary.
• Applicable checks were delegated to their owning skills under safe preconditions.
• No skipped, blocked, unavailable, failed, or timed-out work is represented as a pass.
• Findings are normalized and redacted before scoring and rendering.
• Required profile artifacts and readiness decision are generated or explicitly marked unavailable with a reason.

Failure Criteria

• The agent scans without a run manifest, bypasses preflight, or substitutes its own conclusion for an owning specialist skill.
• The plan performs an unauthorized dynamic action, mutates the project, or writes outside the approved artifact root.
• Check statuses, service identity, timestamps, or tool provenance are absent or contradictory.
• A final report claims full coverage despite missing mandatory checks.
• Raw secrets, access tokens, private URLs, or unredacted sensitive request bodies reach persisted artifacts.

Constraints

• Default to read-only audit behavior. Never run package repair, format-write, database migration, deployment, global install, or destructive cleanup.
• Do not alter severity, score, or finding content; route those decisions to the intelligence skills.
• Do not broaden a dynamic target from the request. Production targets are prohibited unless a separately approved policy explicitly permits them.
• Respect declared time, concurrency, rate, CPU, memory, and network budgets.
• Use relative artifact paths in contracts and immutable timestamped output directories as defined in Report Layout and Retention.

Best Practices

• Start every run with a narrow, explicit profile; use scheduled-deep for expensive and dynamic checks rather than surprising a developer locally.
• Keep service findings separate until global rollup so ownership and remediation stay clear.
• Run independent static, dependency, and secret checks concurrently only after preflight confirms that concurrency is safe.
• Preserve raw scanner evidence alongside normalized findings for auditability, while redacting sensitive values before persistence.
• Treat capability gaps as useful evidence: report them prominently and use them to reduce confidence rather than hiding them.
• Reuse a single run ID across all artifacts and keep prior runs immutable.

Related Skills

• Project Discovery identifies roots, services, manifests, and repository topology.
• Framework Detection emits evidence-backed capabilities and applicable commands.
• Execution Preflight verifies safe, authorized execution conditions.
• Finding Intelligence normalizes and correlates evidence.
• Health Scoring owns score arithmetic and release-readiness gates.
• Report Generation owns persisted report rendering and redaction validation.

Examples

Release audit for a monorepo

Request: Audit the repository for release readiness, generate reports under the approved artifact directory, compare with the previous release run, and test only the documented staging API.

Behavior: create one run manifest; discover each workspace; detect which are React, Next.js, Express, NestJS, and Docker services; preflight all tools and the staging target; dispatch applicable evidence skills by service; normalize results; compare compatible history; calculate hard gates and score; generate service and global reports; create repair context; then produce proposed CI gates. An unavailable Snyk credential remains unavailable and reduces completeness; it is never shown as a clean dependency result.

Local pull-request audit without a dynamic target

Request: Run the pull-request profile for the changed Node service and provide an AI-ready Markdown report.

Behavior: select changed services from discovery, run static, test, dependency, secret, and configuration checks allowed by the profile, mark API/runtime/k6 checks skipped_by_policy because no authorized non-production target exists, then generate the normalized report, score, and repair context. The summary states that dynamic coverage was intentionally absent.

Version

1.0.0