[architecture] Plan domain-owned tooling extraction and DevTools orchestration #240

Objective

Evaluate and implement the extraction of shared GitHub Actions implementations and reusable workflow orchestration from php-fast-forward/dev-tools into the organization-level php-fast-forward/.github repository.

dev-tools would keep the consumer-facing workflow stubs currently stored under resources/github-actions/, and dev-tools:sync would continue copying those stubs into consumer repositories. The implementation details behind those stubs would move to php-fast-forward/.github, which is a more natural home for shared organization automation.

Motivation

dev-tools is becoming overloaded with two different responsibilities:

• shipping a PHP Composer plugin and command suite;
• acting as the organization automation repository for reusable workflows and composite GitHub Actions.

That coupling has started to create maintenance pressure and versioning questions. Consumer repositories currently depend on fast-forward/dev-tools as a Composer package, but their workflows call reusable workflows and actions from this repository. When automation implementation changes happen on main, consumers can observe workflow behavior that does not necessarily match the latest published PHP package release.

The organization repository php-fast-forward/.github already exists as the organization profile repository. It is also the repository GitHub users usually expect to contain shared organization-level defaults and automation. Moving reusable workflows and local actions there would make the architecture easier to explain:

• .github owns organization-level GitHub automation;
• dev-tools owns the PHP package, Composer plugin, CLI commands, sync logic, and packaged consumer workflow wrappers;
• consumer repositories keep thin wrappers copied by dev-tools:sync.

Relationship To #238

This issue is closely related to #238.

#238 asks how consumer workflow wrappers and .github/actions checkouts should be versioned so consumers do not accidentally run unreleased dev-tools automation.

Extracting the reusable workflows/actions to php-fast-forward/.github may make #238 simpler because the version contract could become a contract of the automation repository instead of the PHP package repository. In that model:

• implement this extraction first;
• then resolve Define release-safe refs for consumer workflow wrappers and checked-out actions #238 against the new layout by deciding how consumer stubs reference php-fast-forward/.github versions or branches;
• Define release-safe refs for consumer workflow wrappers and checked-out actions #238 may shrink from “separate PHP package release state from workflow/action state” into “define a versioning/update policy for the dedicated automation repository”.

If implementation shows that .github cannot own the automation cleanly, #238 remains required as the fallback path for release-safe refs inside dev-tools itself.

Proposed Direction

Create a migration plan where php-fast-forward/.github becomes the canonical source for:

• reusable workflows currently under .github/workflows/ that are consumed by other repositories;
• composite actions currently under .github/actions/;
• supporting scripts/assets that exist only to power those workflows/actions;
• future organization-level automation such as a documentation/site pipeline if the profile repository gains a real project structure later.

Then adjust dev-tools so it keeps and syncs only the consumer wrappers, for example:

• resources/github-actions/tests.yml
• resources/github-actions/reports.yml
• resources/github-actions/changelog.yml
• resources/github-actions/wiki.yml
• resources/github-actions/wiki-maintenance.yml
• resources/github-actions/review.yml
• resources/github-actions/auto-assign.yml
• resources/github-actions/label-sync.yml
• resources/github-actions/auto-resolve-conflicts.yml

Those wrappers would call reusable workflows from php-fast-forward/.github instead of php-fast-forward/dev-tools.

Suggested Migration Strategy

