myaidev-method 0.3.2 → 0.3.3

package/skills/myaidev-tester/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: myaidev-tester
+description: "Multi-agent test generation and execution with TDD support, coverage analysis, and iterative improvement. Supports London and Chicago TDD styles."
+argument-hint: "[path-or-spec] [--tdd] [--style=london|chicago] [--type=unit|integration|e2e|api|all] [--coverage] [--gate=strict|standard|minimal]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion]
+context: fork
+---
+
+# MyAIDev Tester Skill v2 — Orchestrator Pattern
+
+You are the **Test Orchestrator**, a coordinator that decomposes test generation and execution into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive work to isolated subagents, iterating until coverage thresholds are met.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  ORCHESTRATOR (this skill)               │
+│  * Parses arguments & detects test framework             │
+│  * Creates execution plan                                │
+│  * Dispatches subagents                                  │
+│  * Manages iteration cycles                              │
+│  * Reports results and coverage                          │
+└──────────────┬──────────────────────────────────────────┘
+               │ spawns
+    ┌──────────┼──────────────┬──────────────────┐
+    v          v              v                  v
+┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐
+│ Strategy │ │  Writer  │ │  Runner  │ │    Coverage     │
+│  Agent   │ │  Agent   │ │  Agent   │ │    Analyst      │
+└──────────┘ └──────────┘ └──────────┘ └────────────────┘
+
+                 --- OR (if --tdd) ---
+
+┌─────────────────────────────────────────────────────────┐
+│                  ORCHESTRATOR (this skill)               │
+│  * TDD mode: delegates to TDD Driver                     │
+└──────────────┬──────────────────────────────────────────┘
+               │ spawns
+               v
+        ┌─────────────┐
+        │  TDD Driver  │
+        │    Agent     │
+        │ RED → GREEN  │
+        │ → REFACTOR   │
+        └─────────────┘
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+
+- Parse `$ARGUMENTS` for path, flags, and parameters
+- Detect the project's test framework by inspecting:
+  - `package.json` for `jest`, `vitest`, `mocha`, `@testing-library/*`, `cypress`, `playwright`
+  - `pytest.ini`, `pyproject.toml`, `setup.cfg` for `pytest`
+  - `Cargo.toml` for Rust test configuration
+  - `go.mod` for Go test conventions
+  - Existing test files for patterns and conventions
+- Determine test runner command (e.g., `npx jest`, `pytest`, `cargo test`, `go test`)
+- Detect coverage tool (e.g., `--coverage` flag, `pytest-cov`, `go tool cover`)
+- Create scratchpad directory: `.sparc-session/` (shared with SPARC workflow, or standalone)
+- Save configuration to `.sparc-session/test-config.json`
+- If `--tdd` flag is set, skip to TDD Mode (see below)
+
+### Phase 1: Strategy (Subagent)
+
+Spawn a **test-strategist subagent** to analyze code and plan the testing approach:
+
+```
+Task(subagent_type: "general-purpose", prompt: "...")
+```
+
+The strategist:
+- Reads source code at the specified path
+- Identifies all testable units (functions, classes, API endpoints, components)
+- Determines appropriate test types per unit (unit, integration, e2e, api, component)
+- Identifies edge cases: null/undefined inputs, boundary values, error states, async failures, concurrent access
+- Prioritizes tests by risk: critical paths first, then edge cases, then nice-to-haves
+- Writes strategy to `.sparc-session/test-strategy.md`
+- Returns a concise strategy summary
+
+### Phase 2: Write (Subagent)
+
+Spawn a **test-writer subagent** with the strategy + source code:
+
+The writer:
+- Reads the test strategy and source code
+- Generates tests following AAA (Arrange-Act-Assert) pattern
+- Uses `describe`/`it` blocks with clear, behavior-describing names
+- Creates proper mocks, stubs, and spies for dependencies
+- Generates test fixtures and factory functions where needed
+- Handles async tests properly (async/await, done callbacks, promise chains)
+- Creates setup/teardown hooks (beforeEach, afterEach, beforeAll, afterAll)
+- Follows the project's existing test conventions (detected from existing tests)
+- Writes test files to the project's test directory (matching existing convention)
+- Returns list of created test files
+
+### Phase 3: Run (Subagent)
+
+Spawn a **test-runner subagent** to execute the suite:
+
+The runner:
+- Detects and runs the test command with coverage flags enabled
+- Parses test output: pass/fail counts, failure messages, execution time
+- Parses coverage output: line/branch/function/statement percentages
+- Handles test failures gracefully (reports them without crashing the pipeline)
+- Writes structured results to `.sparc-session/test-results.md`
+- Returns pass/fail summary and coverage percentages
+
+### Phase 4: Analyze (Subagent)
+
+Spawn a **coverage-analyst subagent** to check for gaps:
+
+The analyst:
+- Reads coverage report and source code
+- Identifies untested lines, branches, and functions
+- Maps gaps to specific code paths that need tests
+- Prioritizes gaps by importance (critical paths > edge cases > utilities)
+- Generates specific test case descriptions for each gap
+- Writes recommendations to `.sparc-session/coverage-gaps.md`
+- Returns gap count and whether threshold is met
+
+### Phase 5: Iterate (Orchestrator)
+
+The orchestrator evaluates:
+- If coverage >= threshold AND 0 failures: **PASS** - proceed to reporting
+- If coverage < threshold: dispatch test-writer again with coverage gaps as input
+- If failures > 0: dispatch test-writer to fix failing tests
+- Maximum **3 iteration cycles** to prevent infinite loops
+- Each cycle: Write → Run → Analyze → evaluate
+- Log each iteration to `.sparc-session/iteration-log.md`
+
+### Phase 6: Report & Cleanup
+
+The orchestrator:
+- Reads all scratchpad files
+- Produces a final test report with:
+  - Total tests: passed/failed/skipped
+  - Coverage percentages: line/branch/function/statement
+  - Quality gate result: PASS/FAIL with gate level applied
+  - List of test files created/modified
+  - Uncovered areas that remain (if any)
+- Reports results to the user
+- Cleans up `.sparc-session/` directory (unless part of SPARC workflow)
+
+## TDD Mode (--tdd flag)
+
+When `--tdd` is specified, the orchestrator skips the standard pipeline and delegates entirely to the **TDD Driver Agent**.
+
+### TDD Workflow
+
+```
+1. INIT        → Parse args, detect framework, determine TDD style
+2. TDD DRIVER  → Spawn TDD driver agent with requirements + style
+                  → RED: Write failing test
+                  → GREEN: Write minimal code to pass
+                  → REFACTOR: Clean up while keeping tests green
+                  → Repeat for each requirement
+3. REPORT      → Collect TDD cycle log, report results
+4. CLEANUP     → Remove session files
+```
+
+### TDD Styles
+
+| Style | Approach | When to Use |
+|-------|----------|-------------|
+| `london` | Outside-in, mock dependencies, behavior-focused | API layers, controllers, services with many collaborators |
+| `chicago` | Inside-out, state-based, build from domain up | Domain logic, pure functions, data transformations |
+
+Default style is `chicago` if not specified.
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `path-or-spec` | File, directory, or spec description to test | `./src` |
+| `--tdd` | Enable TDD red-green-refactor mode | `false` |
+| `--style` | TDD style: `london` or `chicago` | `chicago` |
+| `--type` | Test type: `unit`, `integration`, `e2e`, `api`, `all` | `unit` |
+| `--coverage` | Generate and analyze coverage report | `false` |
+| `--gate` | Quality gate level: `strict`, `standard`, `minimal` | `standard` |
+| `--watch` | Run tests in watch mode after generation | `false` |
+| `--fix` | Auto-fix failing tests on iteration | `true` |
+| `--verbose` | Show detailed progress from each phase | `false` |
+
+## Quality Gates
+
+| Gate | Coverage | Failures | Branches | Functions |
+|------|----------|----------|----------|-----------|
+| `strict` | >= 90% lines | 0 allowed | >= 85% | >= 90% |
+| `standard` | >= 80% lines | 0 allowed | >= 75% | >= 80% |
+| `minimal` | >= 60% lines | <= 3 allowed | >= 50% | >= 60% |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt template in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Strategy | [agents/test-strategist-agent.md](agents/test-strategist-agent.md) | path, test_type, framework, existing_tests |
+| Write | [agents/test-writer-agent.md](agents/test-writer-agent.md) | strategy, source_code, framework, conventions |
+| Run | [agents/test-runner-agent.md](agents/test-runner-agent.md) | test_command, coverage_flags, test_files |
+| Analyze | [agents/coverage-analyst-agent.md](agents/coverage-analyst-agent.md) | coverage_report, source_code, threshold |
+| TDD | [agents/tdd-driver-agent.md](agents/tdd-driver-agent.md) | requirements, style, framework, path |
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to `.sparc-session/` directory:
+
+```
+.sparc-session/
+├── test-config.json       # Parsed arguments, detected framework, settings
+├── test-strategy.md       # Strategy agent output: test plan matrix
+├── test-results.md        # Runner agent output: pass/fail, coverage
+├── coverage-gaps.md       # Analyst agent output: uncovered code paths
+├── iteration-log.md       # Iteration cycle history
+├── tdd-log.md             # TDD cycle log (TDD mode only)
+└── test-report.md         # Final assembled test report
+```
+
+This keeps the orchestrator's context lean -- it reads only what it needs for each phase.
+
+## Execution Flow
+
+```
+Standard Mode:
+1. INIT        → Parse args, detect framework, create session dir
+2. STRATEGY    → Spawn strategist agent
+3. WRITE       → Spawn writer agent with strategy
+4. RUN         → Spawn runner agent to execute tests
+5. ANALYZE     → Spawn coverage analyst
+6. ITERATE     → If coverage < threshold, loop steps 3-5 (max 3 cycles)
+7. REPORT      → Assemble final test report
+8. CLEANUP     → Remove .sparc-session/ (unless in SPARC workflow)
+
+TDD Mode:
+1. INIT        → Parse args, detect framework, create session dir
+2. TDD DRIVER  → Spawn TDD driver with requirements
+3. REPORT      → Assemble TDD cycle report
+4. CLEANUP     → Remove .sparc-session/
+```
+
+## Error Handling
+
+- If strategy agent fails, fall back to basic heuristic (test all exported functions)
+- If test runner fails to execute, check framework installation and report actionable fix
+- If coverage tool is not available, skip coverage analysis and report tests only
+- If iteration limit reached without meeting threshold, report current state and gaps
+- Never block the entire pipeline on a single failure
+- Log all errors to `.sparc-session/iteration-log.md`
+
+## Context Management (Long-Running Agent Patterns)
+
+### Context Regurgitation
+Before dispatching each subagent, briefly restate in your prompt:
+- Current phase number and what has been completed so far
+- Key decisions made (framework detected, test style chosen, conventions found)
+- What this subagent needs to accomplish and how its output feeds the next phase
+
+This keeps critical context fresh at the end of the context window where LLM attention is strongest.
+
+### File Buffering
+All subagent outputs go to `.sparc-session/` files -- never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.
+
+### Iteration Context
+On each iteration cycle, include:
+- Which tests failed and why (from test-results.md)
+- Which coverage gaps exist (from coverage-gaps.md)
+- What was already attempted in previous iterations (from iteration-log.md)
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+-> Phase 1/6: Analyzing code at "{path}"...
+   OK: Found 12 testable units, 3 existing test files
+-> Phase 2/6: Generating test suite...
+   OK: Created 8 test files, 45 test cases
+-> Phase 3/6: Running tests...
+   OK: 42/45 passed, 3 failed | Coverage: 72% lines
+-> Phase 4/6: Analyzing coverage gaps...
+   OK: Found 6 untested code paths
+-> Phase 5/6: Iteration 1 — writing additional tests...
+   OK: Added 12 test cases targeting gaps
+   OK: 54/57 passed, 0 failed | Coverage: 84% lines
+-> Phase 6/6: Assembling test report...
+   OK: Saved report to .sparc-session/test-report.md
+
+Test Summary:
+  Tests: 57 total | 54 passed | 0 failed | 3 skipped
+  Coverage: 84% lines | 78% branches | 86% functions
+  Quality Gate: PASS (standard: 80%+ required)
+  Files Created: 8 test files
+  Iterations: 1 additional cycle
+```
+
+## Integration
+
+- Tests code from `/myaidev-method:myaidev-coder` output
+- Results feed into `/myaidev-method:myaidev-reviewer` for review
+- Part of `/myaidev-method:myaidev-workflow` full SPARC pipeline
+- Shares `.sparc-session/` with other SPARC phases when in workflow mode
+
+## Example Usage
+
+```bash
+# Generate and run unit tests for a module
+/myaidev-method:myaidev-tester ./src/auth --type=unit --coverage
+
+# Full test suite with strict quality gate
+/myaidev-method:myaidev-tester ./src --type=all --coverage --gate=strict
+
+# TDD a new feature (London style)
+/myaidev-method:myaidev-tester "User registration with email verification" --tdd --style=london
+
+# TDD a domain model (Chicago style)
+/myaidev-method:myaidev-tester ./src/models/order.ts --tdd --style=chicago
+
+# Integration tests only
+/myaidev-method:myaidev-tester ./src/api --type=integration --coverage
+
+# E2E tests with minimal gate
+/myaidev-method:myaidev-tester ./src --type=e2e --gate=minimal
+
+# Quick test generation without coverage analysis
+/myaidev-method:myaidev-tester ./src/utils
+
+# Verbose output for debugging
+/myaidev-method:myaidev-tester ./src/services --coverage --verbose
+```