agentleFS
ci4meci4me/CQRSTemplate/.claude/skills/business-rule-addition/SKILL.md

business-rule-addition

Skill0 starsChanged 6 months agoMITView on GitHub

Adds a new business rule/validation rule/business constraint/invariant/domain logic to a domain, determining correct placement (value object, entity, or handler) and creating comprehensive tests. Use when user requests to add business logic, validation rules, constraints, or invariants. Provides placement guidance.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When should this rule be enforced?

    line 17

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Business Rule Addition Skill

Guides adding business rules with correct placement and testing.


Step 1: Understand the Rule

Ask user:

  1. What is the business rule? (describe in plain language)
  2. When should this rule be enforced?
  3. What data does the rule need to evaluate?
  4. What should happen if rule is violated?

Step 2: Determine Correct Placement

Use decision tree: See patterns/placement-decision-tree.md

Quick reference:

  • Single value validity? → Value Object
  • Single entity consistency? → Entity Method
  • Multiple entities or cross-aggregate? → Handler (Domain Service)

Invoke ddd-specialist for placement guidance.


Step 3: Implement in Value Object (If Applicable)

Pattern:

private function __construct(private type $value)
{
    // Validate rule
    if (/* violation */) {
        throw ValidationException::ruleViolated(/* details */);
    }
}

Examples:

  • Price must be >= $0.01
  • Name length 3-100 characters
  • Email must match format
  • Date must be in future

Invoke: ddd-specialist + php-specialist


Step 4: Implement in Entity (If Applicable)

Pattern:

public function businessOperation(params): void
{
    // Check invariant
    if (/* violation */) {
        throw ValidationException::ruleViolated(/* details */);
    }

    // Apply change
    $this->property = newValue;
}

Examples:

  • Cannot decrease stock below zero
  • Cannot activate without stock
  • Cannot apply discount to discounted item
  • Cannot change status in certain states

Detailed Example: See examples/complex-rule-example.md

Invoke: ddd-specialist + clean-code-specialist


Step 5: Implement in Handler (If Applicable)

Pattern:

public function handle(Command $command): ReturnType
{
    // Check cross-aggregate rule
    if (/* violation */) {
        throw ValidationException::ruleViolated(/* details */);
    }

    // Proceed with operation
}

Examples:

  • Cannot create duplicate names
  • Cannot exceed system limits
  • Cannot violate referential integrity
  • Cannot conflict with existing records

Invoke: cqrs-specialist + clean-code-specialist


Step 6: Create Comprehensive Tests

For EACH rule, create tests:

  • Happy path (rule passes)
  • Each violation condition
  • Boundary values (min, max, zero, negative)
  • Edge cases (null, empty, extreme values)

Test naming:

public function test_throws_exception_when_{specific_violation}(): void
{
    $this->expectException(ValidationException::class);
    // Code that violates rule
}

Complete test examples: See examples/complex-rule-example.md

Invoke: test-specialist for comprehensive coverage


Step 7: Document the Rule

Add AI-optimized docblock:

/**
 * {Action description}.
 *
 * @ai-context Business Rule: {Rule name}
 *             Enforces: {What constraint}
 *             Reason: {Why rule exists}
 *
 * @ai-pattern {Pattern name}
 *
 * @ai-example
 * ```php
 * ${entity}->{method}({params});
 * // Throws if {violation condition}
 * ```
 *
 * @param {Type} ${param} {Description}
 *
 * @return {Type}
 *
 * @throws ValidationException If {violation description}
 *
 * @debugPoint Inspect {what to check} during debugging
 */

Step 8: Validate Implementation

Run checks:

vendor/bin/phpstan analyse --level=8
vendor/bin/phpcs
vendor/bin/phpunit --filter={RuleTest}

Invoke:

  1. phpstan-specialist (type safety)
  2. slevomat-specialist (code style)
  3. test-specialist (coverage maintained)

Completion Checklist

  • Rule placement determined correctly
  • Rule implemented in appropriate location
  • Exception messages are descriptive
  • All violation paths tested
  • Boundary conditions tested
  • AI-optimized docblock added
  • PHPStan passes
  • Slevomat passes
  • Test coverage maintained at 90%+

Supporting Documentation

Patterns:

  • patterns/placement-decision-tree.md - Complete decision flowchart with examples

Examples:

  • examples/complex-rule-example.md - Entity method example with full test suite

References:

  • .claude/documentation/BUSINESS_RULE_PROTOCOL.md - Complete protocol
  • Cookie domain - Reference implementation

Business rules are the CORE of the domain. Implement and test thoroughly.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.