context-mode 1.0.110 → 1.0.112

package/skills/context-mode-ops/review-pr.md

@@ -1,269 +0,0 @@
-# Review PR Workflow
-
-## Trigger
-
-User says: "review PR #N", "merge PR #N", "check PR #N"
-
-## Core Philosophy
-
-**Merge first, fix on top.** Contributors ghost when you request changes. Merge their work (if not absurd), then fix issues in follow-up commits. This keeps momentum and respects their effort.
-
-**Exception:** Only reject if the PR introduces a security vulnerability, breaks core functionality beyond repair, or is completely unrelated to the project.
-
-## Step-by-Step
-
-### 1. Gather Intelligence (ONE batch call)
-
-```javascript
-commands: [
-  { label: "pr-body", command: "gh pr view {N} --json title,body,state,author,baseRefName,headRefName,additions,deletions,files,reviews,comments,labels" },
-  { label: "pr-diff", command: "gh pr diff {N}" },
-  { label: "pr-comments", command: "gh pr view {N} --comments" },
-  { label: "pr-checks", command: "gh pr checks {N}" },
-  { label: "pr-files", command: "gh pr view {N} --json files --jq '.files[].path'" },
-  { label: "related-issue", command: "gh pr view {N} --json body --jq '.body' | grep -oP '#\\d+' | head -5" }
-],
-queries: [
-  "PR title description changes",
-  "files modified adapter platform",
-  "diff code changes additions deletions",
-  "review comments feedback",
-  "CI check status pass fail",
-  "related issues referenced"
-]
-```
-
-### 2. Classify & Spawn Agents
-
-Same classification as [triage-issue.md](triage-issue.md) step 2, but based on PR diff:
-
-```
-ALWAYS spawn:
-├── Context Mode Architect (reviews all changes)
-├── QA Engineer (tests everything)
-├── DX Engineer (output quality check)
-
-BASED ON FILES CHANGED:
-├── {Platform} Architect (for each affected adapter)
-├── Validation Engineer (verify ENV vars, hooks, configs via websearch)
-
-BASED ON CONTENT:
-├── {Domain} Architect (database, security, OS, hooks, session, etc.)
-```
-
-**Critical addition for PRs — Validation Engineer:**
-
-This agent specifically validates claims made in the PR:
-- ENV variables actually exist in the target platform
-- Hook formats match the platform's actual API
-- Config paths are real, not LLM hallucinations
-- Features referenced actually exist in the platform's codebase
-
-Uses WebSearch and Context7 to verify against official docs.
-
-### 3. Validation Phase (Parallel)
-
-All agents run simultaneously:
-
-**Context Mode Architect:**
-- Does the change align with project architecture?
-- Does it follow existing patterns?
-- Are there edge cases the author missed?
-- Is session continuity preserved?
-- **TDD compliance**: Does the PR include tests? Do tests verify behavior (not implementation)?
-  - If no tests: flag as CHANGES_NEEDED (but still merge + add tests in follow-up)
-  - If tests mock internal collaborators: flag — tests should use public interfaces per [tdd.md](tdd.md)
-
-**QA Engineer:**
-```shell
-# Checkout PR locally
-gh pr checkout {N}
-
-# Run affected adapter tests
-npx vitest run tests/adapters/{affected}.test.ts
-
-# Run full suite
-npm test
-
-# TypeScript
-npm run typecheck
-```
-
-**Validation Engineer:**
-```javascript
-// For each ENV var mentioned in the PR:
-// 1. Grep for it in context-mode source
-// 2. WebSearch: "{PLATFORM_NAME} {ENV_VAR} environment variable"
-// 3. Context7: resolve-library-id for the platform, then query-docs
-
-// Example: PR adds OPENCODE_CONFIG_PATH
-// → Search OpenCode source: does this env var exist?
-// → If not: flag as potential LLM hallucination
-```
-
-**Platform Architects:**
-- Review changes specific to their platform
-- Validate against platform's actual hook/config format
-- Check backward compatibility
-
-### 4. Merge Decision Matrix
-
-```
-All tests pass + All architects APPROVE?
-├── YES → Merge immediately
-│
-├── TESTS FAIL but fix is trivial?
-│   └── Merge → Fix on top in follow-up commit
-│
-├── ARCHITECT has minor concerns?
-│   └── Merge → Fix concerns in follow-up commit
-│
-├── VALIDATION catches hallucinated ENV/feature?
-│   └── Merge if core logic is sound → Remove hallucinated parts
-│   └── OR: Comment explaining the issue, give 48h, then merge+fix
-│
-├── SECURITY issue found?
-│   └── Do NOT merge. Comment with specific vulnerability.
-│
-└── PR is completely off-base?
-    └── Close with kind explanation. Rare — almost never do this.
-```
-
-### 5. Merge to `next` & Fix Flow
-
-Always use `gh` CLI. Always squash merge into `next`:
-
-```bash
-# Change PR base to next if needed
-gh pr edit {N} --base next
-
-# Squash merge into next
-gh pr merge {N} --squash
-```
-
-If follow-up fixes needed, push directly to `next`:
-
-```bash
-git checkout next
-git pull origin next
-```
-
-**Follow-up fixes MUST follow TDD** (per [tdd.md](tdd.md)):
-
-```bash
-# RED: Write failing test for the issue found during review
-npx vitest run tests/{file}.test.ts  # verify FAILS
-
-# GREEN: Write minimal fix
-# ... edit files ...
-npx vitest run tests/{file}.test.ts  # verify PASSES
-
-# REFACTOR: Clean up
-npm test  # full suite still passes
-
-# Commit
-git add {files}
-git commit -m "fix: address review findings from #{N}
-
-- {fix 1}
-- {fix 2}
-
-Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
-
-git push origin next
-```
-
-### 6. Comment on PR
-
-**After merge (standard):**
-
-```bash
-gh pr comment {N} --body "$(cat <<'EOF'
-Thanks for this contribution, @{author}! 🎉
-
-Merged into `next` — this will ship in the next release.
-
-Could you please test it in your setup once the release is out? You know this area best, so your verification would be really valuable. 🙏
-
-{IF follow-up fixes were made:}
-I made a small follow-up adjustment in {commit_sha}:
-- {what was adjusted and why}
-EOF
-)"
-```
-
-**After merge with concerns:**
-
-```bash
-gh pr comment {N} --body "$(cat <<'EOF'
-Thanks @{author}! Merged this into `next`.
-
-I made a few adjustments on top:
-- {change 1}: {reason}
-- {change 2}: {reason}
-
-These are in {commit_sha}. Could you review those changes and test the complete flow in your environment? The responsibility for verifying this works end-to-end is on you since you're closest to the use case. 🙏
-
-This will ship in the next release!
-EOF
-)"
-```
-
-**Rare: closing without merge:**
-
-```bash
-gh pr comment {N} --body "$(cat <<'EOF'
-Hey @{author}, thanks for taking the time to put this together!
-
-Unfortunately, we can't merge this as-is because:
-- {specific technical reason}
-
-{IF salvageable:}
-If you'd like to take another pass, here's what would need to change:
-- {specific guidance}
-
-{IF not salvageable:}
-The direction we're going with this area is {explanation}. I appreciate the effort though!
-EOF
-)"
-gh pr close {N}
-```
-
-## ENV/Feature Validation Protocol
-
-This is the most critical part of PR review. LLMs frequently hallucinate ENV vars, hooks, and features.
-
-### Red Flags to Watch For
-
-1. **New ENV variable** — Does this actually exist in the platform?
-2. **New hook type** — Does the platform support this hook lifecycle?
-3. **Config path** — Is this the real config location?
-4. **API endpoint** — Does this API actually exist?
-5. **Feature flag** — Is this a real feature of the platform?
-
-### Verification Steps
-
-For EACH claim in the PR:
-
-1. **Grep source**: `rg "{CLAIM}" src/` — is it already used?
-2. **WebSearch**: Search for official documentation of the claim
-3. **Context7**: `resolve-library-id` → `query-docs` for the platform
-4. **GitHub source**: Check the platform's actual repository if open source
-
-### Example: Fake ENV Detection
-
-```
-PR adds: process.env.OPENCODE_HOOK_PATH
-Step 1: rg "OPENCODE_HOOK_PATH" src/ → not found
-Step 2: WebSearch "OpenCode OPENCODE_HOOK_PATH environment variable" → no results
-Step 3: Context7 query OpenCode docs for "HOOK_PATH" → not documented
-Verdict: HALLUCINATED — flag to EM, remove from PR
-```
-
-## Handling Stale PRs
-
-If a PR has been open >7 days with no activity:
-1. Check if it's still relevant
-2. If yes: merge it, fix on top
-3. If no: close with kind explanation
-4. Never leave PRs in limbo

