context-mode 1.0.54 → 1.0.56

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

@@ -0,0 +1,329 @@
+# 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.
+```

package/skills/context-mode-ops/triage-issue.md

@@ -0,0 +1,218 @@
+# Triage Issue Workflow
+
+## Trigger
+
+User says: "triage issue #N", "fix issue #N", "analyze issue #N"
+
+## Step-by-Step
+
+### 1. Gather Intelligence (ONE batch call)
+
+Use `ctx_batch_execute` to gather everything in ONE call:
+
+```javascript
+commands: [
+  { label: "issue-body", command: "gh issue view {N} --json title,body,labels,state,comments,author,createdAt" },
+  { label: "issue-comments", command: "gh issue view {N} --comments" },
+  { label: "recent-related-prs", command: "gh pr list --state all --limit 10 --json number,title,state,headRefName" },
+  { label: "source-tree", command: "find src -type f -name '*.ts' | sort" },
+  { label: "test-tree", command: "find tests -type f -name '*.test.ts' | sort" },
+  { label: "open-issues", command: "gh issue list --state open --limit 20 --json number,title,labels" }
+],
+queries: [
+  "issue title description problem",
+  "affected adapter platform",
+  "error message stack trace",
+  "environment variables mentioned",
+  "OS platform specific",
+  "related PRs and issues"
+]
+```
+
+### 2. Classify Domains
+
+From the gathered intelligence, identify:
+
+- [ ] **Affected adapters** — which of the 12 platforms?
+- [ ] **Affected OS** — macOS, Linux, Windows, or all?
+- [ ] **Core modules** — server, store, executor, session, hooks?
+- [ ] **Issue type** — bug, feature request, question, discussion?
+- [ ] **Severity** — breaking (can't use tool), degraded (works but wrong), cosmetic
+
+### 3. Spawn Agent Army
+
+Based on classification, spawn from [agent-teams.md](agent-teams.md):
+
+```
+ALWAYS spawn:
+├── Context Mode Architect (reviews everything)
+├── QA Engineer (runs all tests)
+├── DX Engineer (checks user-facing quality)
+
+IF adapter X is affected:
+├── {X} Architect
+├── {X} Staff Engineer
+
+IF OS-specific:
+├── OS Compatibility Architect
+├── {macOS|Linux|Windows} Staff Engineer
+
+IF domain-specific:
+├── {Domain} Architect
+└── (Staff Engineer if code changes needed)
+```
+
+**Example: Issue #208 "CLI upgrade full support for Opencode/Kilocode"**
+```
+Agents to spawn:
+1. Context Mode Architect
+2. QA Engineer
+3. DX Engineer
+4. OpenCode Architect
+5. OpenCode Staff Engineer
+6. Kilo Architect
+7. Kilo Staff Engineer
+8. Hooks Architect (CLI upgrade touches hooks)
+9. OS Compatibility Architect (CLI runs on all OS)
+```
+
+### 4. Investigation Phase (Parallel)
+
+All agents investigate simultaneously:
+
+**Architects** research:
+- Read relevant source files
+- Check if claimed behavior actually exists
+- Validate ENV vars against real platform docs (use WebSearch + Context7)
+- Review related closed issues for prior art
+- Report: FINDINGS with specific file:line references
+
+**Staff Engineers** prepare (TDD-first per [tdd.md](tdd.md)):
+- Read the code that needs changing
+- **RED**: Write a failing test that reproduces the bug / specifies new behavior
+- Run test — verify it **FAILS** (if it passes, the test is useless)
+- **GREEN**: Write minimal code to make the test pass
+- Run test — verify it **PASSES**
+- **REFACTOR**: Clean up while keeping tests green
+- Repeat for each behavior (vertical slices, never horizontal)
+- Run full affected adapter tests
+- Report: DRAFT_FIX with RED→GREEN evidence for each behavior
+
+### 5. Ping-Pong Review
+
+Route Staff Engineer outputs to their paired Architects:
+
+```
+EM reads Staff Engineer result
+  → Sends to Architect via Agent(SendMessage)
+  → Architect reviews: APPROVED or CHANGES_NEEDED
+  → If CHANGES_NEEDED: route back to Staff Engineer
+  → Max 2 rounds, then EM decides
+```
+
+### 6. Validate (QA Engineer)
+
+QA Engineer runs the full validation matrix:
+
+```shell
+# All adapter tests
+npx vitest run tests/adapters/
+
+# Core tests
+npx vitest run tests/core/
+
+# Full suite
+npm test
+
+# TypeScript
+npm run typecheck
+```
+
+Report as a matrix:
+
+```
+Adapter Tests:
+  ✓ claude-code    ✓ gemini-cli    ✓ opencode
+  ✓ openclaw       ✓ kilo          ✓ codex
+  ✓ vscode-copilot ✓ cursor        ✓ antigravity
+  ✓ kiro           ✓ pi            ✓ zed
+
+Core Tests:    ✓ routing  ✓ search  ✓ server  ✓ cli
+TypeScript:    ✓ no errors
+Full Suite:    ✓ 47/47 passed
+```
+
+### 7. Push Directly to `next`
+
+**Do NOT open a PR.** Push fixes directly to the `next` branch:
+
+```bash
+# Ensure we're on next
+git checkout next
+git pull origin next
+
+# Apply changes from worktree agents
+# ... (merge worktree changes)
+
+# Commit with issue reference
+git commit -m "fix: {concise description} (closes #{N})
+
+- {what was broken}
+- {what was fixed}
+- {which adapters/modules affected}
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+
+# Push to next
+git push origin next
+```
+
+### 8. Comment on Issue & Close
+
+After pushing to `next`, comment and **close the issue immediately**:
+
+```bash
+gh issue comment {N} --body "$(cat <<'EOF'
+Hey @{author}! 👋
+
+We investigated this and pushed a fix to the `next` branch ({commit_sha}).
+
+**What was happening:** {technical explanation of the root cause}
+
+**What we fixed:** {technical explanation of the fix}
+
+**Affected area:** {adapter/module names}
+
+This will ship in the next release. Once it's out, could you please test it in your setup and let us know if it resolves the issue? 🙏
+
+If the fix doesn't work for you, feel free to reopen this issue.
+
+Thanks for reporting this!
+EOF
+)"
+
+# Close the issue — fix is pushed, job done
+gh issue close {N}
+```
+
+## Decision Tree: Fix vs. Wontfix vs. Needs Info
+
+```
+Issue is clear and reproducible?
+├── YES → Fix it (steps 3-8 above)
+├── UNCLEAR → Comment asking for reproduction steps
+│   └── Template: "Could you share the exact command/config that triggers this?"
+└── BY DESIGN → Explain why, close with "working as intended" label
+    └── Be kind — explain the design decision
+```
+
+## Edge Cases
+
+### Issue references a feature that doesn't exist
+The issue author may have been told by an LLM that a feature exists when it doesn't. Use [validation.md](validation.md) ENV verification to catch this. Comment explaining the misunderstanding kindly.
+
+### Issue is a duplicate
+Link to the original issue, close as duplicate, thank the reporter.
+
+### Issue is actually a feature request
+Re-label, add to backlog discussion, don't close — let the community weigh in.