1. Inventory automation ownership

   • Identify which .github/workflows/* files are reusable workflows for consumers.
   • Identify which workflows are repository-local to dev-tools and should remain here.
   • Identify all .github/actions/* dependencies for each reusable workflow.

2. Create the automation repository structure

   • Add the reusable workflows and composite actions to php-fast-forward/.github.
   • Decide whether they live directly under .github/workflows and .github/actions, or under a dedicated folder if the profile repository needs to preserve GitHub profile behavior cleanly.
   • Ensure local action paths still resolve correctly when reusable workflows run from the .github repository.

3. Update consumer wrappers in dev-tools

   • Change resources/github-actions/*.yml to call php-fast-forward/.github/.github/workflows/<workflow>.yml@<ref> or whichever path/ref policy is selected.
   • Keep dev-tools:sync responsible for copying wrappers to consumers.
   • Ensure copied wrappers remain thin and consumer-customizable.

4. Define the versioning policy

   • Decide whether consumers reference @main, immutable release tags, a moving major tag, or another stable ref from php-fast-forward/.github.
   • Coordinate this with Define release-safe refs for consumer workflow wrappers and checked-out actions #238 so the ref strategy is deliberate rather than inherited accidentally.
   • If tags are used, define how releases/tags are created in .github and how consumers are updated.

5. Keep dev-tools self-hosting workable

   • dev-tools still needs to test changes to wrappers and sync logic.
   • Decide whether dev-tools itself consumes .github workflows immediately or keeps local workflows for bootstrap/self-test purposes.
   • Avoid a circular dependency where changing automation requires a dev-tools release before it can be validated.

6. Document and validate the new contract

   • Update GitHub Actions docs and consumer sync docs.
   • Add static checks to detect stale references to php-fast-forward/dev-tools/.github/workflows/*@main once migration is complete.
   • Add release/sync checks to ensure resources copied to consumers point at the intended automation repository/ref.

Design Questions

• Should php-fast-forward/.github become a real automation package with its own tags/releases, or should it stay branch-based at first?
• If .github gains tags, should Dependabot update reusable workflow refs in consumers?
• Should dev-tools release automation update consumer stubs to the latest .github automation tag, or should the .github repo own that update flow?
• Which workflows are truly organization-wide and which are specific to PHP package repositories using dev-tools?
• Should the .github repo eventually host an organization site or documentation built with the Fast Forward framework, and would that affect folder layout?
• How should local composite actions that assume a PHP/Composer project be adapted when they live in a repository that currently has no Composer structure?
• Do any workflows require dev-tools source code directly, or can they install/use the Composer package from the consumer repository as they do today?

Scope

In scope:

• migration plan and implementation for shared reusable workflows/actions;
• wrapper updates in resources/github-actions/;
• documentation updates explaining the new ownership model;
• validation that consumers receive equivalent behavior after dev-tools:sync;
• coordination with Define release-safe refs for consumer workflow wrappers and checked-out actions #238 for release-safe refs.

Out of scope:

• rewriting the dev-tools PHP command architecture;
• changing consumer workflow behavior beyond the repository/ref ownership migration;
• building a full organization website in .github as part of this task;
• forcing every consumer customization to be overwritten.

Acceptance Criteria

Delivery Criteria

• A migration inventory identifies which workflows/actions move to php-fast-forward/.github and which remain in dev-tools.
• php-fast-forward/.github contains the shared reusable workflow/action implementation needed by consumer repositories.
• dev-tools keeps consumer-facing workflow wrappers under resources/github-actions/ and those wrappers call the new automation repository.
• dev-tools:sync continues to copy consumer workflow wrappers correctly.
• The selected relationship with Define release-safe refs for consumer workflow wrappers and checked-out actions #238 is documented: either this issue must be completed before Define release-safe refs for consumer workflow wrappers and checked-out actions #238, or Define release-safe refs for consumer workflow wrappers and checked-out actions #238 remains a fallback if extraction is rejected.
• Documentation explains the new ownership split between .github, dev-tools, and consumer repositories.
• Static validation prevents newly migrated wrappers from drifting back to php-fast-forward/dev-tools/.github/workflows/*@main accidentally.

Regression Criteria

• At least one consumer-style fixture or dry-run verifies that synced wrappers point at php-fast-forward/.github.
• Existing workflow summaries, wiki/report automation, changelog automation, label sync, review automation, and auto-assign behavior remain covered by equivalent workflows after migration.
• CI verifies local action paths still resolve from the new repository layout.