vociferate/AGENTS.md

# Agent Integration Guide

This guide is for agentic coding partners that need to integrate the composite actions published by this repository.

## Source Of Truth

Pin all action references to a released tag (for example `@v1.0.1`) and keep all vociferate references on the same tag in a workflow.

Published composite actions:

- `git.hrafn.xyz/aether/vociferate@v1.0.1` (root action)
- `git.hrafn.xyz/aether/vociferate/prepare@v1.0.1`
- `git.hrafn.xyz/aether/vociferate/publish@v1.0.1`
- `git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.1`
- `git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.1`

## Action Selection Matrix

Use this when deciding which action to call:

- Choose `prepare` when you need to update changelog/version files, commit, and push a release tag.
- Choose `publish` when a tag already exists and you need to create or update release notes/assets.
- Choose `coverage-badge` after tests have produced `coverage.out` and you need coverage artefacts uploaded.
- Choose `decorate-pr` to annotate pull requests with coverage information and unreleased changelog entries.
- Choose root `vociferate` for direct recommend/prepare logic without commit/tag/push behavior.

## Preconditions

Apply these checks before invoking actions:

- Checkout repository first.
- For prepare/publish flows that depend on tags/history, use full history checkout (`fetch-depth: 0`).
- Use valid credentials in `github.token` (or explicit token input for `publish` when needed).
- Set required vars/secrets for coverage uploads:
  - `vars.ARTEFACT_BUCKET_NAME`
  - `vars.ARTEFACT_BUCKET_ENDPONT`
  - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY`
  - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET`
- For externally visible changelog links, set `vars.VOCIFERATE_REPOSITORY_URL` to the server/base URL only.

## Changelog Format Guidance

Agents should keep `CHANGELOG.md` in a Keep a Changelog compatible structure because vociferate derives versions and release notes from headings.

Required conventions:

- Keep the top-level heading as `# Changelog`.
- Maintain an `## [Unreleased]` section.
- Keep the standard subsections under `Unreleased` in this order:
  - `### Breaking`
  - `### Added`
  - `### Changed`
  - `### Removed`
  - `### Fixed`
- Record releases with headings like `## [1.2.3] - YYYY-MM-DD`.
- Use bullet entries under subsections (for example `- Added new publish output`).
- Preserve or regenerate bottom reference links (`[Unreleased]: ...`, `[1.2.3]: ...`) instead of mixing inline heading links.

Semver behavior used by recommendation logic:

- `Breaking` or `Removed` entries trigger a major bump.
- `Added` entries trigger a minor bump.
- Otherwise recommendation falls back to a patch bump.

Minimal template:

```markdown
# Changelog

## [Unreleased]

### Breaking

### Added

### Changed

### Removed

### Fixed
```

## Minimal Integration Patterns

### 1. Prepare Then Publish

```yaml
jobs:
  prepare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: prepare
        uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.1

  publish:
    needs: prepare
    uses: aether/vociferate/.gitea/workflows/do-release.yml@v1.0.1
    with:
      tag: ${{ needs.prepare.outputs.version }}
    secrets: inherit
```

### 2. Publish Existing Tag

```yaml
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: publish
        uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.1
        with:
          version: v1.2.3
```

### 3. Coverage Badge Publication

```yaml
jobs:
  coverage:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
      AWS_EC2_METADATA_DISABLED: true
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: go test -covermode=atomic -coverprofile=coverage.out ./...
      - id: badge
        uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.1
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
```

### 4. Decorate Pull Request With Coverage and Changes

```yaml
jobs:
  coverage:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
      AWS_EC2_METADATA_DISABLED: true
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: go test -covermode=atomic -coverprofile=coverage.out ./...
      - id: badge
        uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.1
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
      - name: Decorate PR
        uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.1
        with:
          coverage-percentage: ${{ steps.badge.outputs.total }}
          badge-url: ${{ steps.badge.outputs.badge-url }}
```

## Inputs And Outputs Cheatsheet

### prepare

Common inputs:

- `version` (optional override)
- `version-file` (optional)
- `version-pattern` (optional)
- `changelog` (optional)

Primary output:

- `version` (resolved tag, for example `v1.2.3`)

### publish

Common inputs:

- `token` (optional, defaults to workflow token)
- `version` (optional if running from tag ref)
- `changelog` (optional)

Primary outputs:

- `release-id`
- `tag`
- `version`

### coverage-badge

Required inputs:

- `artefact-bucket-name`
- `artefact-bucket-endpoint`

Useful optional inputs:

- `coverage-profile` (default `coverage.out`)
- `summary-file` (append markdown summary)

Primary outputs:

- `total`
- `report-url`
- `badge-url`

### decorate-pr

Required inputs:

- `coverage-percentage` (0-100, typically from coverage-badge action)
- `badge-url` (SVG badge URL, typically from coverage-badge action)

Useful optional inputs:

- `changelog` (default `CHANGELOG.md`)
- `comment-title` (default `Vociferate Review`)
- `token` (defaults to workflow token)

Primary outputs:

- `comment-id`
- `comment-url`

## Guardrails For Agents

Use these rules to avoid common automation mistakes:

- Do not mix action tags in one workflow update.
- Do not assume a release workflow will run from a tag push in all environments; reusable workflow call paths are supported.
- Do not treat `VOCIFERATE_REPOSITORY_URL` as a full repository URL; it must be a base URL.