@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/codex/implementation-planning/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: implementation-planning
+description: "Transform design documents into TDD-based implementation plans with parallelizable tasks. Triggers: 'plan implementation', 'create tasks from design', or /plan. Enforces the Iron Law: no production code without a failing test first. Requires an existing design document — use /ideate first if none exists. Do NOT use for brainstorming, debugging, or code review."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: plan
+---
+
+# Implementation Planning Skill
+
+## Overview
+
+Transform design documents into TDD-based implementation plans with granular, parallelizable tasks. Ensures complete spec coverage through explicit traceability.
+
+For a complete worked example, see `references/worked-example.md`.
+
+## Triggers
+
+Activate this skill when:
+- User runs `plan` command
+- User wants to break down a design into tasks
+- A design document exists and needs implementation steps
+- User says "plan the implementation" or similar
+- Auto-chained from `ideate` after design completion
+- Auto-chained from plan-review with `--revise` flag (gaps found)
+
+## Revision Mode (--revise flag)
+
+When invoked with `--revise`, plan-review found gaps. Read `.planReview.gaps` from state, re-read the design, add tasks to address each gap, update the plan file, then clear gaps via `mcp__exarchos__exarchos_workflow` `action: "set"`.
+
+### Revision Loop Guard
+
+Max revisions: 3 per plan.
+
+After 3 failed revisions:
+1. Set `planReview.revisionsExhausted = true`
+2. Output: "Plan revision failed after 3 attempts. Design may be incomplete."
+3. Escalate: Suggest `ideate --redesign` to revisit design
+
+> **MANDATORY:** Before accepting any rationalization for skipping tests, planning, or TDD steps, consult `references/rationalization-refutation.md`. Every common excuse is catalogued with a counter-argument and the correct action.
+
+## The Iron Law
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+Every implementation task MUST:
+1. Start with writing a failing test
+2. Specify the expected failure reason
+3. Only then implement minimum code to pass
+
+**Verify TDD compliance** in git history after implementation:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_tdd_compliance",
+  featureId: "<featureId>",
+  taskId: "<taskId>",
+  branch: "feature/<name>"
+})
+```
+
+- **`passed: true`** — All commits have test files before or alongside implementation
+- **`passed: false`** — Violations found; commits have implementation without corresponding tests
+
+## Planning Process
+
+### Step 1: Analyze Design Document
+
+Read the design document thoroughly. For each major section, extract:
+- **Problem Statement** — Context (no tasks, but informs scope)
+- **Chosen Approach** — Architectural decisions to implement
+- **Technical Design** — Core implementation requirements
+- **Integration Points** — Integration and glue code tasks
+- **Testing Strategy** — Test coverage requirements
+- **Open Questions** — Decisions to resolve or explicitly defer
+
+### Step 1.5: Spec Tracing (Required)
+
+Create a traceability matrix mapping design sections to planned tasks.
+Consult `references/spec-tracing-guide.md` for the methodology and template.
+
+**Pre-populate the matrix** using the traceability generator script:
+
+```typescript
+exarchos_orchestrate({
+  action: "generate_traceability",
+  designFile: "docs/designs/<feature>.md",
+  planFile: "docs/plans/<date>-<feature>.md",
+  output: "docs/plans/<date>-<feature>-traceability.md"
+})
+```
+
+- **`passed: true`** — Matrix generated; review and fill in "Key Requirements" column
+- **`passed: false`** — Parse error; design document may lack expected `##`/`###` headers
+
+### Step 2: Decompose into Tasks
+
+Each task follows the TDD format in `references/task-template.md`.
+
+**Granularity Guidelines:**
+- Each task: 2-5 minutes of focused work
+- One test = one behavior
+- Prefer many small tasks over few large ones
+
+Assign a `testingStrategy` to each task using `references/testing-strategy-guide.md` to control which verification techniques agents apply. Auto-determine `propertyTests` and `benchmarks` flags by matching each task's description and file paths against the category tables — do not leave these for the implementer to decide.
+
+**Task Ordering:**
+1. Foundation first (types, interfaces, data structures)
+2. Core behaviors second
+3. Edge cases and error handling third
+4. Integration and glue code last
+
+### Step 3: Identify Parallelization
+
+Analyze dependencies to find sequential chains and parallel-safe groups that can run simultaneously in worktrees.
+
+### Step 4: Generate Plan Document
+
+Save to: `docs/plans/YYYY-MM-DD-<feature>.md`
+Use the template from `references/plan-document-template.md`.
+
+### Step 5: Plan Verification
+
+Run deterministic verification scripts instead of manual checklist review.
+
+**5a. Design-to-plan coverage** — verify every Technical Design subsection maps to a task:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_plan_coverage",
+  featureId: "<id>",
+  designPath: "docs/designs/<feature>.md",
+  planPath: "docs/plans/<date>-<feature>.md"
+})
+```
+
+- **passed: true** — All design sections covered; proceed to 5a-ii
+- **passed: false** — Gaps found; add tasks for uncovered sections or defer with rationale
+- **error** — Usage error or empty design; check arguments
+
+**5a-ii. Provenance chain verification** — verify every DR-N requirement maps to a task via `Implements:` field:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_provenance_chain",
+  featureId: "<id>",
+  designPath: "docs/designs/<feature>.md",
+  planPath: "docs/plans/<date>-<feature>.md"
+})
+```
+
+- **passed: true** — All DR-N requirements traced; proceed to 5b
+- **passed: false** — **Block:** gaps or orphan references found. Add `**Implements:** DR-N` to tasks for each uncovered requirement before proceeding. Every DR-N requirement MUST trace to at least one task.
+- **error** — No DR-N identifiers in design (exit 2); if design doesn't use DR-N identifiers, this check is skipped (exempt)
+
+**5a-iii. D5: Task decomposition quality (advisory)** — verify each task has clear description, file targets, and test expectations; dependency graph is a valid DAG; parallelizable tasks don't modify the same files:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_task_decomposition",
+  featureId: "<id>",
+  planPath: "docs/plans/<date>-<feature>.md"
+})
+```
+
+- **passed: true** — All tasks well-decomposed; proceed to 5b
+- **passed: false** — Findings recorded as D5 gate events for the ConvergenceView. Present findings to the user for awareness but do not block plan approval.
+- **error** — Input error (missing file, no task headers); check arguments
+
+**Advisory:** This gate verifies task structure quality but does not block plan approval. Findings are recorded for convergence tracking.
+
+**5b. Spec coverage check** — verify planned test files exist and pass:
+
+```typescript
+exarchos_orchestrate({
+  action: "spec_coverage_check",
+  planFile: "docs/plans/<date>-<feature>.md",
+  repoRoot: ".",
+  threshold: 80
+})
+```
+
+- **`passed: true`** — All planned tests found and passing; plan verification complete
+- **`passed: false`** — Missing test files or test failures; create missing tests or fix failures
+
+For reference, consult `references/spec-tracing-guide.md` for the underlying methodology.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Write implementation first | Write failing test first |
+| Create large tasks | Break into 2-5 min chunks |
+| Skip dependency analysis | Identify parallel opportunities |
+| Vague test descriptions | Specific: Method_Scenario_Outcome |
+| Assume tests pass | Verify each test fails first |
+| Add "nice to have" code | Only what the test requires |
+
+## Rationalization Debunking
+
+| Excuse | Reality |
+|--------|---------|
+| "This is too simple for tests" | Simple code breaks too. Test it. |
+| "I'll add tests after" | You won't. Or they'll be weak. |
+| "Tests slow me down" | Debugging without tests is slower. |
+| "The design is obvious" | Obvious to you now. Not in 3 months. |
+
+## State Management
+
+On plan save, transition phase based on `workflowType`: feature → `plan-review`, refactor → `overhaul-plan-review`.
+```
+action: "set", featureId: "<id>", phase: "<plan-review-phase>", updates: {
+  "artifacts": { "plan": "<plan-file-path>" },
+  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
+}
+```
+
+### Phase Transitions and Guards
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+**Quick reference:** The `plan` → `plan-review` transition requires guard `plan-artifact-exists` — set `artifacts.plan` in the same `set` call as `phase`.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+(or `"debug"`, `"refactor"`) for phase transitions, guards, and playbook guidance.
+Use `exarchos_orchestrate({ action: "describe", actions: ["check_plan_coverage", "check_provenance_chain"] })`
+for orchestrate action schemas.
+
+## Completion Criteria
+
+- [ ] Design document read and understood
+- [ ] Spec traceability table created (`exarchos_orchestrate({ action: "generate_traceability" })`)
+- [ ] Scope declared (full or partial with rationale)
+- [ ] Tasks decomposed to 2-5 min granularity
+- [ ] Each task starts with failing test
+- [ ] Dependencies mapped
+- [ ] Parallel groups identified
+- [ ] Plan verification passed — `exarchos_orchestrate({ action: "check_plan_coverage" })` returns passed: true
+- [ ] Provenance chain checked — `exarchos_orchestrate({ action: "check_provenance_chain" })` passed (blocking; gaps must be resolved before proceeding)
+- [ ] Task decomposition checked — `exarchos_orchestrate({ action: "check_task_decomposition" })` run (advisory; findings presented but non-blocking)
+- [ ] Spec coverage check passed — `exarchos_orchestrate({ action: "spec_coverage_check" })` passed: true
+- [ ] Coverage thresholds met — `exarchos_orchestrate({ action: "check_coverage_thresholds" })` passed: true:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_coverage_thresholds",
+  coverageFile: "coverage/coverage-summary.json",
+  lineThreshold: 80,
+  branchThreshold: 70,
+  functionThreshold: 100
+})
+```
+
+- [ ] Plan saved to `docs/plans/`
+- [ ] State file updated with plan path and tasks
+
+## Transition
+
+After planning completes, **auto-continue to plan-review** (delta analysis). Set `.phase` to the appropriate review phase (feature: `plan-review`, refactor: `overhaul-plan-review`). Plan-review compares design sections against planned tasks:
+- Gaps found: set `.planReview.gaps`, auto-loop back to `plan --revise`
+- No gaps: present to user for approval (human checkpoint)
+- On approval: set `.planReview.approved = true`, invoke `delegate`
+
+**REQUIRED:** Run `exarchos_orchestrate({ action: "check_plan_coverage" })`. If passed: false → auto-invoke `plan --revise`. If passed: true → continue to the plan-review phase (feature: `plan-review`, refactor: `overhaul-plan-review`) and only invoke `delegate` after plan-review approval.
+
+## Exarchos Integration
+
+Phase transitions auto-emit `workflow.transition` events via `exarchos_workflow` `set`. No manual `exarchos_event` append needed.
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| `check_plan_coverage` returns passed: false | Design sections not mapped to tasks | Add tasks for uncovered sections or add explicit deferral rationale |
+| `spec_coverage_check` passed: false | Planned test files missing or failing | Create missing test stubs, verify file paths in plan match actual paths |
+| `generate_traceability` passed: false | Design doc missing expected `##`/`###` headers | Verify design uses standard Markdown headings |
+| Revision loop (3+ attempts) | Persistent gaps between design and plan | Set `planReview.revisionsExhausted = true`, suggest `ideate --redesign` |
+
+## Performance Notes
+
+- Complete each step fully before advancing — quality over speed
+- Do not skip validation checks even when the change appears trivial
+- Trace every design section to at least one task. Do not leave uncovered sections without explicit rationale.

