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.
Summary
The current
dev-toolspackage still ships the packaged.agentspayload 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/agentspackage and install it into the expected consumer path through Composer installer paths instead of relying on thedev-toolsarchive layout.Problem
Issue #188 showed two adjacent problems:
.agentspayload is currently tied to thefast-forward/dev-toolsarchive;Even with the export-ignore fixes from #188, the current packaging model still makes
dev-toolsresponsible 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:
fast-forward/agentsfast-forward/agentsThen 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-toolsshould then:fast-forward/agents;update-composer-json/ sync bootstrap to add the matchinginstaller-pathsconfiguration to consumercomposer.jsonfiles;dev-toolspackage archive.Expected Result
.agents/...path through Composer configuration;dev-toolsno longer needs to carry the packaged.agentstree in its own release archive;Acceptance Criteria
fast-forward/agentspackage is introduced for the packaged agent payload currently bundled under.agents/agentsand any related packaged agent metadata that belongs with it.fast-forward/dev-toolsrequires the new package and resolves packaged agent assets from that installed dependency.extra.installer-pathsrule 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.dev-toolsis installed from Composer in a fresh consumer repository.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
dev-toolsresources into separate repositories in the same issue.