# Agentbriefer documentation > Versioned documentation for configuring AI coding-agent behavior with Agentbriefer. ## search Documentation for Agentbriefer, the CLI that creates consistent project instructions for AI coding agents. - [Search the documentation](/search.md): Documentation for Agentbriefer, the CLI that creates consistent project instructions for AI coding agents. ## docs ### next - [Architecture](/docs/next/contributing/architecture.md): Internal architecture and data flow of the Agentbriefer CLI. - [Development setup](/docs/next/contributing/development.md): Build, run, and test Agentbriefer locally. - [Documentation workflow](/docs/next/contributing/documentation.md): Author, version, validate, and deploy the Agentbriefer documentation. - [Extending Agentbriefer](/docs/next/contributing/extending-agentbriefer.md): Add detectors, bundled skills, output formats, and configuration behavior safely. - [Testing and release](/docs/next/contributing/testing-and-release.md): Validation layers and the Agentbriefer v1 release checklist. - [Use cases and examples](/docs/next/examples/overview.md): Choose a complete Agentbriefer workflow for your project or team. - [Profiles, skill sets, and manual notes](/docs/next/examples/profiles-and-sync.md): Reuse personal preferences and skill sets while preserving handwritten project notes. - [Solo developer, several agents](/docs/next/examples/solo-multi-agent.md): Keep Claude Code, Cursor, Copilot, and AGENTS.md-compatible tools aligned. - [Stack detection and skills](/docs/next/examples/stack-skills.md): Use detected stack tags to discover relevant skills for Rust, Next.js, and SvelteKit. - [Security-first backend team](/docs/next/examples/team-security.md): Make authentication, secrets, dependencies, and test expectations explicit. - [Configure a project](/docs/next/guides/configure-project.md): Use init, detected stack values, project policies, custom instructions, and stop rules. - [Developer profiles](/docs/next/guides/developer-profiles.md): Reuse personal development and explanation styles across projects. - [Doctor and maintenance](/docs/next/guides/doctor-maintenance.md): Diagnose conflicting policy, missing output, drift, and catalog mismatches. - [Generate vs. sync](/docs/next/guides/generate-vs-sync.md): Choose between full output replacement and managed-block synchronization. - [Skill profiles](/docs/next/guides/skill-profiles.md): Save and apply reusable named sets of skill IDs. - [Skills](/docs/next/guides/skills.md): Discover, inspect, install, update, and remove focused Agentbriefer skills. - [Stack detection](/docs/next/guides/stack-detection.md): Understand detected languages, manifests, dependencies, limitations, and editable prefilled values. - [Team workflow](/docs/next/guides/team-workflow.md): Share project policy while keeping personal filters and profiles separate. - [How Agentbriefer works](/docs/next/how-it-works.md): The Agentbriefer configuration, rendering, skills, and output lifecycle. - [Installation](/docs/next/installation.md): Install Agentbriefer through npm, native installers, GitHub releases, or source. - [Meet Agentbriefer](/docs/next/introduction.md): What Agentbriefer is, what it solves, and when to use it. - [Quick start](/docs/next/quick-start.md): Configure a project and generate AI-agent instructions in minutes. - [Command reference](/docs/next/reference/commands.md): Complete reference for every Agentbriefer CLI command and option. - [Configuration schema](/docs/next/reference/configuration.md): Reference for agentbriefer.yaml and every supported configuration value. - [Detection matrix](/docs/next/reference/detection-matrix.md): Languages, manifest files, and package managers Agentbriefer can detect. - [Files and safety](/docs/next/reference/files-and-safety.md): Files Agentbriefer reads and writes, preservation guarantees, and source-control guidance. - [Outputs](/docs/next/reference/outputs.md): Supported AI-agent instruction formats and how Agentbriefer writes them. - [Bundled skill catalog](/docs/next/reference/skill-catalog.md): Reference for the seven focused skills included with Agentbriefer v1. - [Agentbriefer v1 πŸŽ‰](/docs/next/release-notes/v1.md): The first stable Agentbriefer release and its user-facing capabilities. - [Troubleshooting](/docs/next/troubleshooting.md): Diagnose installation, configuration, generation, synchronization, and skill issues. ### contributing - [Architecture](/docs/contributing/architecture.md): Internal architecture and data flow of the Agentbriefer CLI. - [Development setup](/docs/contributing/development.md): Build, run, and test Agentbriefer locally. - [Documentation workflow](/docs/contributing/documentation.md): Author, version, validate, and deploy the Agentbriefer documentation. - [Extending Agentbriefer](/docs/contributing/extending-agentbriefer.md): Add detectors, bundled skills, output formats, and configuration behavior safely. - [Testing and release](/docs/contributing/testing-and-release.md): Validation layers and the Agentbriefer v1 release checklist. ### examples - [Use cases and examples](/docs/examples/overview.md): Choose a complete Agentbriefer workflow for your project or team. - [Profiles, skill sets, and manual notes](/docs/examples/profiles-and-sync.md): Reuse personal preferences and skill sets while preserving handwritten project notes. - [Solo developer, several agents](/docs/examples/solo-multi-agent.md): Keep Claude Code, Cursor, Copilot, and AGENTS.md-compatible tools aligned. - [Stack detection and skills](/docs/examples/stack-skills.md): Use detected stack tags to discover relevant skills for Rust, Next.js, and SvelteKit. - [Security-first backend team](/docs/examples/team-security.md): Make authentication, secrets, dependencies, and test expectations explicit. ### guides - [Configure a project](/docs/guides/configure-project.md): Use init, detected stack values, project policies, custom instructions, and stop rules. - [Developer profiles](/docs/guides/developer-profiles.md): Reuse personal development and explanation styles across projects. - [Doctor and maintenance](/docs/guides/doctor-maintenance.md): Diagnose conflicting policy, missing output, drift, and catalog mismatches. - [Generate vs. sync](/docs/guides/generate-vs-sync.md): Choose between full output replacement and managed-block synchronization. - [Skill profiles](/docs/guides/skill-profiles.md): Save and apply reusable named sets of skill IDs. - [Skills](/docs/guides/skills.md): Discover, inspect, install, update, and remove focused Agentbriefer skills. - [Stack detection](/docs/guides/stack-detection.md): Understand detected languages, manifests, dependencies, limitations, and editable prefilled values. - [Team workflow](/docs/guides/team-workflow.md): Share project policy while keeping personal filters and profiles separate. ### how-it-works The Agentbriefer configuration, rendering, skills, and output lifecycle. - [How Agentbriefer works](/docs/how-it-works.md): The Agentbriefer configuration, rendering, skills, and output lifecycle. ### installation Install Agentbriefer through npm, native installers, GitHub releases, or source. - [Installation](/docs/installation.md): Install Agentbriefer through npm, native installers, GitHub releases, or source. ### introduction What Agentbriefer is, what it solves, and when to use it. - [Meet Agentbriefer](/docs/introduction.md): What Agentbriefer is, what it solves, and when to use it. ### quick-start Configure a project and generate AI-agent instructions in minutes. - [Quick start](/docs/quick-start.md): Configure a project and generate AI-agent instructions in minutes. ### reference - [Command reference](/docs/reference/commands.md): Complete reference for every Agentbriefer CLI command and option. - [Configuration schema](/docs/reference/configuration.md): Reference for agentbriefer.yaml and every supported configuration value. - [Detection matrix](/docs/reference/detection-matrix.md): Languages, manifest files, and package managers Agentbriefer can detect. - [Files and safety](/docs/reference/files-and-safety.md): Files Agentbriefer reads and writes, preservation guarantees, and source-control guidance. - [Outputs](/docs/reference/outputs.md): Supported AI-agent instruction formats and how Agentbriefer writes them. - [Bundled skill catalog](/docs/reference/skill-catalog.md): Reference for the seven focused skills included with Agentbriefer v1. ### release-notes - [Agentbriefer v1 πŸŽ‰](/docs/release-notes/v1.md): The first stable Agentbriefer release and its user-facing capabilities. ### troubleshooting Diagnose installation, configuration, generation, synchronization, and skill issues. - [Troubleshooting](/docs/troubleshooting.md): Diagnose installation, configuration, generation, synchronization, and skill issues. --- # Full Documentation Content [Skip to main content](#__docusaurus_skipToContent_fallback) [![Agentbriefer logo](/img/agentbriefer-icon.svg)![Agentbriefer logo](/img/agentbriefer-icon.svg)](/) [**agentbriefer**](/)[Docs](/docs/introduction.md)[Examples](/docs/examples/overview.md)[Reference](/docs/reference/commands.md) [v1.0](/docs/introduction.md) * [Next](/docs/next/introduction.md) * [v1.0](/docs/introduction.md) [GitHub](https://github.com/dexterhere/agentbriefer) Search # Search the documentation Documentation * [Get started](/docs/quick-start.md) * [Installation](/docs/installation.md) * [Command reference](/docs/reference/commands.md) Project * [GitHub](https://github.com/dexterhere/agentbriefer) * [npm](https://www.npmjs.com/package/agentbriefer) * [Security](https://github.com/dexterhere/agentbriefer/security/policy) AI access * [llms.txt](https://docsagentbriefer.vercel.app/llms.txt) * [llms-full.txt](https://docsagentbriefer.vercel.app/llms-full.txt) Copyright Β© 2026 Agentbriefer. Built with Docusaurus. --- # Architecture Agentbriefer is a Rust CLI organized around pure configuration, detection, rendering, and skill components, with the `cli` module owning interactive behavior and real filesystem operations. ## Modules[​](#modules "Direct link to Modules") ### `config`[​](#config "Direct link to config") Defines the typed YAML schema and generic load/save operations. It turns a path into a validated Rust value or serializes a value back to YAML. Project location and prompting remain outside it. ### `detect`[​](#detect "Direct link to detect") Contains one detector per supported ecosystem plus shared dependency categorization. Detection reads manifest evidence from the current directory and returns an optional `DetectedStack`; it does not write configuration. ### `skills`[​](#skills "Direct link to skills") Loads `skills/**/SKILL.md` through `rust-embed`, parses YAML frontmatter and Markdown bodies, validates directory/ID agreement, sorts the catalog, and provides role and stack recommendation queries. ### `render`[​](#render "Direct link to render") Registers embedded Tera templates once, serializes configuration and resolved skills into a rendering context, and returns text for an `OutputFormat`. It does not choose destinations or write files. ### `cli`[​](#cli "Direct link to cli") Owns clap dispatch, prompts, terminal presentation, current-directory resolution, per-user profile paths, materialized skills, and output writes. Command modules compose the pure components and report partial per-format failures. ### `textutil`[​](#textutil "Direct link to textutil") Provides shared frontmatter splitting used by skill parsing and synchronized Cursor output handling. ## Embedded assets[​](#embedded-assets "Direct link to Embedded assets") `templates/` and `skills/` are read directly in debug builds and embedded into release binaries. A released executable therefore needs no runtime template or catalog directory. ## Write models[​](#write-models "Direct link to Write models") * `generate` renders and replaces every selected output. * `sync` preserves text outside line-delimited managed markers. * skill commands materialize catalog entries under `.agentbriefer/skills/` and synchronize outputs. * developer profiles and skill profiles use platform-standard per-user configuration directories. The repository-level [architecture note](https://github.com/dexterhere/agentbriefer/blob/main/docs/ARCHITECTURE.md) is maintained alongside this page for contributors browsing the source tree. --- # Development setup ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * a stable Rust toolchain with `rustfmt` and `clippy`; * Git; * Node.js 20 or newer for the documentation site. ## Build the CLI[​](#build-the-cli "Direct link to Build the CLI") ``` git clone https://github.com/dexterhere/agentbriefer.git cd agentbriefer cargo build cargo run -- --help ``` Run project commands against a disposable fixture directory because `init`, `generate`, `sync`, and skill lifecycle commands write files in the current directory. ## Quality checks[​](#quality-checks "Direct link to Quality checks") ``` cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test --all-targets ``` Unit tests live beside their modules. End-to-end CLI behavior lives in `tests/cli_integration.rs`, and rendered output is protected by `insta` snapshots under `src/render/snapshots/`. When a deliberate template change modifies snapshots, review the semantic diff before accepting it. ## Run the documentation[​](#run-the-documentation "Direct link to Run the documentation") ``` cd docs-site npm install npm start ``` Before submitting documentation changes: ``` npm run typecheck npm run build ``` The production build checks internal links and emits the local search index, sitemap, and AI-readable documentation files. --- # Documentation workflow The Docusaurus site lives in `docs-site/` within the CLI repository so documentation can be reviewed and versioned with the behavior it describes. ## Writing standards[​](#writing-standards "Direct link to Writing standards") * Lead with the user's goal and show commands that can be copied safely. * Verify names, flags, paths, defaults, and exit behavior against the Rust source or `--help`. * Use emoji sparingly as wayfinding, not as a replacement for labels. ✨ * Include realistic snippets without credentials, tokens, or private repository details. * Link to the canonical reference instead of duplicating long schemas. * Update both user and contributor material when a change affects both audiences. ## Local workflow[​](#local-workflow "Direct link to Local workflow") ``` cd docs-site npm install npm start ``` Edit current documentation in `docs/`. Docusaurus reloads pages during development. Before commit: ``` npm run typecheck npm run build ``` The build is configured to fail on broken links and anchors. ## Create a release snapshot[​](#create-a-release-snapshot "Direct link to Create a release snapshot") With the current docs describing the release: ``` npm run docusaurus docs:version 1.0.0 ``` Then configure `1.0.0` as the latest stable version and current docs as **Next**. Keep release notes inside the snapshot and continue future work only in `docs/`. ## Deployment[​](#deployment "Direct link to Deployment") Vercel can deploy this static site from the monorepo by setting the project root to `docs-site`. The repository includes `docs-site/vercel.json` and a maintainer runbook in `docs-site/DEPLOYMENT.md`. Deploy previews should build every pull request; production should track the chosen release branch. --- # Extending Agentbriefer Keep new functionality in the narrowest subsystem that owns it and add tests at the same boundary. ## Add a bundled skill[​](#add-a-bundled-skill "Direct link to Add a bundled skill") Create `skills///SKILL.md`. The directory name and frontmatter `id` must match. skills/security/example-policy/SKILL.md ``` --- id: example-policy name: Example Policy description: One sentence describing the behavior this skill enforces. category: security roles: [security, backend] compatible_stacks: [rust, axum] --- Write direct, actionable instructions for the coding agent here. ``` Use lowercase kebab-case IDs. `roles` are browsing tags. `compatible_stacks` participate in case-insensitive any-tag recommendation matching; an empty list makes the skill stack-agnostic. Then test the registry and update the public catalog: ``` cargo test skills cargo test --test cli_integration ``` ## Add or improve a detector[​](#add-or-improve-a-detector "Direct link to Add or improve a detector") Implement an ecosystem module under `src/detect/`, expose it through `src/detect/mod.rs`, and preserve the detector order intentionally because the first matching ecosystem wins. A detector should: * return no match when its root manifest is absent; * tolerate malformed input without preventing `init`; * identify package manager, framework, database, tests, and key direct dependencies when evidence is reliable; * keep dependency output deterministic and bounded. Add focused unit fixtures and update the [detection matrix](/docs/next/reference/detection-matrix.md). ## Add an output format[​](#add-an-output-format "Direct link to Add an output format") Add the `OutputFormat` enum value and path mapping, a top-level Tera template, prompt support, and generate/sync/doctor coverage. Reuse shared template partials so behavioral policy does not drift between tools. Document the consumer and output path. ## Change configuration[​](#change-configuration "Direct link to Change configuration") Schema changes affect YAML compatibility, templates, interactive prompts, profiles, snapshots, and the documentation reference. For v1 maintenance releases, prefer optional fields with safe serde defaults. Treat renamed or reinterpreted values as compatibility-sensitive changes. --- # Testing and release ## Validation layers[​](#validation-layers "Direct link to Validation layers") Run the complete Rust gate: ``` cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test --all-targets ``` Run the documentation gate: ``` cd docs-site npm ci npm run typecheck npm run build ``` Also exercise `agentbriefer init`, `generate`, `sync`, `doctor`, and the skill lifecycle in a temporary project when user-visible workflows change. ## Release checklist[​](#release-checklist "Direct link to Release checklist") 1. Set the same semantic version in `Cargo.toml`, the changelog, and the release notes. 2. Verify generated snapshots and documentation examples against the current clap help. 3. Build docs and confirm stable plus Next navigation, local search, sitemap, `llms.txt`, and `llms-full.txt`. 4. Run the Rust validation gate on a clean checkout. 5. Review `dist-workspace.toml` targets and installers. 6. Create and push the matching Git tag only after the release commit is approved. 7. Verify the GitHub release archives, checksums, shell and PowerShell installers, and npm package. 8. Smoke-test `agentbriefer --version` and `agentbriefer skill list` through at least one published installation path. The generated cargo-dist workflow builds macOS ARM64/x64, Linux ARM64/x64, and Windows x64 artifacts, then publishes GitHub-hosted installers and the npm package. Tagging and publishing change external state and remain a maintainer-controlled action. ## Versioned docs[​](#versioned-docs "Direct link to Versioned docs") Stable documentation is a snapshot under `versioned_docs/version-/`. Ongoing source docs under `docs/` appear as **Next**. Create a new snapshot only for a real release boundary; do not edit an old snapshot to describe later behavior. --- # Use cases and examples These examples start from a real goal and show the resulting configuration and workflowβ€”not just isolated command syntax. | Goal | Example | | ------------------------------------------- | -------------------------------------------------------------------- | | Keep several coding assistants aligned | [Solo multi-agent workflow](/docs/next/examples/solo-multi-agent.md) | | Establish strict team security boundaries | [Team security policy](/docs/next/examples/team-security.md) | | Combine stack detection with focused skills | [Stack-specific skills](/docs/next/examples/stack-skills.md) | | Reuse preferences and preserve manual notes | [Profiles and sync](/docs/next/examples/profiles-and-sync.md) | ## A useful baseline[​](#a-useful-baseline "Direct link to A useful baseline") Most projects can begin with: ``` developer: style: practical explanation_style: short project: project_type: library stack: language: rust package_manager: cargo security_level: standard testing_level: practical dependency_policy: explain-first architecture_style: simple stop_rules: [] skills: - no-secrets-in-repo ``` Then change only settings that express a real project constraint. More strict is not automatically more useful; the best brief is the one the team will follow and review. --- # Profiles, skill sets, and manual notes This workflow separates three concerns: * personal communication preferences in a developer profile; * reusable technical guidance in a skill profile; * repository-specific notes outside a managed output block. ## Save personal preferences[​](#save-personal-preferences "Direct link to Save personal preferences") ``` agentbriefer profile create # Name: practical-short # Style: practical # Explanation style: short ``` Future `init` runs can copy that profile without hiding the values from project YAML. ## Save a skill set[​](#save-a-skill-set "Direct link to Save a skill set") After configuring a representative frontend project: ``` agentbriefer skill add server-components-by-default agentbriefer skill add css-first-motion agentbriefer skill add no-secrets-in-repo agentbriefer skill profile create frontend-basics ``` Apply it to another configured project: ``` agentbriefer skill profile apply frontend-basics ``` Remember that apply replaces the complete skills list. ## Preserve handwritten instructions[​](#preserve-handwritten-instructions "Direct link to Preserve handwritten instructions") Run sync once, then add notes outside the block: AGENTS.md ``` # Repository note The `fixtures/legacy` directory is an external compatibility corpus. Do not reformat it. Generated project guidance... ``` Now configuration changes are safe to merge: ``` agentbriefer sync agentbriefer doctor ``` The compatibility note survives while the managed section reflects current policy and skills. --- # Solo developer, several agents You use different AI tools for different tasks but want the same scope, dependency, testing, and explanation expectations everywhere. ## Configure once[​](#configure-once "Direct link to Configure once") ``` cd my-project agentbriefer init agentbriefer generate ``` Choose all four outputs and a practical, concise profile: agentbriefer.yaml ``` developer: style: practical explanation_style: short project: project_type: full-stack-app stack: language: typescript framework: next testing_tools: - vitest - playwright package_manager: npm key_dependencies: - react security_level: standard testing_level: practical dependency_policy: explain-first architecture_style: feature-based stop_rules: - Ask before changing a public API contract. skills: - server-components-by-default - css-first-motion outputs: - claude-md - agents-md - cursor-rules - copilot-instructions ``` ## Result[​](#result "Direct link to Result") * Claude Code reads `CLAUDE.md`. * compatible agent runners discover `AGENTS.md`. * Cursor loads its always-applied `.mdc` rule. * GitHub Copilot reads repository-wide custom instructions. All four receive the same decision loop, project policy, workflow loops, stop rules, and installed skill bodies. ## Ongoing changes[​](#ongoing-changes "Direct link to Ongoing changes") Edit `agentbriefer.yaml`, then run: ``` agentbriefer sync agentbriefer doctor ``` This keeps tool syntax separate while project intent stays unified. --- # Stack detection and skills Recommendation narrows the bundled catalog; it does not install anything. ``` agentbriefer skill list --recommended agentbriefer skill info agentbriefer skill add ``` ## Rust and Axum[​](#rust-and-axum "Direct link to Rust and Axum") Given a `Cargo.toml` containing Axum and SQLx, review: ``` agentbriefer skill info rust-axum-layered-structure agentbriefer skill info password-and-session-auth agentbriefer skill add rust-axum-layered-structure ``` Add the authentication skill only when the project actually owns password and session behavior. Recommendations use any matching tag, so human review matters. ## Next.js and React[​](#nextjs-and-react "Direct link to Next.js and React") ``` agentbriefer skill list --role frontend --recommended agentbriefer skill add server-components-by-default agentbriefer skill add css-first-motion ``` This keeps client boundaries intentional and prefers CSS motion with reduced motion support. ## SvelteKit[​](#sveltekit "Direct link to SvelteKit") ``` agentbriefer skill info sveltekit-component-structure agentbriefer skill add sveltekit-component-structure ``` The skill keeps reusable components and stores under `src/lib` while route files remain focused on routing and page composition. ## Stack-agnostic security[​](#stack-agnostic-security "Direct link to Stack-agnostic security") `no-secrets-in-repo` has no compatible-stack restriction and appears in every recommendation set: ``` agentbriefer skill add no-secrets-in-repo ``` --- # Security-first backend team The team maintains a backend with authentication and wants agents to treat security-relevant changes conservatively. agentbriefer.yaml ``` developer: style: security-first explanation_style: tradeoff-based project: project_type: backend-api stack: language: rust framework: axum database: sqlx testing_tools: - cargo-test package_manager: cargo key_dependencies: - argon2 - tower-http security_level: strict testing_level: strict dependency_policy: ask-first architecture_style: simple-layered stop_rules: - Stop before changing session lifetime or cookie policy. - Ask before adding a new authentication dependency. - Never weaken validation to make a test pass. skills: - rust-axum-layered-structure - password-and-session-auth - no-secrets-in-repo outputs: - claude-md - agents-md ``` ## Apply and verify[​](#apply-and-verify "Direct link to Apply and verify") ``` agentbriefer skill add rust-axum-layered-structure agentbriefer skill add password-and-session-auth agentbriefer skill add no-secrets-in-repo agentbriefer doctor ``` Strict security with `ask-first` dependencies and strict testing is internally consistent. Doctor would warn if the same project allowed dependencies freely or used light testing. ## Team review points[​](#team-review-points "Direct link to Team review points") * Commit policy changes with the related architecture decision. * Review skill additions as executable guidance, not decorative metadata. * Keep secrets and environment-specific values out of YAML and generated files. * Use stop rules for decisions requiring human ownership, not for ordinary work. --- # Configure a project `agentbriefer init` is the only interactive project command. It turns a guided conversation into a typed YAML configuration. ## Before the prompts[​](#before-the-prompts "Direct link to Before the prompts") Run it from the project root: ``` agentbriefer init ``` If `agentbriefer.yaml` already exists, the wizard asks before overwriting it and defaults to leaving it untouched. Agentbriefer then detects a supported manifest and loads any saved developer profiles. ## Stack answers[​](#stack-answers "Direct link to Stack answers") Detected values prefill language, framework, database, package manager, testing tools, and key dependencies. They remain editable because repositories can be polyglot or use a tool the detector does not recognize. Comma-separated testing tools and dependencies are normalized into YAML lists. Optional fields can be left blank. ## Behavioral policy[​](#behavioral-policy "Direct link to Behavioral policy") The structured settings are deliberately concrete: | Setting | What it changes | | ------------------ | ---------------------------------------------------------------------- | | Developer style | Scope, tradeoffs, teaching, maintainability, or security posture | | Explanation style | Short, beginner-friendly, detailed, or tradeoff-focused reporting | | Project type | Backend, frontend, CLI, full-stack, library, or docs priorities | | Security level | Caution around auth, secrets, validation, permissions, and data access | | Testing level | When tests are optional, practical, or required | | Dependency policy | Whether agents may add, must explain, or must ask first | | Architecture style | Flat, lightly layered, feature-based, or advanced existing patterns | Every value is rendered with an agent-facing description; generated files do not rely on an unexplained label such as `practical` or `strict`. ## Custom instructions[​](#custom-instructions "Direct link to Custom instructions") Custom instructions hold project-specific guidance that does not fit a dropdown: ``` Run `make fixtures` before integration tests. Never edit generated files under src/protocol/. Keep public error codes backward compatible. ``` The wizard opens `$VISUAL` or `$EDITOR` when available, falling back to the platform editor. Closing without saving keeps the previous value. ## Stop rules[​](#stop-rules "Direct link to Stop rules") Stop rules describe boundaries where an agent must pause or avoid continuing: ``` stop_rules: - Stop before changing CI/CD configuration. - Ask before modifying a public API. - Do not access production credentials. ``` When no stop rules are configured, generated output still tells the agent to stop after the requested change is complete and verified. ## Review and save[​](#review-and-save "Direct link to Review and save") The final screen shows every answer. Select a field to edit it using its current value as the default, or select **Save and finish**. The wizard writes YAML only after this review. note `init` starts with no installed skills. Add them after saving with `agentbriefer skill list` and `agentbriefer skill add `. --- # Developer profiles A developer profile stores the two preferences that usually follow a person rather than a repository: ``` style: practical explanation_style: tradeoff-based ``` ## Create a profile[​](#create-a-profile "Direct link to Create a profile") ``` agentbriefer profile create ``` Choose a simple name, developer style, and explanation style. Existing names require overwrite confirmation. Profiles are stored in the platform configuration directory, commonly: ``` ~/.config/agentbriefer/profiles/.yaml ``` ## List profiles[​](#list-profiles "Direct link to List profiles") ``` agentbriefer profile list ``` ## Use a profile during init[​](#use-a-profile-during-init "Direct link to Use a profile during init") When profiles exist, `agentbriefer init` offers them before asking the two developer questions. The selected values are copied into the project YAML. ## Switch an existing project[​](#switch-an-existing-project "Direct link to Switch an existing project") ``` cd your-project agentbriefer profile switch agentbriefer sync ``` Switch replaces the project's `developer` section and records the source profile name in `extends`. It does not automatically regenerate output files, so run `sync` afterward. ## Copy semantics[​](#copy-semantics "Direct link to Copy semantics") Profiles are snapshots, not live inheritance. Updating a saved profile does not retroactively change projects that used it. This keeps `agentbriefer.yaml` self-contained and reviewable by teammates who do not have your profile. --- # Doctor and maintenance Run the read-only project linter after configuration changes, Agentbriefer upgrades, or unexpected generated output: ``` agentbriefer doctor ``` ## What doctor checks[​](#what-doctor-checks "Direct link to What doctor checks") * `dependency_policy: allow` combined with `security_level: strict`; * `testing_level: light` combined with `security_level: strict`; * an empty primary language; * configured skill IDs missing from the bundled catalog; * configured output files that do not exist; * generated files that differ from a fresh render. For synced files, drift is measured only inside the managed block. Manual notes outside it do not make the file stale. ## Findings and exit behavior[​](#findings-and-exit-behavior "Direct link to Findings and exit behavior") Doctor prints warnings for every finding and `No issues found.` when clean. Findings currently do not produce a non-zero exit code. ``` agentbriefer doctor # Use the report for visibility; do not assume warnings fail the process. ``` ## Maintenance cycle[​](#maintenance-cycle "Direct link to Maintenance cycle") ``` # Upgrade the CLI using your installation method. npm install -g agentbriefer@latest # Refresh bundled skill content and generated files. agentbriefer skill update # Confirm project state. agentbriefer doctor ``` If an unknown skill ID appears after working with a teammate, upgrade first. Remove the ID only when the project no longer intends to use that skill. --- # Generate vs. sync Both commands render the same configuration and installed skills. They differ only in how the result is written. | Behavior | `generate` | `sync` | | -------------------------------- | ---------- | --------------------------------- | | Render every configured format | Yes | Yes | | Create parent directories | Yes | Yes | | Replace the whole file | Yes | Only when no managed block exists | | Preserve content outside markers | No | Yes | | Refuse final-path symlinks | Yes | Yes | ## Generate[​](#generate "Direct link to Generate") ``` agentbriefer generate ``` Use it for the first render or when outputs are completely machine-owned. It always writes a clean template result and discards existing file contents. ## Sync[​](#sync "Direct link to Sync") ``` agentbriefer sync ``` Sync wraps the generated body in markers: ``` Generated Agentbriefer content lives here. ``` Future syncs replace that block and preserve content before or after it. CLAUDE.md ``` My repository-specific note stays here. Agentbriefer replaces only this section. Another manual note also stays here. ``` Cursor's YAML frontmatter stays before the managed block because `.mdc` files must begin with frontmatter. ## Missing or malformed markers[​](#missing-or-malformed-markers "Direct link to Missing or malformed markers") If a file exists without a valid managed block, sync warns and replaces the whole file with a fresh managed result. Markers are recognized only when they appear alone on their own lines, preventing quoted marker text inside a stop rule from corrupting synchronization. ## Recommended workflow[​](#recommended-workflow "Direct link to Recommended workflow") 1. Run `generate` on initial setup. 2. If no manual output edits are needed, continue using `generate` or `sync`. 3. Before adding manual notes, run `sync` once to establish markers. 4. Add notes only outside the markers. 5. Use `sync` thereafter. Do not switch back casually Running `generate` after manual edits fully overwrites the file. Agentbriefer does not try to recover discarded content. --- # Skill profiles A skill profile snapshots the current project's installed skill IDs so the same set can be applied elsewhere. ## Create a profile[​](#create-a-profile "Direct link to Create a profile") ``` cd configured-project agentbriefer skill profile create secure-rust-backend ``` The profile is stored under the platform configuration directory, commonly: ``` ~/.config/agentbriefer/skill-profiles/secure-rust-backend.yaml ``` ## List profiles[​](#list-profiles "Direct link to List profiles") ``` agentbriefer skill profile list ``` ## Apply a profile[​](#apply-a-profile "Direct link to Apply a profile") ``` cd another-configured-project agentbriefer skill profile apply secure-rust-backend ``` Apply **replaces** the target project's entire `skills` list. Agentbriefer then materializes the new set, removes stale skill directories, and synchronizes all configured outputs. caution Apply is not additive. Review the profile and the target project's existing skill list before applying it. Like developer profiles, skill profiles are copied snapshots rather than live links. Changing one does not mutate projects that previously applied it. --- # Skills Skills add focused practices that are more specific than Agentbriefer's general project policy. They ship inside the CLI as validated `SKILL.md` documents. ## Browse the catalog[​](#browse-the-catalog "Direct link to Browse the catalog") ``` agentbriefer skill list agentbriefer skill list --role frontend agentbriefer skill list --recommended agentbriefer skill list --role security --recommended ``` Role and recommendation filters affect only the current listing. They never change the project's installed skills. ## Inspect before installing[​](#inspect-before-installing "Direct link to Inspect before installing") ``` agentbriefer skill info no-secrets-in-repo ``` Info prints the name, ID, description, category, roles, compatible-stack tags, and full instruction body. ## Add a skill[​](#add-a-skill "Direct link to Add a skill") ``` agentbriefer skill add no-secrets-in-repo ``` This operation: 1. validates the ID against the bundled catalog; 2. appends the ID to `agentbriefer.yaml`; 3. materializes `.agentbriefer/skills//SKILL.md`; 4. synchronizes every configured agent output. Adding an installed skill again is a harmless no-op. Unknown IDs fail with a catalog hint. ## Update installed skill content[​](#update-installed-skill-content "Direct link to Update installed skill content") ``` agentbriefer skill update ``` Update re-materializes configured skills and synchronizes outputs using the catalog bundled in the currently installed CLI. It does not fetch a marketplace or contact a server; upgrade Agentbriefer first to receive newer bundled content. ## Remove a skill[​](#remove-a-skill "Direct link to Remove a skill") ``` agentbriefer skill remove no-secrets-in-repo ``` Removal updates YAML, deletes stale materialized skill directories, and synchronizes outputs. Removing an absent ID warns and succeeds. ## Source of truth[​](#source-of-truth "Direct link to Source of truth") The IDs in `agentbriefer.yaml` are authoritative. Materialized `SKILL.md` files contain a do-not-edit header and are replaced during update. Put project-specific exceptions in `custom_instructions`, not inside generated skill files. See the [v1 skill catalog](/docs/next/reference/skill-catalog.md) for every bundled ID. --- # Stack detection During `init`, Agentbriefer looks for supported manifest files directly in the current directory. A successful detector can prefill: * primary language; * package manager; * framework; * database or data-access library; * testing tools; * up to 20 key direct dependencies; * the manifest used as evidence. The complete ecosystem list is in the [detection matrix](/docs/next/reference/detection-matrix.md). ## Dependency categorization[​](#dependency-categorization "Direct link to Dependency categorization") Each detector has prioritized framework, testing, and database lookup lists. Recognized packages are assigned to those fields; remaining direct dependencies are alphabetized and capped at 20. ``` axum + sqlx + insta + serde ↓ framework: axum database: sqlx testing_tools: [insta] key_dependencies: [serde] ``` ## Detection never blocks init[​](#detection-never-blocks-init "Direct link to Detection never blocks init") Malformed, absent, or unreadable manifests produce an empty detection result. The wizard still runs and accepts manual answers. ## Polyglot repositories[​](#polyglot-repositories "Direct link to Polyglot repositories") Detectors run in a fixed order and the first matching ecosystem wins. Detection is not recursive and does not merge multiple applications in a monorepo. For a Rust API with a nested JavaScript frontend, running `init` at the repository root may detect only the root manifest. Correct the prefilled values or maintain separate configurations at the appropriate project roots. Detection is a starting point 🧭 Press Enter to accept an accurate prefill. Edit it whenever the manifest does not reflect the context you want agents to prioritize. ## Detection and skill recommendations[​](#detection-and-skill-recommendations "Direct link to Detection and skill recommendations") `agentbriefer skill list --recommended` runs detection for the current session and shows skills whose compatible-stack tags intersect the detected tags. A stack-agnostic skill is always recommended. Matching is an **any-tag** intersection. A skill tagged `rust`, `axum`, and `postgres` may be recommended by a Rust project even when Axum and PostgreSQL were not detected. Review the skill with `skill info` before adding it. --- # Team workflow Agentbriefer separates shared repository policy from personal conveniences. ## Commit shared state[​](#commit-shared-state "Direct link to Commit shared state") Commit `agentbriefer.yaml`. It contains the complete developer/project policy, output selection, stop rules, custom instructions, and installed skill IDs. Teams may also commit generated instruction files so agents receive guidance immediately after checkout. If the team chooses not to commit them, document `agentbriefer sync` as a setup step. Materialized `.agentbriefer/skills/` files are reproducible from the config and CLI catalog. Decide as a team whether readable copies should be committed. ## Keep personal state personal[​](#keep-personal-state-personal "Direct link to Keep personal state personal") Developer profiles and skill profiles live in the user's configuration directory and are not part of the repository. Applying either writes explicit values back to project YAML, keeping the shared result visible. `skill list --role` and `--recommended` are browsing filters only. Two teammates can use different filters without changing installed project state. ## Suggested review process[​](#suggested-review-process "Direct link to Suggested review process") When `agentbriefer.yaml` changes, review it like application configuration: * Does a policy conflict with the project's risk level? * Is a new stop rule precise enough to act on? * Does an installed skill fit the actual stack? * Will changing outputs add or remove tool-specific files? * Were generated files synchronized in the same change? ## Example pull-request check[​](#example-pull-request-check "Direct link to Example pull-request check") ``` cargo test --all-targets # project-specific checks, when applicable agentbriefer sync agentbriefer doctor git diff -- agentbriefer.yaml CLAUDE.md AGENTS.md .cursor .github ``` Because doctor warnings do not fail the process, review its output explicitly. --- # How Agentbriefer works Agentbriefer separates project policy from the syntax expected by individual AI tools. ## 1. Initialize the project[​](#1-initialize-the-project "Direct link to 1. Initialize the project") Run `agentbriefer init` from the repository root. Agentbriefer inspects supported manifest files, uses the result as editable prompt defaults, and asks about the project and your preferred agent behavior. The wizard writes `agentbriefer.yaml`. Detection is a convenience, not an uneditable verdict. ## 2. Keep policy in YAML[​](#2-keep-policy-in-yaml "Direct link to 2. Keep policy in YAML") The configuration stores structured choices such as developer style, testing level, dependency policy, architecture style, outputs, stop rules, and installed skill IDs. It does not copy generated skill content into YAML. agentbriefer.yaml ``` developer: style: practical explanation_style: short project: project_type: cli-tool stack: language: rust package_manager: cargo security_level: standard testing_level: practical dependency_policy: explain-first architecture_style: simple skills: - no-secrets-in-repo stop_rules: - Stop before changing the release workflow. ``` ## 3. Render tool-specific files[​](#3-render-tool-specific-files "Direct link to 3. Render tool-specific files") `generate` and `sync` load the same configuration and render the same shared instruction content through Tera templates. Each output adds only the wrapper needed by its target tool. | Tool or convention | Output path | | ------------------- | --------------------------------- | | Claude Code | `CLAUDE.md` | | AGENTS.md consumers | `AGENTS.md` | | Cursor | `.cursor/rules/agentbriefer.mdc` | | GitHub Copilot | `.github/copilot-instructions.md` | ## 4. Resolve skills at render time[​](#4-resolve-skills-at-render-time "Direct link to 4. Resolve skills at render time") Skills ship inside the Agentbriefer binary. The configuration stores their IDs; the renderer resolves those IDs against the current bundled catalog and inlines the instruction body into every configured output. Adding a skill also materializes a readable copy at `.agentbriefer/skills//SKILL.md`. That copy is generated and should not be hand-edited. ## 5. Check drift[​](#5-check-drift "Direct link to 5. Check drift") `agentbriefer doctor` compares configured outputs with a fresh render. It also checks policy conflicts, required fields, and skill IDs missing from the local catalog. note Doctor reports findings but currently exits successfully. Treat it as a diagnostic report, not as a failing CI quality gate. --- # Installation The npm package is the recommended installation path. It installs the native Agentbriefer binary for your supported platform. ## Recommended: npm[​](#recommended-npm "Direct link to Recommended: npm") Requires a maintained Node.js and npm installation. ``` npm install -g agentbriefer agentbriefer --version ``` To try a command without keeping a global installation: ``` npx agentbriefer@latest --version npx agentbriefer@latest skill list ``` Project commands need a project directory Run `init`, `generate`, `sync`, `doctor`, and skill installation commands from the repository you want Agentbriefer to configure. ## Native installer[​](#native-installer "Direct link to Native installer") The v1 GitHub release publishes installers generated by `cargo-dist`. * macOS / Linux * Windows PowerShell ``` curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/dexterhere/agentbriefer/releases/latest/download/agentbriefer-installer.sh | sh ``` ``` powershell -ExecutionPolicy ByPass -c "irm https://github.com/dexterhere/agentbriefer/releases/latest/download/agentbriefer-installer.ps1 | iex" ``` After installation, open a new terminal and verify: ``` agentbriefer --version ``` ## GitHub release archives[​](#github-release-archives "Direct link to GitHub release archives") Download a platform archive and checksum from the [latest GitHub release](https://github.com/dexterhere/agentbriefer/releases/latest). Extract the `agentbriefer` executable into a directory on your `PATH`. | Operating system | Architecture | | ---------------- | ------------------------------------------- | | macOS | Apple Silicon (`aarch64`), Intel (`x86_64`) | | Linux | ARM64 (`aarch64`), Intel/AMD (`x86_64`) | | Windows | Intel/AMD (`x86_64`) | Windows ARM64 and 32-bit targets are not published in v1. ## Install with Cargo[​](#install-with-cargo "Direct link to Install with Cargo") Rust users can install the tagged source directly from GitHub: ``` cargo install --git https://github.com/dexterhere/agentbriefer.git \ --tag v1.0.0 agentbriefer ``` Agentbriefer is not currently published to crates.io, so `cargo install agentbriefer` by itself is not a supported v1 method. ## Build from source[​](#build-from-source "Direct link to Build from source") Requires the stable Rust toolchain and Git. ``` git clone https://github.com/dexterhere/agentbriefer.git cd agentbriefer cargo test --all-targets cargo install --path . ``` ## Upgrade[​](#upgrade "Direct link to Upgrade") * npm * Native installer * Cargo ``` npm install -g agentbriefer@latest ``` Run the platform installer again. It replaces the installed binary with the current release. ``` cargo install --git https://github.com/dexterhere/agentbriefer.git \ --tag v1.0.0 agentbriefer --force ``` ## Uninstall[​](#uninstall "Direct link to Uninstall") Use the same ecosystem that installed Agentbriefer: ``` # npm npm uninstall -g agentbriefer # Cargo cargo uninstall agentbriefer ``` For a manual archive installation, delete the executable you placed on `PATH`. User profiles under your platform configuration directory are not removed automatically. ## PATH troubleshooting[​](#path-troubleshooting "Direct link to PATH troubleshooting") If installation succeeds but the command is unavailable: ``` # npm global binary directory npm prefix -g # Cargo binary directory (normally) echo "$HOME/.cargo/bin" ``` Ensure the relevant binary directory is on `PATH`, restart the terminal, then run `agentbriefer --version`. See [Troubleshooting](/docs/next/troubleshooting.md) for additional recovery steps. --- # Meet Agentbriefer Agentbriefer is a command-line tool that gives AI coding agents a consistent, project-specific operating brief. You describe how work should be approached once in `agentbriefer.yaml`; Agentbriefer turns that configuration into the instruction files Claude Code, AGENTS.md-compatible tools, Cursor, and GitHub Copilot already understand. ``` agentbriefer.yaml ↓ Agentbriefer renderer + installed skills ↓ CLAUDE.md Β· AGENTS.md Β· Cursor rules Β· Copilot instructions ``` ## The problem it solves[​](#the-problem-it-solves "Direct link to The problem it solves") AI agents can be productive and still behave inconsistently. One session may make a focused change; another may add dependencies, refactor unrelated code, or continue beyond the requested scope. Repeating the same expectations in every prompt is tedious, easy to forget, and difficult to share with a team. Agentbriefer makes those expectations explicit and reviewable: * how much architecture the agent should introduce; * when dependencies require an explanation or approval; * how security-sensitive changes should be treated; * how much testing is expected; * how detailed explanations should be; * when the agent must stop and ask; * which focused skills apply to the project. ## When Agentbriefer is useful[​](#when-agentbriefer-is-useful "Direct link to When Agentbriefer is useful") * **One developer, several tools:** keep Claude Code, Cursor, and Copilot aligned. * **A shared repository:** review agent policy like any other project configuration. * **Security-sensitive work:** make conservative auth, secret, permission, and validation behavior explicit. * **A mixed-experience team:** choose learning-focused or concise explanations without rewriting prompts. * **Repeated project setup:** reuse developer profiles and named skill sets. * **Existing handwritten guidance:** use `sync` to preserve content outside Agentbriefer's managed block. ## What it is not[​](#what-it-is-not "Direct link to What it is not") Agentbriefer does not run an autonomous agent, execute prompts, create pull requests, store cloud memory, or replace your coding assistant. It prepares the repository-level context those assistants consume. The shortest mental model πŸ’‘ Agentbriefer is a compiler for agent instructions: YAML and bundled skills go in; tool-specific Markdown and rules files come out. ## Continue[​](#continue "Direct link to Continue") Start with [Installation](/docs/next/installation.md), follow the [Quick start](/docs/next/quick-start.md), or read [How it works](/docs/next/how-it-works.md) for the full data flow. --- # Quick start This walkthrough configures one project, generates all four supported output formats, adds a security skill, and verifies the result. ## 1. Install and enter your project[​](#1-install-and-enter-your-project "Direct link to 1. Install and enter your project") ``` npm install -g agentbriefer cd path/to/your-project ``` ## 2. Run the setup wizard[​](#2-run-the-setup-wizard "Direct link to 2. Run the setup wizard") ``` agentbriefer init ``` When Agentbriefer recognizes a project manifest, it announces the detected language and pre-fills stack questions. Press Enter to accept a value or edit it. The wizard covers: 1. developer and explanation styles; 2. language, framework, database, package manager, tests, and dependencies; 3. project type and architecture expectations; 4. security, testing, and dependency policies; 5. custom instructions and stop rules; 6. output formats; 7. a review screen where every answer remains editable. It writes `agentbriefer.yaml` in the current directory. ## 3. Generate instruction files[​](#3-generate-instruction-files "Direct link to 3. Generate instruction files") ``` agentbriefer generate ``` With the default output selection, the project now contains: ``` your-project/ β”œβ”€β”€ agentbriefer.yaml β”œβ”€β”€ CLAUDE.md β”œβ”€β”€ AGENTS.md β”œβ”€β”€ .cursor/rules/agentbriefer.mdc └── .github/copilot-instructions.md ``` ## 4. Add a focused skill[​](#4-add-a-focused-skill "Direct link to 4. Add a focused skill") ``` agentbriefer skill list --recommended agentbriefer skill add no-secrets-in-repo ``` Adding a skill updates `agentbriefer.yaml`, creates `.agentbriefer/skills/no-secrets-in-repo/SKILL.md`, and synchronizes all configured output files. ## 5. Verify the project[​](#5-verify-the-project "Direct link to 5. Verify the project") ``` agentbriefer doctor ``` A clean project prints `No issues found.` Doctor reports warnings rather than returning a failing status code. ## 6. Choose the right regeneration command[​](#6-choose-the-right-regeneration-command "Direct link to 6. Choose the right regeneration command") * Continue using `generate` if the outputs are entirely machine-owned. * Switch to `sync` before adding manual notes outside Agentbriefer's managed markers. ``` agentbriefer sync ``` Generate overwrites the whole file After you add manual content around a managed block, use `sync`. A later `generate` does not preserve those additions. ## Next steps[​](#next-steps "Direct link to Next steps") * Understand [generate versus sync](/docs/next/guides/generate-vs-sync.md). * Browse the [skill guide](/docs/next/guides/skills.md). * Review a complete [configuration reference](/docs/next/reference/configuration.md). * Explore real [use cases and examples](/docs/next/examples/overview.md). --- # Command reference Agentbriefer uses the following command shape: ``` agentbriefer ``` Use `agentbriefer help`, `agentbriefer --help`, or `agentbriefer skill --help` for the reference shipped with your installed version. The root command supports `-h, --help` and `-V, --version`. Run project commands from the directory that contains `agentbriefer.yaml`. ## Core commands[​](#core-commands "Direct link to Core commands") ### `init`[​](#init "Direct link to init") Interactively inspect a project and create `agentbriefer.yaml`. ``` agentbriefer init ``` The wizard proposes values based on detected manifests and lets you choose generated outputs, developer preferences, stop rules, and skills. ### `generate`[​](#generate "Direct link to generate") Render configured AI instruction files from `agentbriefer.yaml`. ``` agentbriefer generate ``` Generation replaces the selected output files. Use [`sync`](#sync) when an existing file contains human-maintained content that must remain outside Agentbriefer's managed section. ### `sync`[​](#sync "Direct link to sync") Refresh only the Agentbriefer-managed section in each configured output. ``` agentbriefer sync ``` When a file has no managed section, Agentbriefer appends one without deleting the existing content. ### `doctor`[​](#doctor "Direct link to doctor") Validate configuration, skills, profiles, output paths, and generated content. ``` agentbriefer doctor ``` Run this after configuration changes and in pull-request checks. Errors require attention; warnings usually identify stale or incomplete project context. ### `profile list`[​](#profile-list "Direct link to profile-list") List saved developer profiles. ``` agentbriefer profile list ``` ### `profile create`[​](#profile-create "Direct link to profile-create") Interactively save a reusable developer style and explanation style. ``` agentbriefer profile create ``` ### `profile switch`[​](#profile-switch "Direct link to profile-switch") Interactively choose a saved profile and copy it into the current project. ``` agentbriefer profile switch ``` Switch updates `agentbriefer.yaml` but does not regenerate outputs. Run `agentbriefer sync` next. ## Skill commands[​](#skill-commands "Direct link to Skill commands") ### `skill list`[​](#skill-list "Direct link to skill-list") List bundled and locally installed skills. ``` agentbriefer skill list ``` ### `skill add `[​](#skill-add-id "Direct link to skill-add-id") Install a bundled skill into the current project. ``` agentbriefer skill add no-secrets-in-repo ``` ### `skill remove `[​](#skill-remove-name "Direct link to skill-remove-name") Remove an installed skill from the current project. ``` agentbriefer skill remove no-secrets-in-repo ``` Bundled skills remain part of the Agentbriefer binary and can be installed again later. ### `skill update`[​](#skill-update "Direct link to skill-update") Re-materialize all installed skills from the catalog in the current binary and synchronize outputs. ``` agentbriefer skill update ``` ### `skill info `[​](#skill-info-name "Direct link to skill-info-name") Show a skill's metadata and source. ``` agentbriefer skill info no-secrets-in-repo ``` ### `skill profile list`[​](#skill-profile-list "Direct link to skill-profile-list") List reusable skill profiles. ``` agentbriefer skill profile list ``` ### `skill profile create `[​](#skill-profile-create-name "Direct link to skill-profile-create-name") Create a named profile from selected skills. ``` agentbriefer skill profile create secure-api ``` ### `skill profile apply `[​](#skill-profile-apply-name "Direct link to skill-profile-apply-name") Apply a profile to the current project's `agentbriefer.yaml`. ``` agentbriefer skill profile apply secure-api ``` Review the changed configuration, then run `agentbriefer doctor` and `agentbriefer sync`. ## Exit behavior[​](#exit-behavior "Direct link to Exit behavior") Agentbriefer exits with a non-zero status when a command cannot complete or configuration cannot be loaded. `doctor` findings are currently diagnostic warnings and do not make the command fail, so CI must review its output explicitly. --- # Configuration schema `agentbriefer.yaml` is the source of truth for a project's generated instructions. Commit it so the team reviews changes to agent behavior like any other development policy. ## Complete example[​](#complete-example "Direct link to Complete example") agentbriefer.yaml ``` developer: style: practical explanation_style: tradeoff-based project: project_type: backend-api stack: language: rust framework: axum database: postgresql testing_tools: - cargo test package_manager: cargo key_dependencies: - tokio - serde architecture_style: simple-layered security_level: strict testing_level: practical dependency_policy: explain-first stop_rules: - Stop before changing the public API. - Stop before adding a production dependency. skills: - secure-api - testing custom_instructions: | Prefer small, reviewable patches. Keep database migrations backward compatible. outputs: - agents-md - claude-md - cursor-rules - copilot-instructions ``` ## Top-level fields[​](#top-level-fields "Direct link to Top-level fields") | Field | Required | Description | | --------------------- | -------- | ---------------------------------------------------------------------- | | `extends` | No | Reusable developer profile to inherit before applying project values. | | `developer` | Yes | Preferred working and explanation styles. | | `project` | Yes | Project type and detected or curated stack context. | | `stop_rules` | No | Explicit conditions that require the agent to pause. Defaults to `[]`. | | `skills` | No | Ordered names of bundled or installed skills. Defaults to `[]`. | | `custom_instructions` | No | Project-specific guidance that does not fit another field. | | `outputs` | No | Files to generate. Defaults to all supported outputs. | Use only the documented field names. YAML syntax and invalid enum values are rejected; review the generated result because unrecognized extra mapping fields are not part of the supported schema. ## Developer preferences[​](#developer-preferences "Direct link to Developer preferences") ### `developer.style`[​](#developerstyle "Direct link to developerstyle") Choose one of: * `minimal` * `practical` * `learning-focused` * `enterprise` * `security-first` ### `developer.explanation_style`[​](#developerexplanation_style "Direct link to developerexplanation_style") Choose one of: * `short` * `beginner-friendly` * `detailed` * `tradeoff-based` ## Project values[​](#project-values "Direct link to Project values") ### `project.project_type`[​](#projectproject_type "Direct link to projectproject_type") Choose one of: * `backend-api` * `frontend-app` * `cli-tool` * `full-stack-app` * `library` * `documentation-heavy` ### `project.stack`[​](#projectstack "Direct link to projectstack") `language` is required. `framework`, `database`, `package_manager`, and `key_dependencies` are optional context; `testing_tools` and `key_dependencies` default to empty lists. Detection is a starting point, not a constraint. Keep product-specific details that a manifest cannot infer, and remove incidental dependencies that should not influence agent decisions. ## Policy values[​](#policy-values "Direct link to Policy values") | Field | Supported values | | ---------------------------- | ------------------------------------------------------- | | `project.architecture_style` | `simple`, `simple-layered`, `feature-based`, `advanced` | | `project.security_level` | `basic`, `standard`, `strict` | | `project.testing_level` | `light`, `practical`, `strict` | | `project.dependency_policy` | `allow`, `explain-first`, `ask-first` | ## Output values[​](#output-values "Direct link to Output values") | Value | Generated path | | ---------------------- | --------------------------------- | | `agents-md` | `AGENTS.md` | | `claude-md` | `CLAUDE.md` | | `cursor-rules` | `.cursor/rules/agentbriefer.mdc` | | `copilot-instructions` | `.github/copilot-instructions.md` | See [Outputs](/docs/next/reference/outputs.md) for platform behavior and safe synchronization. ## Precedence[​](#precedence "Direct link to Precedence") `extends` records which saved developer profile was copied into the project. It is informational: generation does not resolve or merge the saved profile again. The concrete `developer` values in the project are always authoritative. Skills are resolved in their configured order at render time. After any manual edit, run: ``` agentbriefer doctor agentbriefer sync ``` --- # Detection matrix Agentbriefer inspects common project manifests during `init`. Detection fills in an editable draft; it never replaces your judgment about the project's intended architecture or policy. | Ecosystem | Signals | Typical package manager | | -------------------- | ----------------------------------------------- | ----------------------------- | | Rust | `Cargo.toml` | Cargo | | Node.js / TypeScript | `package.json` and lockfiles | npm, pnpm, Yarn, or Bun | | Go | `go.mod` | Go modules | | Python | `pyproject.toml`, `requirements.txt` | Project-dependent | | PHP | `composer.json` | Composer | | Java / Maven | `pom.xml` | Maven | | C# | `*.csproj` | NuGet / dotnet | | F# | `*.fsproj` | NuGet / dotnet | | Dart | `pubspec.yaml` | pub | | Julia | `Project.toml` | Pkg | | Crystal | `shard.yml` | Shards | | Haskell | `package.yaml`, `*.cabal`, `stack.yaml` | Cabal or Stack | | R | `DESCRIPTION`, `renv.lock` | renv when present | | Ruby | `Gemfile`, `Gemfile.lock` | Bundler | | Swift | `Package.swift` | Swift Package Manager | | Scala | `build.sbt` | sbt | | JVM / Gradle | `build.gradle`, `build.gradle.kts` | Gradle | | C / C++ | `vcpkg.json`, `conanfile.txt`, `CMakeLists.txt` | vcpkg, Conan, or CMake | | Elixir | `mix.exs` | Mix | | Clojure | `deps.edn`, `project.clj` | Clojure CLI or Leiningen | | Erlang | `rebar.config` | Rebar3 | | Objective-C | `Podfile` | CocoaPods | | Lua | `*.rockspec` | LuaRocks | | Perl | `cpanfile` | cpanm / Carton | | Visual Basic .NET | `*.vbproj` | NuGet / dotnet | | Nim | `*.nimble` | Nimble | | PowerShell | `*.psd1` | PowerShellGet / PSResourceGet | | Zig | `build.zig.zon` | Zig package manager | ## Monorepos and mixed stacks[​](#monorepos-and-mixed-stacks "Direct link to Monorepos and mixed stacks") If several signals exist, Agentbriefer combines the evidence it understands and presents a proposal. Run `init` from the directory whose scope should receive the generated instructions: ``` cd ./services/payments agentbriefer init ``` For a repository-wide policy plus package-specific policy, maintain an Agentbriefer configuration at each intentional instruction boundary. --- # Files and safety Agentbriefer is local-first. It inspects project files, stores configuration and reusable data on your machine, and writes the instruction outputs you select. ## Project files[​](#project-files "Direct link to Project files") | Path | Ownership | | --------------------------------- | ----------------------------------------- | | `agentbriefer.yaml` | Human-reviewed Agentbriefer configuration | | `AGENTS.md` | Generated or synchronized output | | `CLAUDE.md` | Generated or synchronized output | | `.cursor/rules/agentbriefer.mdc` | Generated or synchronized output | | `.github/copilot-instructions.md` | Generated or synchronized output | Project manifests and lockfiles are read for stack detection. Agentbriefer does not modify them. ## User data[​](#user-data "Direct link to User data") Installed skills and reusable developer or skill profiles live in the operating system's standard per-user application data directory. The exact base directory follows the platform conventions resolved for Agentbriefer, rather than assuming a hard-coded home path. Back up custom skills and profiles if they are important organizational assets. Prefer keeping their source in a version-controlled repository and installing from that source. ## Preservation rules[​](#preservation-rules "Direct link to Preservation rules") * `generate` owns the complete selected output. * `sync` changes only Agentbriefer's marked section and retains surrounding content. * Required parent directories are created when needed. * Symbolic-link output paths are refused to avoid writing through an unexpected target. * Invalid YAML, missing profiles, and unresolved skills are reported instead of silently rewriting intent. An unknown skill is excluded from rendering and reported by validation. Run `doctor` before relying on newly generated output. ## Source-control checklist[​](#source-control-checklist "Direct link to Source-control checklist") Commit `agentbriefer.yaml` and the generated files your team consumes. Do not commit private custom skill content or profile data unless it is intentionally safe for every repository reader. Before merging a policy change: ``` agentbriefer doctor agentbriefer sync git diff --check ``` Review the semantic change in the generated instructionsβ€”not just whether generation succeeded. --- # Outputs Agentbriefer turns one project profile into native instruction files for four AI coding ecosystems. Select only the tools your project uses, or keep all outputs to offer contributors a consistent experience. | Configuration value | Path | Intended consumer | | ---------------------- | --------------------------------- | ---------------------------------------------- | | `agents-md` | `AGENTS.md` | Agents that implement the AGENTS.md convention | | `claude-md` | `CLAUDE.md` | Claude Code | | `cursor-rules` | `.cursor/rules/agentbriefer.mdc` | Cursor | | `copilot-instructions` | `.github/copilot-instructions.md` | GitHub Copilot | ## Generate or synchronize[​](#generate-or-synchronize "Direct link to Generate or synchronize") `agentbriefer generate` renders a complete Agentbriefer-owned file. It is the clearest choice for a new output or a file the team intends to manage entirely from configuration. `agentbriefer sync` updates the marked Agentbriefer section and preserves content outside it. Use it when a file also contains carefully maintained human instructions. ``` # First creation agentbriefer generate # Subsequent update that preserves surrounding content agentbriefer sync ``` ## Nested paths[​](#nested-paths "Direct link to Nested paths") Agentbriefer creates required parent directories for Cursor and GitHub output paths. If an output path is a symbolic link, it resolves and writes to the final target rather than replacing the link. ## Reviewing changes[​](#reviewing-changes "Direct link to Reviewing changes") Treat generated instructions as source-controlled artifacts: ``` agentbriefer doctor agentbriefer sync git diff -- agentbriefer.yaml AGENTS.md CLAUDE.md .cursor .github ``` This makes changes visible to reviewers and keeps agent behavior reproducible across machines. ## Tool-specific additions[​](#tool-specific-additions "Direct link to Tool-specific additions") If a platform needs unique guidance, add it outside the managed markers and use `sync`. Put shared policy in `agentbriefer.yaml`, a reusable profile, or a skill so it does not drift between outputs. --- # Bundled skill catalog Agentbriefer v1 bundles seven skills inside the binary. They require no separate download and are installed into a project by ID. | Skill ID | Category | Use it when | | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `docker-compose-for-local-dev` | Backend | Local infrastructure should stay minimal, configurable, healthy, and free of committed secrets. | | `rust-axum-layered-structure` | Backend | An Axum service needs light handler, service, and data boundaries without premature abstractions. | | `css-first-motion` | Frontend | UI animation should prefer CSS and respect reduced-motion preferences. | | `server-components-by-default` | Frontend | A Next.js or React project should keep client components small and intentional. | | `sveltekit-component-structure` | Frontend | A SvelteKit app needs thin routes and well-placed components, stores, and API helpers. | | `no-secrets-in-repo` | Security | Every stack should keep keys, tokens, and credentials out of tracked files. | | `password-and-session-auth` | Security | A Rust/Axum/PostgreSQL backend owns password, cookie, session, or token behavior. | ## Browse and inspect[​](#browse-and-inspect "Direct link to Browse and inspect") ``` agentbriefer skill list agentbriefer skill list --recommended agentbriefer skill info no-secrets-in-repo ``` `--role` and `--recommended` filter only the displayed catalog. They never install a skill or change the shared project configuration. ## Choose a focused set[​](#choose-a-focused-set "Direct link to Choose a focused set") Skills add specialized guidance to every selected output, so install only rules that repeatedly apply to the repository. ``` agentbriefer skill add rust-axum-layered-structure agentbriefer skill add no-secrets-in-repo ``` The IDs are stored in `agentbriefer.yaml`, materialized under `.agentbriefer/skills/`, and inlined into generated instructions. See [Skills](/docs/next/guides/skills.md) for the full lifecycle. --- # Agentbriefer v1 πŸŽ‰ Agentbriefer v1 is the first stable release of the project policy compiler for AI coding agents. ## Highlights[​](#highlights "Direct link to Highlights") * Interactive project initialization with editable detection across 28 ecosystems. * One typed `agentbriefer.yaml` for developer style, project policy, stop rules, custom guidance, and outputs. * Native instruction generation for Claude Code, AGENTS.md consumers, Cursor, and GitHub Copilot. * Safe managed-block synchronization for files that also contain handwritten guidance. * Reusable developer profiles and named skill profiles. * Seven embedded skills with role and stack recommendation filters. * Read-only diagnostics for policy conflicts, missing files, unknown skills, and output drift. * Native release artifacts for macOS, Linux, and Windows plus shell, PowerShell, and npm installers. ## Compatibility notes[​](#compatibility-notes "Direct link to Compatibility notes") The v1 configuration file is named `agentbriefer.yaml`. Skill content is bundled with the installed binary; `skill update` re-materializes that catalog and does not fetch a remote marketplace. `doctor` findings are diagnostic in v1 and do not change the command's successful exit status. ## Upgrade checklist[​](#upgrade-checklist "Direct link to Upgrade checklist") ``` npm install -g agentbriefer@latest agentbriefer --version agentbriefer skill update agentbriefer doctor ``` Review synchronized output changes before committing them, especially when upgrading from a build that predates skills. --- # Troubleshooting Start with the installed help and the read-only project diagnostic: ``` agentbriefer --version agentbriefer --help agentbriefer doctor ``` ## Command not found after installation[​](#command-not-found-after-installation "Direct link to Command not found after installation") Open a new terminal, then check the binary directory for your installation method. ``` npm prefix -g echo "$HOME/.cargo/bin" ``` Add the applicable binary directory to `PATH`. On Windows, reopen PowerShell after the installer updates the environment. ## No `agentbriefer.yaml` found[​](#no-agentbrieferyaml-found "Direct link to no-agentbrieferyaml-found") Project commands resolve the current working directory. Change to the configured repository root or initialize the current directory: ``` cd path/to/project agentbriefer init ``` ## YAML cannot be parsed[​](#yaml-cannot-be-parsed "Direct link to YAML cannot be parsed") Compare the file with the [configuration schema](/docs/next/reference/configuration.md). Common causes are incorrect indentation, a policy field placed outside `project`, or a list written as a scalar. If the file is disposable, move it aside and rerun `init`; otherwise fix the YAML and run `doctor`. ## Generated output is stale[​](#generated-output-is-stale "Direct link to Generated output is stale") Refresh configured files and check again: ``` agentbriefer sync agentbriefer doctor ``` If a file has no valid managed block, sync warns and replaces its contents. Back up valuable manual content first, establish the managed block, then restore the manual content outside the markers. ## Manual output edits disappeared[​](#manual-output-edits-disappeared "Direct link to Manual output edits disappeared") `generate` replaces a complete output. Only `sync` preserves text outside managed markers. Recover the previous file from source control, run `sync` to add a managed block, and keep restored notes outside it. ## A symlink output is refused[​](#a-symlink-output-is-refused "Direct link to A symlink output is refused") Agentbriefer will not write through an output path whose final file is a symbolic link. Replace it with a regular file in the project, then rerun the command. This boundary prevents an instruction path from redirecting writes somewhere unexpected. ## Skill is unknown[​](#skill-is-unknown "Direct link to Skill is unknown") The project may reference an ID that is not bundled with the installed CLI version. ``` agentbriefer skill list agentbriefer --version ``` Upgrade Agentbriefer if a teammate used a newer catalog. Otherwise correct or remove the invalid ID in `agentbriefer.yaml`, then run `agentbriefer skill update`. ## Recommended skills look unrelated[​](#recommended-skills-look-unrelated "Direct link to Recommended skills look unrelated") Recommendations match when any compatible stack tag intersects detected language, framework, database, package manager, test tool, or dependency tags. Inspect before installing: ``` agentbriefer skill list --recommended agentbriefer skill info ``` ## Doctor reports warnings but exits successfully[​](#doctor-reports-warnings-but-exits-successfully "Direct link to Doctor reports warnings but exits successfully") That is the v1 behavior: findings are diagnostic and do not set a failing exit code. Review the output explicitly in CI rather than treating process success as a clean report. ## Still blocked[​](#still-blocked "Direct link to Still blocked") Collect the output of `agentbriefer --version`, the relevant command, and a redacted configuration, then [open a GitHub issue](https://github.com/dexterhere/agentbriefer/issues). Never include secrets or private skill content in a public report. --- # Architecture Agentbriefer is a Rust CLI organized around pure configuration, detection, rendering, and skill components, with the `cli` module owning interactive behavior and real filesystem operations. ## Modules[​](#modules "Direct link to Modules") ### `config`[​](#config "Direct link to config") Defines the typed YAML schema and generic load/save operations. It turns a path into a validated Rust value or serializes a value back to YAML. Project location and prompting remain outside it. ### `detect`[​](#detect "Direct link to detect") Contains one detector per supported ecosystem plus shared dependency categorization. Detection reads manifest evidence from the current directory and returns an optional `DetectedStack`; it does not write configuration. ### `skills`[​](#skills "Direct link to skills") Loads `skills/**/SKILL.md` through `rust-embed`, parses YAML frontmatter and Markdown bodies, validates directory/ID agreement, sorts the catalog, and provides role and stack recommendation queries. ### `render`[​](#render "Direct link to render") Registers embedded Tera templates once, serializes configuration and resolved skills into a rendering context, and returns text for an `OutputFormat`. It does not choose destinations or write files. ### `cli`[​](#cli "Direct link to cli") Owns clap dispatch, prompts, terminal presentation, current-directory resolution, per-user profile paths, materialized skills, and output writes. Command modules compose the pure components and report partial per-format failures. ### `textutil`[​](#textutil "Direct link to textutil") Provides shared frontmatter splitting used by skill parsing and synchronized Cursor output handling. ## Embedded assets[​](#embedded-assets "Direct link to Embedded assets") `templates/` and `skills/` are read directly in debug builds and embedded into release binaries. A released executable therefore needs no runtime template or catalog directory. ## Write models[​](#write-models "Direct link to Write models") * `generate` renders and replaces every selected output. * `sync` preserves text outside line-delimited managed markers. * skill commands materialize catalog entries under `.agentbriefer/skills/` and synchronize outputs. * developer profiles and skill profiles use platform-standard per-user configuration directories. The repository-level [architecture note](https://github.com/dexterhere/agentbriefer/blob/main/docs/ARCHITECTURE.md) is maintained alongside this page for contributors browsing the source tree. --- # Development setup ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * a stable Rust toolchain with `rustfmt` and `clippy`; * Git; * Node.js 20 or newer for the documentation site. ## Build the CLI[​](#build-the-cli "Direct link to Build the CLI") ``` git clone https://github.com/dexterhere/agentbriefer.git cd agentbriefer cargo build cargo run -- --help ``` Run project commands against a disposable fixture directory because `init`, `generate`, `sync`, and skill lifecycle commands write files in the current directory. ## Quality checks[​](#quality-checks "Direct link to Quality checks") ``` cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test --all-targets ``` Unit tests live beside their modules. End-to-end CLI behavior lives in `tests/cli_integration.rs`, and rendered output is protected by `insta` snapshots under `src/render/snapshots/`. When a deliberate template change modifies snapshots, review the semantic diff before accepting it. ## Run the documentation[​](#run-the-documentation "Direct link to Run the documentation") ``` cd docs-site npm install npm start ``` Before submitting documentation changes: ``` npm run typecheck npm run build ``` The production build checks internal links and emits the local search index, sitemap, and AI-readable documentation files. --- # Documentation workflow The Docusaurus site lives in `docs-site/` within the CLI repository so documentation can be reviewed and versioned with the behavior it describes. ## Writing standards[​](#writing-standards "Direct link to Writing standards") * Lead with the user's goal and show commands that can be copied safely. * Verify names, flags, paths, defaults, and exit behavior against the Rust source or `--help`. * Use emoji sparingly as wayfinding, not as a replacement for labels. ✨ * Include realistic snippets without credentials, tokens, or private repository details. * Link to the canonical reference instead of duplicating long schemas. * Update both user and contributor material when a change affects both audiences. ## Local workflow[​](#local-workflow "Direct link to Local workflow") ``` cd docs-site npm install npm start ``` Edit current documentation in `docs/`. Docusaurus reloads pages during development. Before commit: ``` npm run typecheck npm run build ``` The build is configured to fail on broken links and anchors. ## Create a release snapshot[​](#create-a-release-snapshot "Direct link to Create a release snapshot") With the current docs describing the release: ``` npm run docusaurus docs:version 1.0.0 ``` Then configure `1.0.0` as the latest stable version and current docs as **Next**. Keep release notes inside the snapshot and continue future work only in `docs/`. ## Deployment[​](#deployment "Direct link to Deployment") Vercel can deploy this static site from the monorepo by setting the project root to `docs-site`. The repository includes `docs-site/vercel.json` and a maintainer runbook in `docs-site/DEPLOYMENT.md`. Deploy previews should build every pull request; production should track the chosen release branch. --- # Extending Agentbriefer Keep new functionality in the narrowest subsystem that owns it and add tests at the same boundary. ## Add a bundled skill[​](#add-a-bundled-skill "Direct link to Add a bundled skill") Create `skills///SKILL.md`. The directory name and frontmatter `id` must match. skills/security/example-policy/SKILL.md ``` --- id: example-policy name: Example Policy description: One sentence describing the behavior this skill enforces. category: security roles: [security, backend] compatible_stacks: [rust, axum] --- Write direct, actionable instructions for the coding agent here. ``` Use lowercase kebab-case IDs. `roles` are browsing tags. `compatible_stacks` participate in case-insensitive any-tag recommendation matching; an empty list makes the skill stack-agnostic. Then test the registry and update the public catalog: ``` cargo test skills cargo test --test cli_integration ``` ## Add or improve a detector[​](#add-or-improve-a-detector "Direct link to Add or improve a detector") Implement an ecosystem module under `src/detect/`, expose it through `src/detect/mod.rs`, and preserve the detector order intentionally because the first matching ecosystem wins. A detector should: * return no match when its root manifest is absent; * tolerate malformed input without preventing `init`; * identify package manager, framework, database, tests, and key direct dependencies when evidence is reliable; * keep dependency output deterministic and bounded. Add focused unit fixtures and update the [detection matrix](/docs/reference/detection-matrix.md). ## Add an output format[​](#add-an-output-format "Direct link to Add an output format") Add the `OutputFormat` enum value and path mapping, a top-level Tera template, prompt support, and generate/sync/doctor coverage. Reuse shared template partials so behavioral policy does not drift between tools. Document the consumer and output path. ## Change configuration[​](#change-configuration "Direct link to Change configuration") Schema changes affect YAML compatibility, templates, interactive prompts, profiles, snapshots, and the documentation reference. For v1 maintenance releases, prefer optional fields with safe serde defaults. Treat renamed or reinterpreted values as compatibility-sensitive changes. --- # Testing and release ## Validation layers[​](#validation-layers "Direct link to Validation layers") Run the complete Rust gate: ``` cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test --all-targets ``` Run the documentation gate: ``` cd docs-site npm ci npm run typecheck npm run build ``` Also exercise `agentbriefer init`, `generate`, `sync`, `doctor`, and the skill lifecycle in a temporary project when user-visible workflows change. ## Release checklist[​](#release-checklist "Direct link to Release checklist") 1. Set the same semantic version in `Cargo.toml`, the changelog, and the release notes. 2. Verify generated snapshots and documentation examples against the current clap help. 3. Build docs and confirm stable plus Next navigation, local search, sitemap, `llms.txt`, and `llms-full.txt`. 4. Run the Rust validation gate on a clean checkout. 5. Review `dist-workspace.toml` targets and installers. 6. Create and push the matching Git tag only after the release commit is approved. 7. Verify the GitHub release archives, checksums, shell and PowerShell installers, and npm package. 8. Smoke-test `agentbriefer --version` and `agentbriefer skill list` through at least one published installation path. The generated cargo-dist workflow builds macOS ARM64/x64, Linux ARM64/x64, and Windows x64 artifacts, then publishes GitHub-hosted installers and the npm package. Tagging and publishing change external state and remain a maintainer-controlled action. ## Versioned docs[​](#versioned-docs "Direct link to Versioned docs") Stable documentation is a snapshot under `versioned_docs/version-/`. Ongoing source docs under `docs/` appear as **Next**. Create a new snapshot only for a real release boundary; do not edit an old snapshot to describe later behavior. --- # Use cases and examples These examples start from a real goal and show the resulting configuration and workflowβ€”not just isolated command syntax. | Goal | Example | | ------------------------------------------- | --------------------------------------------------------------- | | Keep several coding assistants aligned | [Solo multi-agent workflow](/docs/examples/solo-multi-agent.md) | | Establish strict team security boundaries | [Team security policy](/docs/examples/team-security.md) | | Combine stack detection with focused skills | [Stack-specific skills](/docs/examples/stack-skills.md) | | Reuse preferences and preserve manual notes | [Profiles and sync](/docs/examples/profiles-and-sync.md) | ## A useful baseline[​](#a-useful-baseline "Direct link to A useful baseline") Most projects can begin with: ``` developer: style: practical explanation_style: short project: project_type: library stack: language: rust package_manager: cargo security_level: standard testing_level: practical dependency_policy: explain-first architecture_style: simple stop_rules: [] skills: - no-secrets-in-repo ``` Then change only settings that express a real project constraint. More strict is not automatically more useful; the best brief is the one the team will follow and review. --- # Profiles, skill sets, and manual notes This workflow separates three concerns: * personal communication preferences in a developer profile; * reusable technical guidance in a skill profile; * repository-specific notes outside a managed output block. ## Save personal preferences[​](#save-personal-preferences "Direct link to Save personal preferences") ``` agentbriefer profile create # Name: practical-short # Style: practical # Explanation style: short ``` Future `init` runs can copy that profile without hiding the values from project YAML. ## Save a skill set[​](#save-a-skill-set "Direct link to Save a skill set") After configuring a representative frontend project: ``` agentbriefer skill add server-components-by-default agentbriefer skill add css-first-motion agentbriefer skill add no-secrets-in-repo agentbriefer skill profile create frontend-basics ``` Apply it to another configured project: ``` agentbriefer skill profile apply frontend-basics ``` Remember that apply replaces the complete skills list. ## Preserve handwritten instructions[​](#preserve-handwritten-instructions "Direct link to Preserve handwritten instructions") Run sync once, then add notes outside the block: AGENTS.md ``` # Repository note The `fixtures/legacy` directory is an external compatibility corpus. Do not reformat it. Generated project guidance... ``` Now configuration changes are safe to merge: ``` agentbriefer sync agentbriefer doctor ``` The compatibility note survives while the managed section reflects current policy and skills. --- # Solo developer, several agents You use different AI tools for different tasks but want the same scope, dependency, testing, and explanation expectations everywhere. ## Configure once[​](#configure-once "Direct link to Configure once") ``` cd my-project agentbriefer init agentbriefer generate ``` Choose all four outputs and a practical, concise profile: agentbriefer.yaml ``` developer: style: practical explanation_style: short project: project_type: full-stack-app stack: language: typescript framework: next testing_tools: - vitest - playwright package_manager: npm key_dependencies: - react security_level: standard testing_level: practical dependency_policy: explain-first architecture_style: feature-based stop_rules: - Ask before changing a public API contract. skills: - server-components-by-default - css-first-motion outputs: - claude-md - agents-md - cursor-rules - copilot-instructions ``` ## Result[​](#result "Direct link to Result") * Claude Code reads `CLAUDE.md`. * compatible agent runners discover `AGENTS.md`. * Cursor loads its always-applied `.mdc` rule. * GitHub Copilot reads repository-wide custom instructions. All four receive the same decision loop, project policy, workflow loops, stop rules, and installed skill bodies. ## Ongoing changes[​](#ongoing-changes "Direct link to Ongoing changes") Edit `agentbriefer.yaml`, then run: ``` agentbriefer sync agentbriefer doctor ``` This keeps tool syntax separate while project intent stays unified. --- # Stack detection and skills Recommendation narrows the bundled catalog; it does not install anything. ``` agentbriefer skill list --recommended agentbriefer skill info agentbriefer skill add ``` ## Rust and Axum[​](#rust-and-axum "Direct link to Rust and Axum") Given a `Cargo.toml` containing Axum and SQLx, review: ``` agentbriefer skill info rust-axum-layered-structure agentbriefer skill info password-and-session-auth agentbriefer skill add rust-axum-layered-structure ``` Add the authentication skill only when the project actually owns password and session behavior. Recommendations use any matching tag, so human review matters. ## Next.js and React[​](#nextjs-and-react "Direct link to Next.js and React") ``` agentbriefer skill list --role frontend --recommended agentbriefer skill add server-components-by-default agentbriefer skill add css-first-motion ``` This keeps client boundaries intentional and prefers CSS motion with reduced motion support. ## SvelteKit[​](#sveltekit "Direct link to SvelteKit") ``` agentbriefer skill info sveltekit-component-structure agentbriefer skill add sveltekit-component-structure ``` The skill keeps reusable components and stores under `src/lib` while route files remain focused on routing and page composition. ## Stack-agnostic security[​](#stack-agnostic-security "Direct link to Stack-agnostic security") `no-secrets-in-repo` has no compatible-stack restriction and appears in every recommendation set: ``` agentbriefer skill add no-secrets-in-repo ``` --- # Security-first backend team The team maintains a backend with authentication and wants agents to treat security-relevant changes conservatively. agentbriefer.yaml ``` developer: style: security-first explanation_style: tradeoff-based project: project_type: backend-api stack: language: rust framework: axum database: sqlx testing_tools: - cargo-test package_manager: cargo key_dependencies: - argon2 - tower-http security_level: strict testing_level: strict dependency_policy: ask-first architecture_style: simple-layered stop_rules: - Stop before changing session lifetime or cookie policy. - Ask before adding a new authentication dependency. - Never weaken validation to make a test pass. skills: - rust-axum-layered-structure - password-and-session-auth - no-secrets-in-repo outputs: - claude-md - agents-md ``` ## Apply and verify[​](#apply-and-verify "Direct link to Apply and verify") ``` agentbriefer skill add rust-axum-layered-structure agentbriefer skill add password-and-session-auth agentbriefer skill add no-secrets-in-repo agentbriefer doctor ``` Strict security with `ask-first` dependencies and strict testing is internally consistent. Doctor would warn if the same project allowed dependencies freely or used light testing. ## Team review points[​](#team-review-points "Direct link to Team review points") * Commit policy changes with the related architecture decision. * Review skill additions as executable guidance, not decorative metadata. * Keep secrets and environment-specific values out of YAML and generated files. * Use stop rules for decisions requiring human ownership, not for ordinary work. --- # Configure a project `agentbriefer init` is the only interactive project command. It turns a guided conversation into a typed YAML configuration. ## Before the prompts[​](#before-the-prompts "Direct link to Before the prompts") Run it from the project root: ``` agentbriefer init ``` If `agentbriefer.yaml` already exists, the wizard asks before overwriting it and defaults to leaving it untouched. Agentbriefer then detects a supported manifest and loads any saved developer profiles. ## Stack answers[​](#stack-answers "Direct link to Stack answers") Detected values prefill language, framework, database, package manager, testing tools, and key dependencies. They remain editable because repositories can be polyglot or use a tool the detector does not recognize. Comma-separated testing tools and dependencies are normalized into YAML lists. Optional fields can be left blank. ## Behavioral policy[​](#behavioral-policy "Direct link to Behavioral policy") The structured settings are deliberately concrete: | Setting | What it changes | | ------------------ | ---------------------------------------------------------------------- | | Developer style | Scope, tradeoffs, teaching, maintainability, or security posture | | Explanation style | Short, beginner-friendly, detailed, or tradeoff-focused reporting | | Project type | Backend, frontend, CLI, full-stack, library, or docs priorities | | Security level | Caution around auth, secrets, validation, permissions, and data access | | Testing level | When tests are optional, practical, or required | | Dependency policy | Whether agents may add, must explain, or must ask first | | Architecture style | Flat, lightly layered, feature-based, or advanced existing patterns | Every value is rendered with an agent-facing description; generated files do not rely on an unexplained label such as `practical` or `strict`. ## Custom instructions[​](#custom-instructions "Direct link to Custom instructions") Custom instructions hold project-specific guidance that does not fit a dropdown: ``` Run `make fixtures` before integration tests. Never edit generated files under src/protocol/. Keep public error codes backward compatible. ``` The wizard opens `$VISUAL` or `$EDITOR` when available, falling back to the platform editor. Closing without saving keeps the previous value. ## Stop rules[​](#stop-rules "Direct link to Stop rules") Stop rules describe boundaries where an agent must pause or avoid continuing: ``` stop_rules: - Stop before changing CI/CD configuration. - Ask before modifying a public API. - Do not access production credentials. ``` When no stop rules are configured, generated output still tells the agent to stop after the requested change is complete and verified. ## Review and save[​](#review-and-save "Direct link to Review and save") The final screen shows every answer. Select a field to edit it using its current value as the default, or select **Save and finish**. The wizard writes YAML only after this review. note `init` starts with no installed skills. Add them after saving with `agentbriefer skill list` and `agentbriefer skill add `. --- # Developer profiles A developer profile stores the two preferences that usually follow a person rather than a repository: ``` style: practical explanation_style: tradeoff-based ``` ## Create a profile[​](#create-a-profile "Direct link to Create a profile") ``` agentbriefer profile create ``` Choose a simple name, developer style, and explanation style. Existing names require overwrite confirmation. Profiles are stored in the platform configuration directory, commonly: ``` ~/.config/agentbriefer/profiles/.yaml ``` ## List profiles[​](#list-profiles "Direct link to List profiles") ``` agentbriefer profile list ``` ## Use a profile during init[​](#use-a-profile-during-init "Direct link to Use a profile during init") When profiles exist, `agentbriefer init` offers them before asking the two developer questions. The selected values are copied into the project YAML. ## Switch an existing project[​](#switch-an-existing-project "Direct link to Switch an existing project") ``` cd your-project agentbriefer profile switch agentbriefer sync ``` Switch replaces the project's `developer` section and records the source profile name in `extends`. It does not automatically regenerate output files, so run `sync` afterward. ## Copy semantics[​](#copy-semantics "Direct link to Copy semantics") Profiles are snapshots, not live inheritance. Updating a saved profile does not retroactively change projects that used it. This keeps `agentbriefer.yaml` self-contained and reviewable by teammates who do not have your profile. --- # Doctor and maintenance Run the read-only project linter after configuration changes, Agentbriefer upgrades, or unexpected generated output: ``` agentbriefer doctor ``` ## What doctor checks[​](#what-doctor-checks "Direct link to What doctor checks") * `dependency_policy: allow` combined with `security_level: strict`; * `testing_level: light` combined with `security_level: strict`; * an empty primary language; * configured skill IDs missing from the bundled catalog; * configured output files that do not exist; * generated files that differ from a fresh render. For synced files, drift is measured only inside the managed block. Manual notes outside it do not make the file stale. ## Findings and exit behavior[​](#findings-and-exit-behavior "Direct link to Findings and exit behavior") Doctor prints warnings for every finding and `No issues found.` when clean. Findings currently do not produce a non-zero exit code. ``` agentbriefer doctor # Use the report for visibility; do not assume warnings fail the process. ``` ## Maintenance cycle[​](#maintenance-cycle "Direct link to Maintenance cycle") ``` # Upgrade the CLI using your installation method. npm install -g agentbriefer@latest # Refresh bundled skill content and generated files. agentbriefer skill update # Confirm project state. agentbriefer doctor ``` If an unknown skill ID appears after working with a teammate, upgrade first. Remove the ID only when the project no longer intends to use that skill. --- # Generate vs. sync Both commands render the same configuration and installed skills. They differ only in how the result is written. | Behavior | `generate` | `sync` | | -------------------------------- | ---------- | --------------------------------- | | Render every configured format | Yes | Yes | | Create parent directories | Yes | Yes | | Replace the whole file | Yes | Only when no managed block exists | | Preserve content outside markers | No | Yes | | Refuse final-path symlinks | Yes | Yes | ## Generate[​](#generate "Direct link to Generate") ``` agentbriefer generate ``` Use it for the first render or when outputs are completely machine-owned. It always writes a clean template result and discards existing file contents. ## Sync[​](#sync "Direct link to Sync") ``` agentbriefer sync ``` Sync wraps the generated body in markers: ``` Generated Agentbriefer content lives here. ``` Future syncs replace that block and preserve content before or after it. CLAUDE.md ``` My repository-specific note stays here. Agentbriefer replaces only this section. Another manual note also stays here. ``` Cursor's YAML frontmatter stays before the managed block because `.mdc` files must begin with frontmatter. ## Missing or malformed markers[​](#missing-or-malformed-markers "Direct link to Missing or malformed markers") If a file exists without a valid managed block, sync warns and replaces the whole file with a fresh managed result. Markers are recognized only when they appear alone on their own lines, preventing quoted marker text inside a stop rule from corrupting synchronization. ## Recommended workflow[​](#recommended-workflow "Direct link to Recommended workflow") 1. Run `generate` on initial setup. 2. If no manual output edits are needed, continue using `generate` or `sync`. 3. Before adding manual notes, run `sync` once to establish markers. 4. Add notes only outside the markers. 5. Use `sync` thereafter. Do not switch back casually Running `generate` after manual edits fully overwrites the file. Agentbriefer does not try to recover discarded content. --- # Skill profiles A skill profile snapshots the current project's installed skill IDs so the same set can be applied elsewhere. ## Create a profile[​](#create-a-profile "Direct link to Create a profile") ``` cd configured-project agentbriefer skill profile create secure-rust-backend ``` The profile is stored under the platform configuration directory, commonly: ``` ~/.config/agentbriefer/skill-profiles/secure-rust-backend.yaml ``` ## List profiles[​](#list-profiles "Direct link to List profiles") ``` agentbriefer skill profile list ``` ## Apply a profile[​](#apply-a-profile "Direct link to Apply a profile") ``` cd another-configured-project agentbriefer skill profile apply secure-rust-backend ``` Apply **replaces** the target project's entire `skills` list. Agentbriefer then materializes the new set, removes stale skill directories, and synchronizes all configured outputs. caution Apply is not additive. Review the profile and the target project's existing skill list before applying it. Like developer profiles, skill profiles are copied snapshots rather than live links. Changing one does not mutate projects that previously applied it. --- # Skills Skills add focused practices that are more specific than Agentbriefer's general project policy. They ship inside the CLI as validated `SKILL.md` documents. ## Browse the catalog[​](#browse-the-catalog "Direct link to Browse the catalog") ``` agentbriefer skill list agentbriefer skill list --role frontend agentbriefer skill list --recommended agentbriefer skill list --role security --recommended ``` Role and recommendation filters affect only the current listing. They never change the project's installed skills. ## Inspect before installing[​](#inspect-before-installing "Direct link to Inspect before installing") ``` agentbriefer skill info no-secrets-in-repo ``` Info prints the name, ID, description, category, roles, compatible-stack tags, and full instruction body. ## Add a skill[​](#add-a-skill "Direct link to Add a skill") ``` agentbriefer skill add no-secrets-in-repo ``` This operation: 1. validates the ID against the bundled catalog; 2. appends the ID to `agentbriefer.yaml`; 3. materializes `.agentbriefer/skills//SKILL.md`; 4. synchronizes every configured agent output. Adding an installed skill again is a harmless no-op. Unknown IDs fail with a catalog hint. ## Update installed skill content[​](#update-installed-skill-content "Direct link to Update installed skill content") ``` agentbriefer skill update ``` Update re-materializes configured skills and synchronizes outputs using the catalog bundled in the currently installed CLI. It does not fetch a marketplace or contact a server; upgrade Agentbriefer first to receive newer bundled content. ## Remove a skill[​](#remove-a-skill "Direct link to Remove a skill") ``` agentbriefer skill remove no-secrets-in-repo ``` Removal updates YAML, deletes stale materialized skill directories, and synchronizes outputs. Removing an absent ID warns and succeeds. ## Source of truth[​](#source-of-truth "Direct link to Source of truth") The IDs in `agentbriefer.yaml` are authoritative. Materialized `SKILL.md` files contain a do-not-edit header and are replaced during update. Put project-specific exceptions in `custom_instructions`, not inside generated skill files. See the [v1 skill catalog](/docs/reference/skill-catalog.md) for every bundled ID. --- # Stack detection During `init`, Agentbriefer looks for supported manifest files directly in the current directory. A successful detector can prefill: * primary language; * package manager; * framework; * database or data-access library; * testing tools; * up to 20 key direct dependencies; * the manifest used as evidence. The complete ecosystem list is in the [detection matrix](/docs/reference/detection-matrix.md). ## Dependency categorization[​](#dependency-categorization "Direct link to Dependency categorization") Each detector has prioritized framework, testing, and database lookup lists. Recognized packages are assigned to those fields; remaining direct dependencies are alphabetized and capped at 20. ``` axum + sqlx + insta + serde ↓ framework: axum database: sqlx testing_tools: [insta] key_dependencies: [serde] ``` ## Detection never blocks init[​](#detection-never-blocks-init "Direct link to Detection never blocks init") Malformed, absent, or unreadable manifests produce an empty detection result. The wizard still runs and accepts manual answers. ## Polyglot repositories[​](#polyglot-repositories "Direct link to Polyglot repositories") Detectors run in a fixed order and the first matching ecosystem wins. Detection is not recursive and does not merge multiple applications in a monorepo. For a Rust API with a nested JavaScript frontend, running `init` at the repository root may detect only the root manifest. Correct the prefilled values or maintain separate configurations at the appropriate project roots. Detection is a starting point 🧭 Press Enter to accept an accurate prefill. Edit it whenever the manifest does not reflect the context you want agents to prioritize. ## Detection and skill recommendations[​](#detection-and-skill-recommendations "Direct link to Detection and skill recommendations") `agentbriefer skill list --recommended` runs detection for the current session and shows skills whose compatible-stack tags intersect the detected tags. A stack-agnostic skill is always recommended. Matching is an **any-tag** intersection. A skill tagged `rust`, `axum`, and `postgres` may be recommended by a Rust project even when Axum and PostgreSQL were not detected. Review the skill with `skill info` before adding it. --- # Team workflow Agentbriefer separates shared repository policy from personal conveniences. ## Commit shared state[​](#commit-shared-state "Direct link to Commit shared state") Commit `agentbriefer.yaml`. It contains the complete developer/project policy, output selection, stop rules, custom instructions, and installed skill IDs. Teams may also commit generated instruction files so agents receive guidance immediately after checkout. If the team chooses not to commit them, document `agentbriefer sync` as a setup step. Materialized `.agentbriefer/skills/` files are reproducible from the config and CLI catalog. Decide as a team whether readable copies should be committed. ## Keep personal state personal[​](#keep-personal-state-personal "Direct link to Keep personal state personal") Developer profiles and skill profiles live in the user's configuration directory and are not part of the repository. Applying either writes explicit values back to project YAML, keeping the shared result visible. `skill list --role` and `--recommended` are browsing filters only. Two teammates can use different filters without changing installed project state. ## Suggested review process[​](#suggested-review-process "Direct link to Suggested review process") When `agentbriefer.yaml` changes, review it like application configuration: * Does a policy conflict with the project's risk level? * Is a new stop rule precise enough to act on? * Does an installed skill fit the actual stack? * Will changing outputs add or remove tool-specific files? * Were generated files synchronized in the same change? ## Example pull-request check[​](#example-pull-request-check "Direct link to Example pull-request check") ``` cargo test --all-targets # project-specific checks, when applicable agentbriefer sync agentbriefer doctor git diff -- agentbriefer.yaml CLAUDE.md AGENTS.md .cursor .github ``` Because doctor warnings do not fail the process, review its output explicitly. --- # How Agentbriefer works Agentbriefer separates project policy from the syntax expected by individual AI tools. ## 1. Initialize the project[​](#1-initialize-the-project "Direct link to 1. Initialize the project") Run `agentbriefer init` from the repository root. Agentbriefer inspects supported manifest files, uses the result as editable prompt defaults, and asks about the project and your preferred agent behavior. The wizard writes `agentbriefer.yaml`. Detection is a convenience, not an uneditable verdict. ## 2. Keep policy in YAML[​](#2-keep-policy-in-yaml "Direct link to 2. Keep policy in YAML") The configuration stores structured choices such as developer style, testing level, dependency policy, architecture style, outputs, stop rules, and installed skill IDs. It does not copy generated skill content into YAML. agentbriefer.yaml ``` developer: style: practical explanation_style: short project: project_type: cli-tool stack: language: rust package_manager: cargo security_level: standard testing_level: practical dependency_policy: explain-first architecture_style: simple skills: - no-secrets-in-repo stop_rules: - Stop before changing the release workflow. ``` ## 3. Render tool-specific files[​](#3-render-tool-specific-files "Direct link to 3. Render tool-specific files") `generate` and `sync` load the same configuration and render the same shared instruction content through Tera templates. Each output adds only the wrapper needed by its target tool. | Tool or convention | Output path | | ------------------- | --------------------------------- | | Claude Code | `CLAUDE.md` | | AGENTS.md consumers | `AGENTS.md` | | Cursor | `.cursor/rules/agentbriefer.mdc` | | GitHub Copilot | `.github/copilot-instructions.md` | ## 4. Resolve skills at render time[​](#4-resolve-skills-at-render-time "Direct link to 4. Resolve skills at render time") Skills ship inside the Agentbriefer binary. The configuration stores their IDs; the renderer resolves those IDs against the current bundled catalog and inlines the instruction body into every configured output. Adding a skill also materializes a readable copy at `.agentbriefer/skills//SKILL.md`. That copy is generated and should not be hand-edited. ## 5. Check drift[​](#5-check-drift "Direct link to 5. Check drift") `agentbriefer doctor` compares configured outputs with a fresh render. It also checks policy conflicts, required fields, and skill IDs missing from the local catalog. note Doctor reports findings but currently exits successfully. Treat it as a diagnostic report, not as a failing CI quality gate. --- # Installation The npm package is the recommended installation path. It installs the native Agentbriefer binary for your supported platform. ## Recommended: npm[​](#recommended-npm "Direct link to Recommended: npm") Requires a maintained Node.js and npm installation. ``` npm install -g agentbriefer agentbriefer --version ``` To try a command without keeping a global installation: ``` npx agentbriefer@latest --version npx agentbriefer@latest skill list ``` Project commands need a project directory Run `init`, `generate`, `sync`, `doctor`, and skill installation commands from the repository you want Agentbriefer to configure. ## Native installer[​](#native-installer "Direct link to Native installer") The v1 GitHub release publishes installers generated by `cargo-dist`. * macOS / Linux * Windows PowerShell ``` curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/dexterhere/agentbriefer/releases/latest/download/agentbriefer-installer.sh | sh ``` ``` powershell -ExecutionPolicy ByPass -c "irm https://github.com/dexterhere/agentbriefer/releases/latest/download/agentbriefer-installer.ps1 | iex" ``` After installation, open a new terminal and verify: ``` agentbriefer --version ``` ## GitHub release archives[​](#github-release-archives "Direct link to GitHub release archives") Download a platform archive and checksum from the [latest GitHub release](https://github.com/dexterhere/agentbriefer/releases/latest). Extract the `agentbriefer` executable into a directory on your `PATH`. | Operating system | Architecture | | ---------------- | ------------------------------------------- | | macOS | Apple Silicon (`aarch64`), Intel (`x86_64`) | | Linux | ARM64 (`aarch64`), Intel/AMD (`x86_64`) | | Windows | Intel/AMD (`x86_64`) | Windows ARM64 and 32-bit targets are not published in v1. ## Install with Cargo[​](#install-with-cargo "Direct link to Install with Cargo") Rust users can install the tagged source directly from GitHub: ``` cargo install --git https://github.com/dexterhere/agentbriefer.git \ --tag v1.0.0 agentbriefer ``` Agentbriefer is not currently published to crates.io, so `cargo install agentbriefer` by itself is not a supported v1 method. ## Build from source[​](#build-from-source "Direct link to Build from source") Requires the stable Rust toolchain and Git. ``` git clone https://github.com/dexterhere/agentbriefer.git cd agentbriefer cargo test --all-targets cargo install --path . ``` ## Upgrade[​](#upgrade "Direct link to Upgrade") * npm * Native installer * Cargo ``` npm install -g agentbriefer@latest ``` Run the platform installer again. It replaces the installed binary with the current release. ``` cargo install --git https://github.com/dexterhere/agentbriefer.git \ --tag v1.0.0 agentbriefer --force ``` ## Uninstall[​](#uninstall "Direct link to Uninstall") Use the same ecosystem that installed Agentbriefer: ``` # npm npm uninstall -g agentbriefer # Cargo cargo uninstall agentbriefer ``` For a manual archive installation, delete the executable you placed on `PATH`. User profiles under your platform configuration directory are not removed automatically. ## PATH troubleshooting[​](#path-troubleshooting "Direct link to PATH troubleshooting") If installation succeeds but the command is unavailable: ``` # npm global binary directory npm prefix -g # Cargo binary directory (normally) echo "$HOME/.cargo/bin" ``` Ensure the relevant binary directory is on `PATH`, restart the terminal, then run `agentbriefer --version`. See [Troubleshooting](/docs/troubleshooting.md) for additional recovery steps. --- # Meet Agentbriefer Agentbriefer is a command-line tool that gives AI coding agents a consistent, project-specific operating brief. You describe how work should be approached once in `agentbriefer.yaml`; Agentbriefer turns that configuration into the instruction files Claude Code, AGENTS.md-compatible tools, Cursor, and GitHub Copilot already understand. ``` agentbriefer.yaml ↓ Agentbriefer renderer + installed skills ↓ CLAUDE.md Β· AGENTS.md Β· Cursor rules Β· Copilot instructions ``` ## The problem it solves[​](#the-problem-it-solves "Direct link to The problem it solves") AI agents can be productive and still behave inconsistently. One session may make a focused change; another may add dependencies, refactor unrelated code, or continue beyond the requested scope. Repeating the same expectations in every prompt is tedious, easy to forget, and difficult to share with a team. Agentbriefer makes those expectations explicit and reviewable: * how much architecture the agent should introduce; * when dependencies require an explanation or approval; * how security-sensitive changes should be treated; * how much testing is expected; * how detailed explanations should be; * when the agent must stop and ask; * which focused skills apply to the project. ## When Agentbriefer is useful[​](#when-agentbriefer-is-useful "Direct link to When Agentbriefer is useful") * **One developer, several tools:** keep Claude Code, Cursor, and Copilot aligned. * **A shared repository:** review agent policy like any other project configuration. * **Security-sensitive work:** make conservative auth, secret, permission, and validation behavior explicit. * **A mixed-experience team:** choose learning-focused or concise explanations without rewriting prompts. * **Repeated project setup:** reuse developer profiles and named skill sets. * **Existing handwritten guidance:** use `sync` to preserve content outside Agentbriefer's managed block. ## What it is not[​](#what-it-is-not "Direct link to What it is not") Agentbriefer does not run an autonomous agent, execute prompts, create pull requests, store cloud memory, or replace your coding assistant. It prepares the repository-level context those assistants consume. The shortest mental model πŸ’‘ Agentbriefer is a compiler for agent instructions: YAML and bundled skills go in; tool-specific Markdown and rules files come out. ## Continue[​](#continue "Direct link to Continue") Start with [Installation](/docs/installation.md), follow the [Quick start](/docs/quick-start.md), or read [How it works](/docs/how-it-works.md) for the full data flow. --- # Quick start This walkthrough configures one project, generates all four supported output formats, adds a security skill, and verifies the result. ## 1. Install and enter your project[​](#1-install-and-enter-your-project "Direct link to 1. Install and enter your project") ``` npm install -g agentbriefer cd path/to/your-project ``` ## 2. Run the setup wizard[​](#2-run-the-setup-wizard "Direct link to 2. Run the setup wizard") ``` agentbriefer init ``` When Agentbriefer recognizes a project manifest, it announces the detected language and pre-fills stack questions. Press Enter to accept a value or edit it. The wizard covers: 1. developer and explanation styles; 2. language, framework, database, package manager, tests, and dependencies; 3. project type and architecture expectations; 4. security, testing, and dependency policies; 5. custom instructions and stop rules; 6. output formats; 7. a review screen where every answer remains editable. It writes `agentbriefer.yaml` in the current directory. ## 3. Generate instruction files[​](#3-generate-instruction-files "Direct link to 3. Generate instruction files") ``` agentbriefer generate ``` With the default output selection, the project now contains: ``` your-project/ β”œβ”€β”€ agentbriefer.yaml β”œβ”€β”€ CLAUDE.md β”œβ”€β”€ AGENTS.md β”œβ”€β”€ .cursor/rules/agentbriefer.mdc └── .github/copilot-instructions.md ``` ## 4. Add a focused skill[​](#4-add-a-focused-skill "Direct link to 4. Add a focused skill") ``` agentbriefer skill list --recommended agentbriefer skill add no-secrets-in-repo ``` Adding a skill updates `agentbriefer.yaml`, creates `.agentbriefer/skills/no-secrets-in-repo/SKILL.md`, and synchronizes all configured output files. ## 5. Verify the project[​](#5-verify-the-project "Direct link to 5. Verify the project") ``` agentbriefer doctor ``` A clean project prints `No issues found.` Doctor reports warnings rather than returning a failing status code. ## 6. Choose the right regeneration command[​](#6-choose-the-right-regeneration-command "Direct link to 6. Choose the right regeneration command") * Continue using `generate` if the outputs are entirely machine-owned. * Switch to `sync` before adding manual notes outside Agentbriefer's managed markers. ``` agentbriefer sync ``` Generate overwrites the whole file After you add manual content around a managed block, use `sync`. A later `generate` does not preserve those additions. ## Next steps[​](#next-steps "Direct link to Next steps") * Understand [generate versus sync](/docs/guides/generate-vs-sync.md). * Browse the [skill guide](/docs/guides/skills.md). * Review a complete [configuration reference](/docs/reference/configuration.md). * Explore real [use cases and examples](/docs/examples/overview.md). --- # Command reference Agentbriefer uses the following command shape: ``` agentbriefer ``` Use `agentbriefer help`, `agentbriefer --help`, or `agentbriefer skill --help` for the reference shipped with your installed version. The root command supports `-h, --help` and `-V, --version`. Run project commands from the directory that contains `agentbriefer.yaml`. ## Core commands[​](#core-commands "Direct link to Core commands") ### `init`[​](#init "Direct link to init") Interactively inspect a project and create `agentbriefer.yaml`. ``` agentbriefer init ``` The wizard proposes values based on detected manifests and lets you choose generated outputs, developer preferences, stop rules, and skills. ### `generate`[​](#generate "Direct link to generate") Render configured AI instruction files from `agentbriefer.yaml`. ``` agentbriefer generate ``` Generation replaces the selected output files. Use [`sync`](#sync) when an existing file contains human-maintained content that must remain outside Agentbriefer's managed section. ### `sync`[​](#sync "Direct link to sync") Refresh only the Agentbriefer-managed section in each configured output. ``` agentbriefer sync ``` When a file has no managed section, Agentbriefer appends one without deleting the existing content. ### `doctor`[​](#doctor "Direct link to doctor") Validate configuration, skills, profiles, output paths, and generated content. ``` agentbriefer doctor ``` Run this after configuration changes and in pull-request checks. Errors require attention; warnings usually identify stale or incomplete project context. ### `profile list`[​](#profile-list "Direct link to profile-list") List saved developer profiles. ``` agentbriefer profile list ``` ### `profile create`[​](#profile-create "Direct link to profile-create") Interactively save a reusable developer style and explanation style. ``` agentbriefer profile create ``` ### `profile switch`[​](#profile-switch "Direct link to profile-switch") Interactively choose a saved profile and copy it into the current project. ``` agentbriefer profile switch ``` Switch updates `agentbriefer.yaml` but does not regenerate outputs. Run `agentbriefer sync` next. ## Skill commands[​](#skill-commands "Direct link to Skill commands") ### `skill list`[​](#skill-list "Direct link to skill-list") List bundled and locally installed skills. ``` agentbriefer skill list ``` ### `skill add `[​](#skill-add-id "Direct link to skill-add-id") Install a bundled skill into the current project. ``` agentbriefer skill add no-secrets-in-repo ``` ### `skill remove `[​](#skill-remove-name "Direct link to skill-remove-name") Remove an installed skill from the current project. ``` agentbriefer skill remove no-secrets-in-repo ``` Bundled skills remain part of the Agentbriefer binary and can be installed again later. ### `skill update`[​](#skill-update "Direct link to skill-update") Re-materialize all installed skills from the catalog in the current binary and synchronize outputs. ``` agentbriefer skill update ``` ### `skill info `[​](#skill-info-name "Direct link to skill-info-name") Show a skill's metadata and source. ``` agentbriefer skill info no-secrets-in-repo ``` ### `skill profile list`[​](#skill-profile-list "Direct link to skill-profile-list") List reusable skill profiles. ``` agentbriefer skill profile list ``` ### `skill profile create `[​](#skill-profile-create-name "Direct link to skill-profile-create-name") Create a named profile from selected skills. ``` agentbriefer skill profile create secure-api ``` ### `skill profile apply `[​](#skill-profile-apply-name "Direct link to skill-profile-apply-name") Apply a profile to the current project's `agentbriefer.yaml`. ``` agentbriefer skill profile apply secure-api ``` Review the changed configuration, then run `agentbriefer doctor` and `agentbriefer sync`. ## Exit behavior[​](#exit-behavior "Direct link to Exit behavior") Agentbriefer exits with a non-zero status when a command cannot complete or configuration cannot be loaded. `doctor` findings are currently diagnostic warnings and do not make the command fail, so CI must review its output explicitly. --- # Configuration schema `agentbriefer.yaml` is the source of truth for a project's generated instructions. Commit it so the team reviews changes to agent behavior like any other development policy. ## Complete example[​](#complete-example "Direct link to Complete example") agentbriefer.yaml ``` developer: style: practical explanation_style: tradeoff-based project: project_type: backend-api stack: language: rust framework: axum database: postgresql testing_tools: - cargo test package_manager: cargo key_dependencies: - tokio - serde architecture_style: simple-layered security_level: strict testing_level: practical dependency_policy: explain-first stop_rules: - Stop before changing the public API. - Stop before adding a production dependency. skills: - secure-api - testing custom_instructions: | Prefer small, reviewable patches. Keep database migrations backward compatible. outputs: - agents-md - claude-md - cursor-rules - copilot-instructions ``` ## Top-level fields[​](#top-level-fields "Direct link to Top-level fields") | Field | Required | Description | | --------------------- | -------- | ---------------------------------------------------------------------- | | `extends` | No | Reusable developer profile to inherit before applying project values. | | `developer` | Yes | Preferred working and explanation styles. | | `project` | Yes | Project type and detected or curated stack context. | | `stop_rules` | No | Explicit conditions that require the agent to pause. Defaults to `[]`. | | `skills` | No | Ordered names of bundled or installed skills. Defaults to `[]`. | | `custom_instructions` | No | Project-specific guidance that does not fit another field. | | `outputs` | No | Files to generate. Defaults to all supported outputs. | Use only the documented field names. YAML syntax and invalid enum values are rejected; review the generated result because unrecognized extra mapping fields are not part of the supported schema. ## Developer preferences[​](#developer-preferences "Direct link to Developer preferences") ### `developer.style`[​](#developerstyle "Direct link to developerstyle") Choose one of: * `minimal` * `practical` * `learning-focused` * `enterprise` * `security-first` ### `developer.explanation_style`[​](#developerexplanation_style "Direct link to developerexplanation_style") Choose one of: * `short` * `beginner-friendly` * `detailed` * `tradeoff-based` ## Project values[​](#project-values "Direct link to Project values") ### `project.project_type`[​](#projectproject_type "Direct link to projectproject_type") Choose one of: * `backend-api` * `frontend-app` * `cli-tool` * `full-stack-app` * `library` * `documentation-heavy` ### `project.stack`[​](#projectstack "Direct link to projectstack") `language` is required. `framework`, `database`, `package_manager`, and `key_dependencies` are optional context; `testing_tools` and `key_dependencies` default to empty lists. Detection is a starting point, not a constraint. Keep product-specific details that a manifest cannot infer, and remove incidental dependencies that should not influence agent decisions. ## Policy values[​](#policy-values "Direct link to Policy values") | Field | Supported values | | ---------------------------- | ------------------------------------------------------- | | `project.architecture_style` | `simple`, `simple-layered`, `feature-based`, `advanced` | | `project.security_level` | `basic`, `standard`, `strict` | | `project.testing_level` | `light`, `practical`, `strict` | | `project.dependency_policy` | `allow`, `explain-first`, `ask-first` | ## Output values[​](#output-values "Direct link to Output values") | Value | Generated path | | ---------------------- | --------------------------------- | | `agents-md` | `AGENTS.md` | | `claude-md` | `CLAUDE.md` | | `cursor-rules` | `.cursor/rules/agentbriefer.mdc` | | `copilot-instructions` | `.github/copilot-instructions.md` | See [Outputs](/docs/reference/outputs.md) for platform behavior and safe synchronization. ## Precedence[​](#precedence "Direct link to Precedence") `extends` records which saved developer profile was copied into the project. It is informational: generation does not resolve or merge the saved profile again. The concrete `developer` values in the project are always authoritative. Skills are resolved in their configured order at render time. After any manual edit, run: ``` agentbriefer doctor agentbriefer sync ``` --- # Detection matrix Agentbriefer inspects common project manifests during `init`. Detection fills in an editable draft; it never replaces your judgment about the project's intended architecture or policy. | Ecosystem | Signals | Typical package manager | | -------------------- | ----------------------------------------------- | ----------------------------- | | Rust | `Cargo.toml` | Cargo | | Node.js / TypeScript | `package.json` and lockfiles | npm, pnpm, Yarn, or Bun | | Go | `go.mod` | Go modules | | Python | `pyproject.toml`, `requirements.txt` | Project-dependent | | PHP | `composer.json` | Composer | | Java / Maven | `pom.xml` | Maven | | C# | `*.csproj` | NuGet / dotnet | | F# | `*.fsproj` | NuGet / dotnet | | Dart | `pubspec.yaml` | pub | | Julia | `Project.toml` | Pkg | | Crystal | `shard.yml` | Shards | | Haskell | `package.yaml`, `*.cabal`, `stack.yaml` | Cabal or Stack | | R | `DESCRIPTION`, `renv.lock` | renv when present | | Ruby | `Gemfile`, `Gemfile.lock` | Bundler | | Swift | `Package.swift` | Swift Package Manager | | Scala | `build.sbt` | sbt | | JVM / Gradle | `build.gradle`, `build.gradle.kts` | Gradle | | C / C++ | `vcpkg.json`, `conanfile.txt`, `CMakeLists.txt` | vcpkg, Conan, or CMake | | Elixir | `mix.exs` | Mix | | Clojure | `deps.edn`, `project.clj` | Clojure CLI or Leiningen | | Erlang | `rebar.config` | Rebar3 | | Objective-C | `Podfile` | CocoaPods | | Lua | `*.rockspec` | LuaRocks | | Perl | `cpanfile` | cpanm / Carton | | Visual Basic .NET | `*.vbproj` | NuGet / dotnet | | Nim | `*.nimble` | Nimble | | PowerShell | `*.psd1` | PowerShellGet / PSResourceGet | | Zig | `build.zig.zon` | Zig package manager | ## Monorepos and mixed stacks[​](#monorepos-and-mixed-stacks "Direct link to Monorepos and mixed stacks") If several signals exist, Agentbriefer combines the evidence it understands and presents a proposal. Run `init` from the directory whose scope should receive the generated instructions: ``` cd ./services/payments agentbriefer init ``` For a repository-wide policy plus package-specific policy, maintain an Agentbriefer configuration at each intentional instruction boundary. --- # Files and safety Agentbriefer is local-first. It inspects project files, stores configuration and reusable data on your machine, and writes the instruction outputs you select. ## Project files[​](#project-files "Direct link to Project files") | Path | Ownership | | --------------------------------- | ----------------------------------------- | | `agentbriefer.yaml` | Human-reviewed Agentbriefer configuration | | `AGENTS.md` | Generated or synchronized output | | `CLAUDE.md` | Generated or synchronized output | | `.cursor/rules/agentbriefer.mdc` | Generated or synchronized output | | `.github/copilot-instructions.md` | Generated or synchronized output | Project manifests and lockfiles are read for stack detection. Agentbriefer does not modify them. ## User data[​](#user-data "Direct link to User data") Installed skills and reusable developer or skill profiles live in the operating system's standard per-user application data directory. The exact base directory follows the platform conventions resolved for Agentbriefer, rather than assuming a hard-coded home path. Back up custom skills and profiles if they are important organizational assets. Prefer keeping their source in a version-controlled repository and installing from that source. ## Preservation rules[​](#preservation-rules "Direct link to Preservation rules") * `generate` owns the complete selected output. * `sync` changes only Agentbriefer's marked section and retains surrounding content. * Required parent directories are created when needed. * Symbolic-link output paths are refused to avoid writing through an unexpected target. * Invalid YAML, missing profiles, and unresolved skills are reported instead of silently rewriting intent. An unknown skill is excluded from rendering and reported by validation. Run `doctor` before relying on newly generated output. ## Source-control checklist[​](#source-control-checklist "Direct link to Source-control checklist") Commit `agentbriefer.yaml` and the generated files your team consumes. Do not commit private custom skill content or profile data unless it is intentionally safe for every repository reader. Before merging a policy change: ``` agentbriefer doctor agentbriefer sync git diff --check ``` Review the semantic change in the generated instructionsβ€”not just whether generation succeeded. --- # Outputs Agentbriefer turns one project profile into native instruction files for four AI coding ecosystems. Select only the tools your project uses, or keep all outputs to offer contributors a consistent experience. | Configuration value | Path | Intended consumer | | ---------------------- | --------------------------------- | ---------------------------------------------- | | `agents-md` | `AGENTS.md` | Agents that implement the AGENTS.md convention | | `claude-md` | `CLAUDE.md` | Claude Code | | `cursor-rules` | `.cursor/rules/agentbriefer.mdc` | Cursor | | `copilot-instructions` | `.github/copilot-instructions.md` | GitHub Copilot | ## Generate or synchronize[​](#generate-or-synchronize "Direct link to Generate or synchronize") `agentbriefer generate` renders a complete Agentbriefer-owned file. It is the clearest choice for a new output or a file the team intends to manage entirely from configuration. `agentbriefer sync` updates the marked Agentbriefer section and preserves content outside it. Use it when a file also contains carefully maintained human instructions. ``` # First creation agentbriefer generate # Subsequent update that preserves surrounding content agentbriefer sync ``` ## Nested paths[​](#nested-paths "Direct link to Nested paths") Agentbriefer creates required parent directories for Cursor and GitHub output paths. If an output path is a symbolic link, it resolves and writes to the final target rather than replacing the link. ## Reviewing changes[​](#reviewing-changes "Direct link to Reviewing changes") Treat generated instructions as source-controlled artifacts: ``` agentbriefer doctor agentbriefer sync git diff -- agentbriefer.yaml AGENTS.md CLAUDE.md .cursor .github ``` This makes changes visible to reviewers and keeps agent behavior reproducible across machines. ## Tool-specific additions[​](#tool-specific-additions "Direct link to Tool-specific additions") If a platform needs unique guidance, add it outside the managed markers and use `sync`. Put shared policy in `agentbriefer.yaml`, a reusable profile, or a skill so it does not drift between outputs. --- # Bundled skill catalog Agentbriefer v1 bundles seven skills inside the binary. They require no separate download and are installed into a project by ID. | Skill ID | Category | Use it when | | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `docker-compose-for-local-dev` | Backend | Local infrastructure should stay minimal, configurable, healthy, and free of committed secrets. | | `rust-axum-layered-structure` | Backend | An Axum service needs light handler, service, and data boundaries without premature abstractions. | | `css-first-motion` | Frontend | UI animation should prefer CSS and respect reduced-motion preferences. | | `server-components-by-default` | Frontend | A Next.js or React project should keep client components small and intentional. | | `sveltekit-component-structure` | Frontend | A SvelteKit app needs thin routes and well-placed components, stores, and API helpers. | | `no-secrets-in-repo` | Security | Every stack should keep keys, tokens, and credentials out of tracked files. | | `password-and-session-auth` | Security | A Rust/Axum/PostgreSQL backend owns password, cookie, session, or token behavior. | ## Browse and inspect[​](#browse-and-inspect "Direct link to Browse and inspect") ``` agentbriefer skill list agentbriefer skill list --recommended agentbriefer skill info no-secrets-in-repo ``` `--role` and `--recommended` filter only the displayed catalog. They never install a skill or change the shared project configuration. ## Choose a focused set[​](#choose-a-focused-set "Direct link to Choose a focused set") Skills add specialized guidance to every selected output, so install only rules that repeatedly apply to the repository. ``` agentbriefer skill add rust-axum-layered-structure agentbriefer skill add no-secrets-in-repo ``` The IDs are stored in `agentbriefer.yaml`, materialized under `.agentbriefer/skills/`, and inlined into generated instructions. See [Skills](/docs/guides/skills.md) for the full lifecycle. --- # Agentbriefer v1 πŸŽ‰ Agentbriefer v1 is the first stable release of the project policy compiler for AI coding agents. ## Highlights[​](#highlights "Direct link to Highlights") * Interactive project initialization with editable detection across 28 ecosystems. * One typed `agentbriefer.yaml` for developer style, project policy, stop rules, custom guidance, and outputs. * Native instruction generation for Claude Code, AGENTS.md consumers, Cursor, and GitHub Copilot. * Safe managed-block synchronization for files that also contain handwritten guidance. * Reusable developer profiles and named skill profiles. * Seven embedded skills with role and stack recommendation filters. * Read-only diagnostics for policy conflicts, missing files, unknown skills, and output drift. * Native release artifacts for macOS, Linux, and Windows plus shell, PowerShell, and npm installers. ## Compatibility notes[​](#compatibility-notes "Direct link to Compatibility notes") The v1 configuration file is named `agentbriefer.yaml`. Skill content is bundled with the installed binary; `skill update` re-materializes that catalog and does not fetch a remote marketplace. `doctor` findings are diagnostic in v1 and do not change the command's successful exit status. ## Upgrade checklist[​](#upgrade-checklist "Direct link to Upgrade checklist") ``` npm install -g agentbriefer@latest agentbriefer --version agentbriefer skill update agentbriefer doctor ``` Review synchronized output changes before committing them, especially when upgrading from a build that predates skills. --- # Troubleshooting Start with the installed help and the read-only project diagnostic: ``` agentbriefer --version agentbriefer --help agentbriefer doctor ``` ## Command not found after installation[​](#command-not-found-after-installation "Direct link to Command not found after installation") Open a new terminal, then check the binary directory for your installation method. ``` npm prefix -g echo "$HOME/.cargo/bin" ``` Add the applicable binary directory to `PATH`. On Windows, reopen PowerShell after the installer updates the environment. ## No `agentbriefer.yaml` found[​](#no-agentbrieferyaml-found "Direct link to no-agentbrieferyaml-found") Project commands resolve the current working directory. Change to the configured repository root or initialize the current directory: ``` cd path/to/project agentbriefer init ``` ## YAML cannot be parsed[​](#yaml-cannot-be-parsed "Direct link to YAML cannot be parsed") Compare the file with the [configuration schema](/docs/reference/configuration.md). Common causes are incorrect indentation, a policy field placed outside `project`, or a list written as a scalar. If the file is disposable, move it aside and rerun `init`; otherwise fix the YAML and run `doctor`. ## Generated output is stale[​](#generated-output-is-stale "Direct link to Generated output is stale") Refresh configured files and check again: ``` agentbriefer sync agentbriefer doctor ``` If a file has no valid managed block, sync warns and replaces its contents. Back up valuable manual content first, establish the managed block, then restore the manual content outside the markers. ## Manual output edits disappeared[​](#manual-output-edits-disappeared "Direct link to Manual output edits disappeared") `generate` replaces a complete output. Only `sync` preserves text outside managed markers. Recover the previous file from source control, run `sync` to add a managed block, and keep restored notes outside it. ## A symlink output is refused[​](#a-symlink-output-is-refused "Direct link to A symlink output is refused") Agentbriefer will not write through an output path whose final file is a symbolic link. Replace it with a regular file in the project, then rerun the command. This boundary prevents an instruction path from redirecting writes somewhere unexpected. ## Skill is unknown[​](#skill-is-unknown "Direct link to Skill is unknown") The project may reference an ID that is not bundled with the installed CLI version. ``` agentbriefer skill list agentbriefer --version ``` Upgrade Agentbriefer if a teammate used a newer catalog. Otherwise correct or remove the invalid ID in `agentbriefer.yaml`, then run `agentbriefer skill update`. ## Recommended skills look unrelated[​](#recommended-skills-look-unrelated "Direct link to Recommended skills look unrelated") Recommendations match when any compatible stack tag intersects detected language, framework, database, package manager, test tool, or dependency tags. Inspect before installing: ``` agentbriefer skill list --recommended agentbriefer skill info ``` ## Doctor reports warnings but exits successfully[​](#doctor-reports-warnings-but-exits-successfully "Direct link to Doctor reports warnings but exits successfully") That is the v1 behavior: findings are diagnostic and do not set a failing exit code. Review the output explicitly in CI rather than treating process success as a clean report. ## Still blocked[​](#still-blocked "Direct link to Still blocked") Collect the output of `agentbriefer --version`, the relevant command, and a redacted configuration, then [open a GitHub issue](https://github.com/dexterhere/agentbriefer/issues). Never include secrets or private skill content in a public report. ---