Workplan Execution

# M{id} — {Feature Title} Workplan

> **Phase:** M{id} — {Feature Title}
> **Duration:** {estimated time}
> **Work Units Backend:** {count}
> **Work Units Frontend:** {count}
> **Prerequisites:** {list of completed milestones, or "None"}

## Context

**Problem:** {What problem does this feature solve?}

**Objective:** {One-sentence goal}

**Non-Goals:**
- {Feature or scope item explicitly excluded}
- {Another excluded item}
- {A third excluded item}

## WU-B01: Domain Primitives

**Objective:** Create foundational models, migrations, factories, enums,
and DTOs for the notifications feature.

**Files (8):**
- `database/migrations/2026_01_15_000001_create_notifications_table.php` (new)
- `app/Domain/Notification/Enums/NotificationType.php` (new)
- `app/Domain/Notification/Enums/NotificationChannel.php` (new)
- `app/Models/Notification.php` (new)
- `database/factories/NotificationFactory.php` (new)
- `app/Application/Notification/DTO/CreateNotificationData.php` (new)
- `tests/Unit/Domain/Notification/Enums/NotificationTypeTest.php` (new)
- `tests/Unit/Domain/Notification/Enums/NotificationChannelTest.php` (new)

**Dependencies:** None

### Implementation Details

- Migration: UUID primary key, `tenant_id` FK (indexed), `user_id` FK,
  `type` enum, `channel` enum, `data` JSON, timestamps, soft deletes
- Model: `BelongsToTenant` trait, `HasUuids`, `HasFactory`, `SoftDeletes`
- Factory: realistic states for each notification type
- Enums: include helper methods (`isTransient()`, `requiresDelivery()`)

### Acceptance Criteria
- [ ] Migration creates `notifications` table with UUID PK and tenant_id FK
- [ ] Model uses `BelongsToTenant`, `HasUuids`, `HasFactory`
- [ ] Factory includes states for each notification type
- [ ] 2 enums with helper methods
- [ ] `docker compose exec php vendor/bin/pint --dirty` passes
- [ ] 8 tests passing

### Verification Commands
```bash
docker compose exec php php artisan test --compact --filter=Notification
docker compose exec php vendor/bin/pint --dirty
docker compose exec php vendor/bin/phpstan analyse --memory-limit=1G

Key rules for WU specifications:

- **Each WU should be completable in a single session** — if it requires multiple sessions, split it
- **Tests are part of the WU**, not a separate WU — implementation and testing happen together
- **File paths are explicit** — not "create a migration" but the exact migration filename
- **Acceptance criteria are objectively verifiable** — "8 tests passing" not "good test coverage"

---

## Progress Tracking

A companion tracking file records the actual implementation of each Work Unit. It mirrors the workplan structure but captures what was actually built, not what was planned.

### Initial State

When a milestone begins, the tracking file is initialized:

```markdown
# Current Work Unit Progress — M{id}

**Milestone:** M{id} — {Feature Title}
**Last Updated:** 2026-03-27

---

(Work units will be documented here as they are completed.)

## WU-B01: Domain Primitives

**Status:** Completed

### Overview
Created foundational models, migrations, factories, and enums for the
notifications feature. Includes 2 enums with helper methods, 1 model
with tenant scoping, and 1 factory with type-specific states.

### Files Created
| File | Purpose |
|------|---------|
| `database/migrations/..._create_notifications_table.php` | Notifications table with UUID PK, tenant_id FK |
| `app/Domain/Notification/Enums/NotificationType.php` | Enum: email, push, sms with `isTransient()` helper |
| `app/Models/Notification.php` | Eloquent model with BelongsToTenant, HasUuids |
| `database/factories/NotificationFactory.php` | Factory with states per notification type |
| `app/Application/Notification/DTO/CreateNotificationData.php` | Input DTO for notification creation |

### Files Modified
| File | Changes |
|------|---------|
| None | — |

### Test Coverage
| Test File | Tests | Description |
|-----------|-------|-------------|
| `NotificationTypeTest.php` | 5 | Enum values, helpers, edge cases |
| `NotificationChannelTest.php` | 3 | Channel validation and properties |

### Verification Commands
```bash
docker compose exec php php artisan test --compact --filter=Notification
docker compose exec php vendor/bin/pint --dirty

This creates a complete audit trail: what was built, how it was verified, what tests cover it. When you return to the project weeks later — or when a different developer picks up the next milestone — the tracking file shows exactly where things stand.

---

## The /implement-wu Workflow

The [`/implement-wu`](/docs/ai-assisted-development/claude-code/skills-system) skill automates the execution of individual Work Units. It follows a strict five-phase process.

### Phase 1 — Context (Read Only)

The agent reads before it writes:

1. Parses the arguments to identify the target milestone and WU (e.g., `M6 WU-B03`)
2. Reads the **tracking file** to check if the WU is already completed
3. Reads the **workplan** to extract the full WU specification
4. Checks the **dependency graph** — if any prerequisite WU is not completed, the agent stops and reports
5. Loads **project conventions** (CLAUDE.md, API contracts) based on WU scope

::callout{type="warning"}
Phase 1 is not optional. The agent never writes code before reading the workplan and verifying dependencies. If a dependency is unmet, it reports the blocker instead of proceeding.
::

### Phase 2 — Plan (User Validation)

The agent presents a plan and waits for your approval:

1. Lists all files to create and modify, with purposes
2. Finds **reference patterns** — existing similar files in the codebase to match structure and conventions
3. Identifies **test scenarios** from the acceptance criteria
4. Presents the full plan including any concerns or questions

The agent does **not** proceed to implementation until you explicitly validate the plan. This is your last chance to catch misunderstandings before code is written.

### Phase 3 — Implementation

With the plan approved, the agent implements:

1. Reads each reference pattern file identified in Phase 2
2. Implements following the same structure and conventions
3. Writes **tests in parallel with code** — not after. For each piece of functionality, the implementation file and its test are created together.
4. Adds **translations** in all 4 locales (en, fr, es, it) if the WU introduces user-facing strings

### Phase 4 — Quality Gate

Before marking the WU as complete, the agent runs all relevant checks:

::code-group
```bash [Backend]
# Code formatting
docker compose exec php vendor/bin/pint --dirty

# Static analysis
docker compose exec php vendor/bin/phpstan analyse --memory-limit=1G

# Targeted tests
docker compose exec php php artisan test --compact --filter=<RelevantTest>

// Reference: app/Application/Billing/DTO/CreateSubscriptionData.php
final readonly class CreateNotificationData
{
    public function __construct(
        public string $tenantId,
        public string $userId,
        public NotificationType $type,
        public NotificationChannel $channel,
        public array $data,
    ) {}
}

- [ ] 8 tests passing (24 assertions) covering happy path, validation, and tenant isolation
- [ ] `docker compose exec php vendor/bin/pint --dirty` produces no changes
- [ ] `docker compose exec php vendor/bin/phpstan analyse` passes at level 9

**Non-Goals:**
- Email notifications (future milestone)
- Notification preferences UI
- Notification batching or digest
- WebSocket real-time delivery (use polling in V1)