repo-agent-brief 0.2.1 → 0.3.0

package/README.md

@@ -15,6 +15,7 @@ npx repo-agent-brief
 - Finds high-signal files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.
 - Infers stack and common commands.
 - Builds a compact repo map.
+- Suggests a prioritized verification plan (`must` / `should` / `optional`) from detected scripts, risks, and changed files.
 - Optionally summarizes the current git diff so agents can start from “what changed?” instead of rereading the whole repo.
 - Scans context files for obvious secrets and risky operational instructions.
 - Emits Markdown for humans/agents or JSON for automation.
@@ -65,6 +66,19 @@ agent-brief . --diff origin/main > AGENT_HANDOFF.md
 
 The brief adds a `Git diff` section with changed paths, line counts, and warnings for high-impact files such as GitHub Actions workflows, deploy scripts, migrations, Docker Compose files, and lockfiles. This keeps the first agent turn grounded in the actual patch instead of a vague repo overview.
 
+## Verification plans
+
+Every brief now includes a `Suggested verification plan` section. It turns discovered scripts plus patch context into a short checklist an agent can follow before finalizing:
+
+```markdown
+## Suggested verification plan
+- [must] Run type checks for changed code paths — `npm run typecheck`
+- [should] Run lint for fast static feedback — `npm run lint`
+- [must] Run the primary test suite before final handoff — `npm run test`
+```
+
+If you pass `--diff`, the plan gets sharper: docs-only changes downgrade expensive checks, source changes promote tests/typechecks, and CI/deploy/infra/lockfile changes add a manual high-impact-path review. If no test/lint/build commands are found, the plan calls that gap out plainly so the agent does not pretend verification happened.
+
 ## Why this exists
 
 The current agent tooling boom has plenty of orchestration, MCP servers, and observability dashboards. The missing small thing is a cheap, local preflight that gives any agent the same crisp project orientation before it spends tokens or touches files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-agent-brief",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Generate concise, safety-aware project briefs for coding agents.",
   "type": "module",
   "bin": {

package/src/index.js

@@ -44,6 +44,7 @@ export function generateBrief(root = process.cwd(), options = {}) {
   const risks = scanRisks(absRoot, context.files);
   const commands = inferCommands(absRoot, packageInfo);
   const stack = inferStack(absRoot, packageInfo);
+  const verificationPlan = inferVerificationPlan({ commands, diff, risks });
   const score = scoreRepo({ context, commands, risks });
 
   return {
@@ -55,6 +56,7 @@ export function generateBrief(root = process.cwd(), options = {}) {
     diff,
     stack,
     commands,
+    verificationPlan,
     contextFiles: context.files,
     tree,
     risks,
@@ -83,6 +85,17 @@ export function formatMarkdown(brief) {
   }
   lines.push('');
 
+  lines.push('## Suggested verification plan');
+  if (brief.verificationPlan.length) {
+    for (const step of brief.verificationPlan) {
+      const command = step.command ? ` — \`${step.command}\`` : '';
+      lines.push(`- [${step.priority}] ${step.reason}${command}`);
+    }
+  } else {
+    lines.push('- No automatic verification plan could be inferred. Add test/lint/build scripts for better agent handoffs.');
+  }
+  lines.push('');
+
   if (brief.diff) {
     lines.push(`## Git diff vs ${brief.diff.ref}`);
     if (brief.diff.available) {
@@ -295,6 +308,40 @@ function inferCommands(root, pkg) {
   return dedupe(commands, c => c.command);
 }
 
+function inferVerificationPlan({ commands, diff, risks }) {
+  const plan = [];
+  const byName = new Map(commands.map(command => [command.name, command]));
+  const add = (priority, reason, command) => {
+    if (command && plan.some(step => step.command === command.command)) return;
+    plan.push({ priority, reason, command: command?.command || '' });
+  };
+
+  if (risks.some(r => r.severity === 'high')) {
+    add('must', 'Manually inspect high-severity risk matches before sharing output or committing changes');
+  }
+
+  const changedPaths = diff?.available ? diff.files.map(file => file.path) : [];
+  const onlyDocsChanged = changedPaths.length > 0 && changedPaths.every(path => /(^|\/)(README|CHANGELOG|AGENTS|CLAUDE|GEMINI)\.md$|\.md$/i.test(path));
+  const changedPackageOrLock = changedPaths.some(path => /(^|\/)(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/i.test(path));
+  const changedSource = changedPaths.some(path => /(^|\/)(src|lib|app|pages|components|test|tests|spec)\//i.test(path) || /\.(?:[cm]?[jt]sx?|tsx?|py|rs|go)$/i.test(path));
+  const changedCiOrDeploy = changedPaths.some(isRiskyChangedPath);
+
+  if (changedCiOrDeploy) add('must', 'Review high-impact changed paths such as CI, deploy, infra, lockfiles, or migrations');
+  if (changedPackageOrLock) add('should', 'Inspect dependency or package metadata changes before publishing/merging');
+
+  if (byName.has('typecheck')) add(changedSource ? 'must' : 'should', 'Run type checks for changed code paths', byName.get('typecheck'));
+  if (byName.has('lint')) add(changedSource ? 'should' : 'optional', 'Run lint for fast static feedback', byName.get('lint'));
+  if (byName.has('test')) add(changedSource || !onlyDocsChanged ? 'must' : 'optional', 'Run the primary test suite before final handoff', byName.get('test'));
+  if (byName.has('build')) add(changedSource || changedPackageOrLock ? 'should' : 'optional', 'Run a production build if behavior or packaging changed', byName.get('build'));
+
+  if (!commands.some(c => ['test', 'lint', 'typecheck', 'build'].includes(c.name))) {
+    add('should', 'No test/lint/build commands were detected; do a focused manual smoke check and document the gap');
+  }
+
+  if (!diff) add('optional', 'Run with --diff origin/main or --diff HEAD to tailor this plan to the current patch');
+  return plan;
+}
+
 function inferStack(root, pkg) {
   const stack = [];
   if (pkg) {