Skip to content

[agents] Extract packaged agents into fast-forward/agents and install via composer installer-paths #195

@coisa

Description

@coisa

Summary

The current dev-tools package still ships the packaged .agents payload directly, which keeps coupling the agent prompt distribution model to the main Composer plugin archive.

We should split the packaged agent payload into a dedicated fast-forward/agents package and install it into the expected consumer path through Composer installer paths instead of relying on the dev-tools archive layout.

Problem

Issue #188 showed two adjacent problems:

  • the packaged .agents payload is currently tied to the fast-forward/dev-tools archive;
  • consumer repositories expect packaged skills and project agents to exist at a stable path that synchronization commands can target.

Even with the export-ignore fixes from #188, the current packaging model still makes dev-tools responsible for distributing content that conceptually belongs to a dedicated packaged prompt bundle.

Proposed Direction

Create a dedicated repository and package for packaged Fast Forward agent assets:

  • repository: fast-forward/agents
  • package: fast-forward/agents

Then install that package into the expected path inside consumer repositories using Composer installer paths, for example:

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

fast-forward/dev-tools should then:

  • require fast-forward/agents;
  • teach update-composer-json / sync bootstrap to add the matching installer-paths configuration to consumer composer.json files;
  • resolve packaged agent assets from the installed package path instead of assuming they live inside the dev-tools package archive.

Expected Result

  • packaged agent prompts live in their own repository and release cycle;
  • consumers install them into the expected local .agents/... path through Composer configuration;
  • dev-tools no longer needs to carry the packaged .agents tree in its own release archive;
  • sync commands keep working against a stable installed path in both this repository and consumer repositories.

Acceptance Criteria

  • A new fast-forward/agents package is introduced for the packaged agent payload currently bundled under .agents/agents and any related packaged agent metadata that belongs with it.
  • fast-forward/dev-tools requires the new package and resolves packaged agent assets from that installed dependency.
  • Consumer bootstrap/configuration adds the necessary Composer extra.installer-paths rule so the agent package installs into the expected .agents/... location.
  • update-composer-json (or the canonical consumer sync/configuration command) can add or preserve the required installer-paths configuration without clobbering unrelated installer-path rules.
  • Agent synchronization and consumer onboarding flows continue to work when dev-tools is installed from Composer in a fresh consumer repository.
  • Documentation covers the new package split, installation path expectation, and any migration needed for existing consumers.
  • Tests cover path resolution, composer.json mutation/merge behavior, and sync behavior after the package split.

Notes

The exact custom package type name can be finalized during implementation, but the solution should rely on Composer installer paths rather than ad hoc post-install copying.

Non-goals

  • Redesigning the skill content itself.
  • Moving unrelated dev-tools resources into separate repositories in the same issue.
  • Reworking the entire consumer sync system beyond what is needed to support the new packaged agent dependency.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions