Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# bedrock-python engineering assets

> The files every bedrock-python library shares, delivered to each of them as a pull request: the documentation site's assets and workflow, community and release settings, and instructions for coding agents.
> The files every bedrock-python library shares, delivered to each of them as a pull request: the documentation site's assets and workflow, community and release settings, and instructions, an AI review and workflows for coding agents.

This is the hub of the bedrock-python organisation, created from [engineering-assets-template](https://github.com/bedrock-python/engineering-assets-template). Its CI runs [touchmark](https://github.com/bedrock-python/touchmark): whenever a pack changes, every library the hub subscribes gets a pull request with the change, and a file a library has made its own stays its own.

Expand All @@ -22,10 +22,12 @@ bedrock-python/clientwright, … the libraries: topic python, subscr
| `agents` | `AGENTS.md`, the project profile `.agents/project.md` to fill in, review prompts | the template's starter pack |
| `claude` | Claude Code instructions, settings, skills and a reviewer agent | the template's starter pack |
| `python-library` | guidelines for public APIs, versioning and deprecation | the template's starter pack |
| `ai-review` | `.agents/review/`: an AI review by six directions in fresh contexts, which the author runs before a pull request, with a record per branch in `local/reviews/`, a pure-refactor check and `check.py` for a pre-push reminder; the skill `review-change` for every agent | the template's opt-in pack |
| `workflow` | skills for every agent in `.agents/skills/`: `implement`, `new-branch`, `commit`, `pr` (with the AI Review section) and `spec`; `/implement` for Claude Code | the template's opt-in pack |

The first two packs are the files python-library-template gives every new library, taken from its `template/` directory at commit `a1a1e7d` (`CODE_OF_CONDUCT.md` from the repository root, which is the rendered `CODE_OF_CONDUCT.md.jinja`). Their blob ids are the ones the libraries already have, so for every library that never changed them, touchmark recognises them as shipped and connects them with an empty diff. Keep python-library-template and these packs in step: a change goes to the pack here, and the same bytes to the template, so new libraries start in sync. The first such change, on 2026-10-07: `docs.yml` takes clientwright's `workflow_dispatch`, `concurrency: pages` and `--no-dev --group docs` on `uv run`, and pg-partsmith's `uv sync --locked`. The second, on 2026-11-15: `release-please.yml` takes python-library-template#23, a token of the org's release App so that CI runs on release pull requests. Every library had already taken it from the template on 2026-10-17, which made their copies their own; they are the same bytes as the pack now, so they are the hub's again.

`targets.yml` selects the libraries created from python-library-template, the organisation's repositories with the topic `python` but mr-review, the blog and the template itself, and gives each all five packs. The libraries share one owner with the hub, so the hub subscribes them itself (`opt_in: assumed`) instead of waiting for an `.engineering-assets.yml` in each; a library chooses packs or ignores files by adding that file, and opts out with `enabled: false` in it. The subscription rolled out in two steps ([Rollout](#rollout)): deadline-budget first, then every library.
`targets.yml` selects the libraries created from python-library-template, the organisation's repositories with the topic `python` but mr-review, the blog and the template itself, and gives each all seven packs. The libraries share one owner with the hub, so the hub subscribes them itself (`opt_in: assumed`) instead of waiting for an `.engineering-assets.yml` in each; a library chooses packs or ignores files by adding that file, and opts out with `enabled: false` in it. The subscription rolled out in two steps ([Rollout](#rollout)): deadline-budget first, then every library.

A new library is a target once it has the topic `python` and both of the hub's GitHub Apps are installed on it: the Apps are installed on selected repositories only, since the writer must not reach this hub.

Expand Down Expand Up @@ -74,6 +76,7 @@ The reader's keys are the repository variable `TOUCHMARK_READ_APP_ID` and secret
2. **Every library**, 2026-10-07: `defaults.opt_in: assumed` in `targets.yml`. Its merge opens a sync pull request in each of the other twelve libraries, which says the hub subscribed it and how to opt out.
3. **The libraries' own files**, 2026-10-07. clientwright's and pg-partsmith's improvements to `docs.yml` went into `zensical-docs` (#5) and both took the hub's version back; grpc-client-kit took back three copies that differed only in line endings; mattermind keeps its own `docs.yml` and pg-partsmith its own `dependabot.yml`, through `ignore` in their `.engineering-assets.yml`. Every library filled in its `.agents/project.md`. expected.md describes the result.
4. **Deeper starter packs**, 2026-10-11 (#13, from engineering-assets-template#9): the review prompt in slices with "Justify or remove", the new `.agents/prompts/pure-refactor.md`, working principles in `AGENTS.md`, concrete `python-library` guidelines. One sync pull request per library, 10 files each; all 13 merged the same day with their checks green.
5. **The AI review and the workflows**, 2026-11-15 (from engineering-assets-template#11 to #16): the opt-in packs `ai-review` and `workflow` join `defaults.packs`, and `agents` and `claude` take the template's lines that hand over to them when a repository has them. One sync pull request per library, 18 files created and 8 updated each. After the merge, a library that wants the pre-push reminder adds the hook from `.agents/review/README.md` to its `.pre-commit-config.yaml`.

After that, the hub runs itself: `distribute` on every merge to `master` and daily, `doctor` weekly. A new library joins once it has the topic `python` and both Apps are installed on it; a new Python repository that is not a library goes under `exclude` in `targets.yml`. In a public repository GitHub disables scheduled workflows after 60 days without activity; re-enable the workflow if the daily run stops.

Expand Down
104 changes: 62 additions & 42 deletions expected.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,57 +4,59 @@ touchmark's check against a real fleet: `touchmark plan --assume-opt-in --all` o

## Where it stands

The rollout finished on 2026-10-07 (README, "Rollout"), and the deeper starter packs of 2026-10-11 (#13) reached every library the same day: all 13 sync pull requests are merged. Every library has the hub's files, so a plan changes nothing anywhere. What differs, differs on purpose:
The rollout finished on 2026-10-07 (README, "Rollout"), and the deeper starter packs of 2026-10-11 (#13) reached every library the same day. This change takes the template's `ai-review` and `workflow` packs into every library and updates `agents` and `claude` from the template, so the plan opens one sync pull request in each library: the 18 new files of the two packs, and 8 files of `agents` and `claude` updated. What differs otherwise, differs on purpose, as before:

- every library filled in `.agents/project.md`, which is therefore its own (`local`);
- every library filled in `.agents/project.md`, which is therefore its own (`local`), so the template's new lines in the profile skeleton reach none of them;
- mattermind keeps its own `.github/workflows/docs.yml`, since its docs dependencies are an extra, and pg-partsmith its own `.github/dependabot.yml`, which adds the `docker` ecosystem. Their `.engineering-assets.yml` lists those files under `ignore`.

Once the 13 sync pull requests are merged, the expectation goes back to "nothing changes anywhere": the outcomes `unchanged` with no counts, and the states below `current`.

The expectation holds while:

- only mattermind and pg-partsmith have an `.engineering-assets.yml`, and it only ignores those files. `targets.yml` subscribes every target (`defaults.opt_in: assumed`), so `--assume-opt-in` changes nothing;
- the organisation's repositories with the topic `python`, minus the `exclude` patterns of `targets.yml`, are these 13. A new one shows up as an unexpected target;
- touchmark has no open sync pull request in any target;
- touchmark has no open sync pull request in any target, before the merge of this change;
- the packs and the libraries' copies stay as they are. A change to a pack makes the copies `outdated` and the plan `opened`; a library that changes a copy makes it `local`. Either way, write the expectation again.

The default branches it was checked at, on 2026-10-11:
The default branches it was checked at, on 2026-11-15:

| Repository | Commit |
|---|---|
| aiokafka-foundation-kit | `a609399448c6771f528bde69cfad27400f16b546` |
| alembic-gauntlet | `1b74059ac166a0e0e03da188918d68766e850830` |
| clientwright | `0f58abba7c4d038b94156bbfcf499078883ef306` |
| deadline-budget | `9132b54747d7ddcb296fe0d8aecb549ee29ca336` |
| grpc-client-kit | `040c5420b48f3938b5d76354773fc1c14417531d` |
| grpc-server-kit | `05394320aedd31b2423c04e0e000d7d0a94009e0` |
| idempotency-kit | `f4bc4e4c2cd69ab75b232225337d2a1c6a65d60f` |
| mattermind | `17691e7f0dff2a99996c8b8f5958860fbdd59bd8` |
| omni-box | `27e8e3eb8ed62fbc9e8d82bbd20edbf58fa02b7c` |
| pg-partsmith | `2890538ccabdbd7bf4034ca6f2c951991833cb5f` |
| redis-client-kit | `e23db4fd40d2f632215884c1149c5b83c7c80543` |
| servicewright | `e11de17a3f1efc36c1174d5fdd27dc7e393f2bbc` |
| sqlalchemy-foundation-kit | `adcd6455b475b96650adcd1aa4d6f0690c7aaa1d` |
| aiokafka-foundation-kit | `62d5e126485fe9f7a5eccc26aa66fe8d0ffa7f48` |
| alembic-gauntlet | `de2170d0609228deb11f2e056e1cbb35a11f1119` |
| clientwright | `8d5835e59545614bca7849ce1b68426e52e12c61` |
| deadline-budget | `158de0215a25192a9f6e070bb812cc1bb4e7635d` |
| grpc-client-kit | `6b333b9551c6db622cfd839ca21acde4d241f19f` |
| grpc-server-kit | `f9f9c609867f42cef528f14864b0b55657a7876e` |
| idempotency-kit | `1bf9a264acd21d96cd2284b7683bf458c012a41a` |
| mattermind | `771c92abb025dfb623163cc2918209d64d735a7f` |
| omni-box | `6b0f9728a5697ce8e8b07091c7e8ef8b2e90fef8` |
| pg-partsmith | `eb29d57456f1fe74a68dd9a26e663a4d1b20c7e5` |
| redis-client-kit | `ccf50c262492a50a44ff6a4e93c7ee4a879d5994` |
| servicewright | `805c4d090b61b1d2ed995f3d6d423a979d2cdf82` |
| sqlalchemy-foundation-kit | `ce9b15cbde116facfb9e9435009c04f06a0413b7` |

## Expectation

Packs of every target: `zensical-docs, bedrock-community, agents, claude, python-library`
Packs of every target: `zensical-docs, bedrock-community, agents, claude, python-library, ai-review, workflow`

That is `defaults.packs` of `targets.yml`, with `agents` placed before the packs that require it. No target adds packs: the two opt-in files only ignore paths.
That is `defaults.packs` of `targets.yml`, with `agents` placed before the packs that require it. `ai-review` and `workflow` both ship `local/.gitignore`, with the same content; `workflow`, the later, is its pack. No target adds packs: the two opt-in files only ignore paths.

| Repository | Outcome | Create | Update | Delete |
|---|---|---:|---:|---:|
| `bedrock-python/aiokafka-foundation-kit` | unchanged | 0 | 0 | 0 |
| `bedrock-python/alembic-gauntlet` | unchanged | 0 | 0 | 0 |
| `bedrock-python/clientwright` | unchanged | 0 | 0 | 0 |
| `bedrock-python/deadline-budget` | unchanged | 0 | 0 | 0 |
| `bedrock-python/grpc-client-kit` | unchanged | 0 | 0 | 0 |
| `bedrock-python/grpc-server-kit` | unchanged | 0 | 0 | 0 |
| `bedrock-python/idempotency-kit` | unchanged | 0 | 0 | 0 |
| `bedrock-python/mattermind` | unchanged | 0 | 0 | 0 |
| `bedrock-python/omni-box` | unchanged | 0 | 0 | 0 |
| `bedrock-python/pg-partsmith` | unchanged | 0 | 0 | 0 |
| `bedrock-python/redis-client-kit` | unchanged | 0 | 0 | 0 |
| `bedrock-python/servicewright` | unchanged | 0 | 0 | 0 |
| `bedrock-python/sqlalchemy-foundation-kit` | unchanged | 0 | 0 | 0 |
| `bedrock-python/aiokafka-foundation-kit` | opened | 18 | 8 | 0 |
| `bedrock-python/alembic-gauntlet` | opened | 18 | 8 | 0 |
| `bedrock-python/clientwright` | opened | 18 | 8 | 0 |
| `bedrock-python/deadline-budget` | opened | 18 | 8 | 0 |
| `bedrock-python/grpc-client-kit` | opened | 18 | 8 | 0 |
| `bedrock-python/grpc-server-kit` | opened | 18 | 8 | 0 |
| `bedrock-python/idempotency-kit` | opened | 18 | 8 | 0 |
| `bedrock-python/mattermind` | opened | 18 | 8 | 0 |
| `bedrock-python/omni-box` | opened | 18 | 8 | 0 |
| `bedrock-python/pg-partsmith` | opened | 18 | 8 | 0 |
| `bedrock-python/redis-client-kit` | opened | 18 | 8 | 0 |
| `bedrock-python/servicewright` | opened | 18 | 8 | 0 |
| `bedrock-python/sqlalchemy-foundation-kit` | opened | 18 | 8 | 0 |

| Path | Pack | State | Exceptions | Sensitive |
|---|---|---|---|---|
Expand All @@ -71,20 +73,38 @@ That is `defaults.packs` of `targets.yml`, with `agents` placed before the packs
| `.agents/prompts/pure-refactor.md` | agents | current | - | no |
| `.agents/prompts/refactor-check.md` | agents | current | - | no |
| `.agents/prompts/review.md` | agents | current | - | no |
| `AGENTS.md` | agents | current | - | no |
| `.claude/agents/reviewer.md` | claude | current | - | yes |
| `AGENTS.md` | agents | outdated | - | no |
| `.claude/agents/reviewer.md` | claude | outdated | - | yes |
| `.claude/settings.json` | claude | current | - | yes |
| `.claude/skills/commit/SKILL.md` | claude | current | - | yes |
| `.claude/skills/new-branch/SKILL.md` | claude | current | - | yes |
| `.claude/skills/pr/SKILL.md` | claude | current | - | yes |
| `.claude/skills/review-change/SKILL.md` | claude | current | - | yes |
| `.claude/skills/spec/SKILL.md` | claude | current | - | yes |
| `CLAUDE.md` | claude | current | - | no |
| `.claude/skills/commit/SKILL.md` | claude | outdated | - | yes |
| `.claude/skills/new-branch/SKILL.md` | claude | outdated | - | yes |
| `.claude/skills/pr/SKILL.md` | claude | outdated | - | yes |
| `.claude/skills/review-change/SKILL.md` | claude | outdated | - | yes |
| `.claude/skills/spec/SKILL.md` | claude | outdated | - | yes |
| `CLAUDE.md` | claude | outdated | - | no |
| `.agents/guidelines/public-api.md` | python-library | current | - | no |
| `.agents/guidelines/python.md` | python-library | current | - | no |
| `.agents/guidelines/testing.md` | python-library | current | - | no |

Sensitive files are those the pull request description lists under ⚠: touchmark's built-in list (workflows, `dependabot.yml`, `.claude/settings*.json`, `.claude/agents/**`, `.claude/skills/**`, ...) and `sensitive_paths` of `hub.yml`. Skills are on the list because a skill's `allowed-tools` lets Claude Code use those tools without asking.
| `.agents/review/README.md` | ai-review | missing | - | no |
| `.agents/review/check.py` | ai-review | missing | - | yes |
| `.agents/review/directions/compatibility.md` | ai-review | missing | - | no |
| `.agents/review/directions/correctness.md` | ai-review | missing | - | no |
| `.agents/review/directions/design.md` | ai-review | missing | - | no |
| `.agents/review/directions/performance.md` | ai-review | missing | - | no |
| `.agents/review/directions/security.md` | ai-review | missing | - | no |
| `.agents/review/directions/tests.md` | ai-review | missing | - | no |
| `.agents/review/pure-refactor.md` | ai-review | missing | - | no |
| `.agents/review/review.md` | ai-review | missing | - | no |
| `.agents/skills/review-change/SKILL.md` | ai-review | missing | - | yes |
| `.agents/skills/commit/SKILL.md` | workflow | missing | - | yes |
| `.agents/skills/implement/SKILL.md` | workflow | missing | - | yes |
| `.agents/skills/new-branch/SKILL.md` | workflow | missing | - | yes |
| `.agents/skills/pr/SKILL.md` | workflow | missing | - | yes |
| `.agents/skills/spec/SKILL.md` | workflow | missing | - | yes |
| `.claude/skills/implement/SKILL.md` | workflow | missing | - | yes |
| `local/.gitignore` | workflow | missing | - | no |

Sensitive files are those the pull request description lists under ⚠: touchmark's built-in list (workflows, `dependabot.yml`, `.claude/settings*.json`, `.claude/agents/**`, `.claude/skills/**`, `.agents/skills/**`, ...) and `sensitive_paths` of `hub.yml`, which adds `.agents/review/check.py`. Skills are on the list because a skill's `allowed-tools` lets Claude Code use those tools without asking.

## How the rollout got here

Expand Down
7 changes: 7 additions & 0 deletions hub.yml
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ sensitive_paths:
- scripts/** # emit_markdown.py runs in the docs workflow
- overrides/** # HTML on every page of the documentation site
- docs/assets/javascripts/** # JavaScript on every page of the documentation site
- .agents/review/check.py # ai-review: a pre-push hook runs it on developers' machines

# What the packs under packs/ are for, and which packs each one needs: a target
# that gets a pack gets its requires first. A renamed pack lists its old names
Expand All @@ -86,3 +87,9 @@ packs:
python-library:
description: Python, testing and public API guidelines for libraries
requires: [agents]
ai-review:
description: An AI review by directions (correctness, security, performance, design, tests, compatibility) in fresh contexts, which the author runs before a pull request, with a record per branch, a pure-refactor check and a pre-push reminder
requires: [agents]
workflow:
description: Skills for every agent in .agents/skills - implement (a task from understanding it to the report), new-branch (with worktrees), commit (docs and rules checked first), pr (a short description about why, with the AI Review section) and spec (an interactive planning session) - and /implement for Claude Code
requires: [agents]
4 changes: 3 additions & 1 deletion packs/agents/.agents/project.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,12 @@ find these facts in the repository instead, and say where they found them.
## Conventions

- Default branch:
- Issue tracker, and how commits and pull requests refer to an issue (for example `#123` or `ACME-123`):
- Issue tracker, the URL of an issue by its id, and how commits and pull requests refer to an issue (for example `#123` or `ACME-123`):
- Branch names (for example `fix/123-short-description`):
- Commit messages (for example Conventional Commits):
- Language of pull request titles and descriptions:
- Languages of the docs, of code comments and of notes for agents:
- Where operational runbooks live:
- Where specs and design notes go:

## Boundaries
Expand Down
Loading
Loading