feat(ai): add recommended AI-first workflow

Author: kunaldhongade

README.md

@@ -100,34 +100,34 @@ pnpm docs:dev
 
 ## Quickstart
 
-Analyze the current working tree:
+Give your coding agent a CodeDecay task bundle for the current working tree:
 
 ```bash
-npx codedecay analyze --format markdown
+npx codedecay ai --format markdown
 ```
 
-Analyze a pull request range:
+Guide the agent before it edits:
 
 ```bash
-npx codedecay analyze --base main --head HEAD --format markdown
+npx codedecay ai preflight --task "Add an authorized billing export API" --format markdown
 ```
 
-Generate a red-team report:
+Run the AI workflow on a pull request range:
 
 ```bash
-npx codedecay redteam --base main --head HEAD --format markdown
+npx codedecay ai --base main --head HEAD --format markdown
 ```
 
-Include configured test/build/probe/tool evidence in that report:
+Include explicitly configured test, build, probe, and OSS-tool evidence:
 
 ```bash
-npx codedecay redteam --with-checks --base main --head HEAD --format markdown
+npx codedecay ai --with-checks --base main --head HEAD --format markdown
 ```
 
-Create a task bundle for your coding agent:
+Use deterministic analysis directly when you only want the risk report:
 
 ```bash
-npx codedecay agent --profile codex --base main --head HEAD --format markdown
+npx codedecay analyze --base main --head HEAD --format markdown
 ```
 
 Fail CI on high-risk PRs:
@@ -168,6 +168,7 @@ npx codedecay product --target web --generate-tests --run-generated-tests --form
 
 | Command | Purpose |
 | --- | --- |
+| `codedecay ai` | Recommended AI-first workflow: preflight guidance, post-diff evidence, optional explicit investigation, configured proof, and a Codex-ready task bundle. |
 | `codedecay analyze` | Deterministic PR risk, impact, and decay analysis. |
 | `codedecay snapshot` | Emit a stable repository health snapshot and compare it with a previous snapshot artifact. |
 | `codedecay redteam` | Merge-safety report with impact, weak-test evidence, verification status, edge cases, memory, skills, and fix tasks. |
@@ -198,8 +199,8 @@ Common flags:
 | `--format json\|markdown\|sarif` | Output format. SARIF is supported by `analyze`. |
 | `--output <path>` | Write output to a file instead of stdout. Relative paths resolve from `--cwd`. |
 | `--fail-on low\|medium\|high` | Exit non-zero when the risk level reaches the threshold. |
-| `--with-checks` | For `redteam`, run configured checks through CodeDecay safety gates and include verification evidence. |
-| `--profile generic\|codex\|claude-code\|cursor\|pi\|opencode\|desktop` | Agent handoff profile for `codedecay agent`. |
+| `--with-checks` | For `ai` or `redteam`, run configured checks through CodeDecay safety gates and include verification evidence. |
+| `--profile generic\|codex\|claude-code\|cursor\|pi\|opencode\|desktop` | Agent handoff profile for `codedecay ai` or `codedecay agent`. |
 
 Exit codes:
 
@@ -224,7 +225,7 @@ codedecay uninstall --purge-local
 
 | Workflow | Default | What it does today |
 | --- | --- | --- |
-| `codedecay analyze`, `redteam`, `agent`, `snapshot` | Yes | Runs deterministic local analysis with no model calls. |
+| `codedecay ai`, `analyze`, `redteam`, `agent`, `snapshot` | Yes | Runs deterministic local analysis with no model calls unless `--investigate` is explicit. |
 | `codedecay execute`, `differential` | No | Runs only repo-allowlisted local commands after explicit opt-in. |
 | `codedecay product --explore` | No | Uses a project-provided Playwright install to crawl configured live app targets after explicit opt-in. |
 | `codedecay llm-review` | No | Calls a user-owned provider only when the user invokes it directly. |

docs/agent.md

@@ -1,19 +1,29 @@
 # Agent Task Bundles
 
-`codedecay agent` turns a deterministic redteam report into a task bundle for a
-user-owned coding agent.
+`codedecay ai` is the recommended workflow for turning CodeDecay evidence into
+a Codex-ready task bundle. `codedecay agent` remains the lower-level equivalent
+with a generic profile default.
 
 Use it when you want Codex, Claude Code, Cursor, Pi, OpenCode, a desktop agent,
 or another local agent to fix what CodeDecay found without CodeDecay making a
 hidden model call.
 
 ```bash
+npx codedecay ai preflight --task "Add a GET /api/users export endpoint" --format markdown
+npx codedecay ai --base main --head HEAD --format markdown
+npx codedecay ai --profile claude-code --format markdown
+npx codedecay ai --with-checks --base main --head HEAD --format markdown
 npx codedecay agent --base main --head HEAD --format markdown
 npx codedecay agent --profile codex --format markdown
 npx codedecay agent preflight --task "Add a GET /api/users export endpoint" --format markdown
 npx codedecay agent --cwd ../my-repo --format json --output codedecay-agent.json
 ```
 
