docs: add Codex subagent and hooks guidance

CONTRIBUTING.md

@@ -32,13 +32,16 @@ Use the root repository for work about:
 - root maintainer docs under [`docs/`](./docs/)
 - root policies in [README.md](./README.md), [AGENTS.md](./AGENTS.md), and [ROADMAP.md](./ROADMAP.md)
 - root validation and CI such as [`scripts/validate_socket_metadata.py`](./scripts/validate_socket_metadata.py) and [`.github/workflows/validate-socket-metadata.yml`](./.github/workflows/validate-socket-metadata.yml)
+- coordinated child-skill guidance that needs one consistent policy across multiple monorepo-owned plugin or skills repositories
 
 If the change is really about one child repository's own skills, packaging, tests, or release flow, start in that child repository's docs and workflow instead of treating `socket` as a generic catch-all.
 
 ### Making Changes
 
 Keep changes bounded to one coherent root concern at a time, such as docs-only root alignment, marketplace-path or manifest-alignment fixes, root validation improvements, or root subtree-workflow documentation updates. For ordinary work in monorepo-owned child directories, edit the copy in the relevant directory under `plugins/` directly from this checkout. For `apple-dev-skills`, keep subtree pull and push operations explicit and separate from unrelated edits. For `SpeakSwiftlyServer`, treat `socket` as a pull-only mirror of the standalone release checkout unless maintainers explicitly approve a one-off push from `socket`.
 
+For coordinated child-skill guidance, keep the root explanation small and put detailed behavior in the child repo that owns the skill surface. The root docs should explain why the pass is coordinated; the child docs should explain the actual skill contract.
+
 ### Asking For Review
 
 A root change is ready for review when:

README.md

@@ -55,6 +55,7 @@ Use `socket` when the task is about the superproject layer:
 - mixed monorepo policy
 - subtree sync flow for `apple-dev-skills` or `SpeakSwiftlyServer`
 - cross-repo maintainer guidance
+- coordinated child-skill guidance, such as Codex subagent wording that must stay consistent across exported skills
 - coordinated release-prep work that needs the root docs and child version surfaces to stay in sync
 - coordinated semantic-version bumps that keep the maintained manifests aligned across the superproject
 
@@ -80,6 +81,8 @@ Treat Gale's local `socket` checkout as the normal day-to-day checkout on `main`
 
 Keep root docs and marketplace wiring in sync with packaging changes in the same pass. For monorepo-owned child directories, edit the relevant directory under [`plugins/`](./plugins/) directly and commit in `socket`. For `apple-dev-skills` and `SpeakSwiftlyServer`, keep subtree sync operations explicit and isolated. `SpeakSwiftlyServer` is pull-only from `socket` by default: release and validate it in its standalone checkout, then pull the released state down here.
 
+When a guidance change intentionally spans multiple child skill repositories, update the affected child docs and the root `socket` docs in the same pass so the superproject still explains why the coordinated edit belongs here.
+
 ### Shared Versioning
 
 The maintained version surfaces in `socket` now move together on one shared semantic version. Use the root release-version script to inventory the live targets or to apply a patch, minor, major, or explicit custom version across the superproject:

ROADMAP.md

@@ -77,6 +77,8 @@ No active backlog candidates are currently tracked here. Add new candidates only
 
 ## History
 
+- Added coordinated OpenAI Codex Hooks guidance across `agent-plugin-skills` and `productivity-skills`, with future `maintain-project-hooks` work tracked in the productivity roadmap.
+- Added coordinated Codex subagent guidance across `agent-plugin-skills` and `productivity-skills`, grounding skill wording in OpenAI's current explicit-trigger `subagents` model while keeping the root docs clear about why the pass belongs in `socket`.
 - Completed the subtree workflow and release-discipline milestones by adding the root marketplace audit pass, the public child plugin removal checklist, and a tighter roadmap state that no longer carries stale backlog items as active work.
 - Prepared the `v6.1.0` minor release by adding the `maintain-project-api` productivity skill and keeping the monorepo-owned child docs, tests, and shared version surfaces aligned.
 - Added explicit `standard` and `subtrees` release-mode guidance, including the pull-only `SpeakSwiftlyServer` rule for `socket` subtree sync.

docs/maintainers/subtree-workflow.md

@@ -9,6 +9,7 @@ This document explains how `socket` is maintained after the monorepo simplificat
 - the nested directory layout under `plugins/`
 - the root Codex marketplace at `.agents/plugins/marketplace.json`
 - the maintainer docs that explain the mixed monorepo experiment
+- coordinated guidance passes that intentionally keep multiple child skill repositories aligned
 - release tags and release notes for the superproject itself
 
 Treat Gale's local `socket` checkout as the normal day-to-day working checkout on `main`.
@@ -19,6 +20,8 @@ Direct work on local `main` is the default for `socket`. Use a feature branch or
 
 For ordinary child-directory fixes, work in the monorepo copy under `plugins/<name>/` and commit in `socket`.
 
+For coordinated guidance that spans multiple monorepo-owned child repositories, edit the relevant child directories directly and update the root docs only enough to explain the cross-child policy or discovery reason.
+
 For `apple-dev-skills`, when a change should publish back to its source repository, work in `plugins/apple-dev-skills/`, commit in `socket`, and then use `git subtree push --prefix=plugins/apple-dev-skills apple-dev-skills main`.
 
 For `SpeakSwiftlyServer`, treat `plugins/SpeakSwiftlyServer/` as a downstream mirror. Build, validate, tag, release, and live-refresh SpeakSwiftlyServer in its standalone checkout, then use `git subtree pull --prefix=plugins/SpeakSwiftlyServer speak-swiftly-server main` to bring that released child state down into `socket`.

plugins/SpeakSwiftlyServer/.github/workflows/validate-repo-maintenance.yml

@@ -1,5 +1,8 @@
 name: Validate Repo Maintenance
 
+# Branch protection should require the Actions check context `validate`.
+# GitHub exposes the job check run by this job name, not by the workflow title.
+
 on:
   pull_request:
   push:
@@ -8,16 +11,17 @@ on:
 
 jobs:
   validate:
+    name: validate
     runs-on: macos-26
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v4
       - name: Select latest stable Xcode
         uses: maxim-lobanov/setup-xcode@v1
         with:
           xcode-version: latest-stable
       - name: Show Swift version
         run: xcrun swift --version
-      - name: Install formatting and linting tools
+      - name: Install Swift repo-maintenance tools
         run: brew install swiftformat swiftlint
       - name: Run repo-maintenance validation
         run: bash scripts/repo-maintenance/validate-all.sh