claude-dev-env 1.38.0 → 1.39.0

package/skills/code/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: code
+description: >-
+  Prepends strict code standards to every implementation session. Enforces
+  strong typing, no Any, no casts, no type: ignore, treated-as-immutable
+  TypedDicts, 100% test coverage, DRY, no mocks, no stubs, no fallbacks, and
+  proper module structure. Triggers: /code, code standards, strict code, enforce
+  standards, implement with standards.
+---
+
+# Code Standards Enforcer
+
+Prepends these standards to every implementation session. Every criterion is binary — pass or fail. No partial credit.
+
+## When this applies
+
+Invoke at the start of any implementation task. The standards persist for the entire session.
+
+**Refusal cases — first match wins:**
+
+- **Not an implementation task.** "This skill applies to code implementation. Ask me to implement something specific."
+- **Exploratory research or planning.** "Code standards are for implementation. Use /anthropic-plan for planning, then invoke /code when implementing."
+
+## Gotchas
+
+- **`make check` must run from pwsh, not bash.** The Bash tool routes through Git Bash on Windows, where `make` may not be on PATH. Always use `pwsh -NoProfile -Command 'make check 2>&1 | Select-Object -Last 100; exit $LASTEXITCODE'` so the pipeline does not mask a non-zero exit code from make.
+- **`New-Item`, `Get-ChildItem`, `Remove-Item` are pwsh cmdlets.** Don't use them inside Bash tool calls. Use the PowerShell tool or prefix with `pwsh -NoProfile -Command`.
+- **`TypedDict` encode/decode must be manual.** Pydantic and similar frameworks bypass the strict validation pattern. Write `_encode_*` and `_decode_*` functions by hand.
+- **`_test_hooks.py` is per-module, not per-package.** Every module that has dependencies needs its own hooks file. A single `conftest.py` with mocks does not satisfy this rule.
+- **Protocol must match the real API exactly.** If the real class has `async def fetch(self, key: str) -> bytes`, the Protocol must declare the same signature. A mismatch is caught at type-check time by mypy strict mode.
+
+---
+
+## Completion criteria
+
+Every criterion below must be met before the change is complete.
+
+### 1. Typing strictness
+
+Zero violations across the project's source, test, and script directories (adapt `src/`, `tests/`, `scripts/` to the project's actual layout):
+
+- No `Any`, `cast()`, `# type: ignore`, `# noqa`.
+- No `.pyi` files, stubs, or shims.
+- Mypy strict mode exits 0 with no errors.
+- All TypedDicts are treated as immutable after construction and carry explicit `_encode_*` / `_decode_*` functions.
+- All decode functions call `require_*` validation on every field.
+- Internal encoder is typed — no untyped dict intermediaries.
+
+### 2. Error handling
+
+- No `try`/`except` in core logic that recovers, softens, or best-efforts a failure.
+- Failures propagate. Callers decide whether to handle.
+- APIs signal failure points through naming, docstrings, and test expectations — not by catching.
+
+### 3. Test coverage
+
+- Test runner exits 0 with full statement and branch coverage (e.g. `pytest -n auto --cov --cov-branch --cov-report=term-missing` with paths adapted to the project layout) (requires pytest-xdist and pytest-cov).
+- Statement coverage: 100%. Branch coverage: 100%.
+- Zero mocks. Every test exercises actual code paths through fakes injected via DI hooks (see criterion 4).
+- Zero weak assertions. Every assert checks a specific, falsifiable property.
+- Zero fake tests (tests that pass without validating behavior).
+
+### 4. Dependency injection
+
+- Every module that has external dependencies provides a `_test_hooks.py` with internal DI hooks (underscore = private). The hook file lives alongside the module it services.
+- A shared testing utility module exports public test helpers for consumers (adapt the path to the project's conventions, e.g. `Libs/testing.py`).
+- Production code sets hooks to real implementations at startup. Tests set them to fakes.
+- No `if`/`else` branching on test vs. production — call the hook directly.
+
+### 5. Codebase standards
+
+- DRY: zero duplicate function bodies longer than 3 lines. Zero duplicate constant definitions.
+- No placeholder code, no dead code, no commented-out blocks.
+- No fallback paths, no back-compat shims, no legacy code.
+- No `TypeAlias`, no `TYPE_CHECKING` import guards.
+
+### 6. TypedDict protocol
+
+- Every TypedDict has a paired `_encode_*` and `_decode_*` function.
+- Every decode calls `require_*` (non-null, type-check, range-check) on every field before returning.
+- Decode functions are the single point where untyped data becomes typed.
+
+### 7. Redis boundary
+
+- Use module-level helper functions or a Protocol.
+- Never reference `Redis[Any]` in type annotations.
+
+### 8. TOML boundary
+
+- No `TYPE_CHECKING` guard for TOML types.
+- Parse untyped dicts from TOML, then convert into TypedDict (no dataclasses) before use.
+
+### 9. JSON recursive types
+
+- Bypass framework validation (e.g., Pydantic).
+- Parse with `json.loads()`, validate immediately with internal `_decode_*` / `_load_json_*` functions before any other use.
+
+### 10. ASGI / framework boundaries
+
+- Define a Protocol for the minimal interface (e.g., `async def body() -> bytes`).
+- Never use `dict[str, Any]` in ASGI scopes.
+- Parse at the edge, validate immediately, propagate as strict types.
+
+### 11. Dynamic import pattern
+
+When using `importlib.import_module()` + `getattr()`, the intermediate variables are untyped. Bind the final instance through a typed wrapper so the result carries a concrete type rather than `Any`:
+
+```python
+import importlib
+from collections.abc import Callable
+
+mod = importlib.import_module("module_name")
+cls = getattr(mod, "ClassName")
+
+def _construct(klass: Callable[..., TheProtocol]) -> TheProtocol:
+    return klass()
+
+instance = _construct(cls)
+```
+
+### 12. Documentation
+
+Google-style docstrings on every public function, method, and class:
+
+```python
+def load_config(config_path: str) -> AppConfig:
+    """Load and validate the application configuration from disk.
+
+    Args:
+        config_path: Absolute path to the TOML configuration file.
+
+    Returns:
+        A fully validated AppConfig TypedDict.
+
+    Raises:
+        FileNotFoundError: If config_path does not exist.
+        ValidationError: If the parsed config fails require_* checks.
+    """
+```
+
+### 13. Build infrastructure
+
+The project under development must contain:
+
+- `Makefile` with targets: `check`, `lint`, `test`, `coverage`.
+- `pyproject.toml` with `[tool.mypy]` strict mode, `[tool.pytest.ini_options]` with `addopts = -n auto` (requires pytest-xdist).
+- A lint guard script that covers the project's source, test, and script directories.
+
+### 14. Lint gates
+
+- `make lint` runs mypy (strict), ruff, and the project's guard script.
+- All linters cover the project's source, test, and script directories.
+- `make lint` exits 0 before `make test` is valid.
+
+### 15. Protocol signature match
+
+- Every Protocol's method signatures match the real API they abstract.
+- If the real API changes, the Protocol fails type-checking — no silent drift.
+
+### 16. Auth, credentials, multi-tenancy
+
+- Auth and credential handling is explicit, typed, and testable.
+- Multi-tenant DB access uses typed connection factories, not string-formatted queries.
+- MCP-shared resources follow the same strictness as application code.
+
+---
+
+## Verification
+
+Each criterion returns either **at least one finding** OR **exactly one proof-of-absence** with at least 3 adversarial probes specific to that criterion. A criterion returning neither is a protocol gap.
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Hub — binary criteria, gotchas, when-to-apply, verification protocol |

package/skills/doc-gist/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: doc-gist
+description: >-
+  Use when the user asks to share, publish, preview, or open as a webpage any
+  HTML doc, writeup, report, plan, decision record, runbook, explainer, status
+  update, or interactive artifact. Triggers on `/doc-gist`, "publish this",
+  "share as a gist", "open this as a webpage", "make me a writeup", "publish my
+  report", or any request that ends in a shareable HTML preview URL. Provides
+  the `gist_upload` transport script, an auto-publish hook keyed off the
+  `<!-- @publish-as-gist -->` HTML comment, and a 20-file gallery of HTML
+  artifact patterns to draw from when designing fresh.
+---
+
+# doc-gist
+
+Design fresh HTML for the artifact at hand, mark it for publishing, write it. The rest is automatic — a hook spots the marker, uploads to a secret gist, and prints the htmlpreview URL into your output for the user to click.
+
+## Principle (and what this skill deliberately does not ship)
+
+This skill ships **transport, not shape**. There are no document templates here. There is no markdown-to-HTML converter. There is no rebase-report mode. The shape of every artifact is your fresh design per request, drawing on the gallery in [`references/examples/`](references/examples/) for inspiration.
+
+Per Thariq's html-effectiveness thesis: *"twenty self-contained .html files an agent produced — each one trades a document you'd skim for one you'd actually read."* Every doc-gist invocation produces a fresh design appropriate to the work, not a template fill.
+
+## How auto-publish works
+
+1. You write HTML to any path (no directory rule, no naming rule).
+2. The HTML contains the marker comment `<!-- @publish-as-gist -->` — typically as the first child of `<head>` or just inside `<body>`.
+3. The PostToolUse hook ([`workflow/doc_gist_auto_publish.py`](../../hooks/workflow/doc_gist_auto_publish.py)) fires after the Write/Edit completes, sees the marker, and runs [`skills/doc-gist/scripts/gist_upload.py`](scripts/gist_upload.py) against the file.
+4. The upload script's gist + preview URLs print into your tool output. Quote them back to the user.
+
+The hook is a no-op for any HTML that lacks the marker — React components, test fixtures, scraped pages, partial fragments. The marker is the *intent signal*; absent marker means "this HTML isn't for sharing."
+
+## Gotchas
+
+- **`gh` must be authenticated.** The upload runs `gh gist create`. If `gh auth status` is failing, the hook surfaces the error to stderr and exits 0 (does not block the write). Run `gh auth login` and re-trigger by editing the HTML once more.
+- **The marker is a literal HTML comment, not a meta tag.** `<!-- @publish-as-gist -->` exactly. `<meta name="publish-as-gist">` does not match. Whitespace inside the marker breaks it.
+- **htmlpreview render delay.** First load of the preview URL takes 5–10 seconds while htmlpreview.github.io fetches the raw gist content. A blank page on first visit means refresh once.
+- **Filenames carry into the gist.** The gist filename is the same as the source file's name. Name your files for the artifact, not for filesystem convenience — `auth-migration-plan.html` reads better in the gist UI than `tmp_plan_v3_final.html`.
+- **Markers in code samples need escaping.** If you embed an example HTML snippet inside `<pre><code>` and that snippet contains the literal marker text, the hook will publish on first save. Either escape the comment angle brackets in the embedded sample, or write the marker as `<!- - @publish-as-gist - ->` in the embedded version.
+- **Self-contained HTML only.** The upload sends a single file. External CSS/JS via `<link href="./style.css">` or `<script src="./app.js">` will fail to load in the htmlpreview view. Inline everything — `<style>`, `<script>`, base64 images, SVG.
+- **Secret gist, not private.** `gh gist create` defaults to "secret" (anyone with the URL can view; not indexed; not on your public profile). Treat the preview URL like a shareable Google Doc — share with intent.
+
+## When to include the marker
+
+Include `<!-- @publish-as-gist -->` when **the artifact is for sharing or reading**: writeups, plans, reports, explainers, decision records, runbooks, status updates, prototypes the user will look at. Skip the marker for: HTML that's part of a code change (React components, test fixtures), HTML you're authoring as a one-off scratch file you'll delete, embedded HTML samples inside other artifacts.
+
+The user's prompt is the strongest signal. *"Make me a writeup of this PR"* → publish. *"Add this React component"* → don't publish.
+
+## The transport script — `skills/doc-gist/scripts/gist_upload.py`
+
+For manual invocation when the marker route doesn't apply (an existing file you want to publish, HTML piped from another tool, a one-off):
+
+```
+python3 skills/doc-gist/scripts/gist_upload.py --input <path-or-stdin>
+                              [--filename gist-file.html]
+                              [--description "short label"]
+                              [--no-open]
+```
+
+Reads HTML from `--input <path>` or stdin (`--input -`), runs `gh gist create`, prints `Gist:` and `Preview:` URLs to stderr, prints the preview URL to stdout (so callers can pipe), opens the preview in the default browser unless `--no-open`.
+
+## Designing fresh — the example gallery
+
+The skill ships [`references/examples/`](references/examples/) with all 20 of Thariq's html-effectiveness prototypes verbatim from [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/). They are *examples to learn from, not templates to fill.*
+
+When the user requests an artifact, decide the shape that fits. Use the gallery for grounding:
+
+| User wants | Gallery entries to study |
+|---|---|
+| PR writeup with file-by-file tour | `17-pr-writeup.html` |
+| Annotated diff or code review | `03-code-review-pr.html` |
+| Code-explainer with module map | `04-code-understanding.html` |
+| Implementation plan with timeline + risks | `16-implementation-plan.html` |
+| Side-by-side approach exploration | `01-exploration-code-approaches.html` |
+| Visual design comparison | `02-exploration-visual-designs.html` |
+| Design system swatches | `05-design-system.html` |
+| Component variants matrix | `06-component-variants.html` |
+| Animation tuning sandbox with sliders | `07-prototype-animation.html` |
+| Multi-screen interaction mockup | `08-prototype-interaction.html` |
+| Slide deck (keyboard-navigable) | `09-slide-deck.html` |
+| SVG illustration | `10-svg-illustrations.html` |
+| Status report (visual) | `11-status-report.html` |
+| Incident timeline / post-mortem | `12-incident-report.html` |
+| Flowchart / pipeline diagram | `13-flowchart-diagram.html` |
+| Feature explainer with collapsibles | `14-research-feature-explainer.html` |
+| Concept explainer (interactive learning) | `15-research-concept-explainer.html` |
+| Triage / kanban board (drag-drop) | `18-editor-triage-board.html` |
+| Feature flag toggles with deps | `19-editor-feature-flags.html` |
+| Live-updating template editor | `20-editor-prompt-tuner.html` |
+
+Read the matching example for the artifact you're designing. Crib palette, typography, spatial idioms, component patterns. **Adapt — do not copy.** A PR writeup for a hooks PR shouldn't look identical to one for a notification-queue PR. The gallery teaches what shapes work; the request decides which shape fits.
+
+## Folder map
+
+- `SKILL.md` — this file.
+- `skills/doc-gist/scripts/gist_upload.py` — transport: HTML in, gist + preview URLs out.
+- `skills/doc-gist/scripts/config/gist_upload_constants.py` — the URL prefixes and template strings.
+- `references/examples/` — Thariq's 20 html-effectiveness prototypes.
+- (PostToolUse hook lives in `packages/claude-dev-env/hooks/workflow/doc_gist_auto_publish.py` — wired into the plugin's `hooks.json`.)