repo-agent-brief 0.2.1 → 0.4.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.
@@ -44,6 +45,7 @@ Options:
 - `--max-file-bytes N` — max bytes to read per context file. Default: `12000`.
 - `--no-snippets` — omit source snippets.
 - `--diff [ref]` — include changed files, insertions/deletions, and high-impact path warnings versus a git ref. Defaults to `HEAD` when no ref is provided.
+- `--bundle [dir]` — write a durable handoff bundle with `brief.md`, `brief.json`, and `verification.md`. Default: `.agent-brief`.
 - `--fail-on-high-risk` — exit `2` if high-severity risk patterns are found.
 
 Examples:
@@ -52,6 +54,7 @@ Examples:
 agent-brief . > AGENT_BRIEF.md
 agent-brief ~/dev/my-app --format json
 agent-brief . --diff origin/main
+agent-brief . --diff HEAD --bundle
 agent-brief . --fail-on-high-risk
 ```
 
@@ -65,6 +68,39 @@ 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.
+
+## Handoff bundles
+
+For longer-running work, use `--bundle` to leave a stable artifact another agent or human can inspect later:
+
+```bash
+agent-brief . --diff HEAD --bundle
+```
+
+This writes:
+
+- `.agent-brief/brief.md` — the full human-readable project brief.
+- `.agent-brief/brief.json` — the same data for automation.
+- `.agent-brief/verification.md` — a focused checklist of the exact checks the next agent should run or document.
+
+Use a custom directory when you want to attach the bundle to a ticket, run log, or CI artifact:
+
+```bash
+agent-brief . --diff origin/main --bundle artifacts/agent-brief
+```
+
 ## 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.4.0",
   "description": "Generate concise, safety-aware project briefs for coding agents.",
   "type": "module",
   "bin": {

package/skills/repo-agent-brief/SKILL.md

@@ -29,6 +29,14 @@ For machine-readable automation:
 npx repo-agent-brief . --format json > agent-brief.json
 ```
 
+For durable handoffs:
+
+```bash
+npx repo-agent-brief . --diff HEAD --bundle
+sed -n '1,220p' .agent-brief/brief.md
+sed -n '1,160p' .agent-brief/verification.md
+```
+
 ## When to use
 
 - First pass in an unfamiliar repo.
@@ -48,6 +56,7 @@ npx repo-agent-brief . --format json > agent-brief.json
 ```bash
 npx repo-agent-brief .
 npx repo-agent-brief . --diff HEAD
+npx repo-agent-brief . --diff HEAD --bundle
 npx repo-agent-brief . --diff origin/main --fail-on-high-risk
 npx repo-agent-brief . --no-snippets
 ```

