Packaged dev-tools archive excludes .agents payload needed by agents sync

[coisa]

Summary

Consumer projects running dev-tools agent synchronization cannot find the packaged .agents/agents payload inside vendor/fast-forward/dev-tools.

Reproduction

In a consumer package using fast-forward/dev-tools, run sync that reaches the agents step.

Observed error:

2026-04-23T23:09:53+00:00 [ERROR] No packaged .agents/agents found at: /Users/mentordosnerds/Sites/github.com/php-fast-forward/enum/vendor/fast-forward/dev-tools/.agents/agents

Suspected cause

The distributed package appears to exclude .agents from the Composer archive.

In the installed package, vendor/fast-forward/dev-tools/composer.json contains:

"archive": {
  "exclude": [
    "/.agents/"
  ]
}

That would explain why AgentsCommand looks for .agents/agents in the installed package and finds nothing.

Additional problem

When agent/skill metadata is generated into the consumer repository, links must not be written as absolute filesystem paths.

In the consumer package (php-fast-forward/enum), agent-facing references were saved as absolute local paths, which is incorrect for versioned repository content because it bakes one developer machine path into Git.

These links should be written relative to the consumer package root instead.

Examples:

• bad: /Users/.../enum/...
• good: repository-relative paths resolved from the consumer package root

Even if the packaging issue is fixed, writing absolute paths into the consumer repository still makes the generated agent metadata invalid for other contributors.

Impact

• dev-tools cannot synchronize packaged subagents into consumer repositories
• consumers need manual workarounds even though the command exists
• generated agent metadata can be invalid for every clone except the machine that produced it

Expected result

If dev-tools ships an agents sync command, the packaged artifact installed via Composer should include the .agents/agents payload required by that command.

Any generated agent/skill references written into the consumer repository should also be relative to the consumer package root, never absolute local filesystem paths.

Context

Reproduced in consumer repo: php-fast-forward/enum

[coisa]

Another problem from the same sync flow: generated agent/skill links must not be absolute filesystem paths.

In the consumer package (php-fast-forward/enum), agent-facing references were saved as absolute local paths, which is wrong for versioned repository content because it bakes one developer machine path into Git.

These links should be written relative to the consumer package root instead.

In other words:

• bad: absolute paths like /Users/.../enum/...
• good: repository-relative paths that remain valid for any clone of the consumer package

Please treat this as part of the .agents packaging/sync problem, because even when the payload exists, writing absolute paths into the consumer repository makes the generated agent metadata invalid for other contributors.