[architecture] Map domain-owned skills and replace redundant agent distribution #195

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.

Revised scope — skills first, ownership by responsibility (2026-10-21)

The former mandatory central agents bundle / Composer installer-paths proposal below is superseded as the default. Keep this issue open for design validation and migration mapping, not as evidence an extraction has been implemented. #240 tracks the full architecture; #384 owns onboarding composition.

Main still ships .agents/skills and .agents/agents; open PR #376 at cde0cc6 proposes portable resources/skills, LLM Skills distribution, removing skills/agents copy/symlink commands and retaining repository-owned custom prompts. It is not merged/released. Build on the reviewed result, do not recreate the removed installer under another name.

Inspected inventory and proposed canonical owners

Role prompts are not automatically needed as dedicated subagents. Convert useful procedures into skills or a composition skill invoking other skills. Retain a specialist agent format only with a concrete capability/quality/isolation benefit demonstrated against a skill, with no default extra prompt copies. Repository-specific custom roles remain user-owned and are not deleted by a package migration.

Residual Skills option — last resort, not decided

The user suggested a possible php-fast-forward/skills only for reusable procedures that genuinely fit no domain, possibly including installation/configuration guidance for LLM Skills. Compare:

1. domain-owned skills (default: versioned beside behavior);
2. DevTools-owned composition/onboarding skills (natural for its orchestration);
3. direct LLM Skills configuration without another package;
4. residual skills repo (only if independently useful unowned procedures remain).

If option 4 wins, specify its bounded inventory, why each item cannot live with a domain, independent release value, trust model and any explicit LLM Skills setup adapter. It must not fork LLM Skills, invent a new installer/symlink sync mechanism, become a dependency of all domain packages, or silently install software/mutate projects. Do not create it before maintainer validation.

Acceptance / design deliverables

• Map every current skill, role prompt, mirror/symlink, PR feat!: distribute DevTools through CPX and portable skills #376 replacement and consumer source to one owner; document merge/convert/retain/remove and justification.
• Compare the four residual alternatives with concrete payloads and maintenance cost; recommend the smallest architecture, not a default agents/skills megarepo.
• Define canonical references, compatible version pins, licenses, installation provenance, semantic names and cross-skill invocation without circular chains or duplicated instructions.
• LLM Skills owns discovery/install/update; use trusted installed-library sources where applicable and explicitly pinned GitHub sources for external tools. Missing trusted payload is not permission to fetch latest elsewhere.
• Preview existing consumer customizations and collision handling; one installed copy per skill, no deletion of local edited prompts, reproducible rollback.
• Test installed/archive payloads, documented CLI/help correspondence, second-run no-op, multi-domain composition and unsupported/missing skill diagnostics.
• Coordinate Add component-preference skill/reference for Fast Forward dependency guidance #350 component guidance, Create NotebookLM integration skill for automated documentation updates #351 optional docs/NotebookLM, Add first-class llms.txt support for AI-native repositories #144 llms.txt, Add github/local-action to dev-tools local workflow validation path #347/Integrate github/gh-aw for workflow/action inspection in dev-tools #348/Adopt github/spec-kit specs and pinned-action hash governance #349 validation with real domain needs; none is declared complete solely by this mapping.
• Validate proposal with maintainer before implementation; preserve feat!: distribute DevTools through CPX and portable skills #376 review and [architecture] Map domain-owned skills and replace redundant agent distribution #195 historical discussion. No new repo or consumer edit in this issue-planning run.

Historical proposal — preserved, superseded default

{
  "extra": {
    "installer-paths": {
      ".agents/{$name}/": ["type:fast-forward-agent-bundle"]
    }
  }
}