@kennethsolomon/shipkit 1.0.0

package/skills/sk:test/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sk:test
+description: "Auto-detect BE + FE test runners, run both in parallel, verify 100% coverage on new code, fix failures and re-run until all pass."
+---
+
+# Test Verification
+
+## Overview
+
+Auto-detect the project's backend and frontend testing frameworks from config files, run all suites in parallel, and verify 100% coverage on new code. This is the **verification step** (TDD green check) — tests should already exist from `/sk:write-tests`. This skill does NOT write tests.
+
+## Allowed Tools
+
+Bash, Read, Glob, Grep
+
+## Steps
+
+You MUST complete these steps in order:
+
+### 0. Check Project Lessons
+
+If `tasks/lessons.md` exists, read it before doing anything else. Apply every active lesson as a standing constraint. Look for:
+- Known flaky tests in this project
+- Environment-specific runner issues
+- Coverage tool quirks
+
+### 1. Detect Testing Frameworks
+
+Scan for **all** testing stacks by checking config files:
+
+**Backend detection:**
+```bash
+cat composer.json 2>/dev/null    # Pest / PHPUnit
+cat pyproject.toml 2>/dev/null   # pytest
+cat go.mod 2>/dev/null           # Go testing
+cat Cargo.toml 2>/dev/null       # Rust cargo test
+```
+
+**Frontend detection:**
+```bash
+cat package.json 2>/dev/null     # Vitest / Jest
+```
+
+**Detection table:**
+
+| Config file | Indicator | Runner | Command |
+|-------------|-----------|--------|---------|
+| `composer.json` | `pestphp/pest` in require-dev | Pest | `./vendor/bin/pest --coverage --compact` |
+| `composer.json` | `phpunit/phpunit` (no Pest) | PHPUnit | `./vendor/bin/phpunit --coverage-text` |
+| `package.json` | `vitest` in devDependencies | Vitest | `npx vitest run --coverage` |
+| `package.json` | `jest` in devDependencies | Jest | `npx jest --coverage` |
+| `pyproject.toml` | `pytest` in dependencies | pytest | `python -m pytest --cov` |
+| `go.mod` | present | Go test | `go test -cover ./...` |
+| `Cargo.toml` | present | cargo test | `cargo test` |
+
+Report what was detected:
+```
+Backend:  [runner] — [command]
+Frontend: [runner] — [command]
+```
+
+If only one stack exists, report that and proceed with what is available.
+
+### 2. Setup Vitest (conditional)
+
+**Only if Vitest is detected but not yet configured** (no `vitest.config.ts` exists):
+
+Install dependencies:
+```bash
+npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom @vitejs/plugin-react @vitest/coverage-v8
+```
+
+Create `vitest.config.ts`:
+```ts
+import { defineConfig } from 'vitest/sk:config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+    plugins: [react()],
+    test: {
+        environment: 'jsdom',
+        globals: true,
+        setupFiles: ['./resources/js/__tests__/setup.ts'],
+        include: ['resources/js/__tests__/**/*.{test,spec}.{ts,tsx}'],
+        coverage: {
+            provider: 'v8',
+            include: ['resources/js/**/*.{ts,tsx}'],
+            exclude: ['resources/js/__tests__/**', 'resources/js/types/**'],
+        },
+    },
+    resolve: {
+        alias: {
+            '@': '/resources/js',
+        },
+    },
+});
+```
+
+Create `resources/js/__tests__/setup.ts` if missing:
+```ts
+import '@testing-library/jest-dom';
+```
+
+Skip this step entirely if Vitest config already exists or a different FE runner was detected.
+
+### 3. Run All Test Suites
+
+Run BE and FE test suites **in parallel using sub-agents** since they are fully independent:
+
+```
+Sub-agent 1 (BE): [detected BE command]
+Sub-agent 2 (FE): [detected FE command]
+```
+
+If only one stack exists, run it directly — no sub-agent needed.
+
+For large BE suites, you may split further:
+```
+Sub-agent 1: ./vendor/bin/pest --filter=Feature --coverage --compact
+Sub-agent 2: ./vendor/bin/pest --filter=Unit --coverage --compact
+Sub-agent 3: [FE command]
+```
+
+### 4. If Tests Fail
+
+- Read the failure output carefully — identify the root cause
+- Fix the failing **implementation code** or test setup, not the test assertions (tests define expected behavior)
+- Do NOT skip, mark incomplete, or delete failing tests
+- Re-run the failing suite until all tests pass
+- If a fix changes behavior, confirm with the user before applying
+
+### 5. Verify Coverage
+
+- **100% coverage on new code** is required for both suites
+- Check the coverage output from each runner
+- If coverage is below 100% on new code, identify the uncovered lines and report them — do NOT write new tests (that is `/sk:write-tests` responsibility)
+
+### 6. Report Results
+
+Output the final status in this exact format:
+
+```
+BE: X tests passed, X failed — coverage X%
+FE: X tests passed, X failed — coverage X%
+```
+
+- Omit a line if that stack was not detected
+- List any failing tests with `file:line`
+- List any uncovered new code with `file:line`
+
+## Pass Criteria
+
+All detected suites pass with 100% coverage on new code. Both lines of the report show zero failures.
+
+---
+
+## Model Routing
+
+Read `.shipkit/sk:config.json` from the project root if it exists.
+
+- If `model_overrides["sk:test"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | sonnet |
+| `quality` | sonnet |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:write-tests/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: sk:write-tests
+description: "TDD: Auto-detect BE + FE testing stacks, write failing tests before implementation. Updates existing tests when behavior changes."
+---
+
+# Test Generation (TDD)
+
+## Overview
+
+Auto-detect the project's backend AND frontend testing frameworks, read the plan from `tasks/todo.md`, and write comprehensive failing tests BEFORE implementation. Tests define the expected behavior — implementation makes them pass.
+
+## Allowed Tools
+
+Bash, Read, Write, Edit, Glob, Grep
+
+**When the detected framework is `@playwright/sk:test`**, also use:
+mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_run_code, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_take_screenshot
+
+## Steps
+
+You MUST complete these steps in order:
+
+### 0. Check Project Lessons
+
+If `tasks/lessons.md` exists, read it before doing anything else. Apply every active lesson as a standing constraint. Look for:
+- Known flaky test patterns in this project
+- Mocking approaches that caused issues before
+- Framework-specific gotchas
+- File location conventions that broke in the past
+
+### 1. Read the Plan
+
+- Read `tasks/todo.md` to understand what will be implemented
+- Read `tasks/progress.md` for context from brainstorm/design steps
+- Identify all code that will be created or modified
+- This is the **source of truth** for what tests to write
+
+### 2. Detect ALL Testing Frameworks
+
+Scan for **both backend and frontend** testing stacks:
+
+**Backend detection:**
+```bash
+cat composer.json 2>/dev/null       # PHPUnit / Pest
+cat pyproject.toml 2>/dev/null      # pytest
+cat go.mod 2>/dev/null              # Go testing
+cat Cargo.toml 2>/dev/null          # Rust #[cfg(test)]
+cat Gemfile 2>/dev/null             # RSpec / Minitest
+cat build.gradle 2>/dev/null        # JUnit
+```
+
+**Frontend detection:**
+```bash
+cat package.json 2>/dev/null        # Jest, Vitest, Mocha, Cypress, Playwright
+```
+
+Check for framework-specific config:
+- `vitest.config.ts` / `vite.config.ts` (Vitest)
+- `jest.config.js` / `jest.config.ts` (Jest)
+- `phpunit.xml` / `pest` in composer.json (PHPUnit / Pest)
+- `pytest.ini` / `conftest.py` (pytest)
+- `cypress.config.ts` (Cypress)
+- `playwright.config.ts` (Playwright)
+
+Report ALL detected frameworks:
+```
+Backend:  [framework] ([language]) — [test runner command]
+Frontend: [framework] ([language]) — [test runner command]
+```
+
+If only one stack exists (e.g., API-only with no FE, or FE-only SPA), report that and proceed with what's available.
+
+### 3. Check Existing Tests
+
+- Find existing tests related to the code being changed
+- If modifying existing behavior: **update those tests first** to expect the new behavior
+- If adding new code: identify what test files need to be created
+- Report: "Updating X existing test files, creating Y new test files"
+
+### 4. Learn Project Test Conventions
+
+Find and read 1-2 existing test files **per stack** to learn patterns:
+
+From existing tests, learn:
+- Import style and aliases
+- Test structure (describe/it, test(), func TestX)
+- Assertion library and patterns
+- Mocking approach
+- Setup/teardown patterns
+- File naming convention
+- Test file location (co-located vs `tests/` directory)
+
+If **no existing tests** are found, use `references/patterns.md` for framework-appropriate templates.
+
+### 5. Analyze Target Code from Plan
+
+Based on the plan in `tasks/todo.md`, identify test cases for each piece of planned code:
+
+**Backend tests:**
+- **Happy path**: Normal expected behavior for each endpoint/function
+- **Edge cases**: Empty inputs, boundary values, null/undefined
+- **Error handling**: Invalid inputs, thrown exceptions, error responses
+- **Authorization**: Ensure policies/guards are tested
+- **Validation**: All form request / input validation rules
+
+**Frontend tests:**
+- **Component rendering**: Correct output for given props
+- **User interactions**: Click, type, submit, navigate
+- **Conditional rendering**: Show/hide based on state
+- **Error states**: Loading, empty, error displays
+- **Form handling**: Validation, submission, reset
+
+### 6. Determine Test File Locations
+
+Follow the project's existing convention:
+
+| Convention | Pattern | Example |
+|-----------|---------|---------|
+| Co-located | Same directory as source | `src/auth/login.test.ts` |
+| Mirror `tests/` | Parallel directory structure | `tests/auth/login.test.ts` |
+| `__tests__/` | Jest/Vitest convention | `src/auth/__tests__/login.test.ts` |
+| `test_` prefix | Python convention | `tests/test_login.py` |
+| `_test` suffix | Go convention | `auth/login_test.go` |
+| `tests/Feature/` + `tests/Unit/` | Laravel/Pest convention | `tests/Feature/ServerTest.php` |
+
+### 7. Write Backend Test Files
+
+Generate complete test files matching the project's style:
+- One test per behavior, not per line of code
+- Descriptive test names that explain expected behavior
+- Arrange-Act-Assert pattern
+- Mock external dependencies, not the code under test
+- Test behavior, not implementation details
+
+### 8. Write Frontend Test Files
+
+If a frontend stack was detected, generate FE test files:
+- Component tests for every new/modified component
+- Page tests for every new/modified page
+- Hook tests for custom hooks
+- Mock framework helpers (e.g., Inertia's `useForm`, Next.js `useRouter`, SvelteKit `goto`)
+- Use `@testing-library` conventions: prefer `getByRole`, `getByText`, `getByLabelText`
+
+Skip this step if no FE stack was detected.
+
+### 8b. Playwright-Specific (conditional)
+
+**Only if `@playwright/sk:test` is detected:**
+
+Use the Playwright MCP plugin to inspect live page state for more accurate selectors:
+
+1. Navigate to target URL
+2. Capture accessibility snapshot for role-based selectors
+3. Screenshot for visual reference
+4. Optionally run inline assertions for complex interactions
+
+### 9. Verify Tests Fail (Red Phase)
+
+Run both suites to confirm tests fail as expected:
+
+- **Tests SHOULD fail** — this confirms they're testing the right thing
+- If tests pass without implementation, they're not testing anything useful — rewrite them
+- Report which tests fail and why (missing class, missing route, missing component, etc.)
+
+### 10. Report
+
+Output:
+```
+BE tests written: X tests in Y files ([framework])
+FE tests written: X tests in Y files ([framework])  ← omit if no FE stack
+Existing tests updated: X files
+Status: RED (tests fail as expected — ready for implementation)
+```
+
+## Key Principle
+
+Tests define the **expected behavior**. Implementation makes them pass. If you're unsure what a piece of code should do, the test is where you decide.
+
+---
+
+## Model Routing
+
+Read `.shipkit/sk:config.json` from the project root if it exists.
+
+- If `model_overrides["sk:write-tests"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:write-tests/references/patterns.md

@@ -0,0 +1,209 @@
+# Test Framework Templates
+
+Use these templates when the project has **no existing test files** to learn from. Adapt to the project's specific needs.
+
+---
+
+## Vitest + React Testing Library
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { ComponentName } from './ComponentName'
+
+describe('ComponentName', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('renders with default props', () => {
+    render(<ComponentName />)
+    expect(screen.getByText('expected text')).toBeInTheDocument()
+  })
+
+  it('handles user interaction', async () => {
+    const onAction = vi.fn()
+    render(<ComponentName onAction={onAction} />)
+    fireEvent.click(screen.getByRole('button', { name: /submit/i }))
+    expect(onAction).toHaveBeenCalledOnce()
+  })
+
+  it('displays error state', () => {
+    render(<ComponentName error="Something went wrong" />)
+    expect(screen.getByRole('alert')).toHaveTextContent('Something went wrong')
+  })
+})
+```
+
+---
+
+## Jest (Node.js)
+
+```ts
+import { functionName } from './module'
+
+describe('functionName', () => {
+  it('returns expected result for valid input', () => {
+    expect(functionName('input')).toBe('expected')
+  })
+
+  it('throws on invalid input', () => {
+    expect(() => functionName(null)).toThrow('Expected error message')
+  })
+
+  it('handles edge case', () => {
+    expect(functionName('')).toBe('default')
+  })
+})
+
+// Mocking example
+jest.mock('./dependency', () => ({
+  depFunction: jest.fn().mockResolvedValue('mocked'),
+}))
+```
+
+---
+
+## pytest (Python)
+
+```python
+import pytest
+from module import function_name
+
+
+class TestFunctionName:
+    def test_returns_expected_for_valid_input(self):
+        result = function_name("input")
+        assert result == "expected"
+
+    def test_raises_on_invalid_input(self):
+        with pytest.raises(ValueError, match="expected message"):
+            function_name(None)
+
+    def test_handles_empty_input(self):
+        assert function_name("") == "default"
+
+
+# Fixture example
+@pytest.fixture
+def sample_data():
+    return {"key": "value"}
+
+
+def test_with_fixture(sample_data):
+    result = function_name(sample_data)
+    assert result is not None
+
+
+# Mocking example
+def test_with_mock(mocker):
+    mock_dep = mocker.patch("module.dependency.dep_function")
+    mock_dep.return_value = "mocked"
+    result = function_name("input")
+    assert result == "mocked"
+```
+
+---
+
+## Go testing
+
+```go
+package mypackage
+
+import (
+	"testing"
+)
+
+func TestFunctionName(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+		wantErr  bool
+	}{
+		{
+			name:     "valid input",
+			input:    "hello",
+			expected: "HELLO",
+		},
+		{
+			name:    "empty input returns error",
+			input:   "",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := FunctionName(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("FunctionName() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if got != tt.expected {
+				t.Errorf("FunctionName() = %v, want %v", got, tt.expected)
+			}
+		})
+	}
+}
+```
+
+---
+
+## Rust
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_valid_input() {
+        let result = function_name("input");
+        assert_eq!(result, "expected");
+    }
+
+    #[test]
+    #[should_panic(expected = "error message")]
+    fn test_invalid_input_panics() {
+        function_name("");
+    }
+
+    #[test]
+    fn test_returns_none_for_missing() {
+        assert!(function_name("missing").is_none());
+    }
+}
+```
+
+---
+
+## Mocha + Chai
+
+```ts
+import { expect } from 'chai'
+import sinon from 'sinon'
+import { functionName } from './module'
+
+describe('functionName', () => {
+  afterEach(() => {
+    sinon.restore()
+  })
+
+  it('should return expected result for valid input', () => {
+    const result = functionName('input')
+    expect(result).to.equal('expected')
+  })
+
+  it('should throw on invalid input', () => {
+    expect(() => functionName(null)).to.throw('Expected error message')
+  })
+
+  it('should call dependency correctly', () => {
+    const stub = sinon.stub(dependency, 'method').returns('mocked')
+    const result = functionName('input')
+    expect(stub.calledOnce).to.be.true
+    expect(result).to.equal('mocked')
+  })
+})
+```