Add role-based project agents for DevTools workflows

[coisa]

Objective

Create repository-specific agent definitions for Fast Forward DevTools so recurring responsibilities have dedicated behavioral prompts in addition to procedural skills.

Current Limitation

The repository already packages useful skills under .agents/skills, but contributors and AI assistants still need to infer the right role, tone, boundaries, and responsibility split for each task. Skills describe procedures; agents should describe durable role behavior and delegation boundaries.

Proposed Work

Add .agents/agents with a focused set of project agents, wire them into the repository guidance, and expose them through .github/agents for GitHub-oriented discovery.

Agent Set

Create initial agent definitions for:

• issue-editor: triages short requests into implementation-ready GitHub issues and maintains issue lifecycle actions.
• issue-implementer: takes a ready issue through branch, implementation, verification, and pull request.
• test-guardian: creates, extends, and repairs PHPUnit/Prophecy tests.
• php-style-curator: normalizes PHP style, PHPDoc, headers, and repository wording without behavior changes.
• readme-maintainer: keeps README onboarding, links, installation, usage, and discovery content aligned with the package.
• docs-writer: creates and updates Sphinx/reStructuredText documentation under docs/.
• consumer-sync-auditor: audits impacts on dev-tools:sync, packaged skills, .editorconfig, workflows, wiki, and downstream bootstrap behavior.
• quality-pipeline-auditor: evaluates cross-tool quality pipeline impacts across tests, code style, PHPDoc, docs, reports, and dependency analysis.

Scope

• Define an agent file format and naming convention under .agents/agents.
• Each agent definition should include purpose, responsibilities, when to use it, boundaries, and primary/supporting skills.
• Update AGENTS.md with guidance for when to use each agent.
• Add or document the symlink .github/agents -> ../.agents/agents or equivalent repository-safe link target.
• Ensure sync/downstream impact is considered if agents should be packaged or exposed to consumer repositories.
• Add docs or README notes if agent discovery is part of the public contributor workflow.

Non-goals

• Replacing existing skills.
• Implementing an agent runtime or custom dispatcher.
• Creating agent definitions for every possible task in the first pass.
• Changing GitHub issue or pull request workflows beyond documenting agent responsibilities.

Acceptance Criteria

Functional Criteria

• .agents/agents exists and contains definitions for the eight initial agents.
• Each agent definition names its primary responsibility and supported tasks.
• Each agent definition references its primary skill or supporting skills where applicable.
• AGENTS.md includes clear rules mapping common work types to these agents.
• .github/agents exposes the agent definitions through a symlink or documented equivalent.
• The implementation preserves existing .agents/skills behavior.

Content Criteria

• issue-editor is clearly scoped to issue drafting, refinement, comments, updates, and closure.
• issue-implementer is clearly scoped to issue-to-branch-to-PR execution.
• test-guardian is clearly scoped to PHPUnit/Prophecy testing.
• php-style-curator is clearly scoped to PHPDoc/style cleanup without behavior changes.
• readme-maintainer is clearly scoped to README maintenance.
• docs-writer is clearly scoped to Sphinx docs.
• consumer-sync-auditor is clearly scoped to downstream sync assets and consumer bootstrap behavior.
• quality-pipeline-auditor is clearly scoped to cross-tool pipeline validation.

Architectural / Isolation Criteria

• Agent prompts describe role behavior while skills remain the procedural source of truth.
• Agent definitions avoid duplicating full skill instructions; they link or reference skills instead.
• The structure can support future agents without changing existing skill paths.
• Any symlink target works from the repository root and remains portable in Git.

Implementation Notes

A possible AGENTS.md mapping:

- Use `issue-editor` for issue drafting, refinement, comments, and closure workflows.
- Use `issue-implementer` for issue-to-branch-to-PR execution.
- Delegate to `test-guardian` whenever behavior changes, regressions, or missing coverage are involved.
- 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 `quality-pipeline-auditor` when a task changes command orchestration, verification flow, or quality gates.