diff --git a/plugins/engineering-playbook/skills/code-review/SKILL.md b/plugins/engineering-playbook/skills/code-review/SKILL.md index c7cf010..f051474 100644 --- a/plugins/engineering-playbook/skills/code-review/SKILL.md +++ b/plugins/engineering-playbook/skills/code-review/SKILL.md @@ -7,9 +7,10 @@ description: Reviews software changes and reports actionable defects. Use for an ## Required Context -Before reviewing the code, read these skills completely: +Read these skills completely before evaluating the change: -- `coding-standards` +- `coding-standards`, including any conditional references applicable to the + request and affected code - `laravel-standards` when the changed code is inside, touches, or affects a Laravel application @@ -17,8 +18,10 @@ Use those standards as hard review criteria, not background suggestions. ## Review Process -1. Identify the exact review scope: pull request, issue implementation, branch - diff, commit diff, staged changes, or working-tree changes. +1. Identify the exact review scope and affected code: pull request, issue + implementation, branch diff, commit diff, staged changes, or working-tree + changes. Complete the conditional-reference check before evaluating the + change. 2. Inspect every changed file line by line. For each changed class, method, function, variable, route, config value, migration, test, and dependency boundary, check whether the implementation is correct and whether the text @@ -31,7 +34,7 @@ Use those standards as hard review criteria, not background suggestions. violation as a `Blocker` finding with the exact file and line. Do not conclude the review until this audit is complete. 5. Check the implementation against: - - coding standards and hexagonal architecture rules + - coding standards and all loaded conditional references - Laravel delivery-layer boundaries and framework conventions - functional correctness against the requested behavior - security, authorization, validation, escaping, secrets, and data exposure diff --git a/plugins/engineering-playbook/skills/coding-standards/SKILL.md b/plugins/engineering-playbook/skills/coding-standards/SKILL.md index 595a1d4..2422bee 100644 --- a/plugins/engineering-playbook/skills/coding-standards/SKILL.md +++ b/plugins/engineering-playbook/skills/coding-standards/SKILL.md @@ -20,7 +20,6 @@ description: Defines shared implementation and review standards loaded by the de - Use `validate...` for value object validation methods that throw, and make them return `void`. Use predicate names such as `is...`, `has...`, or `does...` only for methods that return `bool` and do not throw. -- In PHP tests, mark test methods with the `#[Test]` attribute instead of the `test...` prefix or `@test` docblock annotation. ## Rule: Truthful Naming All text and names must tell the truth about the implementation they represent. @@ -32,40 +31,16 @@ All text and names must tell the truth about the implementation they represent. 3. Prefer renaming over hiding behavior behind vague, aspirational, or overly-polished language. -## Rule: GDPR -During every feature implementation and code review, check whether personal data -is involved. If so, do not complete or approve the change until these are clear: +## Conditional References -- Why the data is collected and the lawful basis. -- How the minimum necessary data is processed and protected. -- How long the data is retained. -- When and how the data is deleted. +After identifying the affected code, read only the references that apply: -Treat unknown GDPR requirements as blockers and request privacy or legal guidance. - -## Rule: Hexagonal Architecture -Follow hexagonal architecture as the baseline. - -- Organize each business module in `src` as `Domain`, `Application`, and `Infrastructure`; - dependencies point inward only. -- Before writing or reviewing any conditional, validation, state transition, - calculation, policy, or workflow decision, ask: "Is this a business rule?" -- If the answer is yes, put it in `Domain`. This is a hard requirement: business - rules must never live in `Application`, `Infrastructure`, framework code, - adapters, controllers, jobs, requests, commands, listeners, or UI glue. -- Use `Application` only for use-case orchestration, transaction boundaries, - authorization handoff, domain calls, ports, and input/output mapping. -- Use `Infrastructure` only for adapters such as persistence, queues, HTTP - clients, framework integration, and serialization. -- Treat framework applications as infrastructure adapters only; do not create - or hide `Domain`, `Application`, business rules, or use-case orchestration - there. -- Use cases live under `/Application/UseCase`, start with a verb, end - with `UseCase`, do one user-intent only, and expose exactly one public method: - `__invoke`. For example, use `CreateUserUseCase`, not - `UserCreationUseCase`. -- Use explicit parameters on `__invoke`; add input DTOs only when they provide - real behavior, reuse, validation, normalization, or boundary mapping. -- Ports are interfaces named `*Interface`; domain-needed ports live in - `Domain`, application-needed ports live in `Application`, and concrete - adapters live in `Infrastructure`. +- Read [privacy.md](references/privacy.md) when the request, issue, or affected + data flow handles personal data or changes its collection, processing, + storage, exposure, retention, or deletion. +- Read [architecture.md](references/architecture.md) when the affected code + contains a conditional, validation, state transition, calculation, policy, + or workflow decision that may be business behavior, or when the change + affects a business module, use case, port, adapter, or layer boundary. +- Read [php-testing.md](references/php-testing.md) before adding, updating, or + reviewing PHP tests. diff --git a/plugins/engineering-playbook/skills/coding-standards/references/architecture.md b/plugins/engineering-playbook/skills/coding-standards/references/architecture.md new file mode 100644 index 0000000..ef51b4a --- /dev/null +++ b/plugins/engineering-playbook/skills/coding-standards/references/architecture.md @@ -0,0 +1,27 @@ +# Hexagonal Architecture + +Follow hexagonal architecture as the baseline. + +- Organize each business module in `src` as `Domain`, `Application`, and `Infrastructure`; + dependencies point inward only. +- Before writing or reviewing any conditional, validation, state transition, + calculation, policy, or workflow decision, ask: "Is this a business rule?" +- If the answer is yes, put it in `Domain`. This is a hard requirement: business + rules must never live in `Application`, `Infrastructure`, framework code, + adapters, controllers, jobs, requests, commands, listeners, or UI glue. +- Use `Application` only for use-case orchestration, transaction boundaries, + authorization handoff, domain calls, ports, and input/output mapping. +- Use `Infrastructure` only for adapters such as persistence, queues, HTTP + clients, framework integration, and serialization. +- Treat framework applications as infrastructure adapters only; do not create + or hide `Domain`, `Application`, business rules, or use-case orchestration + there. +- Use cases live under `/Application/UseCase`, start with a verb, end + with `UseCase`, do one user-intent only, and expose exactly one public method: + `__invoke`. For example, use `CreateUserUseCase`, not + `UserCreationUseCase`. +- Use explicit parameters on `__invoke`; add input DTOs only when they provide + real behavior, reuse, validation, normalization, or boundary mapping. +- Ports are interfaces named `*Interface`; domain-needed ports live in + `Domain`, application-needed ports live in `Application`, and concrete + adapters live in `Infrastructure`. diff --git a/plugins/engineering-playbook/skills/coding-standards/references/php-testing.md b/plugins/engineering-playbook/skills/coding-standards/references/php-testing.md new file mode 100644 index 0000000..16cad5e --- /dev/null +++ b/plugins/engineering-playbook/skills/coding-standards/references/php-testing.md @@ -0,0 +1,4 @@ +# PHP Testing + +In PHP tests, mark test methods with the `#[Test]` attribute instead of the +`test...` prefix or `@test` docblock annotation. diff --git a/plugins/engineering-playbook/skills/coding-standards/references/privacy.md b/plugins/engineering-playbook/skills/coding-standards/references/privacy.md new file mode 100644 index 0000000..c9a7c1d --- /dev/null +++ b/plugins/engineering-playbook/skills/coding-standards/references/privacy.md @@ -0,0 +1,11 @@ +# Privacy + +During every feature implementation and code review, check whether personal data +is involved. If so, do not complete or approve the change until these are clear: + +- Why the data is collected and the lawful basis. +- How the minimum necessary data is processed and protected. +- How long the data is retained. +- When and how the data is deleted. + +Treat unknown GDPR requirements as blockers and request privacy or legal guidance. diff --git a/plugins/engineering-playbook/skills/development/SKILL.md b/plugins/engineering-playbook/skills/development/SKILL.md index daea30b..d3982ba 100644 --- a/plugins/engineering-playbook/skills/development/SKILL.md +++ b/plugins/engineering-playbook/skills/development/SKILL.md @@ -14,6 +14,9 @@ source of truth. ## Load First - Read `coding-standards`. +- After identifying the affected code, apply its conditional-reference loading + rules and read only the references that apply before choosing an + implementation or editing files. - Read `creating-skills` before creating or editing a skill or any file referenced by a skill. - Read `pull-request` before creating or preparing a pull request. @@ -25,7 +28,8 @@ source of truth. 1. Identify the goal, context, constraints, and done condition. If a GitHub issue is provided, read it before editing and extract the problem, expected behavior, acceptance criteria, and non-goals. -2. Inspect the relevant code, tests, and documented commands before choosing an +2. Inspect the relevant code, tests, data flows, and documented commands. Use + that scope to complete the conditional-reference check before choosing an implementation. 3. Ask only blocking questions. If the request is clear enough to implement, start without waiting.