Imported from justAnArthur/modo (.github/AGENTS.md). Install upstream with npx skills add justAnArthur/modo --skill .github. Copyright stays with the author.

AGENTS.md — installed by just-github-actions-n-workflows init

Owned by the toolkit. This file is generated and overwritten by init and update from the docs/AGENTS.template.md of the just-github-actions-n-workflows toolkit. To customize agent-facing instructions for this specific repo, create a separate CONTRIBUTING.md or repo-level instructions — do NOT hand-edit this file.

TL;DR

This repo's release machinery is wired by workflows from justAnArthur/just-github-actions-n-workflows. As an AI agent you need three things to be useful here:

1. Use Conventional Commits with a scope — missing scope = silent no-bump.
2. The scope maps to a package via properties.gitCommitScopeRelatedNames in that package's package.json. Read it BEFORE editing.
3. Tags carry JSON annotations that control which publish/deploy workflows fire. Inspect with git tag -l --format='%(contents)' <tag> if anything looks skipped.

1. Repo layout after install

• .github/workflows/*.yml — workflows owned by the toolkit. Do not hand-edit.
• .github/workflows/.toolkit-lock.json — tracks installed {name, file, ref, installedAt}. update reads this; deleting it forces a full re-install.
• .github/AGENTS.md — this file (symlinked to ./AGENTS.md at repo root).
• .justactions.yml — deploy config (only used by deploy-docker-compose.yml and deploy-vercel-on-tag.yml).

The # toolkit-ref: <ref> comment at the top of each workflow YAML is injected by init. The uses: justAnArthur/just-github-actions-n-workflows/...@main references inside the workflow bodies are rewritten to @<sha> at install time.

2. Commit format — the part you MUST get right

Conventional Commits. Scope is mandatory.

<type>(<scope>[,<scope>,...]): <subject>

Type → version bump:

Multiple scopes (comma-separated) bump multiple packages at once. To suppress a bump entirely, include [skip bump] anywhere in the commit message.

3. Scope → package mapping

The mapping lives in each package's manifest, not in any single file. Example:

// packages/api/package.json
{
  "name": "@myorg/api",
  "properties": {
    "gitCommitScopeRelatedNames": "api,backend"
  }
}

Then feat(api): ... AND feat(backend): ... both bump @myorg/api. Match logic is in the toolkit: a scope matches if it equals the manifest name or any value in gitCommitScopeRelatedNames (see lib/src/manifests/discovery.ts and lib/src/modules/index.ts).

Before editing code in this repo: read every package.json (or pom.xml) under the path you'll touch. Check its properties.gitCommitScopeRelatedNames. Use one of those values as your commit scope.

If you use a scope that isn't in any manifest, your commit is silently dropped — no version bump occurs and no error surfaces.

4. Tags and deploy targets

When the bump-version.yml workflow runs (push to main, or via workflow_dispatch), it:

1. Parses commits since the last tag, finds the highest-bump-type per scope.

2. Updates package.json / pom.xml versions.

3. Commits and pushes the version bump as a chore[skip bump]: bumping ... commit.

4. Creates annotated git tags in the form @scope/name@version (e.g. @myorg/api@0.2.0).

5. The tag's annotation message is JSON:

   {"deployTargets":["npm","docker"]}

   This JSON controls which publish/deploy workflows fire.

deployTargets is inferred from each manifest's properties:

5. Why a publish or deploy silently skipped

Each of publish-npm-on-tag.yml, publish-docker-on-tag.yml, deploy-vercel-on-tag.yml runs resolve-tag-meta first, then guards the main job with if:. The job skips when the tag annotation doesn't list its target.

To inspect a tag's annotation:

git fetch --tags
git tag -l --format='%(contents)' '@myorg/api@0.2.0'

• Empty output or non-JSON → legacy tag. Re-dispatch the workflow manually to fall back to runtime detection (check-publishable for npm, get-dockerfile-path for docker).
• JSON without the target you want → fix properties.deployTargets (or the inferred source property) and trigger a new bump.
• JSON with the target, but workflow still skipped → check resolve-tag-meta.outputs.has_annotation and the matching publish_* output in the workflow run logs.

6. Manual dispatch inputs

Re-dispatch is the right tool when a tag annotation is missing or the workflow errored non-deterministically.

7. Required secrets (set in repo Settings → Secrets → Actions)

All workflows use the auto-provided GITHUB_TOKEN — no PAT required. If you need a PAT with elevated scopes for a specific run, set GH_TOKEN in secrets and forward it via workflow_call.

8. Updating the toolkit

just-github-actions-n-workflows status    # show installed vs latest
just-github-actions-n-workflows update    # upgrade to latest
just-github-actions-n-workflows update --ref v1.2.3   # pin to version

If you can't run the CLI (the v1 npm-install limitation noted in the toolkit README), re-curl the workflow files manually from the new tag and re-commit. The update command refreshes both workflows and this AGENTS.md.

9. Don't edit the workflows or this file directly

.github/workflows/*.yml and .github/AGENTS.md are owned by the toolkit. Local edits get blown away on the next update or init --force. If you need different behavior:

• Adjust the workflow's push.branches / push.tags pattern after install (this is expected — init does NOT customize triggers).
• Open an issue / PR upstream for behavior changes.
• For repo-specific agent instructions, write a separate CONTRIBUTING.md or root-level AGENTS.md outside the toolkit's managed path.

10. Common agent mistakes in this repo

• feat: add endpoint — missing scope, silent no-bump.
• feat(API): ... — uppercase scope; manifests use lowercase by convention.
• Adding a new package without setting properties.gitCommitScopeRelatedNames — bumps for it will never fire.
• Pushing a tag like v1.2.3 instead of @scope/name@1.2.3 — none of the **@* triggers will match.
• Running npm version patch directly — bypasses the conventional-commit-driven bump and produces a tag without the JSON annotation, which downstream workflows then fall back to legacy detection for.
• Hand-editing bump-version.yml to change the bump logic — overwritten by update.