package/src/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { resolve } from 'node:path';
-import { generateBrief, formatJson, formatMarkdown } from './index.js';
+import { generateBrief, formatJson, formatMarkdown, writeBundle } from './index.js';
 
 function parseArgs(argv) {
-  const args = { path: '.', format: 'markdown', maxFileBytes: 12000, noSnippets: false, failOnHighRisk: false, diffRef: null };
+  const args = { path: '.', format: 'markdown', maxFileBytes: 12000, noSnippets: false, failOnHighRisk: false, diffRef: null, bundleDir: null };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--format' || arg === '-f') args.format = argv[++i];
@@ -11,6 +11,7 @@ function parseArgs(argv) {
     else if (arg === '--no-snippets') args.noSnippets = true;
     else if (arg === '--fail-on-high-risk') args.failOnHighRisk = true;
     else if (arg === '--diff') args.diffRef = argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : 'HEAD';
+    else if (arg === '--bundle') args.bundleDir = argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : '.agent-brief';
     else if (arg === '--help' || arg === '-h') args.help = true;
     else if (!arg.startsWith('-')) args.path = arg;
     else throw new Error(`Unknown option: ${arg}`);
@@ -29,13 +30,15 @@ Options:
       --max-file-bytes N       Max bytes to read per context file (default: 12000)
       --no-snippets            Omit context snippets from output
       --diff [ref]             Include changed files vs ref (default: HEAD)
+      --bundle [dir]           Write brief.md, brief.json, and verification.md (default: .agent-brief)
       --fail-on-high-risk      Exit 2 if high-severity risk patterns are found
   -h, --help                   Show help
 
 Examples:
-  npx @builtbyecho/agent-brief
+  npx repo-agent-brief
   agent-brief ~/dev/my-app --format json
   agent-brief . --diff origin/main
+  agent-brief . --diff HEAD --bundle
   agent-brief . --fail-on-high-risk > AGENT_BRIEF.md
 `;
 }
@@ -52,7 +55,15 @@ try {
     includeSnippets: !args.noSnippets,
     diffRef: args.diffRef
   });
-  console.log(args.format === 'json' ? formatJson(brief) : formatMarkdown(brief));
+  if (args.bundleDir) {
+    const files = writeBundle(resolve(args.path), brief, args.bundleDir);
+    console.log(`Agent brief bundle written:
+- Markdown: ${files.markdown}
+- JSON: ${files.json}
+- Verification: ${files.verification}`);
+  } else {
+    console.log(args.format === 'json' ? formatJson(brief) : formatMarkdown(brief));
+  }
   if (args.failOnHighRisk && brief.risks.some(r => r.severity === 'high')) process.exit(2);
 } catch (error) {
   console.error(`agent-brief: ${error.message}`);

package/src/index.js

@@ -1,5 +1,5 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, join, relative } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 const DEFAULT_IGNORES = new Set([
@@ -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) {
@@ -145,6 +158,61 @@ export function formatJson(brief) {
   return JSON.stringify(brief, null, 2);
 }
 
+export function formatVerificationMarkdown(brief) {
+  const lines = [];
+  lines.push(`# Verification Plan: ${brief.project}`);
+  lines.push('');
+  lines.push(`Generated: ${brief.generatedAt}`);
+  if (brief.git.branch || brief.git.status) lines.push(`Git: ${brief.git.branch || 'unknown'}${brief.git.status ? ` - ${brief.git.status}` : ''}`);
+  lines.push('');
+
+  lines.push('## Checklist');
+  if (brief.verificationPlan.length) {
+    for (const step of brief.verificationPlan) {
+      const command = step.command ? `\n  - Command: \`${step.command}\`` : '';
+      lines.push(`- [ ] [${step.priority}] ${step.reason}${command}`);
+    }
+  } else {
+    lines.push('- [ ] Do a focused manual smoke check and document what could not be verified.');
+  }
+  lines.push('');
+
+  if (brief.diff?.available) {
+    lines.push(`## Changed Files vs ${brief.diff.ref}`);
+    if (brief.diff.files.length) {
+      for (const file of brief.diff.files) {
+        lines.push(`- ${file.status} ${file.path}${file.risky ? ' (high-impact)' : ''}`);
+      }
+    } else {
+      lines.push('- No changed files detected.');
+    }
+    lines.push('');
+  }
+
+  lines.push('## Risk Notes');
+  if (brief.risks.length) {
+    for (const risk of brief.risks) lines.push(`- [${risk.severity}] ${risk.path}: ${risk.message}`);
+  } else {
+    lines.push('- No obvious secret/risky-instruction patterns found in scanned context files.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function writeBundle(root, brief, bundleDir = '.agent-brief') {
+  const outDir = resolve(root, bundleDir);
+  mkdirSync(outDir, { recursive: true });
+  const files = {
+    markdown: join(outDir, 'brief.md'),
+    json: join(outDir, 'brief.json'),
+    verification: join(outDir, 'verification.md')
+  };
+  writeFileSync(files.markdown, formatMarkdown(brief));
+  writeFileSync(files.json, `${formatJson(brief)}\n`);
+  writeFileSync(files.verification, formatVerificationMarkdown(brief));
+  return files;
+}
+
 function collectContext(root, opts) {
   const files = [];
   for (const name of CONTEXT_FILES) {
@@ -295,6 +363,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) {