@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/generic/delegation/references/implementer-prompt.md

@@ -0,0 +1,401 @@
+# Implementer Prompt Template
+
+**Note:** On Claude Code, this template is compiled into `servers/exarchos-mcp/src/agents/definitions.ts` (IMPLEMENTER spec) and the native agent file `agents/exarchos-implementer.md` is generated from the registry at build time. This reference document is the canonical prompt evolution record and is used directly by cross-platform clients (Cursor, Copilot CLI, etc.) that lack native agent support.
+
+Use this template when dispatching tasks via the Task tool.
+
+## Quality Hints Integration
+
+Before dispatch, query `exarchos_view` with `action: 'quality_hints'` and `skill: '<skill-name>'` to retrieve quality signals for the target skill. If the returned `hints` array is non-empty, include the **Quality Signals** section in the prompt. If empty, omit it entirely.
+
+## Template
+
+```markdown
+# Task: [Task Title]
+
+## Working Directory
+[Absolute path to worktree or project root]
+
+## CRITICAL: Worktree Verification (MANDATORY)
+
+Before making ANY file changes, you MUST verify you are in a worktree:
+
+1. Run: `pwd`
+2. Verify the path contains `.worktrees/`
+3. If NOT in a worktree directory:
+   - STOP immediately
+   - Report: "ERROR: Working directory is not a worktree. Aborting task."
+   - DO NOT proceed with any file modifications
+
+**Example verification:**
+```bash
+pwd | grep -q "\.worktrees" || { echo "ERROR: Not in worktree!"; exit 1; }
+```
+
+This check prevents accidental modifications to the main project root, which would cause merge conflicts with other parallel tasks.
+
+## Task Description
+[Full task description from implementation plan - never reference external files]
+
+## Files to Modify
+
+### Create/Modify:
+- `[path/to/file.ts]` - [Brief description of changes]
+
+### Test Files:
+- `[path/to/file.test.ts]` - [Test file to create/modify]
+
+## TDD Requirements (MANDATORY)
+
+You MUST follow strict Test-Driven Development:
+
+### Phase 1: RED - Write Failing Test
+
+1. Create test file at the specified path
+2. Write test with name: `[MethodName]_[Scenario]_[ExpectedOutcome]`
+3. Run tests: `npm run test:run`
+4. **VERIFY test fails for the expected reason**
+5. Do NOT proceed until you've witnessed the failure
+
+### Phase 2: GREEN - Minimum Implementation
+
+1. Write the minimum code to make the test pass
+2. No additional features or optimizations
+3. Run tests: `npm run test:run`
+4. **VERIFY test passes**
+
+### Phase 3: REFACTOR - Clean Up
+
+1. Apply SOLID principles if applicable
+2. Extract helpers for clarity
+3. Run tests after each change
+4. **VERIFY tests stay green**
+
+## Testing Approach (Testing Trophy)
+
+Prefer **integration tests with real collaborators** (sociable tests). Mock only at infrastructure boundaries (HTTP, database, filesystem). This gives the best confidence-per-effort ratio.
+
+- **Acceptance test tasks** (`testLayer: acceptance`): Use real collaborators throughout. No mocks except true external boundaries. This test stays RED until inner tasks complete — it is the "north star."
+- **Integration test tasks** (`testLayer: integration`): Default layer. Use real collaborators, mock only infrastructure boundaries.
+- **Unit test tasks** (`testLayer: unit`): For isolated complex logic only. Mocking is acceptable here.
+
+## Characterization Testing
+
+When a task has `characterizationRequired: true`, capture existing behavior BEFORE modifying code:
+
+1. Write tests that document what the code **currently does** (not what it should do)
+2. Use snapshot-style assertions: capture output, assert it matches
+3. Make your changes — any characterization test failure means behavior changed
+4. Document which characterization test failures are intentional vs accidental
+
+## Acceptance Test Completion Check
+
+When a task has `acceptanceTestRef`, run the parent acceptance test after completing your inner task:
+- Still failing → expected (other inner tasks may not be complete yet)
+- Now passing → the feature may be complete; report this in your completion output
+
+## Property-Based Testing Patterns
+
+When this task has `testingStrategy.propertyTests: true`, write property tests alongside example tests during the RED phase. Use the patterns from `@skills/delegation/references/pbt-patterns.md`:
+
+- **Roundtrip:** For encode/decode pairs, verify `decode(encode(x)) === x` for all inputs
+- **Invariant:** For operations with business rules, verify bounds/constraints hold for all inputs
+- **Idempotence:** For normalization/formatting, verify `f(f(x)) === f(x)` for all inputs
+- **Commutativity:** For order-independent operations, verify `f(a, b) === f(b, a)` for all inputs
+
+**TypeScript:** Use `fast-check` with `fc.property`, `fc.assert`, or `it.prop`
+**C#:** Use `FsCheck` with `Prop.ForAll` or `[Property]` attribute
+
+Property tests complement example tests -- write both in the RED phase.
+
+## Expected Test
+
+```typescript
+describe('[ComponentName]', () => {
+  it('should [expected behavior] when [condition]', async () => {
+    // Arrange
+    [Setup code]
+
+    // Act
+    [Execution code]
+
+    // Assert
+    expect(result).[matcher](expected);
+  });
+});
+```
+
+## Success Criteria
+
+- [ ] Test written BEFORE implementation
+- [ ] Test fails for the right reason
+- [ ] Implementation passes test
+- [ ] No extra code beyond requirements
+- [ ] All tests in worktree pass
+
+## Coordination (Native APIs)
+<!-- Agent Teams mode only. Remove this section for subagent mode. -->
+- Use `TaskList` to see available tasks and their statuses
+- Use `TaskUpdate` to mark tasks `in_progress` when you start and `completed` when done
+- Use `SendMessage` to communicate findings to teammates or the lead
+
+## Workflow Intelligence (Exarchos MCP)
+<!-- Agent Teams mode only. Remove this section for subagent mode. -->
+- Use `exarchos_workflow get` to query current workflow state
+- Use `exarchos_view tasks` to see task details across the team
+- Use `exarchos_event append` to report TDD phase transitions:
+    stream: "{featureId}"
+    event: { type: "task.progress", taskId: "{taskId}", tddPhase: "red|green|refactor" }
+
+## Team Context
+<!-- Agent Teams mode only. Populated at spawn time by orchestrator. -->
+{teamComposition}
+
+> This data is injected at spawn time. The SubagentStart hook provides only live coordination updates (task status changes, newly unblocked tasks).
+
+## Historical Context
+<!-- Agent Teams mode only. Populated at spawn time by orchestrator. -->
+{historicalIntelligence}
+
+> This data is injected at spawn time. The SubagentStart hook provides only live coordination updates.
+
+## Quality Signals
+<!-- Populated at dispatch time by orchestrator when quality hints are available. -->
+<!-- Query: exarchos_view with action: 'quality_hints' and skill: '<skill-name>' -->
+<!-- If hints array is non-empty, include this section. If empty, omit entirely. -->
+
+Based on historical quality data for this skill:
+
+{{#each hints}}
+- **{{category}}** ({{severity}}): {{hint}}
+{{/each}}
+
+Use these signals to guide your implementation. Address warnings proactively.
+
+## Code Exploration Tools
+
+For navigating and understanding code:
+- `Grep` — Search for patterns across the codebase
+- `Glob` — Find files by name pattern
+- `Read` — Read file contents (prefer targeted reads over full-file reads)
+
+When Serena MCP is available, prefer semantic tools for precision:
+- `mcp__plugin_serena_serena__find_symbol` — Locate classes, functions, methods by name
+- `mcp__plugin_serena_serena__get_symbols_overview` — Understand file structure without reading entire files
+- `mcp__plugin_serena_serena__search_for_pattern` — Regex search across the codebase
+- `mcp__plugin_serena_serena__find_referencing_symbols` — Find all callers/users of a symbol
+
+## Schema Sync (If Modifying API Files)
+
+If this task modifies any of these file patterns, run schema sync after implementation:
+- `*Endpoints.cs` - API endpoint definitions
+- `Models/*.cs`, `Requests/*.cs`, `Responses/*.cs`, `Dtos/*.cs` - DTOs
+
+```bash
+# From worktree root
+npm run sync:schemas
+npm run typecheck
+```
+
+This regenerates TypeScript types from the OpenAPI spec. Include generated files in your commit.
+
+## Commit Strategy
+<!-- REQUIRED in both Agent Teams and Subagent modes. Never omit this section. -->
+
+After completing each logical task within your assignment:
+
+1. Stage the relevant files: `git add <files>`
+2. Commit with a descriptive message: `git commit -m "feat: <task summary>"`
+3. Continue to the next task
+
+After all tasks are complete:
+4. Push your branch: `git push -u origin <branch-name>`
+
+PR creation is handled during the synthesis phase — do not create PRs from implementation tasks.
+
+### Grouping Guidance
+
+Commits should match logical review units, not individual TDD test cycles. Group related changes that form a coherent feature into one commit. For example, if you implement types + config + tests for a module, that's one commit, not three.
+
+## Provenance Reporting
+
+When completing a task, include structured provenance data in your completion report. This data flows into the `task.completed` event for traceability through the provenance chain.
+
+### Required Fields
+
+1. **implements** — Design requirement IDs you implemented (e.g., `["DR-1", "DR-3"]`)
+2. **tests** — Tests written, each with name and file path
+3. **files** — Files created or modified
+4. **acceptanceTestRef** — (optional) Task ID of the parent acceptance test, if this task has an `acceptanceTestRef` field
+
+### Structured Format
+
+Report provenance as a JSON object in your task completion call:
+
+```json
+{
+  "implements": ["DR-1", "DR-3"],
+  "acceptanceTestRef": "task-000",
+  "tests": [
+    { "name": "validateEmail_InvalidFormat_ReturnsError", "file": "src/validators/email.test.ts" },
+    { "name": "validateEmail_ValidFormat_ReturnsSuccess", "file": "src/validators/email.test.ts" }
+  ],
+  "files": ["src/validators/email.ts", "src/validators/email.test.ts"]
+}
+```
+
+### Passing Provenance in Task Completion
+
+When using Exarchos MCP to mark a task complete, pass provenance fields in the `result` parameter:
+
+```typescript
+exarchos_orchestrate({
+  action: "task_complete",
+  taskId: "task-001",
+  streamId: "<featureId>",
+  result: {
+    summary: "Implemented email validation with TDD",
+    implements: ["DR-1"],
+    acceptanceTestRef: "task-000",
+    tests: [{ name: "validateEmail_InvalidFormat_ReturnsError", file: "src/validators/email.test.ts" }],
+    files: ["src/validators/email.ts", "src/validators/email.test.ts"]
+  }
+})
+```
+
+These fields are extracted by `handleTaskComplete` and included in the `task.completed` event, enabling the ProvenanceView to trace requirements through to implementation.
+
+## Completion
+
+When done, report:
+1. Test file path and test name
+2. Implementation file path
+3. Test results (pass/fail)
+4. Provenance: implements (requirement IDs), acceptanceTestRef (if present), tests (name + file), files (paths)
+5. Any issues encountered
+```
+
+## Usage Example
+
+```typescript
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  description: "Implement user validation",
+  prompt: `
+# Task: Implement User Email Validation
+
+## Working Directory
+/home/user/project/.worktrees/task-003
+
+## CRITICAL: Worktree Verification (MANDATORY)
+
+Before making ANY file changes, you MUST verify you are in a worktree:
+
+1. Run: \`pwd\`
+2. Verify the path contains \`.worktrees/\`
+3. If NOT in a worktree directory:
+   - STOP immediately
+   - Report: "ERROR: Working directory is not a worktree. Aborting task."
+   - DO NOT proceed with any file modifications
+
+**Example verification:**
+\`\`\`bash
+pwd | grep -q "\\.worktrees" || { echo "ERROR: Not in worktree!"; exit 1; }
+\`\`\`
+
+This check prevents accidental modifications to the main project root, which would cause merge conflicts with other parallel tasks.
+
+## Task Description
+Implement email validation for user registration. The validator should:
+- Check email format using regex
+- Verify domain has MX record (mock in tests)
+- Return validation result with error messages
+
+## Files to Modify
+
+### Create/Modify:
+- \`src/validators/email.ts\` - Email validation function
+
+### Test Files:
+- \`src/validators/email.test.ts\` - Validation tests
+
+## TDD Requirements (MANDATORY)
+
+You MUST follow strict Test-Driven Development:
+
+### Phase 1: RED - Write Failing Test
+
+1. Create test file at src/validators/email.test.ts
+2. Write test: \`validateEmail_InvalidFormat_ReturnsError\`
+3. Run tests: \`npm run test:run\`
+4. VERIFY test fails for the expected reason
+
+### Phase 2: GREEN - Minimum Implementation
+
+1. Write minimum code in src/validators/email.ts
+2. Run tests: \`npm run test:run\`
+3. VERIFY test passes
+
+### Phase 3: REFACTOR - Clean Up
+
+1. Extract regex to constant
+2. Run tests after change
+3. VERIFY tests stay green
+
+## Expected Test
+
+\`\`\`typescript
+describe('validateEmail', () => {
+  it('should return error when email format is invalid', async () => {
+    // Arrange
+    const invalidEmail = 'not-an-email';
+
+    // Act
+    const result = validateEmail(invalidEmail);
+
+    // Assert
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('format');
+  });
+});
+\`\`\`
+
+## Success Criteria
+
+- [ ] Test written BEFORE implementation
+- [ ] Test fails for the right reason
+- [ ] Implementation passes test
+- [ ] No extra code beyond requirements
+- [ ] All tests in worktree pass
+`
+})
+```
+
+## Key Principles
+
+1. **Full Context** - Include everything the implementer needs
+2. **No File References** - Don't say "see plan.md" - paste content
+3. **Explicit Paths** - Absolute paths to working directory and files
+4. **TDD Mandatory** - Always include TDD requirements
+5. **Git-First** - Standard git commit + push. PR creation handled by synthesis phase.
+6. **Clear Success Criteria** - Checkboxes for completion
+
+## Agent Teams vs Subagent Mode
+
+The table below shows which sections to include per dispatch mode. Unmarked sections (TDD Requirements, Files, Success Criteria, Completion) are **always included** in both modes.
+
+| Section | Agent Teams Mode | Subagent Mode |
+|---------|-----------------|---------------|
+| Coordination (Native APIs) | Include in spawn prompt | Omit (not applicable) |
+| Workflow Intelligence (Exarchos MCP) | Include in spawn prompt | Omit (hook injects) |
+| Team Context | Include -- populated at spawn time | Omit (hook injects) |
+| Historical Context | Include -- populated at spawn time | Omit (hook injects) |
+| Quality Signals | Conditional -- include if hints non-empty | Conditional -- include if hints non-empty |
+| Code Exploration Tools | Include | Include |
+| Schema Sync | Include if task modifies API files | Include if task modifies API files |
+| **Commit Strategy** | **Include -- REQUIRED** | **Include -- REQUIRED** |
+
+## MCP Auto-Loading
+
+Teammates automatically load project MCP servers (including Exarchos). The Coordination and Workflow Intelligence sections guide WHICH tools to use, not HOW to access them. Do not include MCP connection instructions or tool registration details in the spawn prompt.

package/skills/generic/delegation/references/parallel-strategy.md

@@ -0,0 +1,124 @@
+# Parallel Execution Strategy
+
+## Identifying Parallel Groups
+
+From implementation plan:
+```markdown
+## Parallel Groups
+
+Group A (can run simultaneously):
+- Task 001: Types
+- Task 002: Interfaces
+
+Group B (depends on Group A):
+- Task 003: Implementation
+- Task 004: API handlers
+```
+
+## Dispatching Parallel Tasks
+
+**Critical:** Use single message with multiple Task calls:
+
+```typescript
+// CORRECT: Single message, parallel execution
+Task({ model: "opus", description: "Task 001", prompt: "..." })
+Task({ model: "opus", description: "Task 002", prompt: "..." })
+
+// WRONG: Separate messages = sequential
+```
+
+## Agent Teams Dispatch
+
+When using `--mode agent-team`, parallel execution uses named teammates instead of Task tool calls:
+
+### Creating the Team
+
+Orchestrator activates delegate mode and describes the parallel work:
+
+```text
+"Create a team with 3 teammates:
+- teammate-1: Work in /path/.worktrees/group-a on tasks 1-2 (settings)
+- teammate-2: Work in /path/.worktrees/group-b on tasks 3-5 (gate bridge)
+- teammate-3: Work in /path/.worktrees/group-c on tasks 6-8 (content)"
+```
+
+Each teammate receives the full implementer prompt content as context.
+
+### Self-Coordination
+
+Teammates use Claude Code's native shared task list for claim/complete tracking. When a teammate becomes idle after completing its tasks, the `TeammateIdle` quality gate hook fires automatically, running quality checks and updating Exarchos workflow state (see SKILL.md State Bridge section).
+
+### One Team Per Session
+
+Agent Teams supports one team per session. If you need more parallel groups than teammates, assign multiple tasks per teammate (sequential within the group).
+
+## Dispatch Mode Comparison
+
+| Aspect | Task Tool (Subagent) | Agent Teams (Teammate) |
+|--------|---------------------|----------------------|
+| Parallel dispatch | Multiple `Task()` in one message | Named teammates in agent team |
+| Waiting | `TaskOutput({ block: true })` | `TeammateIdle` hook (fires when teammate idle) |
+| Visibility | None (background) | tmux split panes |
+| Model control | `model: "opus"` per task | Session model for all |
+| Max parallelism | Unlimited | One team, N teammates |
+| Resume on crash | Task results preserved | Teammates lost (worktrees survive) |
+
+## Waiting for Parallel Completion
+
+```typescript
+// Wait for all background tasks
+TaskOutput({ task_id: "task-001-id" })
+TaskOutput({ task_id: "task-002-id" })
+```
+
+## Model Selection Guide
+
+| Task Type | Model | Reason |
+|-----------|-------|--------|
+| Code implementation | `opus` | Best quality for coding |
+| Code review | `opus` | Thorough analysis |
+| File search/exploration | (default) | Speed over quality |
+| Simple queries | `haiku` | Fast, low cost |
+
+**Note:** When using Agent Teams, all teammates inherit the session's model. Use Task tool dispatch if you need per-task model selection (e.g., `haiku` for simple queries, `opus` for implementation).
+
+## Agent Teams Dispatch Pattern
+
+When using `--mode agent-team`, the orchestrator creates named teammates and delegates via natural language:
+
+### Dispatch Example
+
+```text
+"Create a team with 4 teammates:
+- wt1-schemas-views: Work in .worktrees/group-ab-schemas-views on Tasks 1-5 (event schemas + CQRS views)
+- wt2-subagent: Work in .worktrees/group-c-subagent-context on Tasks 6-7 (SubagentStart enrichment)
+- wt3-gates: Work in .worktrees/group-de-gates-lifecycle on Tasks 8-11 (TeammateIdle + lifecycle hooks)
+- wt4-content: Work in .worktrees/group-f-skill-content on Tasks 12-13 (documentation updates)"
+```
+
+Each teammate receives the full implementer prompt including TDD requirements, file paths, and commit strategy.
+
+### Subagent vs Agent Teams Parallelism
+
+| Aspect | Task Tool (Subagent) | Agent Teams (Teammate) |
+|--------|---------------------|----------------------|
+| Parallelism | Multiple `Task()` calls in one message | Named teammates in one team |
+| Cross-task deps | Orchestrator manages phases | Shared task list + unblocked task detection |
+| Monitoring | `TaskOutput` polling | tmux panes + `TeammateIdle` hook |
+| State updates | Orchestrator updates state | Hook auto-updates via state bridge |
+| Model per task | Yes (`model: "opus"` per Task) | No (session model for all) |
+| Quality gates | Manual via `post_delegation_check` action | Automatic via `TeammateIdle` hook |
+| Recovery | Task results preserved | Worktrees survive, teammates lost |
+
+### Shared Task List Coordination
+
+In Agent Teams mode, teammates coordinate via Claude Code's native shared task list:
+1. Orchestrator creates tasks with dependencies
+2. Teammates claim available (unblocked) tasks
+3. On task completion, `TeammateIdle` hook runs quality gates
+4. Hook scans task graph for newly unblocked work (dependencies all completed)
+5. Teammate picks up next task or goes idle
+
+### One Team Per Session
+
+Agent Teams supports one team per session. For more parallel groups than teammates, assign sequential task chains to each teammate (e.g., "Do Task 1, then Task 2, then Task 3").

package/skills/generic/delegation/references/pbt-patterns.md

@@ -0,0 +1,172 @@
+# Property-Based Testing Patterns
+
+When a task has `testingStrategy.propertyTests: true`, write property tests alongside example tests during the TDD RED phase. Property tests use generators to produce random inputs and invariant assertions to verify that properties hold across the entire input space.
+
+## Roundtrip Pattern
+
+For any encode/decode, serialize/deserialize, or transform/inverse-transform pair, the roundtrip property ensures no data is lost.
+
+**TypeScript (fast-check):**
+
+```typescript
+import { fc } from '@fast-check/vitest';
+
+describe('codec', () => {
+  it.prop([fc.anything()], (input) => {
+    expect(decode(encode(input))).toEqual(input);
+  });
+
+  // Or with fc.assert:
+  it('roundtrip for strings', () => {
+    fc.assert(
+      fc.property(fc.string(), (s) => {
+        expect(decode(encode(s))).toBe(s);
+      })
+    );
+  });
+});
+```
+
+**C# (FsCheck):**
+
+```csharp
+using FsCheck;
+
+[Property]
+public void Roundtrip_EncodeDecode(string input)
+{
+    var encoded = Encode(input);
+    var decoded = Decode(encoded);
+    Assert.Equal(input, decoded);
+}
+
+// Or with Prop.ForAll:
+[Test]
+public void Roundtrip_SerializeDeserialize()
+{
+    Prop.ForAll<MyRecord>(record =>
+    {
+        var json = Serialize(record);
+        var result = Deserialize(json);
+        return result.Equals(record);
+    }).QuickCheck();
+}
+```
+
+## Invariant Pattern
+
+For operations with mathematical or business invariants that must hold for all inputs.
+
+**TypeScript (fast-check):**
+
+```typescript
+describe('scoring', () => {
+  it.prop([fc.integer(), fc.integer()], (a, b) => {
+    const result = calculateScore(a, b);
+    expect(result).toBeGreaterThanOrEqual(0);
+    expect(result).toBeLessThanOrEqual(1);
+  });
+
+  it.prop([fc.array(fc.integer())], (items) => {
+    const result = computeTotal(items);
+    expect(result).toBeGreaterThanOrEqual(0);
+  });
+});
+```
+
+**C# (FsCheck):**
+
+```csharp
+[Property]
+public void Score_AlwaysInRange(int a, int b)
+{
+    var score = CalculateScore(a, b);
+    Assert.InRange(score, 0.0, 1.0);
+}
+
+[Property]
+public void Collection_SizeNeverNegative(List<int> items)
+{
+    var result = ProcessItems(items);
+    Assert.True(result.Count >= 0);
+}
+```
+
+## Idempotence Pattern
+
+For operations where applying the function twice produces the same result as applying it once: `f(f(x)) === f(x)`.
+
+**TypeScript (fast-check):**
+
+```typescript
+describe('normalization', () => {
+  it.prop([fc.array(fc.integer())], (arr) => {
+    expect(sort(sort(arr))).toEqual(sort(arr));
+  });
+
+  it.prop([fc.string()], (input) => {
+    expect(normalize(normalize(input))).toBe(normalize(input));
+  });
+});
+```
+
+**C# (FsCheck):**
+
+```csharp
+[Property]
+public void Sort_Idempotent(List<int> items)
+{
+    var once = Sort(items);
+    var twice = Sort(once);
+    Assert.Equal(once, twice);
+}
+
+[Property]
+public void Normalize_Idempotent(string input)
+{
+    var once = Normalize(input);
+    var twice = Normalize(once);
+    Assert.Equal(once, twice);
+}
+```
+
+## Commutativity Pattern
+
+For operations where order should not affect the result.
+
+**TypeScript (fast-check):**
+
+```typescript
+describe('event materialization', () => {
+  it.prop(
+    [fc.array(eventArb()), fc.array(eventArb())],
+    (eventsA, eventsB) => {
+      const resultAB = materialize([...eventsA, ...eventsB]);
+      const resultBA = materialize([...eventsB, ...eventsA]);
+      expect(resultAB).toEqual(resultBA);
+    }
+  );
+});
+```
+
+**C# (FsCheck):**
+
+```csharp
+[Property]
+public void Merge_Commutative(List<int> a, List<int> b)
+{
+    var resultAB = Merge(a, b);
+    var resultBA = Merge(b, a);
+    Assert.Equal(resultAB, resultBA);
+}
+```
+
+## Integration with TDD RED Phase
+
+Property tests are written as part of the TDD RED phase, alongside example tests:
+
+1. **RED:** Write example test (specific case) AND property test (general invariant)
+2. **GREEN:** Implement minimum code to pass both
+3. **REFACTOR:** Extract generators, improve property descriptions
+
+Property tests complement example tests -- they do not replace them. Example tests document specific behaviors; property tests verify invariants across the input domain.