agentsclimarketplace

Spec

Skill BULDEE/ai-craftsman-superpowers/skills/spec

Specification-first development (BDD/TDD). Use when implementing new features, creating new components, or when requirements need clarification through tests.From its SKILL.md

Install
npx -y skills add BULDEE/ai-craftsman-superpowers --skill spec

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

6.7 KB, as published. Nobody here has run it

/craftsman:spec - Specification-First Development

Outcome Contract

  • Outcome: executable specifications that fail for the right reason before any implementation exists.
  • Done when: each acceptance criterion maps to a test, every test fails first with a meaningful message, and the scope excluded is stated.
  • Evidence: the failing test output before implementation.

You are a Senior Engineer practicing TDD/BDD. You write SPECS before CODE.

Philosophy

"If you can't write the test, you don't understand the requirement."

The Iron Law

┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│           NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST       │
│                                                                  │
│   Wrote code before test? Delete it. Start over with TDD.       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Process (STRICT ORDER)

Phase 1: Behavior Discovery

Answer these questions:

## Behavior Specification

### SHOULD (Happy paths)
- [ ] Accept valid email formats
- [ ] Create user with correct initial state
- [ ] Emit UserCreated event

### SHOULD NOT (Explicit non-behaviors)
- [ ] Validate if email actually exists (external concern)
- [ ] Modify the email string after creation

### EDGE CASES
- [ ] Empty string → Exception
- [ ] Very long email (>254 chars) → Exception
- [ ] Unicode characters → Handled correctly
- [ ] Multiple @ symbols → Exception

### ERROR SCENARIOS
- [ ] Invalid format → InvalidEmailException
- [ ] Null input → TypeError

Phase 2: Test Specification

Write test METHOD NAMES ONLY (no implementation yet):

final class EmailTest extends TestCase
{
    // Happy paths
    public function test_creates_email_from_valid_string(): void
    public function test_two_emails_with_same_value_are_equal(): void
    public function test_preserves_original_case_in_value(): void

    // Edge cases
    public function test_rejects_empty_string(): void
    public function test_rejects_string_without_at_symbol(): void
    public function test_rejects_email_longer_than_254_characters(): void

    // Behavior
    public function test_comparison_is_case_insensitive(): void
}

Ask user: "Does this test list cover the expected behavior?"

Phase 3: RED - Write Failing Tests

Implement test bodies. They MUST fail (class doesn't exist yet).

public function test_creates_email_from_valid_string(): void
{
    $email = Email::fromString('[email protected]');

    self::assertSame('[email protected]', $email->toString());
}

public function test_rejects_empty_string(): void
{
    $this->expectException(InvalidEmailException::class);

    Email::fromString('');
}

Run tests - Confirm RED:

vendor/bin/phpunit --filter=EmailTest
# Expected: FAILURES (class Email does not exist)

Phase 4: GREEN - Minimal Implementation

Write the MINIMUM code to make tests pass. No more, no less.

<?php

declare(strict_types=1);

namespace App\Domain\ValueObject;

final class Email
{
    private function __construct(
        private readonly string $value,
    ) {
    }

    public static function fromString(string $value): self
    {
        if ($value === '') {
            throw InvalidEmailException::empty();
        }

        if (!str_contains($value, '@')) {
            throw InvalidEmailException::missingAtSymbol($value);
        }

        return new self($value);
    }

    public function toString(): string
    {
        return $this->value;
    }
}

Run tests - Confirm GREEN:

vendor/bin/phpunit --filter=EmailTest
# Expected: OK (X tests, Y assertions)

Phase 5: REFACTOR

Improve code while keeping tests GREEN:

  • Extract private methods
  • Improve naming
  • Remove duplication
  • Add Value Object behaviors

After each change, run tests to confirm still GREEN.

Test Quality Rules

RuleWhy
Test BEHAVIOR, not implementationTests survive refactoring
One concept per testClear failure messages
Test names are documentationtest_rejects_email_without_domain
No mocking the unit under testYou'd test the mock
Use DataProviders for variantsDRY, comprehensive

DataProvider Pattern

#[DataProvider('invalidEmailProvider')]
public function test_rejects_invalid_emails(string $invalidEmail): void
{
    $this->expectException(InvalidEmailException::class);

    Email::fromString($invalidEmail);
}

public static function invalidEmailProvider(): iterable
{
    yield 'empty string' => [''];
    yield 'no @ symbol' => ['testexample.com'];
    yield 'no domain' => ['test@'];
    yield 'spaces' => ['test @example.com'];
    yield 'multiple @' => ['test@@example.com'];
}

Output Structure

# Always create test FIRST
tests/Unit/Domain/ValueObject/EmailTest.php  ← FIRST

# Then implementation
src/Domain/ValueObject/Email.php             ← SECOND

Red Flags - STOP and Start Over

Red FlagAction
Code before testDelete code, write test first
Test passes immediatelyYou wrote implementation first
Can't explain why test failedYou don't understand the requirement
"I already manually tested it"Manual ≠ Automated. Write the test.

Output Format

## Specification: [Component]

### Behaviors to Test
1. [Behavior 1] - MUST TEST (critical)
2. [Behavior 2] - MUST TEST (core functionality)
3. [Behavior 3] - SKIP (framework handles this)

### Test File
`tests/Unit/Domain/ValueObject/EmailTest.php`

### Tests (8 total)
- test_creates_email_from_valid_string ✅
- test_rejects_empty_string ✅
- test_rejects_invalid_format ✅
- ...

### Implementation File
`src/Domain/ValueObject/Email.php`

### Verification

vendor/bin/phpunit --filter=EmailTest OK (8 tests, 12 assertions)

Bias Protection

Acceleration: "Skip tests, just implement" → Tests ARE the spec. No tests = no spec = bugs.

Over-optimization: "Add extra features while implementing" → YAGNI. Minimal code to pass tests. Nothing more.

Keep looking

Skills are one crate of 614,194. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.