auditor-lambda

Skill-first audit orchestration backend for the /audit-code product surface.

Canonical Product Route

The primary product is /audit-code in conversation.

Normal product usage should:

• use the active conversation model by default
• use project files and attached repository context by default
• avoid manual paths, provider flags, and model-selection arguments
• keep semantic review with the active conversation agent by default
• advance the audit automatically until it completes or no further automatic progress is possible

Conversation Setup

The canonical asset for editor and conversation integrations is:

skills/audit-code/audit-code.prompt.md

Packaged installs and repository checkouts both ship that prompt asset.

The intended user install is one global tool install:

npm install -g auditor-lambda

That makes audit-code available on PATH. During package install, the package also writes user-level command/skill assets for hosts we can seed safely, including the Claude command file and Codex skill bundle.

After that, invoke /audit-code in a supported host. The prompt self-bootstraps the current repository by running:

audit-code ensure --quiet

That command writes or refreshes the repo-local assets only when they are missing or stale, then normal audit execution continues without manual paths, provider flags, or model-selection arguments.

The explicit repair and compatibility setup path remains:

audit-code install

That bootstraps repo-local /audit-code surfaces for the hosts we can automate today, including:

• Codex skill bundle, AGENTS.md guidance, and MCP setup notes
• Claude Desktop local MCP bundle artifacts and project template guidance
• OpenCode command, skill, and opencode.json surfaces
• VS Code prompt, custom agent, Copilot instructions, and .vscode/mcp.json
• Antigravity planning-mode guidance plus the shared repo-local MCP launcher

audit-code ensure refreshes those files automatically when the packaged prompt or skill changes. Use audit-code install or audit-code ensure --force when you intentionally want to rewrite every generated host surface on demand.

After bootstrap, you can smoke-test the generated host assets and launcher from the repository root:

audit-code verify-install

After that, open a supported conversation surface in the repository and invoke /audit-code.

If a host still needs manual prompt import after bootstrap, open:

.audit-code/install/GETTING-STARTED.md

That repo-local guide now includes dedicated quick-start sections for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity, plus the installed canonical prompt asset path for prompt-import fallback flows.

For narrower compatibility, audit-code install-host --host copilot still exists.

For hosts that still need manual import after bootstrap, or for environments with no repo-local install surface, after installing the package or checking out the repository, use:

audit-code prompt-path

Import the reported file into your editor or conversation environment's custom prompt configuration, then invoke /audit-code in conversation.

Typical examples include custom instructions, .cursorrules, prompt libraries, or comparable editor-specific prompt surfaces.

Repo-Local Backend Fallback

The CLI in this repository is backend infrastructure and a repo-local fallback surface.

From the target repository root:

audit-code

Repository-local equivalent:

node /path/to/auditor-lambda/audit-code.mjs

This wrapper:

• defaults artifacts to <repo-root>/.audit-artifacts
• creates that directory automatically
• auto-builds dist/ if it is missing
• advances fresh worker sessions automatically until the audit completes or the remaining work requires imported results or an interactive provider
• continues through provider-assisted audit review automatically when .audit-artifacts/session-config.json selects an interactive provider bridge
• keeps those provider bridges as fallback compatibility modes rather than the primary product path
• emits contract_version: "audit-code/v1alpha1"
• refreshes .audit-artifacts/operator-handoff.json and .audit-artifacts/operator-handoff.md with suggested evidence-import paths and continuation hints

Explicit root override still exists for callers running from outside the target repository:

audit-code --root /path/to/repo

For one bounded debug step instead of run-to-completion:

audit-code --single-step

For an operator-side artifact consistency check:

audit-code validate

That check now covers the artifact bundle plus session-config.json and explicit provider readiness.

For native batch ingestion of multiple result files:

audit-code --batch-results /path/to/audit-results-dir

For task-to-coverage inspection without reverse-engineering multiple artifacts:

audit-code explain-task <task_id>

For a local stdio MCP server entrypoint:

audit-code mcp

The backend wrapper response schema is schemas/audit-code-v1alpha1.schema.json.

Backend Provider Modes

If provider is omitted, the backend defaults to the safest mode:

{
  "provider": "local-subprocess"
}

If you want best-effort cross-editor or provider routing, opt into:

{
  "provider": "auto",
  "ui_mode": "visible"
}

Optional backend config:

.audit-artifacts/session-config.json

Practical Guidance

• use /audit-code in conversation as the canonical product surface
• install once with npm install -g auditor-lambda, then let /audit-code run audit-code ensure --quiet in each repository
• use audit-code install when you want to repair or force-refresh repo-local host assets
• use audit-code prompt-path to locate the packaged prompt asset
• use audit-code from the repository root only when you need the repo-local backend fallback
• use omitted provider or local-subprocess for the safest deterministic fallback behavior
• use provider: "auto" only when you want best-effort routing across installed backends
• treat explicit provider bridges as compatibility fallback, not as the intended owner of semantic review

Implementation Next Steps

The next implementation work is tracked in:

• docs/next-steps.md

The short version is:

• keep the packet dispatch workflow verified in real host environments
• benchmark /audit-code packet counts and warning counts against nontrivial external repositories
• prove the generated Codex, Claude Desktop, OpenCode, VS Code, and Antigravity guidance in real host flows
• tighten the repo-local MCP-first bootstrap where host smoke tests expose friction
• polish provider-assisted continuation and failure guidance
• finish publish and release hardening for packaged installs

Build And Test

npm install
npm run verify:release
npm run release:patch
npm run release:patch:publish

For GitHub Actions publication and npm Trusted Publishing setup, see docs/releasing.md.

Key Docs

• docs/product-direction.md
• docs/workflow-refactor-brief.md
• docs/remediation-baseline.md
• docs/releasing.md
• docs/production-readiness.md
• docs/production-launch-bar.md
• docs/next-steps.md
• skills/audit-code/SKILL.md
• docs/bootstrap-install.md
• docs/agent-integrations.md
• docs/github-copilot.md
• docs/contract.md
• docs/model-selection.md
• docs/packaging.md
• docs/session-config.md
• docs/supervisor.md
• docs/windows-setup.md