repo-agent-brief 0.2.0 → 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.
@@ -87,3 +101,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.2.0",
+  "version": "0.3.0",
   "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/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) {