package/skills/context-mode-ops/tdd.md

@@ -1,329 +0,0 @@
-# Test-Driven Development
-
-<tdd_enforcement>
-THIS FILE IS MANDATORY. Every agent, every Staff Engineer, every Architect MUST follow this.
-If you skip TDD, your work will be REJECTED. There are no exceptions.
-Do NOT write implementation code before you have a failing test.
-</tdd_enforcement>
-
-> Source: [mattpocock/skills/tdd](https://github.com/mattpocock/skills/tree/main/tdd) — embedded with context-mode enforcement.
-
-## Philosophy
-
-**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
-
-**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
-
-**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
-
-## Anti-Pattern: Horizontal Slices
-
-**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
-
-This produces **crap tests**:
-
-- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
-- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
-- Tests become insensitive to real changes — they pass when behavior breaks, fail when behavior is fine
-- You outrun your headlights, committing to test structure before understanding the implementation
-
-**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
-
-```
-WRONG (horizontal):
-  RED:   test1, test2, test3, test4, test5
-  GREEN: impl1, impl2, impl3, impl4, impl5
-
-RIGHT (vertical):
-  RED→GREEN: test1→impl1
-  RED→GREEN: test2→impl2
-  RED→GREEN: test3→impl3
-  ...
-```
-
-## Workflow
-
-### 1. Planning
-
-Before writing any code:
-
-- [ ] Identify what behaviors need to change or be added
-- [ ] List the behaviors to test (not implementation steps)
-- [ ] Identify opportunities for deep modules (small interface, deep implementation)
-- [ ] Design interfaces for testability
-
-**You can't test everything.** Focus testing effort on critical paths and complex logic, not every possible edge case.
-
-### 2. Tracer Bullet
-
-For the first behavior:
-
-```
-RED:   Write test for first behavior → test fails
-GREEN: Write minimal code to pass → test passes
-```
-
-Then refactor:
-
-- [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
-- [ ] Apply SOLID principles where natural
-- [ ] Consider what new code reveals about existing code
-- [ ] Run tests after each refactor step
-
-**Never refactor while RED.** Get to GREEN first.
-
-### 3. Next Behavior
-
-```
-RED:   Write next test → fails
-GREEN: Minimal code to pass → passes
-```
-
-Refactor again. Repeat until all behaviors are covered.
-
----
-
-## Good and Bad Tests
-
-### Good Tests (Integration-Style)
-
-```typescript
-// GOOD: Tests observable behavior
-test("user can checkout with valid cart", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
-
-Characteristics:
-
-- Tests behavior users/callers care about
-- Uses public API only
-- Survives internal refactors
-- Describes WHAT, not HOW
-- One logical assertion per test
-
-### Bad Tests (Implementation-Coupled)
-
-```typescript
-// BAD: Tests implementation details
-test("checkout calls paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-Red flags:
-
-- Mocking internal collaborators
-- Testing private methods
-- Asserting on call counts/order
-- Test breaks when refactoring without behavior change
-- Test name describes HOW not WHAT
-- Verifying through external means instead of interface
-
-```typescript
-// BAD: Bypasses interface to verify
-test("createUser saves to database", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// GOOD: Verifies through interface
-test("createUser makes user retrievable", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```
-
----
-
-## When to Mock
-
-Mock at **system boundaries** only:
-
-- External APIs (payment, email, etc.)
-- Databases (sometimes — prefer test DB)
-- Time/randomness
-- File system (sometimes)
-
-Don't mock:
-
-- Your own classes/modules
-- Internal collaborators
-- Anything you control
-
-### Designing for Mockability
-
-**1. Use dependency injection**
-
-Pass external dependencies in rather than creating them internally:
-
-```typescript
-// Easy to mock
-function processPayment(order, paymentClient) {
-  return paymentClient.charge(order.total);
-}
-
-// Hard to mock
-function processPayment(order) {
-  const client = new StripeClient(process.env.STRIPE_KEY);
-  return client.charge(order.total);
-}
-```
-
-**2. Prefer SDK-style interfaces over generic fetchers**
-
-Create specific functions for each external operation instead of one generic function with conditional logic:
-
-```typescript
-// GOOD: Each function is independently mockable
-const api = {
-  getUser: (id) => fetch(`/users/${id}`),
-  getOrders: (userId) => fetch(`/users/${userId}/orders`),
-  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
-};
-
-// BAD: Mocking requires conditional logic inside the mock
-const api = {
-  fetch: (endpoint, options) => fetch(endpoint, options),
-};
-```
-
-The SDK approach means:
-- Each mock returns one specific shape
-- No conditional logic in test setup
-- Easier to see which endpoints a test exercises
-- Type safety per endpoint
-
----
-
-## Interface Design for Testability
-
-Good interfaces make testing natural:
-
-1. **Accept dependencies, don't create them**
-
-   ```typescript
-   // Testable
-   function processOrder(order, paymentGateway) {}
-
-   // Hard to test
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **Return results, don't produce side effects**
-
-   ```typescript
-   // Testable
-   function calculateDiscount(cart): Discount {}
-
-   // Hard to test
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **Small surface area**
-   - Fewer methods = fewer tests needed
-   - Fewer params = simpler test setup
-
----
-
-## Deep Modules
-
-From "A Philosophy of Software Design":
-
-**Deep module** = small interface + lots of implementation
-
-```
-┌─────────────────────┐
-│   Small Interface   │  ← Few methods, simple params
-├─────────────────────┤
-│                     │
-│                     │
-│  Deep Implementation│  ← Complex logic hidden
-│                     │
-│                     │
-└─────────────────────┘
-```
-
-**Shallow module** = large interface + little implementation (avoid)
-
-```
-┌─────────────────────────────────┐
-│       Large Interface           │  ← Many methods, complex params
-├─────────────────────────────────┤
-│  Thin Implementation            │  ← Just passes through
-└─────────────────────────────────┘
-```
-
-When designing interfaces, ask:
-
-- Can I reduce the number of methods?
-- Can I simplify the parameters?
-- Can I hide more complexity inside?
-
----
-
-## Refactor Candidates
-
-After TDD cycle, look for:
-
-- **Duplication** → Extract function/class
-- **Long methods** → Break into private helpers (keep tests on public interface)
-- **Shallow modules** → Combine or deepen
-- **Feature envy** → Move logic to where data lives
-- **Primitive obsession** → Introduce value objects
-- **Existing code** the new code reveals as problematic
-
----
-
-## context-mode Specific Rules
-
-### CONTRIBUTING.md Is the Authority
-
-**Read `CONTRIBUTING.md` before writing any test.** It defines:
-- Test file organization (which file to put your test in)
-- TDD workflow (Red-Green-Refactor)
-- Output quality comparison (before/after)
-- Local development setup
-
-**Do NOT create new test files.** `CONTRIBUTING.md` has the complete test file mapping. Add your tests to the existing file that covers the same domain. If no file fits, ask the maintainer.
-
-### CI Builds Bundles — You Don't
-
-**Do NOT run `npm run build` or `npm run bundle`.** Bundle files (`server.bundle.mjs`, `cli.bundle.mjs`) are generated by GitHub CI automatically. Never create, modify, or push bundle files. You only run:
-
-```bash
-npm test              # vitest — validates behavior
-npm run typecheck     # tsc --noEmit — validates types
-```
-
-That's it. No build. No bundle. CI handles the rest.
-
-### TDD Enforcement in Subagents
-
-Every Staff Engineer agent MUST include this in their prompt:
-
-```
-MANDATORY TDD — your work will be REJECTED without this:
-1. Read CONTRIBUTING.md for test file organization — do NOT create new test files
-2. Write a failing test FIRST in the correct existing test file
-3. Run: npx vitest run tests/{file} — MUST FAIL
-4. Write minimal code to pass
-5. Run: npx vitest run tests/{file} — MUST PASS
-6. Refactor if needed, tests stay green
-7. Report RED→GREEN evidence:
-   "RED:  test 'detects opencode via env var' — FAIL (expected)"
-   "GREEN: added env check in detect.ts — PASS"
-   Without this evidence, your PR is auto-rejected.
-```