@lvlup-sw/exarchos 2.0.1

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

@@ -0,0 +1,322 @@
+# Implementer Prompt Template
+
+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**
+
+## 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
+
+After completing each logical task within your assignment:
+
+1. Stage the relevant files: `git add <files>`
+2. Create a stacked branch: `gt create <task-branch-name> -m "feat: <task summary>"`
+3. Continue to the next task (you are now on a new branch stacked on the previous)
+
+After all tasks are complete:
+4. Submit the full stack: `gt submit --no-interactive --publish --stack`
+
+**IMPORTANT:** When using Graphite, never use `git commit` or `git push`. Always use `gt create` and `gt submit`.
+
+### Grouping Guidance
+
+Stack branches should match logical review units, not individual TDD test cycles. Group related changes that form a coherent feature into one stack layer. For example, if you implement types + config + tests for a module, that's one `gt create`, not three.
+
+## Completion
+
+When done, report:
+1. Test file path and test name
+2. Implementation file path
+3. Test results (pass/fail)
+4. 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. **Graphite-First** - Include commit strategy section; always use `gt create` and `gt submit`
+6. **Clear Success Criteria** - Checkboxes for completion
+
+## Agent Teams vs Subagent Mode
+
+The template sections marked "Agent Teams mode only" (Coordination, Workflow Intelligence, Team Context, Historical Context) should be **included only when dispatching via Agent Teams mode** (`Task` with `team_name`). When dispatching via subagent mode (`Task` with `run_in_background`), omit these sections -- the SubagentStart hook handles context injection for subagents.
+
+| 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) |
+
+## 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/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.sh` | 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/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.