# Communiqué Development Guide
## Conventional Commits
Pull request titles must use
`<type>[optional scope][optional !]: <description>`; intermediate commit
subjects should use the same format. Start descriptions with a lowercase
character and keep them concise and imperative. Use `!` for a breaking change and explain it with a
`BREAKING CHANGE:` footer.
Allowed types are `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`,
`revert`, `security`, `style`, and `test`.
CI validates the pull request title and re-runs when it is edited. Intermediate
commit subjects are not checked because pull requests are squash-merged. CI
mechanically checks the allowed type, syntax, and lowercase-leading description;
imperative mood and breaking-change details remain review rules.
## Project
Communiqué is a Rust CLI that generates AI-powered editorialized release notes.
It uses an agentic loop in which an LLM reads repository context through tools
and produces structured notes through the `submit_release_notes` tool.
## Commands
- `cargo build` — build the project
- `cargo test` — run all tests
- `cargo test <test_name>` — run one test
- `cargo clippy` — lint
- `cargo fmt` — format
- `mise run lint` — run every linter through hk
## Architecture
The entry flow is `main.rs` → `cli.rs` → `generate.rs`. Generation gathers
configuration and repository context, builds prompts, runs the agent loop, and
optionally publishes the result.
- `llm.rs` defines `LlmClient`; providers live under `providers/`.
- `tools/mod.rs` dispatches the tools exposed to the agent.
- `config.rs` loads `communique.toml`; CLI arguments override its defaults.
Use `miette::Result` for diagnostics and tokio for asynchronous work. Tests use
`wiremock` and `test_helpers::TempRepo`. Preserve the path-traversal checks in
the `read_file` tool and URL validation in `links.rs`.
## Dependency Updates
- Use the lowest compatibility-significant specificity in `Cargo.toml` (for example, `"1"` for stable 1.x dependencies).
- When the existing manifest requirement accepts a routine dependency update, change only `Cargo.lock`.
- Keep lockfile updates focused and avoid unrelated transitive dependency churn.
## PR titles and descriptions are release-note inputs
PR titles and descriptions are source material for release notes, including those
generated by Communique. Write them for a communique user who has not read the diff
or this conversation.
- **Describe the final result.** Before requesting review and again after feedback
changes the implementation, compare the title and body with the complete current
diff. Rewrite both when the scope changes. Remove abandoned approaches, stale
requirements, and claims that the final code or validation no longer supports.
- **Lead with the user-visible change.** Keep the conventional commit format, but
name the affected behavior and outcome in the title. Open the body with the
problem or use case and what users can now do. Avoid titles such as "address
feedback" or "fix CI" when the PR's actual purpose is a feature or behavior fix.
For internal-only work, explain the concrete maintainer or contributor benefit
without inventing a user-facing impact.
- **Make the change concrete.** For new configuration, commands, or APIs, include
a small, valid example and explain its result. For a bug fix, describe the trigger
and before/after behavior. For visible UI or output changes, include actual
before/after screenshots or a short recording when they help reviewers assess the
change; CLI input/output snippets are often clearer than terminal screenshots.
Use measured results for performance claims and state how they were measured.
- **Keep the essential facts in text.** Caption screenshots and explain examples.
A reader or release-note generator should understand the change without opening
an image, following an external link, or reading the diff. Do not fabricate
screenshots, output, measurements, or validation results.
- **State adoption details when relevant.** Include new flags or settings, defaults,
supported platforms, experimental status, required dependency versions, and any
compatibility changes or migration steps that affect using the feature. Distinguish
current behavior from planned follow-ups; do not advertise unfinished work.
- **Keep review details proportionate.** Summarize meaningful validation and its
limitations. Include implementation details only when they explain behavior or a
tradeoff reviewers need to assess. Omit agent work logs, intermediate commit
summaries, and exhaustive test-command lists. A small fix can be a short paragraph
and a test result; screenshots and sections are not mandatory for every PR.
For a hypothetical fix, prefer `fix(generate): include pull request context in release notes`
over `fix: address review feedback`. Its description should show the generation command and a short excerpt illustrating the resulting release notes.
These rules supplement the repository's existing commit, release, and disclosure
requirements.
## GitHub Interactions
When AI contributes GitHub content—including a pull request description, review, pull request
comment, or discussion post—append this disclosure:
`*AI-assisted — Tool: <tool>; model: <provider>/<model>; version: <version-or-unavailable>.*`
Use the exact model and version identifiers exposed by the runtime. Never infer or guess them; use
`unavailable` when either value is not exposed.