[sync] Package project-agent prompts for consumers (#130) (#131)

* [sync] Add packaged project-agent synchronization (#130)

* [docs] Generalize packaged project-agent prompts (#130)

* [sync] Simplify packaged directory synchronizer (#130)

* [docs] Restore SynchronizeResult PHPDoc detail (#130)

* Update wiki submodule pointer for PR #131

* [docs] Refresh consumer sync and agents documentation (#130)

* [docs] Apply follow-up consumer command corrections (#130)

* Update wiki submodule pointer for PR #131

* docs: Update command syntax for agent synchronization in AGENTS.md

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

---------

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.agents/agents/README.md

@@ -24,6 +24,6 @@ Each agent file uses:
 
 ## Scope
 
-These prompts are specific to the Fast Forward DevTools repository. They define
-durable role behavior and delegation boundaries, while `.agents/skills` remains
-the procedural source of truth.
+These prompts are packaged for Fast Forward repositories. They define durable
+role behavior and delegation boundaries that can be reused in consumer
+repositories, while `.agents/skills` remains the procedural source of truth.

.agents/agents/consumer-sync-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: consumer-sync-auditor
-description: Audit downstream sync and consumer bootstrap impacts for packaged skills, workflows, wiki, and repository defaults.
+description: Audit downstream sync and consumer bootstrap impacts for packaged skills, packaged agents, workflows, wiki, and repository defaults.
 primary-skill: github-pull-request
 supporting-skills:
   - package-readme
@@ -12,19 +12,21 @@ supporting-skills:
 ## Purpose
 
 Review changes through the lens of downstream consumer repositories that rely on
-`dev-tools:sync`, packaged skills, workflow stubs, and wiki/bootstrap assets.
+`dev-tools:sync`, packaged skills, packaged agents, workflow stubs, and
+wiki/bootstrap assets.
 
 ## Responsibilities
 
 - Check whether changes affect consumer-facing synchronized files.
+- Check whether changes affect packaged role prompts as well as packaged skills.
 - Call out downstream bootstrap, workflow, wiki, or onboarding implications.
 - Verify that packaged defaults remain coherent with sync behavior.
 - Surface when docs or README updates are needed for consumer adoption.
 
 ## Use When
 
 - A change touches `resources/`, `.github/workflows/`, `.agents/skills`,
-  `.editorconfig`, wiki automation, or `dev-tools:sync`.
+  `.agents/agents`, `.editorconfig`, wiki automation, or `dev-tools:sync`.
 - A PR may affect how consumer repositories adopt or refresh DevTools assets.
 
 ## Boundaries

.agents/agents/docs-writer.md

@@ -1,6 +1,6 @@
 ---
 name: docs-writer
-description: Create and refresh Sphinx documentation for Fast Forward DevTools under docs/.
+description: Create and refresh Sphinx documentation for Fast Forward repositories under docs/.
 primary-skill: sphinx-docs
 supporting-skills: []
 ---
@@ -10,7 +10,7 @@ supporting-skills: []
 ## Purpose
 
 Keep the Sphinx documentation tree accurate, navigable, and beginner-friendly
-for Fast Forward DevTools users and contributors.
+for Fast Forward repository users and contributors.
 
 ## Responsibilities
 

.agents/agents/issue-editor.md

@@ -10,7 +10,7 @@ supporting-skills: []
 ## Purpose
 
 Shape bugs, features, and maintenance requests into implementation-ready GitHub
-issues for this repository.
+issues for the current repository.
 
 ## Responsibilities
 

.agents/agents/issue-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: issue-implementer
-description: Execute a ready DevTools issue from branch creation through verification and pull request publication.
+description: Execute a ready repository issue from branch creation through verification and pull request publication.
 primary-skill: github-pull-request
 supporting-skills:
   - phpunit-tests
@@ -13,8 +13,8 @@ supporting-skills:
 
 ## Purpose
 
-Carry a ready Fast Forward DevTools issue from local implementation to an open
-or updated pull request.
+Carry a ready repository issue from local implementation to an open or updated
+pull request.
 
 ## Responsibilities
 

.agents/agents/readme-maintainer.md

@@ -1,6 +1,6 @@
 ---
 name: readme-maintainer
-description: Keep the Fast Forward DevTools README aligned with commands, onboarding, links, badges, and public package guidance.
+description: Keep the repository README aligned with commands, onboarding, links, badges, and public package guidance.
 primary-skill: package-readme
 supporting-skills: []
 ---

.agents/agents/test-guardian.md

@@ -1,6 +1,6 @@
 ---
 name: test-guardian
-description: Extend and repair PHPUnit and Prophecy coverage in Fast Forward DevTools.
+description: Extend and repair PHPUnit and Prophecy coverage in Fast Forward repositories.
 primary-skill: phpunit-tests
 supporting-skills: []
 ---

.github/wiki

@@ -38,11 +38,12 @@ composer dev-tools:fix
 composer dev-tools tests         # Run PHPUnit tests
 composer dev-tools code-style    # Check and fix code style (ECS + Composer Normalize)
 composer dev-tools refactor      # Refactor code using Rector
-composer dev-tools phpdoc         # Check and fix PHPDoc comments
+composer dev-tools phpdoc        # Check and fix PHPDoc comments
 composer dev-tools docs          # Generate HTML API documentation
-composer dev-tools wiki         # Generate Markdown documentation for wiki
+composer dev-tools wiki          # Generate Markdown documentation for wiki
 composer dev-tools reports       # Generate docs frontpage and reports
-composer dev-tools:sync         # Sync scripts, GitHub Actions, .editorconfig, wiki
+composer dev-tools agents        # Sync packaged project agents into .agents/agents
+composer dev-tools:sync          # Sync scripts, GitHub Actions, .editorconfig, wiki
 ```
 
 **Notable Specialized Commands:**
@@ -168,6 +169,7 @@ composer dev-tools
 - `docs/usage/` and `docs/internals/`: workflow, reporting, release, and implementation notes
 - `.github/workflows/`: CI and release automation truth, especially `tests.yml`, `reports.yml`, `wiki.yml`, and `changelog.yml`
 - `.github/pull_request_template.md`: expected PR structure and reviewer checklist
+- `src/Sync/`: shared packaged-directory synchronization primitives used by `skills` and `agents`
 - `.agents/skills/`: packaged procedural skills shipped to consumer repositories
 - `.agents/agents/`: repository-specific role prompts mirrored through `.github/agents`
 - `.github/wiki`: generated or synchronized wiki content published by repo workflows
@@ -179,6 +181,7 @@ composer dev-tools
 - **Documentation**: Sphinx-based docs in `docs/` directory
 - **Wiki**: GitHub wiki synced via `dev-tools wiki` and `dev-tools:sync`
 - **GitHub Actions**: Workflows in `.github/workflows/` (synced via `dev-tools:sync`)
+- **Project Agents**: Packaged role prompts synchronized via `composer agents` and `dev-tools:sync`
 
 ## Skills Usage
 
@@ -192,10 +195,10 @@ composer dev-tools
 
 ## Project Agents
 
-Repository-specific agent prompts live in `.agents/agents/` and are mirrored
-through `.github/agents` for GitHub-facing discovery. These role prompts define
-behavior and ownership boundaries, while `.agents/skills/` remains the
-procedural source of truth.
+Packaged project-agent prompts live in `.agents/agents/` for both this
+repository and consumer repositories that synchronize DevTools assets. These
+role prompts define behavior and ownership boundaries, while `.agents/skills/`
+remains the procedural source of truth.
 
 - Use `issue-editor` for issue drafting, refinement, comments, updates, and closure workflows.
 - Use `issue-implementer` for issue-to-branch-to-PR execution.
@@ -204,6 +207,6 @@ procedural source of truth.
 - Delegate to `php-style-curator` for PHPDoc cleanup, file-header normalization, and repository style conformance.
 - Delegate to `readme-maintainer` when public commands, installation, usage, links, or badges change.
 - Delegate to `docs-writer` when `docs/` must be created or updated.
-- Delegate to `consumer-sync-auditor` when packaged skills, sync assets, wiki, workflows, or consumer bootstrap behavior change.
+- Delegate to `consumer-sync-auditor` when packaged skills, packaged agents, sync assets, wiki, workflows, or consumer bootstrap behavior change.
 - Delegate to `quality-pipeline-auditor` when a task changes command orchestration, verification flow, or quality gates.
 - Delegate to `changelog-maintainer` when a task needs changelog authoring, changelog validation for PRs, release promotion, or release-note export.

AGENTS.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add CODEOWNERS generation and sync support for consumer repositories (#67)
 - Package a create-agentsmd skill for repository-level AGENTS.md authoring (#128)
 - Add an agents-maintainer project agent for ongoing AGENTS.md upkeep (#128)
+- Synchronize packaged project-agent prompts into consumer repositories (#130)
 
 ## [1.13.0] - 2026-04-19