Skip to content

AGENTS.md

Latest commit

 

History

History
213 lines (161 loc) · 9.3 KB

AGENTS.md

File metadata and controls

213 lines (161 loc) · 9.3 KB

AGENTS.md

Project Overview

FastForward\DevTools is a Composer plugin that aggregates multiple PHP development tools into a single unified command. It provides automated execution of tests, static analysis, code styling, refactoring, and documentation generation.

Key Technologies:

  • PHP 8.3+
  • Composer plugin
  • PHPUnit 12.5 (testing)
  • Rector 2.x (automated refactoring)
  • Easy Coding Standard (code style)
  • phpDocumentor (API docs)
  • GrumPHP (Git hooks)
  • PHPSpec/Prophecy (test doubles)

Setup Commands

# Install as development dependency
composer require --dev fast-forward/dev-tools:dev-main

# Install dependencies
composer install

Development Workflow

# Run all standard checks (refactoring, code styling, docs, tests, reports)
composer dev-tools

# Automatically fix code standards issues
composer dev-tools:fix

# Individual commands
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 docs          # Generate HTML API documentation
composer dev-tools wiki          # Generate Markdown documentation for wiki
composer dev-tools reports       # Generate docs frontpage and reports
composer dev-tools agents        # Sync packaged project agents into .agents/agents
composer dev-tools:sync          # Sync scripts, GitHub Actions, .editorconfig, wiki

Notable Specialized Commands:

  • composer skills: Synchronize packaged skills into consumer .agents/skills
  • composer funding: Sync funding metadata between composer.json and .github/FUNDING.yml
  • composer codeowners: Generate .github/CODEOWNERS from repository metadata
  • composer gitattributes: Manage export-ignore rules in .gitattributes
  • composer gitignore: Synchronize managed .gitignore content
  • composer license: Generate or refresh repository LICENSE files
  • composer dependencies: Run dependency analysis workflows
  • composer metrics: Generate PhpMetrics reports and related artifacts
  • composer update-composer-json: Normalize managed composer.json settings
  • composer changelog:entry|check|next-version|promote|show: Manage changelog-driven release workflows

Testing Instructions

# Run all tests with coverage
composer dev-tools tests

# Run tests matching a pattern
composer dev-tools tests -- --filter=CodeStyle

# Run with coverage report
composer dev-tools tests -- --coverage=public/coverage

Test Configuration:

  • PHPUnit XML config: phpunit.xml
  • Test namespace: FastForward\DevTools\Tests\
  • Source namespace: FastForward\DevTools\
  • Coverage required (strict metadata enforcement)
  • Coverage threshold: configured in phpunit.xml

Test Patterns:

  • Tests use PHPUnit 12.x with Prophecy for mocking
  • Custom PHPUnit extension: FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension

Creating/Updating Tests:

  • Use skill phpunit-tests in .agents/skills/phpunit-tests/ for creating or updating PHPUnit tests with Prophecy
  • Run skill when: creating new test classes, adding test methods, or fixing existing tests

Code Style

PHP Coding Standard: PSR-12 with Symfony style

ECS Configuration: ecs.php

  • Uses Symfony, PSR-12, and Symplify rule sets
  • PHPDoc alignment: left-aligned
  • PHPUnit test case static methods: use self::
  • Skips: vendor, resources, public, tmp directories

File Organization:

  • Source code: src/ (PSR-4: FastForward\DevTools\)
  • Tests: tests/ (PSR-4: FastForward\DevTools\Tests\)
  • Commands: src/Console/Command/
  • PHPUnit events: src/PhpUnit/Event/
  • Rector rules: src/Rector/
  • Composer plugin: src/Composer/

Naming Conventions:

  • Classes: PascalCase
  • Methods: camelCase
  • Properties: camelCase
  • Constants: UPPER_CASE

PHPdoc Requirements:

  • All classes require docblocks with @copyright and @license
  • Use RFC 2119 keywords (MUST, SHOULD, MAY, etc.)
  • PHPDoc checked via dev-tools phpdoc command
  • Use skill phpdoc-code-style in .agents/skills/phpdoc-code-style/ for PHPDoc cleanup and repository-specific PHP formatting

Build and Deployment

This repository ships a Composer plugin plus the local bin/dev-tools binary, so there is no separate frontend or asset build step. The package is published to Packagist, while consumer repositories adopt workflows, packaged skills, and other managed assets through composer dev-tools:sync.

Release and publishing behavior is driven primarily through .github/workflows/changelog.yml, reports.yml, and wiki.yml, with packaged skills living under .agents/skills/ and mirrored project-agent prompts under .agents/agents/.

Package Details:

  • Type: composer-plugin
  • Class: FastForward\DevTools\Composer\Plugin
  • Minimum stability: stable

Pull Request Guidelines

Required Checks:

composer dev-tools

Before Submitting:

  • Run full dev-tools suite
  • Ensure all tests pass
  • Code style must be clean (ECS)
  • PHPDoc must be valid
  • Coverage must meet threshold
  • Rector should handle refactoring automatically
  • Follow .github/pull_request_template.md and include issue linkage, verification notes, documentation/generated-output review, and changelog status

Canonical References

  • README.md: high-level command surface, architecture overview, and consumer-facing context
  • docs/commands/: command-specific behavior and option details
  • 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

Additional Notes

  • GrumPHP: Automatically runs on pre-commit (configured in grumphp.yml)
  • Rector: Custom rules in src/Rector/ for automated refactoring
  • 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)
  • Dependency Health CI: .github/workflows/tests.yml always runs the dependency-health job, and its default max-outdated input is -1 so outdated packages are reported without failing CI on count alone
  • Project Agents: Packaged role prompts synchronized via composer agents and dev-tools:sync

Skills Usage

  • Creating/Updating Tests: Use skill phpunit-tests in .agents/skills/phpunit-tests/ for PHPUnit tests with Prophecy
  • Creating/Refreshing AGENTS.md: Use skill create-agentsmd in .agents/skills/create-agentsmd/ to generate or update repository-root AGENTS instructions for coding agents
  • Generating Documentation: Use skill sphinx-docs in .agents/skills/sphinx-docs/ for Sphinx documentation in docs/
  • Updating README: Use skill package-readme in .agents/skills/package-readme/ for generating README.md files
  • Updating PHPDoc / PHP Style: Use skill phpdoc-code-style in .agents/skills/phpdoc-code-style/ for PHPDoc cleanup and repository-specific PHP formatting
  • Drafting / Publishing GitHub Issues: Use skill github-issues in .agents/skills/github-issues/ to transform a short feature description into a complete, production-ready GitHub issue and create or update it on GitHub when needed
  • Implementing Issues & PRs: Use skill github-pull-request in .agents/skills/github-pull-request/ to iterate through open GitHub issues and implement them one by one with branching, testing, documentation, and pull requests

Project Agents

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.
  • Delegate to agents-maintainer when repository AGENTS.md guidance needs to be created, refreshed, or realigned with current workflows.
  • 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, 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.