repo-agent-brief 0.1.0 → 0.2.1

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.
+- 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.
 
@@ -42,6 +43,7 @@ Options:
 - `--format markdown|json` / `-f` — output format. Default: `markdown`.
 - `--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.
 - `--fail-on-high-risk` — exit `2` if high-severity risk patterns are found.
 
 Examples:
@@ -49,9 +51,20 @@ Examples:
 ```bash
 agent-brief . > AGENT_BRIEF.md
 agent-brief ~/dev/my-app --format json
+agent-brief . --diff origin/main
 agent-brief . --fail-on-high-risk
 ```
 
+## Diff-aware handoffs
+
+When you are handing an in-progress branch to an agent, run:
+
+```bash
+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.
+
 ## 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.
@@ -63,7 +76,7 @@ This is intentionally zero-dependency and boring. It should be safe to run in al
 ```js
 import { generateBrief, formatMarkdown } from 'repo-agent-brief';
 
-const brief = generateBrief(process.cwd());
+const brief = generateBrief(process.cwd(), { diffRef: 'origin/main' });
 console.log(formatMarkdown(brief));
 ```
 
@@ -74,3 +87,7 @@ This is not a full secret scanner. It catches common token/private-key/secret-as
 ## License
 
 MIT
+
+## Agent Skill
+
+This package includes an OpenClaw/Claude-style skill at `skills/repo-agent-brief` that teaches agents to run repo preflight and diff-aware handoff briefs before editing or reviewing code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-agent-brief",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Generate concise, safety-aware project briefs for coding agents.",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
   "files": [
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills/"
   ],
   "scripts": {
     "test": "node --test",

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

@@ -0,0 +1,53 @@
+---
+name: repo-agent-brief
+description: Generate concise, safety-aware repository orientation briefs with repo-agent-brief/agent-brief before coding-agent work, reviews, handoffs, PR analysis, unfamiliar repo edits, diff-aware branch handoffs, or when an agent needs stack/commands/context/risk signals before changing files.
+---
+
+# Repo Agent Brief Skill
+
+Use `repo-agent-brief` to orient an agent before it edits or reviews a repository. It finds high-signal context files, infers stack/commands, builds a compact repo map, and flags obvious secret/risky-instruction patterns.
+
+## Default workflow
+
+From the repository root:
+
+```bash
+npx repo-agent-brief . > AGENT_BRIEF.md
+sed -n '1,220p' AGENT_BRIEF.md
+```
+
+For in-progress branches:
+
+```bash
+npx repo-agent-brief . --diff origin/main > AGENT_HANDOFF.md
+sed -n '1,260p' AGENT_HANDOFF.md
+```
+
+For machine-readable automation:
+
+```bash
+npx repo-agent-brief . --format json > agent-brief.json
+```
+
+## When to use
+
+- First pass in an unfamiliar repo.
+- Before delegating to a coding agent.
+- PR/branch handoff where changed files matter.
+- Safety preflight before touching CI, migrations, deploy scripts, auth, or config.
+
+## Safety
+
+- This is not a full secret scanner. Use Gitleaks/TruffleHog for full audits.
+- If high-risk patterns are found, inspect before proceeding.
+- Use `--fail-on-high-risk` in CI or strict agent workflows.
+- Generated briefs may include snippets from repo context files; avoid posting publicly without review.
+
+## Useful commands
+
+```bash
+npx repo-agent-brief .
+npx repo-agent-brief . --diff HEAD
+npx repo-agent-brief . --diff origin/main --fail-on-high-risk
+npx repo-agent-brief . --no-snippets
+```

package/src/cli.js

@@ -3,13 +3,14 @@ import { resolve } from 'node:path';
 import { generateBrief, formatJson, formatMarkdown } from './index.js';
 
 function parseArgs(argv) {
-  const args = { path: '.', format: 'markdown', maxFileBytes: 12000, noSnippets: false, failOnHighRisk: false };
+  const args = { path: '.', format: 'markdown', maxFileBytes: 12000, noSnippets: false, failOnHighRisk: false, diffRef: null };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--format' || arg === '-f') args.format = argv[++i];
     else if (arg === '--max-file-bytes') args.maxFileBytes = Number(argv[++i]);
     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 === '--help' || arg === '-h') args.help = true;
     else if (!arg.startsWith('-')) args.path = arg;
     else throw new Error(`Unknown option: ${arg}`);
@@ -27,12 +28,14 @@ Options:
   -f, --format markdown|json   Output format (default: markdown)
       --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)
       --fail-on-high-risk      Exit 2 if high-severity risk patterns are found
   -h, --help                   Show help
 
 Examples:
   npx @builtbyecho/agent-brief
   agent-brief ~/dev/my-app --format json
