audit-tools 0.28.0

package/skills/remediate-code/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: remediate-code
+description: Conversation-first remediation of audit findings or feedback. Loads one backend-rendered step prompt at a time via remediate-code next-step.
+version: 0.2.0
+---
+
+# remediate-code skill
+
+The canonical entrypoint is `/remediate-code` in conversation.
+
+This skill should be treated as a conversational product surface first.
+
+## Primary contract
+
+Normal usage should:
+
+- run from conversation, not from manual shell arguments
+- avoid manual paths, provider flags, and batching arguments
+- advance the remediation automatically until it completes or no further
+  automatic progress is possible
+
+The backend accepts structured audit reports, feedback documents, and
+conversation-only starting points. Non-structured starts must go through the
+backend-rendered intake brief and clarification steps before normal planning.
+
+Semantic work (documentation, implementation) should be delegated to bounded
+subagents whenever the host can dispatch them. The conversation orchestrator
+owns dispatch and ingestion control; it should not perform broad work itself
+when subagents are available. Entering `/remediate-code` is explicit user
+authorization to fan out those subagents; do not require a separate delegation
+request before parallel dispatch.
+
+If the host cannot delegate to subagents, the conversation orchestrator may
+complete exactly one assigned task, ingest it through the provided backend
+command, then stop so the user can rerun `/remediate-code` from fresh context.
+The backend writes a deterministic single-task fallback prompt for that case so
+the orchestrator does not need to infer the first task from a broad batch prompt.
+
+When dispatch-plan entries include complexity and `model_hint.tier` metadata,
+a capable host may map those tiers to its own subagent models. The backend
+should not prescribe concrete model names.
+
+Bounded steps are a backend implementation detail, not the intended user
+experience.
+
+## Embedded Prompt Payload
+
+The prompt payload in `remediate-code.prompt.md` remains the canonical
+instruction asset.
+
+The intended user setup is one global package install:
+
+```bash
+npm install -g remediator-lambda
+```
+
+That makes `remediate-code` available on `PATH` and seeds user-level
+command/skill assets for hosts the package can safely update. The prompt
+self-bootstraps before advancing the remediation:
+
+```bash
+remediate-code ensure --quiet
+```
+
+That idempotent bootstrap writes host assets (Claude command, Codex skill,
+OpenCode config) only when they are missing or stale.
+
+Use the explicit installer for repair or forced refresh:
+
+```bash
+remediate-code install
+```
+
+Use direct prompt import only when the target host still needs it after
+bootstrap.
+
+## Repo-local fallback
+
+When developing inside the `remediator-lambda` repository itself, prefer:
+
+```bash
+node remediate-code.mjs
+```
+
+That keeps the run pinned to the local wrapper and local `dist/` output instead
+of whichever global `remediate-code` binary happens to be on `PATH`.
+
+## Development rule
+
+Prefer the skill-first conversational contract over the CLI-first backend shape.

package/skills/remediate-code/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "remediate-code"
+  short_description: "Conversation-first remediation workflow that applies one backend-rendered fix at a time."
+  default_prompt: "Start /remediate-code for this repository and continue until all findings are remediated or the workflow blocks for operator input."

package/skills/remediate-code/remediate-code.prompt.md

@@ -0,0 +1,94 @@
+---
+description: Autonomous local-loop remediation - loads one backend-rendered remediation step at a time
+allowed-tools: [Read, Bash, Glob, Grep, Agent]
+---
+
+# `/remediate-code` Loader
+
+You are the remediate-code orchestrator for this conversation. The user-facing
+surface is `/remediate-code`, but the backend owns every remediation workflow
+branch.
+
+## Loader
+
+First, make sure the global host assets are current:
+
+```bash
+remediate-code ensure --quiet
+```
+
+If the user supplied arguments to `/remediate-code`, preserve them as the
+starting point:
+
+- If the argument is an existing path, pass it to the backend with
+  `--input`.
+- If the argument is conversational feedback, write it to a temporary file
+  and pass that file with `--guidance-file <path>` (single-step bootstrap:
+  the backend writes it to intake/conversation-start.md itself, idempotently).
+
+For Claude-style command expansion, the raw user arguments are:
+
+```text
+$ARGUMENTS
+```
+
+Then ask the backend for exactly one next step. If you have a path argument,
+use:
+
+```bash
+remediate-code next-step --input <path>
+```
+
+If you have conversational guidance to pass as a file, use:
+
+```bash
+remediate-code next-step --guidance-file <path-to-guidance-file>
+```
+
+Otherwise use:
+
+```bash
+remediate-code next-step
+```
+
+Every `next-step` call is also the **capability handshake**: report what you can
+dispatch to *right now* so the backend sizes remediation waves and per-worker
+context to your real model instead of a conservative 32k floor. Report:
+
+- `--host-can-dispatch-subagents` / `--host-max-concurrent` — whether you can run
+  callable subagents and how many in parallel. Without them the backend assumes
+  serial dispatch.
+- `--host-models` — an ordered JSON array (lowest rank first) of the models you
+  can dispatch workers to *right now*, one entry per relative rank:
+  `{"rank": "small"|"standard"|"deep", "context_tokens": N, "output_tokens": N}`.
+  Ranks are relative capability labels that line up with each item's
+  `model_hint.tier` — never report model names to the backend. Report only ranks
+  you can actually dispatch to. Each entry may carry an optional opaque
+  `model_id` (and `--host-model-id` is the single-model equivalent) used only to
+  key per-model quota learning — it is never interpreted.
+- `--host-context-tokens` / `--host-output-tokens` — single-model shorthand when
+  every worker runs on one model: the context window and output cap of that
+  model. When `--host-models` is also given, the roster wins. Omit both and
+  dispatch falls back to the conservative 32k default. Use the actual numbers
+  for your dispatch model — discover them, do not guess a smaller-than-real
+  value.
+
+```bash
+remediate-code next-step --input <path> --host-max-concurrent 4 --host-models '[{"rank":"standard","context_tokens":200000,"output_tokens":32000},{"rank":"deep","context_tokens":200000,"output_tokens":64000}]'
+```
+
+Or with a single dispatch model:
+
+```bash
+remediate-code next-step --input <path> --host-max-concurrent 4 --host-context-tokens 200000 --host-output-tokens 32000
+```
+
+Read the returned JSON only far enough to find `prompt_path`, then read and
+follow only that prompt. Do not read dispatch prompts, schemas, state files,
+or result files unless the current step prompt explicitly instructs you to do
+so.
+
+When a step prompt tells you to continue, run `remediate-code next-step` again
+(with the same capability flags) and follow only the newly returned `prompt_path`.
+
+Stop when the current step prompt tells you to stop.

package/templates/AGENTS.remediate-code.md

@@ -0,0 +1,6 @@
+<!-- remediate-code:begin -->
+## /remediate-code
+When the user enters `/remediate-code`, treat it as this repository's autonomous remediation workflow.
+If your host does not automatically register the installed slash command file, load and follow the global `~/.claude/commands/remediate-code.md`.
+Normal usage should stay conversation-first and avoid manual paths, provider flags, or batching arguments.
+<!-- remediate-code:end -->