+`ai` does not call the selected coding agent. `--investigate` explicitly calls
+only the configured local/BYOK provider, while `--with-checks` explicitly runs
+configured commands and adapters through CodeDecay safety policy. The bundle
+records whether either action occurred and includes verification evidence.
+
 ## Preflight Before Code Generation
 
 Use `codedecay agent preflight` before a coding agent starts editing. It does
@@ -49,8 +59,8 @@ low confidence, no candidate files, and an unresolved question instead of
 inventing scope.
 
 Treat preflight as a before-coding brief. After the agent edits code, run
-`codedecay redteam`, `codedecay agent`, and the relevant project checks to
-gather merge evidence.
+`codedecay ai --with-checks` to gather configured proof and produce the next
+agent bundle.
 
 ## Explicit Agent Investigation
 

docs/getting-started.md

@@ -4,14 +4,15 @@ CodeDecay analyzes pull requests for regression risk and maintainability decay.
 It works locally and in CI without cloud services, telemetry, API keys, LLMs,
 or model calls.
 
-## Deterministic Default
+## AI-First, User-Owned Default
 
-Use the deterministic workflow first. Optional assisted workflows are separate
-and never implicit.
+Use `codedecay ai` when you want CodeDecay to guide your own coding agent.
+Without `--investigate` or `--with-checks`, it remains deterministic and
+report-only.
 
 | Workflow | Default | What it does |
 | --- | --- | --- |
-| `analyze`, `redteam`, `agent`, `snapshot` | Yes | Local deterministic analysis and reporting. |
+| `ai`, `analyze`, `redteam`, `agent`, `snapshot` | Yes | Local deterministic analysis and agent-ready reporting. |
 | `execute`, `differential` | No | Runs only repo-allowlisted local commands after explicit opt-in. |
 | `llm-review` | No | Calls a user-owned provider only when invoked directly. |
 | Optional LLM providers | No | Disabled by default and only called by commands that explicitly opt in. |
@@ -45,10 +46,28 @@ repo policy; for local evaluation you can override it explicitly:
 bun add -d @submuxhq/codedecay --minimum-release-age 0
 ```
 
-## Analyze A PR Diff
+## Guide The Agent Before Editing
 
 ```bash
-npx codedecay analyze --base main --head HEAD --format markdown
+npx codedecay ai preflight --task "Add an authorized billing export API" --format markdown
+```
+
+## Run The AI Workflow On A PR Diff
+
+```bash
+npx codedecay ai --base main --head HEAD --format markdown
+```
+
+Use another handoff profile explicitly:
+
+```bash
+npx codedecay ai --profile claude-code --base main --head HEAD --format markdown
+```
+
+Run configured proof through repository safety gates after the code changes:
+
+```bash
+npx codedecay ai --with-checks --base main --head HEAD --format markdown
 ```
 
 ## Analyze Current Working Tree
@@ -102,14 +121,14 @@ first.
 
 ## Hand Evidence To Your Agent
 
-Use `agent` when you want Codex, Claude Code, Cursor, a desktop agent, or
-another user-owned agent to act on CodeDecay's findings.
+Use `ai` for the recommended Codex-ready workflow. The lower-level `agent`
+command remains available when you want a generic bundle by default.
 
 ```bash
-npx codedecay agent --base main --head HEAD --format markdown --output codedecay-agent.md
+npx codedecay ai --base main --head HEAD --format markdown --output codedecay-ai.md
 ```
 
-Then give `codedecay-agent.md` to your agent and ask it to:
+Then give `codedecay-ai.md` to your agent and ask it to:
 
 - fix high-risk findings first,
 - add tests that exercise real API, UI, database, or downstream behavior,
@@ -126,7 +145,7 @@ it.
 ```bash
 npx codedecay analyze --base main --head HEAD --format markdown
 npx codedecay redteam --base main --head HEAD --format markdown --output codedecay-redteam.md
