convez.ai
Agente
ShawWang1996

agentbrief

ShawWang1996/agentbrief

Ver no GitHub
BomPluginScore · de 0 a 100

Generate repo-grounded task briefs for AI coding agents like Codex, Claude Code, and Cursor.

Instalação

$npx convez-ai ShawWang1996/agentbrief

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

AgentBrief

English | 简体中文

Repo-grounded task briefs for AI coding agents.

AgentBrief turns a repository and an engineering task into a portable brief that can be handed to Codex, Claude Code, Cursor, Copilot, or a generic LLM chat. It collects the files that matter, detects validation commands, redacts likely secrets, and renders a task contract with acceptance checks.

The goal is simple: make coding agents start from repo evidence instead of a vague prompt.

Why This Exists

AI coding agents are useful, but they still fail on ordinary engineering details: missing setup commands, stale assumptions about project structure, oversized context, and accidental secret exposure. Existing repo packers are good at bundling files. AgentBrief focuses on the task handoff layer around those files:

  • What is the objective?
  • What files are relevant?
  • What commands prove the work is done?
  • What sensitive values must not be copied into prompts?
  • What prompt shape works across different agents?

Features

  • agentbrief init: create a small agentbrief.toml task contract.
  • agentbrief doctor: inspect included files and likely sensitive data before sharing.
  • agentbrief pack: generate a Markdown or JSON context package.
  • agentbrief render: generate Codex, Claude, Cursor, or generic agent prompts.
  • Local-first by default: no network calls, no model calls, no telemetry.
  • Zero runtime dependencies beyond Python 3.9+.

Quick Start

python -m pip install -e .
agentbrief init
agentbrief pack
agentbrief render --target codex

This creates:

  • agentbrief.toml: task, acceptance checks, include/exclude rules.
  • agentbrief.md: repo-grounded context package.
  • agentbrief-prompt.md: agent-specific prompt wrapper.

Example Config

[task]
title = "Fix the failing checkout flow"
objective = "Find the root cause, implement the smallest safe fix, and verify the checkout tests pass."
acceptance = [
  "The failing checkout test passes",
  "Existing payment behavior is preserved",
  "No credentials or generated artifacts are included",
]

[context]
include = ["src/**", "tests/**", "pyproject.toml", "package.json", "README.md"]
exclude = ["dist/**", "build/**", "*.lock"]
max_file_bytes = 64000
max_total_bytes = 750000

[commands]
test = "python -m unittest discover"
lint = "python -m compileall agentbrief"

CLI

agentbrief init --root /path/to/repo
agentbrief doctor --root /path/to/repo --strict
agentbrief pack --root /path/to/repo --format markdown --output agentbrief.md
agentbrief pack --root /path/to/repo --format json --output agentbrief.json
agentbrief render --root /path/to/repo --target claude --output claude-brief.md

What The Brief Contains

  • Task title, objective, and acceptance checks.
  • Detected and configured validation commands.
  • Existing agent instruction files such as AGENTS.md, CLAUDE.md, and Cursor rules.
  • Language/file manifest with SHA-256 prefixes.
  • Sensitive-data findings with matched values redacted.
  • Included file contents in path-labeled code fences.
  • Agent instructions for scoped edits and validation.

Design Principles

  • Evidence first: every agent handoff should include actual repository files, not only prose.
  • Verification first-class: acceptance checks and commands belong in the brief.
  • Private by default: local execution and redaction are core behavior, not add-ons.
  • Agent portable: the same brief should work across competing agent tools.
  • Small core: no framework lock-in, no hosted dependency, no mandatory LLM key.

Development

python -m unittest discover
python -m compileall agentbrief

Roadmap

  • Smarter git-diff and issue-based context selection.
  • Token budget estimation and context ranking.
  • Native AGENTS.md, Claude skill, Cursor rule, and Copilot instruction generation.
  • MCP server mode for live agent consumption.
  • GitHub Action that attaches an AgentBrief to issues or pull requests.
  • Plugin API for project-specific scanners and command detectors.

See docs/ROADMAP.md and docs/PRODUCT_SPEC.zh-CN.md.

For release operations and launch copy, see docs/LAUNCH.md.

Security

AgentBrief includes heuristic secret detection and redaction, but no scanner is perfect. Run agentbrief doctor --strict before sharing a brief outside your local machine.

See SECURITY.md.

License

MIT

Ver o original no GitHub

Bom para

Relacionados