@mclawnet/agent 0.5.8 → 0.6.1

package/skills/technical-writing/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: technical-writing
+description: Write clear, accurate technical documentation including API docs, architecture guides, runbooks, READMEs, and technical proposals. Use when creating or improving technical documents, writing specs, or documenting systems for developer audiences.
+---
+
+# Technical Writing
+
+Write clear, accurate, and useful technical documentation for developer audiences — API docs, architecture guides, runbooks, READMEs, RFCs, and technical proposals.
+
+## Overview
+
+Good technical writing is invisible: readers find what they need, understand it on first read, and can act on it without asking someone. This skill provides a systematic approach to planning, structuring, writing, and reviewing technical documents.
+
+## When to Use
+
+- Writing API documentation or reference guides
+- Creating architecture decision records (ADRs) or design docs
+- Writing README files for projects or packages
+- Authoring runbooks for operational procedures
+- Drafting RFCs or technical proposals
+- Documenting onboarding guides or setup instructions
+- Improving existing documentation that is unclear or outdated
+
+## When NOT to Use
+
+- **Blog posts or marketing content** — use the `content-research-writer` skill
+- **Meeting notes** — use the `meeting-insights-analyzer` skill
+- **Code comments** — those belong in the code, not a separate document
+- **User-facing help articles** — different audience, different style
+
+## Writing Process
+
+### Step 1: Define Audience and Purpose
+
+Before writing a single word:
+
+1. **Who reads this?** (Junior dev? SRE? External API consumer? Future you?)
+2. **What do they need to do?** (Set up the project? Call an API? Debug an issue?)
+3. **What do they already know?** (Don't explain Git to senior engineers)
+4. **When do they read this?** (During onboarding? At 3am during an incident?)
+
+### Step 2: Choose the Document Type
+
+| Type | Purpose | Structure |
+|---|---|---|
+| README | First impression, quick start | Title → What → Quick start → Install → Usage → Contributing |
+| API Reference | Endpoint/function documentation | Endpoint → Parameters → Request → Response → Errors → Example |
+| Architecture Doc | System design explanation | Context → Goals → Design → Trade-offs → Alternatives |
+| ADR | Record a specific decision | Status → Context → Decision → Consequences |
+| Runbook | Step-by-step operational procedure | When to use → Prerequisites → Steps → Rollback → Contacts |
+| RFC/Proposal | Propose a change for review | Problem → Proposal → Alternatives → Migration → Timeline |
+| Onboarding Guide | Get someone productive | Prerequisites → Setup → First task → Resources → FAQ |
+
+### Step 3: Write the First Draft
+
+**Structure first, prose second.** Write all headings and bullet points before filling in paragraphs. This prevents rambling and ensures logical flow.
+
+**Lead with the action.** For every section, the reader should know within the first sentence what to DO.
+
+**One idea per paragraph.** If a paragraph covers two topics, split it.
+
+### Step 4: Review and Refine
+
+Run through the quality checklist (below) before publishing.
+
+## Writing Principles
+
+### Be Direct
+
+- Bad: "It should be noted that the configuration file needs to be updated prior to deployment."
+- Good: "Update `config.yaml` before deploying."
+
+### Be Specific
+
+- Bad: "The API may return an error in certain conditions."
+- Good: "The API returns `403 Forbidden` when the API key lacks `write` scope."
+
+### Be Complete
+
+- Bad: "Install the dependencies and run the server."
+- Good: "Run `npm install` to install dependencies, then `npm run dev` to start the server on port 3000."
+
+### Show, Don't Just Tell
+
+- Bad: "The function accepts various options."
+- Good:
+  ```typescript
+  createUser({
+    name: "Alice",          // required
+    email: "alice@co.com",  // required, must be valid email
+    role: "admin",          // optional, defaults to "viewer"
+  });
+  ```
+
+### Use Consistent Terminology
+
+Pick one term for each concept and use it everywhere. Don't alternate between "endpoint", "route", and "API path" for the same thing. Define terms in a glossary if needed.
+
+## Document Templates
+
+### README Template
+
+```markdown
+# Project Name
+
+One-sentence description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+# Open http://localhost:3000
+\`\`\`
+
+## What This Does
+
+2-3 paragraphs explaining the project's purpose and key features.
+
+## Installation
+
+Step-by-step installation instructions.
+
+## Usage
+
+Most common usage examples with code.
+
+## Configuration
+
+Environment variables and config file options.
+
+## API
+
+Brief API reference or link to full docs.
+
+## Development
+
+How to set up the dev environment, run tests, and contribute.
+
+## License
+
+[License type]
+```
+
+### API Endpoint Template
+
+```markdown
+## POST /api/users
+
+Create a new user account.
+
+### Request
+
+**Headers:**
+| Header | Value | Required |
+|--------|-------|----------|
+| Authorization | Bearer {token} | Yes |
+| Content-Type | application/json | Yes |
+
+**Body:**
+\`\`\`json
+{
+  "name": "Alice Smith",
+  "email": "alice@example.com",
+  "role": "admin"
+}
+\`\`\`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Full name, 1-100 characters |
+| email | string | Yes | Valid email address |
+| role | string | No | One of: admin, editor, viewer. Default: viewer |
+
+### Response
+
+**201 Created:**
+\`\`\`json
+{
+  "id": "usr_abc123",
+  "name": "Alice Smith",
+  "email": "alice@example.com",
+  "role": "admin",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+\`\`\`
+
+### Errors
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | INVALID_EMAIL | Email format is invalid |
+| 409 | EMAIL_EXISTS | An account with this email already exists |
+| 403 | INSUFFICIENT_PERMISSIONS | API key lacks user:create scope |
+```
+
+### Runbook Template
+
+```markdown
+# Runbook: [Procedure Name]
+
+## When to Use
+[Describe the situation that triggers this runbook]
+
+## Prerequisites
+- [ ] Access to [system/tool]
+- [ ] Permissions: [specific permissions needed]
+- [ ] Notify: [who to inform before starting]
+
+## Steps
+
+### 1. [First Step]
+\`\`\`bash
+[exact command]
+\`\`\`
+Expected output: [what you should see]
+If this fails: [what to do]
+
+### 2. [Second Step]
+...
+
+## Verification
+How to confirm the procedure was successful:
+\`\`\`bash
+[verification command]
+\`\`\`
+
+## Rollback
+If something goes wrong:
+1. [Rollback step 1]
+2. [Rollback step 2]
+
+## Contacts
+- Primary: [name, contact]
+- Escalation: [name, contact]
+
+## Revision History
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | Name | Initial version |
+```
+
+## Quality Checklist
+
+### Structure
+- [ ] Title clearly states what the document is about
+- [ ] Table of contents for documents > 3 sections
+- [ ] Headings create a logical hierarchy (H1 → H2 → H3, no skipping)
+- [ ] Sections are ordered by importance or workflow sequence
+
+### Content
+- [ ] Every claim is verifiable (commands, URLs, examples)
+- [ ] Code examples are complete and runnable (not pseudocode)
+- [ ] Error scenarios are documented, not just the happy path
+- [ ] Prerequisites are listed before the steps that need them
+- [ ] No assumptions about reader's environment (OS, tools, versions stated)
+
+### Clarity
+- [ ] No jargon without definition on first use
+- [ ] Sentences average < 20 words
+- [ ] Active voice used throughout ("Run the command" not "The command should be run")
+- [ ] Each paragraph has one topic
+
+### Maintenance
+- [ ] Version/date visible (so readers know if it's current)
+- [ ] No hardcoded values that change (use variables or "replace X with your value")
+- [ ] Links are to specific versions/commits, not "latest" (which changes)
+- [ ] Contact/owner information included
+
+## Common Anti-Patterns
+
+### Write Once, Never Update
+**Problem**: Documentation written at launch, never updated as the system changes.
+**Fix**: Treat docs as code — update them in the same PR that changes the feature.
+
+### Wall of Text
+**Problem**: 2000-word document with no headings, no code blocks, no structure.
+**Fix**: Use headings every 3-5 paragraphs. Add code blocks for commands. Use tables for structured data.
+
+### Assumed Knowledge
+**Problem**: "Just SSH in and restart the service" — assumes reader knows which server, which service, and how to SSH.
+**Fix**: Include every detail. Over-specify rather than under-specify.
+
+### Tutorial Disguised as Reference
+**Problem**: API docs that read like a tutorial ("First, you'll want to...").
+**Fix**: Reference docs should be scannable. Use tables, consistent format, and direct language.

package/skills/testing/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: testing
+description: Design and implement comprehensive test suites using TDD methodology. Use when writing tests, improving test coverage, debugging test failures, or deciding what type of test to write for a given scenario.
+---
+
+# Testing
+
+Design and implement comprehensive, maintainable test suites following Test-Driven Development methodology and proven test design techniques.
+
+## Overview
+
+This skill provides structured guidance for all testing activities: choosing the right test type for a given scenario, designing effective test cases using formal techniques, writing readable and maintainable tests, and achieving meaningful coverage targets.
+
+Testing is not about achieving a coverage number. It is about building a safety net that catches real bugs, documents intended behavior, and gives developers confidence to refactor.
+
+## When to Use
+
+- Writing tests for new features or bug fixes
+- Improving test coverage for existing code
+- Debugging flaky or failing tests
+- Deciding what type of test to write (unit vs integration vs E2E)
+- Applying TDD workflow to drive implementation
+- Reviewing test quality and identifying gaps
+
+## When NOT to Use
+
+- **Code review** — use the `code-review` skill instead
+- **Browser-based E2E testing** with Playwright/Puppeteer — use the `webapp-testing` skill instead
+- **Performance benchmarking** — use the `performance-analysis` skill
+- **Security testing** — use the `security-audit` skill
+
+## TDD Cycle
+
+Follow the Red-Green-Refactor cycle strictly. Do not skip steps.
+
+### Step 1: Red — Write a Failing Test
+
+1. Identify the next smallest piece of behavior to implement
+2. Write a test that describes that behavior in terms of inputs and expected outputs
+3. Run the test suite and confirm the new test fails
+4. The failure message should clearly indicate what is missing
+
+Key rules:
+- Write only ONE test at a time
+- The test must fail for the RIGHT reason (missing implementation, not a syntax error)
+- Do not write implementation code during this step
+
+### Step 2: Green — Make It Pass
+
+1. Write the MINIMAL code to make the failing test pass
+2. It is acceptable to hardcode return values or use shortcuts at this stage
+3. Run the full test suite to confirm the new test passes AND no existing tests broke
+
+Key rules:
+- Change only production code, not test code
+- Do not add functionality beyond what the test requires
+
+### Step 3: Refactor — Improve the Code
+
+1. Look for duplication, unclear naming, or structural issues in BOTH test and production code
+2. Apply refactoring patterns (extract method, rename, simplify conditionals)
+3. Run the full test suite after each refactoring step
+4. All tests must remain green throughout
+
+Key rules:
+- Do not change behavior during refactoring — only structure
+- Refactor test code too: extract helpers, improve naming, reduce duplication
+
+## Test Strategy Selection
+
+Choose the test type based on what you are testing. Use the most focused test type that can verify the behavior.
+
+### Decision Matrix
+
+| What You Are Testing | Test Type | Why |
+|---|---|---|
+| Pure function (input → output) | Unit test | Fast, isolated, deterministic |
+| Single class or module behavior | Unit test | Mock collaborators, test logic |
+| Component interaction (2-3 modules) | Integration test | Verify contracts between components |
+| Database queries or ORM behavior | Integration test | Need real or in-memory database |
+| API endpoint request/response | Integration test | Test HTTP layer with real routing |
+| Full user workflow (multi-step) | E2E test | Validate end-to-end behavior |
+| Data transformation correctness | Property-based test | Generate many inputs automatically |
+| Error handling and failure modes | Negative test | Verify graceful degradation |
+| Performance-critical path | Benchmark test | Measure and assert timing/throughput |
+| Backward compatibility | Contract test | Assert API shape has not changed |
+
+### Rules of Thumb
+
+- If you can test it with a unit test, do not write an integration test
+- If the behavior depends on infrastructure (DB, network, filesystem), use an integration test
+- Write E2E tests only for critical user paths — they are slow and brittle
+- Aim for a test pyramid: many unit tests, fewer integration tests, fewest E2E tests
+
+## Test Design Techniques
+
+### Boundary Value Analysis
+
+Bugs cluster at boundaries. For every input range, test:
+
+- **Minimum value** — the lowest valid input
+- **Just below minimum** — should be rejected or handled
+- **Just above minimum** — should be accepted
+- **Maximum value** — the highest valid input
+- **Just above maximum** — should be rejected or handled
+- **Zero / empty / null** — often a special case
+- **Off-by-one** — array indices, loop counters, pagination offsets
+
+Example boundaries: empty string, single character, max length string; empty array, single element, max size array; integer 0, -1, 1, MAX_SAFE_INTEGER.
+
+### Equivalence Partitioning
+
+Divide inputs into classes where all values in a class should produce the same behavior. Test ONE representative from each class.
+
+**Valid partitions** — inputs the system should accept:
+- Typical value from each valid range
+- Each distinct valid format or type
+
+**Invalid partitions** — inputs the system should reject:
+- Wrong type (string instead of number, null instead of object)
+- Out of range (negative age, future birthdate)
+- Malformed format (invalid email, wrong date format)
+- Missing required fields
+
+### State Transition Testing
+
+For components with lifecycle or state machines:
+
+1. Identify all states the component can be in
+2. Identify all events/inputs that trigger transitions
+3. Map every valid transition (state + event → new state)
+4. Test each valid transition at least once
+5. Test invalid transitions (events that should not be possible in a given state)
+
+### Decision Table Testing
+
+For functions with complex conditional logic (multiple boolean conditions):
+
+1. List all conditions (inputs that affect the decision)
+2. List all actions (possible outcomes)
+3. Create a truth table with every combination of conditions
+4. For each combination, determine the expected action
+5. Write one test for each row in the table
+
+## Test Quality Dimensions
+
+Use these dimensions to assess and improve test suite quality.
+
+### 1. Coverage
+
+Track three types:
+- **Line coverage** — percentage of lines executed
+- **Branch coverage** — percentage of conditional branches taken
+- **Function coverage** — percentage of functions called
+
+Important: High coverage does not mean good tests. A test that executes code without meaningful assertions provides false confidence.
+
+### 2. Isolation
+
+Each test must be independent:
+- Tests must not depend on execution order
+- Tests must not share mutable state
+- Use fresh fixtures for each test (setup/teardown)
+- Mock external systems (network, database, filesystem) in unit tests
+
+### 3. Readability
+
+Tests are documentation. Optimize for clarity:
+- **Naming**: `should [expected behavior] when [condition]`
+- **AAA pattern**: Clearly separate Arrange, Act, and Assert sections
+- **One concept per test**: Each test verifies one logical assertion
+- **No logic in tests**: Avoid conditionals, loops, or try/catch in test code
+- **Literal values**: Use concrete values, not computed values, in assertions
+
+### 4. Maintainability
+
+Tests must be cheap to maintain:
+- **DRY test helpers**: Extract repeated setup into helper functions
+- **Builder pattern**: Use test data builders for complex objects
+- **Avoid brittle selectors**: Test behavior, not implementation details
+- **Keep tests close to source**: Co-locate `foo.test.ts` with `foo.ts`
+
+### 5. Speed
+
+Fast tests get run more often:
+- Unit tests: target < 10ms each, entire suite < 10 seconds
+- Integration tests: target < 500ms each, entire suite < 2 minutes
+- Segregate slow tests with tags or directories
+
+### 6. Determinism
+
+A test that sometimes passes and sometimes fails is worse than no test:
+- Do not depend on wall-clock time — use fake timers
+- Do not depend on random values unless you seed the generator
+- Do not depend on network availability — mock HTTP calls
+- Do not depend on file system state — use temporary directories
+- If a test is flaky, fix it immediately or delete it
+
+## Test Organization
+
+### File Structure
+
+```
+src/
+  services/
+    user-service.ts
+    user-service.test.ts          # unit tests co-located
+  utils/
+    validator.ts
+    validator.test.ts
+test/
+  integration/
+    user-api.integration.test.ts  # integration tests separated
+  e2e/
+    user-workflow.e2e.test.ts     # E2E tests separated
+  helpers/
+    test-factory.ts               # shared test data builders
+    mock-database.ts              # shared mocks
+  fixtures/
+    sample-user.json              # static test data
+```
+
+### Describe/It Nesting
+
+```typescript
+describe("UserService", () => {
+  describe("createUser", () => {
+    it("should create a user with valid input", () => {
+      // Arrange
+      const input = { name: "Alice", email: "alice@example.com" };
+      // Act
+      const result = userService.createUser(input);
+      // Assert
+      expect(result.id).toBeDefined();
+      expect(result.name).toBe("Alice");
+    });
+
+    it("should throw ValidationError when email is missing", () => {
+      expect(() => userService.createUser({ name: "Alice" })).toThrow(ValidationError);
+    });
+
+    describe("when user already exists", () => {
+      it("should throw DuplicateError", () => { /* ... */ });
+    });
+  });
+});
+```
+
+### Setup and Teardown
+
+- Use `beforeEach` for per-test setup (fresh state)
+- Use `afterEach` for per-test cleanup (close connections, clear mocks)
+- Use `beforeAll` / `afterAll` sparingly — only for expensive, read-only setup
+- Always call `jest.restoreAllMocks()` or equivalent in `afterEach`
+
+## Common Patterns
+
+### Parameterized Tests
+
+```typescript
+it.each([
+  { input: "", expected: false },
+  { input: "a", expected: false },
+  { input: "valid@email.com", expected: true },
+  { input: "no-at-sign.com", expected: false },
+])("isValidEmail('$input') should return $expected", ({ input, expected }) => {
+  expect(isValidEmail(input)).toBe(expected);
+});
+```
+
+### Snapshot Tests
+
+- Review snapshot diffs carefully during code review
+- Update snapshots intentionally, never blindly with `--update`
+- Keep snapshots small — snapshot a component, not an entire page
+- Prefer inline snapshots for small outputs
+
+### Error Testing
+
+```typescript
+// Synchronous
+expect(() => divide(1, 0)).toThrow(DivisionByZeroError);
+
+// Async
+await expect(fetchUser("nonexistent")).rejects.toThrow(NotFoundError);
+
+// Error properties
+try {
+  await riskyOperation();
+  fail("Expected an error");
+} catch (error) {
+  expect(error).toBeInstanceOf(AppError);
+  expect(error.code).toBe("RATE_LIMITED");
+}
+```
+
+### Async Testing
+
+```typescript
+// Awaiting promises
+it("should fetch user data", async () => {
+  const user = await userService.getById("123");
+  expect(user.name).toBe("Alice");
+});
+
+// Fake timers
+it("should retry after delay", async () => {
+  jest.useFakeTimers();
+  const promise = retryableOperation();
+  jest.advanceTimersByTime(3000);
+  const result = await promise;
+  expect(result).toBe("success");
+  jest.useRealTimers();
+});
+```
+
+## Coverage Goals
+
+### Tiered Targets
+
+| Code Category | Line Coverage | Branch Coverage | Rationale |
+|---|---|---|---|
+| Business logic, domain rules | 90%+ | 80%+ | Highest value, highest risk |
+| API handlers, controllers | 80%+ | 70%+ | User-facing entry points |
+| Utility functions, helpers | 70%+ | 60%+ | Reused widely, moderate risk |
+| Glue code, configuration | 50%+ | — | Low logic density |
+| Generated code, vendor wrappers | No target | — | Not worth testing |
+
+### Coverage Rules
+
+- Every bug fix MUST include a regression test that fails without the fix and passes with it
+- New features must meet the coverage target for their category before merge
+- Coverage should never decrease on a PR without explicit justification
+
+## Anti-Patterns to Avoid
+
+### Testing Implementation Details
+BAD: Testing that a function calls another function internally.
+GOOD: Testing that given input X, the output is Y. If you refactor internals and tests break without any behavior change, the tests are testing implementation.
+
+### Over-Mocking
+BAD: Mocking every dependency, including simple value objects and pure functions.
+GOOD: Mock only external systems (network, database, clock) and expensive operations.
+
+### Test Interdependence
+BAD: Test B relies on state created by Test A.
+GOOD: Each test creates its own state from scratch.
+
+### Ignoring Test Failures
+BAD: Marking failing tests as `skip` and moving on.
+GOOD: Fix the test immediately. If it cannot be fixed now, create a tracked issue and delete the test.
+
+### Testing the Framework
+BAD: Testing that Express routes requests to handlers, or that React renders JSX.
+GOOD: Testing your logic within those frameworks. Trust the framework.
+
+### Tautological Tests
+BAD: `expect(add(2, 3)).toBe(2 + 3)` — repeats the implementation logic.
+GOOD: `expect(add(2, 3)).toBe(5)` — uses a hardcoded expected value.
+
+### Assertion-Free Tests
+BAD: A test that calls a function but never asserts anything.
+GOOD: Every test has at least one meaningful assertion about the result or side effect.