devharness-contributing
/devharness-contributing
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.
- Author
- indate ↗
- Repository
- devharness ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Releasing: what an agent gets wrong
- Tool failures are THROWN, not returned
- Read meta, never rendered text
- Which file takes the prose
- Config philosophy
SKILL.md preview
---
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.
Versions
The database has no other skills named devharness-contributing.
Database snapshot: 13.11.2026 · package version a303623b49f7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100devharness
Drive and debug a running app via the devharness MCP server - launch or attach to Chrome and Node.js, set breakpoints and logpoints, inspect call stacks and variables, watch console and network, manage dev servers, replay any earlier tool call by its history index, and record… - 90instructing-sessions
Where each fact devharness sends a session belongs, and how a session is moved off a worse path. Use when adding or changing any text a session receives from devharness - server instructions, the SessionStart hook, a tool or parameter description, reply or error text in… - 100documentation-structure
Documentation architecture for this repository. Use when creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files. Covers separation of concerns, vendor documentation standards, cross-references, and validation. - 100contributing-guide-creator
Create contributing guide creator operations. Auto-activating skill for Technical Documentation. Triggers on: contributing guide creator, contributing guide creator Part of the Technical Documentation skill category. Use when working with contributing guide creator… - 100contributing
Use when contributing to the Butterbase codebase, adding new MCP tools, creating API routes, writing migrations, or understanding the monorepo architecture - 95agents-contributing-setup-repo
Set up a repository to receive help from AI agents under the AGENTS-CONTRIBUTING spec. Use when a repository owner asks to accept agent contributions, add AGENTS-CONTRIBUTING.md, or open their repo to donated AI capacity.