devharness-contributing
/devharness-contributing
Opisuje konwencje pisania kodu w repozytorium devharness: propagację błędów narzędzi, czytanie _meta zamiast renderowanego tekstu, miejsca dokumentacji i zasady wydań.
- Autor
- indate ↗
- Repozytorium
- devharness ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 21.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 21.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Opisuje konwencje pisania kodu w repozytorium devharness: propagację błędów narzędzi, czytanie _meta zamiast renderowanego tekstu, miejsca dokumentacji i zasady wydań.
Oryginalny opis (EN)
Conventions for writing code in the devharness repo itself (as opposed to using its tools to debug some other app) - how tool failures propagate, why behaviour must read _meta rather than rendered text, where each kind of documentation lives, and the release rules an agent gets wrong. Use when editing files under src/, adding or changing an MCP tool, cutting a release, or debugging why a rebuild didn't take effect in a live session.
Jak działa
- Releasing: what an agent gets wrong
- Tool failures are THROWN, not returned
- Read meta, never rendered text
- Which file takes the prose
- Config philosophy
Podgląd SKILL.md
---
name: devharness-contributing
description: Conventions for writing code in the devharness repo itself (as opposed to using its tools to debug some other app) - how tool failures propagate, why behaviour must read _meta rather than rendered text, where each kind of documentation lives, and the release rules an agent gets wrong. Use when editing files under src/, adding or changing an MCP tool, cutting a release, or debugging why a rebuild didn't take effect in a live session.
---
# Contributing to devharness
**Read `CONTRIBUTING.md` first.** It owns the mechanics — build and test commands, running your build as `devharness-dev`, hot-reload and how to tell whether it took, `stress:suspend`, the release sequence, and the doc-sync list. It is the single source for all of that; this skill does not repeat it.
What follows is what `CONTRIBUTING.md` does not say: the code conventions, and the release habits an agent specifically gets wrong.
## Releasing: what an agent gets wrong
The sequence is in `CONTRIBUTING.md`. Three things about it change how you should behave, not just what you type:
- **`npm run build:verify` before bumping, always.** Skipping it once put out a tag whose publish failed on a stale `plugin/.mcp.json` pin, while `notify-marketplace` had already opened a PR pinning a version npm never received. After the tag, it is too late.
- **`postversion` pushes the branch and the tag with no confirmation.** Every local commit on `main` ships. Nothing is "committed but held back locally" once someone bumps — never describe a commit that way, and make `main` exactly what should ship before bumping.
- **Don't offer to push afterwards, and don't say a release "wasn't published".** Both already happened. Check rather than guess: `gh run list --workflow=publish.yml`, `npm view devharness version`.
Never run `npm publish` by hand — a second unverified path to the registry that collides with the run the tag already started.
## Tool failures are THROWN, not returned
`executeToolCall` (`src/index.ts`) converts any `isError` response into a thrown `ToolError` (`src/tool-error.ts`) carrying that response. **Downstream code branching on `result.isError` is dead**, and a fake `executeToolCall` that *returns* isError responses covers that dead branch while the live path goes untested. That mismatch shipped absent-element conditions failing whole runs, `LAUNCH_FAILED` never reaching the user, and a leaked verification tab.
- **Wrap every fake `executeToolCall` in `productionShaped()`** (`src/test-support/fake-execute-tool-call.ts`). Import the real `ToolError` rather than re-declaring its shape.
- **Classify failures by `_errorId`, not message text.** `createErrorResponse` attaches it and `ToolError` carries the response, so `err.response._errorId` is available in-process. `isElementNotFoundFailure()` in `messages.ts` is the worked example.
- **Build fixtures with the real helpers** (`createErrorResponse`, `getErrorMessage`, `formatCodeBlock`, `webStorageMeta`). Hand-written text drifts: fixtures asserted `Element not found: ...` for a year while `MessageManager` emitted `Error: Element not found: ...`.
## Read `_meta`, never rendered text
Structured results live in `_meta` (`src/tool-response.ts`). Anything deciding *behaviour* must read that — rendered text mixes our formatting with page-controlled data. Every instance of grepping the markdown was a bug: a localStorage `"null"` read as absent, a URL containing a comma compared truncated, `**error**` counted inside a logged message, `\d{3}` matching any three digits as an HTTP status.
If the data isn't in `_meta`, add it there rather than parsing the string. **No text fallback "just in case"** — production has one shape, and a fallback no path reaches is untestable and hides drift. The one exception is a raw library exception with no `_errorId`.
## Which file takes the prose
- `src/tools/*.ts` — one file per tool family, action-based schemas.
- `docs/mcp-instructions.md` — sent on every MCP connection, injected unconditionally. Keep it tiny.
- `docs/instructions.md` — full tool reference for clients without Agent Skills support.
- `plugin/skills/devharness/` — the Agent Skill shipped to consumers; loads only on activation.
- `docs/messages.md` — source of truth for response text (`## MESSAGE_ID` sections), parsed at runtime by `messages.ts`. Costs tokens only when that call happens, so detail is fine here.
**Keep tool schema descriptions terse** (`.describe()` and `createTool()`'s first argument). They go to every session at `listTools` time whether or not the tool is ever called — a fixed cost, not a progressive-disclosure surface. Put why/when/what-happens in the shipped skill or its `references/`.
**Skill and reference prose is a token budget, not a page count.** Say it once, in the fewest words that survive being wrong. Cut restatement and any sentence that only reassures. If a paragraph and a table say the same thing, keep the table.
**Comments are not journals.** What the code does, or why the non-obvious choice was made, in one line where possible. No narrating history ("this used to..."), no arguing with a previous author, no restating the line below. Git holds history; the comment holds the constraint.
## Config philosophy
Per `docs/working_with_llm_notes.md`: LLMs editing this server's own behavior are optimistic and sometimes wrong. Any LLM-driven config change needs a manual override path the user can reach without going through the LLM — don't add a setting only reachable through an agent's tool calls.
Wersje
W bazie nie ma innych skilli o nazwie devharness-contributing.
Migawka bazy z 13.11.2026 · wersja paczki a303623b49f7 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100devharness
Steruje i debuguje działającą aplikację przez serwer MCP devharness: uruchamianie Chrome i Node.js, breakpointy i logpointy, stos wywołań, konsola i sieć, serwery dev, powtarzanie wywołań oraz nagrywanie sekwencji odtwarzających błąd. - 90instructing-sessions
Ustala, gdzie w devharness trafia każda informacja dla sesji i jak przenieść sesję z gorszej ścieżki na lepszą. - 100documentation-structure
Opisuje architekturę dokumentacji repozytorium: README.md, CONTRIBUTING.md i katalog docs/, z podziałem odpowiedzialności, standardami dokumentacji dostawców, odsyłaczami i walidacją. - 100contributing-guide-creator
Prawdopodobnie pomaga tworzyć przewodniki dla współtwórców projektu w ramach dokumentacji technicznej. - 100contributing
Pomaga w pracy nad bazą kodu Butterbase: dodawaniu narzędzi MCP, tworzeniu tras API, pisaniu migracji i rozumieniu architektury monorepo. - 95agents-contributing-setup-repo
Przygotowuje repozytorium do przyjmowania wkładu od agentów AI przez plik AGENTS-CONTRIBUTING.md zgodny ze specyfikacją.