{"_id":"@builtbyecho/repo-agent-brief","_rev":"2-4ea1c80237b1d30c4af40c37f448ff9b","name":"@builtbyecho/repo-agent-brief","dist-tags":{"latest":"0.4.2"},"versions":{"0.4.1":{"name":"@builtbyecho/repo-agent-brief","version":"0.4.1","keywords":["ai-agent","agents","context","cli","mcp","developer-tools","agentic"],"author":{"name":"BuiltByEcho"},"license":"MIT","_id":"@builtbyecho/repo-agent-brief@0.4.1","maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"homepage":"https://github.com/BuiltByEcho/agent-brief#readme","bugs":{"url":"https://github.com/BuiltByEcho/agent-brief/issues"},"bin":{"agent-brief":"src/cli.js"},"dist":{"shasum":"f43204e1b3feec3886f5b81fc1f10b93d3cddec2","tarball":"https://registry.npmjs.org/@builtbyecho/repo-agent-brief/-/repo-agent-brief-0.4.1.tgz","fileCount":6,"integrity":"sha512-fYIrNbLEx/VEEtLQKlYMXM/039D93O29xhI7QfaplUMU3A+nTjrdZBpXVHy/AtRcNgPEkMVIGcDGmrXfPFvpSg==","signatures":[{"sig":"MEUCIQCveXZeY9qsutFtfb+ZKp3MaEYAoCUxYv4IW8ozeEmyhwIgL2BPZ5v6NMakC6hdzdNWKeTC0KFSOwuF4QWWjCSeKsk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32246},"type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.js"},"gitHead":"ade6511f125bdfb56389a4662817993215e258fd","scripts":{"test":"node --test","smoke":"node src/cli.js . --format markdown --max-file-bytes 3000"},"_npmUser":{"name":"builtbyecho","email":"echo-token@agentmail.to"},"repository":{"url":"git+https://github.com/BuiltByEcho/agent-brief.git","type":"git"},"_npmVersion":"11.14.1","description":"Generate concise, safety-aware project briefs for coding agents.","directories":{},"_nodeVersion":"26.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/repo-agent-brief_0.4.1_1779926267441_0.4750129288004439","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@builtbyecho/repo-agent-brief","version":"0.4.2","description":"Generate concise, safety-aware project briefs for coding agents.","type":"module","bin":{"agent-brief":"src/cli.js"},"exports":{".":"./src/index.js"},"scripts":{"test":"node --test","smoke":"node src/cli.js . --format markdown --max-file-bytes 3000"},"keywords":["ai-agent","agents","context","cli","mcp","developer-tools","agentic"],"author":{"name":"BuiltByEcho"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/BuiltByEcho/agent-brief.git"},"bugs":{"url":"https://github.com/BuiltByEcho/agent-brief/issues"},"homepage":"https://github.com/BuiltByEcho/agent-brief#readme","engines":{"node":">=20"},"gitHead":"af80c2d3c8b5a2866daca739b1ac9504afdb1765","_id":"@builtbyecho/repo-agent-brief@0.4.2","_nodeVersion":"22.22.3","_npmVersion":"11.17.0","dist":{"integrity":"sha512-pIB2nx4QGLHKXC8/43KjNLKPZPB9aokX5LNk+/P11Nd9e9TV2RH20OQ5wBtrNuggp0JbissbbTy4lskS3D1PCA==","shasum":"db8f9bf5b0e0ec8a8b24547fe5f7fe982c406da8","tarball":"https://registry.npmjs.org/@builtbyecho/repo-agent-brief/-/repo-agent-brief-0.4.2.tgz","fileCount":6,"unpackedSize":32455,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@builtbyecho%2frepo-agent-brief@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC20HyfI7rvPJ+k13EW7GFoZlgMDMMfHGwq0D815GYuBgIgOo7GSNlkQw8wQcaIJfVqvMLAcKtjBV8AA3ldgT/H0fw="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:1000930d-7036-4fcf-b5f1-e2716ff62be3"}},"directories":{},"maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/repo-agent-brief_0.4.2_1782167844391_0.339936300722556"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T23:57:47.331Z","modified":"2026-06-22T22:37:24.838Z","0.4.1":"2026-05-27T23:57:47.603Z","0.4.2":"2026-06-22T22:37:24.561Z"},"bugs":{"url":"https://github.com/BuiltByEcho/agent-brief/issues"},"author":{"name":"BuiltByEcho"},"license":"MIT","homepage":"https://github.com/BuiltByEcho/agent-brief#readme","keywords":["ai-agent","agents","context","cli","mcp","developer-tools","agentic"],"repository":{"type":"git","url":"git+https://github.com/BuiltByEcho/agent-brief.git"},"description":"Generate concise, safety-aware project briefs for coding agents.","maintainers":[{"name":"builtbyecho","email":"echo-token@agentmail.to"}],"readme":"# agent-brief\n\nGenerate a concise, safety-aware project brief for coding agents.\n\nAgents waste a surprising amount of time rediscovering the same basics: What stack is this? Which command runs tests? Is there an AGENTS.md? Are there risky instructions or secret-looking strings in the handoff context?\n\n`agent-brief` turns a repo into a short briefing an agent can read before it starts changing code.\n\n```bash\nnpx @builtbyecho/repo-agent-brief\n```\n\n## What it does\n\n- Finds high-signal files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.\n- Infers stack and common commands.\n- Builds a compact repo map.\n- Suggests a prioritized verification plan (`must` / `should` / `optional`) from detected scripts, risks, and changed files.\n- Optionally summarizes the current git diff so agents can start from “what changed?” instead of rereading the whole repo.\n- Scans context files for obvious secrets and risky operational instructions.\n- Emits Markdown for humans/agents or JSON for automation.\n\n## Install\n\n```bash\nnpm install -g @builtbyecho/repo-agent-brief\nagent-brief /path/to/repo\n```\n\nOr run without installing:\n\n```bash\nnpx @builtbyecho/repo-agent-brief /path/to/repo\n```\n\n## Usage\n\n```bash\nagent-brief [path] [options]\n```\n\nOptions:\n\n- `--format markdown|json` / `-f` — output format. Default: `markdown`.\n- `--max-file-bytes N` — max bytes to read per context file. Default: `12000`.\n- `--no-snippets` — omit source snippets.\n- `--diff [ref]` — include changed files, insertions/deletions, and high-impact path warnings versus a git ref. Defaults to `HEAD` when no ref is provided.\n- `--bundle [dir]` — write a durable handoff bundle with `brief.md`, `brief.json`, and `verification.md`. Default: `.agent-brief`.\n- `--fail-on-high-risk` — exit `2` if high-severity risk patterns are found.\n\nExamples:\n\n```bash\nagent-brief . > AGENT_BRIEF.md\nagent-brief ~/dev/my-app --format json\nagent-brief . --diff origin/main\nagent-brief . --diff HEAD --bundle\nagent-brief . --fail-on-high-risk\n```\n\n## Diff-aware handoffs\n\nWhen you are handing an in-progress branch to an agent, run:\n\n```bash\nagent-brief . --diff origin/main > AGENT_HANDOFF.md\n```\n\nThe 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.\n\n## Verification plans\n\nEvery 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:\n\n```markdown\n## Suggested verification plan\n- [must] Run type checks for changed code paths — `npm run typecheck`\n- [should] Run lint for fast static feedback — `npm run lint`\n- [must] Run the primary test suite before final handoff — `npm run test`\n```\n\nIf 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.\n\n## Handoff bundles\n\nFor longer-running work, use `--bundle` to leave a stable artifact another agent or human can inspect later:\n\n```bash\nagent-brief . --diff HEAD --bundle\n```\n\nThis writes:\n\n- `.agent-brief/brief.md` — the full human-readable project brief.\n- `.agent-brief/brief.json` — the same data for automation.\n- `.agent-brief/verification.md` — a focused checklist of the exact checks the next agent should run or document.\n\nUse a custom directory when you want to attach the bundle to a ticket, run log, or CI artifact:\n\n```bash\nagent-brief . --diff origin/main --bundle artifacts/agent-brief\n```\n\n## Why this exists\n\nThe 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.\n\nThis is intentionally zero-dependency and boring. It should be safe to run in almost any repo.\n\n## Library API\n\n```js\nimport { generateBrief, formatMarkdown } from '@builtbyecho/repo-agent-brief';\n\nconst brief = generateBrief(process.cwd(), { diffRef: 'origin/main' });\nconsole.log(formatMarkdown(brief));\n```\n\n## Notes on risk scanning\n\nThis is not a full secret scanner. It catches common token/private-key/secret-assignment patterns in the context files most likely to be pasted into agents. Use a dedicated scanner like Gitleaks or TruffleHog for full repository security reviews.\n\n## License\n\nMIT\n\n## Agent Skill\n\nThis 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.\n\n## Package Names\n\n`@builtbyecho/repo-agent-brief` is the canonical package. The older unscoped `repo-agent-brief` package remains on npm as a compatibility package for historical installs.\n\n## Release Automation\n\nThis package is published from GitHub Actions using npm Trusted Publishing with provenance. Releases are built on GitHub-hosted runners and no long-lived npm publish token is required.\n","readmeFilename":"README.md"}