From 17eb108e9b62551ba3d5cbb9227838598da571fb Mon Sep 17 00:00:00 2001
From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com>
Date: Sun, 11 Oct 2026 08:40:46 +0000
Subject: [PATCH 1/2] docs(STRINGS-3714): add CLAUDE.md with spec workflow
 guidance

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CLAUDE.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..a31f1c984
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,25 @@
+# strings-openapi
+
+## Spec changes workflow
+
+1. Before adding a path file or endpoint docs, grep `paths.yaml`, `doc/compiled.json` and `paths/` for the endpoint to confirm it is not already documented under another file name or tag.
+2. Edit the source YAML.
+3. Run `make lint` (runs `swagger-cli validate`, `make bundle`, then `lint.sh`). Do not run a second manual `swagger-cli bundle` afterwards.
+4. `git diff` to confirm scope.
+5. Commit the source change together with the regenerated `doc/compiled.json` (generated but committed). `tmp/compiled.yaml` is gitignored; never stage it.
+
+## Finding endpoints
+
+`paths.yaml` references path files, not literal URLs. Find where an endpoint is wired up with e.g. `grep -n "search.yaml" paths.yaml`.
+
+## Consistency
+
+When adding or editing a request-body property for a resource, apply it to both `paths/<resource>/create.yaml` and `paths/<resource>/update.yaml`, and to the shared response schema under `schemas/`, so POST/PATCH/GET contracts do not drift.
+
+## Breaking changes CI
+
+`.github/workflows/breaking-changes.yml` diffs the compiled spec against the base branch. Adding or reordering enum values, or altering shared response schemas such as `schemas/project_details.yaml`, can fail it. Inspect its diff output before pushing; if it fails on a purely additive enum/field change, explain the additive nature in the PR body instead of re-pushing the same change.
+
+## Commits and PR titles
+
+Use `docs(STRINGS-XXXX): <summary>` for commit messages and PR titles (matches git log history), not the `JIRA-KEY - title` default.

From b4e2d63a7426f7fed0e72a7ac42ec9e31729d542 Mon Sep 17 00:00:00 2001
From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com>
Date: Mon, 12 Oct 2026 12:33:54 +0000
Subject: [PATCH 2/2] docs(API): correct PR title guidance in CLAUDE.md
 #STRINGS-3714

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CLAUDE.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a31f1c984..2965dc3ab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,4 +22,7 @@ When adding or editing a request-body property for a resource, apply it to both
 
 ## Commits and PR titles
 
-Use `docs(STRINGS-XXXX): <summary>` for commit messages and PR titles (matches git log history), not the `JIRA-KEY - title` default.
+PR titles are used to generate client library changelogs and version bumps. Follow the "PR titles" section of the README (https://github.com/phrase/strings-openapi#pr-titles): `change_type(affected_library): description #STRINGS-TICKET`, e.g. `docs(API): clarify field description #STRINGS-1234`.
+
+- `change_type`: `feat` (new endpoints, properties, query parameters), `fix` (schema fixes), `docs` (description-only changes, no schema change), `build` (build system or CI changes).
+- `affected_library`: most commonly `API`; schema changes always use `API`.