Another team's agent ships its toolkit into our repo. A pre-push hook keeps our docs in step.
DEV Community

Another team's agent ships its toolkit into our repo. A pre-push hook keeps our docs in step.

Our AI Extension Builder writes custom sections for GoodBarber apps from a description. The code it writes calls the app through the GoodBarber App API, with a JavaScript toolkit, GBJSTK, documented in a public reference.

A colleague maintains the toolkit in its own repository and works on it with a coding agent. Between September 2 and September 25, six versions of it reached our repository, from 2.6.0 to 2.7.0, and nobody scheduled a meeting about any of them.

The release ends in our repository

The toolkit's release process is written for agents, in the CLAUDE.md of its repository, and its last two steps are the documentation and our repository.

On the toolkit side, a post-commit hook regenerates the public API reference, so the reference follows the code commit by commit. Then the agent copies the new toolkit file into our repository and commits it there.

The six commits are in our history under my colleague's name, each with Claude as co-author. Some of those commits go further than the file. On September 25, the day 2.7.0 arrived, another commit by my colleague added the new gb.viewport methods to the list of calls our builder accepts in the code it generates.

The copy that stayed behind

We also keep a Markdown copy of that reference in our repository, so that our agents have a version they can grep, and our CLAUDE.md points them to it. From March 26 to October 20, it opened with "Current version: 2.3.1".

In September, the toolkit file next to it went from 2.6.0 to 2.7.0. The release step for our repository updated that file and never touched the copy.

A script, then a hook that only checks

On October 20 we wrote a script that renders the copy from the OpenAPI spec behind the public reference and stamps the API version and the generation date in its first lines. With --check, it compares that stamp with the online reference and with the toolkit file in our repository:

$ python scripts/update_gb_app_api_doc.py --check
docs/GOODBARBER_APP_API.md: 2.7.0
online reference (major 2): 2.7.0
vendored GBJSTK.js: 2.7.0
Up to date.

A pre-push hook went in the same morning. On a push to master, it regenerated the copy, committed it and stopped the push. It came out at 16:30, because it could commit to master on its own, even during the freeze before a build. It was active for six and a half hours and never made a commit.

It came back on October 27, as a check only. It reads the copy in the commit being pushed to master, and when that copy is behind, it stops the push and says what to run. Replayed on our commit from April 23, it prints this:

pre-push: docs/GOODBARBER_APP_API.md is outdated in the commit pushed to master: push stopped.
docs/GOODBARBER_APP_API.md in the pushed commit: no version marker
online reference (major 2): 2.7.0
vendored GBJSTK.js: 2.7.0
OUTDATED: run `python scripts/update_gb_app_api_doc.py` and commit the result.
pre-push: to fix it, run `python scripts/update_gb_app_api_doc.py`, commit docs/GOODBARBER_APP_API.md, then push again.
`git push --no-verify` skips this check once.

Whoever is pushing, one of us or an agent, runs the script, commits the copy and pushes again. The hook itself writes nothing, and a network or Python problem never blocks a push.

Where it stops

A git hook runs only in the clones that turned it on with:

git config core.hooksPath .githooks

If the next toolkit version lands from a clone without it, our copy catches up at the next push to master from a clone that has it.

The hook also stops at the documentation. Whether our builder may use a new method is still decided in a commit. The gb.viewport methods accepted on September 25 carry a comment saying they are accepted for hand-written or imported plugins and "not taught by the prompt".

On October 27, the check reports 2.7.0 on every side, and the hook has not stopped a push yet. When a team you depend on ships a new version, what tells your coding agents?

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.