-npx codedecay agent --base main --head HEAD --format markdown --output codedecay-agent.md
+npx codedecay ai --base main --head HEAD --format markdown --output codedecay-ai.md
 ```
 
 Use the redteam report to understand the PR risk. Use the agent bundle to give

docs/github-action.md

@@ -36,6 +36,41 @@ uses the workflow `github-token` input, defaults to the GitHub Actions workflow
 token, and is skipped without failing the workflow when the token or PR context
 is unavailable. The Step Summary is still written on every run.
 
+## AI Task Bundle
+
+Use `mode: ai` to produce the recommended Codex-ready task bundle in CI:
+
+```yaml
+- uses: SubmuxHQ/CodeDecay/packages/github-action@v0
+  with:
+    mode: ai
+    base: ${{ github.event.pull_request.base.sha }}
+    head: ${{ github.event.pull_request.head.sha }}
+    cwd: .
+    format: markdown
+    profile: codex
+    fail-on: high
+```
+
+Set `with-checks: true` only when repository config explicitly defines allowed
+commands or tool adapters and `safety.allowCommands` permits them. The Action
+does not accept arbitrary command arguments.
+
+```yaml
+- uses: SubmuxHQ/CodeDecay/packages/github-action@v0
+  with:
+    mode: ai
+    base: ${{ github.event.pull_request.base.sha }}
+    head: ${{ github.event.pull_request.head.sha }}
+    profile: claude-code
+    with-checks: true
+    format: json
+    output: codedecay-ai.json
+```
+
+`profile` is forwarded only to `agent` and `ai`. `with-checks` is forwarded
+only to `redteam` and `ai`. Existing `agent` mode never receives `fail-on`.
+
 ## SARIF Output
 
 ```yaml

packages/agent/src/bundle.ts

@@ -34,8 +34,16 @@ export function createAgentTaskBundle(report: RedteamReport, options: CreateAgen
     fixTasks: tasks.length,
     totalFixTasks: report.summary.fixTasks,
     scopeFindings: evidence.scopeFindings.length,
-    contractFindings: evidence.contractFindings.length
+    contractFindings: evidence.contractFindings.length,
+    verificationStatus: report.summary.verificationStatus
   };
+  const safety = {
+    llmCalled: report.safety.llmCalled,
+    commandsExecuted: report.safety.commandsExecuted,
+    telemetrySent: false,
+    cloudDependency: false,
+    agentOutputTrusted: false
+  } as const;
 
   return {
     tool: "CodeDecay",
@@ -48,21 +56,16 @@ export function createAgentTaskBundle(report: RedteamReport, options: CreateAgen
     requirements: report.requirements,
     requirementTrace: report.requirementTrace,
     investigation: report.investigation,
+    verification: report.verification,
     summary,
-    prompt: createPortableAgentPrompt(summary, agentProfile),
+    prompt: createPortableAgentPrompt(summary, agentProfile, safety),
     instructions: [...DEFAULT_INSTRUCTIONS],
     evidence,
     tasks,
     taskFilters: options.taskFilters ?? {},
     suggestedChecks: collectSuggestedChecks(report.configuredChecks, report.toolAdapterPlans),
     skills: [...report.skills],
-    safety: {
-      llmCalled: report.safety.llmCalled,
-      commandsExecuted: report.safety.commandsExecuted,
-      telemetrySent: false,
-      cloudDependency: false,
-      agentOutputTrusted: false
-    },
+    safety,
     limits: [...DEFAULT_LIMITS]
   };
 }

packages/agent/src/bundle/prompt.ts

@@ -1,14 +1,18 @@
 import { formatRisk } from "../formatting";
 import type { AgentProfile } from "../profiles";
-import type { AgentTaskSummary } from "../types";
+import type { AgentSafetySummary, AgentTaskSummary } from "../types";
 