package/skills/codex/implementation-planning/references/plan-document-template.md

@@ -0,0 +1,42 @@
+# Plan Document Template
+
+Save to: `docs/plans/YYYY-MM-DD-<feature>.md`
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Source Design
+Link: `docs/designs/YYYY-MM-DD-<feature>.md`
+
+## Scope
+**Target:** [Full design | Partial: <specific components>]
+**Excluded:** [None | List excluded sections with rationale]
+
+## Summary
+- Total tasks: [N]
+- Parallel groups: [N]
+- Estimated test count: [N]
+- Design coverage: [X of Y sections covered]
+
+## Spec Traceability
+
+[Traceability matrix from Step 1.5]
+
+## Task Breakdown
+
+[Tasks in execution order]
+
+## Parallelization Strategy
+
+[Which tasks can run in parallel worktrees]
+
+## Deferred Items
+
+[Open questions or design sections not addressed, with rationale]
+
+## Completion Checklist
+- [ ] All tests written before implementation
+- [ ] All tests pass
+- [ ] Code coverage meets standards
+- [ ] Ready for review
+```

package/skills/codex/implementation-planning/references/rationalization-refutation.md

@@ -0,0 +1,13 @@
+# Rationalization Refutation — Implementation Planning
+
+Common rationalizations that undermine planning rigor, with counter-arguments and correct actions.
+
+| Rationalization | Counter-argument | What to do instead |
+|-----------------|------------------|--------------------|
+| "The design is clear enough to skip planning" | Designs describe *what* to build, not the sequence, dependencies, or test strategy. Skipping planning leads to ad-hoc implementation, missed edge cases, and rework. | Run `/exarchos:plan` to decompose the design into granular TDD tasks with explicit dependencies and parallel groups. |
+| "Tests are implied by the implementation" | Implied tests are never written. The Iron Law exists because every "implied" test is a missing safety net that lets regressions ship. | Write each test explicitly in the plan: name, file path, method under test, expected failure reason. |
+| "Small change doesn't need tests" | Small changes break things too — especially boundary conditions and integration points. The change's size does not determine its risk. | Plan a test for every behavioral change, regardless of size. Use the task template's TDD section. |
+| "I'll add tests after the implementation" | Post-hoc tests validate what you built, not what you should have built. They miss edge cases the implementation accidentally handles and confirm bugs as features. | Plan tests first (RED step). Each task starts with a failing test that defines the expected behavior before any production code. |
+| "This is just a refactor, no tests needed" | Refactors change structure, and structural changes can alter behavior in subtle ways. Without tests, you cannot prove the refactor preserved semantics. | Ensure existing tests cover the code being refactored. If coverage gaps exist, plan tests to fill them before the refactor task. |
+| "We can plan as we go" | Incremental planning without upfront decomposition hides dependency conflicts, prevents parallelization, and makes progress invisible. | Complete the full planning process: analyze design, decompose tasks, identify dependencies, then delegate. |
+| "The task is too simple to decompose further" | Tasks that feel "simple" often contain hidden subtasks (error handling, validation, edge cases). Undecomposed tasks balloon during implementation. | Apply the 2-5 minute granularity rule. If a task takes longer than 5 minutes, it needs further decomposition. |

package/skills/codex/implementation-planning/references/spec-tracing-guide.md

@@ -0,0 +1,51 @@
+# Spec Tracing Guide
+
+## Traceability Matrix
+
+Create a traceability table mapping design sections to planned tasks. This ensures complete coverage.
+
+```markdown
+## Spec Traceability
+
+### Scope Declaration
+
+**Target:** [Full design | Partial: <specific components>]
+**Excluded:** [List any intentionally excluded sections with rationale]
+
+### Traceability Matrix
+
+| Design Section | Key Requirements | Task ID(s) | Status |
+|----------------|-----------------|------------|--------|
+| Technical Design > Component A | - Requirement 1<br>- Requirement 2 | 001, 002 | Covered |
+| Technical Design > Component B | - Requirement 3 | 003 | Covered |
+| Integration Points > X | - Connection to Y | 004 | Covered |
+| Testing Strategy | - Unit tests<br>- Integration tests | 005, 006 | Covered |
+| Open Questions > Q1 | Decision needed | — | Deferred: [reason] |
+```
+
+### Rules
+
+- Every sub-section of Technical Design MUST map to at least one task
+- Every file in "Files Changed" table MUST be touched by at least one task
+- Open Questions MUST be resolved OR explicitly deferred with rationale
+- For partial plans, declare scope upfront and only trace in-scope sections
+
+## Plan Verification
+
+Before saving, verify completeness against the design document.
+
+### Coverage Checklist
+
+- [ ] Every sub-section of "Technical Design" has at least one task
+- [ ] All files in "Files Changed" table are touched by tasks
+- [ ] Testing strategy items have corresponding test tasks
+- [ ] Open questions are resolved OR explicitly deferred with rationale
+- [ ] For partial plans: scope declaration is clear and justified
+
+### Delta Analysis
+
+Compare design sections against task list. For each gap:
+1. Create a task to address it, OR
+2. Add to "Deferred Items" with explicit rationale
+
+If significant gaps remain that cannot be justified, **do not proceed** — return to design phase for clarification.

package/skills/codex/implementation-planning/references/task-template.md

@@ -0,0 +1,63 @@
+# TDD Task Template
+
+## Task Format
+
+Each task follows this structure:
+
+```markdown
+### Task [N]: [Brief Description]
+
+**Phase:** [RED | GREEN | REFACTOR]
+**Test Layer:** [acceptance | integration | unit | property]
+**Acceptance Test Ref:** [Task ID of parent acceptance test, or omit]
+**Implements:** [DR-N identifiers]
+
+**TDD Steps:**
+1. [RED] Write test: `TestName_Scenario_ExpectedOutcome`
+   - File: `path/to/test.ts`
+   - Expected failure: [Specific failure reason]
+   - Run: `npm run test:run` - MUST FAIL
+
+2. [GREEN] Implement minimum code
+   - File: `path/to/implementation.ts`
+   - Changes: [Brief description]
+   - Run: `npm run test:run` - MUST PASS
+
+3. [REFACTOR] Clean up (optional)
+   - Apply: [SOLID principle or improvement]
+   - Run: `npm run test:run` - MUST STAY GREEN
+
+**Verification:**
+- [ ] Witnessed test fail for the right reason
+- [ ] Test passes after implementation
+- [ ] No extra code beyond test requirements
+
+**Dependencies:** [Task IDs this depends on, or "None"]
+**Parallelizable:** [Yes/No]
+```
+
+## Test Layer Selection
+
+Each task must declare its test layer. This determines the scope and style of testing:
+
+| Layer | Scope | When to use |
+|---|---|---|
+| `acceptance` | Feature-level behavior from user perspective | First task per feature or DR-N cluster. Uses real collaborators, no mocks. Remains RED until inner tasks complete. |
+| `integration` | Multiple components working together | **Default for most tasks.** Uses real collaborators, mocks only at infrastructure boundaries. |
+| `unit` | Single function/class in isolation | Complex algorithmic logic, pure functions, parsers. |
+| `property` | Invariants across input space | Transformations, state machines, serialization (auto-determined via testingStrategy). |
+
+**Acceptance Test Ref:** Inner tasks that implement toward an acceptance test should declare `**Acceptance Test Ref:** [Task ID]` linking to the parent acceptance test task. This creates the provenance chain: `DR-N → Acceptance Test → Inner Tests → Code`.
+
+## Characterization Testing
+
+When a task modifies existing code behavior, the planner should set `characterizationRequired: true` in the testingStrategy. The implementer captures current behavior as characterization tests before making changes, providing a safety net against unintended regressions.
+
+## Test Naming Convention
+
+Follow: `MethodName_Scenario_ExpectedOutcome`
+
+**Examples:**
+- `CreateUser_ValidInput_ReturnsUserId`
+- `CreateUser_EmptyEmail_ThrowsValidationError`
+- `GetUser_NonExistentId_ReturnsNull`

package/skills/codex/implementation-planning/references/testing-strategy-guide.md

@@ -0,0 +1,109 @@
+# Testing Strategy Guide
+
+When creating implementation plans, assign a `testingStrategy` to each task. This field controls which verification techniques agents apply during implementation.
+
+## Schema
+
+```typescript
+testingStrategy: {
+  exampleTests: true;           // Always required (literal true)
+  propertyTests: boolean;       // Property-based tests required?
+  benchmarks: boolean;          // Performance benchmarks required?
+  testLayer: 'acceptance' | 'integration' | 'unit';  // Required (property is a separate axis via propertyTests)
+  characterizationRequired?: boolean;  // Pre-capture behavior before modifying existing code?
+  properties?: string[];        // Guidance: which properties to verify
+  performanceSLAs?: PerformanceSLA[]; // Guidance: performance targets
+}
+```
+
+## Category Requirements
+
+Assign `propertyTests: true` when the task involves any of these categories:
+
+| Category | Example Code | Properties to Test |
+|---|---|---|
+| **Data transformations** | Parse/serialize, encode/decode, format/unformat | Roundtrip: `decode(encode(x)) === x` |
+| **State machines** | Workflow HSM, circuit breaker, connection lifecycle | Transition validity: no invalid state reachable from any valid state |
+| **Collections/ordering** | Sort, filter, deduplicate, paginate, merge | Idempotence: `sort(sort(x)) === sort(x)` |
+| **Concurrency** | Optimistic locking, CAS, event ordering | Linearizability: concurrent operations produce valid state |
+| **Serialization** | Event schemas, API contracts, JSON/YAML/TOML | Schema compliance: output matches declared schema for all inputs |
+| **Mathematical operations** | Scoring, percentages, budgets, rates | Invariants: `score >= 0 && score <= 1.0`, conservation laws |
+
+Assign `propertyTests: false` when the task is:
+- Pure wiring (DI registration, configuration binding)
+- UI layout or styling
+- Simple CRUD without business logic
+- Documentation or content-only changes
+
+## Populating the `properties` Array
+
+When `propertyTests: true`, provide guidance strings in the `properties` array describing which properties to verify:
+
+```json
+{
+  "exampleTests": true,
+  "propertyTests": true,
+  "benchmarks": false,
+  "properties": [
+    "roundtrip: decode(encode(x)) === x for all valid inputs",
+    "idempotence: format(format(x)) === format(x)"
+  ]
+}
+```
+
+## Benchmark Requirements
+
+Assign `benchmarks: true` when the task involves any of these categories:
+
+| Category | Example Code | What to Measure |
+|---|---|---|
+| **Event store operations** | Append, query, snapshot | Throughput (ops/sec), p99 latency |
+| **View materialization** | Projection apply, cold-start rebuild | Events/sec, cold-start time |
+| **Serialization hot paths** | JSON parse/stringify, schema validation | Throughput, memory allocation |
+| **Query-heavy reads** | CQRS projections, aggregations | Query latency under load |
+
+Assign `benchmarks: false` when the task is:
+- Pure wiring, configuration, or DI registration
+- Content-only changes (Markdown, documentation)
+- Test infrastructure (test helpers, fixtures)
+- UI components or styling
+
+When `benchmarks: true`, populate `performanceSLAs` with targets:
+
+```json
+{
+  "exampleTests": true,
+  "propertyTests": false,
+  "benchmarks": true,
+  "performanceSLAs": [
+    { "operation": "event-append", "metric": "p99_ms", "threshold": 10 }
+  ]
+}
+```
+
+## Test Layer Selection (Testing Trophy Distribution)
+
+The planner MUST assign `testLayer` to each task. Follow the Testing Trophy distribution: **integration-heavy, unit-light**.
+
+| Layer | When to assign | Default? |
+|---|---|---|
+| `acceptance` | First task per feature or DR-N cluster with Given/When/Then criteria. Tests feature from user perspective with real collaborators. | No — explicitly assigned |
+| `integration` | Task tests multiple components working together. Uses real collaborators, mocks only at infrastructure boundaries. | **Yes — default layer** |
+| `unit` | Task involves isolated complex logic (parsers, algorithms, math). Pure functions with complex edge cases. | No — only for naturally isolated code |
+
+
+> **Note:** `propertyTests: true` can coexist with any `testLayer` value — it's an independent overlay, not a mutually exclusive layer.
+
+**Sociable test preference:** Default to using real collaborators (sociable tests). Mock only at infrastructure boundaries — external HTTP services, databases, filesystem. If a test requires >3 mocked dependencies, the task may be at the wrong test layer.
+
+## Characterization Testing
+
+Assign `characterizationRequired: true` when the task modifies existing code behavior (refactoring, fixing, enhancing). The implementer captures current behavior before making changes. Not applicable for new code creation.
+
+## Auto-Determination
+
+The planner MUST auto-determine `propertyTests`, `benchmarks`, and `testLayer` for each task based on the category tables above. Do NOT leave these fields for the implementer to decide. Analyze each task's description and file paths to match against the categories. When uncertain, default `testLayer` to `"integration"`, `propertyTests` to `false`, and `benchmarks` to `false`.
+
+## Reference
+
+See [Autonomous Code Verification design](../../../docs/designs/2026-02-15-autonomous-code-verification.md#when-to-require-property-based-tests) for the full rationale and category taxonomy.

package/skills/codex/implementation-planning/references/worked-example.md

@@ -0,0 +1,76 @@
+---
+name: implementation-planning-worked-example
+description: "Complete trace of the implementation planning skill in action, showing happy path and re-planning after gap detection."
+---
+
+# Worked Example: Implementation Planning — Event Stream Compaction
+
+## Context
+
+Feature: event stream compaction for the Exarchos MCP server. Design document exists at `docs/designs/2026-02-20-stream-compaction.md`. The user runs `/exarchos:plan` (or auto-chained from `/exarchos:ideate`).
+
+## Step 1: Analyze Design Document
+
+Agent reads design and extracts key sections:
+
+- **Problem Statement:** Event streams grow unbounded; view queries slow down after 1000+ events.
+- **Chosen Approach:** Snapshot-based compaction. Periodically write a snapshot event summarizing state, then readers start from latest snapshot.
+- **Technical Design:** `SnapshotWriter` class, `StreamReader` with snapshot-aware cursor, snapshot trigger threshold.
+- **Integration Points:** `exarchos_view` tool, `exarchos_event` append tool.
+- **Testing Strategy:** Unit tests for writer/reader, integration test for round-trip.
+
+## Step 1.5: Spec Tracing
+
+Agent runs `exarchos_orchestrate({ action: "generate_traceability" })` to pre-populate the traceability matrix, then fills in key requirements per section.
+
+## Step 2: Decompose into Tasks
+
+| Task | Test Name | Dependencies | Parallel |
+|------|-----------|-------------|----------|
+| 1 | `SnapshotEvent_Serialize_RoundTrips` | None | Yes |
+| 2 | `SnapshotWriter_ThresholdReached_WritesSnapshot` | Task 1 | Yes |
+| 3 | `SnapshotWriter_BelowThreshold_NoSnapshot` | Task 1 | Yes |
+| 4 | `StreamReader_SnapshotExists_StartsFromSnapshot` | Task 1 | No (after 1) |
+| 5 | `StreamReader_NoSnapshot_ReadsFullStream` | Task 4 | No (after 4) |
+| 6 | `ViewTool_WithCompaction_ReturnsCorrectState` | Tasks 2, 4 | No |
+
+**Parallel groups:** Tasks 1-3 run simultaneously. Task 4 waits for 1. Task 5 waits for 4. Task 6 is the integration task, last.
+
+## Step 3: Plan Verification
+
+Agent runs `exarchos_orchestrate({ action: "check_plan_coverage" })`:
+
+```
+exarchos_orchestrate({
+  action: "check_plan_coverage",
+  featureId: "<id>",
+  designPath: "docs/designs/2026-02-20-stream-compaction.md",
+  planPath: "docs/plans/2026-02-20-stream-compaction.md"
+})
+→ passed: false — Uncovered section: "Snapshot trigger threshold configuration"
+```
+
+## Gap Detected: Re-Planning
+
+The design specifies a configurable threshold (default 500 events). No task covers configuration parsing.
+
+**Agent adds Task 7:**
+
+| Task | Test Name | Dependencies | Parallel |
+|------|-----------|-------------|----------|
+| 7 | `CompactionConfig_CustomThreshold_OverridesDefault` | None | Yes |
+
+Agent re-runs verification:
+
+```
+exarchos_orchestrate({ action: "check_plan_coverage", ... })
+→ passed: true — All design sections covered
+```
+
+Agent runs `exarchos_orchestrate({ action: "spec_coverage_check", planFile: "docs/plans/2026-02-20-stream-compaction.md", repoRoot: "." })` -- passed: true (no pre-existing tests expected at planning time).
+
+## Output
+
+Plan saved to `docs/plans/2026-02-20-stream-compaction.md`. State updated: `artifacts.plan` set, `tasks` array populated with 7 tasks, phase transitions to `plan-review`.
+
+**Agent:** "Plan complete. Auto-continuing to plan-review for gap analysis..."