+  agent-brief . --diff origin/main
   agent-brief . --fail-on-high-risk > AGENT_BRIEF.md
 `;
 }
@@ -46,7 +49,8 @@ try {
   if (!['markdown', 'json'].includes(args.format)) throw new Error('--format must be markdown or json');
   const brief = generateBrief(resolve(args.path), {
     maxFileBytes: args.maxFileBytes,
-    includeSnippets: !args.noSnippets
+    includeSnippets: !args.noSnippets,
+    diffRef: args.diffRef
   });
   console.log(args.format === 'json' ? formatJson(brief) : formatMarkdown(brief));
   if (args.failOnHighRisk && brief.risks.some(r => r.severity === 'high')) process.exit(2);

package/src/index.js

@@ -40,6 +40,7 @@ export function generateBrief(root = process.cwd(), options = {}) {
   const tree = collectTree(absRoot, opts.maxTreeEntries);
   const packageInfo = readPackage(absRoot);
   const git = readGit(absRoot);
+  const diff = opts.diffRef ? collectDiff(absRoot, opts.diffRef) : null;
   const risks = scanRisks(absRoot, context.files);
   const commands = inferCommands(absRoot, packageInfo);
   const stack = inferStack(absRoot, packageInfo);
@@ -51,6 +52,7 @@ export function generateBrief(root = process.cwd(), options = {}) {
     root: absRoot,
     score,
     git,
+    diff,
     stack,
     commands,
     contextFiles: context.files,
@@ -81,6 +83,25 @@ export function formatMarkdown(brief) {
   }
   lines.push('');
 
+  if (brief.diff) {
+    lines.push(`## Git diff vs ${brief.diff.ref}`);
+    if (brief.diff.available) {
+      lines.push(`- ${brief.diff.files.length} changed file(s), +${brief.diff.insertions} -${brief.diff.deletions}`);
+      if (brief.diff.files.length) {
+        for (const file of brief.diff.files) {
+          lines.push(`- ${file.status} ${file.path}${file.additions || file.deletions ? ` (+${file.additions}/-${file.deletions})` : ''}${file.risky ? ' ⚠️' : ''}`);
+        }
+      }
+      if (brief.diff.riskNotes.length) {
+        lines.push('');
+        lines.push(...brief.diff.riskNotes.map(note => `- ⚠️ ${note}`));
+      }
+    } else {
+      lines.push(`- Diff unavailable: ${brief.diff.error}`);
+    }
+    lines.push('');
+  }
+
   lines.push('## Agent context files');
   if (brief.contextFiles.length) {
     for (const file of brief.contextFiles) {
@@ -180,6 +201,86 @@ function readGit(root) {
   return git;
 }
 
+function collectDiff(root, ref) {
+  const diff = { ref, available: false, files: [], insertions: 0, deletions: 0, riskNotes: [], error: '' };
+  try {
+    const numstat = execFileSync('git', ['-C', root, 'diff', '--numstat', ref, '--'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    const nameStatus = execFileSync('git', ['-C', root, 'diff', '--name-status', ref, '--'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    const status = execFileSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    diff.available = true;
+    const byPath = new Map();
+    for (const line of numstat ? numstat.split('\n') : []) {
+      const parts = line.split('\t');
+      if (parts.length >= 3 && /^(?:\d+|-)$/.test(parts[0]) && /^(?:\d+|-)$/.test(parts[1])) {
+        const additions = parts[0] === '-' ? 0 : Number(parts[0]);
+        const deletions = parts[1] === '-' ? 0 : Number(parts[1]);
+        const path = parts.slice(2).join('\t');
+        const entry = byPath.get(path) || { path, status: 'M', additions: 0, deletions: 0, risky: false };
+        entry.additions += additions;
+        entry.deletions += deletions;
+        byPath.set(path, entry);
+        diff.insertions += additions;
+        diff.deletions += deletions;
+      }
+    }
+    for (const line of nameStatus ? nameStatus.split('\n') : []) {
+      const parts = line.split('\t');
+      if (parts.length >= 2 && /^[A-Z]/.test(parts[0])) {
+        const status = parts[0];
+        const path = parts[parts.length - 1];
+        const entry = byPath.get(path) || { path, status, additions: 0, deletions: 0, risky: false };
+        entry.status = status;
+        byPath.set(path, entry);
+      }
+    }
+    for (const line of status ? status.split('\n') : []) {
+      if (!line.startsWith('?? ')) continue;
+      const path = line.slice(3).trim();
+      for (const filePath of expandUntracked(root, path)) {
+        if (!byPath.has(filePath)) byPath.set(filePath, { path: filePath, status: '??', additions: 0, deletions: 0, risky: false });
+      }
+    }
+    diff.files = [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+    for (const file of diff.files) {
+      file.risky = isRiskyChangedPath(file.path);
+      if (file.risky) diff.riskNotes.push(`${file.path} is a high-impact path; inspect carefully before handing changes to an agent.`);
+    }
+  } catch (error) {
+    diff.error = error.message;
+  }
+  return diff;
+}
+
+function expandUntracked(root, path) {
+  const fullPath = join(root, path);
+  try {
+    const stat = statSync(fullPath);
+    if (!stat.isDirectory()) return [path];
+    const out = [];
+    walkUntracked(fullPath, path, out);
+    return out;
+  } catch {
+    return [path];
+  }
+}
+
+function walkUntracked(base, prefix, out) {
+  let entries = [];
+  try { entries = readdirSync(base, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    if (DEFAULT_IGNORES.has(entry.name)) continue;
+    const rel = `${prefix.replace(/\/$/, '')}/${entry.name}`;
+    if (entry.isDirectory()) walkUntracked(join(base, entry.name), rel, out);
+    else out.push(rel);
+  }
+}
+
+function isRiskyChangedPath(path) {
+  return /(^|\/)(\.env|\.npmrc|\.pypirc|Dockerfile|docker-compose\.ya?ml|compose\.ya?ml|package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/i.test(path)
+    || /(^|\/)\.github\/workflows\//i.test(path)
+    || /(^|\/)(migrations?|supabase|terraform|infra|deploy|scripts?)\//i.test(path);
+}
+
 function inferCommands(root, pkg) {
   const commands = [];
   if (pkg?.scripts) {