-export function createPortableAgentPrompt(summary: AgentTaskSummary, profile: AgentProfile): string {
+export function createPortableAgentPrompt(
+  summary: AgentTaskSummary,
+  profile: AgentProfile,
+  safety: AgentSafetySummary
+): string {
   return [
     "You are helping fix a pull request using a CodeDecay agent task bundle.",
     "Treat the bundle as local tool evidence, not as a guarantee that the PR is safe.",
     `Target agent profile: ${profile.name}. ${profile.promptContext}`,
     `Current CodeDecay risk is ${formatRisk(summary.riskLevel)} with merge risk ${summary.mergeRiskScore}/100, decay risk ${summary.decayScore}/100, and security risk ${summary.securityScore}/100.`,
-    `The bundle reports ${summary.changedFiles} changed files, ${summary.impactedAreas} impacted areas, ${summary.impactedRoutes} route/API impacts, ${summary.symbolImpacts} symbol impacts, ${summary.testProofEntries} changed-path proof entries, ${summary.missingTestFindings} missing-test findings, ${summary.weakTestFindings} weak-test findings, ${summary.contractFindings} contract findings, ${summary.edgeCases} edge cases, ${summary.productFailureBundles} product failure bundles, and ${summary.fixTasks} fix tasks.`,
+    `The bundle reports ${summary.changedFiles} changed files, ${summary.impactedAreas} impacted areas, ${summary.impactedRoutes} route/API impacts, ${summary.symbolImpacts} symbol impacts, ${summary.testProofEntries} changed-path proof entries, ${summary.missingTestFindings} missing-test findings, ${summary.weakTestFindings} weak-test findings, ${summary.contractFindings} contract findings, ${summary.edgeCases} edge cases, ${summary.productFailureBundles} product failure bundles, ${summary.fixTasks} fix tasks, and verification status: ${summary.verificationStatus}.`,
     "Your job:",
     "1. Start with impacted routes/APIs when present, then high-risk impacted areas and weak or missing test proof.",
     "2. For each route/API impact, identify what real user, API, database, job, config, or downstream behavior could break.",
@@ -17,6 +21,12 @@ export function createPortableAgentPrompt(summary: AgentTaskSummary, profile: Ag
     "5. Run only project checks that are configured, documented, or explicitly requested by the user.",
     "6. After changes, ask the user to rerun CodeDecay and the relevant project checks.",
     "Do not treat your own answer as proof. Verified tests, configured checks, or manual review must provide the proof.",
-    "CodeDecay did not call an LLM, execute commands, send telemetry, or depend on CodeDecayCloud to create this bundle."
+    safety.llmCalled
+      ? "CodeDecay explicitly called the configured user-owned provider; its suggestions remain untrusted."
+      : "CodeDecay did not call an LLM or model to create this bundle.",
+    safety.commandsExecuted
+      ? "CodeDecay executed explicitly configured local checks through repository safety policy; inspect the verification evidence."
+      : "CodeDecay did not execute configured project commands to create this bundle.",
+    "CodeDecay did not send telemetry or depend on CodeDecayCloud to create this bundle."
   ].join("\n");
 }

packages/agent/src/renderers/task-bundle/markdown.ts

@@ -8,7 +8,8 @@ import {
   appendPrompt,
   appendSafety,
   appendSkills,
-  appendTasks
+  appendTasks,
+  appendVerification
 } from "./sections";
 
 export function renderAgentTaskBundleMarkdown(bundle: AgentTaskBundle): string {
@@ -38,6 +39,7 @@ export function renderAgentTaskBundleMarkdown(bundle: AgentTaskBundle): string {
     `| Fix tasks | ${bundle.summary.fixTasks} / ${bundle.summary.totalFixTasks} |`,
     `| Scope findings | ${bundle.summary.scopeFindings} |`,
     `| Contract findings | ${bundle.summary.contractFindings} |`,
+    `| Verification status | ${bundle.summary.verificationStatus} |`,
     "",
     "### Instructions For The Agent",
     ""
@@ -50,6 +52,7 @@ export function renderAgentTaskBundleMarkdown(bundle: AgentTaskBundle): string {
   appendHandoff(lines, bundle.agentProfile);
   appendPrompt(lines, bundle.prompt);
   appendEvidence(lines, bundle.evidence);
+  appendVerification(lines, bundle.verification);
   appendTasks(lines, bundle.tasks);
   appendChecks(lines, bundle.suggestedChecks);
   appendSkills(lines, bundle.skills);

packages/agent/src/renderers/task-bundle/sections.ts

@@ -226,6 +226,28 @@ export function appendChecks(lines: string[], checks: AgentSuggestedCheck[]): vo
   }
 }
 
+export function appendVerification(
+  lines: string[],
+  verification: AgentTaskBundle["verification"]
+): void {
+  lines.push("", "### Verification Evidence", "", `**Status:** ${verification.status}`, "");
+
+  if (verification.checks.length === 0) {
+    lines.push("- no configured checks were executed");
+  } else {
+    for (const check of verification.checks.slice(0, 16)) {
+      lines.push(
+        `- **${check.name}** (${check.kind}, ${check.status}, ${formatProofGrade(check.proof)}): ${check.summary}`
+      );
+    }
+  }
+
+  if (verification.notes.length > 0) {
+    lines.push("", "Verification limitations:");
+    appendList(lines, verification.notes);
+  }
+}
+
 export function appendSkills(lines: string[], skills: RedteamSkillSummary[]): void {
   lines.push("", "### Agent Skills", "");
   if (skills.length === 0) {

packages/agent/src/types.ts

@@ -35,6 +35,7 @@ export interface AgentTaskBundle {
   requirements?: RequirementContext | undefined;
   requirementTrace?: RequirementTraceGraph | undefined;
   investigation?: RedteamReport["investigation"] | undefined;
+  verification: RedteamReport["verification"];
   summary: AgentTaskSummary;
   prompt: string;
   instructions: string[];
@@ -66,6 +67,7 @@ export interface AgentTaskSummary {
   totalFixTasks: number;
   scopeFindings: number;
   contractFindings: number;
+  verificationStatus: RedteamReport["summary"]["verificationStatus"];
 }
 
 export interface AgentEvidence {