[architecture] Make DevTools the profile-based bootstrap and upgrade orchestrator for domain packages #384

Proposal / validation gate: this issue records an extraction design for maintainer validation. Repository/package names are candidates. Approve the boundary and migration plan before implementation; this task does not authorize creating repositories, implementing the extraction, releases or consumer rollout.

Problem and user direction

Avoid a permanently maintained static template or copying other repositories whenever starting a project. Retain dev-tools as an orchestrator that selects and integrates the independently versioned domain packages; it must not retain their rules/engines under a new name.

Observed baseline

SyncCommand hard-codes metadata/resources/hooks/Wiki/skills/agents orchestration. #143 and #141 are closed historical work; their completion does not establish the new multi-package model. Main remains a Composer plugin; open #376 proposes external pinned CPX execution and LLM Skills with explicit sync. Design against the reviewed resulting contract, not an assumption that #376 has shipped.

Concrete tasks / acceptance

• Define selectable profiles (library/application/docs-only/custom) and explicit capabilities/opt-outs; infer suggestions but preview exact choices. One composition config records selected packages, compatible versions, provenance and overrides.
• Each domain declares its own executable/API, workflow/Action callers and portable skill payload; DevTools resolves verified releases and presents a plan without reimplementing the rules.
• Bootstrap a clean repo AND upgrade an existing customized repo without copying another project or updating a separate static template. Inventory existing template repositories before deciding whether they remain examples/adapters; no deletion implied.
• Ownership ledger per artifact/managed region: package, source path/version/commit, prior rendered hash, consumer modifications and output target. Exactly one owner per skill/workflow; installed libraries use their trusted package source and external tools an explicitly pinned source.
• Provide deterministic dry-run/diff/check/explicit apply; no writes, network publication or hook execution in preview. Stage/validate plans, detect concurrent edits and conflicts, preserve unknown/custom content, fail closed instead of overwriting; reversible migration/rollback.
• Project update verifies runtime/workflow/skill compatibility, released availability and source identity; never silently replace exact pins with latest. No plugin post-install side effects if feat!: distribute DevTools through CPX and portable skills #376 is accepted. Do not persist CPX cache paths or reinstall DevTools into application dependencies.
• Orchestrate standards/reports via domain exit/result contracts; dependencies remain acyclic. Prefer existing small contracts/libraries; do not require a universal dev-tools-runtime, service container or shim for every package.
• Add integration fixtures for fresh project, legacy plugin consumer, CPX consumer, customized scripts/config/hooks, docs-only, missing capability, incompatible releases, no-op second run, rollback and interrupted/concurrent changes.
• Use Add a doctor command for repository readiness diagnostics #142 doctor as readiness diagnostics, Define release-safe refs for consumer workflow wrappers and checked-out actions #238 for references and [architecture] Map domain-owned skills and replace redundant agent distribution #195 for skill/role-prompt separation. Do not duplicate their implementation work.

Adoption

Pilot a small component (clock), then config/container compatibility, then custom test/report publisher, then remaining repos from a refreshed inventory. Detect imports/vendor paths, plugin allowlists, scripts, hooks, required checks and skill sources per repo. Every consumer gets a reviewable migration PR and verification on its exact head. Package publication and rollout require their existing review/release gates.

Alternatives

Static template repo drifts; copying workflows loses provenance; a monolithic universal actions repo reverses the domain split. A small orchestrator with explicit profiles makes new and existing projects use the same integration path.

Skills-first composition

DevTools may expose onboarding/consumer-sync/quality-pipeline orchestration skills that call domain skills; it does not own copies of their instructions. LLM Skills already handles distribution. Convert existing consumer-sync-auditor/quality-pipeline-auditor prompts when useful; retain a separate agent only for demonstrated nonredundant behavior. #195 owns the whole mapping/removal plan.

Delivery and migration gates

• One domain owner for library/CLI, relevant reusable workflow/Action, portable skill, tests and versioned docs; adapters call the same implementation. Do not create a surface solely for symmetry.
• No production dependency back to DevTools; no generic Actions repository as mandatory runtime. CPX/external execution does not isolate PHPUnit/config classes loaded in the same PHP process.
• Preserve project overrides, exit codes, JSON contracts, working directory/cache/color options, and PHP consumer compatibility. Distinguish tool runtime from application minimum.
• Validate Composer archives, runtime resources and skill provenance outside the source checkout; no host-cache absolute paths in consumer files.
• Release availability, exact workflow/runtime/skill compatibility, then pilot consumer PRs and rollback are separate gates. Never point consumers at a not-yet-published version. No release/merge/deploy/repository creation is performed by this planning issue.
• Root architecture tracking: [architecture] Plan domain-owned tooling extraction and DevTools orchestration #240; release-safe refs Define release-safe refs for consumer workflow wrappers and checked-out actions #238; open distribution redesign PR feat!: distribute DevTools through CPX and portable skills #376 must be revalidated before implementation. Evidence baseline: DevTools main 35d27ee (2026-10-21), not an assertion that PR feat!: distribute DevTools through CPX and portable skills #376 is merged.

Architectural / Isolation Criteria

• MUST: Core logic MUST live in dedicated services; commands/controllers only orchestrate.
• MUST: Separate input resolution, domain transformations and rendering; keep CLI/framework I/O out of reusable behavior.
• MUST: Support reuse/extensibility without major refactoring and deterministic, testable exits/output.
• MUST: Separate gathering/transformation from writes/publishing; repeated execution MUST be idempotent or explicitly bounded.
• MUST: Update README, command/config docs, skill references and synchronized consumer examples with the actual new ownership.