Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (75 loc) · 6.06 KB

AGENTS.md

File metadata and controls

88 lines (75 loc) · 6.06 KB
Raw

Instruction Economy (check before EVERY instruction you add)

Before adding an instruction ANYWHERE (AGENTS.mds, rules, agents, skills, hooks, configs): prefer the NATIVE mechanism (frontmatter field, config key, existing rule, a router to the single source) over new prose, and prefer DELETING prose over adding it. Every added instruction is a contradiction-and-drift surface; condensed copies of another artifact's content drift silently. Success metric: the diff shrinks or holds while capability grows. Consistency beats token thrift.

Before doing anything read this file to ensure you are up to date with it.

Project Instructions

Dependencies

  • Install: make install.
  • Require a new package: make composer-require "PACKAGENAME" or make composer-require "PACKAGENAME --dev".

Executing commands

  • Do now use cd for everything, you're already in the root!
  • Check make help for all available commands.
  • Check make help-contrib for all available contrib commands.
  • Need something custom that is not in the list? Use make run "YOUR COMMAND HERE" to run a command in the container and run whatever you require there.
  • If a package needs custom make commands, put them in etc/Makefile, then run make install to make them available through the root Makefile.
  • Always split tasks up in small chunks and feed those to sub agents, then collect what comes out of that, make logical groups for the next set of tasks to be split over subagents.

Flow

  • After each logical block of changes made ensure make contrib passes.
  • Before you return to the uses run make to ensure all QA checks pass.
  • Use make unit-testing-filter TESTCLASSNAME_OR_TESTMETHODNAME to run a specific test.
  • Always add unit tests for new code.
  • If composer.lock is out of sync with composer.json, run make update.

Writing code

  • Keep things simple, once done implementing a feature, iterate on improving it. Less code is more.
  • Make sure the code is readable and easy to understand.
  • Prefer a logical block of code to be within one screen size over splitting it up in multiple smaller functions.
  • Make a class static if it doesn't hold state.
  • Put classes in logical folders.
  • Once done writing code iterate of it to make sure it's easy to understand and maintain, that it's easy to test, and that it doesn't duplicate code.
  • Search existing code for examples of how to do things.
  • Search existing code for classes/methods you can use instead of writing your own.

Markdown

  • Always link every reference that has a URL ([label](url)); never bare backticks or plain text alone
  • Composer packages → GitHub repo (resolve via Packagist); docs and specs → canonical URL

Unit tests

  • Test the happy flows (PHPUnit)
  • Test the unhappy flows (PHPUnit)
  • Test the edge cases (PHPUnit)
  • Test the fuzzy cases (PHPUnit)
  • 100% coverage is required (PHPUnit)
  • 100% MSI is required (mutation testing (InfectionPHP))
  • 100% type coverage is required (PHPStan)
  • Use dataproviders wherever possible (PHPUnit)
  • Prefer creating subs and spies over mocks
  • Look at wyrihaximus/test-utilities and wyrihaximus/async-test-utilities for some useful helpers
  • When tests are known to take longer than 10 seconds, when possible use make unit-testing-filter TESTCLASSNAME_OR_TESTMETHODNAME to run them in parallel across subagents

Immutable laws

  • Consistency is the key.
  • Always add regressions to the test suite when fixing bugs or when the user tells you whatever you wrote is still broken.
  • If several parts of the code rely on the same behavior (and data), centralize it in a single place.
  • Always run make before you're returning control to the user.
  • Always apply the boyscout rule: Leave the code better than you found it. But do not touch anything else than what you're touching.
  • Always reload this file before you start processing a new request.
  • Always show the plan. / When calling CreatePlan always show the plan.
  • When ever you're done, before returning to the user always done 1 to 3 passes of reducing the amount of code you wrote while keeping it readable and maintainable.
  • Shutdown works by removing everything that uses the event loop; never call Loop::stop() anywhere.
  • Always extend PHPUnit test classes from WyriHaximus\AsyncTestUtilities\AsyncTestCase or WyriHaximus\TestUtilities\TestCase.

Packages to consider when working with logging

Forbidden commands

  • Never call, attempt or even consider to use sudo
  • Never call, attempt or even consider to use su
  • Never call, attempt or even consider to use sudo su
  • Never call, attempt or even consider to use cd
  • Never call, attempt or even consider to use docker
  • Never call, attempt or even consider to use git commit
  • Never call, attempt or even consider to use git push
  • Any command not in the allowed commands list
  • Never, ever, ever use — in documentation!!!!!

Forbidden actions

  • Create dead/unused methods/classes/functions/code
  • Using the assert function
  • Assigning a property to a variable without assigning a new value to it
  • Never update Makefile or AGENTS.md outside wyrihaximus/makefiles; suggest changes to that repository instead