repo-agent-brief 0.3.0 → 0.4.0

package/README.md

@@ -45,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:
@@ -53,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
 ```
 
@@ -79,6 +81,26 @@ Every brief now includes a `Suggested verification plan` section. It turns disco
 
 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.3.0",
+  "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([
@@ -158,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) {